OpenSubtitles Pet

Search and download movie and TV show subtitles from the OpenSubtitles.com database.

Features

• Search Subtitles - Find subtitles by title, IMDB ID, TMDB ID, or other criteria
• Download Files - Download subtitle files directly to your local machine
• Multi-Language Support - Search and download subtitles in any language
• TV Show Support - Search by season and episode numbers
• File Management - Organize downloads with custom directories
• Authentication - Secure login with credential caching

Setup

1. Get an API Key

Sign up for a free API key at OpenSubtitles Consumers.

2. Create OpenSubtitles Account (for downloads)

To download subtitles, you need a free account at OpenSubtitles.com.

3. Configure Environment Variables

Copy .env.example to .env and fill in your credentials:

cp .env.example .env

Edit .env:

# REQUIRED: API key
OPENSUBTITLES_API_KEY=your_api_key_here

# REQUIRED FOR DOWNLOADS: Account credentials
OPENSUBTITLES_USERNAME=your_username
OPENSUBTITLES_PASSWORD=your_password

# OPTIONAL: Custom download directory (default: ./subtitles)
# OPENSUBTITLES_DOWNLOAD_PATH=./subtitles

4. Install Dependencies

bun install

Usage

Test Connection

opencode run "test opensubtitles connection"

Search for Subtitles

By movie title:

opencode run "search opensubtitles for The Matrix"
opencode run "search opensubtitles for Inception in English and Spanish"

By IMDB ID:

opencode run "search opensubtitles for IMDB ID tt0133093"

By TV show:

opencode run "search opensubtitles for Breaking Bad season 1 episode 1"
opencode run "search opensubtitles for Game of Thrones S05E08 in French"

With filters:

opencode run "search opensubtitles for Avatar year 2009 type movie"

Download Subtitles

After searching, use the file_id from the results to download:

opencode run "download opensubtitles file ID 12345"
opencode run "download opensubtitles file ID 12345 to movies/inception subdirectory"

Get Supported Languages

opencode run "get opensubtitles supported languages"

Available Tools

| Tool | Description | |------|-------------| | opensubtitles-test-connection | Test API connection and show configuration status | | opensubtitles-search | Search for subtitles with various filters | | opensubtitles-download | Download subtitle file to local machine | | opensubtitles-login | Authenticate to enable downloads | | opensubtitles-get-subtitle-details | Get detailed info about a specific subtitle | | opensubtitles-get-languages | List all supported language codes |

Search Parameters

The opensubtitles-search tool supports:

| Parameter | Type | Description | |-----------|------|-------------| | query | string | Search text (movie/show title) | | imdb_id | string | IMDB ID (e.g., "tt0133093") | | tmdb_id | string | TMDB ID for movies/shows | | languages | string | Comma-separated language codes (e.g., "en,es,fr") | | type | enum | Filter by "movie", "episode", or "all" | | season_number | number | Season number for TV shows | | episode_number | number | Episode number for TV shows | | year | number | Release year | | limit | number | Max results (1-100, default: 10) |

Language Codes

Common language codes for the languages parameter:

| Code | Language | |------|----------| | en | English | | es | Spanish | | fr | French | | de | German | | it | Italian | | pt | Portuguese | | ru | Russian | | ja | Japanese | | ko | Korean | | zh | Chinese | | ar | Arabic |

For a complete list, run: opencode run "get opensubtitles supported languages"

Download Management

Default Location

Subtitles are saved to ./subtitles/ by default.

Custom Directory

Set the download path in your .env:

OPENSUBTITLES_DOWNLOAD_PATH=/Users/you/Movies/Subtitles

Organizing Downloads

Use subdirectories to organize your downloads:

opencode run "download opensubtitles file ID 12345 to movies/matrix subdirectory"
opencode run "download opensubtitles file ID 67890 to tv/breaking-bad/s01 subdirectory"

This creates:

./subtitles/
├── movies/
│   └── matrix/
│       └── The.Matrix.1999.srt
└── tv/
    └── breaking-bad/
        └── s01/
            └── Breaking.Bad.S01E01.srt

Examples

Example 1: Search and Download Movie Subtitles

# Search for The Matrix in English
opencode run "search opensubtitles for The Matrix in English"

# Response includes file_id: 5588033

# Download the subtitle
opencode run "download opensubtitles file ID 5588033"

Example 2: TV Show with Season/Episode

# Search for specific episode
opencode run "search opensubtitles for Breaking Bad season 1 episode 1 in English"

# Download to organized directory
opencode run "download opensubtitles file ID 1234567 to tv/breaking-bad/s01 subdirectory"

Example 3: Multi-Language Search

# Search in multiple languages
opencode run "search opensubtitles for Parasite in English, Spanish, and Korean"

# Result shows subtitles in all three languages
# Download specific ones by file_id

Example 4: IMDB Search

# Search by IMDB ID (more accurate than title)
opencode run "search opensubtitles for IMDB ID tt1375666"

# Inception (2010) results with file_id
opencode run "download opensubtitles file ID 9876543"

Authentication

Automatic Login

The pet automatically logs you in when you use download features. Your credentials are:

• Read from OPENSUBTITLES_USERNAME and OPENSUBTITLES_PASSWORD
• Cached for 24 hours to avoid repeated logins
• Used to generate bearer tokens for authenticated requests

Manual Login

You can manually trigger login to test credentials:

opencode run "login to opensubtitles"

Rate Limits

OpenSubtitles has rate limits on downloads:

• Free accounts: 20 downloads per day
• VIP accounts: Higher limits

The download response includes remaining_downloads and reset_time.

Troubleshooting

"API key not configured"

Set OPENSUBTITLES_API_KEY in your .env file.

"USERNAME and PASSWORD required for login"

Downloads require authentication. Set OPENSUBTITLES_USERNAME and OPENSUBTITLES_PASSWORD.

"No results found"

Try:

• Use IMDB ID instead of title (more accurate)
• Check spelling of movie/show name
• Try different language codes
• Verify the content exists on OpenSubtitles.com

"Download failed"

Check:

• You haven't exceeded daily download limit
• File ID is correct from search results
• You're logged in (credentials are set)

API Documentation

For more details on the OpenSubtitles API:

• API Documentation
• Consumer Registration

Development

Testing Locally

cd pets/opensubtitles
opencode run "test opensubtitles connection" --print-logs

Validation

pets validate

Publishing

pets publish --preview  # Dry-run first
pets publish           # Publish to npm

License

MIT