caption-track-doctor-kit

Inspect SRT and WebVTT caption tracks with browser-focused diagnostics.

caption-track-doctor-kit is a clean-room TypeScript utility for checking subtitle files before they reach a browser player, upload form or media pipeline. It parses SRT and WebVTT text, reports stable diagnostic codes, and can convert simple SRT cues to WebVTT without Node-only APIs.

Links: Demo · npm · GitHub

Install

npm install caption-track-doctor-kit

Quick Start

import { convertSrtToWebVtt, inspectCaptionTrack } from "caption-track-doctor-kit";

const srt = `1
00:00:01,000 --> 00:00:03,500
Hello world`;

const report = inspectCaptionTrack(srt);

if (report.ok) {
  const converted = convertSrtToWebVtt(srt);
  console.log(converted.webvtt);
}

API

inspectCaptionTrack(input, options?)

Returns { ok, format, cues, diagnostics, durationMs }.

Expected user-input problems return diagnostics instead of throwing:

const report = inspectCaptionTrack(fileText, {
  format: "auto",
  maxInputLength: 500_000,
  allowHtmlTags: false
});

convertSrtToWebVtt(input, options?)

Converts valid SRT input to WebVTT text and returns { ok, webvtt, diagnostics, cues }.

The converter escapes cue text for WebVTT output. It is intentionally conservative: invalid timing or unknown input returns ok: false.

formatWebVttTimestamp(milliseconds)

Formats milliseconds as HH:MM:SS.mmm.

Diagnostics

Diagnostic codes are stable strings for UI, tests and logs:

• invalid-input
• invalid-options
• input-too-large
• empty-input
• unknown-format
• missing-webvtt-header
• invalid-cue-timing
• cue-end-before-start
• overlapping-cue
• empty-cue-text
• non-sequential-srt-index
• webvtt-block-ignored
• webvtt-setting-preserved
• webvtt-inline-timestamp
• html-like-tag
• bom-removed

Scope

This draft focuses on practical browser compatibility checks:

• SRT cue indexes and comma timestamps;
• WebVTT headers, identifiers, settings and dot timestamps;
• overlap detection;
• empty cues;
• inline WebVTT timestamps often found in generated captions;
• HTML-like cue text warnings;
• SRT to WebVTT conversion for simple cues.

It does not implement the full WebVTT rendering model, CSS cue styling, TTML, ASS/SSA, encoding detection, language detection or media container integration.

Package quality

• TypeScript types are generated from the source.
• ESM-only package with no runtime dependencies.
• Browser-friendly core: no fs, path, Buffer, process, network access or native Node modules.
• Defensive API: invalid input and invalid runtime options return diagnostics instead of throwing.
• CI runs npm ci, typecheck, build, and test.
• Tested on Node.js 20 and 22 with GitHub Actions.

License

MPL-2.0