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', 5x18]>
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 'h264'
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 ['episode', 'format', 'release_group', 'season', 'series', 'video_codec', 'year']
107 ['episode', 'format', 'season', 'series', '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]>: 354}
114 {<PodnapisiSubtitle 'ONAW' [hu]>: 337}
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 · SubsCenter
177 · TheSubDB
179 · TvSubtitles
181 Providers all inherit the same Provider base class and thus share the
183 same API. They are registered on the subliminal.providers entry point
184 and are exposed through the provider_manager for easy access.
185 To work with multiple providers seamlessly, the ProviderPool exposes
187 the same API but distributes it to its providers and AsyncProviderPool
188 does it asynchronously.
189 Scoring
191 Rating subtitles and comparing them is probably the most difficult part
192 and this is where subliminal excels with its powerful scoring algo‐
193 rithm.
194 Using guessit and enzyme, subliminal extracts properties of the video
196 and match them with the properties of the subtitles found with the
197 providers.
198 Equations in subliminal.score give a score to each property (called a
200 match). The more matches the video and the subtitle have, the higher
201 the score computed with compute_score() gets.
202 Libraries
204 Various libraries are used by subliminal and are key to its success:
205 · guessit to guess information from filenames
207 · enzyme to detect embedded subtitles in videos and read other video
209 metadata
210 · babelfish to work with languages
212 · requests to make human readable HTTP requests
214 · BeautifulSoup to parse HTML and XML
216 · dogpile.cache to cache intermediate search results
218 · stevedore to manage the provider entry point
220 · chardet to detect subtitles’ encoding
222 · pysrt to validate downloaded subtitles
224 CLI
226 subliminal
227 Usage: subliminal [OPTIONS] COMMAND [ARGS]...
228 Subtitles, faster than your thoughts.
230 Options:
232 --addic7ed USERNAME PASSWORD Addic7ed configuration.
233 --legendastv USERNAME PASSWORD LegendasTV configuration.
234 --opensubtitles USERNAME PASSWORD
235 OpenSubtitles configuration.
236 --subscenter USERNAME PASSWORD SubsCenter configuration.
237 --cache-dir DIRECTORY Path to the cache directory. [default:
238 /builddir/.cache/subliminal]
239 --debug Print useful information for debugging
240 subliminal and for reporting bugs.
241 --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|legendastv|opensubtitles|podnapisi|shooter|subscenter|thesubdb|tvsubtitles]
266 Provider to use (can be used multiple
267 times).
268 -r, --refiner [metadata|omdb|tvdb]
269 Refiner to use (can be used multiple times).
270 -a, --age AGE Filter videos newer than AGE, e.g. 12h,
271 1w2d.
272 -d, --directory DIR Directory where to save subtitles, default
273 is next to the video file.
274 -e, --encoding ENC Subtitle file encoding, default is to
275 preserve original encoding.
276 -s, --single Save subtitle without language code in the
277 file name, i.e. use .srt extension. Do not
278 use this unless your media player requires
279 it.
280 -f, --force Force download even if a subtitle already
281 exist.
282 -hi, --hearing-impaired Prefer hearing impaired subtitles.
283 -m, --min-score INTEGER RANGE Minimum score for a subtitle to be
284 downloaded (0 to 100).
285 -w, --max-workers INTEGER RANGE
286 Maximum number of threads to use.
287 -z, --archives / -Z, --no-archives
288 Scan archives for videos (supported
289 extensions: .rar). [default: True]
290 -v, --verbose Increase verbosity.
291 --help Show this message and exit.
292 subliminal cache
294 Usage: subliminal cache [OPTIONS]
295 Cache management.
297 Options:
299 --clear-subliminal Clear subliminal's cache. Use this ONLY if your cache is
300 corrupted or if you experience issues.
301 --help Show this message and exit.
302 Provider Guide
304 This guide is going to explain how to add a Provider to subliminal. You
305 are encouraged to take a look at the existing providers, it can be a
306 nice base to start your own provider.
307 Requirements
309 When starting a provider you should be able to answer to the following
310 questions:
311 · What languages does my provider support?
313 · What are the language codes for the supported languages?
315 · Does my provider deliver subtitles for episodes? for movies?
317 · Does my provider require a video hash?
319 Each response of these questions will help you set the correct
321 attributes for your Provider.
322 Video Validation
324 Not all providers deliver subtitles for Episode. Some may require a
325 hash. The check() method does validation against a Video object and
326 will return False if the given Video isn’t suitable. If you’re not
327 happy with the default implementation, you can override it.
328 Configuration
330 API keys must not be configurable by the user and must remain linked to
331 subliminal. Hence they must be written in the provider module.
332 Per-user authentication is allowed and must be configured at instantia‐
334 tion as keyword arguments. Configuration will be done by the user
335 through the provider_configs argument of the list_subtitles() and down‐
336 load_best_subtitles() functions. No network operation must be done dur‐
337 ing instantiation, only configuration. Any error in the configuration
338 must raise a ConfigurationError.
339 Beyond this point, if an error occurs, a generic ProviderError excep‐
341 tion must be raised. You can also use more explicit exception classes
342 AuthenticationError and DownloadLimitExceeded.
343 Initialization / Termination
345 Actual authentication operations must take place in the initialize()
346 method. If you need anything to be executed when the provider isn’t
347 used anymore like logout, use terminate().
348 Caching policy
350 To save bandwidth and improve querying time, intermediate data should
351 be cached when possible. Typical use case is when a query to retrieve
352 show ids is required prior to the query to actually search for subti‐
353 tles. In that case the function that gets the show id from the show
354 name must be cached. Expiration time should be SHOW_EXPIRATION_TIME
355 for shows and EPISODE_EXPIRATION_TIME for episodes.
356 Language
358 To be able to handle various language codes, subliminal makes use of
359 babelfish Language and converters. You must set the attribute languages
360 with a set of supported Language.
361 If you cannot find a suitable converter for your provider, you can make
363 one of your own.
364 Querying
366 The query() method parameters must include all aspects of provider’s
367 querying with primary types.
368 Subtitle
370 A custom Subtitle subclass must be created to represent a subtitle from
371 the provider. It must have relevant attributes that can be used to
372 compute the matches of the subtitle against a Video object.
373 Score computation
375 To be able to compare subtitles coming from different providers between
376 them, the get_matches() method must be implemented.
377 Unittesting
379 All possible uses of query(), list_subtitles() and download_subtitle()
380 methods must have integration tests. Use vcrpy for recording and play‐
381 back of network activity. Other functions must be unittested. If nec‐
382 essary, you can use unittest.mock to mock some functions.
383
385 If you are looking for information on a specific function, class or
386 method, this part of the documentation is for you.
387 Core
389 subliminal.core.ARCHIVE_EXTENSIONS
390 Supported archive extensions
391 class subliminal.core.ProviderPool(providers=None, provider_con‐
393 figs=None)
394 A pool of providers with the same API as a single Provider.
395 It has a few extra features:
397 · Lazy loads providers when needed and supports the with
399 statement to terminate() the providers on exit.
400 · Automatically discard providers on failure.
402 Parameters
404 · providers (list) – name of providers to use, if not
406 all.
407 · provider_configs (dict) – provider configuration as
409 keyword arguments per provider name to pass when
410 instanciating the Provider.
411 providers = None
413 Name of providers to use
414 provider_configs = None
416 Provider configuration
417 initialized_providers = None
419 Initialized providers
420 discarded_providers = None
422 Discarded providers
423 list_subtitles_provider(provider, video, languages)
425 List subtitles with a single provider.
426 The video and languages are checked against the provider.
428 Parameters
430 · provider (str) – name of the provider.
432 · video (Video) – video to list subtitles for.
434 · languages (set of Language) – languages to
436 search for.
437 Returns
439 found subtitles.
440 Return type
442 list of Subtitle or None
443 list_subtitles(video, languages)
445 List subtitles.
446 Parameters
448 · video (Video) – video to list subtitles for.
450 · languages (set of Language) – languages to
452 search for.
453 Returns
455 found subtitles.
456 Return type
458 list of Subtitle
459 download_subtitle(subtitle)
461 Download subtitle’s content.
462 Parameters
464 subtitle (Subtitle) – subtitle to download.
465 Returns
467 True if the subtitle has been successfully down‐
468 loaded, False otherwise.
469 Return type
471 bool
472 download_best_subtitles(subtitles, video, languages,
474 min_score=0, hearing_impaired=False, only_one=False, com‐
475 pute_score=None)
476 Download the best matching subtitles.
477 Parameters
479 · subtitles (list of Subtitle) – the subtitles to
481 use.
482 · video (Video) – video to download subtitles for.
484 · languages (set of Language) – languages to down‐
486 load.
487 · min_score (int) – minimum score for a subtitle
489 to be downloaded.
490 · hearing_impaired (bool) – hearing impaired pref‐
492 erence.
493 · only_one (bool) – download only one subtitle,
495 not one per language.
496 · compute_score – function that takes subtitle and
498 video as positional arguments, hearing_impaired
499 as keyword argument and returns the score.
500 Returns
502 downloaded subtitles.
503 Return type
505 list of Subtitle
506 terminate()
508 Terminate all the initialized_providers.
509 class subliminal.core.AsyncProviderPool(max_workers=None, *args,
511 **kwargs)
512 Subclass of ProviderPool with asynchronous support for
513 list_subtitles().
514 Parameters
516 max_workers (int) – maximum number of threads to use. If
517 None, max_workers will be set to the number of providers.
518 max_workers = None
520 Maximum number of threads to use
521 list_subtitles_provider(provider, video, languages)
523 List subtitles with a single provider.
524 The video and languages are checked against the provider.
526 Parameters
528 · provider (str) – name of the provider.
530 · video (Video) – video to list subtitles for.
532 · languages (set of Language) – languages to
534 search for.
535 Returns
537 found subtitles.
538 Return type
540 list of Subtitle or None
541 list_subtitles(video, languages)
543 List subtitles.
544 Parameters
546 · video (Video) – video to list subtitles for.
548 · languages (set of Language) – languages to
550 search for.
551 Returns
553 found subtitles.
554 Return type
556 list of Subtitle
557 subliminal.core.check_video(video, languages=None, age=None, unde‐
559 fined=False)
560 Perform some checks on the video.
561 All the checks are optional. Return False if any of this check
563 fails:
564 · languages already exist in video’s subtitle_languages.
566 · video is older than age.
568 · video has an undefined language in subtitle_languages.
570 Parameters
572 · video (Video) – video to check.
574 · languages (set of Language) – desired languages.
576 · age (datetime.timedelta) – maximum age of the video.
578 · undefined (bool) – fail on existing undefined language.
580 Returns
582 True if the video passes the checks, False otherwise.
583 Return type
585 bool
586 subliminal.core.search_external_subtitles(path, directory=None)
588 Search for external subtitles from a video path and their asso‐
589 ciated language.
590 Unless directory is provided, search will be made in the same
592 directory as the video file.
593 Parameters
595 · path (str) – path to the video.
597 · directory (str) – directory to search for subtitles.
599 Returns
601 found subtitles with their languages.
602 Return type
604 dict
605 subliminal.core.scan_video(path)
607 Scan a video from a path.
608 Parameters
610 path (str) – existing path to the video.
611 Returns
613 the scanned video.
614 Return type
616 Video
617 subliminal.core.scan_archive(path)
619 Scan an archive from a path.
620 Parameters
622 path (str) – existing path to the archive.
623 Returns
625 the scanned video.
626 Return type
628 Video
629 subliminal.core.scan_videos(path, age=None, archives=True)
631 Scan path for videos and their subtitles.
632 See refine() to find additional information for the video.
634 Parameters
636 · path (str) – existing directory path to scan.
638 · age (datetime.timedelta) – maximum age of the video or
640 archive.
641 · archives (bool) – scan videos in archives.
643 Returns
645 the scanned videos.
646 Return type
648 list of Video
649 subliminal.core.refine(video, episode_refiners=None, movie_refin‐
651 ers=None, **kwargs)
652 Refine a video using refiners.
653 NOTE:
655 Exceptions raised in refiners are silently passed and logged.
656 Parameters
658 · video (Video) – the video to refine.
660 · episode_refiners (tuple) – refiners to use for
662 episodes.
663 · movie_refiners (tuple) – refiners to use for movies.
665 · **kwargs – additional parameters for the refine() func‐
667 tions.
668 subliminal.core.list_subtitles(videos, languages, pool_class=<class
670 'subliminal.core.ProviderPool'>, **kwargs)
671 List subtitles.
672 The videos must pass the languages check of check_video().
674 Parameters
676 · videos (set of Video) – videos to list subtitles for.
678 · languages (set of Language) – languages to search for.
680 · pool_class (ProviderPool, AsyncProviderPool or similar)
682 – class to use as provider pool.
683 · **kwargs – additional parameters for the provided
685 pool_class constructor.
686 Returns
688 found subtitles per video.
689 Return type
691 dict of Video to list of Subtitle
692 subliminal.core.download_subtitles(subtitles, pool_class=<class 'sub‐
694 liminal.core.ProviderPool'>, **kwargs)
695 Download content of subtitles.
696 Parameters
698 · subtitles (list of Subtitle) – subtitles to download.
700 · pool_class (ProviderPool, AsyncProviderPool or similar)
702 – class to use as provider pool.
703 · **kwargs – additional parameters for the provided
705 pool_class constructor.
706 subliminal.core.download_best_subtitles(videos, languages, min_score=0,
708 hearing_impaired=False, only_one=False, compute_score=None,
709 pool_class=<class 'subliminal.core.ProviderPool'>, **kwargs)
710 List and download the best matching subtitles.
711 The videos must pass the languages and undefined (only_one)
713 checks of check_video().
714 Parameters
716 · videos (set of Video) – videos to download subtitles
718 for.
719 · languages (set of Language) – languages to download.
721 · min_score (int) – minimum score for a subtitle to be
723 downloaded.
724 · hearing_impaired (bool) – hearing impaired preference.
726 · only_one (bool) – download only one subtitle, not one
728 per language.
729 · compute_score – function that takes subtitle and video
731 as positional arguments, hearing_impaired as keyword
732 argument and returns the score.
733 · pool_class (ProviderPool, AsyncProviderPool or similar)
735 – class to use as provider pool.
736 · **kwargs – additional parameters for the provided
738 pool_class constructor.
739 Returns
741 downloaded subtitles per video.
742 Return type
744 dict of Video to list of Subtitle
745 subliminal.core.save_subtitles(video, subtitles, single=False, direc‐
747 tory=None, encoding=None)
748 Save subtitles on filesystem.
749 Subtitles are saved in the order of the list. If a subtitle with
751 a language has already been saved, other subtitles with the same
752 language are silently ignored.
753 The extension used is .lang.srt by default or .srt is single is
755 True, with lang being the IETF code for the language of the sub‐
756 title.
757 Parameters
759 · video (Video) – video of the subtitles.
761 · subtitles (list of Subtitle) – subtitles to save.
763 · single (bool) – save a single subtitle, default is to
765 save one subtitle per language.
766 · directory (str) – path to directory where to save the
768 subtitles, default is next to the video.
769 · encoding (str) – encoding in which to save the subti‐
771 tles, default is to keep original encoding.
772 Returns
774 the saved subtitles
775 Return type
777 list of Subtitle
778 Video
780 subliminal.video.VIDEO_EXTENSIONS
781 Video extensions
782 class subliminal.video.Video(name, format=None, release_group=None,
784 resolution=None, video_codec=None, audio_codec=None, imdb_id=None,
785 hashes=None, size=None, subtitle_languages=None)
786 Base class for videos.
787 Represent a video, existing or not.
789 Parameters
791 · name (str) – name or path of the video.
793 · format (str) – format of the video (HDTV, WEB-DL, Blu‐
795 Ray, …).
796 · release_group (str) – release group of the video.
798 · resolution (str) – resolution of the video stream
800 (480p, 720p, 1080p or 1080i).
801 · video_codec (str) – codec of the video stream.
803 · audio_codec (str) – codec of the main audio stream.
805 · imdb_id (str) – IMDb id of the video.
807 · hashes (dict) – hashes of the video file by provider
809 names.
810 · size (int) – size of the video file in bytes.
812 · subtitle_languages (set) – existing subtitle languages.
814 name = None
816 Name or path of the video
817 format = None
819 Format of the video (HDTV, WEB-DL, BluRay, …)
820 release_group = None
822 Release group of the video
823 resolution = None
825 Resolution of the video stream (480p, 720p, 1080p or
826 1080i)
827 video_codec = None
829 Codec of the video stream
830 audio_codec = None
832 Codec of the main audio stream
833 imdb_id = None
835 IMDb id of the video
836 hashes = None
838 Hashes of the video file by provider names
839 size = None
841 Size of the video file in bytes
842 subtitle_languages = None
844 Existing subtitle languages
845 property exists
847 Test whether the video exists
848 property age
850 Age of the video
851 classmethod fromguess(name, guess)
853 Create an Episode or a Movie with the given name based on
854 the guess.
855 Parameters
857 · name (str) – name of the video.
859 · guess (dict) – guessed data.
861 Raise ValueError if the type of the guess is invalid
863 classmethod fromname(name)
865 Shortcut for fromguess() with a guess guessed from the
866 name.
867 Parameters
869 name (str) – name of the video.
870 class subliminal.video.Episode(name, series, season, episode,
872 title=None, year=None, original_series=True, tvdb_id=None,
873 series_tvdb_id=None, series_imdb_id=None, **kwargs)
874 Episode Video.
875 Parameters
877 · series (str) – series of the episode.
879 · season (int) – season number of the episode.
881 · episode (int) – episode number of the episode.
883 · title (str) – title of the episode.
885 · year (int) – year of the series.
887 · original_series (bool) – whether the series is the
889 first with this name.
890 · tvdb_id (int) – TVDB id of the episode.
892 · **kwargs – additional parameters for the Video con‐
894 structor.
895 series = None
897 Series of the episode
898 season = None
900 Season number of the episode
901 episode = None
903 Episode number of the episode
904 title = None
906 Title of the episode
907 year = None
909 Year of series
910 original_series = None
912 The series is the first with this name
913 tvdb_id = None
915 TVDB id of the episode
916 series_tvdb_id = None
918 TVDB id of the series
919 series_imdb_id = None
921 IMDb id of the series
922 classmethod fromguess(name, guess)
924 Create an Episode or a Movie with the given name based on
925 the guess.
926 Parameters
928 · name (str) – name of the video.
930 · guess (dict) – guessed data.
932 Raise ValueError if the type of the guess is invalid
934 classmethod fromname(name)
936 Shortcut for fromguess() with a guess guessed from the
937 name.
938 Parameters
940 name (str) – name of the video.
941 class subliminal.video.Movie(name, title, year=None, **kwargs)
943 Movie Video.
944 Parameters
946 · title (str) – title of the movie.
948 · year (int) – year of the movie.
950 · **kwargs – additional parameters for the Video con‐
952 structor.
953 title = None
955 Title of the movie
956 year = None
958 Year of the movie
959 classmethod fromguess(name, guess)
961 Create an Episode or a Movie with the given name based on
962 the guess.
963 Parameters
965 · name (str) – name of the video.
967 · guess (dict) – guessed data.
969 Raise ValueError if the type of the guess is invalid
971 classmethod fromname(name)
973 Shortcut for fromguess() with a guess guessed from the
974 name.
975 Parameters
977 name (str) – name of the video.
978 Subtitle
980 subliminal.subtitle.SUBTITLE_EXTENSIONS
981 Subtitle extensions
982 class subliminal.subtitle.Subtitle(language, hearing_impaired=False,
984 page_link=None, encoding=None)
985 Base class for subtitle.
986 Parameters
988 · language (Language) – language of the subtitle.
990 · hearing_impaired (bool) – whether or not the subtitle
992 is hearing impaired.
993 · page_link (str) – URL of the web page from which the
995 subtitle can be downloaded.
996 · encoding (str) – Text encoding of the subtitle.
998 provider_name = ''
1000 Name of the provider that returns that class of subtitle
1001 language = None
1003 Language of the subtitle
1004 hearing_impaired = None
1006 Whether or not the subtitle is hearing impaired
1007 page_link = None
1009 URL of the web page from which the subtitle can be down‐
1010 loaded
1011 content = None
1013 Content as bytes
1014 encoding = None
1016 Encoding to decode with when accessing text
1017 property id
1019 Unique identifier of the subtitle
1020 property text
1022 Content as string
1023 If encoding is None, the encoding is guessed with
1025 guess_encoding()
1026 is_valid()
1028 Check if a text is a valid SubRip format.
1029 Returns
1031 whether or not the subtitle is valid.
1032 Return type
1034 bool
1035 guess_encoding()
1037 Guess encoding using the language, falling back on
1038 chardet.
1039 Returns
1041 the guessed encoding.
1042 Return type
1044 str
1045 get_matches(video)
1047 Get the matches against the video.
1048 Parameters
1050 video (Video) – the video to get the matches with.
1051 Returns
1053 matches of the subtitle.
1054 Return type
1056 set
1057 subliminal.subtitle.get_subtitle_path(video_path, language=None, exten‐
1059 sion='.srt')
1060 Get the subtitle path using the video_path and language.
1061 Parameters
1063 · video_path (str) – path to the video.
1065 · language (Language) – language of the subtitle to put
1067 in the path.
1068 · extension (str) – extension of the subtitle.
1070 Returns
1072 path of the subtitle.
1073 Return type
1075 str
1076 subliminal.subtitle.guess_matches(video, guess, partial=False)
1078 Get matches between a video and a guess.
1079 If a guess is partial, the absence information won’t be counted
1081 as a match.
1082 Parameters
1084 · video (Video) – the video.
1086 · guess (dict) – the guess.
1088 · partial (bool) – whether or not the guess is partial.
1090 Returns
1092 matches between the video and the guess.
1093 Return type
1095 set
1096 subliminal.subtitle.fix_line_ending(content)
1098 Fix line ending of content by changing it to
1099 param bytes content
1101 content of the subtitle.
1102 return the content with fixed line endings.
1104 rtype bytes
1106 Providers
1108 class subliminal.providers.TimeoutSafeTransport(timeout, *args,
1109 **kwargs)
1110 Timeout support for xmlrpc.client.SafeTransport.
1111 class subliminal.providers.ParserBeautifulSoup(markup, parsers,
1113 **kwargs)
1114 A bs4.BeautifulSoup that picks the first parser available in
1115 parsers.
1116 Parameters
1118 · markup – markup for the bs4.BeautifulSoup.
1120 · parsers (list) – parser names, in order of preference.
1122 class subliminal.providers.Provider
1124 Base class for providers.
1125 If any configuration is possible for the provider, like creden‐
1127 tials, it must take place during instantiation.
1128 Raise ConfigurationError if there is a configuration error
1130 languages = {}
1132 Supported set of Language
1133 video_types = (<class 'subliminal.video.Episode'>, <class 'sub‐
1135 liminal.video.Movie'>)
1136 Supported video types
1137 required_hash = None
1139 Required hash, if any
1140 initialize()
1142 Initialize the provider.
1143 Must be called when starting to work with the provider.
1145 This is the place for network initialization or login
1146 operations.
1147 NOTE:
1149 This is called automatically when entering the with
1150 statement
1151 terminate()
1153 Terminate the provider.
1154 Must be called when done with the provider. This is the
1156 place for network shutdown or logout operations.
1157 NOTE:
1159 This is called automatically when exiting the with
1160 statement
1161 classmethod check(video)
1163 Check if the video can be processed.
1164 The video is considered invalid if not an instance of
1166 video_types or if the required_hash is not present in
1167 hashes attribute of the video.
1168 Parameters
1170 video (Video) – the video to check.
1171 Returns
1173 True if the video is valid, False otherwise.
1174 Return type
1176 bool
1177 query(*args, **kwargs)
1179 Query the provider for subtitles.
1180 Arguments should match as much as possible the actual
1182 parameters for querying the provider
1183 Returns
1185 found subtitles.
1186 Return type
1188 list of Subtitle
1189 Raise ProviderError
1191 list_subtitles(video, languages)
1193 List subtitles for the video with the given languages.
1194 This will call the query() method internally. The parame‐
1196 ters passed to the query() method may vary depending on
1197 the amount of information available in the video.
1198 Parameters
1200 · video (Video) – video to list subtitles for.
1202 · languages (set of Language) – languages to
1204 search for.
1205 Returns
1207 found subtitles.
1208 Return type
1210 list of Subtitle
1211 Raise ProviderError
1213 download_subtitle(subtitle)
1215 Download subtitle’s content.
1216 Parameters
1218 subtitle (Subtitle) – subtitle to download.
1219 Raise ProviderError
1221 Addic7ed
1223 subliminal.providers.addic7ed.series_year_re = re.com‐
1224 pile("^(?P<series>[ \\w\\'.:(),&!?-]+?)(?: \\((?P<year>\\d{4})\\))?$")
1225 Series header parsing regex
1226 class subliminal.providers.addic7ed.Addic7edSubtitle(language, hear‐
1228 ing_impaired, page_link, series, season, episode, title, year, version,
1229 download_link)
1230 Addic7ed Subtitle.
1231 property id
1233 Unique identifier of the subtitle
1234 get_matches(video)
1236 Get the matches against the video.
1237 Parameters
1239 video (Video) – the video to get the matches with.
1240 Returns
1242 matches of the subtitle.
1243 Return type
1245 set
1246 class subliminal.providers.addic7ed.Addic7edProvider(username=None,
1248 password=None)
1249 Addic7ed Provider.
1250 initialize()
1252 Initialize the provider.
1253 Must be called when starting to work with the provider.
1255 This is the place for network initialization or login
1256 operations.
1257 NOTE:
1259 This is called automatically when entering the with
1260 statement
1261 terminate()
1263 Terminate the provider.
1264 Must be called when done with the provider. This is the
1266 place for network shutdown or logout operations.
1267 NOTE:
1269 This is called automatically when exiting the with
1270 statement
1271 _get_show_ids()
1273 Get the dict of show ids per series by querying the
1274 shows.php page.
1275 Returns
1277 show id per series, lower case and without quotes.
1278 Return type
1280 dict
1281 _search_show_id(series, year=None)
1283 Search the show id from the series and year.
1284 Parameters
1286 · series (str) – series of the episode.
1288 · year (int) – year of the series, if any.
1290 Returns
1292 the show id, if found.
1293 Return type
1295 int
1296 get_show_id(series, year=None, country_code=None)
1298 Get the best matching show id for series, year and coun‐
1299 try_code.
1300 First search in the result of _get_show_ids() and fall‐
1302 back on a search with _search_show_id().
1303 Parameters
1305 · series (str) – series of the episode.
1307 · year (int) – year of the series, if any.
1309 · country_code (str) – country code of the series,
1311 if any.
1312 Returns
1314 the show id, if found.
1315 Return type
1317 int
1318 query(series, season, year=None, country=None)
1320 Query the provider for subtitles.
1321 Arguments should match as much as possible the actual
1323 parameters for querying the provider
1324 Returns
1326 found subtitles.
1327 Return type
1329 list of Subtitle
1330 Raise ProviderError
1332 list_subtitles(video, languages)
1334 List subtitles for the video with the given languages.
1335 This will call the query() method internally. The parame‐
1337 ters passed to the query() method may vary depending on
1338 the amount of information available in the video.
1339 Parameters
1341 · video (Video) – video to list subtitles for.
1343 · languages (set of Language) – languages to
1345 search for.
1346 Returns
1348 found subtitles.
1349 Return type
1351 list of Subtitle
1352 Raise ProviderError
1354 download_subtitle(subtitle)
1356 Download subtitle’s content.
1357 Parameters
1359 subtitle (Subtitle) – subtitle to download.
1360 Raise ProviderError
1362 LegendasTv
1364 subliminal.providers.legendastv.type_map = {'C': 'episode', 'M':
1365 'movie', 'S': 'episode'}
1366 Conversion map for types
1367 subliminal.providers.legendastv.season_re = re.compile(' - (?P<sea‐
1369 son>\\d+)(\\xaa|a|st|nd|rd|th) (temporada|season)', re.IGNORECASE)
1370 BR title season parsing regex
1371 subliminal.providers.legendastv.downloads_re = re.compile('(?P<down‐
1373 loads>\\d+) downloads')
1374 Downloads parsing regex
1375 subliminal.providers.legendastv.rating_re = re.compile('nota (?P<rat‐
1377 ing>\\d+)')
1378 Rating parsing regex
1379 subliminal.providers.legendastv.timestamp_re = re.com‐
1381 pile('(?P<day>\\d+)/(?P<month>\\d+)/(?P<year>\\d+) -
1382 (?P<hour>\\d+):(?P<minute>\\d+)')
1383 Timestamp parsing regex
1384 subliminal.providers.legendastv.releases_key = 'sublimi‐
1386 nal.providers.legendastv:releases|{archive_id}'
1387 Cache key for releases
1388 class subliminal.providers.legendastv.LegendasTVArchive(id, name, pack,
1390 featured, link, downloads=0, rating=0, timestamp=None)
1391 LegendasTV Archive.
1392 Parameters
1394 · id (str) – identifier.
1396 · name (str) – name.
1398 · pack (bool) – contains subtitles for multiple episodes.
1400 · pack – featured.
1402 · link (str) – link.
1404 · downloads (int) – download count.
1406 · rating (int) – rating (0-10).
1408 · timestamp (datetime.datetime) – timestamp.
1410 id = None
1412 Identifier
1413 name = None
1415 Name
1416 pack = None
1418 Pack
1419 featured = None
1421 Featured
1422 link = None
1424 Link
1425 downloads = None
1427 Download count
1428 rating = None
1430 Rating (0-10)
1431 timestamp = None
1433 Timestamp
1434 content = None
1436 Compressed content as rarfile.RarFile or zipfile.ZipFile
1437 class subliminal.providers.legendastv.LegendasTVSubtitle(language,
1439 type, title, year, imdb_id, season, archive, name)
1440 LegendasTV Subtitle.
1441 property id
1443 Unique identifier of the subtitle
1444 get_matches(video, hearing_impaired=False)
1446 Get the matches against the video.
1447 Parameters
1449 video (Video) – the video to get the matches with.
1450 Returns
1452 matches of the subtitle.
1453 Return type
1455 set
1456 class subliminal.providers.legendastv.LegendasTVProvider(username=None,
1458 password=None)
1459 LegendasTV Provider.
1460 Parameters
1462 · username (str) – username.
1464 · password (str) – password.
1466 initialize()
1468 Initialize the provider.
1469 Must be called when starting to work with the provider.
1471 This is the place for network initialization or login
1472 operations.
1473 NOTE:
1475 This is called automatically when entering the with
1476 statement
1477 terminate()
1479 Terminate the provider.
1480 Must be called when done with the provider. This is the
1482 place for network shutdown or logout operations.
1483 NOTE:
1485 This is called automatically when exiting the with
1486 statement
1487 search_titles(title)
1489 Search for titles matching the title.
1490 Parameters
1492 title (str) – the title to search for.
1493 Returns
1495 found titles.
1496 Return type
1498 dict
1499 get_archives(title_id, language_code)
1501 Get the archive list from a given title_id and lan‐
1502 guage_code.
1503 Parameters
1505 · title_id (int) – title id.
1507 · language_code (int) – language code.
1509 Returns
1511 the archives.
1512 Return type
1514 list of LegendasTVArchive
1515 download_archive(archive)
1517 Download an archive’s content.
1518 Parameters
1520 archive (LegendasTVArchive) – the archive to down‐
1521 load content of.
1522 query(language, title, season=None, episode=None, year=None)
1524 Query the provider for subtitles.
1525 Arguments should match as much as possible the actual
1527 parameters for querying the provider
1528 Returns
1530 found subtitles.
1531 Return type
1533 list of Subtitle
1534 Raise ProviderError
1536 list_subtitles(video, languages)
1538 List subtitles for the video with the given languages.
1539 This will call the query() method internally. The parame‐
1541 ters passed to the query() method may vary depending on
1542 the amount of information available in the video.
1543 Parameters
1545 · video (Video) – video to list subtitles for.
1547 · languages (set of Language) – languages to
1549 search for.
1550 Returns
1552 found subtitles.
1553 Return type
1555 list of Subtitle
1556 Raise ProviderError
1558 download_subtitle(subtitle)
1560 Download subtitle’s content.
1561 Parameters
1563 subtitle (Subtitle) – subtitle to download.
1564 Raise ProviderError
1566 NapiProjekt
1568 subliminal.providers.napiprojekt.get_subhash(hash)
1569 Get a second hash based on napiprojekt’s hash.
1570 Parameters
1572 hash (str) – napiprojekt’s hash.
1573 Returns
1575 the subhash.
1576 Return type
1578 str
1579 class subliminal.providers.napiprojekt.NapiProjektSubtitle(language,
1581 hash)
1582 NapiProjekt Subtitle.
1583 property id
1585 Unique identifier of the subtitle
1586 get_matches(video)
1588 Get the matches against the video.
1589 Parameters
1591 video (Video) – the video to get the matches with.
1592 Returns
1594 matches of the subtitle.
1595 Return type
1597 set
1598 class subliminal.providers.napiprojekt.NapiProjektProvider
1600 NapiProjekt Provider.
1601 initialize()
1603 Initialize the provider.
1604 Must be called when starting to work with the provider.
1606 This is the place for network initialization or login
1607 operations.
1608 NOTE:
1610 This is called automatically when entering the with
1611 statement
1612 terminate()
1614 Terminate the provider.
1615 Must be called when done with the provider. This is the
1617 place for network shutdown or logout operations.
1618 NOTE:
1620 This is called automatically when exiting the with
1621 statement
1622 query(language, hash)
1624 Query the provider for subtitles.
1625 Arguments should match as much as possible the actual
1627 parameters for querying the provider
1628 Returns
1630 found subtitles.
1631 Return type
1633 list of Subtitle
1634 Raise ProviderError
1636 list_subtitles(video, languages)
1638 List subtitles for the video with the given languages.
1639 This will call the query() method internally. The parame‐
1641 ters passed to the query() method may vary depending on
1642 the amount of information available in the video.
1643 Parameters
1645 · video (Video) – video to list subtitles for.
1647 · languages (set of Language) – languages to
1649 search for.
1650 Returns
1652 found subtitles.
1653 Return type
1655 list of Subtitle
1656 Raise ProviderError
1658 download_subtitle(subtitle)
1660 Download subtitle’s content.
1661 Parameters
1663 subtitle (Subtitle) – subtitle to download.
1664 Raise ProviderError
1666 OpenSubtitles
1668 class subliminal.providers.opensubtitles.OpenSubtitlesSubtitle(lan‐
1669 guage, hearing_impaired, page_link, subtitle_id, matched_by,
1670 movie_kind, hash, movie_name, movie_release_name, movie_year,
1671 movie_imdb_id, series_season, series_episode, filename, encoding)
1672 OpenSubtitles Subtitle.
1673 property id
1675 Unique identifier of the subtitle
1676 get_matches(video)
1678 Get the matches against the video.
1679 Parameters
1681 video (Video) – the video to get the matches with.
1682 Returns
1684 matches of the subtitle.
1685 Return type
1687 set
1688 class subliminal.providers.opensubtitles.OpenSubtitlesProvider(user‐
1690 name=None, password=None)
1691 OpenSubtitles Provider.
1692 Parameters
1694 · username (str) – username.
1696 · password (str) – password.
1698 initialize()
1700 Initialize the provider.
1701 Must be called when starting to work with the provider.
1703 This is the place for network initialization or login
1704 operations.
1705 NOTE:
1707 This is called automatically when entering the with
1708 statement
1709 terminate()
1711 Terminate the provider.
1712 Must be called when done with the provider. This is the
1714 place for network shutdown or logout operations.
1715 NOTE:
1717 This is called automatically when exiting the with
1718 statement
1719 query(languages, hash=None, size=None, imdb_id=None, query=None,
1721 season=None, episode=None, tag=None)
1722 Query the provider for subtitles.
1723 Arguments should match as much as possible the actual
1725 parameters for querying the provider
1726 Returns
1728 found subtitles.
1729 Return type
1731 list of Subtitle
1732 Raise ProviderError
1734 list_subtitles(video, languages)
1736 List subtitles for the video with the given languages.
1737 This will call the query() method internally. The parame‐
1739 ters passed to the query() method may vary depending on
1740 the amount of information available in the video.
1741 Parameters
1743 · video (Video) – video to list subtitles for.
1745 · languages (set of Language) – languages to
1747 search for.
1748 Returns
1750 found subtitles.
1751 Return type
1753 list of Subtitle
1754 Raise ProviderError
1756 download_subtitle(subtitle)
1758 Download subtitle’s content.
1759 Parameters
1761 subtitle (Subtitle) – subtitle to download.
1762 Raise ProviderError
1764 exception subliminal.providers.opensubtitles.OpenSubtitlesError
1766 Base class for non-generic OpenSubtitlesProvider exceptions.
1767 exception subliminal.providers.opensubtitles.Unauthorized
1769 Exception raised when status is ‘401 Unauthorized’.
1770 exception subliminal.providers.opensubtitles.NoSession
1772 Exception raised when status is ‘406 No session’.
1773 exception subliminal.providers.opensubtitles.DownloadLimitReached
1775 Exception raised when status is ‘407 Download limit reached’.
1776 exception subliminal.providers.opensubtitles.InvalidImdbid
1778 Exception raised when status is ‘413 Invalid ImdbID’.
1779 exception subliminal.providers.opensubtitles.UnknownUserAgent
1781 Exception raised when status is ‘414 Unknown User Agent’.
1782 exception subliminal.providers.opensubtitles.DisabledUserAgent
1784 Exception raised when status is ‘415 Disabled user agent’.
1785 exception subliminal.providers.opensubtitles.ServiceUnavailable
1787 Exception raised when status is ‘503 Service Unavailable’.
1788 subliminal.providers.opensubtitles.checked(response)
1790 Check a response status before returning it.
1791 Parameters
1793 response – a response from a XMLRPC call to OpenSubti‐
1794 tles.
1795 Returns
1797 the response.
1798 Raise OpenSubtitlesError
1800 Podnapisi
1802 class subliminal.providers.podnapisi.PodnapisiSubtitle(language, hear‐
1803 ing_impaired, page_link, pid, releases, title, season=None,
1804 episode=None, year=None)
1805 Podnapisi Subtitle.
1806 property id
1808 Unique identifier of the subtitle
1809 get_matches(video)
1811 Get the matches against the video.
1812 Parameters
1814 video (Video) – the video to get the matches with.
1815 Returns
1817 matches of the subtitle.
1818 Return type
1820 set
1821 class subliminal.providers.podnapisi.PodnapisiProvider
1823 Podnapisi Provider.
1824 initialize()
1826 Initialize the provider.
1827 Must be called when starting to work with the provider.
1829 This is the place for network initialization or login
1830 operations.
1831 NOTE:
1833 This is called automatically when entering the with
1834 statement
1835 terminate()
1837 Terminate the provider.
1838 Must be called when done with the provider. This is the
1840 place for network shutdown or logout operations.
1841 NOTE:
1843 This is called automatically when exiting the with
1844 statement
1845 query(language, keyword, season=None, episode=None, year=None)
1847 Query the provider for subtitles.
1848 Arguments should match as much as possible the actual
1850 parameters for querying the provider
1851 Returns
1853 found subtitles.
1854 Return type
1856 list of Subtitle
1857 Raise ProviderError
1859 list_subtitles(video, languages)
1861 List subtitles for the video with the given languages.
1862 This will call the query() method internally. The parame‐
1864 ters passed to the query() method may vary depending on
1865 the amount of information available in the video.
1866 Parameters
1868 · video (Video) – video to list subtitles for.
1870 · languages (set of Language) – languages to
1872 search for.
1873 Returns
1875 found subtitles.
1876 Return type
1878 list of Subtitle
1879 Raise ProviderError
1881 download_subtitle(subtitle)
1883 Download subtitle’s content.
1884 Parameters
1886 subtitle (Subtitle) – subtitle to download.
1887 Raise ProviderError
1889 Shooter
1891 class subliminal.providers.shooter.ShooterSubtitle(language, hash,
1892 download_link)
1893 Shooter Subtitle.
1894 property id
1896 Unique identifier of the subtitle
1897 get_matches(video)
1899 Get the matches against the video.
1900 Parameters
1902 video (Video) – the video to get the matches with.
1903 Returns
1905 matches of the subtitle.
1906 Return type
1908 set
1909 class subliminal.providers.shooter.ShooterProvider
1911 Shooter Provider.
1912 initialize()
1914 Initialize the provider.
1915 Must be called when starting to work with the provider.
1917 This is the place for network initialization or login
1918 operations.
1919 NOTE:
1921 This is called automatically when entering the with
1922 statement
1923 terminate()
1925 Terminate the provider.
1926 Must be called when done with the provider. This is the
1928 place for network shutdown or logout operations.
1929 NOTE:
1931 This is called automatically when exiting the with
1932 statement
1933 query(language, filename, hash=None)
1935 Query the provider for subtitles.
1936 Arguments should match as much as possible the actual
1938 parameters for querying the provider
1939 Returns
1941 found subtitles.
1942 Return type
1944 list of Subtitle
1945 Raise ProviderError
1947 list_subtitles(video, languages)
1949 List subtitles for the video with the given languages.
1950 This will call the query() method internally. The parame‐
1952 ters passed to the query() method may vary depending on
1953 the amount of information available in the video.
1954 Parameters
1956 · video (Video) – video to list subtitles for.
1958 · languages (set of Language) – languages to
1960 search for.
1961 Returns
1963 found subtitles.
1964 Return type
1966 list of Subtitle
1967 Raise ProviderError
1969 download_subtitle(subtitle)
1971 Download subtitle’s content.
1972 Parameters
1974 subtitle (Subtitle) – subtitle to download.
1975 Raise ProviderError
1977 SubsCenter
1979 class subliminal.providers.subscenter.SubsCenterSubtitle(language,
1980 hearing_impaired, page_link, series, season, episode, title, subti‐
1981 tle_id, subtitle_key, downloaded, releases)
1982 SubsCenter Subtitle.
1983 property id
1985 Unique identifier of the subtitle
1986 get_matches(video)
1988 Get the matches against the video.
1989 Parameters
1991 video (Video) – the video to get the matches with.
1992 Returns
1994 matches of the subtitle.
1995 Return type
1997 set
1998 class subliminal.providers.subscenter.SubsCenterProvider(username=None,
2000 password=None)
2001 SubsCenter Provider.
2002 initialize()
2004 Initialize the provider.
2005 Must be called when starting to work with the provider.
2007 This is the place for network initialization or login
2008 operations.
2009 NOTE:
2011 This is called automatically when entering the with
2012 statement
2013 terminate()
2015 Terminate the provider.
2016 Must be called when done with the provider. This is the
2018 place for network shutdown or logout operations.
2019 NOTE:
2021 This is called automatically when exiting the with
2022 statement
2023 _search_url_titles(title)
2025 Search the URL titles by kind for the given title.
2026 Parameters
2028 title (str) – title to search for.
2029 Returns
2031 the URL titles by kind.
2032 Return type
2034 collections.defaultdict
2035 query(title, season=None, episode=None)
2037 Query the provider for subtitles.
2038 Arguments should match as much as possible the actual
2040 parameters for querying the provider
2041 Returns
2043 found subtitles.
2044 Return type
2046 list of Subtitle
2047 Raise ProviderError
2049 list_subtitles(video, languages)
2051 List subtitles for the video with the given languages.
2052 This will call the query() method internally. The parame‐
2054 ters passed to the query() method may vary depending on
2055 the amount of information available in the video.
2056 Parameters
2058 · video (Video) – video to list subtitles for.
2060 · languages (set of Language) – languages to
2062 search for.
2063 Returns
2065 found subtitles.
2066 Return type
2068 list of Subtitle
2069 Raise ProviderError
2071 download_subtitle(subtitle)
2073 Download subtitle’s content.
2074 Parameters
2076 subtitle (Subtitle) – subtitle to download.
2077 Raise ProviderError
2079 TheSubDB
2081 class subliminal.providers.thesubdb.TheSubDBSubtitle(language, hash)
2082 TheSubDB Subtitle.
2083 property id
2085 Unique identifier of the subtitle
2086 get_matches(video)
2088 Get the matches against the video.
2089 Parameters
2091 video (Video) – the video to get the matches with.
2092 Returns
2094 matches of the subtitle.
2095 Return type
2097 set
2098 class subliminal.providers.thesubdb.TheSubDBProvider
2100 TheSubDB Provider.
2101 initialize()
2103 Initialize the provider.
2104 Must be called when starting to work with the provider.
2106 This is the place for network initialization or login
2107 operations.
2108 NOTE:
2110 This is called automatically when entering the with
2111 statement
2112 terminate()
2114 Terminate the provider.
2115 Must be called when done with the provider. This is the
2117 place for network shutdown or logout operations.
2118 NOTE:
2120 This is called automatically when exiting the with
2121 statement
2122 query(hash)
2124 Query the provider for subtitles.
2125 Arguments should match as much as possible the actual
2127 parameters for querying the provider
2128 Returns
2130 found subtitles.
2131 Return type
2133 list of Subtitle
2134 Raise ProviderError
2136 list_subtitles(video, languages)
2138 List subtitles for the video with the given languages.
2139 This will call the query() method internally. The parame‐
2141 ters passed to the query() method may vary depending on
2142 the amount of information available in the video.
2143 Parameters
2145 · video (Video) – video to list subtitles for.
2147 · languages (set of Language) – languages to
2149 search for.
2150 Returns
2152 found subtitles.
2153 Return type
2155 list of Subtitle
2156 Raise ProviderError
2158 download_subtitle(subtitle)
2160 Download subtitle’s content.
2161 Parameters
2163 subtitle (Subtitle) – subtitle to download.
2164 Raise ProviderError
2166 TVsubtitles
2168 class subliminal.providers.tvsubtitles.TVsubtitlesSubtitle(language,
2169 page_link, subtitle_id, series, season, episode, year, rip, release)
2170 TVsubtitles Subtitle.
2171 property id
2173 Unique identifier of the subtitle
2174 get_matches(video)
2176 Get the matches against the video.
2177 Parameters
2179 video (Video) – the video to get the matches with.
2180 Returns
2182 matches of the subtitle.
2183 Return type
2185 set
2186 class subliminal.providers.tvsubtitles.TVsubtitlesProvider
2188 TVsubtitles Provider.
2189 initialize()
2191 Initialize the provider.
2192 Must be called when starting to work with the provider.
2194 This is the place for network initialization or login
2195 operations.
2196 NOTE:
2198 This is called automatically when entering the with
2199 statement
2200 terminate()
2202 Terminate the provider.
2203 Must be called when done with the provider. This is the
2205 place for network shutdown or logout operations.
2206 NOTE:
2208 This is called automatically when exiting the with
2209 statement
2210 search_show_id(series, year=None)
2212 Search the show id from the series and year.
2213 Parameters
2215 · series (str) – series of the episode.
2217 · year (int) – year of the series, if any.
2219 Returns
2221 the show id, if any.
2222 Return type
2224 int
2225 get_episode_ids(show_id, season)
2227 Get episode ids from the show id and the season.
2228 Parameters
2230 · show_id (int) – show id.
2232 · season (int) – season of the episode.
2234 Returns
2236 episode ids per episode number.
2237 Return type
2239 dict
2240 query(series, season, episode, year=None)
2242 Query the provider for subtitles.
2243 Arguments should match as much as possible the actual
2245 parameters for querying the provider
2246 Returns
2248 found subtitles.
2249 Return type
2251 list of Subtitle
2252 Raise ProviderError
2254 list_subtitles(video, languages)
2256 List subtitles for the video with the given languages.
2257 This will call the query() method internally. The parame‐
2259 ters passed to the query() method may vary depending on
2260 the amount of information available in the video.
2261 Parameters
2263 · video (Video) – video to list subtitles for.
2265 · languages (set of Language) – languages to
2267 search for.
2268 Returns
2270 found subtitles.
2271 Return type
2273 list of Subtitle
2274 Raise ProviderError
2276 download_subtitle(subtitle)
2278 Download subtitle’s content.
2279 Parameters
2281 subtitle (Subtitle) – subtitle to download.
2282 Raise ProviderError
2284 Refiners
2286 Refiners enrich a Video object by adding information to it.
2287 A refiner is a simple function:
2289 subliminal.refiners.refine(video, **kwargs)
2291 Parameters
2293 · video (Video) – the video to refine.
2295 · **kwargs – additional parameters for refiners.
2297 Metadata
2299 subliminal.refiners.metadata.refine(video, embedded_subtitles=True,
2300 **kwargs)
2301 Refine a video by searching its metadata.
2302 Several Video attributes can be found:
2304 · resolution
2306 · video_codec
2308 · audio_codec
2310 · subtitle_languages
2312 Parameters
2314 embedded_subtitles (bool) – search for embedded subti‐
2315 tles.
2316 TVDB
2318 subliminal.refiners.tvdb.refine(video, **kwargs)
2319 Refine a video by searching TheTVDB.
2320 NOTE:
2322 This refiner only work for instances of Episode.
2323 Several attributes can be found:
2325 · series
2327 · year
2329 · series_imdb_id
2331 · series_tvdb_id
2333 · title
2335 · imdb_id
2337 · tvdb_id
2339 OMDb
2341 subliminal.refiners.omdb.refine(video, **kwargs)
2342 Refine a video by searching OMDb API.
2343 Several Episode attributes can be found:
2345 · series
2347 · year
2349 · series_imdb_id
2351 Similarly, for a Movie:
2353 · title
2355 · year
2357 · imdb_id
2359 Extensions
2361 class subliminal.extensions.RegistrableExtensionManager(namespace,
2362 internal_extensions, **kwargs)
2363 :class:~stevedore.extensions.ExtensionManager` with support for
2364 registration.
2365 It allows loading of internal extensions without setup and reg‐
2367 istering/unregistering additional extensions.
2368 Loading is done in this order:
2370 · Entry point extensions
2372 · Internal extensions
2374 · Registered extensions
2376 Parameters
2378 · namespace (str) – namespace argument for :class:~steve‐
2380 dore.extensions.ExtensionManager`.
2381 · internal_extensions (list) – internal extensions to use
2383 with entry point syntax.
2384 · **kwargs – additional parameters for the :class:~steve‐
2386 dore.extensions.ExtensionManager` constructor.
2387 registered_extensions = None
2389 Registered extensions with entry point syntax
2390 internal_extensions = None
2392 Internal extensions with entry point syntax
2393 register(entry_point)
2395 Register an extension
2396 Parameters
2398 entry_point (str) – extension to register (entry
2399 point syntax).
2400 Raise ValueError if already registered.
2402 unregister(entry_point)
2404 Unregister a provider
2405 Parameters
2407 entry_point (str) – provider to unregister (entry
2408 point syntax).
2409 subliminal.extensions.provider_manager = <subliminal.extensions.Regis‐
2411 trableExtensionManager object>
2412 Provider manager
2413 subliminal.extensions.refiner_manager = <subliminal.extensions.Regis‐
2415 trableExtensionManager object>
2416 Refiner manager
2417 Score
2419 This module provides the default implementation of the compute_score
2420 parameter in download_best_subtitles() and download_best_subtitles().
2421 NOTE:
2423 To avoid unnecessary dependency on sympy and boost subliminal’s
2424 import time, the resulting scores are hardcoded here and manually
2425 updated when the set of equations change.
2426 Available matches:
2428 · hash
2430 · title
2432 · year
2434 · series
2436 · season
2438 · episode
2440 · release_group
2442 · format
2444 · audio_codec
2446 · resolution
2448 · hearing_impaired
2450 · video_codec
2452 · series_imdb_id
2454 · imdb_id
2456 · tvdb_id
2458 subliminal.score.episode_scores = {'audio_codec': 3, 'episode': 30,
2460 'format': 7, 'hash': 359, 'hearing_impaired': 1, 'release_group': 15,
2461 'resolution': 2, 'season': 30, 'series': 180, 'video_codec': 2, 'year':
2462 90}
2463 Scores for episodes
2464 subliminal.score.movie_scores = {'audio_codec': 3, 'format': 7, 'hash':
2466 119, 'hearing_impaired': 1, 'release_group': 15, 'resolution': 2,
2467 'title': 60, 'video_codec': 2, 'year': 30}
2468 Scores for movies
2469 subliminal.score.equivalent_release_groups = ({'DIMENSION', 'LOL'},
2471 {'FLEET', 'ASAP', 'IMMERSE'})
2472 Equivalent release groups
2473 subliminal.score.get_equivalent_release_groups(release_group)
2475 Get all the equivalents of the given release group.
2476 Parameters
2478 release_group (str) – the release group to get the equiv‐
2479 alents of.
2480 Returns
2482 the equivalent release groups.
2483 Return type
2485 set
2486 subliminal.score.get_scores(video)
2488 Get the scores dict for the given video.
2489 This will return either episode_scores or movie_scores based on
2491 the type of the video.
2492 Parameters
2494 video (Video) – the video to compute the score against.
2495 Returns
2497 the scores dict.
2498 Return type
2500 dict
2501 subliminal.score.compute_score(subtitle, video, hearing_impaired=None)
2503 Compute the score of the subtitle against the video with hear‐
2504 ing_impaired preference.
2505 compute_score() uses the Subtitle.get_matches method and applies
2507 the scores (either from episode_scores or movie_scores) after
2508 some processing.
2509 Parameters
2511 · subtitle (Subtitle) – the subtitle to compute the score
2513 of.
2514 · video (Video) – the video to compute the score against.
2516 · hearing_impaired (bool) – hearing impaired preference.
2518 Returns
2520 score of the subtitle.
2521 Return type
2523 int
2524 Utils
2526 subliminal.utils.hash_opensubtitles(video_path)
2527 Compute a hash using OpenSubtitles’ algorithm.
2528 Parameters
2530 video_path (str) – path of the video.
2531 Returns
2533 the hash.
2534 Return type
2536 str
2537 subliminal.utils.hash_thesubdb(video_path)
2539 Compute a hash using TheSubDB’s algorithm.
2540 Parameters
2542 video_path (str) – path of the video.
2543 Returns
2545 the hash.
2546 Return type
2548 str
2549 subliminal.utils.hash_napiprojekt(video_path)
2551 Compute a hash using NapiProjekt’s algorithm.
2552 Parameters
2554 video_path (str) – path of the video.
2555 Returns
2557 the hash.
2558 Return type
2560 str
2561 subliminal.utils.hash_shooter(video_path)
2563 Compute a hash using Shooter’s algorithm
2564 Parameters
2566 video_path (string) – path of the video
2567 Returns
2569 the hash
2570 Return type
2572 string
2573 subliminal.utils.sanitize(string, ignore_characters=None)
2575 Sanitize a string to strip special characters.
2576 Parameters
2578 · string (str) – the string to sanitize.
2580 · ignore_characters (set) – characters to ignore.
2582 Returns
2584 the sanitized string.
2585 Return type
2587 str
2588 subliminal.utils.sanitize_release_group(string)
2590 Sanitize a release_group string to remove content in square
2591 brackets.
2592 Parameters
2594 string (str) – the release group to sanitize.
2595 Returns
2597 the sanitized release group.
2598 Return type
2600 str
2601 subliminal.utils.timestamp(date)
2603 Get the timestamp of the date, python2/3 compatible
2604 Parameters
2606 date (datetime.datetime) – the utc date.
2607 Returns
2609 the timestamp of the date.
2610 Return type
2612 float
2613 Cache
2615 subliminal.cache.SHOW_EXPIRATION_TIME
2616 Expiration time for show caching
2617 subliminal.cache.EPISODE_EXPIRATION_TIME
2619 Expiration time for episode caching
2620 subliminal.cache.REFINER_EXPIRATION_TIME
2622 Expiration time for scraper searches
2623 subliminal.cache.region
2625 The CacheRegion
2626 Refer to dogpile.cache’s region configuration documentation to see how
2628 to configure the region
2629 CLI
2631 Subliminal uses click to provide a powerful CLI.
2632 class subliminal.cli.MutexLock(filename)
2634 MutexLock is a thread-based rw lock based on dogpile.core.Read‐
2635 WriteMutex.
2636 acquire_read_lock(wait)
2638 Acquire a ‘reader’ lock.
2639 Raises NotImplementedError by default, must be imple‐
2641 mented by subclasses.
2642 acquire_write_lock(wait)
2644 Acquire a ‘write’ lock.
2645 Raises NotImplementedError by default, must be imple‐
2647 mented by subclasses.
2648 release_read_lock()
2650 Release a ‘reader’ lock.
2651 Raises NotImplementedError by default, must be imple‐
2653 mented by subclasses.
2654 release_write_lock()
2656 Release a ‘writer’ lock.
2657 Raises NotImplementedError by default, must be imple‐
2659 mented by subclasses.
2660 class subliminal.cli.Config(path)
2662 A ConfigParser wrapper to store configuration.
2663 Interaction with the configuration is done with the properties.
2665 Parameters
2667 path (str) – path to the configuration file.
2668 path = None
2670 Path to the configuration file
2671 config = None
2673 The underlying configuration object
2674 read() Read the configuration from path
2676 write()
2678 Write the configuration to path
2679 class subliminal.cli.LanguageParamType
2681 ParamType for languages that returns a Language
2682 convert(value, param, ctx)
2684 Converts the value. This is not invoked for values that
2685 are None (the missing value).
2686 class subliminal.cli.AgeParamType
2688 ParamType for age strings that returns a timedelta
2689 An age string is in the form number + identifier with possible
2691 identifiers:
2692 · w for weeks
2694 · d for days
2696 · h for hours
2698 The form can be specified multiple times but only with that
2700 idenfier ordering. For example:
2701 · 1w2d4h for 1 week, 2 days and 4 hours
2703 · 2w for 2 weeks
2705 · 3w6h for 3 weeks and 6 hours
2707 convert(value, param, ctx)
2709 Converts the value. This is not invoked for values that
2710 are None (the missing value).
2711 Exceptions
2713 exception subliminal.exceptions.Error
2714 Base class for exceptions in subliminal.
2715 exception subliminal.exceptions.ProviderError
2717 Exception raised by providers.
2718 exception subliminal.exceptions.ConfigurationError
2720 Exception raised by providers when badly configured.
2721 exception subliminal.exceptions.AuthenticationError
2723 Exception raised by providers when authentication failed.
2724 exception subliminal.exceptions.TooManyRequests
2726 Exception raised by providers when too many requests are made.
2727 exception subliminal.exceptions.DownloadLimitExceeded
2729 Exception raised by providers when download limit is exceeded.
2730
2732 MIT
2733 · genindex
2735 · modindex
2737 · search
2739
2741 Antoine Bertin
2742
2744 2020, Antoine Bertin
27452.0.5 Jan 31, 2020 SUBLIMINAL(1)