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
238 subliminal and for reporting bugs.
239 --version Show the version and exit.
240 --help Show this message and exit.
241 Commands:
243 cache Cache management.
244 download Download best subtitles.
245 Suggestions and bug reports are greatly appreciated:
247 https://github.com/Diaoul/subliminal/
248 subliminal download
250 Usage: subliminal download [OPTIONS] PATH...
251 Download best subtitles.
253 PATH can be an directory containing videos, a video file path or a video
255 file name. It can be used multiple times.
256 If an existing subtitle is detected (external or embedded) in the correct
258 language, the download is skipped for the associated video.
259 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 subliminal cache
293 Usage: subliminal cache [OPTIONS]
294 Cache management.
296 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 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 Requirements
308 When starting a provider you should be able to answer to the following
309 questions:
310 • What languages does my provider support?
312 • What are the language codes for the supported languages?
314 • Does my provider deliver subtitles for episodes? for movies?
316 • Does my provider require a video hash?
318 Each response of these questions will help you set the correct at‐
320 tributes for your Provider.
321 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 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 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 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 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 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 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 If you cannot find a suitable converter for your provider, you can make
362 one of your own.
363 Querying
365 The query() method parameters must include all aspects of provider’s
366 querying with primary types.
367 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 Score computation
374 To be able to compare subtitles coming from different providers between
375 them, the get_matches() method must be implemented.
376 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
384 If you are looking for information on a specific function, class or
385 method, this part of the documentation is for you.
386 Core
388 subliminal.core.ARCHIVE_EXTENSIONS
389 Supported archive extensions
390 Video
392 subliminal.video.VIDEO_EXTENSIONS
393 Video extensions
394 Subtitle
396 subliminal.subtitle.SUBTITLE_EXTENSIONS
397 Subtitle extensions
398 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 A refiner is a simple function:
412 subliminal.refiners.refine(video, **kwargs)
414 Parameters
416 • video (Video) – the video to refine.
418 • **kwargs – additional parameters for refiners.
420 Metadata
422 subliminal.refiners.metadata.refine(video, embedded_subtitles=True,
423 **kwargs)
424 Refine a video by searching its metadata.
425 Several Video attributes can be found:
427 • resolution
429 • video_codec
431 • audio_codec
433 • subtitle_languages
435 Parameters
437 embedded_subtitles (bool) – search for embedded subti‐
438 tles.
439 TVDB
441 subliminal.refiners.tvdb.refine(video, **kwargs)
442 Refine a video by searching TheTVDB.
443 NOTE:
445 This refiner only work for instances of Episode.
446 Several attributes can be found:
448 • series
450 • year
452 • series_imdb_id
454 • series_tvdb_id
456 • title
458 • imdb_id
460 • tvdb_id
462 OMDb
464 subliminal.refiners.omdb.refine(video, apikey=None, **kwargs)
465 Refine a video by searching OMDb API.
466 Several Episode attributes can be found:
468 • series
470 • year
472 • series_imdb_id
474 Similarly, for a Movie:
476 • title
478 • year
480 • imdb_id
482 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 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 Available matches:
494 • hash
496 • title
498 • year
500 • country
502 • series
504 • season
506 • episode
508 • release_group
510 • streaming_service
512 • source
514 • audio_codec
516 • resolution
518 • hearing_impaired
520 • video_codec
522 • series_imdb_id
524 • imdb_id
526 • tvdb_id
528 Utils
530 Cache
531 subliminal.cache.SHOW_EXPIRATION_TIME
532 Expiration time for show caching
533 subliminal.cache.EPISODE_EXPIRATION_TIME
535 Expiration time for episode caching
536 subliminal.cache.REFINER_EXPIRATION_TIME
538 Expiration time for scraper searches
539 subliminal.cache.region
541 The CacheRegion
542 Refer to dogpile.cache’s region configuration documentation to see how
544 to configure the region
545 CLI
547 Subliminal uses click to provide a powerful CLI.
548 Exceptions
551 MIT
552 • Index
554 • Module Index
556 • Search Page
558
560 Antoine Bertin
561
563 2023, Antoine Bertin
5642.1.0 Jan 20, 2023 SUBLIMINAL(1)