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 exists Test whether the video exists
847 age Age of the video
849 classmethod fromguess(name, guess)
851 Create an Episode or a Movie with the given name based on
852 the guess.
853 Parameters
855 · name (str) – name of the video.
857 · guess (dict) – guessed data.
859 Raise ValueError if the type of the guess is invalid
861 classmethod fromname(name)
863 Shortcut for fromguess() with a guess guessed from the
864 name.
865 Parameters
867 name (str) – name of the video.
868 class subliminal.video.Episode(name, series, season, episode,
870 title=None, year=None, original_series=True, tvdb_id=None,
871 series_tvdb_id=None, series_imdb_id=None, **kwargs)
872 Episode Video.
873 Parameters
875 · series (str) – series of the episode.
877 · season (int) – season number of the episode.
879 · episode (int) – episode number of the episode.
881 · title (str) – title of the episode.
883 · year (int) – year of the series.
885 · original_series (bool) – whether the series is the
887 first with this name.
888 · tvdb_id (int) – TVDB id of the episode.
890 · **kwargs – additional parameters for the Video con‐
892 structor.
893 series = None
895 Series of the episode
896 season = None
898 Season number of the episode
899 episode = None
901 Episode number of the episode
902 title = None
904 Title of the episode
905 year = None
907 Year of series
908 original_series = None
910 The series is the first with this name
911 tvdb_id = None
913 TVDB id of the episode
914 series_tvdb_id = None
916 TVDB id of the series
917 series_imdb_id = None
919 IMDb id of the series
920 classmethod fromguess(name, guess)
922 Create an Episode or a Movie with the given name based on
923 the guess.
924 Parameters
926 · name (str) – name of the video.
928 · guess (dict) – guessed data.
930 Raise ValueError if the type of the guess is invalid
932 classmethod fromname(name)
934 Shortcut for fromguess() with a guess guessed from the
935 name.
936 Parameters
938 name (str) – name of the video.
939 class subliminal.video.Movie(name, title, year=None, **kwargs)
941 Movie Video.
942 Parameters
944 · title (str) – title of the movie.
946 · year (int) – year of the movie.
948 · **kwargs – additional parameters for the Video con‐
950 structor.
951 title = None
953 Title of the movie
954 year = None
956 Year of the movie
957 classmethod fromguess(name, guess)
959 Create an Episode or a Movie with the given name based on
960 the guess.
961 Parameters
963 · name (str) – name of the video.
965 · guess (dict) – guessed data.
967 Raise ValueError if the type of the guess is invalid
969 classmethod fromname(name)
971 Shortcut for fromguess() with a guess guessed from the
972 name.
973 Parameters
975 name (str) – name of the video.
976 Subtitle
978 subliminal.subtitle.SUBTITLE_EXTENSIONS
979 Subtitle extensions
980 class subliminal.subtitle.Subtitle(language, hearing_impaired=False,
982 page_link=None, encoding=None)
983 Base class for subtitle.
984 Parameters
986 · language (Language) – language of the subtitle.
988 · hearing_impaired (bool) – whether or not the subtitle
990 is hearing impaired.
991 · page_link (str) – URL of the web page from which the
993 subtitle can be downloaded.
994 · encoding (str) – Text encoding of the subtitle.
996 provider_name = ''
998 Name of the provider that returns that class of subtitle
999 language = None
1001 Language of the subtitle
1002 hearing_impaired = None
1004 Whether or not the subtitle is hearing impaired
1005 page_link = None
1007 URL of the web page from which the subtitle can be down‐
1008 loaded
1009 content = None
1011 Content as bytes
1012 encoding = None
1014 Encoding to decode with when accessing text
1015 id Unique identifier of the subtitle
1017 text Content as string
1019 If encoding is None, the encoding is guessed with
1021 guess_encoding()
1022 is_valid()
1024 Check if a text is a valid SubRip format.
1025 Returns
1027 whether or not the subtitle is valid.
1028 Return type
1030 bool
1031 guess_encoding()
1033 Guess encoding using the language, falling back on
1034 chardet.
1035 Returns
1037 the guessed encoding.
1038 Return type
1040 str
1041 get_matches(video)
1043 Get the matches against the video.
1044 Parameters
1046 video (Video) – the video to get the matches with.
1047 Returns
1049 matches of the subtitle.
1050 Return type
1052 set
1053 subliminal.subtitle.get_subtitle_path(video_path, language=None, exten‐
1055 sion='.srt')
1056 Get the subtitle path using the video_path and language.
1057 Parameters
1059 · video_path (str) – path to the video.
1061 · language (Language) – language of the subtitle to put
1063 in the path.
1064 · extension (str) – extension of the subtitle.
1066 Returns
1068 path of the subtitle.
1069 Return type
1071 str
1072 subliminal.subtitle.guess_matches(video, guess, partial=False)
1074 Get matches between a video and a guess.
1075 If a guess is partial, the absence information won’t be counted
1077 as a match.
1078 Parameters
1080 · video (Video) – the video.
1082 · guess (dict) – the guess.
1084 · partial (bool) – whether or not the guess is partial.
1086 Returns
1088 matches between the video and the guess.
1089 Return type
1091 set
1092 subliminal.subtitle.fix_line_ending(content)
1094 Fix line ending of content by changing it to
1095 param bytes content
1097 content of the subtitle.
1098 return the content with fixed line endings.
1100 rtype bytes
1102 Providers
1104 class subliminal.providers.TimeoutSafeTransport(timeout, *args,
1105 **kwargs)
1106 Timeout support for xmlrpc.client.SafeTransport.
1107 class subliminal.providers.ParserBeautifulSoup(markup, parsers,
1109 **kwargs)
1110 A bs4.BeautifulSoup that picks the first parser available in
1111 parsers.
1112 Parameters
1114 · markup – markup for the bs4.BeautifulSoup.
1116 · parsers (list) – parser names, in order of preference.
1118 class subliminal.providers.Provider
1120 Base class for providers.
1121 If any configuration is possible for the provider, like creden‐
1123 tials, it must take place during instantiation.
1124 Raise ConfigurationError if there is a configuration error
1126 languages = set()
1128 Supported set of Language
1129 video_types = (<class 'subliminal.video.Episode'>, <class 'sub‐
1131 liminal.video.Movie'>)
1132 Supported video types
1133 required_hash = None
1135 Required hash, if any
1136 initialize()
1138 Initialize the provider.
1139 Must be called when starting to work with the provider.
1141 This is the place for network initialization or login
1142 operations.
1143 NOTE:
1145 This is called automatically when entering the with
1146 statement
1147 terminate()
1149 Terminate the provider.
1150 Must be called when done with the provider. This is the
1152 place for network shutdown or logout operations.
1153 NOTE:
1155 This is called automatically when exiting the with
1156 statement
1157 classmethod check(video)
1159 Check if the video can be processed.
1160 The video is considered invalid if not an instance of
1162 video_types or if the required_hash is not present in
1163 hashes attribute of the video.
1164 Parameters
1166 video (Video) – the video to check.
1167 Returns
1169 True if the video is valid, False otherwise.
1170 Return type
1172 bool
1173 query(*args, **kwargs)
1175 Query the provider for subtitles.
1176 Arguments should match as much as possible the actual
1178 parameters for querying the provider
1179 Returns
1181 found subtitles.
1182 Return type
1184 list of Subtitle
1185 Raise ProviderError
1187 list_subtitles(video, languages)
1189 List subtitles for the video with the given languages.
1190 This will call the query() method internally. The parame‐
1192 ters passed to the query() method may vary depending on
1193 the amount of information available in the video.
1194 Parameters
1196 · video (Video) – video to list subtitles for.
1198 · languages (set of Language) – languages to
1200 search for.
1201 Returns
1203 found subtitles.
1204 Return type
1206 list of Subtitle
1207 Raise ProviderError
1209 download_subtitle(subtitle)
1211 Download subtitle’s content.
1212 Parameters
1214 subtitle (Subtitle) – subtitle to download.
1215 Raise ProviderError
1217 Addic7ed
1219 subliminal.providers.addic7ed.series_year_re = re.com‐
1220 pile("^(?P<series>[ \\w\\'.:(),&!?-]+?)(?: \\((?P<year>\\d{4})\\))?$")
1221 Series header parsing regex
1222 class subliminal.providers.addic7ed.Addic7edSubtitle(language, hear‐
1224 ing_impaired, page_link, series, season, episode, title, year, version,
1225 download_link)
1226 Addic7ed Subtitle.
1227 id Unique identifier of the subtitle
1229 get_matches(video)
1231 Get the matches against the video.
1232 Parameters
1234 video (Video) – the video to get the matches with.
1235 Returns
1237 matches of the subtitle.
1238 Return type
1240 set
1241 class subliminal.providers.addic7ed.Addic7edProvider(username=None,
1243 password=None)
1244 Addic7ed Provider.
1245 initialize()
1247 Initialize the provider.
1248 Must be called when starting to work with the provider.
1250 This is the place for network initialization or login
1251 operations.
1252 NOTE:
1254 This is called automatically when entering the with
1255 statement
1256 terminate()
1258 Terminate the provider.
1259 Must be called when done with the provider. This is the
1261 place for network shutdown or logout operations.
1262 NOTE:
1264 This is called automatically when exiting the with
1265 statement
1266 _get_show_ids()
1268 Get the dict of show ids per series by querying the
1269 shows.php page.
1270 Returns
1272 show id per series, lower case and without quotes.
1273 Return type
1275 dict
1276 _search_show_id(series, year=None)
1278 Search the show id from the series and year.
1279 Parameters
1281 · series (str) – series of the episode.
1283 · year (int) – year of the series, if any.
1285 Returns
1287 the show id, if found.
1288 Return type
1290 int
1291 get_show_id(series, year=None, country_code=None)
1293 Get the best matching show id for series, year and coun‐
1294 try_code.
1295 First search in the result of _get_show_ids() and fall‐
1297 back on a search with _search_show_id().
1298 Parameters
1300 · series (str) – series of the episode.
1302 · year (int) – year of the series, if any.
1304 · country_code (str) – country code of the series,
1306 if any.
1307 Returns
1309 the show id, if found.
1310 Return type
1312 int
1313 query(series, season, year=None, country=None)
1315 Query the provider for subtitles.
1316 Arguments should match as much as possible the actual
1318 parameters for querying the provider
1319 Returns
1321 found subtitles.
1322 Return type
1324 list of Subtitle
1325 Raise ProviderError
1327 list_subtitles(video, languages)
1329 List subtitles for the video with the given languages.
1330 This will call the query() method internally. The parame‐
1332 ters passed to the query() method may vary depending on
1333 the amount of information available in the video.
1334 Parameters
1336 · video (Video) – video to list subtitles for.
1338 · languages (set of Language) – languages to
1340 search for.
1341 Returns
1343 found subtitles.
1344 Return type
1346 list of Subtitle
1347 Raise ProviderError
1349 download_subtitle(subtitle)
1351 Download subtitle’s content.
1352 Parameters
1354 subtitle (Subtitle) – subtitle to download.
1355 Raise ProviderError
1357 LegendasTv
1359 subliminal.providers.legendastv.type_map = {'C': 'episode', 'M':
1360 'movie', 'S': 'episode'}
1361 Conversion map for types
1362 subliminal.providers.legendastv.season_re = re.compile(' - (?P<sea‐
1364 son>\\d+)(\\xaa|a|st|nd|rd|th) (temporada|season)', re.IGNORECASE)
1365 BR title season parsing regex
1366 subliminal.providers.legendastv.downloads_re = re.compile('(?P<down‐
1368 loads>\\d+) downloads')
1369 Downloads parsing regex
1370 subliminal.providers.legendastv.rating_re = re.compile('nota (?P<rat‐
1372 ing>\\d+)')
1373 Rating parsing regex
1374 subliminal.providers.legendastv.timestamp_re = re.com‐
1376 pile('(?P<day>\\d+)/(?P<month>\\d+)/(?P<year>\\d+) -
1377 (?P<hour>\\d+):(?P<minute>\\d+)')
1378 Timestamp parsing regex
1379 subliminal.providers.legendastv.releases_key = 'sublimi‐
1381 nal.providers.legendastv:releases|{archive_id}'
1382 Cache key for releases
1383 class subliminal.providers.legendastv.LegendasTVArchive(id, name, pack,
1385 featured, link, downloads=0, rating=0, timestamp=None)
1386 LegendasTV Archive.
1387 Parameters
1389 · id (str) – identifier.
1391 · name (str) – name.
1393 · pack (bool) – contains subtitles for multiple episodes.
1395 · pack – featured.
1397 · link (str) – link.
1399 · downloads (int) – download count.
1401 · rating (int) – rating (0-10).
1403 · timestamp (datetime.datetime) – timestamp.
1405 id = None
1407 Identifier
1408 name = None
1410 Name
1411 pack = None
1413 Pack
1414 featured = None
1416 Featured
1417 link = None
1419 Link
1420 downloads = None
1422 Download count
1423 rating = None
1425 Rating (0-10)
1426 timestamp = None
1428 Timestamp
1429 content = None
1431 Compressed content as rarfile.RarFile or zipfile.ZipFile
1432 class subliminal.providers.legendastv.LegendasTVSubtitle(language,
1434 type, title, year, imdb_id, season, archive, name)
1435 LegendasTV Subtitle.
1436 id Unique identifier of the subtitle
1438 get_matches(video, hearing_impaired=False)
1440 Get the matches against the video.
1441 Parameters
1443 video (Video) – the video to get the matches with.
1444 Returns
1446 matches of the subtitle.
1447 Return type
1449 set
1450 class subliminal.providers.legendastv.LegendasTVProvider(username=None,
1452 password=None)
1453 LegendasTV Provider.
1454 Parameters
1456 · username (str) – username.
1458 · password (str) – password.
1460 initialize()
1462 Initialize the provider.
1463 Must be called when starting to work with the provider.
1465 This is the place for network initialization or login
1466 operations.
1467 NOTE:
1469 This is called automatically when entering the with
1470 statement
1471 terminate()
1473 Terminate the provider.
1474 Must be called when done with the provider. This is the
1476 place for network shutdown or logout operations.
1477 NOTE:
1479 This is called automatically when exiting the with
1480 statement
1481 search_titles(title)
1483 Search for titles matching the title.
1484 Parameters
1486 title (str) – the title to search for.
1487 Returns
1489 found titles.
1490 Return type
1492 dict
1493 get_archives(title_id, language_code)
1495 Get the archive list from a given title_id and lan‐
1496 guage_code.
1497 Parameters
1499 · title_id (int) – title id.
1501 · language_code (int) – language code.
1503 Returns
1505 the archives.
1506 Return type
1508 list of LegendasTVArchive
1509 download_archive(archive)
1511 Download an archive’s content.
1512 Parameters
1514 archive (LegendasTVArchive) – the archive to down‐
1515 load content of.
1516 query(language, title, season=None, episode=None, year=None)
1518 Query the provider for subtitles.
1519 Arguments should match as much as possible the actual
1521 parameters for querying the provider
1522 Returns
1524 found subtitles.
1525 Return type
1527 list of Subtitle
1528 Raise ProviderError
1530 list_subtitles(video, languages)
1532 List subtitles for the video with the given languages.
1533 This will call the query() method internally. The parame‐
1535 ters passed to the query() method may vary depending on
1536 the amount of information available in the video.
1537 Parameters
1539 · video (Video) – video to list subtitles for.
1541 · languages (set of Language) – languages to
1543 search for.
1544 Returns
1546 found subtitles.
1547 Return type
1549 list of Subtitle
1550 Raise ProviderError
1552 download_subtitle(subtitle)
1554 Download subtitle’s content.
1555 Parameters
1557 subtitle (Subtitle) – subtitle to download.
1558 Raise ProviderError
1560 NapiProjekt
1562 subliminal.providers.napiprojekt.get_subhash(hash)
1563 Get a second hash based on napiprojekt’s hash.
1564 Parameters
1566 hash (str) – napiprojekt’s hash.
1567 Returns
1569 the subhash.
1570 Return type
1572 str
1573 class subliminal.providers.napiprojekt.NapiProjektSubtitle(language,
1575 hash)
1576 NapiProjekt Subtitle.
1577 id Unique identifier of the subtitle
1579 get_matches(video)
1581 Get the matches against the video.
1582 Parameters
1584 video (Video) – the video to get the matches with.
1585 Returns
1587 matches of the subtitle.
1588 Return type
1590 set
1591 class subliminal.providers.napiprojekt.NapiProjektProvider
1593 NapiProjekt Provider.
1594 initialize()
1596 Initialize the provider.
1597 Must be called when starting to work with the provider.
1599 This is the place for network initialization or login
1600 operations.
1601 NOTE:
1603 This is called automatically when entering the with
1604 statement
1605 terminate()
1607 Terminate the provider.
1608 Must be called when done with the provider. This is the
1610 place for network shutdown or logout operations.
1611 NOTE:
1613 This is called automatically when exiting the with
1614 statement
1615 query(language, hash)
1617 Query the provider for subtitles.
1618 Arguments should match as much as possible the actual
1620 parameters for querying the provider
1621 Returns
1623 found subtitles.
1624 Return type
1626 list of Subtitle
1627 Raise ProviderError
1629 list_subtitles(video, languages)
1631 List subtitles for the video with the given languages.
1632 This will call the query() method internally. The parame‐
1634 ters passed to the query() method may vary depending on
1635 the amount of information available in the video.
1636 Parameters
1638 · video (Video) – video to list subtitles for.
1640 · languages (set of Language) – languages to
1642 search for.
1643 Returns
1645 found subtitles.
1646 Return type
1648 list of Subtitle
1649 Raise ProviderError
1651 download_subtitle(subtitle)
1653 Download subtitle’s content.
1654 Parameters
1656 subtitle (Subtitle) – subtitle to download.
1657 Raise ProviderError
1659 OpenSubtitles
1661 class subliminal.providers.opensubtitles.OpenSubtitlesSubtitle(lan‐
1662 guage, hearing_impaired, page_link, subtitle_id, matched_by,
1663 movie_kind, hash, movie_name, movie_release_name, movie_year,
1664 movie_imdb_id, series_season, series_episode, filename, encoding)
1665 OpenSubtitles Subtitle.
1666 id Unique identifier of the subtitle
1668 get_matches(video)
1670 Get the matches against the video.
1671 Parameters
1673 video (Video) – the video to get the matches with.
1674 Returns
1676 matches of the subtitle.
1677 Return type
1679 set
1680 class subliminal.providers.opensubtitles.OpenSubtitlesProvider(user‐
1682 name=None, password=None)
1683 OpenSubtitles Provider.
1684 Parameters
1686 · username (str) – username.
1688 · password (str) – password.
1690 initialize()
1692 Initialize the provider.
1693 Must be called when starting to work with the provider.
1695 This is the place for network initialization or login
1696 operations.
1697 NOTE:
1699 This is called automatically when entering the with
1700 statement
1701 terminate()
1703 Terminate the provider.
1704 Must be called when done with the provider. This is the
1706 place for network shutdown or logout operations.
1707 NOTE:
1709 This is called automatically when exiting the with
1710 statement
1711 query(languages, hash=None, size=None, imdb_id=None, query=None,
1713 season=None, episode=None, tag=None)
1714 Query the provider for subtitles.
1715 Arguments should match as much as possible the actual
1717 parameters for querying the provider
1718 Returns
1720 found subtitles.
1721 Return type
1723 list of Subtitle
1724 Raise ProviderError
1726 list_subtitles(video, languages)
1728 List subtitles for the video with the given languages.
1729 This will call the query() method internally. The parame‐
1731 ters passed to the query() method may vary depending on
1732 the amount of information available in the video.
1733 Parameters
1735 · video (Video) – video to list subtitles for.
1737 · languages (set of Language) – languages to
1739 search for.
1740 Returns
1742 found subtitles.
1743 Return type
1745 list of Subtitle
1746 Raise ProviderError
1748 download_subtitle(subtitle)
1750 Download subtitle’s content.
1751 Parameters
1753 subtitle (Subtitle) – subtitle to download.
1754 Raise ProviderError
1756 exception subliminal.providers.opensubtitles.OpenSubtitlesError
1758 Base class for non-generic OpenSubtitlesProvider exceptions.
1759 exception subliminal.providers.opensubtitles.Unauthorized
1761 Exception raised when status is ‘401 Unauthorized’.
1762 exception subliminal.providers.opensubtitles.NoSession
1764 Exception raised when status is ‘406 No session’.
1765 exception subliminal.providers.opensubtitles.DownloadLimitReached
1767 Exception raised when status is ‘407 Download limit reached’.
1768 exception subliminal.providers.opensubtitles.InvalidImdbid
1770 Exception raised when status is ‘413 Invalid ImdbID’.
1771 exception subliminal.providers.opensubtitles.UnknownUserAgent
1773 Exception raised when status is ‘414 Unknown User Agent’.
1774 exception subliminal.providers.opensubtitles.DisabledUserAgent
1776 Exception raised when status is ‘415 Disabled user agent’.
1777 exception subliminal.providers.opensubtitles.ServiceUnavailable
1779 Exception raised when status is ‘503 Service Unavailable’.
1780 subliminal.providers.opensubtitles.checked(response)
1782 Check a response status before returning it.
1783 Parameters
1785 response – a response from a XMLRPC call to OpenSubti‐
1786 tles.
1787 Returns
1789 the response.
1790 Raise OpenSubtitlesError
1792 Podnapisi
1794 class subliminal.providers.podnapisi.PodnapisiSubtitle(language, hear‐
1795 ing_impaired, page_link, pid, releases, title, season=None,
1796 episode=None, year=None)
1797 Podnapisi Subtitle.
1798 id Unique identifier of the subtitle
1800 get_matches(video)
1802 Get the matches against the video.
1803 Parameters
1805 video (Video) – the video to get the matches with.
1806 Returns
1808 matches of the subtitle.
1809 Return type
1811 set
1812 class subliminal.providers.podnapisi.PodnapisiProvider
1814 Podnapisi Provider.
1815 initialize()
1817 Initialize the provider.
1818 Must be called when starting to work with the provider.
1820 This is the place for network initialization or login
1821 operations.
1822 NOTE:
1824 This is called automatically when entering the with
1825 statement
1826 terminate()
1828 Terminate the provider.
1829 Must be called when done with the provider. This is the
1831 place for network shutdown or logout operations.
1832 NOTE:
1834 This is called automatically when exiting the with
1835 statement
1836 query(language, keyword, season=None, episode=None, year=None)
1838 Query the provider for subtitles.
1839 Arguments should match as much as possible the actual
1841 parameters for querying the provider
1842 Returns
1844 found subtitles.
1845 Return type
1847 list of Subtitle
1848 Raise ProviderError
1850 list_subtitles(video, languages)
1852 List subtitles for the video with the given languages.
1853 This will call the query() method internally. The parame‐
1855 ters passed to the query() method may vary depending on
1856 the amount of information available in the video.
1857 Parameters
1859 · video (Video) – video to list subtitles for.
1861 · languages (set of Language) – languages to
1863 search for.
1864 Returns
1866 found subtitles.
1867 Return type
1869 list of Subtitle
1870 Raise ProviderError
1872 download_subtitle(subtitle)
1874 Download subtitle’s content.
1875 Parameters
1877 subtitle (Subtitle) – subtitle to download.
1878 Raise ProviderError
1880 Shooter
1882 class subliminal.providers.shooter.ShooterSubtitle(language, hash,
1883 download_link)
1884 Shooter Subtitle.
1885 id Unique identifier of the subtitle
1887 get_matches(video)
1889 Get the matches against the video.
1890 Parameters
1892 video (Video) – the video to get the matches with.
1893 Returns
1895 matches of the subtitle.
1896 Return type
1898 set
1899 class subliminal.providers.shooter.ShooterProvider
1901 Shooter Provider.
1902 initialize()
1904 Initialize the provider.
1905 Must be called when starting to work with the provider.
1907 This is the place for network initialization or login
1908 operations.
1909 NOTE:
1911 This is called automatically when entering the with
1912 statement
1913 terminate()
1915 Terminate the provider.
1916 Must be called when done with the provider. This is the
1918 place for network shutdown or logout operations.
1919 NOTE:
1921 This is called automatically when exiting the with
1922 statement
1923 query(language, filename, hash=None)
1925 Query the provider for subtitles.
1926 Arguments should match as much as possible the actual
1928 parameters for querying the provider
1929 Returns
1931 found subtitles.
1932 Return type
1934 list of Subtitle
1935 Raise ProviderError
1937 list_subtitles(video, languages)
1939 List subtitles for the video with the given languages.
1940 This will call the query() method internally. The parame‐
1942 ters passed to the query() method may vary depending on
1943 the amount of information available in the video.
1944 Parameters
1946 · video (Video) – video to list subtitles for.
1948 · languages (set of Language) – languages to
1950 search for.
1951 Returns
1953 found subtitles.
1954 Return type
1956 list of Subtitle
1957 Raise ProviderError
1959 download_subtitle(subtitle)
1961 Download subtitle’s content.
1962 Parameters
1964 subtitle (Subtitle) – subtitle to download.
1965 Raise ProviderError
1967 SubsCenter
1969 class subliminal.providers.subscenter.SubsCenterSubtitle(language,
1970 hearing_impaired, page_link, series, season, episode, title, subti‐
1971 tle_id, subtitle_key, downloaded, releases)
1972 SubsCenter Subtitle.
1973 id Unique identifier of the subtitle
1975 get_matches(video)
1977 Get the matches against the video.
1978 Parameters
1980 video (Video) – the video to get the matches with.
1981 Returns
1983 matches of the subtitle.
1984 Return type
1986 set
1987 class subliminal.providers.subscenter.SubsCenterProvider(username=None,
1989 password=None)
1990 SubsCenter Provider.
1991 initialize()
1993 Initialize the provider.
1994 Must be called when starting to work with the provider.
1996 This is the place for network initialization or login
1997 operations.
1998 NOTE:
2000 This is called automatically when entering the with
2001 statement
2002 terminate()
2004 Terminate the provider.
2005 Must be called when done with the provider. This is the
2007 place for network shutdown or logout operations.
2008 NOTE:
2010 This is called automatically when exiting the with
2011 statement
2012 _search_url_titles(title)
2014 Search the URL titles by kind for the given title.
2015 Parameters
2017 title (str) – title to search for.
2018 Returns
2020 the URL titles by kind.
2021 Return type
2023 collections.defaultdict
2024 query(title, season=None, episode=None)
2026 Query the provider for subtitles.
2027 Arguments should match as much as possible the actual
2029 parameters for querying the provider
2030 Returns
2032 found subtitles.
2033 Return type
2035 list of Subtitle
2036 Raise ProviderError
2038 list_subtitles(video, languages)
2040 List subtitles for the video with the given languages.
2041 This will call the query() method internally. The parame‐
2043 ters passed to the query() method may vary depending on
2044 the amount of information available in the video.
2045 Parameters
2047 · video (Video) – video to list subtitles for.
2049 · languages (set of Language) – languages to
2051 search for.
2052 Returns
2054 found subtitles.
2055 Return type
2057 list of Subtitle
2058 Raise ProviderError
2060 download_subtitle(subtitle)
2062 Download subtitle’s content.
2063 Parameters
2065 subtitle (Subtitle) – subtitle to download.
2066 Raise ProviderError
2068 TheSubDB
2070 class subliminal.providers.thesubdb.TheSubDBSubtitle(language, hash)
2071 TheSubDB Subtitle.
2072 id Unique identifier of the subtitle
2074 get_matches(video)
2076 Get the matches against the video.
2077 Parameters
2079 video (Video) – the video to get the matches with.
2080 Returns
2082 matches of the subtitle.
2083 Return type
2085 set
2086 class subliminal.providers.thesubdb.TheSubDBProvider
2088 TheSubDB Provider.
2089 initialize()
2091 Initialize the provider.
2092 Must be called when starting to work with the provider.
2094 This is the place for network initialization or login
2095 operations.
2096 NOTE:
2098 This is called automatically when entering the with
2099 statement
2100 terminate()
2102 Terminate the provider.
2103 Must be called when done with the provider. This is the
2105 place for network shutdown or logout operations.
2106 NOTE:
2108 This is called automatically when exiting the with
2109 statement
2110 query(hash)
2112 Query the provider for subtitles.
2113 Arguments should match as much as possible the actual
2115 parameters for querying the provider
2116 Returns
2118 found subtitles.
2119 Return type
2121 list of Subtitle
2122 Raise ProviderError
2124 list_subtitles(video, languages)
2126 List subtitles for the video with the given languages.
2127 This will call the query() method internally. The parame‐
2129 ters passed to the query() method may vary depending on
2130 the amount of information available in the video.
2131 Parameters
2133 · video (Video) – video to list subtitles for.
2135 · languages (set of Language) – languages to
2137 search for.
2138 Returns
2140 found subtitles.
2141 Return type
2143 list of Subtitle
2144 Raise ProviderError
2146 download_subtitle(subtitle)
2148 Download subtitle’s content.
2149 Parameters
2151 subtitle (Subtitle) – subtitle to download.
2152 Raise ProviderError
2154 TVsubtitles
2156 class subliminal.providers.tvsubtitles.TVsubtitlesSubtitle(language,
2157 page_link, subtitle_id, series, season, episode, year, rip, release)
2158 TVsubtitles Subtitle.
2159 id Unique identifier of the subtitle
2161 get_matches(video)
2163 Get the matches against the video.
2164 Parameters
2166 video (Video) – the video to get the matches with.
2167 Returns
2169 matches of the subtitle.
2170 Return type
2172 set
2173 class subliminal.providers.tvsubtitles.TVsubtitlesProvider
2175 TVsubtitles Provider.
2176 initialize()
2178 Initialize the provider.
2179 Must be called when starting to work with the provider.
2181 This is the place for network initialization or login
2182 operations.
2183 NOTE:
2185 This is called automatically when entering the with
2186 statement
2187 terminate()
2189 Terminate the provider.
2190 Must be called when done with the provider. This is the
2192 place for network shutdown or logout operations.
2193 NOTE:
2195 This is called automatically when exiting the with
2196 statement
2197 search_show_id(series, year=None)
2199 Search the show id from the series and year.
2200 Parameters
2202 · series (str) – series of the episode.
2204 · year (int) – year of the series, if any.
2206 Returns
2208 the show id, if any.
2209 Return type
2211 int
2212 get_episode_ids(show_id, season)
2214 Get episode ids from the show id and the season.
2215 Parameters
2217 · show_id (int) – show id.
2219 · season (int) – season of the episode.
2221 Returns
2223 episode ids per episode number.
2224 Return type
2226 dict
2227 query(series, season, episode, year=None)
2229 Query the provider for subtitles.
2230 Arguments should match as much as possible the actual
2232 parameters for querying the provider
2233 Returns
2235 found subtitles.
2236 Return type
2238 list of Subtitle
2239 Raise ProviderError
2241 list_subtitles(video, languages)
2243 List subtitles for the video with the given languages.
2244 This will call the query() method internally. The parame‐
2246 ters passed to the query() method may vary depending on
2247 the amount of information available in the video.
2248 Parameters
2250 · video (Video) – video to list subtitles for.
2252 · languages (set of Language) – languages to
2254 search for.
2255 Returns
2257 found subtitles.
2258 Return type
2260 list of Subtitle
2261 Raise ProviderError
2263 download_subtitle(subtitle)
2265 Download subtitle’s content.
2266 Parameters
2268 subtitle (Subtitle) – subtitle to download.
2269 Raise ProviderError
2271 Refiners
2273 Refiners enrich a Video object by adding information to it.
2274 A refiner is a simple function:
2276 subliminal.refiners.refine(video, **kwargs)
2278 Parameters
2280 · video (Video) – the video to refine.
2282 · **kwargs – additional parameters for refiners.
2284 Metadata
2286 subliminal.refiners.metadata.refine(video, embedded_subtitles=True,
2287 **kwargs)
2288 Refine a video by searching its metadata.
2289 Several Video attributes can be found:
2291 · resolution
2293 · video_codec
2295 · audio_codec
2297 · subtitle_languages
2299 Parameters
2301 embedded_subtitles (bool) – search for embedded subti‐
2302 tles.
2303 TVDB
2305 subliminal.refiners.tvdb.refine(video, **kwargs)
2306 Refine a video by searching TheTVDB.
2307 NOTE:
2309 This refiner only work for instances of Episode.
2310 Several attributes can be found:
2312 · series
2314 · year
2316 · series_imdb_id
2318 · series_tvdb_id
2320 · title
2322 · imdb_id
2324 · tvdb_id
2326 OMDb
2328 subliminal.refiners.omdb.refine(video, **kwargs)
2329 Refine a video by searching OMDb API.
2330 Several Episode attributes can be found:
2332 · series
2334 · year
2336 · series_imdb_id
2338 Similarly, for a Movie:
2340 · title
2342 · year
2344 · imdb_id
2346 Extensions
2348 class subliminal.extensions.RegistrableExtensionManager(namespace,
2349 internal_extensions, **kwargs)
2350 :class:~stevedore.extensions.ExtensionManager` with support for
2351 registration.
2352 It allows loading of internal extensions without setup and reg‐
2354 istering/unregistering additional extensions.
2355 Loading is done in this order:
2357 · Entry point extensions
2359 · Internal extensions
2361 · Registered extensions
2363 Parameters
2365 · namespace (str) – namespace argument for :class:~steve‐
2367 dore.extensions.ExtensionManager`.
2368 · internal_extensions (list) – internal extensions to use
2370 with entry point syntax.
2371 · **kwargs – additional parameters for the :class:~steve‐
2373 dore.extensions.ExtensionManager` constructor.
2374 registered_extensions = None
2376 Registered extensions with entry point syntax
2377 internal_extensions = None
2379 Internal extensions with entry point syntax
2380 register(entry_point)
2382 Register an extension
2383 Parameters
2385 entry_point (str) – extension to register (entry
2386 point syntax).
2387 Raise ValueError if already registered.
2389 unregister(entry_point)
2391 Unregister a provider
2392 Parameters
2394 entry_point (str) – provider to unregister (entry
2395 point syntax).
2396 subliminal.extensions.provider_manager = <subliminal.extensions.Regis‐
2398 trableExtensionManager object>
2399 Provider manager
2400 subliminal.extensions.refiner_manager = <subliminal.extensions.Regis‐
2402 trableExtensionManager object>
2403 Refiner manager
2404 Score
2406 This module provides the default implementation of the compute_score
2407 parameter in download_best_subtitles() and download_best_subtitles().
2408 NOTE:
2410 To avoid unnecessary dependency on sympy and boost subliminal’s
2411 import time, the resulting scores are hardcoded here and manually
2412 updated when the set of equations change.
2413 Available matches:
2415 · hash
2417 · title
2419 · year
2421 · series
2423 · season
2425 · episode
2427 · release_group
2429 · format
2431 · audio_codec
2433 · resolution
2435 · hearing_impaired
2437 · video_codec
2439 · series_imdb_id
2441 · imdb_id
2443 · tvdb_id
2445 subliminal.score.episode_scores = {'audio_codec': 3, 'episode': 30,
2447 'format': 7, 'hash': 359, 'hearing_impaired': 1, 'release_group': 15,
2448 'resolution': 2, 'season': 30, 'series': 180, 'video_codec': 2, 'year':
2449 90}
2450 Scores for episodes
2451 subliminal.score.movie_scores = {'audio_codec': 3, 'format': 7, 'hash':
2453 119, 'hearing_impaired': 1, 'release_group': 15, 'resolution': 2,
2454 'title': 60, 'video_codec': 2, 'year': 30}
2455 Scores for movies
2456 subliminal.score.equivalent_release_groups = ({'LOL', 'DIMENSION'},
2458 {'IMMERSE', 'FLEET', 'ASAP'})
2459 Equivalent release groups
2460 subliminal.score.get_equivalent_release_groups(release_group)
2462 Get all the equivalents of the given release group.
2463 Parameters
2465 release_group (str) – the release group to get the equiv‐
2466 alents of.
2467 Returns
2469 the equivalent release groups.
2470 Return type
2472 set
2473 subliminal.score.get_scores(video)
2475 Get the scores dict for the given video.
2476 This will return either episode_scores or movie_scores based on
2478 the type of the video.
2479 Parameters
2481 video (Video) – the video to compute the score against.
2482 Returns
2484 the scores dict.
2485 Return type
2487 dict
2488 subliminal.score.compute_score(subtitle, video, hearing_impaired=None)
2490 Compute the score of the subtitle against the video with hear‐
2491 ing_impaired preference.
2492 compute_score() uses the Subtitle.get_matches method and applies
2494 the scores (either from episode_scores or movie_scores) after
2495 some processing.
2496 Parameters
2498 · subtitle (Subtitle) – the subtitle to compute the score
2500 of.
2501 · video (Video) – the video to compute the score against.
2503 · hearing_impaired (bool) – hearing impaired preference.
2505 Returns
2507 score of the subtitle.
2508 Return type
2510 int
2511 Utils
2513 subliminal.utils.hash_opensubtitles(video_path)
2514 Compute a hash using OpenSubtitles’ algorithm.
2515 Parameters
2517 video_path (str) – path of the video.
2518 Returns
2520 the hash.
2521 Return type
2523 str
2524 subliminal.utils.hash_thesubdb(video_path)
2526 Compute a hash using TheSubDB’s algorithm.
2527 Parameters
2529 video_path (str) – path of the video.
2530 Returns
2532 the hash.
2533 Return type
2535 str
2536 subliminal.utils.hash_napiprojekt(video_path)
2538 Compute a hash using NapiProjekt’s algorithm.
2539 Parameters
2541 video_path (str) – path of the video.
2542 Returns
2544 the hash.
2545 Return type
2547 str
2548 subliminal.utils.hash_shooter(video_path)
2550 Compute a hash using Shooter’s algorithm
2551 Parameters
2553 video_path (string) – path of the video
2554 Returns
2556 the hash
2557 Return type
2559 string
2560 subliminal.utils.sanitize(string, ignore_characters=None)
2562 Sanitize a string to strip special characters.
2563 Parameters
2565 · string (str) – the string to sanitize.
2567 · ignore_characters (set) – characters to ignore.
2569 Returns
2571 the sanitized string.
2572 Return type
2574 str
2575 subliminal.utils.sanitize_release_group(string)
2577 Sanitize a release_group string to remove content in square
2578 brackets.
2579 Parameters
2581 string (str) – the release group to sanitize.
2582 Returns
2584 the sanitized release group.
2585 Return type
2587 str
2588 subliminal.utils.timestamp(date)
2590 Get the timestamp of the date, python2/3 compatible
2591 Parameters
2593 date (datetime.datetime) – the utc date.
2594 Returns
2596 the timestamp of the date.
2597 Return type
2599 float
2600 Cache
2602 subliminal.cache.SHOW_EXPIRATION_TIME
2603 Expiration time for show caching
2604 subliminal.cache.EPISODE_EXPIRATION_TIME
2606 Expiration time for episode caching
2607 subliminal.cache.REFINER_EXPIRATION_TIME
2609 Expiration time for scraper searches
2610 subliminal.cache.region
2612 The CacheRegion
2613 Refer to dogpile.cache’s region configuration documentation to see how
2615 to configure the region
2616 CLI
2618 Subliminal uses click to provide a powerful CLI.
2619 class subliminal.cli.MutexLock(filename)
2621 MutexLock is a thread-based rw lock based on dogpile.core.Read‐
2622 WriteMutex.
2623 acquire_read_lock(wait)
2625 Acquire a ‘reader’ lock.
2626 Raises NotImplementedError by default, must be imple‐
2628 mented by subclasses.
2629 acquire_write_lock(wait)
2631 Acquire a ‘write’ lock.
2632 Raises NotImplementedError by default, must be imple‐
2634 mented by subclasses.
2635 release_read_lock()
2637 Release a ‘reader’ lock.
2638 Raises NotImplementedError by default, must be imple‐
2640 mented by subclasses.
2641 release_write_lock()
2643 Release a ‘writer’ lock.
2644 Raises NotImplementedError by default, must be imple‐
2646 mented by subclasses.
2647 class subliminal.cli.Config(path)
2649 A ConfigParser wrapper to store configuration.
2650 Interaction with the configuration is done with the properties.
2652 Parameters
2654 path (str) – path to the configuration file.
2655 path = None
2657 Path to the configuration file
2658 config = None
2660 The underlying configuration object
2661 read() Read the configuration from path
2663 write()
2665 Write the configuration to path
2666 class subliminal.cli.LanguageParamType
2668 ParamType for languages that returns a Language
2669 convert(value, param, ctx)
2671 Converts the value. This is not invoked for values that
2672 are None (the missing value).
2673 class subliminal.cli.AgeParamType
2675 ParamType for age strings that returns a timedelta
2676 An age string is in the form number + identifier with possible
2678 identifiers:
2679 · w for weeks
2681 · d for days
2683 · h for hours
2685 The form can be specified multiple times but only with that
2687 idenfier ordering. For example:
2688 · 1w2d4h for 1 week, 2 days and 4 hours
2690 · 2w for 2 weeks
2692 · 3w6h for 3 weeks and 6 hours
2694 convert(value, param, ctx)
2696 Converts the value. This is not invoked for values that
2697 are None (the missing value).
2698 Exceptions
2700 exception subliminal.exceptions.Error
2701 Base class for exceptions in subliminal.
2702 exception subliminal.exceptions.ProviderError
2704 Exception raised by providers.
2705 exception subliminal.exceptions.ConfigurationError
2707 Exception raised by providers when badly configured.
2708 exception subliminal.exceptions.AuthenticationError
2710 Exception raised by providers when authentication failed.
2711 exception subliminal.exceptions.TooManyRequests
2713 Exception raised by providers when too many requests are made.
2714 exception subliminal.exceptions.DownloadLimitExceeded
2716 Exception raised by providers when download limit is exceeded.
2717
2719 MIT
2720 · genindex
2722 · modindex
2724 · search
2726
2728 Antoine Bertin
2729
2731 2016, Antoine Bertin
27322.0.5 Feb 02, 2019 SUBLIMINAL(1)