README
¶
osubs
Library to search subtitles from opensubtitles.org
Caveats
- This library requires Go 1.26
- This library provides a high-level, ergonomic API for searching and retrieving subtitles (only from movies) and related metadata from
opensubtitles.org.
Insstallation
go get -u github.com/javiorfo/osubs@latest
Example
package main
import (
"log"
"github.com/javiorfo/osubs"
"github.com/javiorfo/osubs/lang"
"github.com/javiorfo/osubs/order"
)
func main() {
resp, err := osubs.Search("godfather", osubs.Language(lang.Spanish, lang.SpanishLA), osubs.Year(1972))
if err != nil {
log.Fatal(err)
}
processResponse(resp)
resp, err = osubs.Search("pulp fiction", osubs.Language(lang.French, lang.German))
if err != nil {
log.Fatal(err)
}
processResponse(resp)
resp, err = osubs.Search("terminator", osubs.Order(order.Downloads))
if err != nil {
log.Fatal(err)
}
processResponse(resp)
}
func processResponse(r osubs.Response) {
switch s := r.(type) {
case osubs.Result[osubs.Subtitle]:
for sub := range s.Items {
log.Printf("%+v\n", sub)
}
case osubs.Result[osubs.Movie]:
for movie := range s.Items {
log.Printf("%+v\n", movie)
}
s.Items.First().Consume(func(m osubs.Movie) {
resp, err := m.SearchSubtitles()
if err != nil {
log.Fatal(err)
}
processResponse(resp)
})
default:
log.Println("no results")
}
}
Details
- Searching subtitles from
opensubtitles.orgcould return a list of movies or a list of subtitles of the movie searched (if the text and filter are more exactly). For that matter Response is a sealed interface
Donate
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Language ¶
Language sets one or more languages to filter by. If no languages are provided, the filter remains unchanged.
Types ¶
type Movie ¶
type Movie struct {
// ID is the unique identifier for the movie on the provider's database.
ID uint
// Name is the official title of the movie and year of release.
Name string
// contains filtered or unexported fields
}
Movie represents a cinematic title and its associated metadata. It contains a filter to refine subtitle searches specifically for this title.
func (Movie) SearchSubtitles ¶
SearchSubtitles performs a remote request to find subtitles matching the movie's ID and the configured filter criteria (language, year, and sort order).
It returns a Result containing a slice of Subtitle objects or an error if the network request or parsing fails.
type Page ¶
type Page struct {
// The starting index of the current page.
From int
// The ending index of the current page.
To int
// The Total number of items available.
Total int
}
Page represents the pagination info.
type Response ¶
type Response interface {
// contains filtered or unexported methods
}
Response is a sealed interface used to categorize internal search results.
type Result ¶
type Result[T any] struct { // Page contains metadata about the current position and total results. Page Page // Items is stream iterator of data retrieved for the current page. Items steams.It[T] // contains filtered or unexported fields }
Result holds a paginated collection of items of type T. It maintains the internal state required to fetch subsequent pages from the source.
func (*Result[T]) Iter ¶
Iter returns a stream-compatible iterator (steams.It2) that yields the current Result and all subsequent pages.
This allows for clean iteration over all available search results using a range-like functional approach.
type Subtitle ¶
type Subtitle struct {
// ID is the unique identifier for the subtitle on the remote provider.
ID uint
// MovieTitle is the name of the film or show associated with this subtitle and the year of release.
MovieTitle string
// Description provides optional context or version details (e.g., "Godfather.1080p.DVD").
Description nilo.Option[string]
// Language is the subtitle language.
Language string
// Cd indicates disc information for multi-part releases (e.g., "CD1").
Cd string
// Uploaded is the date when the subtitle file was first provided.
Uploaded string
// Downloads tracks the popularity of this specific subtitle entry.
Downloads int
// Format is the file extension (e.g., "srt", "sub").
Format string
// Rating represents the community-assigned quality score.
Rating float32
// Uploader is the username of the community member who provided the file.
Uploader nilo.Option[string]
// DownloadLink is the direct URL used to fetch the subtitle archive.
DownloadLink string
}
Subtitle represents the metadata and download information for a specific subtitle file.
func (Subtitle) Download ¶
Download fetches the subtitle archive from the remote server, extracts the relevant file matching the Subtitle's format, and saves it to the specified path.
The resulting file is named using the MovieTitle and Format fields. The download link points to a ZIP archive, this method automatically iterates through the archive to find and extract the correct file.
Source Files
Directories
