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.
-
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
-
terminate
()[source]¶ Terminate all the
initialized_providers
.
-
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
-
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.
-
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.
-
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
-
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.
-
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
-
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