caption-checker

Check SRT and WebVTT captions against a published caption standard: Netflix English, the BBC subtitle guidelines or the DCMP Captioning Key. It flags captions that read too fast, lines that are too long, too many lines, captions that stay on screen too short or too long, gaps under the minimum, overlaps and broken timestamps.

No dependencies. Node 18+. The same checker runs in the browser, with no install and no upload, at markstudios.com/tools/caption-checker.

$ caption-check examples/travel-vlog.srt
travel-vlog.srt: 2 of 8 captions meet Netflix English, adult programs
  #1  0:00.500 -> 0:03.000  Welcome back to the channel.
      ✗ Gap to the next caption is 0 frames at 24 fps (minimum 2)
  #3  0:06.600 -> 0:07.100  First,
      ✗ On screen 0.50 s (minimum 5/6 of a second)
  #4  0:07.200 -> 0:09.000  we packed water, snacks, a rain jacket and a spare battery for the cam
      ✗ Reading speed 41.1 characters a second (limit 20)
      ✗ Line 1 is 74 characters (limit 42)
  ...

The limits

Each limit was read on the standard's own page on 2026-10-15.

Sources: Netflix English (USA) Timed Text Style Guide · Netflix General Requirements · Netflix Subtitle Timing Guidelines · BBC Subtitle Guidelines · DCMP Captioning Key: Text · DCMP Captioning Key: Presentation Rate

How it counts. Characters include letters, spaces and punctuation, but not line breaks or formatting (<i> tags, {\an8} codes, WebVTT voice spans). Reading speed is characters ÷ (out-time − in-time). Words are runs of characters that hold a letter or a digit, so speaker labels and sound tags count, as DCMP asks. Gaps run from one caption's out-time to the next caption's in-time, in frames at the frame rate you give. Anything a standard words as a recommendation is reported as advice, not as a failure.

Related MCP server: agent-eval-mcp

CLI

npx github:markksantos/caption-checker captions.srt
# or: git clone https://github.com/markksantos/caption-checker && node caption-checker/bin/caption-check.js captions.srt

caption-check <file.srt|file.vtt> [more files] [options]
  -s, --standard <id>   netflix | netflix-kids | bbc | dcmp-upper | dcmp-middle | dcmp-lower  (default: netflix)
  -f, --fps <rate>      frame rate for frame-gap checks (default: 24)
      --vertical        9:16 video (the BBC allows three lines)
      --json            JSON output
      --advice          also print advice-only notes
      --mcp             run as an MCP server on stdio

It exits with 1 when any caption breaks a limit, so it works as a CI check before captions ship.

Library

const { parse, check } = require('caption-checker');
const result = check(parse(fs.readFileSync('captions.vtt', 'utf8')), 'bbc', { vertical: true });
console.log(result.flagged, 'of', result.cues.length, 'captions break a limit');
for (const cue of result.cues) for (const issue of cue.issues) console.log(cue.n, issue.severity, issue.message);

check() accepts a standard id or your own standard object with the same fields as STANDARDS in index.js.

MCP server and Claude Code plugin

The same checks run as an MCP server, so Claude, Cursor, VS Code and other MCP clients can check a caption file mid-task. Two tools: check_captions (a file path or pasted SRT/VTT text, a standard, fps, vertical) and list_standards (each limit and the page it comes from). It runs locally: no key, no network.

# Claude Code plugin (MCP server + a caption QA skill)
/plugin marketplace add markksantos/caption-checker
/plugin install caption-checker@caption-checker

# or the server on its own
claude mcp add caption-checker -- npx -y github:markksantos/caption-checker --mcp

Other clients:

{ "mcpServers": { "caption-checker": { "command": "npx", "args": ["-y", "github:markksantos/caption-checker", "--mcp"] } } }

The skill in skills/caption-checker/SKILL.md tells an agent which standard to pick, how to report results and how to fix a caption without changing its words.

Study

study/ holds the code and data behind the caption reading speed study: 339,521 captions in 387 NASA videos and MIT OpenCourseWare lectures, measured with this library.

Version history

See CHANGELOG.md and releases.

Tests

npm test

License

MIT © Mark Studios, a video editing and production studio.