initial commit

2026-01-18 00:24:14 +01:00
commit 678af9f9bf
11 changed files with 1120 additions and 0 deletions
@@ -0,0 +1,158 @@
+# MetaMesh Plugin: Subtitle Extractor
+
+Extracts embedded subtitles from video files and saves them as standalone text files. The extracted subtitles are republished in the MetaMesh pipeline and linked to the original video via CID.
+
+## Features
+
+- **Automatic extraction**: Extracts all text-based subtitle tracks from video files
+- **Multiple formats**: Supports SRT, ASS, SSA, WebVTT, and MOV_TEXT codecs
+- **Smart filtering**: Automatically skips image-based subtitles (PGS, DVD, DVB) that cannot be converted to text
+- **Language preservation**: Maintains language metadata from video streams
+- **Pipeline integration**: Extracted files are saved to `/output` and automatically picked up by meta-sort
+- **CID linking**: Stores subtitle CIDs as metadata on the source video
+
+## Dependencies
+
+This plugin requires the following plugins to run first:
+- `file-info` - Determines file type
+- `ffmpeg` - Provides subtitle stream information
+
+## Installation
+
+### Build from source
+
+```bash
+cd packages/plugins/metamesh-plugin-subtitle-extractor
+npm install
+npm run build
+```
+
+### Build Docker image
+
+```bash
+docker build -t metamesh-plugin-subtitle-extractor:main .
+```
+
+### Configure in plugins.yml
+
+Add to `dev/plugins.yml`:
+
+```yaml
+plugins:
+  subtitle-extractor:
+    enabled: true
+    image: metamesh-plugin-subtitle-extractor:main
+    instances: 1
+    resources:
+      memory: 256m
+      cpus: 0.5
+```
+
+## Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `forceRecompute` | boolean | `false` | Re-extract subtitles even if already processed |
+| `outputFormat` | select | `srt` | Output format: `srt`, `vtt`, or `ass` |
+
+## Output
+
+### Extracted Files
+
+Subtitle files are saved to `/output` with the naming pattern:
+
+```
+{Title} ({Year})[{VideoCID}]_subtitle.{lang}.{ext}
+```
+
+Example: `Sintel (2010)[bafk...abc]_subtitle.eng.srt`
+
+### Metadata
+
+The plugin stores the following metadata on the source video:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `extractedSubtitles` | array | CIDs of extracted subtitle files |
+| `subtitleLanguages` | array | Language codes of extracted subtitles |
+
+## Supported Codecs
+
+### Text-based (supported)
+- `subrip` / `srt` - SubRip
+- `ass` - Advanced SubStation Alpha
+- `ssa` - SubStation Alpha
+- `webvtt` - WebVTT
+- `mov_text` - QuickTime text
+
+### Image-based (skipped)
+- `hdmv_pgs_subtitle` - Blu-ray PGS
+- `dvd_subtitle` - DVD VOB
+- `dvb_subtitle` - DVB
+- `xsub` - DivX XSUB
+
+## Architecture
+
+```
+Video File (MKV/MP4/AVI)
+        │
+        ▼
+┌───────────────────┐
+│ ffmpeg plugin     │  ← Provides stream info
+└───────────────────┘
+        │
+        ▼
+┌───────────────────┐
+│ subtitle-extractor│
+│                   │
+│  1. Parse streams │
+│  2. Filter codecs │
+│  3. Extract via   │
+│     ffmpeg        │
+│  4. Save to       │
+│     /output       │
+│  5. Compute CID   │
+│  6. Store in      │
+│     Redis         │
+└───────────────────┘
+        │
+        ▼
+┌───────────────────┐
+│ /output folder    │  ← Watched by meta-sort
+│ *.srt files       │
+└───────────────────┘
+        │
+        ▼
+┌───────────────────┐
+│ meta-sort         │  ← Processes extracted files
+│ file watcher      │     like any other media
+└───────────────────┘
+```
+
+## Container Mounts
+
+| Mount | Access | Purpose |
+|-------|--------|---------|
+| `/files` | READ-ONLY | Source video files |
+| `/cache` | READ-WRITE | Plugin cache |
+| `/output` | READ-WRITE | Extracted subtitle output |
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `PORT` | HTTP server port (default: 8080) |
+| `WEBDAV_URL` | WebDAV base URL for file access |
+
+## API Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/health` | GET | Health check |
+| `/manifest` | GET | Plugin manifest |
+| `/configure` | POST | Update configuration |
+| `/process` | POST | Process a video file |
+
+## License
+
+MIT