Subliminal
==========
Subtitles, faster than your thoughts.
.. image:: https://img.shields.io/pypi/v/subliminal.svg
:target: https://pypi.python.org/pypi/subliminal
:alt: Latest Version
.. image:: https://readthedocs.org/projects/subliminal/badge/?version=latest
:target: https://subliminal.readthedocs.org/
:alt: Documentation Status
.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Diaoul/subliminal/python-coverage-comment-action-data/endpoint.json
:target: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Diaoul/subliminal/python-coverage-comment-action-data/endpoint.json
:alt: Code coverage
.. image:: https://img.shields.io/github/license/Diaoul/subliminal.svg
:target: https://github.com/Diaoul/subliminal/blob/master/LICENSE
:alt: License
.. image:: https://img.shields.io/badge/discord-7289da.svg?style=flat-square&logo=discord
:alt: Discord
:target: https://discord.gg/kXW6sWte9N
: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 <https://github.com/Diaoul/subliminal/blob/main/docs/config.toml>`__
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:
.. code:: python
#!/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 <https://github.com/pypa/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 <https://github.com/Diaoul/subliminal/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 <https://github.com/ratoaq2/knowit>`_.
For better results, make sure one of its provider is installed, for instance `MediaInfo <https://mediaarea.net/en/MediaInfo>`_.
Integrations
------------
Subliminal integrates with various desktop file managers to enhance your workflow:
- **Nautilus/Nemo**: See the dedicated `project page <https://github.com/Diaoul/nautilus-subliminal>`_ for more information.
- **Dolphin**: See this `Gist <https://gist.github.com/maurocolella/03a9f02c56b1a90c64f05683e2840d57>`_. 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 <https://github.com/Diaoul/subliminal/issues>`_
and `Pull Requests <https://github.com/Diaoul/subliminal/pulls>`_ 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 <https://github.com/Diaoul/subliminal/blob/main/CONTRIBUTING.md>`_.
Your contributions are greatly appreciated and help make this project better for everyone!
Raw data
{
"_id": null,
"home_page": null,
"name": "subliminal",
"maintainer": null,
"docs_url": "https://pythonhosted.org/subliminal/",
"requires_python": ">=3.9",
"maintainer_email": "Antoine Bertin <diaoulael@gmail.com>, getzze <getzze@gmail.com>, Patrycja Rosa <pypi@ptrcnull.me>",
"keywords": "episode, movie, series, show, subtitle, subtitles, tv, video",
"author": null,
"author_email": "Antoine Bertin <diaoulael@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/f9/d1/f55d55bf7d585f6d749b60479b4f405de0d8805324d83c598ee3d540df79/subliminal-2.4.0.tar.gz",
"platform": null,
"description": "Subliminal\n==========\nSubtitles, faster than your thoughts.\n\n.. image:: https://img.shields.io/pypi/v/subliminal.svg\n :target: https://pypi.python.org/pypi/subliminal\n :alt: Latest Version\n\n.. image:: https://readthedocs.org/projects/subliminal/badge/?version=latest\n :target: https://subliminal.readthedocs.org/\n :alt: Documentation Status\n\n.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Diaoul/subliminal/python-coverage-comment-action-data/endpoint.json\n :target: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Diaoul/subliminal/python-coverage-comment-action-data/endpoint.json\n :alt: Code coverage\n\n.. image:: https://img.shields.io/github/license/Diaoul/subliminal.svg\n :target: https://github.com/Diaoul/subliminal/blob/master/LICENSE\n :alt: License\n\n.. image:: https://img.shields.io/badge/discord-7289da.svg?style=flat-square&logo=discord\n :alt: Discord\n :target: https://discord.gg/kXW6sWte9N\n\n\n:Project page: https://github.com/Diaoul/subliminal\n:Documentation: https://subliminal.readthedocs.org/\n:Community: https://discord.gg/kXW6sWte9N\n\n\nUsage\n-----\nCLI\n^^^\nDownload English subtitles::\n\n $ subliminal download -l en The.Big.Bang.Theory.S05E18.HDTV.x264-LOL.mp4\n Collecting videos [####################################] 100%\n 1 video collected / 0 video ignored / 0 error\n Downloading subtitles [####################################] 100%\n Downloaded 1 subtitle\n\nConfiguration\n^^^^^^^^^^^^^\nArguments can be passed to the CLI using a configuration file.\nBy default it looks for a `subliminal.toml` file in the default configuration folder\n(see the CLI help for the exact platform-specific default path).\nOr use the `-c` option to specify the path to the configuration file.\n\n`Look for this example configuration file <https://github.com/Diaoul/subliminal/blob/main/docs/config.toml>`__\nor use the `generate_default_config` function from the `subliminal.cli` module to generate a\nconfiguration file with all the options and their default values::\n\n $ python -c \"from subliminal.cli import generate_default_config; print(generate_default_config())\"\n\nLibrary\n^^^^^^^\nDownload best subtitles in French and English for videos less than two weeks old in a video folder:\n\n.. code:: python\n\n #!/usr/bin/env python\n\n from datetime import timedelta\n\n from babelfish import Language\n from subliminal import download_best_subtitles, region, save_subtitles, scan_videos\n\n # configure the cache\n region.configure('dogpile.cache.dbm', arguments={'filename': 'cachefile.dbm'})\n\n # scan for videos newer than 2 weeks and their existing subtitles in a folder\n videos = scan_videos('/video/folder', age=timedelta(weeks=2))\n\n # download best subtitles\n subtitles = download_best_subtitles(videos, {Language('eng'), Language('fra')})\n\n # save them to disk, next to the video\n for v in videos:\n save_subtitles(v, subtitles[v])\n\nDocker\n^^^^^^\n\nRun subliminal in a docker container::\n\n $ 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\n\nDebugging\n^^^^^^^^^\n\nBy default, subliminal output is minimal. Run with the `--debug` flag before the `download` command to get more information::\n\n $ subliminal --debug download -l en The.Big.Bang.Theory.S05E18.HDTV.x264-LOL.mp4\n\n\nInstallation\n------------\nFor a better isolation with your system you should use a dedicated virtualenv.\nThe preferred installation method is to use `pipx <https://github.com/pypa/pipx>`_ that does that for you::\n\n $ pipx install subliminal\n\nSubliminal can be also be installed as a regular python module by running::\n\n $ pip install --user subliminal\n\nIf you want to modify the code, `fork <https://github.com/Diaoul/subliminal/fork>`_ this repo,\nclone your fork locally and install a development version::\n\n $ git clone https://github.com/<my-username>/subliminal\n $ cd subliminal\n $ pip install --user -e '.[docs,types,tests,dev]'\n\nTo extract information about the video files, `subliminal` uses `knowit <https://github.com/ratoaq2/knowit>`_.\nFor better results, make sure one of its provider is installed, for instance `MediaInfo <https://mediaarea.net/en/MediaInfo>`_.\n\nIntegrations\n------------\nSubliminal integrates with various desktop file managers to enhance your workflow:\n\n- **Nautilus/Nemo**: See the dedicated `project page <https://github.com/Diaoul/nautilus-subliminal>`_ for more information.\n- **Dolphin**: See this `Gist <https://gist.github.com/maurocolella/03a9f02c56b1a90c64f05683e2840d57>`_. for more details.\n\nContributing\n------------\nWe welcome contributions from the community! If you're interested in contributing, here are a few\nways you can get involved:\n\n- **Browse Issues and Pull Requests**: Check out the existing `Issues <https://github.com/Diaoul/subliminal/issues>`_\n and `Pull Requests <https://github.com/Diaoul/subliminal/pulls>`_ to see where you can help.\n- **Report Bugs or Request Features**: If you encounter a bug or have a feature request, please create a GitHub Issue.\n- **Follow the Contribution Guide**: For detailed instructions on how to contribute, please refer to our\n `Contribution Guide <https://github.com/Diaoul/subliminal/blob/main/CONTRIBUTING.md>`_.\n\nYour contributions are greatly appreciated and help make this project better for everyone!\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Subtitles, faster than your thoughts",
"version": "2.4.0",
"project_urls": {
"documentation": "https://subliminal.readthedocs.org",
"homepage": "https://github.com/Diaoul/subliminal",
"repository": "https://github.com/Diaoul/subliminal"
},
"split_keywords": [
"episode",
" movie",
" series",
" show",
" subtitle",
" subtitles",
" tv",
" video"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "db3bf14266a7c844944c6505398aca7bfbab257b1908d71d3aae12b1dce65994",
"md5": "fc7a603fc6d3571edd1da8678fe6d2ad",
"sha256": "25c91671d96bb1db9484ff2e5cecd748e262119691b87b8cf24d880879a813d0"
},
"downloads": -1,
"filename": "subliminal-2.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fc7a603fc6d3571edd1da8678fe6d2ad",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 113602,
"upload_time": "2025-09-02T23:23:31",
"upload_time_iso_8601": "2025-09-02T23:23:31.738885Z",
"url": "https://files.pythonhosted.org/packages/db/3b/f14266a7c844944c6505398aca7bfbab257b1908d71d3aae12b1dce65994/subliminal-2.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f9d1f55d55bf7d585f6d749b60479b4f405de0d8805324d83c598ee3d540df79",
"md5": "12c440f06e06857873a76a130f4f8900",
"sha256": "73df6d1940166ef0e2cdeb4f8d655a4afe1082d481ec090ad2a9e66b1a1621fc"
},
"downloads": -1,
"filename": "subliminal-2.4.0.tar.gz",
"has_sig": false,
"md5_digest": "12c440f06e06857873a76a130f4f8900",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 3460114,
"upload_time": "2025-09-02T23:23:33",
"upload_time_iso_8601": "2025-09-02T23:23:33.442861Z",
"url": "https://files.pythonhosted.org/packages/f9/d1/f55d55bf7d585f6d749b60479b4f405de0d8805324d83c598ee3d540df79/subliminal-2.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-02 23:23:33",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Diaoul",
"github_project": "subliminal",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "subliminal"
}
JSON
