Crate opensubs

Crate opensubs 

Source
Expand description

§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

§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.