README.rst
1Subliminal
2==========
3Subtitles, faster than your thoughts.
4
5.. image:: https://img.shields.io/pypi/v/subliminal.svg
6 :target: https://pypi.python.org/pypi/subliminal
7 :alt: Latest Version
8
9.. image:: https://travis-ci.org/Diaoul/subliminal.svg?branch=develop
10 :target: https://travis-ci.org/Diaoul/subliminal
11 :alt: Travis CI build status
12
13.. image:: https://readthedocs.org/projects/subliminal/badge/?version=latest
14 :target: https://subliminal.readthedocs.org/
15 :alt: Documentation Status
16
17.. image:: https://coveralls.io/repos/Diaoul/subliminal/badge.svg?branch=develop&service=github
18 :target: https://coveralls.io/github/Diaoul/subliminal?branch=develop
19 :alt: Code coverage
20
21.. image:: https://img.shields.io/github/license/Diaoul/subliminal.svg
22 :target: https://github.com/Diaoul/subliminal/blob/master/LICENSE
23 :alt: License
24
25.. image:: https://img.shields.io/badge/gitter-join%20chat-1dce73.svg
26 :alt: Join the chat at https://gitter.im/Diaoul/subliminal
27 :target: https://gitter.im/Diaoul/subliminal
28
29
30:Project page: https://github.com/Diaoul/subliminal
31:Documentation: https://subliminal.readthedocs.org/
32
33
34Usage
35-----
36CLI
37^^^
38Download English subtitles::
39
40 $ subliminal download -l en The.Big.Bang.Theory.S05E18.HDTV.x264-LOL.mp4
41 Collecting videos [####################################] 100%
42 1 video collected / 0 video ignored / 0 error
43 Downloading subtitles [####################################] 100%
44 Downloaded 1 subtitle
45
46Library
47^^^^^^^
48Download best subtitles in French and English for videos less than two weeks old in a video folder:
49
50.. code:: python
51
52 #!/usr/bin/env python
53
54 from datetime import timedelta
55
56 from babelfish import Language
57 from subliminal import download_best_subtitles, region, save_subtitles, scan_videos
58
59 # configure the cache
60 region.configure('dogpile.cache.dbm', arguments={'filename': 'cachefile.dbm'})
61
62 # scan for videos newer than 2 weeks and their existing subtitles in a folder
63 videos = scan_videos('/video/folder', age=timedelta(weeks=2))
64
65 # download best subtitles
66 subtitles = download_best_subtitles(videos, {Language('eng'), Language('fra')})
67
68 # save them to disk, next to the video
69 for v in videos:
70 save_subtitles(v, subtitles[v])
71
72Docker
73^^^^^^
74Run subliminal in a docker container::
75
76 $ docker run --rm --name subliminal -v subliminal_cache:/usr/src/cache -v /tvshows:/tvshows -it diaoulael/subliminal download -l en /tvshows/The.Big.Bang.Theory.S05E18.HDTV.x264-LOL.mp4
77
78Installation
79------------
80Subliminal can be installed as a regular python module by running::
81
82 $ [sudo] pip install subliminal
83
84For a better isolation with your system you should use a dedicated virtualenv or install for your user only using
85the ``--user`` flag.
86
87Nautilus/Nemo integration
88-------------------------
89See the dedicated `project page <https://github.com/Diaoul/nautilus-subliminal>`_ for more information.
90
