This guide is going to explain how to add a
Provider to subliminal. You are encouraged
to take a look at the existing providers, it can be a nice base to start your own provider.
When starting a provider you should be able to answer to the following questions:
- What languages does my provider support?
- What are the language codes for the supported languages?
- Does my provider deliver subtitles for episodes? for movies?
- Does my provider require a video hash?
Each response of these questions will help you set the correct attributes for your
Not all providers deliver subtitles for
Episode. Some may require a hash.
check() method does validation against a
object and will return False if the given
Video isn’t suitable. If you’re not happy
with the default implementation, you can override it.
API keys must not be configurable by the user and must remain linked to subliminal. Hence they must be written in the provider module.
Per-user authentication is allowed and must be configured at instantiation as keyword arguments. Configuration
will be done by the user through the provider_configs argument of the
download_best_subtitles() functions. No network operation must be done during instantiation,
only configuration. Any error in the configuration must raise a
Beyond this point, if an error occurs, a generic
must be raised. You can also use more explicit exception classes
Initialization / Termination¶
Actual authentication operations must take place in the
If you need anything to be executed when the provider isn’t used anymore like logout,
To save bandwidth and improve querying time, intermediate data should be cached when possible. Typical use case is
when a query to retrieve show ids is required prior to the query to actually search for subtitles. In that case
the function that gets the show id from the show name must be cached.
Expiration time should be
SHOW_EXPIRATION_TIME for shows and
EPISODE_EXPIRATION_TIME for episodes.
To be able to handle various language codes, subliminal makes use of babelfish
Language and converters. You must set the attribute
languages with a set of
If you cannot find a suitable converter for your provider, you can make one of your own.
query() method parameters must include all aspects of provider’s querying with
Subtitle subclass must be created to represent a subtitle from the provider.
It must have relevant attributes that can be used to compute the matches of the subtitle against a
To be able to compare subtitles coming from different providers between them, the
get_matches() method must be implemented.
All possible uses of
methods must have integration tests. Use vcrpy for recording and playback
of network activity.
Other functions must be unittested. If necessary, you can use
unittest.mock to mock some functions.