1SUBLIMINAL(1) subliminal SUBLIMINAL(1)
2
6 subliminal - subliminal Documentation
7 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
13 Usage
14 CLI
15 Download English subtitles:
16 $ 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 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 See cli for more details on the available commands and options.
31 Nautilus/Nemo integration
33 See the dedicated project page for more information.
34 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 Common
41 Let’s start by importing subliminal:
42 >>> import os
44 >>> from babelfish import *
45 >>> from subliminal import *
46 Before going further, there are a few things to know about subliminal.
48 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 >>> video = Video.fromname('The.Big.Bang.Theory.S05E18.HDTV.x264-LOL.mp4')
57 >>> video
58 <Episode [The Big Bang Theory s05e18]>
59 Here video information was guessed based on the name of the video, you
61 can access some video attributes:
62 >>> video.video_codec
64 'H.264'
65 >>> video.release_group
66 'LOL'
67 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 >>> my_region = region.configure('dogpile.cache.memory')
76 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 Now that we’re done with the basics, let’s have some real fun.
83 Listing
85 To list subtitles, subliminal provides a list_subtitles() function that
86 will return all found subtitles:
87 >>> subtitles = list_subtitles([video], {Language('hun')}, providers=['podnapisi'])
89 >>> subtitles[video]
90 [<PodnapisiSubtitle 'ZtAW' [hu]>, <PodnapisiSubtitle 'ONAW' [hu]>]
91 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 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 >>> 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 And then compute a score with those matches with compute_score():
110 >>> for s in subtitles[video]:
112 ... {s: compute_score(s, video)}
113 {<PodnapisiSubtitle 'ZtAW' [hu]>: 789}
114 {<PodnapisiSubtitle 'ONAW' [hu]>: 772}
115 Now you should have a better idea about which one you should choose.
117 Downloading
119 We can settle on the first subtitle and download its content using
120 download_subtitles():
121 >>> 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 If you want a string instead of bytes, you can access decoded content
130 with the text property:
131 >>> subtitle.text.split('\n')[3]
133 'néhány apróságért.'
134 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 >>> 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 We end up with the same subtitle but with one line of code. Neat.
148 Save
150 We got ourselves a nice subtitle, now we can save it on the file system
151 using save_subtitles():
152 >>> save_subtitles(video, [best_subtitle])
154 [<PodnapisiSubtitle 'ZtAW' [hu]>]
155 >>> os.listdir()
156 ['The.Big.Bang.Theory.S05E18.HDTV.x264-LOL.hu.srt']
157 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 · Addic7ed
165 · LegendasTV
167 · NapiProjekt
169 · OpenSubtitles
171 · Podnapisi
173 · Shooter
175 · TheSubDB
177 · TvSubtitles
179 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 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 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 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 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 Libraries
202 Various libraries are used by subliminal and are key to its success:
203 · guessit to guess information from filenames
205 · enzyme to detect embedded subtitles in videos and read other video
207 metadata
208 · babelfish to work with languages
210 · requests to make human readable HTTP requests
212 · BeautifulSoup to parse HTML and XML
214 · dogpile.cache to cache intermediate search results
216 · stevedore to manage the provider entry point
218 · chardet to detect subtitles’ encoding
220 · pysrt to validate downloaded subtitles
222 CLI
224 subliminal
225 Usage: subliminal [OPTIONS] COMMAND [ARGS]...
226 Subtitles, faster than your thoughts.
228 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
239 subliminal and for reporting bugs.
240 --version Show the version and exit.
242 --help Show this message and exit.
243 Commands:
245 cache Cache management.
246 download Download best subtitles.
247 Suggestions and bug reports are greatly appreciated:
249 https://github.com/Diaoul/subliminal/
250 subliminal download
252 Usage: subliminal download [OPTIONS] PATH...
253 Download best subtitles.
255 PATH can be an directory containing videos, a video file path or a video
257 file name. It can be used multiple times.
258 If an existing subtitle is detected (external or embedded) in the correct
260 language, the download is skipped for the associated video.
261 Options:
263 -l, --language LANGUAGE Language as IETF code, e.g. en, pt-BR (can
264 be used multiple times). [required]
265 -p, --provider [addic7ed|argenteam|legendastv|opensubtitles|opensubtitlesvip|podnapisi|shooter|thesubdb|tvsubtitles]
267 Provider to use (can be used multiple
268 times).
269 -r, --refiner [hash|metadata|omdb|tvdb]
271 Refiner to use (can be used multiple times).
272 -a, --age AGE Filter videos newer than AGE, e.g. 12h,
273 1w2d.
274 -d, --directory DIR Directory where to save subtitles, default
276 is next to the video file.
277 -e, --encoding ENC Subtitle file encoding, default is to
279 preserve original encoding.
280 -s, --single Save subtitle without language code in the
282 file name, i.e. use .srt extension. Do not
283 use this unless your media player requires
284 it.
285 -f, --force Force download even if a subtitle already
287 exist.
288 -hi, --hearing-impaired Prefer hearing impaired subtitles.
290 -m, --min-score INTEGER RANGE Minimum score for a subtitle to be
291 downloaded (0 to 100).
292 -w, --max-workers INTEGER RANGE
294 Maximum number of threads to use.
295 -z, --archives / -Z, --no-archives
296 Scan archives for videos (supported
297 extensions: .rar). [default: True]
298 -v, --verbose Increase verbosity.
300 --help Show this message and exit.
301 subliminal cache
303 Usage: subliminal cache [OPTIONS]
304 Cache management.
306 Options:
308 --clear-subliminal Clear subliminal's cache. Use this ONLY if your cache is
309 corrupted or if you experience issues.
310 --help Show this message and exit.
312 Provider Guide
314 This guide is going to explain how to add a Provider to subliminal. You
315 are encouraged to take a look at the existing providers, it can be a
316 nice base to start your own provider.
317 Requirements
319 When starting a provider you should be able to answer to the following
320 questions:
321 · What languages does my provider support?
323 · What are the language codes for the supported languages?
325 · Does my provider deliver subtitles for episodes? for movies?
327 · Does my provider require a video hash?
329 Each response of these questions will help you set the correct
331 attributes for your Provider.
332 Video Validation
334 Not all providers deliver subtitles for Episode. Some may require a
335 hash. The check() method does validation against a Video object and
336 will return False if the given Video isn’t suitable. If you’re not
337 happy with the default implementation, you can override it.
338 Configuration
340 API keys must not be configurable by the user and must remain linked to
341 subliminal. Hence they must be written in the provider module.
342 Per-user authentication is allowed and must be configured at instantia‐
344 tion as keyword arguments. Configuration will be done by the user
345 through the provider_configs argument of the list_subtitles() and down‐
346 load_best_subtitles() functions. No network operation must be done dur‐
347 ing instantiation, only configuration. Any error in the configuration
348 must raise a ConfigurationError.
349 Beyond this point, if an error occurs, a generic ProviderError excep‐
351 tion must be raised. You can also use more explicit exception classes
352 AuthenticationError and DownloadLimitExceeded.
353 Initialization / Termination
355 Actual authentication operations must take place in the initialize()
356 method. If you need anything to be executed when the provider isn’t
357 used anymore like logout, use terminate().
358 Caching policy
360 To save bandwidth and improve querying time, intermediate data should
361 be cached when possible. Typical use case is when a query to retrieve
362 show ids is required prior to the query to actually search for subti‐
363 tles. In that case the function that gets the show id from the show
364 name must be cached. Expiration time should be SHOW_EXPIRATION_TIME
365 for shows and EPISODE_EXPIRATION_TIME for episodes.
366 Language
368 To be able to handle various language codes, subliminal makes use of
369 babelfish Language and converters. You must set the attribute languages
370 with a set of supported Language.
371 If you cannot find a suitable converter for your provider, you can make
373 one of your own.
374 Querying
376 The query() method parameters must include all aspects of provider’s
377 querying with primary types.
378 Subtitle
380 A custom Subtitle subclass must be created to represent a subtitle from
381 the provider. It must have relevant attributes that can be used to
382 compute the matches of the subtitle against a Video object.
383 Score computation
385 To be able to compare subtitles coming from different providers between
386 them, the get_matches() method must be implemented.
387 Unittesting
389 All possible uses of query(), list_subtitles() and download_subtitle()
390 methods must have integration tests. Use vcrpy for recording and play‐
391 back of network activity. Other functions must be unittested. If nec‐
392 essary, you can use unittest.mock to mock some functions.
393
395 If you are looking for information on a specific function, class or
396 method, this part of the documentation is for you.
397 Core
399 subliminal.core.ARCHIVE_EXTENSIONS
400 Supported archive extensions
401 Video
403 subliminal.video.VIDEO_EXTENSIONS
404 Video extensions
405 Subtitle
407 subliminal.subtitle.SUBTITLE_EXTENSIONS
408 Subtitle extensions
409 Providers
411 Addic7ed
412 LegendasTv
413 NapiProjekt
414 OpenSubtitles
415 Podnapisi
416 Shooter
417 TheSubDB
418 TVsubtitles
419 Refiners
420 Refiners enrich a Video object by adding information to it.
421 A refiner is a simple function:
423 subliminal.refiners.refine(video, **kwargs)
425 Parameters
427 · video (Video) – the video to refine.
429 · **kwargs – additional parameters for refiners.
431 Metadata
433 subliminal.refiners.metadata.refine(video, embedded_subtitles=True,
434 **kwargs)
435 Refine a video by searching its metadata.
436 Several Video attributes can be found:
438 · resolution
440 · video_codec
442 · audio_codec
444 · subtitle_languages
446 Parameters
448 embedded_subtitles (bool) – search for embedded subti‐
449 tles.
450 TVDB
452 subliminal.refiners.tvdb.refine(video, **kwargs)
453 Refine a video by searching TheTVDB.
454 NOTE:
456 This refiner only work for instances of Episode.
457 Several attributes can be found:
459 · series
461 · year
463 · series_imdb_id
465 · series_tvdb_id
467 · title
469 · imdb_id
471 · tvdb_id
473 OMDb
475 subliminal.refiners.omdb.refine(video, apikey=None, **kwargs)
476 Refine a video by searching OMDb API.
477 Several Episode attributes can be found:
479 · series
481 · year
483 · series_imdb_id
485 Similarly, for a Movie:
487 · title
489 · year
491 · imdb_id
493 Extensions
495 Score
496 This module provides the default implementation of the compute_score
497 parameter in download_best_subtitles() and download_best_subtitles().
498 NOTE:
500 To avoid unnecessary dependency on sympy and boost subliminal’s
501 import time, the resulting scores are hardcoded here and manually
502 updated when the set of equations change.
503 Available matches:
505 · hash
507 · title
509 · year
511 · country
513 · series
515 · season
517 · episode
519 · release_group
521 · streaming_service
523 · source
525 · audio_codec
527 · resolution
529 · hearing_impaired
531 · video_codec
533 · series_imdb_id
535 · imdb_id
537 · tvdb_id
539 Utils
541 Cache
542 subliminal.cache.SHOW_EXPIRATION_TIME
543 Expiration time for show caching
544 subliminal.cache.EPISODE_EXPIRATION_TIME
546 Expiration time for episode caching
547 subliminal.cache.REFINER_EXPIRATION_TIME
549 Expiration time for scraper searches
550 subliminal.cache.region
552 The CacheRegion
553 Refer to dogpile.cache’s region configuration documentation to see how
555 to configure the region
556 CLI
558 Subliminal uses click to provide a powerful CLI.
559 Exceptions
562 MIT
563 · genindex
565 · modindex
567 · search
569
571 Antoine Bertin
572
574 2020, Antoine Bertin
5752.1.0 Jul 29, 2020 SUBLIMINAL(1)