Metadata-Version: 2.4
Name: subliminal
Version: 2.4.1.dev2+gaca7845cb
Summary: Subtitles, faster than your thoughts
Project-URL: homepage, https://github.com/Diaoul/subliminal
Project-URL: repository, https://github.com/Diaoul/subliminal
Project-URL: documentation, https://subliminal.readthedocs.org
Author-email: Antoine Bertin <diaoulael@gmail.com>
Maintainer-email: Antoine Bertin <diaoulael@gmail.com>, getzze <getzze@gmail.com>, Patrycja Rosa <pypi@ptrcnull.me>
License: MIT
License-File: LICENSE
Keywords: episode,movie,series,show,subtitle,subtitles,tv,video
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Requires-Dist: babelfish>=0.6.1
Requires-Dist: beautifulsoup4>=4.4.0
Requires-Dist: chardet>=5.0
Requires-Dist: click-option-group>=0.5.6
Requires-Dist: click<8.3,>=8.0
Requires-Dist: defusedxml>=0.7.1
Requires-Dist: dogpile-cache>=1.0
Requires-Dist: guessit>=3.0.0
Requires-Dist: knowit>=0.5.5
Requires-Dist: platformdirs>=3
Requires-Dist: pysubs2>=1.7
Requires-Dist: requests>=2.0
Requires-Dist: srt>=3.5
Requires-Dist: stevedore>=3.0
Requires-Dist: tomlkit>=0.13.2
Provides-Extra: dev
Requires-Dist: pre-commit>=2.9.3; extra == 'dev'
Requires-Dist: tox; extra == 'dev'
Provides-Extra: docs
Requires-Dist: sphinx-autodoc-typehints; extra == 'docs'
Requires-Dist: sphinx-changelog; extra == 'docs'
Requires-Dist: sphinx-rtd-theme>=2; extra == 'docs'
Requires-Dist: sphinx<8.2; extra == 'docs'
Requires-Dist: sphinxcontrib-programoutput; extra == 'docs'
Requires-Dist: towncrier; extra == 'docs'
Requires-Dist: vcrpy>=5; extra == 'docs'
Provides-Extra: rar
Requires-Dist: rarfile>=2.7; extra == 'rar'
Provides-Extra: tests
Requires-Dist: colorama; extra == 'tests'
Requires-Dist: coverage[toml]>=7; extra == 'tests'
Requires-Dist: importlib-metadata>=4.6; (python_version < '3.10') and extra == 'tests'
Requires-Dist: pytest-cov; extra == 'tests'
Requires-Dist: pytest-xdist; extra == 'tests'
Requires-Dist: pytest>=6.0; extra == 'tests'
Requires-Dist: rarfile>=2.7; extra == 'tests'
Requires-Dist: sympy; extra == 'tests'
Requires-Dist: vcrpy>=5; extra == 'tests'
Requires-Dist: win32-setctime; (sys_platform == 'win32') and extra == 'tests'
Provides-Extra: types
Requires-Dist: mypy; extra == 'types'
Requires-Dist: types-beautifulsoup4; extra == 'types'
Requires-Dist: types-decorator; extra == 'types'
Requires-Dist: types-requests; extra == 'types'
Description-Content-Type: text/x-rst

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!
