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

cd packages/plugins/metamesh-plugin-subtitle-extractor
npm install
npm run build

Build Docker image

docker build -t metamesh-plugin-subtitle-extractor:main .

Configure in plugins.yml

Add to dev/plugins.yml:

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