Subliminal¶
Release v0.7.5
Subliminal is a python library to search and download subtitles. It comes with an easy to use CLI suitable for direct use or cron jobs.
Providers¶
Subliminal uses multiple providers to give users a vast choice and have a better chance to find the best matching subtitles. Providers are extensible through a dedicated entry point.
- Addic7ed
- OpenSubtitles
- Podnapisi
- TheSubDB
- TvSubtitles
Usage¶
CLI¶
Download english subtitles:
$ subliminal -l en -- The.Big.Bang.Theory.S05E18.HDTV.x264-LOL.mp4
1 subtitle downloaded
See subliminal.cli
Library¶
Download best subtitles in French and English for videos less than one week old in a video folder, skipping videos that already have subtitles whether they are embedded or not:
from babelfish import Language
from datetime import timedelta
import subliminal
# configure the cache
subliminal.cache_region.configure('dogpile.cache.dbm', arguments={'filename': '/path/to/cachefile.dbm'})
# scan for videos in the folder and their subtitles
videos = subliminal.scan_videos(['/path/to/video/folder'], subtitles=True, embedded_subtitles=True, age=timedelta(weeks=1))
# download
subliminal.download_best_subtitles(videos, {Language('eng'), Language('fra')}, age=timedelta(week=1))
See subliminal.api
, scan_videos()
and scan_video()
How it works¶
Subliminal makes use of various libraries to achieve its goal:
- enzyme to detect embedded subtitles in videos and retrieve metadata
- guessit to guess informations from filenames
- babelfish to work with languages
- requests to make human readable HTTP requests
- BeautifulSoup to parse HTML and XML
- dogpile.cache to cache intermediate search data
- charade to detect subtitles’ encoding
- pysrt to validate downloaded subtitles
License¶
MIT
Documentation¶
API Documentation¶
If you are looking for information on a specific function, class or method, this part of the documentation is for you.
Changelog¶
0.7.5¶
release date: 2015-03-04
- Update requirements
- Remove BierDopje provider
- Add pre-guessed video optional argument in scan_video
- Improve hearing impaired support
- Fix TVSubtitles and Podnapisi providers
0.7.3¶
release date: 2013-11-22
- Fix windows compatibility
- Improve subtitle validation
- Improve embedded subtitle languages detection
- Improve unittests
0.7.2¶
release date: 2013-11-10
- Fix TVSubtitles for ambiguous series
- Add a CACHE_VERSION to force cache reloading on version change
- Set CLI default cache expiration time to 30 days
- Add podnapisi provider
- Support script for languages e.g. Latn, Cyrl
- Improve logging levels
- Fix subtitle validation in some rare cases
0.7.1¶
release date: 2013-11-06
- Improve CLI
- Add login support for Addic7ed
- Remove lxml dependency
- Many fixes
0.7.0¶
release date: 2013-10-29
WARNING: Complete rewrite of subliminal with backward incompatible changes
- Use enzyme to parse metadata of videos
- Use babelfish to handle languages
- Use dogpile.cache for caching
- Use charade to detect subtitle encoding
- Use pysrt for subtitle validation
- Use entry points for subtitle providers
- New subtitle score computation
- Hearing impaired subtitles support
- Drop async support
- Drop a few providers
- And much more...
0.6.2¶
release date: 2012-09-15
- Fix BierDopje
- Fix Addic7ed
- Fix SubsWiki
- Fix missing enzyme import
- Add Catalan and Galician languages to Addic7ed
- Add possible services in help message of the CLI
- Allow existing filenames to be passed without the ./ prefix
0.6.1¶
release date: 2012-06-24
- Fix subtitle release name in BierDopje
- Fix subtitles being downloaded multiple times
- Add Chinese support to TvSubtitles
- Fix encoding issues
- Fix single download subtitles without the force option
- Add Spanish (Latin America) exception to Addic7ed
- Fix group_by_video when a list entry has None as subtitles
- Add support for Galician language in Subtitulos
- Add an integrity check after subtitles download for Addic7ed
- Add error handling for if not strict in Language
- Fix TheSubDB hash method to return None if the file is too small
- Fix guessit.Language in Video.scan
- Fix language detection of subtitles
0.6.0¶
release date: 2012-06-16 WARNING: Backward incompatible changes
- Fix –workers option in CLI
- Use a dedicated module for languages
- Use beautifulsoup4
- Improve return types
- Add scan_filter option
- Add –age option in CLI
- Add TvSubtitles service
- Add Addic7ed service
0.5¶
release date: 2012-03-25 WARNING: Backward incompatible changes
- Use more unicode
- New list_subtitles and download_subtitles methods
- New Pool object for asynchronous work
- Improve sort algorithm
- Better error handling
- Make sorting customizable
- Remove class Subliminal
- Remove permissions handling
0.3¶
release date: 2011-08-18
- Fix a bug when series is not guessed by guessit
- Fix dependencies failure when installing package
- Fix encoding issues with logging
- Add a script to ease subtitles download
- Add possibility to choose mode of created files
- Add more checks before adjusting permissions
0.2¶
release date: 2011-07-11
- Fix plugin configuration
- Fix some encoding issues
- Remove extra logging