159 lines
4.2 KiB
Markdown
159 lines
4.2 KiB
Markdown
# 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
|