95 lines
3.7 KiB
Markdown
95 lines
3.7 KiB
Markdown
# MetaMesh Plugin: OpenSubtitles
|
|
|
|
A MetaMesh plugin that **fetches** subtitle sidecars from
|
|
[OpenSubtitles](https://www.opensubtitles.com) (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:
|
|
|
|
1. Computes the OpenSubtitles **moviehash** (size + first/last 64 KiB, read over
|
|
WebDAV) for exact-match accuracy.
|
|
2. 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.
|
|
3. Picks the single best subtitle per wanted language (exact moviehash match
|
|
first, then popularity).
|
|
4. 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`):
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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
|