initial commit

2026-06-06 15:20:36 +02:00
commit 62a2b796e2
16 changed files with 2001 additions and 0 deletions
@@ -0,0 +1,94 @@
+# 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