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 Traceback (most recent call last):
228 File "/builddir/build/BUILDROOT/python-subliminal-2.0.5-8.fc29.noarch/usr/bin/subliminal", line 6, in <module>
229 from pkg_resources import load_entry_point
230 File "/usr/lib/python3.7/site-packages/pkg_resources/__init__.py", line 3112, in <module>
231 @_call_aside
232 File "/usr/lib/python3.7/site-packages/pkg_resources/__init__.py", line 3096, in _call_aside
233 f(*args, **kwargs)
234 File "/usr/lib/python3.7/site-packages/pkg_resources/__init__.py", line 3125, in _initialize_master_working_set
235 working_set = WorkingSet._build_master()
236 File "/usr/lib/python3.7/site-packages/pkg_resources/__init__.py", line 578, in _build_master
237 ws.require(__requires__)
238 File "/usr/lib/python3.7/site-packages/pkg_resources/__init__.py", line 895, in require
239 needed = self.resolve(parse_requirements(requirements))
240 File "/usr/lib/python3.7/site-packages/pkg_resources/__init__.py", line 781, in resolve
241 raise DistributionNotFound(req, requirers)
242 pkg_resources.DistributionNotFound: The 'pytz>=2012c' distribution was not found and is required by subliminal
243 subliminal download
245 Traceback (most recent call last):
246 File "/builddir/build/BUILDROOT/python-subliminal-2.0.5-8.fc29.noarch/usr/bin/subliminal", line 6, in <module>
247 from pkg_resources import load_entry_point
248 File "/usr/lib/python3.7/site-packages/pkg_resources/__init__.py", line 3112, in <module>
249 @_call_aside
250 File "/usr/lib/python3.7/site-packages/pkg_resources/__init__.py", line 3096, in _call_aside
251 f(*args, **kwargs)
252 File "/usr/lib/python3.7/site-packages/pkg_resources/__init__.py", line 3125, in _initialize_master_working_set
253 working_set = WorkingSet._build_master()
254 File "/usr/lib/python3.7/site-packages/pkg_resources/__init__.py", line 578, in _build_master
255 ws.require(__requires__)
256 File "/usr/lib/python3.7/site-packages/pkg_resources/__init__.py", line 895, in require
257 needed = self.resolve(parse_requirements(requirements))
258 File "/usr/lib/python3.7/site-packages/pkg_resources/__init__.py", line 781, in resolve
259 raise DistributionNotFound(req, requirers)
260 pkg_resources.DistributionNotFound: The 'pytz>=2012c' distribution was not found and is required by subliminal
261 subliminal cache
263 Traceback (most recent call last):
264 File "/builddir/build/BUILDROOT/python-subliminal-2.0.5-8.fc29.noarch/usr/bin/subliminal", line 6, in <module>
265 from pkg_resources import load_entry_point
266 File "/usr/lib/python3.7/site-packages/pkg_resources/__init__.py", line 3112, in <module>
267 @_call_aside
268 File "/usr/lib/python3.7/site-packages/pkg_resources/__init__.py", line 3096, in _call_aside
269 f(*args, **kwargs)
270 File "/usr/lib/python3.7/site-packages/pkg_resources/__init__.py", line 3125, in _initialize_master_working_set
271 working_set = WorkingSet._build_master()
272 File "/usr/lib/python3.7/site-packages/pkg_resources/__init__.py", line 578, in _build_master
273 ws.require(__requires__)
274 File "/usr/lib/python3.7/site-packages/pkg_resources/__init__.py", line 895, in require
275 needed = self.resolve(parse_requirements(requirements))
276 File "/usr/lib/python3.7/site-packages/pkg_resources/__init__.py", line 781, in resolve
277 raise DistributionNotFound(req, requirers)
278 pkg_resources.DistributionNotFound: The 'pytz>=2012c' distribution was not found and is required by subliminal
279 Provider Guide
281 This guide is going to explain how to add a Provider to subliminal. You
282 are encouraged to take a look at the existing providers, it can be a
283 nice base to start your own provider.
284 Requirements
286 When starting a provider you should be able to answer to the following
287 questions:
288 · What languages does my provider support?
290 · What are the language codes for the supported languages?
292 · Does my provider deliver subtitles for episodes? for movies?
294 · Does my provider require a video hash?
296 Each response of these questions will help you set the correct
298 attributes for your Provider.
299 Video Validation
301 Not all providers deliver subtitles for Episode. Some may require a
302 hash. The check() method does validation against a Video object and
303 will return False if the given Video isn’t suitable. If you’re not
304 happy with the default implementation, you can override it.
305 Configuration
307 API keys must not be configurable by the user and must remain linked to
308 subliminal. Hence they must be written in the provider module.
309 Per-user authentication is allowed and must be configured at instantia‐
311 tion as keyword arguments. Configuration will be done by the user
312 through the provider_configs argument of the list_subtitles() and down‐
313 load_best_subtitles() functions. No network operation must be done dur‐
314 ing instantiation, only configuration. Any error in the configuration
315 must raise a ConfigurationError.
316 Beyond this point, if an error occurs, a generic ProviderError excep‐
318 tion must be raised. You can also use more explicit exception classes
319 AuthenticationError and DownloadLimitExceeded.
320 Initialization / Termination
322 Actual authentication operations must take place in the initialize()
323 method. If you need anything to be executed when the provider isn’t
324 used anymore like logout, use terminate().
325 Caching policy
327 To save bandwidth and improve querying time, intermediate data should
328 be cached when possible. Typical use case is when a query to retrieve
329 show ids is required prior to the query to actually search for subti‐
330 tles. In that case the function that gets the show id from the show
331 name must be cached. Expiration time should be SHOW_EXPIRATION_TIME
332 for shows and EPISODE_EXPIRATION_TIME for episodes.
333 Language
335 To be able to handle various language codes, subliminal makes use of
336 babelfish Language and converters. You must set the attribute languages
337 with a set of supported Language.
338 If you cannot find a suitable converter for your provider, you can make
340 one of your own.
341 Querying
343 The query() method parameters must include all aspects of provider’s
344 querying with primary types.
345 Subtitle
347 A custom Subtitle subclass must be created to represent a subtitle from
348 the provider. It must have relevant attributes that can be used to
349 compute the matches of the subtitle against a Video object.
350 Score computation
352 To be able to compare subtitles coming from different providers between
353 them, the get_matches() method must be implemented.
354 Unittesting
356 All possible uses of query(), list_subtitles() and download_subtitle()
357 methods must have integration tests. Use vcrpy for recording and play‐
358 back of network activity. Other functions must be unittested. If nec‐
359 essary, you can use unittest.mock to mock some functions.
360
362 If you are looking for information on a specific function, class or
363 method, this part of the documentation is for you.
364 Core
366 subliminal.core.ARCHIVE_EXTENSIONS
367 Supported archive extensions
368 class subliminal.core.ProviderPool(providers=None, provider_con‐
370 figs=None)
371 A pool of providers with the same API as a single Provider.
372 It has a few extra features:
374 · Lazy loads providers when needed and supports the with
376 statement to terminate() the providers on exit.
377 · Automatically discard providers on failure.
379 Parameters
381 · providers (list) – name of providers to use, if not
383 all.
384 · provider_configs (dict) – provider configuration as
386 keyword arguments per provider name to pass when
387 instanciating the Provider.
388 providers = None
390 Name of providers to use
391 provider_configs = None
393 Provider configuration
394 initialized_providers = None
396 Initialized providers
397 discarded_providers = None
399 Discarded providers
400 list_subtitles_provider(provider, video, languages)
402 List subtitles with a single provider.
403 The video and languages are checked against the provider.
405 Parameters
407 · provider (str) – name of the provider.
409 · video (Video) – video to list subtitles for.
411 · languages (set of Language) – languages to
413 search for.
414 Returns
416 found subtitles.
417 Return type
419 list of Subtitle or None
420 list_subtitles(video, languages)
422 List subtitles.
423 Parameters
425 · video (Video) – video to list subtitles for.
427 · languages (set of Language) – languages to
429 search for.
430 Returns
432 found subtitles.
433 Return type
435 list of Subtitle
436 download_subtitle(subtitle)
438 Download subtitle’s content.
439 Parameters
441 subtitle (Subtitle) – subtitle to download.
442 Returns
444 True if the subtitle has been successfully down‐
445 loaded, False otherwise.
446 Return type
448 bool
449 download_best_subtitles(subtitles, video, languages,
451 min_score=0, hearing_impaired=False, only_one=False, com‐
452 pute_score=None)
453 Download the best matching subtitles.
454 Parameters
456 · subtitles (list of Subtitle) – the subtitles to
458 use.
459 · video (Video) – video to download subtitles for.
461 · languages (set of Language) – languages to down‐
463 load.
464 · min_score (int) – minimum score for a subtitle
466 to be downloaded.
467 · hearing_impaired (bool) – hearing impaired pref‐
469 erence.
470 · only_one (bool) – download only one subtitle,
472 not one per language.
473 · compute_score – function that takes subtitle and
475 video as positional arguments, hearing_impaired
476 as keyword argument and returns the score.
477 Returns
479 downloaded subtitles.
480 Return type
482 list of Subtitle
483 terminate()
485 Terminate all the initialized_providers.
486 class subliminal.core.AsyncProviderPool(max_workers=None, *args,
488 **kwargs)
489 Subclass of ProviderPool with asynchronous support for
490 list_subtitles().
491 Parameters
493 max_workers (int) – maximum number of threads to use. If
494 None, max_workers will be set to the number of providers.
495 max_workers = None
497 Maximum number of threads to use
498 list_subtitles_provider(provider, video, languages)
500 List subtitles with a single provider.
501 The video and languages are checked against the provider.
503 Parameters
505 · provider (str) – name of the provider.
507 · video (Video) – video to list subtitles for.
509 · languages (set of Language) – languages to
511 search for.
512 Returns
514 found subtitles.
515 Return type
517 list of Subtitle or None
518 list_subtitles(video, languages)
520 List subtitles.
521 Parameters
523 · video (Video) – video to list subtitles for.
525 · languages (set of Language) – languages to
527 search for.
528 Returns
530 found subtitles.
531 Return type
533 list of Subtitle
534 subliminal.core.check_video(video, languages=None, age=None, unde‐
536 fined=False)
537 Perform some checks on the video.
538 All the checks are optional. Return False if any of this check
540 fails:
541 · languages already exist in video’s subtitle_languages.
543 · video is older than age.
545 · video has an undefined language in subtitle_languages.
547 Parameters
549 · video (Video) – video to check.
551 · languages (set of Language) – desired languages.
553 · age (datetime.timedelta) – maximum age of the video.
555 · undefined (bool) – fail on existing undefined language.
557 Returns
559 True if the video passes the checks, False otherwise.
560 Return type
562 bool
563 subliminal.core.search_external_subtitles(path, directory=None)
565 Search for external subtitles from a video path and their asso‐
566 ciated language.
567 Unless directory is provided, search will be made in the same
569 directory as the video file.
570 Parameters
572 · path (str) – path to the video.
574 · directory (str) – directory to search for subtitles.
576 Returns
578 found subtitles with their languages.
579 Return type
581 dict
582 subliminal.core.scan_video(path)
584 Scan a video from a path.
585 Parameters
587 path (str) – existing path to the video.
588 Returns
590 the scanned video.
591 Return type
593 Video
594 subliminal.core.scan_archive(path)
596 Scan an archive from a path.
597 Parameters
599 path (str) – existing path to the archive.
600 Returns
602 the scanned video.
603 Return type
605 Video
606 subliminal.core.scan_videos(path, age=None, archives=True)
608 Scan path for videos and their subtitles.
609 See refine() to find additional information for the video.
611 Parameters
613 · path (str) – existing directory path to scan.
615 · age (datetime.timedelta) – maximum age of the video or
617 archive.
618 · archives (bool) – scan videos in archives.
620 Returns
622 the scanned videos.
623 Return type
625 list of Video
626 subliminal.core.refine(video, episode_refiners=None, movie_refin‐
628 ers=None, **kwargs)
629 Refine a video using refiners.
630 NOTE:
632 Exceptions raised in refiners are silently passed and logged.
633 Parameters
635 · video (Video) – the video to refine.
637 · episode_refiners (tuple) – refiners to use for
639 episodes.
640 · movie_refiners (tuple) – refiners to use for movies.
642 · **kwargs – additional parameters for the refine() func‐
644 tions.
645 subliminal.core.list_subtitles(videos, languages, pool_class=<class
647 'subliminal.core.ProviderPool'>, **kwargs)
648 List subtitles.
649 The videos must pass the languages check of check_video().
651 Parameters
653 · videos (set of Video) – videos to list subtitles for.
655 · languages (set of Language) – languages to search for.
657 · pool_class (ProviderPool, AsyncProviderPool or similar)
659 – class to use as provider pool.
660 · **kwargs – additional parameters for the provided
662 pool_class constructor.
663 Returns
665 found subtitles per video.
666 Return type
668 dict of Video to list of Subtitle
669 subliminal.core.download_subtitles(subtitles, pool_class=<class 'sub‐
671 liminal.core.ProviderPool'>, **kwargs)
672 Download content of subtitles.
673 Parameters
675 · subtitles (list of Subtitle) – subtitles to download.
677 · pool_class (ProviderPool, AsyncProviderPool or similar)
679 – class to use as provider pool.
680 · **kwargs – additional parameters for the provided
682 pool_class constructor.
683 subliminal.core.download_best_subtitles(videos, languages, min_score=0,
685 hearing_impaired=False, only_one=False, compute_score=None,
686 pool_class=<class 'subliminal.core.ProviderPool'>, **kwargs)
687 List and download the best matching subtitles.
688 The videos must pass the languages and undefined (only_one)
690 checks of check_video().
691 Parameters
693 · videos (set of Video) – videos to download subtitles
695 for.
696 · languages (set of Language) – languages to download.
698 · min_score (int) – minimum score for a subtitle to be
700 downloaded.
701 · hearing_impaired (bool) – hearing impaired preference.
703 · only_one (bool) – download only one subtitle, not one
705 per language.
706 · compute_score – function that takes subtitle and video
708 as positional arguments, hearing_impaired as keyword
709 argument and returns the score.
710 · pool_class (ProviderPool, AsyncProviderPool or similar)
712 – class to use as provider pool.
713 · **kwargs – additional parameters for the provided
715 pool_class constructor.
716 Returns
718 downloaded subtitles per video.
719 Return type
721 dict of Video to list of Subtitle
722 subliminal.core.save_subtitles(video, subtitles, single=False, direc‐
724 tory=None, encoding=None)
725 Save subtitles on filesystem.
726 Subtitles are saved in the order of the list. If a subtitle with
728 a language has already been saved, other subtitles with the same
729 language are silently ignored.
730 The extension used is .lang.srt by default or .srt is single is
732 True, with lang being the IETF code for the language of the sub‐
733 title.
734 Parameters
736 · video (Video) – video of the subtitles.
738 · subtitles (list of Subtitle) – subtitles to save.
740 · single (bool) – save a single subtitle, default is to
742 save one subtitle per language.
743 · directory (str) – path to directory where to save the
745 subtitles, default is next to the video.
746 · encoding (str) – encoding in which to save the subti‐
748 tles, default is to keep original encoding.
749 Returns
751 the saved subtitles
752 Return type
754 list of Subtitle
755 Video
757 subliminal.video.VIDEO_EXTENSIONS
758 Video extensions
759 class subliminal.video.Video(name, format=None, release_group=None,
761 resolution=None, video_codec=None, audio_codec=None, imdb_id=None,
762 hashes=None, size=None, subtitle_languages=None)
763 Base class for videos.
764 Represent a video, existing or not.
766 Parameters
768 · name (str) – name or path of the video.
770 · format (str) – format of the video (HDTV, WEB-DL, Blu‐
772 Ray, …).
773 · release_group (str) – release group of the video.
775 · resolution (str) – resolution of the video stream
777 (480p, 720p, 1080p or 1080i).
778 · video_codec (str) – codec of the video stream.
780 · audio_codec (str) – codec of the main audio stream.
782 · imdb_id (str) – IMDb id of the video.
784 · hashes (dict) – hashes of the video file by provider
786 names.
787 · size (int) – size of the video file in bytes.
789 · subtitle_languages (set) – existing subtitle languages.
791 name = None
793 Name or path of the video
794 format = None
796 Format of the video (HDTV, WEB-DL, BluRay, …)
797 release_group = None
799 Release group of the video
800 resolution = None
802 Resolution of the video stream (480p, 720p, 1080p or
803 1080i)
804 video_codec = None
806 Codec of the video stream
807 audio_codec = None
809 Codec of the main audio stream
810 imdb_id = None
812 IMDb id of the video
813 hashes = None
815 Hashes of the video file by provider names
816 size = None
818 Size of the video file in bytes
819 subtitle_languages = None
821 Existing subtitle languages
822 exists Test whether the video exists
824 age Age of the video
826 classmethod fromguess(name, guess)
828 Create an Episode or a Movie with the given name based on
829 the guess.
830 Parameters
832 · name (str) – name of the video.
834 · guess (dict) – guessed data.
836 Raise ValueError if the type of the guess is invalid
838 classmethod fromname(name)
840 Shortcut for fromguess() with a guess guessed from the
841 name.
842 Parameters
844 name (str) – name of the video.
845 class subliminal.video.Episode(name, series, season, episode,
847 title=None, year=None, original_series=True, tvdb_id=None,
848 series_tvdb_id=None, series_imdb_id=None, **kwargs)
849 Episode Video.
850 Parameters
852 · series (str) – series of the episode.
854 · season (int) – season number of the episode.
856 · episode (int) – episode number of the episode.
858 · title (str) – title of the episode.
860 · year (int) – year of the series.
862 · original_series (bool) – whether the series is the
864 first with this name.
865 · tvdb_id (int) – TVDB id of the episode.
867 · **kwargs – additional parameters for the Video con‐
869 structor.
870 series = None
872 Series of the episode
873 season = None
875 Season number of the episode
876 episode = None
878 Episode number of the episode
879 title = None
881 Title of the episode
882 year = None
884 Year of series
885 original_series = None
887 The series is the first with this name
888 tvdb_id = None
890 TVDB id of the episode
891 series_tvdb_id = None
893 TVDB id of the series
894 series_imdb_id = None
896 IMDb id of the series
897 classmethod fromguess(name, guess)
899 Create an Episode or a Movie with the given name based on
900 the guess.
901 Parameters
903 · name (str) – name of the video.
905 · guess (dict) – guessed data.
907 Raise ValueError if the type of the guess is invalid
909 classmethod fromname(name)
911 Shortcut for fromguess() with a guess guessed from the
912 name.
913 Parameters
915 name (str) – name of the video.
916 class subliminal.video.Movie(name, title, year=None, **kwargs)
918 Movie Video.
919 Parameters
921 · title (str) – title of the movie.
923 · year (int) – year of the movie.
925 · **kwargs – additional parameters for the Video con‐
927 structor.
928 title = None
930 Title of the movie
931 year = None
933 Year of the movie
934 classmethod fromguess(name, guess)
936 Create an Episode or a Movie with the given name based on
937 the guess.
938 Parameters
940 · name (str) – name of the video.
942 · guess (dict) – guessed data.
944 Raise ValueError if the type of the guess is invalid
946 classmethod fromname(name)
948 Shortcut for fromguess() with a guess guessed from the
949 name.
950 Parameters
952 name (str) – name of the video.
953 Subtitle
955 subliminal.subtitle.SUBTITLE_EXTENSIONS
956 Subtitle extensions
957 class subliminal.subtitle.Subtitle(language, hearing_impaired=False,
959 page_link=None, encoding=None)
960 Base class for subtitle.
961 Parameters
963 · language (Language) – language of the subtitle.
965 · hearing_impaired (bool) – whether or not the subtitle
967 is hearing impaired.
968 · page_link (str) – URL of the web page from which the
970 subtitle can be downloaded.
971 · encoding (str) – Text encoding of the subtitle.
973 provider_name = ''
975 Name of the provider that returns that class of subtitle
976 language = None
978 Language of the subtitle
979 hearing_impaired = None
981 Whether or not the subtitle is hearing impaired
982 page_link = None
984 URL of the web page from which the subtitle can be down‐
985 loaded
986 content = None
988 Content as bytes
989 encoding = None
991 Encoding to decode with when accessing text
992 id Unique identifier of the subtitle
994 text Content as string
996 If encoding is None, the encoding is guessed with
998 guess_encoding()
999 is_valid()
1001 Check if a text is a valid SubRip format.
1002 Returns
1004 whether or not the subtitle is valid.
1005 Return type
1007 bool
1008 guess_encoding()
1010 Guess encoding using the language, falling back on
1011 chardet.
1012 Returns
1014 the guessed encoding.
1015 Return type
1017 str
1018 get_matches(video)
1020 Get the matches against the video.
1021 Parameters
1023 video (Video) – the video to get the matches with.
1024 Returns
1026 matches of the subtitle.
1027 Return type
1029 set
1030 subliminal.subtitle.get_subtitle_path(video_path, language=None, exten‐
1032 sion='.srt')
1033 Get the subtitle path using the video_path and language.
1034 Parameters
1036 · video_path (str) – path to the video.
1038 · language (Language) – language of the subtitle to put
1040 in the path.
1041 · extension (str) – extension of the subtitle.
1043 Returns
1045 path of the subtitle.
1046 Return type
1048 str
1049 subliminal.subtitle.guess_matches(video, guess, partial=False)
1051 Get matches between a video and a guess.
1052 If a guess is partial, the absence information won’t be counted
1054 as a match.
1055 Parameters
1057 · video (Video) – the video.
1059 · guess (dict) – the guess.
1061 · partial (bool) – whether or not the guess is partial.
1063 Returns
1065 matches between the video and the guess.
1066 Return type
1068 set
1069 subliminal.subtitle.fix_line_ending(content)
1071 Fix line ending of content by changing it to
1072 param bytes content
1074 content of the subtitle.
1075 return the content with fixed line endings.
1077 rtype bytes
1079 Providers
1081 class subliminal.providers.TimeoutSafeTransport(timeout, *args,
1082 **kwargs)
1083 Timeout support for xmlrpc.client.SafeTransport.
1084 class subliminal.providers.ParserBeautifulSoup(markup, parsers,
1086 **kwargs)
1087 A bs4.BeautifulSoup that picks the first parser available in
1088 parsers.
1089 Parameters
1091 · markup -- markup for the bs4.BeautifulSoup.
1093 · parsers (list) -- parser names, in order of preference.
1095 class subliminal.providers.Provider
1097 Base class for providers.
1098 If any configuration is possible for the provider, like creden‐
1100 tials, it must take place during instantiation.
1101 Raise ConfigurationError if there is a configuration error
1103 languages = set([])
1105 Supported set of Language
1106 video_types = (<class 'subliminal.video.Episode'>, <class 'sub‐
1108 liminal.video.Movie'>)
1109 Supported video types
1110 required_hash = None
1112 Required hash, if any
1113 initialize()
1115 Initialize the provider.
1116 Must be called when starting to work with the provider.
1118 This is the place for network initialization or login
1119 operations.
1120 NOTE:
1122 This is called automatically when entering the with
1123 statement
1124 terminate()
1126 Terminate the provider.
1127 Must be called when done with the provider. This is the
1129 place for network shutdown or logout operations.
1130 NOTE:
1132 This is called automatically when exiting the with
1133 statement
1134 classmethod check(video)
1136 Check if the video can be processed.
1137 The video is considered invalid if not an instance of
1139 video_types or if the required_hash is not present in
1140 hashes attribute of the video.
1141 Parameters
1143 video (Video) -- the video to check.
1144 Returns
1146 True if the video is valid, False otherwise.
1147 Return type
1149 bool
1150 query(*args, **kwargs)
1152 Query the provider for subtitles.
1153 Arguments should match as much as possible the actual
1155 parameters for querying the provider
1156 Returns
1158 found subtitles.
1159 Return type
1161 list of Subtitle
1162 Raise ProviderError
1164 list_subtitles(video, languages)
1166 List subtitles for the video with the given languages.
1167 This will call the query() method internally. The parame‐
1169 ters passed to the query() method may vary depending on
1170 the amount of information available in the video.
1171 Parameters
1173 · video (Video) -- video to list subtitles for.
1175 · languages (set of Language) -- languages to
1177 search for.
1178 Returns
1180 found subtitles.
1181 Return type
1183 list of Subtitle
1184 Raise ProviderError
1186 download_subtitle(subtitle)
1188 Download subtitle's content.
1189 Parameters
1191 subtitle (Subtitle) -- subtitle to download.
1192 Raise ProviderError
1194 Addic7ed
1196 subliminal.providers.addic7ed.series_year_re = <_sre.SRE_Pattern
1197 object>
1198 Series header parsing regex
1199 class subliminal.providers.addic7ed.Addic7edSubtitle(language, hear‐
1201 ing_impaired, page_link, series, season, episode, title, year, version,
1202 download_link)
1203 Addic7ed Subtitle.
1204 get_matches(video)
1206 Get the matches against the video.
1207 Parameters
1209 video (Video) -- the video to get the matches
1210 with.
1211 Returns
1213 matches of the subtitle.
1214 Return type
1216 set
1217 class subliminal.providers.addic7ed.Addic7edProvider(username=None,
1219 password=None)
1220 Addic7ed Provider.
1221 initialize()
1223 Initialize the provider.
1224 Must be called when starting to work with the provider.
1226 This is the place for network initialization or login
1227 operations.
1228 NOTE:
1230 This is called automatically when entering the with
1231 statement
1232 terminate()
1234 Terminate the provider.
1235 Must be called when done with the provider. This is the
1237 place for network shutdown or logout operations.
1238 NOTE:
1240 This is called automatically when exiting the with
1241 statement
1242 _get_show_ids(**kw)
1244 Get the dict of show ids per series by querying the
1245 shows.php page.
1246 Returns
1248 show id per series, lower case and without quotes.
1249 Return type
1251 dict
1252 _search_show_id(**kw)
1254 Search the show id from the series and year.
1255 Parameters
1257 · series (str) -- series of the episode.
1259 · year (int) -- year of the series, if any.
1261 Returns
1263 the show id, if found.
1264 Return type
1266 int
1267 get_show_id(series, year=None, country_code=None)
1269 Get the best matching show id for series, year and coun‐
1270 try_code.
1271 First search in the result of _get_show_ids() and fall‐
1273 back on a search with _search_show_id().
1274 Parameters
1276 · series (str) -- series of the episode.
1278 · year (int) -- year of the series, if any.
1280 · country_code (str) -- country code of the
1282 series, if any.
1283 Returns
1285 the show id, if found.
1286 Return type
1288 int
1289 query(series, season, year=None, country=None)
1291 Query the provider for subtitles.
1292 Arguments should match as much as possible the actual
1294 parameters for querying the provider
1295 Returns
1297 found subtitles.
1298 Return type
1300 list of Subtitle
1301 Raise ProviderError
1303 list_subtitles(video, languages)
1305 List subtitles for the video with the given languages.
1306 This will call the query() method internally. The parame‐
1308 ters passed to the query() method may vary depending on
1309 the amount of information available in the video.
1310 Parameters
1312 · video (Video) -- video to list subtitles for.
1314 · languages (set of Language) -- languages to
1316 search for.
1317 Returns
1319 found subtitles.
1320 Return type
1322 list of Subtitle
1323 Raise ProviderError
1325 download_subtitle(subtitle)
1327 Download subtitle's content.
1328 Parameters
1330 subtitle (Subtitle) -- subtitle to download.
1331 Raise ProviderError
1333 LegendasTv
1335 subliminal.providers.legendastv.type_map = {'C': 'episode', 'M':
1336 'movie', 'S': 'episode'}
1337 Conversion map for types
1338 subliminal.providers.legendastv.season_re = <_sre.SRE_Pattern object>
1340 BR title season parsing regex
1341 subliminal.providers.legendastv.downloads_re = <_sre.SRE_Pattern
1343 object>
1344 Downloads parsing regex
1345 subliminal.providers.legendastv.rating_re = <_sre.SRE_Pattern object>
1347 Rating parsing regex
1348 subliminal.providers.legendastv.timestamp_re = <_sre.SRE_Pattern
1350 object>
1351 Timestamp parsing regex
1352 subliminal.providers.legendastv.releases_key = 'sublimi‐
1354 nal.providers.legendastv:releases|{archive_id}'
1355 Cache key for releases
1356 class subliminal.providers.legendastv.LegendasTVArchive(id, name, pack,
1358 featured, link, downloads=0, rating=0, timestamp=None)
1359 LegendasTV Archive.
1360 Parameters
1362 · id (str) -- identifier.
1364 · name (str) -- name.
1366 · pack (bool) -- contains subtitles for multiple
1368 episodes.
1369 · pack -- featured.
1371 · link (str) -- link.
1373 · downloads (int) -- download count.
1375 · rating (int) -- rating (0-10).
1377 · timestamp (datetime.datetime) -- timestamp.
1379 id = None
1381 Identifier
1382 name = None
1384 Name
1385 pack = None
1387 Pack
1388 featured = None
1390 Featured
1391 link = None
1393 Link
1394 downloads = None
1396 Download count
1397 rating = None
1399 Rating (0-10)
1400 timestamp = None
1402 Timestamp
1403 content = None
1405 Compressed content as rarfile.RarFile or zipfile.ZipFile
1406 class subliminal.providers.legendastv.LegendasTVSubtitle(language,
1408 type, title, year, imdb_id, season, archive, name)
1409 LegendasTV Subtitle.
1410 get_matches(video, hearing_impaired=False)
1412 Get the matches against the video.
1413 Parameters
1415 video (Video) -- the video to get the matches
1416 with.
1417 Returns
1419 matches of the subtitle.
1420 Return type
1422 set
1423 class subliminal.providers.legendastv.LegendasTVProvider(username=None,
1425 password=None)
1426 LegendasTV Provider.
1427 Parameters
1429 · username (str) -- username.
1431 · password (str) -- password.
1433 initialize()
1435 Initialize the provider.
1436 Must be called when starting to work with the provider.
1438 This is the place for network initialization or login
1439 operations.
1440 NOTE:
1442 This is called automatically when entering the with
1443 statement
1444 terminate()
1446 Terminate the provider.
1447 Must be called when done with the provider. This is the
1449 place for network shutdown or logout operations.
1450 NOTE:
1452 This is called automatically when exiting the with
1453 statement
1454 search_titles(**kw)
1456 Search for titles matching the title.
1457 Parameters
1459 title (str) -- the title to search for.
1460 Returns
1462 found titles.
1463 Return type
1465 dict
1466 get_archives(**kw)
1468 Get the archive list from a given title_id and lan‐
1469 guage_code.
1470 Parameters
1472 · title_id (int) -- title id.
1474 · language_code (int) -- language code.
1476 Returns
1478 the archives.
1479 Return type
1481 list of LegendasTVArchive
1482 download_archive(archive)
1484 Download an archive's content.
1485 Parameters
1487 archive (LegendasTVArchive) -- the archive to
1488 download content of.
1489 query(language, title, season=None, episode=None, year=None)
1491 Query the provider for subtitles.
1492 Arguments should match as much as possible the actual
1494 parameters for querying the provider
1495 Returns
1497 found subtitles.
1498 Return type
1500 list of Subtitle
1501 Raise ProviderError
1503 list_subtitles(video, languages)
1505 List subtitles for the video with the given languages.
1506 This will call the query() method internally. The parame‐
1508 ters passed to the query() method may vary depending on
1509 the amount of information available in the video.
1510 Parameters
1512 · video (Video) -- video to list subtitles for.
1514 · languages (set of Language) -- languages to
1516 search for.
1517 Returns
1519 found subtitles.
1520 Return type
1522 list of Subtitle
1523 Raise ProviderError
1525 download_subtitle(subtitle)
1527 Download subtitle's content.
1528 Parameters
1530 subtitle (Subtitle) -- subtitle to download.
1531 Raise ProviderError
1533 NapiProjekt
1535 subliminal.providers.napiprojekt.get_subhash(hash)
1536 Get a second hash based on napiprojekt's hash.
1537 Parameters
1539 hash (str) -- napiprojekt's hash.
1540 Returns
1542 the subhash.
1543 Return type
1545 str
1546 class subliminal.providers.napiprojekt.NapiProjektSubtitle(language,
1548 hash)
1549 NapiProjekt Subtitle.
1550 get_matches(video)
1552 Get the matches against the video.
1553 Parameters
1555 video (Video) -- the video to get the matches
1556 with.
1557 Returns
1559 matches of the subtitle.
1560 Return type
1562 set
1563 class subliminal.providers.napiprojekt.NapiProjektProvider
1565 NapiProjekt Provider.
1566 initialize()
1568 Initialize the provider.
1569 Must be called when starting to work with the provider.
1571 This is the place for network initialization or login
1572 operations.
1573 NOTE:
1575 This is called automatically when entering the with
1576 statement
1577 terminate()
1579 Terminate the provider.
1580 Must be called when done with the provider. This is the
1582 place for network shutdown or logout operations.
1583 NOTE:
1585 This is called automatically when exiting the with
1586 statement
1587 query(language, hash)
1589 Query the provider for subtitles.
1590 Arguments should match as much as possible the actual
1592 parameters for querying the provider
1593 Returns
1595 found subtitles.
1596 Return type
1598 list of Subtitle
1599 Raise ProviderError
1601 list_subtitles(video, languages)
1603 List subtitles for the video with the given languages.
1604 This will call the query() method internally. The parame‐
1606 ters passed to the query() method may vary depending on
1607 the amount of information available in the video.
1608 Parameters
1610 · video (Video) -- video to list subtitles for.
1612 · languages (set of Language) -- languages to
1614 search for.
1615 Returns
1617 found subtitles.
1618 Return type
1620 list of Subtitle
1621 Raise ProviderError
1623 download_subtitle(subtitle)
1625 Download subtitle's content.
1626 Parameters
1628 subtitle (Subtitle) -- subtitle to download.
1629 Raise ProviderError
1631 OpenSubtitles
1633 class subliminal.providers.opensubtitles.OpenSubtitlesSubtitle(lan‐
1634 guage, hearing_impaired, page_link, subtitle_id, matched_by,
1635 movie_kind, hash, movie_name, movie_release_name, movie_year,
1636 movie_imdb_id, series_season, series_episode, filename, encoding)
1637 OpenSubtitles Subtitle.
1638 get_matches(video)
1640 Get the matches against the video.
1641 Parameters
1643 video (Video) -- the video to get the matches
1644 with.
1645 Returns
1647 matches of the subtitle.
1648 Return type
1650 set
1651 class subliminal.providers.opensubtitles.OpenSubtitlesProvider(user‐
1653 name=None, password=None)
1654 OpenSubtitles Provider.
1655 Parameters
1657 · username (str) -- username.
1659 · password (str) -- password.
1661 initialize()
1663 Initialize the provider.
1664 Must be called when starting to work with the provider.
1666 This is the place for network initialization or login
1667 operations.
1668 NOTE:
1670 This is called automatically when entering the with
1671 statement
1672 terminate()
1674 Terminate the provider.
1675 Must be called when done with the provider. This is the
1677 place for network shutdown or logout operations.
1678 NOTE:
1680 This is called automatically when exiting the with
1681 statement
1682 query(languages, hash=None, size=None, imdb_id=None, query=None,
1684 season=None, episode=None, tag=None)
1685 Query the provider for subtitles.
1686 Arguments should match as much as possible the actual
1688 parameters for querying the provider
1689 Returns
1691 found subtitles.
1692 Return type
1694 list of Subtitle
1695 Raise ProviderError
1697 list_subtitles(video, languages)
1699 List subtitles for the video with the given languages.
1700 This will call the query() method internally. The parame‐
1702 ters passed to the query() method may vary depending on
1703 the amount of information available in the video.
1704 Parameters
1706 · video (Video) -- video to list subtitles for.
1708 · languages (set of Language) -- languages to
1710 search for.
1711 Returns
1713 found subtitles.
1714 Return type
1716 list of Subtitle
1717 Raise ProviderError
1719 download_subtitle(subtitle)
1721 Download subtitle's content.
1722 Parameters
1724 subtitle (Subtitle) -- subtitle to download.
1725 Raise ProviderError
1727 exception subliminal.providers.opensubtitles.OpenSubtitlesError
1729 Base class for non-generic OpenSubtitlesProvider exceptions.
1730 exception subliminal.providers.opensubtitles.Unauthorized
1732 Exception raised when status is '401 Unauthorized'.
1733 exception subliminal.providers.opensubtitles.NoSession
1735 Exception raised when status is '406 No session'.
1736 exception subliminal.providers.opensubtitles.DownloadLimitReached
1738 Exception raised when status is '407 Download limit reached'.
1739 exception subliminal.providers.opensubtitles.InvalidImdbid
1741 Exception raised when status is '413 Invalid ImdbID'.
1742 exception subliminal.providers.opensubtitles.UnknownUserAgent
1744 Exception raised when status is '414 Unknown User Agent'.
1745 exception subliminal.providers.opensubtitles.DisabledUserAgent
1747 Exception raised when status is '415 Disabled user agent'.
1748 exception subliminal.providers.opensubtitles.ServiceUnavailable
1750 Exception raised when status is '503 Service Unavailable'.
1751 subliminal.providers.opensubtitles.checked(response)
1753 Check a response status before returning it.
1754 Parameters
1756 response -- a response from a XMLRPC call to OpenSubti‐
1757 tles.
1758 Returns
1760 the response.
1761 Raise OpenSubtitlesError
1763 Podnapisi
1765 class subliminal.providers.podnapisi.PodnapisiSubtitle(language, hear‐
1766 ing_impaired, page_link, pid, releases, title, season=None,
1767 episode=None, year=None)
1768 Podnapisi Subtitle.
1769 get_matches(video)
1771 Get the matches against the video.
1772 Parameters
1774 video (Video) -- the video to get the matches
1775 with.
1776 Returns
1778 matches of the subtitle.
1779 Return type
1781 set
1782 class subliminal.providers.podnapisi.PodnapisiProvider
1784 Podnapisi Provider.
1785 initialize()
1787 Initialize the provider.
1788 Must be called when starting to work with the provider.
1790 This is the place for network initialization or login
1791 operations.
1792 NOTE:
1794 This is called automatically when entering the with
1795 statement
1796 terminate()
1798 Terminate the provider.
1799 Must be called when done with the provider. This is the
1801 place for network shutdown or logout operations.
1802 NOTE:
1804 This is called automatically when exiting the with
1805 statement
1806 query(language, keyword, season=None, episode=None, year=None)
1808 Query the provider for subtitles.
1809 Arguments should match as much as possible the actual
1811 parameters for querying the provider
1812 Returns
1814 found subtitles.
1815 Return type
1817 list of Subtitle
1818 Raise ProviderError
1820 list_subtitles(video, languages)
1822 List subtitles for the video with the given languages.
1823 This will call the query() method internally. The parame‐
1825 ters passed to the query() method may vary depending on
1826 the amount of information available in the video.
1827 Parameters
1829 · video (Video) -- video to list subtitles for.
1831 · languages (set of Language) -- languages to
1833 search for.
1834 Returns
1836 found subtitles.
1837 Return type
1839 list of Subtitle
1840 Raise ProviderError
1842 download_subtitle(subtitle)
1844 Download subtitle's content.
1845 Parameters
1847 subtitle (Subtitle) -- subtitle to download.
1848 Raise ProviderError
1850 Shooter
1852 class subliminal.providers.shooter.ShooterSubtitle(language, hash,
1853 download_link)
1854 Shooter Subtitle.
1855 get_matches(video)
1857 Get the matches against the video.
1858 Parameters
1860 video (Video) -- the video to get the matches
1861 with.
1862 Returns
1864 matches of the subtitle.
1865 Return type
1867 set
1868 class subliminal.providers.shooter.ShooterProvider
1870 Shooter Provider.
1871 initialize()
1873 Initialize the provider.
1874 Must be called when starting to work with the provider.
1876 This is the place for network initialization or login
1877 operations.
1878 NOTE:
1880 This is called automatically when entering the with
1881 statement
1882 terminate()
1884 Terminate the provider.
1885 Must be called when done with the provider. This is the
1887 place for network shutdown or logout operations.
1888 NOTE:
1890 This is called automatically when exiting the with
1891 statement
1892 query(language, filename, hash=None)
1894 Query the provider for subtitles.
1895 Arguments should match as much as possible the actual
1897 parameters for querying the provider
1898 Returns
1900 found subtitles.
1901 Return type
1903 list of Subtitle
1904 Raise ProviderError
1906 list_subtitles(video, languages)
1908 List subtitles for the video with the given languages.
1909 This will call the query() method internally. The parame‐
1911 ters passed to the query() method may vary depending on
1912 the amount of information available in the video.
1913 Parameters
1915 · video (Video) -- video to list subtitles for.
1917 · languages (set of Language) -- languages to
1919 search for.
1920 Returns
1922 found subtitles.
1923 Return type
1925 list of Subtitle
1926 Raise ProviderError
1928 download_subtitle(subtitle)
1930 Download subtitle's content.
1931 Parameters
1933 subtitle (Subtitle) -- subtitle to download.
1934 Raise ProviderError
1936 SubsCenter
1938 class subliminal.providers.subscenter.SubsCenterSubtitle(language,
1939 hearing_impaired, page_link, series, season, episode, title, subti‐
1940 tle_id, subtitle_key, downloaded, releases)
1941 SubsCenter Subtitle.
1942 get_matches(video)
1944 Get the matches against the video.
1945 Parameters
1947 video (Video) -- the video to get the matches
1948 with.
1949 Returns
1951 matches of the subtitle.
1952 Return type
1954 set
1955 class subliminal.providers.subscenter.SubsCenterProvider(username=None,
1957 password=None)
1958 SubsCenter Provider.
1959 initialize()
1961 Initialize the provider.
1962 Must be called when starting to work with the provider.
1964 This is the place for network initialization or login
1965 operations.
1966 NOTE:
1968 This is called automatically when entering the with
1969 statement
1970 terminate()
1972 Terminate the provider.
1973 Must be called when done with the provider. This is the
1975 place for network shutdown or logout operations.
1976 NOTE:
1978 This is called automatically when exiting the with
1979 statement
1980 _search_url_titles(**kw)
1982 Search the URL titles by kind for the given title.
1983 Parameters
1985 title (str) -- title to search for.
1986 Returns
1988 the URL titles by kind.
1989 Return type
1991 collections.defaultdict
1992 query(title, season=None, episode=None)
1994 Query the provider for subtitles.
1995 Arguments should match as much as possible the actual
1997 parameters for querying the provider
1998 Returns
2000 found subtitles.
2001 Return type
2003 list of Subtitle
2004 Raise ProviderError
2006 list_subtitles(video, languages)
2008 List subtitles for the video with the given languages.
2009 This will call the query() method internally. The parame‐
2011 ters passed to the query() method may vary depending on
2012 the amount of information available in the video.
2013 Parameters
2015 · video (Video) -- video to list subtitles for.
2017 · languages (set of Language) -- languages to
2019 search for.
2020 Returns
2022 found subtitles.
2023 Return type
2025 list of Subtitle
2026 Raise ProviderError
2028 download_subtitle(subtitle)
2030 Download subtitle's content.
2031 Parameters
2033 subtitle (Subtitle) -- subtitle to download.
2034 Raise ProviderError
2036 TheSubDB
2038 TVsubtitles
2039 class subliminal.providers.tvsubtitles.TVsubtitlesSubtitle(language,
2040 page_link, subtitle_id, series, season, episode, year, rip, release)
2041 TVsubtitles Subtitle.
2042 get_matches(video)
2044 Get the matches against the video.
2045 Parameters
2047 video (Video) -- the video to get the matches
2048 with.
2049 Returns
2051 matches of the subtitle.
2052 Return type
2054 set
2055 class subliminal.providers.tvsubtitles.TVsubtitlesProvider
2057 TVsubtitles Provider.
2058 initialize()
2060 Initialize the provider.
2061 Must be called when starting to work with the provider.
2063 This is the place for network initialization or login
2064 operations.
2065 NOTE:
2067 This is called automatically when entering the with
2068 statement
2069 terminate()
2071 Terminate the provider.
2072 Must be called when done with the provider. This is the
2074 place for network shutdown or logout operations.
2075 NOTE:
2077 This is called automatically when exiting the with
2078 statement
2079 search_show_id(**kw)
2081 Search the show id from the series and year.
2082 Parameters
2084 · series (str) -- series of the episode.
2086 · year (int) -- year of the series, if any.
2088 Returns
2090 the show id, if any.
2091 Return type
2093 int
2094 get_episode_ids(**kw)
2096 Get episode ids from the show id and the season.
2097 Parameters
2099 · show_id (int) -- show id.
2101 · season (int) -- season of the episode.
2103 Returns
2105 episode ids per episode number.
2106 Return type
2108 dict
2109 query(series, season, episode, year=None)
2111 Query the provider for subtitles.
2112 Arguments should match as much as possible the actual
2114 parameters for querying the provider
2115 Returns
2117 found subtitles.
2118 Return type
2120 list of Subtitle
2121 Raise ProviderError
2123 list_subtitles(video, languages)
2125 List subtitles for the video with the given languages.
2126 This will call the query() method internally. The parame‐
2128 ters passed to the query() method may vary depending on
2129 the amount of information available in the video.
2130 Parameters
2132 · video (Video) -- video to list subtitles for.
2134 · languages (set of Language) -- languages to
2136 search for.
2137 Returns
2139 found subtitles.
2140 Return type
2142 list of Subtitle
2143 Raise ProviderError
2145 download_subtitle(subtitle)
2147 Download subtitle's content.
2148 Parameters
2150 subtitle (Subtitle) -- subtitle to download.
2151 Raise ProviderError
2153 Refiners
2155 Refiners enrich a Video object by adding information to it.
2156 A refiner is a simple function:
2158 subliminal.refiners.refine(video, **kwargs)
2160 Parameters
2162 · video (Video) – the video to refine.
2164 · **kwargs – additional parameters for refiners.
2166 Metadata
2168 subliminal.refiners.metadata.refine(video, embedded_subtitles=True,
2169 **kwargs)
2170 Refine a video by searching its metadata.
2171 Several Video attributes can be found:
2173 · resolution
2175 · video_codec
2177 · audio_codec
2179 · subtitle_languages
2181 Parameters
2183 embedded_subtitles (bool) – search for embedded subti‐
2184 tles.
2185 TVDB
2187 subliminal.refiners.tvdb.refine(video, **kwargs)
2188 Refine a video by searching TheTVDB.
2189 NOTE:
2191 This refiner only work for instances of Episode.
2192 Several attributes can be found:
2194 · series
2196 · year
2198 · series_imdb_id
2200 · series_tvdb_id
2202 · title
2204 · imdb_id
2206 · tvdb_id
2208 OMDb
2210 subliminal.refiners.omdb.refine(video, **kwargs)
2211 Refine a video by searching OMDb API.
2212 Several Episode attributes can be found:
2214 · series
2216 · year
2218 · series_imdb_id
2220 Similarly, for a Movie:
2222 · title
2224 · year
2226 · imdb_id
2228 Extensions
2230 class subliminal.extensions.RegistrableExtensionManager(namespace,
2231 internal_extensions, **kwargs)
2232 :class:~stevedore.extensions.ExtensionManager` with support for
2233 registration.
2234 It allows loading of internal extensions without setup and reg‐
2236 istering/unregistering additional extensions.
2237 Loading is done in this order:
2239 · Entry point extensions
2241 · Internal extensions
2243 · Registered extensions
2245 Parameters
2247 · namespace (str) – namespace argument for :class:~steve‐
2249 dore.extensions.ExtensionManager`.
2250 · internal_extensions (list) – internal extensions to use
2252 with entry point syntax.
2253 · **kwargs – additional parameters for the :class:~steve‐
2255 dore.extensions.ExtensionManager` constructor.
2256 registered_extensions = None
2258 Registered extensions with entry point syntax
2259 internal_extensions = None
2261 Internal extensions with entry point syntax
2262 register(entry_point)
2264 Register an extension
2265 Parameters
2267 entry_point (str) – extension to register (entry
2268 point syntax).
2269 Raise ValueError if already registered.
2271 unregister(entry_point)
2273 Unregister a provider
2274 Parameters
2276 entry_point (str) – provider to unregister (entry
2277 point syntax).
2278 subliminal.extensions.provider_manager = <subliminal.extensions.Regis‐
2280 trableExtensionManager object>
2281 Provider manager
2282 subliminal.extensions.refiner_manager = <subliminal.extensions.Regis‐
2284 trableExtensionManager object>
2285 Refiner manager
2286 Score
2288 This module provides the default implementation of the compute_score
2289 parameter in download_best_subtitles() and download_best_subtitles().
2290 NOTE:
2292 To avoid unnecessary dependency on sympy and boost subliminal’s
2293 import time, the resulting scores are hardcoded here and manually
2294 updated when the set of equations change.
2295 Available matches:
2297 · hash
2299 · title
2301 · year
2303 · series
2305 · season
2307 · episode
2309 · release_group
2311 · format
2313 · audio_codec
2315 · resolution
2317 · hearing_impaired
2319 · video_codec
2321 · series_imdb_id
2323 · imdb_id
2325 · tvdb_id
2327 subliminal.score.episode_scores = {'audio_codec': 3, 'episode': 30,
2329 'format': 7, 'hash': 359, 'hearing_impaired': 1, 'release_group': 15,
2330 'resolution': 2, 'season': 30, 'series': 180, 'video_codec': 2, 'year':
2331 90}
2332 Scores for episodes
2333 subliminal.score.movie_scores = {'audio_codec': 3, 'format': 7, 'hash':
2335 119, 'hearing_impaired': 1, 'release_group': 15, 'resolution': 2,
2336 'title': 60, 'video_codec': 2, 'year': 30}
2337 Scores for movies
2338 subliminal.score.equivalent_release_groups = (set(['DIMENSION',
2340 'LOL']), set(['FLEET', 'IMMERSE', 'ASAP']))
2341 Equivalent release groups
2342 subliminal.score.get_equivalent_release_groups(release_group)
2344 Get all the equivalents of the given release group.
2345 Parameters
2347 release_group (str) – the release group to get the equiv‐
2348 alents of.
2349 Returns
2351 the equivalent release groups.
2352 Return type
2354 set
2355 subliminal.score.get_scores(video)
2357 Get the scores dict for the given video.
2358 This will return either episode_scores or movie_scores based on
2360 the type of the video.
2361 Parameters
2363 video (Video) – the video to compute the score against.
2364 Returns
2366 the scores dict.
2367 Return type
2369 dict
2370 subliminal.score.compute_score(subtitle, video, hearing_impaired=None)
2372 Compute the score of the subtitle against the video with hear‐
2373 ing_impaired preference.
2374 compute_score() uses the Subtitle.get_matches method and applies
2376 the scores (either from episode_scores or movie_scores) after
2377 some processing.
2378 Parameters
2380 · subtitle (Subtitle) – the subtitle to compute the score
2382 of.
2383 · video (Video) – the video to compute the score against.
2385 · hearing_impaired (bool) – hearing impaired preference.
2387 Returns
2389 score of the subtitle.
2390 Return type
2392 int
2393 Utils
2395 subliminal.utils.hash_opensubtitles(video_path)
2396 Compute a hash using OpenSubtitles’ algorithm.
2397 Parameters
2399 video_path (str) – path of the video.
2400 Returns
2402 the hash.
2403 Return type
2405 str
2406 subliminal.utils.hash_thesubdb(video_path)
2408 Compute a hash using TheSubDB’s algorithm.
2409 Parameters
2411 video_path (str) – path of the video.
2412 Returns
2414 the hash.
2415 Return type
2417 str
2418 subliminal.utils.hash_napiprojekt(video_path)
2420 Compute a hash using NapiProjekt’s algorithm.
2421 Parameters
2423 video_path (str) – path of the video.
2424 Returns
2426 the hash.
2427 Return type
2429 str
2430 subliminal.utils.hash_shooter(video_path)
2432 Compute a hash using Shooter’s algorithm
2433 Parameters
2435 video_path (string) – path of the video
2436 Returns
2438 the hash
2439 Return type
2441 string
2442 subliminal.utils.sanitize(string, ignore_characters=None)
2444 Sanitize a string to strip special characters.
2445 Parameters
2447 · string (str) – the string to sanitize.
2449 · ignore_characters (set) – characters to ignore.
2451 Returns
2453 the sanitized string.
2454 Return type
2456 str
2457 subliminal.utils.sanitize_release_group(string)
2459 Sanitize a release_group string to remove content in square
2460 brackets.
2461 Parameters
2463 string (str) – the release group to sanitize.
2464 Returns
2466 the sanitized release group.
2467 Return type
2469 str
2470 subliminal.utils.timestamp(date)
2472 Get the timestamp of the date, python2/3 compatible
2473 Parameters
2475 date (datetime.datetime) – the utc date.
2476 Returns
2478 the timestamp of the date.
2479 Return type
2481 float
2482 Cache
2484 subliminal.cache.SHOW_EXPIRATION_TIME
2485 Expiration time for show caching
2486 subliminal.cache.EPISODE_EXPIRATION_TIME
2488 Expiration time for episode caching
2489 subliminal.cache.REFINER_EXPIRATION_TIME
2491 Expiration time for scraper searches
2492 subliminal.cache.region
2494 The CacheRegion
2495 Refer to dogpile.cache’s region configuration documentation to see how
2497 to configure the region
2498 CLI
2500 Exceptions
2501 exception subliminal.exceptions.Error
2502 Base class for exceptions in subliminal.
2503 exception subliminal.exceptions.ProviderError
2505 Exception raised by providers.
2506 exception subliminal.exceptions.ConfigurationError
2508 Exception raised by providers when badly configured.
2509 exception subliminal.exceptions.AuthenticationError
2511 Exception raised by providers when authentication failed.
2512 exception subliminal.exceptions.TooManyRequests
2514 Exception raised by providers when too many requests are made.
2515 exception subliminal.exceptions.DownloadLimitExceeded
2517 Exception raised by providers when download limit is exceeded.
2518
2520 MIT
2521 · genindex
2523 · modindex
2525 · search
2527
2529 Antoine Bertin
2530
2532 2016, Antoine Bertin
25332.0.5 Dec 28, 2018 SUBLIMINAL(1)