Search subtitles
search_subtitlesFind subtitles for a movie or TV episode and get file_ids to download. Search by title (query), video filename, IMDb/TMDB/feature id with optional season/episode, or moviehash; filter by language and flags. Results are ranked with exact title, episode and release-name matches first.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "search_subtitles"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| type | No | Restrict to movies or TV episodes | |
| year | No | ||
| query | No | Title to search for, e.g. "The Matrix". Not needed when an id, moviehash or filename is given. | |
| imdb_id | No | IMDb id (tt0133093 or 133093). With season_number/episode_number it is the show's id. | |
| tmdb_id | No | TMDB id. With season_number/episode_number it is the show's id. | |
| filename | No | Video filename, e.g. "Chicago.Fire.S14E01.1080p.WEB.h264-ETHEL.mkv". Parsed with guessit-js into title/year/season/episode; its release name ranks matching subtitles first. | |
| order_by | No | relevance = exact title/episode and release-name matches first, then popularity | relevance |
| per_page | No | ||
| languages | No | Subtitle languages in order of preference, e.g. ["en", "pt-BR"]. Omit for all languages. | |
| moviehash | No | OpenSubtitles hash of the video file (calculate_file_hash in local mode). Exact file matches are flagged moviehash_match and ranked first. | |
| feature_id | No | OpenSubtitles feature id from search_features. With season_number/episode_number it is the show's id. | |
| exact_title | No | When searching by title, first resolve it to the exact movie/show (so "The Matrix" does not return "The Matrix Revisited"). Set false for a fuzzy text search. | |
| trusted_only | No | Only subtitles from trusted uploaders | |
| season_number | No | ||
| episode_number | No | ||
| hearing_impaired | No | Subtitles for the deaf and hard of hearing (SDH) | include |
| foreign_parts_only | No | Subtitles that only cover foreign-language dialogue | include |
| include_ai_translated | No | Include AI-translated subtitles | |
| include_machine_translated | No | Include machine-translated subtitles (usually low quality) |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page | Yes | ||
| hints | Yes | ||
| filters | Yes | Effective query sent to the OpenSubtitles API | |
| guessed | Yes | What guessit-js read from filename | |
| results | Yes | ||
| per_page | Yes | ||
| total_count | Yes | Matches at the API for the effective filters | |
| total_pages | Yes | ||
| resolved_feature | Yes | The movie/show the title was resolved to, when exact_title applied |