subliminal

Download English subtitles for a video

$ subliminal download [[-l|--language]] [en] [video.ext]

subliminal [OPTIONS] FILE [FILE...]
subliminal [OPTIONS] --version
subliminal [OPTIONS] --help

FILE [FILE...]
    One or more paths to video files or directories to process. Subliminal will scan these paths for videos.

-l, --language LANGUAGE
    Specify the language of the subtitles to download (e.g., 'en' for English, 'fr' for French). Can be specified multiple times for multiple languages.

-a, --add-descriptor DESCRIPTOR
    Add a video descriptor (e.g., 'series=TV Show' or 'season=1' for better matching on some providers). Can be specified multiple times.

-p, --add-provider PROVIDER
    Enable an additional subtitle provider (e.g., 'opensubtitles', 'thesubdb'). Can be specified multiple times.

-s, --single
    Download only one subtitle per video (the best match). By default, it downloads all good matches.

-m, --multi
    Force multi-episode matching for episode files (e.g., when a single file contains multiple episodes).

-n, --dry-run
    Do not download any subtitles; just show what would be downloaded.

-v, --version
    Show program's version number and exit.

-h, --help
    Show this help message and exit.

--no-opensubtitles
    Disable the OpenSubtitles provider explicitly.

--age DAYS
    Only download subtitles for videos newer than N days. Use 0 for no age limit.

--max-downloads NUMBER
    Maximum number of subtitles to download per video. Defaults to 0 (all good matches).

subliminal is a powerful and highly extensible Python library and command-line tool designed for finding, downloading, and managing subtitles for video files. It automates the process of fetching subtitles from various online providers like OpenSubtitles, TheSubDB, TVsubtitles.net, and more. Users can specify video files or directories, and subliminal will analyze them to find the best matching subtitles based on criteria like file name, hash, and language. It supports a wide range of video formats and integrates seamlessly into media server setups or personal workflows to ensure your media collection always has the right subtitles.

subliminal requires Python to be installed on the system, as it is a Python library and application. It's typically installed via `pip`.
Subtitle availability and quality depend entirely on the external providers it connects to. Some providers may require registration or API keys.
Incorrect video file naming or metadata can lead to poor subtitle matches or no matches at all.
Frequent use might lead to rate limiting from some subtitle provider APIs.

subliminal allows for advanced configuration of subtitle providers, including setting up credentials for services like OpenSubtitles or others that require login. This can be done via configuration files or environment variables, enhancing the success rate of subtitle searches.

Beyond its command-line interface, subliminal is fundamentally a Python library. This means it can be directly integrated into other Python applications, such as media servers (e.g., Plex, Jellyfin integration via plugins) or custom scripts, to add automated subtitle downloading capabilities.

For better subtitle matching, especially for TV shows or obscure movies, subliminal can utilize 'video descriptors'. These are pieces of information like 'series', 'season', 'episode', or 'year' that help the providers narrow down the search for accurate subtitles.

subliminal was created by Antoine Bertin and has been actively developed as an open-source project since around 2012. Its primary goal was to provide a robust and extensible solution for automatic subtitle downloading, addressing the need for media server users and general consumers alike. It gained popularity for its comprehensive provider support and flexible command-line interface, becoming a go-to tool in the Python ecosystem for media management tasks. Development continues with contributions from a community of users and developers.

ffmpeg(1), mkvtoolnix(1), mpv(1)