opensubtitles-api

OpenSubtitles.org api wrapper for downloading and uploading subtitles.

Based on Promises and thus working asynchronously (thanks to Bluebird), this module uses XML-RPC (thanks to xmlrpc) to communicate with OpenSubtitles using Node.js

In addition of allowing to use all available methodCalls asynchronously, it also allows you to directly use powerfull custom calls, like:

search: Chained function returning the best matching subtitles based on the information you can feed it.
upload: Chained function requiring only the path to the video and to the subtitle files to send new subtitles to OpenSubtitles.org (flow: LogIn > TryUploadSubtitles > UploadSubtitles)
extractInfo: Function returning Hash and Byte size for a given video

More complete docs are available. This module requires a valid UserAgent.

Quick start

npm install opensubtitles-api

Then:

var OS = require('opensubtitles-api');
var OpenSubtitles = new OS('UserAgent', 'Username', 'Password');

You can omit username and password to use OpenSubtitles.org anonymously (not all methods are available)

NOTE: 'Password' can be a MD5 encrypted string, OpenSubtitles accept these. It is recommended to use it. You can get the MD5 of a PASSWORD string by doing: require('crypto').createHash('md5').update(PASSWORD).digest('hex');

Examples:

A simple login:

OpenSubtitles.login()
    .then(function(response){
        console.log(response);
    })
    .catch(function(err){
        console.log(err);
    });

If successful, will return:

Object {
    token: "8qnesekc42g8kj1d58i6fonm61"
    status: "200 OK"
    seconds: 0.031
}

NOTE: The login() call is useful to verify "Username" and "Password" (if you get a token, you're authentified, as simple as that), but is never needed for the custom calls (search, upload), they're made by the module itself. If you use raw xml-rpc call (OpenSubtitles.api.methodCall), prefer to login with the raw OpenSubtitles.api.LogIn

Get in touch with OpenSubtitles.org API directly:

var OS = require('opensubtitles-api');
var OpenSubtitles = new OS('UserAgent');

OpenSubtitles.api.LogIn('username', 'password', 'en', 'UserAgent')
    .then( // do stuff...

NOTE: All methods should be supported. You can consult ./lib/opensubtitles.js for the list of available calls and the required parameters.

Search the best subtitles in all languages for a given movie/episode:

OpenSubtitles.search({
    sublanguageid: 'fr',        // Can be an array.join, 'all', or be omitted.
    hash: '8e245d9679d31e12',   // Size + 64bit checksum of the first and last 64k
    filesize: '129994823',      // Total size, in bytes.
    path: 'foo/bar.mp4',        // Complete path to the video file, it allows
                                //   to automatically calculate 'hash'.
    filename: 'bar.mp4',        // The video file name. Better if extension
                                //   is included.
    season: '2',
    episode: '3',
    extensions: ['srt', 'vtt'],  // Accepted extensions, defaults to 'srt'.
    imdbid: '528809',           // 'tt528809' is fine too.
    fps: '23.96',               // Number of frames per sec in the video.
    query: 'Charlie Chaplin',   // Text-based query, this is not recommended.
}).then(function (subtitles) {
    // an array of objects, no duplicates (ordered by
    // matching + uploader, with total downloads as fallback)
});

Example output:

Object {
    ar: "http://dl.opensubtitles.org/download/subtitle_file_id.srt"
    en: "http://dl.opensubtitles.org/download/subtitle_file_id.srt"
    fr: "http://dl.opensubtitles.org/download/subtitle_file_id.srt"
    po: "http://dl.opensubtitles.org/download/subtitle_file_id.srt"
    ru: "http://dl.opensubtitles.org/download/subtitle_file_id.srt"
}

NOTE: No parameter is mandatory, but at least one is required. The more possibilities you add, the best is your chance to get the best matching subtitles in a large variation of languages. I don't recommend ever using "query", as it is highly error-prone.

Here's how the function prioritize:

Hash + filesize (or Path, that will be used to calculate hash and filesize)
Filename
IMDBid (+ Season and Episode for TV Series)

The function internally ranks the subtitles to get the best match given the info you provided. It works like this:

matched by 'hash' and uploaded by:
    + admin|trusted     12
    + platinum|gold     11
    + user|anon         8

matched by tag and uploaded by:
    + admin|trusted     11
    + platinum|gold     10
    + user|anon         7

matched by imdb and uploaded by:
    + admin|trusted     9
    + platinum|gold     8
    + user|anon         5

matched by other and uploaded by:
    + admin|trusted     4
    + platinum|gold     3
    + user|anon         0

bonus of fps matching if:
    + nothing matches   2
    + imdb matches      0.5

Upload a subtitle:

OpenSubtitles.upload({
        path: '/home/user/video.avi',       // path to video file
        subpath: '/home/user/video.srt'     // path to subtitle
    })
    .then(function(response){
        console.log(response);
    })
    .catch(function(err){
        console.log(err);
    });

Example output (if successfully uploaded):

Object {
    status: '200 OK'
    data: 'http://www.opensubtitles.org/subtitles/123456' //absolute link to subtitles
    seconds: '1.171'
}

NOTE: Only path and subpath are mandatory. However, it is highly recommended to also provide imdbid to make sure you can add a subtitle even if the movie isn't already in the database.

Optionnal parameters are self-explanatory:

sublanguageid
highdefinition
hearingimpaired
moviereleasename
movieaka
moviefps
movieframes
movietimems
automatictranslation
subauthorcomment

Extract Hash & MovieByteSize

OpenSubtitles.extractInfo('path/to/file.mp4')
    .then(function (infos) {
        console.log(infos);
    });