Crate opensubs

A library to search subtitles from opensubtitles.org

This crate provides a high-level, ergonomic API for searching and retrieving subtitles and related metadata from opensubtitles.org. It offers both asynchronous and blocking (synchronous) interfaces, with flexible filtering and ordering options.

Features

• Search for subtitles using various criteria (language, filters, ordering, etc.).
• Retrieve detailed information about movies and subtitles.
• Both async and blocking APIs (enable via crate features).
• Strong error handling with Error and Result types.

Async Example (default)

use opensubs::{Filters, Language, OrderBy, SearchBy};

#[tokio::main]
async fn main() -> opensubs::Result {
    // async search movie "holdovers", spanish subs, order by rating
    let results = opensubs::search(SearchBy::MovieAndFilter(
        "holdovers",
        Filters::default()
            .languages(&[Language::Spanish])
            .order_by(OrderBy::Rating)
            .build(),
    ))
    .await?;

    println!("Subtitles {results:#?}");

    Ok(())
}

Blocking Example (feature “blocking”)

use opensubs::{Filters, Language, OrderBy, Response, SearchBy};

fn main() -> opensubs::Result {
    // blocking search movie "the godfather"
    // year 1972, french and german subs, order by rating
    let results = opensubs::blocking::search(SearchBy::MovieAndFilter(
        "the godfather",
        Filters::default()
            .year(1972)
            .languages(&[Language::French, Language::German])
            .order_by(OrderBy::Downloads)
            .build(),
    ))?;

    match results {
        Response::Movie(movies) => {
            // If results is Movie type, get the subtitles_link property
            // and find subtitles for it
            if let Some(movie) = movies.first() {
                let subs = opensubs::blocking::search(SearchBy::Url(&movie.subtitles_link))?;
                println!("Subtitles {subs:#?}");
            }
        }
        // else print the subtitles
        _ => println!("Subtitles {results:#?}"),
    }

    Ok(())
}

Modules & Re-exports

• [client] — Search options, filters, and search implementations.
• [core] — Core types, response parsing, and subtitle/movie models.
• Page, Response, Movie, Subtitle — Main data structures for results.
• Filters, Language, OrderBy, SearchBy — Search configuration types.

Error Handling

All fallible operations return Result<T> with a custom Error enum that wraps errors from underlying dependencies (e.g., reqwest, scraper).

Feature Flags

• async — Enables the asynchronous API (search).
• blocking — Enables the blocking (synchronous) API (blocking::search).

License

This is free software, published under the MIT License.

See Also

• reqwest — HTTP client for requests.
• scraper — HTML parsing for subtitle extraction.

Structs

Filters

Builder for constructing a [Filter] with custom parameters.

Movie

Represents a movie with an associated subtitles search link.

Page

Represents pagination information for search results.

Subtitle

Represents a subtitle entry with metadata and download information.

Enums

Error

Error type for all fallible operations in this crate.

Language

Represents all supported subtitle languages.

OrderBy

Response

Represents a parsed response from a search page.

SearchBy

This enum allows you to search by a direct URL, by movie name, or by movie name with additional filters.

Functions

search

Performs a search using the provided SearchBy criteria, handling manual HTTP redirections.

Type Aliases

Result

A convenient alias for Result with the crate’s Error type.