API

subliminal.api.provider_manager

ExtensionManager based on the entry point subliminal.providers

class subliminal.api.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

manager = None

Dedicated provider_manager as EnabledExtensionManager

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, scores=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.
  • scores (dict) – scores to use, if None, the scores from the video are used.
Returns:

downloaded subtitles.

Return type:

list of Subtitle

terminate()[source]

Terminate all the initialized_providers.

subliminal.api.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.api.list_subtitles(videos, languages, **kwargs)[source]

List subtitles.

The videos must pass the languages check of check_video().

All other parameters are passed onwards to the ProviderPool constructor.

Parameters:
  • videos (set of Video) – videos to list subtitles for.
  • languages (set of Language) – languages to search for.
Returns:

found subtitles per video.

Return type:

dict of Video to list of Subtitle

subliminal.api.download_subtitles(subtitles, **kwargs)[source]

Download content of subtitles.

All other parameters are passed onwards to the ProviderPool constructor.

Parameters:subtitles (list of Subtitle) – subtitles to download.
subliminal.api.download_best_subtitles(videos, languages, min_score=0, hearing_impaired=False, only_one=False, scores=None, **kwargs)[source]

List and download the best matching subtitles.

The videos must pass the languages and undefined (only_one) checks of check_video().

All other parameters are passed onwards to the ProviderPool constructor.

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.
  • scores (dict) – scores to use, if None, the scores from the video are used.
Returns:

downloaded subtitles per video.

Return type:

dict of Video to list of Subtitle

subliminal.api.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