Subliminal

Release v0.6.2

Subliminal is a python library to search and download subtitles.

It uses video hashes and the powerful guessit library that extracts informations from filenames or filepaths to ensure you have the best subtitles. It also relies on enzyme to detect embedded subtitles and avoid duplicates.

Features

Multiple subtitles services are available:

• Addic7ed
• BierDopje
• OpenSubtitles
• SubsWiki
• Subtitulos
• TheSubDB
• TvSubtitles

You can use main subliminal’s functions with a file path, a file name or a folder path.

CLI

Download english subtitles:

$ subliminal -l en The.Big.Bang.Theory.S05E18.HDTV.x264-LOL.mp4
**************************************************
Downloaded 1 subtitle(s) for 1 video(s)
The.Big.Bang.Theory.S05E18.HDTV.x264-LOL.srt from opensubtitles
**************************************************

Module

List english subtitles:

>>> subliminal.list_subtitles('The.Big.Bang.Theory.S05E18.HDTV.x264-LOL.mp4', ['en'])

Multi-threaded use

Use 4 workers to achieve the same result:

>>> with subliminal.Pool(4) as p:
...     p.list_subtitles('The.Big.Bang.Theory.S05E18.HDTV.x264-LOL.mp4', ['en'])

User Guide

This part of the documentation details how to use subliminal for most common tasks

• Basics
  • Services
  • Languages
  • Paths
• CLI
  • Usage
  • Cron job
• Simple module use
• Multi-threaded module use

Developer Guide

This part of the documentation explains internal behavior of subliminal and its algorithms

• Services
• Languages
• Tasks
• Asynchronous
• Core
• Other objects
  • Video
  • Subtitle
  • Utilities
  • Exceptions

API Documentation

Most common subliminal features are listed here

subliminal.list_subtitles(paths, languages=None, services=None, force=True, multi=False, cache_dir=None, max_depth=3, scan_filter=None)

List subtitles in given paths according to the criteria

Parameters:

• paths (unicode or list of unicode) – path(s) to video file or folder
• languages (list of Language or string) – languages to search for, in preferred order
• services (list) – services to use for the search, in preferred order
• force (bool) – force searching for subtitles even if some are detected
• multi (bool) – search multiple languages for the same video
• cache_dir (string) – path to the cache directory to use
• max_depth (int) – maximum depth for scanning entries
• scan_filter (function) – filter function that takes a path as argument and returns a boolean indicating whether it has to be filtered out (True) or not (False)

Returns:

found subtitles

Return type:

dict of Video => [ResultSubtitle]

subliminal.download_subtitles(paths, languages=None, services=None, force=True, multi=False, cache_dir=None, max_depth=3, scan_filter=None, order=None)

Download subtitles in given paths according to the criteria

Parameters:

• paths (unicode or list of unicode) – path(s) to video file or folder
• languages (list of Language or string) – languages to search for, in preferred order
• services (list) – services to use for the search, in preferred order
• force (bool) – force searching for subtitles even if some are detected
• multi (bool) – search multiple languages for the same video
• cache_dir (string) – path to the cache directory to use
• max_depth (int) – maximum depth for scanning entries
• scan_filter (function) – filter function that takes a path as argument and returns a boolean indicating whether it has to be filtered out (True) or not (False)
• order – preferred order for subtitles sorting

Returns:

downloaded subtitles

Return type:

dict of Video => [ResultSubtitle]

Note

If you use multi=True, LANGUAGE_INDEX has to be the first item of the order list or you might get unexpected results.

class subliminal.Pool(size)

Pool of workers

Pool.collect()

Collect available results

Returns:results of tasks Return type:list of Task

Pool.consume_task_list(tasks)

Consume the given list of tasks, multi-threaded mode.

Parameters:tasks (list of ListTask or DownloadTask) – the list of tasks to consume Returns:resulting subtitles (either list of subtitles to download or downloaded subtitles, depending on the tasks type Return type:dict of Video => [ResultSubtitle]

Pool.download_subtitles(paths, languages=None, services=None, force=True, multi=False, cache_dir=None, max_depth=3, scan_filter=None, order=None)

See subliminal.download_subtitles()

Pool.join()

Join the task queue

Pool.list_subtitles(paths, languages=None, services=None, force=True, multi=False, cache_dir=None, max_depth=3, scan_filter=None)

See subliminal.list_subtitles()

Pool.start()

Start workers

Pool.stop()

Stop workers