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']