A MetaMesh plugin that fetches subtitle sidecars from OpenSubtitles (REST API v1) and links them to videos. This is the network-download counterpart to subtitle-extractor, which only pulls subtitles already embedded in the media file.

Description

For each video, the plugin:

Computes the OpenSubtitles moviehash (size + first/last 64 KiB, read over WebDAV) for exact-match accuracy.
Searches /subtitles by moviehash + imdb_id/tmdb_id (+ season/episode for TV), falling back to a title/year query only when no structured identifier is available.
Picks the single best subtitle per wanted language (exact moviehash match first, then popularity).
Logs in (JWT) and downloads each chosen file, writes it via WebDAV to /files/plugin/opensubtitles/, and registers the resulting CID on the video.

Note: Runs on the background queue (external API calls, download quota). Depends on tmdb so imdbid/tmdbid are populated before it runs.

Metadata Fields (written on the video record)

Field	Format	Description
`subtitles`	csv-set of `cid`	Fetched subtitle file CIDs (external/sidecar provenance, per METADATA_KEYS.md §8)
`subtitleLanguages`	csv-set of `lang3`	Denormalized union of available subtitle languages
`languages/<lang3>`	key-set	Adds the subtitle language to the file's language set (§9)

Each downloaded subtitle is itself indexed as a first-class record under its own midhash256 CID — only the CID is stored on the video, never a path.

Migration note: subtitles / subtitleLanguages are written as legacy csv-set via addToSet to stay compatible with current consumers. They are slated to migrate to key-set (METADATA_KEYS.md §14.12) in lockstep with the other subtitle writers (subtitle, subtitle-extractor).

Dependencies

Requires file-info, filename-parser, and tmdb (for imdbid/tmdbid).

Configuration

Set at runtime via the meta-sort REST API (never in plugins.yml):

curl -k -X PUT https://metasort-dev.localhost:8180/api/plugins/opensubtitles/config \
  -H "Content-Type: application/json" \
  -d '{"apiKey":"YOUR_API_KEY","username":"YOUR_USER","password":"YOUR_PASS","languages":"en,fr"}'

Field	Type	Required	Description
`apiKey`	string	Yes	OpenSubtitles API key (Consumer key from your account)
`username`	string	For downloads	OpenSubtitles account username
`password`	string	For downloads	OpenSubtitles account password
`languages`	string	No	CSV of ISO 639-1 codes (default `en`)
`userAgent`	string	No	User-Agent registered with OpenSubtitles
`forceRecompute`	boolean	No	Re-fetch even if subs already present

The API key alone permits search; downloading requires a logged-in account (username + password → JWT). The free tier has a small daily download quota — the plugin stops early and reports when quota is exhausted.

API Endpoints

Endpoint	Method	Description
`/health`	GET	Health check
`/manifest`	GET	Plugin manifest
`/configure`	POST	Update configuration
`/process`	POST	Process a file

Docker

# From the plugin directory
docker build -t metamesh-plugin-opensubtitles:main .

Environment Variables

Variable	Default	Description
`PORT`	`8080`	HTTP server port
`WEBDAV_URL`	—	meta-sort WebDAV base (provided by the orchestrator)
`CACHE_DIR`	`/cache`	Plugin cache mount

License

MIT