Open Subtitles API

Unofficial implementation of the Open Subtitles API.

Note: This package is based on the beta release of the OpenSubtitles REST API.

Installing

You can install this package by entering the following command into your Package Manager Console:

Install-Package MovieCollection.OpenSubtitles -PreRelease

Configuration

First, define an instance of the HttpClient class if you haven't already.

// HttpClient is intended to be instantiated once per application, rather than per-use.
// See https://docs.microsoft.com/en-us/dotnet/api/system.net.http.httpclient
private static readonly HttpClient httpClient = new HttpClient();

Then, you need to set your api key and user-agent.

// using System.Net.Http.Headers;
// using MovieCollection.OpenSubtitles;

var options = new OpenSubtitlesOptions
{
    ApiKey = "your-api-key",
    ProductInformation = new ProductHeaderValue("your-app-name", "your-app-version"),
};

var service = new OpenSubtitlesService(httpClient, options);

Alternatively, you can set the user-agent via HttpClient's default request headers.

// using System.Net.Http.Headers;

var product = new ProductInfoHeaderValue("your-app-name", "your-app-version");
httpClient.DefaultRequestHeaders.UserAgent.Add(product);

Searching for subtitles

You can search for subtitles via SearchSubtitles method.

var search = new NewSubtitleSearch
{
    ImdbId = 11204094,
};

var result = await service.SearchSubtitlesAsync(search);

You can also search by the movie name and year.

var search = new NewSubtitleSearch
{
    Query = "Iron Man",
    Year = 2008,
};

You can also specify season and episode number.

var search = new NewSubtitleSearch
{
    Query = "Rick and Morty",
    SeasonNumber = 5,
    EpisodeNumber = 10,
};

You can also search by movie file hash.

string filePath = "D:\\path-to-file\\";

var search = new NewSubtitleSearch
{
    // For best results with automatic searching based on file analysis,
    // send the file name as a query together with the moviehash.
    Query = Path.GetFileName(filePath),

    // Open Subtitles is using a special hash function to match subtitle files against movie files.
    // Hash is not dependent on file name of movie file.
    MovieHash = OpenSubtitlesHasher.GetFileHash(filePath),
};

Please check out the demo project for more examples.

Notes

Thanks to Open Subtitles for providing free API services.
Please read Open Subtitles terms of use before using their API.

License

This project is licensed under the MIT License.

moviecollection / open-subtitles