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 (list) – name of providers to use, if not all.
  • provider_configs (dict) – provider configuration as keyword arguments per provider name to pass when instanciating the Provider.
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:
  • provider (str) – name of the provider.
  • video (Video) – video to list subtitles for.
  • languages (set of Language) – languages to search for.
Returns:

found subtitles.

Return type:

list of Subtitle or None

list_subtitles(video, languages)[source]

List subtitles.

Parameters:
  • video (Video) – video to list subtitles for.
  • languages (set of Language) – languages to search for.
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

terminate()[source]

Terminate all the initialized_providers.

class subliminal.core.AsyncProviderPool(max_workers=None, *args, **kwargs)[source]

Subclass of ProviderPool with asynchronous support for list_subtitles().

Parameters:max_workers (int) – maximum number of threads to use. If None, max_workers will be set to the number of providers.
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:

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:

bool

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:
  • path (str) – path to the video.
  • directory (str) – directory to search for subtitles.
Returns:

found subtitles with their languages.

Return type:

dict

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:
  • video (Video) – the video to refine.
  • episode_refiners (tuple) – refiners to use for episodes.
  • movie_refiners (tuple) – refiners to use for movies.
  • **kwargs – additional parameters for the refine() functions.
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:

dict of Video to list of Subtitle

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:

dict of Video to list of Subtitle

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