1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
|
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
Downloading subtitles [####################################] 100%
Downloaded 1 subtitle
.. warning::
For cron usage, make sure to specify a maximum age (with ``--age``) so subtitles are searched for recent videos
only. Otherwise you will get banned from the providers for abuse due to too many requests. If subliminal didn't
find subtitles for an old video, it's unlikely it will find subtitles for that video ever anyway.
You can use a configuration file in the `TOML <https://toml.io/>`_ format with the ``--config/-c`` option. If no configuration file is
provided, it looks for a ``subliminal.toml`` file in the default configuration folder for the application. This folder is
`OS dependent <https://github.com/platformdirs/platformdirs>`_:
- Linux: ``/home/<user>/.config/subliminal/subliminal.toml``
- MacOS: ``/Users/<user>/Library/Application Support/subliminal/subliminal.toml``
- Windows: ``C:\\Users\\<user>\\AppData\\Local\\Acme\\subliminal\\subliminal.toml``
See :ref:`cli` for more details on the available commands and options.
Nautilus/Nemo integration
-------------------------
See the dedicated `project page <https://github.com/Diaoul/nautilus-subliminal>`_ for more information.
Dolphin integration
-------------------
See `this Gist <https://gist.github.com/maurocolella/03a9f02c56b1a90c64f05683e2840d57>`_.
High level API
--------------
You can call subliminal in many different ways depending on how much control you want over the process. For most use
cases, you can stick to the standard API.
Common
^^^^^^
Let's start by importing subliminal:
>>> import os
>>> from babelfish import *
>>> from subliminal import *
Before going further, there are a few things to know about subliminal.
Video
^^^^^
The :class:`~subliminal.video.Movie` and :class:`~subliminal.video.Episode` classes represent a video,
existing or not. You can create a video by name (or path) with :meth:`Video.fromname <subliminal.video.Video.fromname>`,
use :func:`~subliminal.core.scan_video` on an existing file path to get even more information about the video or
use :func:`~subliminal.core.scan_videos` on an existing directory path to scan a whole directory for videos.
>>> video = Video.fromname('The.Big.Bang.Theory.S05E18.HDTV.x264-LOL.mp4')
>>> video
<Episode [The Big Bang Theory s05e18]>
Here video information was guessed based on the name of the video, you can access some video attributes:
>>> video.video_codec
'H.264'
>>> video.release_group
'LOL'
Configuration
^^^^^^^^^^^^^
Before proceeding to listing and downloading subtitles, you need to configure the cache. Subliminal uses a cache to
reduce repeated queries to providers and improve overall performance with no impact on search quality. For the sake
of this example, we're going to use a memory backend.
>>> my_region = region.configure('dogpile.cache.memory')
.. warning::
Choose a cache that fits your application and prefer persistent over volatile backends. The ``file`` backend is
usually a good choice.
See `dogpile.cache's documentation <http://dogpilecache.readthedocs.org>`_ for more details on backends.
Now that we're done with the basics, let's have some *real* fun.
Listing
^^^^^^^
To list subtitles, subliminal provides a :func:`~subliminal.core.list_subtitles` function that will return all found
subtitles:
>>> subtitles = list_subtitles([video], {Language('hun')}, providers=['podnapisi'])
>>> subtitles[video]
[<PodnapisiSubtitle 'ZtAW' [hu]>, <PodnapisiSubtitle 'ONAW' [hu]>]
.. note::
As you noticed, all parameters are iterables but only contain one item which means you can deal with a lot of
videos, languages and providers at the same time. For the sake of this example, we filter providers to use only one,
pass ``providers=None`` (default) to search on all providers.
Scoring
^^^^^^^
It's usual you have multiple candidates for subtitles. To help you chose which one to download, subliminal can compare
them to the video and tell you exactly what matches with :meth:`~subliminal.subtitle.Subtitle.get_matches`:
>>> for s in subtitles[video]:
... sorted(s.get_matches(video))
['country', 'episode', 'release_group', 'season', 'series', 'source', 'video_codec', 'year']
['country', 'episode', 'season', 'series', 'source', 'year']
And then compute a score with those matches with :func:`~subliminal.score.compute_score`:
>>> for s in subtitles[video]:
... {s: compute_score(s, video)}
{<PodnapisiSubtitle 'ZtAW' [hu]>: 789}
{<PodnapisiSubtitle 'ONAW' [hu]>: 772}
Now you should have a better idea about which one you should choose.
Downloading
^^^^^^^^^^^
We can settle on the first subtitle and download its content using :func:`~subliminal.core.download_subtitles`:
>>> subtitle = subtitles[video][0]
>>> subtitle.content is None
True
>>> download_subtitles([subtitle])
>>> subtitle.content.split(b'\n')[2]
b'Elszaladok a boltba'
If you want a string instead of bytes, you can access decoded content with the
:attr:`~subliminal.subtitle.Subtitle.text` property:
>>> subtitle.text.split('\n')[3]
'néhány apróságért.'
Downloading best subtitles
^^^^^^^^^^^^^^^^^^^^^^^^^^
Downloading best subtitles is what you want to do in almost all cases, as a shortcut for listing, scoring and
downloading you can use :func:`~subliminal.core.download_best_subtitles`:
>>> best_subtitles = download_best_subtitles([video], {Language('hun')}, providers=['podnapisi'])
>>> best_subtitles[video]
[<PodnapisiSubtitle 'ZtAW' [hu]>]
>>> best_subtitle = best_subtitles[video][0]
>>> best_subtitle.content.split(b'\n')[2]
b'Elszaladok a boltba'
We end up with the same subtitle but with one line of code. Neat.
Save
^^^^
We got ourselves a nice subtitle, now we can save it on the file system using :func:`~subliminal.core.save_subtitles`:
>>> save_subtitles(video, [best_subtitle])
[<PodnapisiSubtitle 'ZtAW' [hu]>]
>>> os.listdir()
['The.Big.Bang.Theory.S05E18.HDTV.x264-LOL.hu.srt']
|
