---
name: Extract Subtitles
description: This skill should be used when the user asks to "extract subtitles", "pull captions from a video", "get the SRT", "convert subtitles to WebVTT", "list subtitle tracks", or wants embedded subtitle/caption streams saved as files. Extracts embedded subtitle tracks to SRT and VTT with ffmpeg.
version: 0.1.0
---

# Extract Subtitles

Pull **embedded subtitle tracks** out of a container (MKV/MP4/etc.) and save them as `.srt`
and `.vtt` files — one per track, named by language.

## When to use

Use this skill when a user wants caption/subtitle files extracted from a video that already
contains subtitle streams, or wants to list which subtitle tracks a file has.

## Workflow

1. Confirm `ffmpeg`/`ffprobe` are available.
2. List subtitle streams first so the user sees what's available:
   ```bash
   ffprobe -v error -select_streams s -show_entries stream=index,codec_name:stream_tags=language -of json INPUT
   ```
3. Run the bundled script to extract every text-based track to SRT + VTT:
   ```bash
   "${CLAUDE_PLUGIN_ROOT}/skills/extract-subtitles/scripts/extract-subs.sh" INPUT out_prefix
   ```
4. Report the files written (with languages). If a track is image-based (PICTURE codecs like
   `hdmv_pgs_subtitle` / `dvd_subtitle`), note that it can't be converted to text without OCR.

## Key details

- Text subtitle codecs (`subrip`, `mov_text`, `ass`, `webvtt`) convert cleanly to SRT/VTT.
- Image-based subtitles (PGS/VOBSUB) are bitmaps — extraction to text requires OCR, which is
  out of scope; surface this clearly rather than producing empty files.
- **No embedded track?** The source has no subtitles to extract — transcription (speech-to-
  text) is a different task; say so instead of failing silently.

## Resources

- **`scripts/extract-subs.sh`** — lists subtitle streams and extracts text tracks to SRT/VTT.