subliminal

Download English subtitles for a video

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

subliminal [OPTIONS...] [PATH]...

-l, --language TEXT
    Subtitle language(s), repeatable; default 'en'

-p, --providers TEXT
    Providers to query, repeatable; e.g., 'opensubtitles'

--force
    Overwrite existing subtitles

--age-cert RATING
    Max age certification (e.g., 'PG-13')

--one-subs
    Download only one subtitle per language

--multi
    Download multiple subtitles per language (default)

--select PROP=VALUE
    Filter by property (e.g., 'imdbid=tt1234567')

--output-dir PATH
    Output directory for subtitles

--cache-dir PATH
    Directory for cache files

--keys PROVIDER=KEY
    API keys, repeatable (e.g., 'opensubtitles=apikey')

--config PATH
    Path to config file

--timeout SECONDS
    Request timeout

--workers COUNT
    Number of parallel workers

--version
    Show version and exit

--help
    Show help

Subliminal is a powerful command-line tool and Python library designed to automatically download subtitles for video files. It parses video filenames using the guessit library to identify details like title, season, episode, and year. Then, it queries multiple online subtitle providers such as OpenSubtitles, Addic7ed, Podnapisi, TheSubDB, and TVSubtitles to find matching subtitles in specified languages.

The tool supports batch processing of directories or individual files, renaming downloaded subtitles to match video naming conventions (e.g., Show.Name.S01E01.mkv gets Show.Name.S01E01.eng.srt). It handles hashing for accurate matches, respects age certifications, and allows filtering by properties like IMDb ID or release year. Subliminal is highly configurable via CLI flags, config files, or environment variables, making it ideal for media servers like Plex or Kodi.

Installation is via pip: pip install subliminal. It requires an active internet connection and optional API keys for premium providers. Subtitles are saved in SRT format by default.

Requires Python 3.8+ and internet; some providers need API keys. Does not embed subtitles into videos. Cache can grow large. Rate-limited by providers.

pip install subliminal
Optional: pip install subliminal[opensubtitles] for extras.

subliminal -l en fr /path/to/videos/
Downloads English/French subs for all videos in directory.

Developed by Diaoul starting 2012 as Python subtitle library. Integrated with guessit for parsing and babelfish for language handling. Maintained on GitHub; v2.1+ supports async providers. Widely used in media automation scripts.

guessit(1), babelfish(1)