subliminal 2.5.0

Subtitles, faster than your thoughts

Subtitles, faster than your thoughts.

Project page:

https://github.com/Diaoul/subliminal

Documentation:

https://subliminal.readthedocs.org/

Community:

https://discord.gg/kXW6sWte9N

Usage

CLI

Download English subtitles:

$ subliminal download -l en The.Big.Bang.Theory.S05E18.HDTV.x264-LOL.mp4
Collecting videos  [####################################]  100%
1 video collected / 0 video ignored / 0 error
Downloading subtitles  [####################################]  100%
Downloaded 1 subtitle

Configuration

Arguments can be passed to the CLI using a configuration file. By default it looks for a subliminal.toml file in the default configuration folder (see the CLI help for the exact platform-specific default path). Or use the -c option to specify the path to the configuration file.

Look for this example configuration file or use the generate_default_config function from the subliminal.cli module to generate a configuration file with all the options and their default values:

$ python -c "from subliminal.cli import generate_default_config; print(generate_default_config())"

Library

Download best subtitles in French and English for videos less than two weeks old in a video folder:

#!/usr/bin/env python

from datetime import timedelta

from babelfish import Language
from subliminal import download_best_subtitles, region, save_subtitles, scan_videos

# configure the cache
region.configure('dogpile.cache.dbm', arguments={'filename': 'cachefile.dbm'})

# scan for videos newer than 2 weeks and their existing subtitles in a folder
videos = scan_videos('/video/folder', age=timedelta(weeks=2))

# download best subtitles
subtitles = download_best_subtitles(videos, {Language('eng'), Language('fra')})

# save them to disk, next to the video
for v in videos:
    save_subtitles(v, subtitles[v])

Docker

Run subliminal in a docker container:

$ docker run --rm --name subliminal -v subliminal_cache:/usr/src/cache -v /tvshows:/tvshows -it ghcr.io/diaoul/subliminal download -l en /tvshows/The.Big.Bang.Theory.S05E18.HDTV.x264-LOL.mp4

Debugging

By default, subliminal output is minimal. Run with the –debug flag before the download command to get more information:

$ subliminal --debug download -l en The.Big.Bang.Theory.S05E18.HDTV.x264-LOL.mp4

Installation

For a better isolation with your system you should use a dedicated virtualenv. The preferred installation method is to use pipx that does that for you:

$ pipx install subliminal

Subliminal can be also be installed as a regular python module by running:

$ pip install --user subliminal

If you want to modify the code, fork this repo, clone your fork locally and install a development version:

$ git clone https://github.com/<my-username>/subliminal
$ cd subliminal
$ pip install --user -e '.[docs,types,tests,dev]'

To extract information about the video files, subliminal uses knowit. For better results, make sure one of its provider is installed, for instance MediaInfo.

Integrations

Subliminal integrates with various desktop file managers to enhance your workflow:

• Nautilus/Nemo: See the dedicated project page for more information.

• Dolphin: See this Gist. for more details.

Contributing

We welcome contributions from the community! If you’re interested in contributing, here are a few ways you can get involved:

• Browse Issues and Pull Requests: Check out the existing Issues and Pull Requests to see where you can help.

• Report Bugs or Request Features: If you encounter a bug or have a feature request, please create a GitHub Issue.

• Follow the Contribution Guide: For detailed instructions on how to contribute, please refer to our Contribution Guide.

Your contributions are greatly appreciated and help make this project better for everyone!