1SUBLIMINAL(1)                     subliminal                     SUBLIMINAL(1)
2
3
4

NAME

6       subliminal - subliminal Documentation
7
8       Subliminal  is  a python 2.7+ library to search and download subtitles.
9       It comes with an easy to use yet powerful CLI suitable for  direct  use
10       or cron jobs.
11

DOCUMENTATION

13   Usage
14   CLI
15       Download English subtitles:
16
17          $ subliminal download -l en The.Big.Bang.Theory.S05E18.HDTV.x264-LOL.mp4
18          Collecting videos  [####################################]  100%
19          1 video collected / 0 video ignored
20          Downloading subtitles  [####################################]  100%
21          Downloaded 1 subtitle
22
23       WARNING:
24          For  cron  usage, make sure to specify a maximum age (with --age) so
25          subtitles are searched for recent videos only.  Otherwise  you  will
26          get banned from the providers for abuse due to too many requests. If
27          subliminal didn’t find subtitles for an old video, it’s unlikely  it
28          will find subtitles for that video ever anyway.
29
30       See CLI for more details on the available commands and options.
31
32   Nautilus/Nemo integration
33       See the dedicated project page for more information.
34
35   High level API
36       You  can  call  subliminal in many different ways depending on how much
37       control you want over the process. For most use cases, you can stick to
38       the standard API.
39
40   Common
41       Let’s start by importing subliminal:
42
43       >>> import os
44       >>> from babelfish import *
45       >>> from subliminal import *
46
47       Before going further, there are a few things to know about subliminal.
48
49   Video
50       The  Movie  and Episode classes represent a video, existing or not. You
51       can  create  a  video  by  name  (or  path)  with  Video.fromname,  use
52       scan_video()  on  an  existing  file  path to get even more information
53       about the video or use scan_videos() on an existing directory  path  to
54       scan a whole directory for videos.
55
56       >>> video = Video.fromname('The.Big.Bang.Theory.S05E18.HDTV.x264-LOL.mp4')
57       >>> video
58       <Episode [The Big Bang Theory s05e18]>
59
60       Here  video information was guessed based on the name of the video, you
61       can access some video attributes:
62
63       >>> video.video_codec
64       'H.264'
65       >>> video.release_group
66       'LOL'
67
68   Configuration
69       Before proceeding to listing and downloading  subtitles,  you  need  to
70       configure the cache. Subliminal uses a cache to reduce repeated queries
71       to providers and improve overall performance with no impact  on  search
72       quality.  For  the  sake  of  this example, we’re going to use a memory
73       backend.
74
75       >>> my_region = region.configure('dogpile.cache.memory')
76
77       WARNING:
78          Choose a cache that fits your application and prefer persistent over
79          volatile  backends.  The file backend is usually a good choice.  See
80          dogpile.cache’s documentation for more details on backends.
81
82       Now that we’re done with the basics, let’s have some real fun.
83
84   Listing
85       To list subtitles, subliminal provides a list_subtitles() function that
86       will return all found subtitles:
87
88       >>> subtitles = list_subtitles([video], {Language('hun')}, providers=['podnapisi'])
89       >>> subtitles[video]
90       [<PodnapisiSubtitle 'ZtAW' [hu]>, <PodnapisiSubtitle 'ONAW' [hu]>]
91
92       NOTE:
93          As  you  noticed,  all parameters are iterables but only contain one
94          item which means you can deal with a lot of  videos,  languages  and
95          providers  at the same time. For the sake of this example, we filter
96          providers to use only one, pass providers=None (default)  to  search
97          on all providers.
98
99   Scoring
100       It’s  usual  you  have  multiple  candidates for subtitles. To help you
101       chose which one to download, subliminal can compare them to  the  video
102       and tell you exactly what matches with get_matches():
103
104       >>> for s in subtitles[video]:
105       ...     sorted(s.get_matches(video))
106       ['country', 'episode', 'release_group', 'season', 'series', 'source', 'video_codec', 'year']
107       ['country', 'episode', 'season', 'series', 'source', 'year']
108
109       And then compute a score with those matches with compute_score():
110
111       >>> for s in subtitles[video]:
112       ...     {s: compute_score(s, video)}
113       {<PodnapisiSubtitle 'ZtAW' [hu]>: 789}
114       {<PodnapisiSubtitle 'ONAW' [hu]>: 772}
115
116       Now you should have a better idea about which one you should choose.
117
118   Downloading
119       We  can  settle  on  the  first subtitle and download its content using
120       download_subtitles():
121
122       >>> subtitle = subtitles[video][0]
123       >>> subtitle.content is None
124       True
125       >>> download_subtitles([subtitle])
126       >>> subtitle.content.split(b'\n')[2]
127       b'Elszaladok a boltba'
128
129       If you want a string instead of bytes, you can access  decoded  content
130       with the text property:
131
132       >>> subtitle.text.split('\n')[3]
133       'néhány apróságért.'
134
135   Downloading best subtitles
136       Downloading  best subtitles is what you want to do in almost all cases,
137       as a shortcut for listing, scoring and downloading you  can  use  down‐
138       load_best_subtitles():
139
140       >>> best_subtitles = download_best_subtitles([video], {Language('hun')}, providers=['podnapisi'])
141       >>> best_subtitles[video]
142       [<PodnapisiSubtitle 'ZtAW' [hu]>]
143       >>> best_subtitle = best_subtitles[video][0]
144       >>> best_subtitle.content.split(b'\n')[2]
145       b'Elszaladok a boltba'
146
147       We end up with the same subtitle but with one line of code. Neat.
148
149   Save
150       We got ourselves a nice subtitle, now we can save it on the file system
151       using save_subtitles():
152
153       >>> save_subtitles(video, [best_subtitle])
154       [<PodnapisiSubtitle 'ZtAW' [hu]>]
155       >>> os.listdir()
156       ['The.Big.Bang.Theory.S05E18.HDTV.x264-LOL.hu.srt']
157
158   How it works
159   Providers
160       Subliminal uses multiple providers to give users a vast choice and have
161       a  better chance to find the best matching subtitles. Current supported
162       providers are:
163
164       • Addic7ed
165
166       • LegendasTV
167
168       • NapiProjekt
169
170       • OpenSubtitles
171
172       • Podnapisi
173
174       • Shooter
175
176       • TheSubDB
177
178       • TvSubtitles
179
180       Providers all inherit the same Provider base class and thus  share  the
181       same  API.  They are registered on the subliminal.providers entry point
182       and are exposed through the provider_manager for easy access.
183
184       To work with multiple providers seamlessly,  the  ProviderPool  exposes
185       the  same API but distributes it to its providers and AsyncProviderPool
186       does it asynchronously.
187
188   Scoring
189       Rating subtitles and comparing them is probably the most difficult part
190       and  this  is  where  subliminal excels with its powerful scoring algo‐
191       rithm.
192
193       Using guessit and enzyme, subliminal extracts properties of  the  video
194       and  match  them  with  the  properties of the subtitles found with the
195       providers.
196
197       Equations in subliminal.score give a score to each property  (called  a
198       match).  The  more  matches the video and the subtitle have, the higher
199       the score computed with compute_score() gets.
200
201   Libraries
202       Various libraries are used by subliminal and are key to its success:
203
204guessit to guess information from filenames
205
206enzyme to detect embedded subtitles in videos and  read  other  video
207         metadata
208
209babelfish to work with languages
210
211requests to make human readable HTTP requests
212
213BeautifulSoup to parse HTML and XML
214
215dogpile.cache to cache intermediate search results
216
217stevedore to manage the provider entry point
218
219chardet to detect subtitles’ encoding
220
221pysrt to validate downloaded subtitles
222
223   CLI
224   subliminal
225          Usage: subliminal [OPTIONS] COMMAND [ARGS]...
226
227            Subtitles, faster than your thoughts.
228
229          Options:
230            --addic7ed USERNAME PASSWORD    Addic7ed configuration.
231            --legendastv USERNAME PASSWORD  LegendasTV configuration.
232            --opensubtitles USERNAME PASSWORD
233                                            OpenSubtitles configuration.
234            --omdb APIKEY                   OMDB API key.
235            --cache-dir DIRECTORY           Path to the cache directory.  [default:
236                                            /builddir/.cache/subliminal]
237            --debug                         Print useful information for debugging
238                                            subliminal and for reporting bugs.
239            --version                       Show the version and exit.
240            --help                          Show this message and exit.
241
242          Commands:
243            cache     Cache management.
244            download  Download best subtitles.
245
246            Suggestions and bug reports are greatly appreciated:
247            https://github.com/Diaoul/subliminal/
248
249   subliminal download
250          Usage: subliminal download [OPTIONS] PATH...
251
252            Download best subtitles.
253
254            PATH can be an directory containing videos, a video file path or a video
255            file name. It can be used multiple times.
256
257            If an existing subtitle is detected (external or embedded) in the correct
258            language, the download is skipped for the associated video.
259
260          Options:
261            -l, --language LANGUAGE         Language as IETF code, e.g. en, pt-BR (can
262                                            be used multiple times).  [required]
263            -p, --provider [addic7ed|argenteam|legendastv|opensubtitles|opensubtitlesvip|podnapisi|shooter|thesubdb|tvsubtitles]
264                                            Provider to use (can be used multiple
265                                            times).
266            -r, --refiner [hash|metadata|omdb|tvdb]
267                                            Refiner to use (can be used multiple times).
268            -a, --age AGE                   Filter videos newer than AGE, e.g. 12h,
269                                            1w2d.
270            -d, --directory DIR             Directory where to save subtitles, default
271                                            is next to the video file.
272            -e, --encoding ENC              Subtitle file encoding, default is to
273                                            preserve original encoding.
274            -s, --single                    Save subtitle without language code in the
275                                            file name, i.e. use .srt extension. Do not
276                                            use this unless your media player requires
277                                            it.
278            -f, --force                     Force download even if a subtitle already
279                                            exist.
280            -hi, --hearing-impaired         Prefer hearing impaired subtitles.
281            -m, --min-score INTEGER RANGE   Minimum score for a subtitle to be
282                                            downloaded (0 to 100).  [0<=x<=100]
283            -w, --max-workers INTEGER RANGE
284                                            Maximum number of threads to use.
285                                            [1<=x<=50]
286            -z, --archives / -Z, --no-archives
287                                            Scan archives for videos (supported
288                                            extensions: .rar).  [default: z]
289            -v, --verbose                   Increase verbosity.
290            --help                          Show this message and exit.
291
292   subliminal cache
293          Usage: subliminal cache [OPTIONS]
294
295            Cache management.
296
297          Options:
298            --clear-subliminal  Clear subliminal's cache. Use this ONLY if your cache is
299                                corrupted or if you experience issues.
300            --help              Show this message and exit.
301
302   Provider Guide
303       This guide is going to explain how to add a Provider to subliminal. You
304       are encouraged to take a look at the existing providers, it  can  be  a
305       nice base to start your own provider.
306
307   Requirements
308       When  starting a provider you should be able to answer to the following
309       questions:
310
311       • What languages does my provider support?
312
313       • What are the language codes for the supported languages?
314
315       • Does my provider deliver subtitles for episodes? for movies?
316
317       • Does my provider require a video hash?
318
319       Each response of these questions will help  you  set  the  correct  at‐
320       tributes for your Provider.
321
322   Video Validation
323       Not  all  providers  deliver  subtitles for Episode. Some may require a
324       hash.  The check() method does validation against a  Video  object  and
325       will  return  False  if  the  given Video isn’t suitable. If you’re not
326       happy with the default implementation, you can override it.
327
328   Configuration
329       API keys must not be configurable by the user and must remain linked to
330       subliminal. Hence they must be written in the provider module.
331
332       Per-user authentication is allowed and must be configured at instantia‐
333       tion as keyword arguments. Configuration  will  be  done  by  the  user
334       through the provider_configs argument of the list_subtitles() and down‐
335       load_best_subtitles() functions. No network operation must be done dur‐
336       ing  instantiation,  only configuration. Any error in the configuration
337       must raise a ConfigurationError.
338
339       Beyond this point, if an error occurs, a generic  ProviderError  excep‐
340       tion  must  be raised. You can also use more explicit exception classes
341       AuthenticationError and DownloadLimitExceeded.
342
343   Initialization / Termination
344       Actual authentication operations must take place  in  the  initialize()
345       method.   If  you  need anything to be executed when the provider isn’t
346       used anymore like logout, use terminate().
347
348   Caching policy
349       To save bandwidth and improve querying time, intermediate  data  should
350       be  cached  when possible. Typical use case is when a query to retrieve
351       show ids is required prior to the query to actually search  for  subti‐
352       tles.  In  that  case  the function that gets the show id from the show
353       name must be cached.  Expiration time  should  be  SHOW_EXPIRATION_TIME
354       for shows and EPISODE_EXPIRATION_TIME for episodes.
355
356   Language
357       To  be  able  to handle various language codes, subliminal makes use of
358       babelfish Language and converters. You must set the attribute languages
359       with a set of supported Language.
360
361       If you cannot find a suitable converter for your provider, you can make
362       one of your own.
363
364   Querying
365       The query() method parameters must include all  aspects  of  provider’s
366       querying with primary types.
367
368   Subtitle
369       A custom Subtitle subclass must be created to represent a subtitle from
370       the provider.  It must have relevant attributes that  can  be  used  to
371       compute the matches of the subtitle against a Video object.
372
373   Score computation
374       To be able to compare subtitles coming from different providers between
375       them, the get_matches() method must be implemented.
376
377   Unittesting
378       All possible uses of query(), list_subtitles() and  download_subtitle()
379       methods  must have integration tests. Use vcrpy for recording and play‐
380       back of network activity.  Other functions must be unittested. If  nec‐
381       essary, you can use unittest.mock to mock some functions.
382

API DOCUMENTATION

384       If  you  are  looking  for information on a specific function, class or
385       method, this part of the documentation is for you.
386
387   Core
388       subliminal.core.ARCHIVE_EXTENSIONS
389              Supported archive extensions
390
391   Video
392       subliminal.video.VIDEO_EXTENSIONS
393              Video extensions
394
395   Subtitle
396       subliminal.subtitle.SUBTITLE_EXTENSIONS
397              Subtitle extensions
398
399   Providers
400   Addic7ed
401   LegendasTv
402   NapiProjekt
403   OpenSubtitles
404   Podnapisi
405   Shooter
406   TheSubDB
407   TVsubtitles
408   Refiners
409       Refiners enrich a Video object by adding information to it.
410
411       A refiner is a simple function:
412
413       subliminal.refiners.refine(video, **kwargs)
414
415              Parameters
416
417video (Video) – the video to refine.
418
419**kwargs – additional parameters for refiners.
420
421   Metadata
422       subliminal.refiners.metadata.refine(video,     embedded_subtitles=True,
423       **kwargs)
424              Refine a video by searching its metadata.
425
426              Several Video attributes can be found:
427
428resolution
429
430video_codec
431
432audio_codec
433
434subtitle_languages
435
436              Parameters
437                     embedded_subtitles  (bool)  –  search for embedded subti‐
438                     tles.
439
440   TVDB
441       subliminal.refiners.tvdb.refine(video, **kwargs)
442              Refine a video by searching TheTVDB.
443
444              NOTE:
445                 This refiner only work for instances of Episode.
446
447              Several attributes can be found:
448
449series
450
451year
452
453series_imdb_id
454
455series_tvdb_id
456
457title
458
459imdb_id
460
461tvdb_id
462
463   OMDb
464       subliminal.refiners.omdb.refine(video, apikey=None, **kwargs)
465              Refine a video by searching OMDb API.
466
467              Several Episode attributes can be found:
468
469series
470
471year
472
473series_imdb_id
474
475              Similarly, for a Movie:
476
477title
478
479year
480
481imdb_id
482
483   Extensions
484   Score
485       This module provides the default implementation  of  the  compute_score
486       parameter in download_best_subtitles() and download_best_subtitles().
487
488       NOTE:
489          To  avoid unnecessary dependency on sympy and boost subliminal’s im‐
490          port time, the resulting scores are hardcoded here and manually  up‐
491          dated when the set of equations change.
492
493       Available matches:
494
495          • hash
496
497          • title
498
499          • year
500
501          • country
502
503          • series
504
505          • season
506
507          • episode
508
509          • release_group
510
511          • streaming_service
512
513          • source
514
515          • audio_codec
516
517          • resolution
518
519          • hearing_impaired
520
521          • video_codec
522
523          • series_imdb_id
524
525          • imdb_id
526
527          • tvdb_id
528
529   Utils
530   Cache
531       subliminal.cache.SHOW_EXPIRATION_TIME
532              Expiration time for show caching
533
534       subliminal.cache.EPISODE_EXPIRATION_TIME
535              Expiration time for episode caching
536
537       subliminal.cache.REFINER_EXPIRATION_TIME
538              Expiration time for scraper searches
539
540       subliminal.cache.region
541              The CacheRegion
542
543       Refer  to dogpile.cache’s region configuration documentation to see how
544       to configure the region
545
546   CLI
547       Subliminal uses click to provide a powerful CLI.
548
549   Exceptions

LICENSE

551       MIT
552
553Index
554
555Module Index
556
557Search Page
558

AUTHOR

560       Antoine Bertin
561
563       2023, Antoine Bertin
564
565
566
567
5682.1.0                            Jan 20, 2023                    SUBLIMINAL(1)
Impressum