Welcome to subliminal!¶
Subliminal is a python 2.7+ library to search and download subtitles. It comes with an easy to use yet powerful CLI suitable for direct use or cron jobs.
Documentation¶
Usage¶
CLI¶
Download English subtitles:
$ subliminal download -l en The.Big.Bang.Theory.S05E18.HDTV.x264-LOL.mp4
Collecting videos [####################################] 100%
1 video collected / 0 video ignored
Downloading subtitles [####################################] 100%
Downloaded 1 subtitle
Warning
For cron usage, make sure to specify a maximum age (with --age
) so subtitles are searched for recent videos
only. Otherwise you will get banned from the providers for abuse due to too many requests. If subliminal didn’t
find subtitles for an old video, it’s unlikely it will find subtitles for that video ever anyway.
See CLI for more details on the available commands and options.
Nautilus/Nemo integration¶
See the dedicated project page for more information.
High level API¶
You can call subliminal in many different ways depending on how much control you want over the process. For most use cases, you can stick to the standard API.
Common¶
Let’s start by importing subliminal:
>>> import os
>>> from babelfish import *
>>> from subliminal import *
Before going further, there are a few things to know about subliminal.
Video¶
The Movie
and Episode
classes represent a video,
existing or not. You can create a video by name (or path) with Video.fromname
,
use scan_video()
on an existing file path to get even more information about the video or
use scan_videos()
on an existing directory path to scan a whole directory for videos.
>>> video = Video.fromname('The.Big.Bang.Theory.S05E18.HDTV.x264-LOL.mp4')
>>> video
<Episode ['The Big Bang Theory', 5x18]>
Here video information was guessed based on the name of the video, you can access some video attributes:
>>> video.video_codec
'h264'
>>> video.release_group
'LOL'
Configuration¶
Before proceeding to listing and downloading subtitles, you need to configure the cache. Subliminal uses a cache to reduce repeated queries to providers and improve overall performance with no impact on search quality. For the sake of this example, we’re going to use a memory backend.
>>> my_region = region.configure('dogpile.cache.memory')
Warning
Choose a cache that fits your application and prefer persistent over volatile backends. The file
backend is
usually a good choice.
See dogpile.cache’s documentation for more details on backends.
Now that we’re done with the basics, let’s have some real fun.
Listing¶
To list subtitles, subliminal provides a list_subtitles()
function that will return all found
subtitles:
>>> subtitles = list_subtitles([video], {Language('hun')}, providers=['podnapisi'])
>>> subtitles[video]
[<PodnapisiSubtitle 'ZtAW' [hu]>, <PodnapisiSubtitle 'ONAW' [hu]>]
Note
As you noticed, all parameters are iterables but only contain one item which means you can deal with a lot of
videos, languages and providers at the same time. For the sake of this example, we filter providers to use only one,
pass providers=None
(default) to search on all providers.
Scoring¶
It’s usual you have multiple candidates for subtitles. To help you chose which one to download, subliminal can compare
them to the video and tell you exactly what matches with get_matches()
:
>>> for s in subtitles[video]:
... sorted(s.get_matches(video))
['episode', 'format', 'release_group', 'season', 'series', 'video_codec', 'year']
['episode', 'format', 'season', 'series', 'year']
And then compute a score with those matches with compute_score()
:
>>> for s in subtitles[video]:
... {s: compute_score(s, video)}
{<PodnapisiSubtitle 'ZtAW' [hu]>: 354}
{<PodnapisiSubtitle 'ONAW' [hu]>: 337}
Now you should have a better idea about which one you should choose.
Downloading¶
We can settle on the first subtitle and download its content using download_subtitles()
:
>>> subtitle = subtitles[video][0]
>>> subtitle.content is None
True
>>> download_subtitles([subtitle])
>>> subtitle.content.split(b'\n')[2]
b'Elszaladok a boltba'
If you want a string instead of bytes, you can access decoded content with the
text
property:
>>> subtitle.text.split('\n')[3]
'néhány apróságért.'
Downloading best subtitles¶
Downloading best subtitles is what you want to do in almost all cases, as a shortcut for listing, scoring and
downloading you can use download_best_subtitles()
:
>>> best_subtitles = download_best_subtitles([video], {Language('hun')}, providers=['podnapisi'])
>>> best_subtitles[video]
[<PodnapisiSubtitle 'ZtAW' [hu]>]
>>> best_subtitle = best_subtitles[video][0]
>>> best_subtitle.content.split(b'\n')[2]
b'Elszaladok a boltba'
We end up with the same subtitle but with one line of code. Neat.
Save¶
We got ourselves a nice subtitle, now we can save it on the file system using save_subtitles()
:
>>> save_subtitles(video, [best_subtitle])
[<PodnapisiSubtitle 'ZtAW' [hu]>]
>>> os.listdir()
['The.Big.Bang.Theory.S05E18.HDTV.x264-LOL.hu.srt']
How it works¶
Providers¶
Subliminal uses multiple providers to give users a vast choice and have a better chance to find the best matching subtitles. Current supported providers are:
- Addic7ed
- LegendasTV
- NapiProjekt
- OpenSubtitles
- Podnapisi
- Shooter
- SubsCenter
- TheSubDB
- TvSubtitles
Providers all inherit the same Provider
base class and thus share the same API.
They are registered on the subliminal.providers
entry point and are exposed through the
provider_manager
for easy access.
To work with multiple providers seamlessly, the ProviderPool
exposes the same API but
distributes it to its providers and AsyncProviderPool
does it asynchronously.
Scoring¶
Rating subtitles and comparing them is probably the most difficult part and this is where subliminal excels with its powerful scoring algorithm.
Using guessit and enzyme, subliminal extracts properties of the video and match them with the properties of the subtitles found with the providers.
Equations in subliminal.score
give a score to each property (called a match). The more matches the video and
the subtitle have, the higher the score computed with compute_score()
gets.
Libraries¶
Various libraries are used by subliminal and are key to its success:
- guessit to guess information from filenames
- enzyme to detect embedded subtitles in videos and read other video metadata
- babelfish to work with languages
- requests to make human readable HTTP requests
- BeautifulSoup to parse HTML and XML
- dogpile.cache to cache intermediate search results
- stevedore to manage the provider entry point
- chardet to detect subtitles’ encoding
- pysrt to validate downloaded subtitles
CLI¶
subliminal¶
Usage: subliminal [OPTIONS] COMMAND [ARGS]...
Subtitles, faster than your thoughts.
Options:
--addic7ed USERNAME PASSWORD Addic7ed configuration.
--legendastv USERNAME PASSWORD LegendasTV configuration.
--opensubtitles USERNAME PASSWORD
OpenSubtitles configuration.
--subscenter USERNAME PASSWORD SubsCenter configuration.
--cache-dir DIRECTORY Path to the cache directory. [default:
/home/docs/.cache/subliminal]
--debug Print useful information for debugging
subliminal and for reporting bugs.
--version Show the version and exit.
--help Show this message and exit.
Commands:
cache Cache management.
download Download best subtitles.
Suggestions and bug reports are greatly appreciated:
https://github.com/Diaoul/subliminal/
subliminal download¶
Usage: subliminal download [OPTIONS] PATH...
Download best subtitles.
PATH can be an directory containing videos, a video file path or a video
file name. It can be used multiple times.
If an existing subtitle is detected (external or embedded) in the correct
language, the download is skipped for the associated video.
Options:
-l, --language LANGUAGE Language as IETF code, e.g. en, pt-BR (can
be used multiple times). [required]
-p, --provider [addic7ed|legendastv|opensubtitles|podnapisi|shooter|subscenter|thesubdb|tvsubtitles]
Provider to use (can be used multiple
times).
-r, --refiner [metadata|omdb|tvdb]
Refiner to use (can be used multiple times).
-a, --age AGE Filter videos newer than AGE, e.g. 12h,
1w2d.
-d, --directory DIR Directory where to save subtitles, default
is next to the video file.
-e, --encoding ENC Subtitle file encoding, default is to
preserve original encoding.
-s, --single Save subtitle without language code in the
file name, i.e. use .srt extension. Do not
use this unless your media player requires
it.
-f, --force Force download even if a subtitle already
exist.
-hi, --hearing-impaired Prefer hearing impaired subtitles.
-m, --min-score INTEGER RANGE Minimum score for a subtitle to be
downloaded (0 to 100).
-w, --max-workers INTEGER RANGE
Maximum number of threads to use.
-z, --archives / -Z, --no-archives
Scan archives for videos (supported
extensions: .rar). [default: True]
-v, --verbose Increase verbosity.
--help Show this message and exit.
subliminal cache¶
Usage: subliminal cache [OPTIONS]
Cache management.
Options:
--clear-subliminal Clear subliminal's cache. Use this ONLY if your cache is
corrupted or if you experience issues.
--help Show this message and exit.
Provider Guide¶
This guide is going to explain how to add a Provider
to subliminal. You are encouraged
to take a look at the existing providers, it can be a nice base to start your own provider.
Requirements¶
When starting a provider you should be able to answer to the following questions:
- What languages does my provider support?
- What are the language codes for the supported languages?
- Does my provider deliver subtitles for episodes? for movies?
- Does my provider require a video hash?
Each response of these questions will help you set the correct attributes for your
Provider
.
Video Validation¶
Not all providers deliver subtitles for Episode
. Some may require a hash.
The check()
method does validation against a Video
object and will return False if the given Video
isn’t suitable. If you’re not happy
with the default implementation, you can override it.
Configuration¶
API keys must not be configurable by the user and must remain linked to subliminal. Hence they must be written in the provider module.
Per-user authentication is allowed and must be configured at instantiation as keyword arguments. Configuration
will be done by the user through the provider_configs argument of the list_subtitles()
and
download_best_subtitles()
functions. No network operation must be done during instantiation,
only configuration. Any error in the configuration must raise a
ConfigurationError
.
Beyond this point, if an error occurs, a generic ProviderError
exception
must be raised. You can also use more explicit exception classes AuthenticationError
and DownloadLimitExceeded
.
Initialization / Termination¶
Actual authentication operations must take place in the initialize()
method.
If you need anything to be executed when the provider isn’t used anymore like logout,
use terminate()
.
Caching policy¶
To save bandwidth and improve querying time, intermediate data should be cached when possible. Typical use case is
when a query to retrieve show ids is required prior to the query to actually search for subtitles. In that case
the function that gets the show id from the show name must be cached.
Expiration time should be SHOW_EXPIRATION_TIME
for shows and
EPISODE_EXPIRATION_TIME
for episodes.
Language¶
To be able to handle various language codes, subliminal makes use of babelfish
Language and converters. You must set the attribute languages
with a set of
supported Language
.
If you cannot find a suitable converter for your provider, you can make one of your own.
Querying¶
The query()
method parameters must include all aspects of provider’s querying with
primary types.
Subtitle¶
A custom Subtitle
subclass must be created to represent a subtitle from the provider.
It must have relevant attributes that can be used to compute the matches of the subtitle against a
Video
object.
Score computation¶
To be able to compare subtitles coming from different providers between them, the
get_matches()
method must be implemented.
Unittesting¶
All possible uses of query()
,
list_subtitles()
and download_subtitle()
methods must have integration tests. Use vcrpy for recording and playback
of network activity.
Other functions must be unittested. If necessary, you can use unittest.mock
to mock some functions.
API Documentation¶
If you are looking for information on a specific function, class or method, this part of the documentation is for you.
Core¶
-
subliminal.core.
ARCHIVE_EXTENSIONS
¶ Supported archive extensions
-
class
subliminal.core.
ProviderPool
(providers=None, provider_configs=None)[source]¶ A pool of providers with the same API as a single
Provider
.It has a few extra features:
- Lazy loads providers when needed and supports the with statement to
terminate()
the providers on exit. - Automatically discard providers on failure.
Parameters: -
providers
= None¶ Name of providers to use
-
provider_configs
= None¶ Provider configuration
-
initialized_providers
= None¶ Initialized providers
-
discarded_providers
= None¶ Discarded providers
-
list_subtitles_provider
(provider, video, languages)[source]¶ List subtitles with a single provider.
The video and languages are checked against the provider.
Parameters: Returns: found subtitles.
Return type: list of
Subtitle
or None
-
list_subtitles
(video, languages)[source]¶ List subtitles.
Parameters: Returns: found subtitles.
Return type: list of
Subtitle
-
download_subtitle
(subtitle)[source]¶ Download subtitle‘s
content
.Parameters: subtitle ( Subtitle
) – subtitle to download.Returns: True if the subtitle has been successfully downloaded, False otherwise. Return type: bool
-
download_best_subtitles
(subtitles, video, languages, min_score=0, hearing_impaired=False, only_one=False, compute_score=None)[source]¶ Download the best matching subtitles.
Parameters: - subtitles (list of
Subtitle
) – the subtitles to use. - video (
Video
) – video to download subtitles for. - languages (set of
Language
) – languages to download. - min_score (int) – minimum score for a subtitle to be downloaded.
- hearing_impaired (bool) – hearing impaired preference.
- only_one (bool) – download only one subtitle, not one per language.
- compute_score – function that takes subtitle and video as positional arguments, hearing_impaired as keyword argument and returns the score.
Returns: downloaded subtitles.
Return type: list of
Subtitle
- subtitles (list of
-
terminate
()[source]¶ Terminate all the
initialized_providers
.
- Lazy loads providers when needed and supports the with statement to
-
class
subliminal.core.
AsyncProviderPool
(max_workers=None, *args, **kwargs)[source]¶ Subclass of
ProviderPool
with asynchronous support forlist_subtitles()
.Parameters: max_workers (int) – maximum number of threads to use. If None, max_workers
will be set to the number ofproviders
.-
max_workers
= None¶ Maximum number of threads to use
-
-
subliminal.core.
check_video
(video, languages=None, age=None, undefined=False)[source]¶ Perform some checks on the video.
All the checks are optional. Return False if any of this check fails:
- languages already exist in video‘s
subtitle_languages
. - video is older than age.
- video has an undefined language in
subtitle_languages
.
Parameters: - video (
Video
) – video to check. - languages (set of
Language
) – desired languages. - age (datetime.timedelta) – maximum age of the video.
- undefined (bool) – fail on existing undefined language.
Returns: True if the video passes the checks, False otherwise.
Return type: - languages already exist in video‘s
-
subliminal.core.
search_external_subtitles
(path, directory=None)[source]¶ Search for external subtitles from a video path and their associated language.
Unless directory is provided, search will be made in the same directory as the video file.
Parameters: Returns: found subtitles with their languages.
Return type:
-
subliminal.core.
scan_video
(path)[source]¶ Scan a video from a path.
Parameters: path (str) – existing path to the video. Returns: the scanned video. Return type: Video
-
subliminal.core.
scan_archive
(path)[source]¶ Scan an archive from a path.
Parameters: path (str) – existing path to the archive. Returns: the scanned video. Return type: Video
-
subliminal.core.
scan_videos
(path, age=None, archives=True)[source]¶ Scan path for videos and their subtitles.
See
refine()
to find additional information for the video.Parameters: - path (str) – existing directory path to scan.
- age (datetime.timedelta) – maximum age of the video or archive.
- archives (bool) – scan videos in archives.
Returns: the scanned videos.
Return type: list of
Video
-
subliminal.core.
refine
(video, episode_refiners=None, movie_refiners=None, **kwargs)[source]¶ Refine a video using Refiners.
Note
Exceptions raised in refiners are silently passed and logged.
Parameters:
-
subliminal.core.
list_subtitles
(videos, languages, pool_class=<class 'subliminal.core.ProviderPool'>, **kwargs)[source]¶ List subtitles.
The videos must pass the languages check of
check_video()
.Parameters: - videos (set of
Video
) – videos to list subtitles for. - languages (set of
Language
) – languages to search for. - pool_class (
ProviderPool
,AsyncProviderPool
or similar) – class to use as provider pool. - **kwargs – additional parameters for the provided pool_class constructor.
Returns: found subtitles per video.
Return type: - videos (set of
-
subliminal.core.
download_subtitles
(subtitles, pool_class=<class 'subliminal.core.ProviderPool'>, **kwargs)[source]¶ Download
content
of subtitles.Parameters: - subtitles (list of
Subtitle
) – subtitles to download. - pool_class (
ProviderPool
,AsyncProviderPool
or similar) – class to use as provider pool. - **kwargs – additional parameters for the provided pool_class constructor.
- subtitles (list of
-
subliminal.core.
download_best_subtitles
(videos, languages, min_score=0, hearing_impaired=False, only_one=False, compute_score=None, pool_class=<class 'subliminal.core.ProviderPool'>, **kwargs)[source]¶ List and download the best matching subtitles.
The videos must pass the languages and undefined (only_one) checks of
check_video()
.Parameters: - videos (set of
Video
) – videos to download subtitles for. - languages (set of
Language
) – languages to download. - min_score (int) – minimum score for a subtitle to be downloaded.
- hearing_impaired (bool) – hearing impaired preference.
- only_one (bool) – download only one subtitle, not one per language.
- compute_score – function that takes subtitle and video as positional arguments, hearing_impaired as keyword argument and returns the score.
- pool_class (
ProviderPool
,AsyncProviderPool
or similar) – class to use as provider pool. - **kwargs – additional parameters for the provided pool_class constructor.
Returns: downloaded subtitles per video.
Return type: - videos (set of
-
subliminal.core.
save_subtitles
(video, subtitles, single=False, directory=None, encoding=None)[source]¶ Save subtitles on filesystem.
Subtitles are saved in the order of the list. If a subtitle with a language has already been saved, other subtitles with the same language are silently ignored.
The extension used is .lang.srt by default or .srt is single is True, with lang being the IETF code for the
language
of the subtitle.Parameters: - video (
Video
) – video of the subtitles. - subtitles (list of
Subtitle
) – subtitles to save. - single (bool) – save a single subtitle, default is to save one subtitle per language.
- directory (str) – path to directory where to save the subtitles, default is next to the video.
- encoding (str) – encoding in which to save the subtitles, default is to keep original encoding.
Returns: the saved subtitles
Return type: list of
Subtitle
- video (
Video¶
-
subliminal.video.
VIDEO_EXTENSIONS
¶ Video extensions
-
class
subliminal.video.
Video
(name, format=None, release_group=None, resolution=None, video_codec=None, audio_codec=None, imdb_id=None, hashes=None, size=None, subtitle_languages=None)[source]¶ Base class for videos.
Represent a video, existing or not.
Parameters: - name (str) – name or path of the video.
- format (str) – format of the video (HDTV, WEB-DL, BluRay, ...).
- release_group (str) – release group of the video.
- resolution (str) – resolution of the video stream (480p, 720p, 1080p or 1080i).
- video_codec (str) – codec of the video stream.
- audio_codec (str) – codec of the main audio stream.
- imdb_id (str) – IMDb id of the video.
- hashes (dict) – hashes of the video file by provider names.
- size (int) – size of the video file in bytes.
- subtitle_languages (set) – existing subtitle languages.
-
name
= None¶ Name or path of the video
-
format
= None¶ Format of the video (HDTV, WEB-DL, BluRay, ...)
-
release_group
= None¶ Release group of the video
-
resolution
= None¶ Resolution of the video stream (480p, 720p, 1080p or 1080i)
-
video_codec
= None¶ Codec of the video stream
-
audio_codec
= None¶ Codec of the main audio stream
-
imdb_id
= None¶ IMDb id of the video
-
hashes
= None¶ Hashes of the video file by provider names
-
size
= None¶ Size of the video file in bytes
-
subtitle_languages
= None¶ Existing subtitle languages
-
exists
¶ Test whether the video exists
-
age
¶ Age of the video
-
classmethod
fromguess
(name, guess)[source]¶ Create an
Episode
or aMovie
with the given name based on the guess.Parameters: Raise: ValueError
if the type of the guess is invalid
-
classmethod
fromname
(name)[source]¶ Shortcut for
fromguess()
with a guess guessed from the name.Parameters: name (str) – name of the video.
-
class
subliminal.video.
Episode
(name, series, season, episode, title=None, year=None, original_series=True, tvdb_id=None, series_tvdb_id=None, series_imdb_id=None, **kwargs)[source]¶ Episode
Video
.Parameters: - series (str) – series of the episode.
- season (int) – season number of the episode.
- episode (int) – episode number of the episode.
- title (str) – title of the episode.
- year (int) – year of the series.
- original_series (bool) – whether the series is the first with this name.
- tvdb_id (int) – TVDB id of the episode.
- **kwargs – additional parameters for the
Video
constructor.
-
series
= None¶ Series of the episode
-
season
= None¶ Season number of the episode
-
episode
= None¶ Episode number of the episode
-
title
= None¶ Title of the episode
-
year
= None¶ Year of series
-
original_series
= None¶ The series is the first with this name
-
tvdb_id
= None¶ TVDB id of the episode
-
series_tvdb_id
= None¶ TVDB id of the series
-
series_imdb_id
= None¶ IMDb id of the series
Subtitle¶
-
subliminal.subtitle.
SUBTITLE_EXTENSIONS
¶ Subtitle extensions
-
class
subliminal.subtitle.
Subtitle
(language, hearing_impaired=False, page_link=None, encoding=None)[source]¶ Base class for subtitle.
Parameters: -
provider_name
= ''¶ Name of the provider that returns that class of subtitle
-
language
= None¶ Language of the subtitle
-
hearing_impaired
= None¶ Whether or not the subtitle is hearing impaired
-
page_link
= None¶ URL of the web page from which the subtitle can be downloaded
-
content
= None¶ Content as bytes
-
id
¶ Unique identifier of the subtitle
-
text
¶ Content as string
If
encoding
is None, the encoding is guessed withguess_encoding()
-
is_valid
()[source]¶ Check if a
text
is a valid SubRip format.Returns: whether or not the subtitle is valid. Return type: bool
-
-
subliminal.subtitle.
get_subtitle_path
(video_path, language=None, extension='.srt')[source]¶ Get the subtitle path using the video_path and language.
Parameters: Returns: path of the subtitle.
Return type:
Providers¶
-
class
subliminal.providers.
TimeoutSafeTransport
(timeout, *args, **kwargs)[source]¶ Timeout support for
xmlrpc.client.SafeTransport
.
-
class
subliminal.providers.
ParserBeautifulSoup
(markup, parsers, **kwargs)[source]¶ A
bs4.BeautifulSoup
that picks the first parser available in parsers.Parameters: - markup – markup for the
bs4.BeautifulSoup
. - parsers (list) – parser names, in order of preference.
- markup – markup for the
-
class
subliminal.providers.
Provider
[source]¶ Base class for providers.
If any configuration is possible for the provider, like credentials, it must take place during instantiation.
Raise: ConfigurationError
if there is a configuration error-
video_types
= (<class 'subliminal.video.Episode'>, <class 'subliminal.video.Movie'>)¶ Supported video types
-
required_hash
= None¶ Required hash, if any
-
initialize
()[source]¶ Initialize the provider.
Must be called when starting to work with the provider. This is the place for network initialization or login operations.
Note
This is called automatically when entering the with statement
-
terminate
()[source]¶ Terminate the provider.
Must be called when done with the provider. This is the place for network shutdown or logout operations.
Note
This is called automatically when exiting the with statement
-
classmethod
check
(video)[source]¶ Check if the video can be processed.
The video is considered invalid if not an instance of
video_types
or if therequired_hash
is not present inhashes
attribute of the video.Parameters: video ( Video
) – the video to check.Returns: True if the video is valid, False otherwise. Return type: bool
-
query
(*args, **kwargs)[source]¶ Query the provider for subtitles.
Arguments should match as much as possible the actual parameters for querying the provider
Returns: found subtitles. Return type: list of Subtitle
Raise: ProviderError
-
list_subtitles
(video, languages)[source]¶ List subtitles for the video with the given languages.
This will call the
query()
method internally. The parameters passed to thequery()
method may vary depending on the amount of information available in the video.Parameters: Returns: found subtitles.
Return type: list of
Subtitle
Raise:
-
download_subtitle
(subtitle)[source]¶ Download subtitle‘s
content
.Parameters: subtitle ( Subtitle
) – subtitle to download.Raise: ProviderError
-
Addic7ed¶
-
subliminal.providers.addic7ed.
series_year_re
= <_sre.SRE_Pattern object>¶ Series header parsing regex
-
class
subliminal.providers.addic7ed.
Addic7edSubtitle
(language, hearing_impaired, page_link, series, season, episode, title, year, version, download_link)[source]¶ Addic7ed Subtitle.
-
class
subliminal.providers.addic7ed.
Addic7edProvider
(username=None, password=None)[source]¶ Addic7ed Provider.
-
_get_show_ids
(*arg, **kw)[source]¶ Get the
dict
of show ids per series by querying the shows.php page.Returns: show id per series, lower case and without quotes. Return type: dict
-
_search_show_id
(*arg, **kw)[source]¶ Search the show id from the series and year.
Parameters: Returns: the show id, if found.
Return type:
-
get_show_id
(series, year=None, country_code=None)[source]¶ Get the best matching show id for series, year and country_code.
First search in the result of
_get_show_ids()
and fallback on a search with_search_show_id()
.Parameters: Returns: the show id, if found.
Return type:
-
LegendasTv¶
-
subliminal.providers.legendastv.
type_map
= {'S': 'episode', 'M': 'movie', 'C': 'episode'}¶ Conversion map for types
-
subliminal.providers.legendastv.
season_re
= <_sre.SRE_Pattern object at 0x29353b0>¶ BR title season parsing regex
-
subliminal.providers.legendastv.
downloads_re
= <_sre.SRE_Pattern object>¶ Downloads parsing regex
-
subliminal.providers.legendastv.
rating_re
= <_sre.SRE_Pattern object>¶ Rating parsing regex
-
subliminal.providers.legendastv.
timestamp_re
= <_sre.SRE_Pattern object>¶ Timestamp parsing regex
-
subliminal.providers.legendastv.
releases_key
= 'subliminal.providers.legendastv:releases|{archive_id}'¶ Cache key for releases
-
class
subliminal.providers.legendastv.
LegendasTVArchive
(id, name, pack, featured, link, downloads=0, rating=0, timestamp=None)[source]¶ LegendasTV Archive.
Parameters: -
id
= None¶ Identifier
-
name
= None¶ Name
-
pack
= None¶ Pack
-
featured
= None¶ Featured
-
link
= None¶ Link
-
downloads
= None¶ Download count
-
rating
= None¶ Rating (0-10)
-
timestamp
= None¶ Timestamp
-
content
= None¶ Compressed content as
rarfile.RarFile
orzipfile.ZipFile
-
-
class
subliminal.providers.legendastv.
LegendasTVSubtitle
(language, type, title, year, imdb_id, season, archive, name)[source]¶ LegendasTV Subtitle.
-
class
subliminal.providers.legendastv.
LegendasTVProvider
(username=None, password=None)[source]¶ LegendasTV Provider.
Parameters: -
search_titles
(*arg, **kw)[source]¶ Search for titles matching the title.
Parameters: title (str) – the title to search for. Returns: found titles. Return type: dict
-
get_archives
(*arg, **kw)[source]¶ Get the archive list from a given title_id and language_code.
Parameters: Returns: the archives.
Return type: list of
LegendasTVArchive
-
download_archive
(archive)[source]¶ Download an archive’s
content
.Parameters: archive ( LegendasTVArchive
) – the archive to downloadcontent
of.
-
NapiProjekt¶
-
subliminal.providers.napiprojekt.
get_subhash
(hash)[source]¶ Get a second hash based on napiprojekt’s hash.
Parameters: hash (str) – napiprojekt’s hash. Returns: the subhash. Return type: str
OpenSubtitles¶
-
class
subliminal.providers.opensubtitles.
OpenSubtitlesSubtitle
(language, hearing_impaired, page_link, subtitle_id, matched_by, movie_kind, hash, movie_name, movie_release_name, movie_year, movie_imdb_id, series_season, series_episode, filename, encoding)[source]¶ OpenSubtitles Subtitle.
-
class
subliminal.providers.opensubtitles.
OpenSubtitlesProvider
(username=None, password=None)[source]¶ OpenSubtitles Provider.
Parameters:
-
exception
subliminal.providers.opensubtitles.
OpenSubtitlesError
[source]¶ Base class for non-generic
OpenSubtitlesProvider
exceptions.
Exception raised when status is ‘401 Unauthorized’.
-
exception
subliminal.providers.opensubtitles.
NoSession
[source]¶ Exception raised when status is ‘406 No session’.
-
exception
subliminal.providers.opensubtitles.
DownloadLimitReached
[source]¶ Exception raised when status is ‘407 Download limit reached’.
-
exception
subliminal.providers.opensubtitles.
InvalidImdbid
[source]¶ Exception raised when status is ‘413 Invalid ImdbID’.
-
exception
subliminal.providers.opensubtitles.
UnknownUserAgent
[source]¶ Exception raised when status is ‘414 Unknown User Agent’.
-
exception
subliminal.providers.opensubtitles.
DisabledUserAgent
[source]¶ Exception raised when status is ‘415 Disabled user agent’.
Exception raised when status is ‘503 Service Unavailable’.
-
subliminal.providers.opensubtitles.
checked
(response)[source]¶ Check a response status before returning it.
Parameters: response – a response from a XMLRPC call to OpenSubtitles. Returns: the response. Raise: OpenSubtitlesError
Podnapisi¶
Shooter¶
SubsCenter¶
-
class
subliminal.providers.subscenter.
SubsCenterSubtitle
(language, hearing_impaired, page_link, series, season, episode, title, subtitle_id, subtitle_key, downloaded, releases)[source]¶ SubsCenter Subtitle.
-
class
subliminal.providers.subscenter.
SubsCenterProvider
(username=None, password=None)[source]¶ SubsCenter Provider.
-
_search_url_titles
(*arg, **kw)[source]¶ Search the URL titles by kind for the given title.
Parameters: title (str) – title to search for. Returns: the URL titles by kind. Return type: collections.defaultdict
-
TheSubDB¶
TVsubtitles¶
-
class
subliminal.providers.tvsubtitles.
TVsubtitlesSubtitle
(language, page_link, subtitle_id, series, season, episode, year, rip, release)[source]¶ TVsubtitles Subtitle.
Refiners¶
Refiners enrich a Video
object by adding information to it.
A refiner is a simple function:
-
subliminal.refiners.
refine
(video, **kwargs)¶ Parameters: - video (
Video
) – the video to refine. - **kwargs – additional parameters for refiners.
- video (
Metadata¶
TVDB¶
Extensions¶
-
class
subliminal.extensions.
RegistrableExtensionManager
(namespace, internal_extensions, **kwargs)[source]¶ :class:~stevedore.extensions.ExtensionManager` with support for registration.
It allows loading of internal extensions without setup and registering/unregistering additional extensions.
Loading is done in this order:
- Entry point extensions
- Internal extensions
- Registered extensions
Parameters: -
registered_extensions
= None¶ Registered extensions with entry point syntax
-
internal_extensions
= None¶ Internal extensions with entry point syntax
-
subliminal.extensions.
provider_manager
= <subliminal.extensions.RegistrableExtensionManager object>¶ Provider manager
-
subliminal.extensions.
refiner_manager
= <subliminal.extensions.RegistrableExtensionManager object>¶ Refiner manager
Score¶
This module provides the default implementation of the compute_score parameter in
download_best_subtitles()
and download_best_subtitles()
.
Note
To avoid unnecessary dependency on sympy and boost subliminal’s import time, the resulting scores are hardcoded here and manually updated when the set of equations change.
Available matches:
- hash
- title
- year
- series
- season
- episode
- release_group
- format
- audio_codec
- resolution
- hearing_impaired
- video_codec
- series_imdb_id
- imdb_id
- tvdb_id
-
subliminal.score.
episode_scores
= {'hash': 359, 'format': 7, 'series': 180, 'audio_codec': 3, 'year': 90, 'hearing_impaired': 1, 'episode': 30, 'season': 30, 'video_codec': 2, 'resolution': 2, 'release_group': 15}¶ Scores for episodes
-
subliminal.score.
movie_scores
= {'hash': 119, 'hearing_impaired': 1, 'audio_codec': 3, 'title': 60, 'video_codec': 2, 'format': 7, 'year': 30, 'resolution': 2, 'release_group': 15}¶ Scores for movies
-
subliminal.score.
get_scores
(video)[source]¶ Get the scores dict for the given video.
This will return either
episode_scores
ormovie_scores
based on the type of the video.Parameters: video ( Video
) – the video to compute the score against.Returns: the scores dict. Return type: dict
-
subliminal.score.
compute_score
(subtitle, video, hearing_impaired=None)[source]¶ Compute the score of the subtitle against the video with hearing_impaired preference.
compute_score()
uses theSubtitle.get_matches
method and applies the scores (either fromepisode_scores
ormovie_scores
) after some processing.Parameters: Returns: score of the subtitle.
Return type:
Utils¶
-
subliminal.utils.
hash_opensubtitles
(video_path)[source]¶ Compute a hash using OpenSubtitles’ algorithm.
Parameters: video_path (str) – path of the video. Returns: the hash. Return type: str
-
subliminal.utils.
hash_thesubdb
(video_path)[source]¶ Compute a hash using TheSubDB’s algorithm.
Parameters: video_path (str) – path of the video. Returns: the hash. Return type: str
-
subliminal.utils.
hash_napiprojekt
(video_path)[source]¶ Compute a hash using NapiProjekt’s algorithm.
Parameters: video_path (str) – path of the video. Returns: the hash. Return type: str
-
subliminal.utils.
hash_shooter
(video_path)[source]¶ Compute a hash using Shooter’s algorithm
Parameters: video_path (string) – path of the video Returns: the hash Return type: string
-
subliminal.utils.
sanitize
(string, ignore_characters=None)[source]¶ Sanitize a string to strip special characters.
Parameters: Returns: the sanitized string.
Return type:
-
subliminal.utils.
sanitize_release_group
(string)[source]¶ Sanitize a release_group string to remove content in square brackets.
Parameters: string (str) – the release group to sanitize. Returns: the sanitized release group. Return type: str
-
subliminal.utils.
timestamp
(date)[source]¶ Get the timestamp of the date, python2/3 compatible
Parameters: date (datetime.datetime) – the utc date. Returns: the timestamp of the date. Return type: float
Cache¶
-
subliminal.cache.
SHOW_EXPIRATION_TIME
¶ Expiration time for show caching
-
subliminal.cache.
EPISODE_EXPIRATION_TIME
¶ Expiration time for episode caching
-
subliminal.cache.
REFINER_EXPIRATION_TIME
¶ Expiration time for scraper searches
-
subliminal.cache.
region
¶ The
CacheRegion
Refer to dogpile.cache’s region configuration documentation to see how to configure the region
CLI¶
Subliminal uses click to provide a powerful CLI.
-
class
subliminal.cli.
MutexLock
(filename)[source]¶ MutexLock
is a thread-based rw lock based ondogpile.core.ReadWriteMutex
.
-
class
subliminal.cli.
Config
(path)[source]¶ A
ConfigParser
wrapper to store configuration.Interaction with the configuration is done with the properties.
Parameters: path (str) – path to the configuration file. -
path
= None¶ Path to the configuration file
-
config
= None¶ The underlying configuration object
-
-
class
subliminal.cli.
AgeParamType
[source]¶ ParamType
for age strings that returns atimedelta
An age string is in the form number + identifier with possible identifiers:
w
for weeksd
for daysh
for hours
The form can be specified multiple times but only with that idenfier ordering. For example:
1w2d4h
for 1 week, 2 days and 4 hours2w
for 2 weeks3w6h
for 3 weeks and 6 hours
Exceptions¶
-
exception
subliminal.exceptions.
ConfigurationError
[source]¶ Exception raised by providers when badly configured.
-
exception
subliminal.exceptions.
AuthenticationError
[source]¶ Exception raised by providers when authentication failed.
License¶
MIT