subtitle-timing-kit 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 0.1.0
+
+- Standalone SRT/WebVTT subset parser with visible parse diagnostics.
+- Timing and configurable readability checks, including nested overlaps.
+- Nonmutating shifts with explicit negative-time clipping reports.
+- Plain-text SRT/VTT serialization, an ESM API and JSON CLI.
+- Static Subtitle Timing Lab and synthetic examples.
+
+GitHub source release. npm registry publication remains pending.

package/CONTRIBUTING.md

@@ -0,0 +1,12 @@
+# Contributing
+
+Use Node.js 22+. No dependency installation is required for tests or the static build.
+
+1. Run `npm run check`.
+2. Run `npm run build:space` and open the demo using `npm run demo`.
+3. For parsing changes, include a synthetic input and its expected timestamps/diagnostics. Add tests for a concrete edge case or regression.
+4. Keep timestamps as safe integer milliseconds, preserve nonmutation, and document any newly lossy behavior.
+
+Do not attach private subtitles, API keys, local environment files or real recordings to issues. Reproduce bugs with invented text. An overlap can be intentional; do not add a repair that silently removes or truncates dialogue.
+
+No network calls, third-party scripts or local storage should be added to the local demo without explicitly changing its privacy description.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 j-river
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,158 @@
-# Temporary Holding Version
+# subtitle-timing-kit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Local SRT and WebVTT parsing, timing diagnostics, shifts, and plain-text exports.
+Runs in Node.js and modern browsers with **zero runtime dependencies**.
+
+**[Try Subtitle Timing Lab](https://huggingface.co/spaces/j-river/subtitle-timing-lab)** · [Format limits](docs/format-support.md) · [Sample files](samples/)
+
+A subtitle file can parse successfully and still contain overlapping cues or text that flashes by too fast. This toolkit makes those problems inspectable. It does not guess which dialogue to delete, translate speech, or align words to audio.
+
+An open-source companion resource from [SubtitlePop](https://subtitlepop.com/), whose separate [subtitle checker](https://subtitlepop.com/tools/subtitle-checker/) provides a ready-made product workflow. This standalone implementation is not a claim about the code deployed inside the commercial website.
+
+![Real Subtitle Timing Lab interface, with an overlapping cue and reading-speed diagnostics](https://raw.githubusercontent.com/j-river/subtitle-timing-kit/main/docs/assets/timing-check.jpg)
+
+## Install
+
+Node.js **22 or newer** is required for the CLI and tests. No model, FFmpeg, Python, API key or runtime npm dependency is needed.
+
+```sh
+npm install subtitle-timing-kit
+npx subtitle-timing-kit --help
+```
+
+```js
+import { parseSubtitles, inspectCues } from 'subtitle-timing-kit';
+const parsed = parseSubtitles('1\n00:00:01,000 --> 00:00:03,000\nHello!\n');
+const report = inspectCues(parsed.cues);
+console.log([...parsed.issues, ...report.issues]);
+```
+
+## Run from GitHub
+
+```sh
+git clone https://github.com/j-river/subtitle-timing-kit.git
+cd subtitle-timing-kit
+npm test
+node src/cli.js inspect samples/overlap.srt
+node src/cli.js convert samples/clean.srt --to vtt
+node src/cli.js shift samples/clean.srt --ms 1500 --to srt
+```
+
+CLI output goes to stdout. To save it, redirect to a **new** file:
+
+```sh
+node src/cli.js convert samples/clean.srt --to vtt > captions.vtt
+```
+
+Never redirect to the input filename: a shell can truncate it before the command reads it.
+Warnings go to stderr. Exit codes: `0` for success (including warnings), `1` for invalid data, `2` for usage or I/O failures.
+
+`npm pack` produces an installable local tarball. For an installed package, import from `subtitle-timing-kit` and run `subtitle-timing --help`. The package is ESM only; type declarations ship with the source.
+
+## API: inspect, shift, export
+
+```js
+import {
+  parseSubtitles,
+  inspectCues,
+  shiftCues,
+  serializeSubtitles,
+} from './src/index.js';
+
+const parsed = parseSubtitles(`1
+00:00:01,000 --> 00:00:03,000
+Keep the words editable.
+`);
+const report = inspectCues(parsed.cues);
+const issues = [...parsed.issues, ...report.issues];
+if (issues.some(issue => issue.severity === 'error')) {
+  throw new Error('Fix input errors before exporting.');
+}
+
+const shifted = shiftCues(parsed.cues, 1500);
+const vtt = serializeSubtitles(shifted.cues, { format: 'vtt' });
+console.log(vtt);
+// WEBVTT
+//
+// 1
+// 00:00:02.500 --> 00:00:04.500
+// Keep the words editable.
+```
+
+`parseSubtitles` returns `{ format, cues, issues }`. Cues use integer **milliseconds** and keep parsed text/identifiers/settings. Parsing errors are returned in `issues`; malformed blocks are not silently accepted. Combine parse issues with inspection issues before converting partial results. Invalid API argument types throw.
+
+`inspectCues` returns diagnostics, per-cue metrics, and a summary. The report refers to **zero-based cue indices**; the demo labels them starting at one.
+
+| Code | Meaning | Treatment |
+| --- | --- | --- |
+| `REVERSED_TIME` / `ZERO_DURATION` | Invalid duration | Error; fix before shift/export |
+| `EMPTY_TEXT` | No visible text after markup removal | Error |
+| `OUT_OF_ORDER` | File order differs from start-time order | Warning; sort explicitly before VTT export |
+| `OVERLAP` | An interval intersects an earlier active interval | Warning; can be intentional |
+| `FAST_READING` | Text exceeds the chosen characters/second limit | Editorial heuristic |
+| `LONG_LINE` / `TOO_MANY_LINES` | Text exceeds chosen layout limits | Editorial heuristic |
+| `VTT_BLOCK_OMITTED` / `HEADER_METADATA_OMITTED` | Metadata is outside the export subset | Loss warning |
+
+Overlap detection handles nested intervals in `O(n log n)` time and emits at most one overlap diagnostic per later cue. It does **not** enumerate every intersecting pair.
+
+### Negative shifts
+
+Negative timestamps are rejected by default. Opt into clipping when it is what you want:
+
+```js
+const result = shiftCues(parsed.cues, -1500, { negative: 'clip' });
+console.log(result.clippedIndices); // start clamped to 0, end still positive
+console.log(result.droppedIndices); // end moved to 0 or earlier
+```
+
+Input arrays and cues are not mutated. Clipping can remove dialogue, so the API reports every changed/dropped index. A global shift preserves overlaps; it does not fix clock drift.
+
+### Reading thresholds
+
+```js
+inspectCues(parsed.cues, { maxLineLength: 42, maxLines: 2, maxCps: 20 });
+```
+
+These defaults are adjustable **heuristics**, not certification against any accessibility, broadcaster or streaming-platform standard. Character counts use Unicode code points, include spaces and exclude line breaks. They are not grapheme or language-specific reading models. Markup is removed for the metrics.
+
+## Format limits and data loss
+
+- SRT: numeric optional cue identifiers, `HH:MM:SS,mmm` times, multiline text; BOM and CRLF accepted. SRT timing-line extensions are rejected.
+- WebVTT: a `WEBVTT` header, cue identifiers, `MM:SS.mmm` or `HH:MM:SS.mmm` times, and raw one-line cue settings. Cue settings are retained for VTT export but not fully validated.
+- `NOTE`, `STYLE`, `REGION` and header metadata are omitted with parse warnings. This is a **WebVTT subset**, not a full conformance validator.
+- Export defaults to plain text: angle-bracket markup, speaker tags, inline word timestamps and simple ASS override blocks are removed; common caption entities are decoded. This can change literal angle-bracket text. Keep originals.
+- `{ textMode: 'preserve' }` retains the cue payload but does not translate markup between formats. It does not make WebVTT voice/region markup valid SRT. `plainText()` is **not an HTML sanitizer**; render untrusted captions using `textContent`.
+- VTT export retains cue settings unless `keepSettings: false`. SRT export renumbers cues and drops VTT settings. VTT export requires start-time order; intentional overlaps remain allowed.
+- Default hard limits: **2 MiB UTF-8 input/output**, **10,000 cues**. Parse options may lower the input limits.
+- No ASS/SSA parser, translation, speech recognition, video rendering or media sync is included.
+
+See [format support and conversion examples](docs/format-support.md) and the primary [WebVTT specification](https://www.w3.org/TR/webvtt1/).
+
+## Browser demo and Hugging Face build
+
+```sh
+npm run build:space
+npm run demo
+```
+
+Open `http://127.0.0.1:4184/demo/index.html`. To reproduce the hosted demo, upload only `.artifacts/hf-space/` to a Hugging Face **Static** Space. Build metadata contains hashes of the source assets. The page has no upload service, remote scripts, analytics, cookies, or local storage; the hosting provider may log page requests.
+
+Try all four synthetic samples: clean timing, overlap/reading problems, VTT markup/positioning, and invalid durations. Source edits invalidate the report and downloads until reanalysis. Shifts apply to the current working cues and accumulate; Analyze resets them to the source. The timing map shows only the first 60 cues, not video playback, and the UI lists at most 300 diagnostics.
+
+## Development
+
+```sh
+npm run check
+npm run build:space
+npm run audit:public
+```
+
+Tests cover timestamp boundaries, Unicode/CRLF round trips, nested overlaps, lossy format behavior, explicit clipping, resource limits, separator injection, and real CLI exit codes. All examples are synthetic and MIT licensed. See [CONTRIBUTING](CONTRIBUTING.md).
+
+## Product workflows
+
+The lab starts from existing subtitle files. To generate captions from speech instead, use the separate [SubtitlePop subtitle generator](https://subtitlepop.com/subtitle-generator/). For a quick format conversion workflow, see [SRT to VTT](https://subtitlepop.com/tools/srt-to-vtt/). Those product features have their own limits and privacy terms; they are not called by this demo.
+
+## License
+
+MIT. No user uploads, production credentials or commercial service code are included.

package/docs/format-support.md

@@ -0,0 +1,54 @@
+# SRT ↔ WebVTT: what changes?
+
+This toolkit supports a deliberately small text-caption subset. Its parser is not the browser's full WebVTT state machine. The [W3C specification](https://www.w3.org/TR/webvtt1/) is the primary reference for WebVTT behavior.
+
+## A conversion you can inspect
+
+Input:
+
+```vtt
+WEBVTT
+
+intro
+00:01.000 --> 00:03.500 align:start position:10%
+<v Narrator><b>Hello</b> &amp; welcome.</v>
+```
+
+Default SRT output:
+
+```srt
+1
+00:00:01,000 --> 00:00:03,500
+Hello & welcome.
+```
+
+Timing and visible words survive. The cue identifier becomes a sequential SRT index, WebVTT position settings are dropped, and speaker/bold markup is removed. A conversion is not a styled-video export.
+
+## Why parse and inspect are separate
+
+`00:00:03,000 --> 00:00:02,000` has recognizable SRT timestamps, but a negative duration. Parsing preserves the evidence; inspection reports `REVERSED_TIME`. Never export partial parse results without checking parse issues first.
+
+An overlap is different: WebVTT can intentionally show simultaneous cues. The overlap warning asks for review; it is not automatically an invalid-file error. A global offset will move both intervals and keep their intersection unchanged.
+
+## What this implementation does not preserve
+
+| Item | Parse | Export |
+| --- | --- | --- |
+| Text cue times | Millisecond integers | Canonical comma/dot format |
+| Multiline cue text | Preserved | Preserved, without blank paragraphs |
+| VTT cue identifiers | Preserved | VTT retains; SRT renumbers |
+| VTT cue settings | Raw text, not full syntax validation | VTT retains by default; SRT drops |
+| Voice/inline timestamp markup | Kept in parsed payload | Plain mode removes; preserve mode leaves raw payload |
+| NOTE / STYLE / REGION blocks | Skipped with warning | Not retained |
+| VTT header metadata | Warning when present | Not retained |
+| ASS/SSA | Unsupported | Unsupported |
+
+Plain-text extraction removes angle-bracket sequences. Literal text written as `<example>` can also be removed; encode or keep the original when that matters. The extraction utility must not be used to sanitize HTML.
+
+## Negative offsets near zero
+
+If `[1000, 3000]` moves by `-1500`, the default rejects the operation. With explicit clipping it becomes `[0, 1500]`. A cue whose end becomes `0` or negative is dropped and its original index reported. Never describe this as lossless repair.
+
+## Sample provenance
+
+All files under `samples/` were written for this project. They contain invented instructional sentences, no real transcripts, names, private recordings or third-party media. They are distributed under the repository's MIT license.

package/package.json

@@ -1,6 +1,23 @@
 {
   "name": "subtitle-timing-kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Local SRT/WebVTT parsing, timing diagnostics, shifts and plain-text subtitle exports.",
+  "type": "module",
+  "license": "MIT",
+  "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" },
+  "author": "j-river",
+  "engines": { "node": ">=22" },
+  "exports": { ".": { "types": "./src/index.d.ts", "import": "./src/index.js" } },
+  "bin": { "subtitle-timing": "./src/cli.js" },
+  "files": ["src/", "samples/", "docs/format-support.md", "README.md", "LICENSE", "CONTRIBUTING.md", "CHANGELOG.md"],
+  "repository": { "type": "git", "url": "git+https://github.com/j-river/subtitle-timing-kit.git" },
+  "homepage": "https://github.com/j-river/subtitle-timing-kit#readme",
+  "keywords": ["subtitles", "srt", "webvtt", "captions", "timing", "subtitlepop"],
+  "scripts": {
+    "test": "node --test tests/*.test.mjs",
+    "check": "node --check src/index.js && node --check src/cli.js && node --check demo/app.js && npm test",
+    "build:space": "node scripts/build-space.mjs",
+    "demo": "node scripts/serve.mjs",
+    "audit:public": "node scripts/audit-public.mjs"
+  }
+}

package/samples/clean.srt

@@ -0,0 +1,11 @@
+1
+00:00:01,000 --> 00:00:03,500
+Small changes make captions easy to read.
+
+2
+00:00:03,700 --> 00:00:06,500
+Keep timecodes and text editable.
+
+3
+00:00:06,700 --> 00:00:09,500
+Export a file your player can read.

package/samples/invalid.srt

@@ -0,0 +1,7 @@
+1
+00:00:03,000 --> 00:00:02,000
+This cue ends before it starts.
+
+2
+00:00:04,000 --> 00:00:04,000
+This cue has no duration.

package/samples/layout.vtt

@@ -0,0 +1,11 @@
+WEBVTT
+
+NOTE This comment is intentionally omitted on export.
+
+intro
+00:01.000 --> 00:03.500 align:start position:10%
+<v Narrator><b>Hello</b> &amp; welcome.</v>
+
+outro
+00:04.000 --> 00:07.000
+Subtitle files are not burned-in video captions.

package/samples/overlap.srt

@@ -0,0 +1,15 @@
+1
+00:00:00,500 --> 00:00:03,500
+The first caption stays on screen.
+
+2
+00:00:02,800 --> 00:00:04,900
+This one begins too early.
+
+3
+00:00:05,000 --> 00:00:05,600
+This sentence is difficult to read in six tenths of a second.
+
+4
+00:00:06,000 --> 00:00:09,000
+Fix the timing. Keep the words.

package/src/cli.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+import { readFile } from 'node:fs/promises';
+import { parseSubtitles, inspectCues, shiftCues, serializeSubtitles, LIMITS } from './index.js';
+
+const help = `subtitle-timing-kit
+subtitle-timing inspect input.srt
+subtitle-timing convert input.srt --to vtt
+subtitle-timing shift input.srt --ms -1500 --to srt [--clip]
+
+Output goes to stdout; redirect to a NEW file, never the input file.
+Inspect returns JSON. Exit codes: 0=success, 1=invalid data, 2=usage/I/O.
+Exports use plain text; WebVTT NOTE/STYLE/REGION blocks are omitted.
+`;
+
+try {
+  const [command, path, ...args] = process.argv.slice(2);
+  if (!command || command === '--help' || command === '-h') { console.log(help); process.exit(0); }
+  if (!['inspect', 'convert', 'shift'].includes(command) || !path) throw Error(help);
+  const flags = {};
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--clip') flags.clip = true;
+    else if (['--to', '--ms'].includes(args[i]) && args[i + 1] !== undefined) flags[args[i].slice(2)] = args[++i];
+    else throw Error(`Unknown or incomplete argument: ${args[i]}`);
+  }
+  if (flags.to !== undefined && !['srt', 'vtt'].includes(flags.to)) throw Error('--to must be srt or vtt.');
+  if (command === 'shift' && (flags.ms === undefined || !/^-?\d+$/.test(flags.ms))) throw Error('shift requires integer --ms.');
+  const { stat } = await import('node:fs/promises');
+  if ((await stat(path)).size > LIMITS.maxBytes) throw Error('Input exceeds 2 MiB.');
+  const result = parseSubtitles(await readFile(path, 'utf8'));
+  const report = inspectCues(result.cues);
+  const issues = [...result.issues, ...report.issues];
+  if (command === 'inspect') {
+    console.log(JSON.stringify({ format: result.format, summary: { ...report.summary, errors: issues.filter(i => i.severity === 'error').length, warnings: issues.filter(i => i.severity === 'warning').length }, issues, metrics: report.metrics }, null, 2));
+    process.exitCode = issues.some(i => i.severity === 'error') ? 1 : 0;
+  } else if (issues.some(i => i.severity === 'error')) {
+    console.error(JSON.stringify({ error: 'Fix invalid cues before export.', issues }, null, 2));
+    process.exitCode = 1;
+  } else {
+    const warnings = issues.filter(i => i.severity === 'warning');
+    if (result.cues.some(c => c.text !== c.text.replace(/<[^>\n]*>/g, '') || c.settings)) warnings.push({ code: 'LOSSY_EXPORT', severity: 'warning', message: 'Plain-text export removes markup; SRT export drops WebVTT cue settings.' });
+    if (warnings.length) console.error(JSON.stringify({ warnings }));
+    let cues = result.cues;
+    if (command === 'shift') {
+      const shifted = shiftCues(cues, Number(flags.ms), { negative: flags.clip ? 'clip' : 'reject' });
+      cues = shifted.cues;
+      if (shifted.droppedIndices.length || shifted.clippedIndices.length) console.error(JSON.stringify({ droppedIndices: shifted.droppedIndices, clippedIndices: shifted.clippedIndices }));
+    }
+    process.stdout.write(serializeSubtitles(cues, { format: flags.to ?? result.format }));
+  }
+} catch (error) {
+  console.error(error.message);
+  process.exitCode = error instanceof RangeError ? 1 : 2;
+}

package/src/index.d.ts

@@ -0,0 +1,14 @@
+export interface Cue { id?: string; startMs: number; endMs: number; text: string; settings?: string }
+export interface Issue { code: string; severity: 'error' | 'warning'; message: string; cueIndex?: number; relatedCueIndex?: number; blockIndex?: number }
+export interface ParseResult { format: 'srt' | 'vtt'; cues: Cue[]; issues: Issue[] }
+export interface Inspection { issues: Issue[]; metrics: { cueIndex: number; durationMs: number; characters: number; lines: number; cps: number | null }[]; summary: { cues: number; endMs: number; errors: number; warnings: number } }
+export const VERSION: string;
+export const LIMITS: Readonly<{ maxBytes: number; maxCues: number }>;
+export function parseTimestamp(value: string, format?: 'srt' | 'vtt'): number;
+export function formatTimestamp(ms: number, format?: 'srt' | 'vtt'): string;
+/** Plain caption text extraction, not HTML sanitization. */
+export function plainText(text: string): string;
+export function parseSubtitles(input: string, options?: { format?: 'auto' | 'srt' | 'vtt'; maxBytes?: number; maxCues?: number }): ParseResult;
+export function inspectCues(cues: Cue[], options?: { maxLineLength?: number; maxLines?: number; maxCps?: number }): Inspection;
+export function shiftCues(cues: Cue[], offsetMs: number, options?: { negative?: 'reject' | 'clip' }): { cues: Cue[]; droppedIndices: number[]; clippedIndices: number[] };
+export function serializeSubtitles(cues: Cue[], options?: { format?: 'srt' | 'vtt'; textMode?: 'plain' | 'preserve'; keepSettings?: boolean }): string;

package/src/index.js

@@ -0,0 +1,166 @@
+/** Plain-text SRT and WebVTT utilities. All timestamps are integer milliseconds. */
+export const VERSION = '0.1.0';
+export const LIMITS = Object.freeze({ maxBytes: 2 * 1024 * 1024, maxCues: 10000 });
+
+const issue = (code, severity, message, extra = {}) => ({ code, severity, message, ...extra });
+const encoder = new TextEncoder();
+
+export function parseTimestamp(value, format = 'vtt') {
+  if (typeof value !== 'string' || !['srt', 'vtt'].includes(format)) throw new TypeError('Expected a timestamp and srt or vtt format.');
+  const pattern = format === 'srt' ? /^(\d{2,}):(\d{2}):(\d{2}),(\d{3})$/ : /^(?:(\d{2,}):)?(\d{2}):(\d{2})\.(\d{3})$/;
+  const m = value.match(pattern);
+  if (!m) throw new RangeError(`Invalid ${format.toUpperCase()} timestamp: ${value}`);
+  const hours = Number(m[1] || 0), minutes = Number(m[2]), seconds = Number(m[3]);
+  const ms = ((hours * 60 + minutes) * 60 + seconds) * 1000 + Number(m[4]);
+  if (minutes > 59 || seconds > 59 || !Number.isSafeInteger(ms)) throw new RangeError(`Out-of-range timestamp: ${value}`);
+  return ms;
+}
+
+export function formatTimestamp(ms, format = 'srt') {
+  if (!Number.isSafeInteger(ms) || ms < 0) throw new RangeError('Time must be a non-negative safe integer in milliseconds.');
+  if (!['srt', 'vtt'].includes(format)) throw new TypeError('Format must be srt or vtt.');
+  const pad = (n, size = 2) => String(n).padStart(size, '0');
+  const h = Math.floor(ms / 3600000), m = Math.floor(ms / 60000) % 60, s = Math.floor(ms / 1000) % 60;
+  return `${pad(h)}:${pad(m)}:${pad(s)}${format === 'srt' ? ',' : '.'}${pad(ms % 1000, 3)}`;
+}
+
+/** Remove angle-bracket markup and common caption entities; not an HTML sanitizer. */
+export function plainText(text) {
+  const entities = { amp: '&', lt: '<', gt: '>', nbsp: ' ', quot: '"', apos: "'" };
+  return String(text).replace(/<[^>\n]*>/g, '').replace(/\{\\[^}\n]*\}/g, '').replace(/&(#x[\da-f]+|#\d+|amp|lt|gt|nbsp|quot|apos);/gi, (whole, entity) => {
+    if (entity[0] !== '#') return entities[entity.toLowerCase()] ?? whole;
+    const n = entity[1].toLowerCase() === 'x' ? parseInt(entity.slice(2), 16) : Number(entity.slice(1));
+    return Number.isInteger(n) && n > 0 && n <= 0x10ffff && !(n >= 0xd800 && n <= 0xdfff) ? String.fromCodePoint(n) : whole;
+  });
+}
+
+export function parseSubtitles(input, options = {}) {
+  if (typeof input !== 'string') throw new TypeError('Subtitle input must be a string.');
+  const maxBytes = options.maxBytes ?? LIMITS.maxBytes, maxCues = options.maxCues ?? LIMITS.maxCues;
+  if (!Number.isSafeInteger(maxBytes) || maxBytes < 1 || maxBytes > LIMITS.maxBytes || !Number.isSafeInteger(maxCues) || maxCues < 1 || maxCues > LIMITS.maxCues) throw new RangeError('Limits must be positive integers no greater than 2 MiB / 10,000 cues.');
+  const formatOption = options.format ?? 'auto';
+  if (!['auto', 'srt', 'vtt'].includes(formatOption)) throw new TypeError('Format must be auto, srt or vtt.');
+  if (input.length > maxBytes || encoder.encode(input).length > maxBytes) return { format: formatOption === 'vtt' ? 'vtt' : 'srt', cues: [], issues: [issue('INPUT_LIMIT', 'error', `Input exceeds ${maxBytes} UTF-8 bytes.`)] };
+  const text = input.replace(/^\uFEFF/, '').replace(/\r\n?/g, '\n');
+  const format = formatOption === 'auto' ? (/^WEBVTT(?:[ \t].*)?(?:\n|$)/.test(text) ? 'vtt' : 'srt') : formatOption;
+  const issues = [], cues = [];
+  if (!text.trim()) return { format, cues, issues: [issue('EMPTY_INPUT', 'error', 'Paste or load a subtitle file.')] };
+  const blocks = text.split(/\n[ \t]*\n/);
+  if (format === 'vtt') {
+    const header = blocks.shift().split('\n');
+    if (!/^WEBVTT(?:[ \t].*)?$/.test(header[0]) || header[0].includes('-->')) return { format, cues, issues: [issue('VTT_HEADER', 'error', 'WebVTT needs a WEBVTT header followed by a blank line.')] };
+    if (header.slice(1).some(line => line.includes('-->'))) return { format, cues, issues: [issue('VTT_HEADER', 'error', 'Separate the WEBVTT header and first cue with a blank line.')] };
+    if (header.length > 1 || header[0] !== 'WEBVTT') issues.push(issue('HEADER_METADATA_OMITTED', 'warning', 'WebVTT header metadata is not retained on export.'));
+  }
+  for (let blockIndex = 0; blockIndex < blocks.length; blockIndex++) {
+    const lines = blocks[blockIndex].replace(/^\n+|\n+$/g, '').split('\n');
+    if (lines.every(line => !line.trim())) continue;
+    if (format === 'vtt' && /^(NOTE(?:[ \t]|$)|STYLE$|REGION$)/.test(lines[0])) {
+      issues.push(issue('VTT_BLOCK_OMITTED', 'warning', 'NOTE, STYLE and REGION blocks are not retained on export.', { blockIndex }));
+      continue;
+    }
+    let timingIndex = lines[0].includes('-->') ? 0 : 1;
+    if (timingIndex === 1 && format === 'srt' && !/^\d+$/.test(lines[0].trim())) {
+      issues.push(issue('SRT_ID', 'error', 'An SRT cue identifier must be numeric.', { blockIndex }));
+      continue;
+    }
+    const timing = lines[timingIndex]?.match(/^(\S+)[ \t]+-->[ \t]+(\S+)(?:[ \t]+(.*))?$/);
+    if (!timing) {
+      issues.push(issue('CUE_TIMING', 'error', 'Expected a start --> end timestamp line.', { blockIndex }));
+      continue;
+    }
+    if (format === 'srt' && timing[3]) {
+      issues.push(issue('SRT_SETTINGS', 'error', 'This SRT subset does not support timing-line extensions.', { blockIndex }));
+      continue;
+    }
+    try {
+      const cue = { startMs: parseTimestamp(timing[1], format), endMs: parseTimestamp(timing[2], format), text: lines.slice(timingIndex + 1).join('\n') };
+      if (timingIndex === 1) cue.id = lines[0];
+      if (timing[3]) cue.settings = timing[3];
+      cues.push(cue);
+      if (cues.length > maxCues) return { format, cues: [], issues: [issue('CUE_LIMIT', 'error', `Input exceeds ${maxCues} cues.`)] };
+    } catch (error) {
+      issues.push(issue('TIMESTAMP', 'error', error.message, { blockIndex }));
+    }
+  }
+  if (!cues.length && !issues.some(i => i.severity === 'error')) issues.push(issue('NO_CUES', 'error', 'No subtitle cues found.'));
+  return { format, cues, issues };
+}
+
+function checkShape(cue) {
+  if (!cue || !Number.isSafeInteger(cue.startMs) || !Number.isSafeInteger(cue.endMs) || cue.startMs < 0 || cue.endMs < 0 || typeof cue.text !== 'string') throw new TypeError('Each cue needs non-negative safe-integer startMs/endMs and string text.');
+}
+
+export function inspectCues(cues, options = {}) {
+  if (!Array.isArray(cues) || cues.length > LIMITS.maxCues) throw new RangeError(`Expected up to ${LIMITS.maxCues} cues.`);
+  const maxLineLength = options.maxLineLength ?? 42, maxLines = options.maxLines ?? 2, maxCps = options.maxCps ?? 20;
+  for (const n of [maxLineLength, maxLines, maxCps]) if (!Number.isFinite(n) || n <= 0) throw new RangeError('Reading thresholds must be positive finite numbers.');
+  const issues = [], metrics = [];
+  cues.forEach((cue, cueIndex) => {
+    checkShape(cue);
+    const text = plainText(cue.text), lines = text.split('\n');
+    const durationMs = cue.endMs - cue.startMs, characters = Array.from(text.replace(/\n/g, '')).length;
+    const cps = durationMs > 0 ? characters / (durationMs / 1000) : null;
+    metrics.push({ cueIndex, durationMs, characters, lines: lines.length, cps });
+    const add = (code, severity, message) => issues.push(issue(code, severity, message, { cueIndex }));
+    if (!text.trim()) add('EMPTY_TEXT', 'error', 'Cue text is empty.');
+    if (durationMs < 0) add('REVERSED_TIME', 'error', 'Cue ends before it starts.');
+    if (durationMs === 0) add('ZERO_DURATION', 'error', 'Cue has zero duration.');
+    if (cueIndex > 0 && cue.startMs < cues[cueIndex - 1].startMs) add('OUT_OF_ORDER', 'warning', 'Cue start precedes the previous cue in file order.');
+    if (lines.some(line => Array.from(line).length > maxLineLength)) add('LONG_LINE', 'warning', `A line exceeds the ${maxLineLength}-character heuristic.`);
+    if (lines.length > maxLines) add('TOO_MANY_LINES', 'warning', `Cue exceeds the ${maxLines}-line heuristic.`);
+    if (cps !== null && cps > maxCps) add('FAST_READING', 'warning', `Reading speed is ${cps.toFixed(1)} characters/s; threshold is ${maxCps}.`);
+  });
+  let furthest = null;
+  for (const entry of cues.map((cue, cueIndex) => ({ cue, cueIndex })).filter(e => e.cue.endMs > e.cue.startMs).sort((a, b) => a.cue.startMs - b.cue.startMs || a.cueIndex - b.cueIndex)) {
+    if (furthest && entry.cue.startMs < furthest.cue.endMs) issues.push(issue('OVERLAP', 'warning', `Overlaps cue ${furthest.cueIndex + 1}. Overlap can be intentional.`, { cueIndex: entry.cueIndex, relatedCueIndex: furthest.cueIndex }));
+    if (!furthest || entry.cue.endMs > furthest.cue.endMs) furthest = entry;
+  }
+  return {
+    issues, metrics,
+    summary: { cues: cues.length, endMs: cues.reduce((n, c) => Math.max(n, c.endMs), 0), errors: issues.filter(i => i.severity === 'error').length, warnings: issues.filter(i => i.severity === 'warning').length }
+  };
+}
+
+export function shiftCues(cues, offsetMs, options = {}) {
+  if (!Array.isArray(cues) || cues.length > LIMITS.maxCues) throw new RangeError(`Expected up to ${LIMITS.maxCues} cues.`);
+  if (!Number.isSafeInteger(offsetMs)) throw new RangeError('Offset must be a safe integer in milliseconds.');
+  const negative = options.negative ?? 'reject';
+  if (!['reject', 'clip'].includes(negative)) throw new TypeError('Negative policy must be reject or clip.');
+  const output = [], droppedIndices = [], clippedIndices = [];
+  cues.forEach((cue, i) => {
+    checkShape(cue);
+    if (cue.endMs <= cue.startMs) throw new RangeError(`Cue ${i + 1} needs positive duration before shifting.`);
+    const start = cue.startMs + offsetMs, end = cue.endMs + offsetMs;
+    if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end)) throw new RangeError('Shift exceeds safe integer limits.');
+    if (start < 0) {
+      if (negative === 'reject') throw new RangeError(`Cue ${i + 1} would start before zero. Choose clipping explicitly.`);
+      if (end <= 0) { droppedIndices.push(i); return; }
+      clippedIndices.push(i);
+    }
+    output.push({ ...cue, startMs: Math.max(0, start), endMs: end });
+  });
+  return { cues: output, droppedIndices, clippedIndices };
+}
+
+export function serializeSubtitles(cues, options = {}) {
+  const format = options.format ?? 'srt', textMode = options.textMode ?? 'plain';
+  if (!['srt', 'vtt'].includes(format) || !['plain', 'preserve'].includes(textMode)) throw new TypeError('Expected srt/vtt format and plain/preserve textMode.');
+  if (!Array.isArray(cues) || cues.length > LIMITS.maxCues) throw new RangeError(`Expected up to ${LIMITS.maxCues} cues.`);
+  const blocks = cues.map((cue, i) => {
+    checkShape(cue);
+    if (cue.endMs <= cue.startMs) throw new RangeError(`Cue ${i + 1} needs positive duration.`);
+    if (format === 'vtt' && i && cue.startMs < cues[i - 1].startMs) throw new RangeError('Sort cues by start time before WebVTT export.');
+    const text = textMode === 'plain' ? plainText(cue.text) : cue.text;
+    if (!text.trim() || /\r|\n[ \t]*\n|-->/.test(text)) throw new RangeError(`Cue ${i + 1} contains empty text or unsupported cue separators.`);
+    if (cue.id !== undefined && (typeof cue.id !== 'string' || /[\r\n]|-->/.test(cue.id))) throw new RangeError('Cue identifiers must stay on one line.');
+    if (format === 'vtt' && cue.id && /^(NOTE(?:[ \t]|$)|STYLE$|REGION$)/.test(cue.id)) throw new RangeError('Reserved WebVTT block names cannot be cue identifiers.');
+    if (cue.settings !== undefined && (typeof cue.settings !== 'string' || /[\r\n]|-->/.test(cue.settings))) throw new RangeError('Cue settings must stay on one line.');
+    const settings = format === 'vtt' && options.keepSettings !== false && cue.settings ? ` ${cue.settings}` : '';
+    const id = format === 'srt' ? `${i + 1}\n` : cue.id ? `${cue.id}\n` : '';
+    return `${id}${formatTimestamp(cue.startMs, format)} --> ${formatTimestamp(cue.endMs, format)}${settings}\n${text}`;
+  });
+  const output = `${format === 'vtt' ? 'WEBVTT\n\n' : ''}${blocks.join('\n\n')}${blocks.length ? '\n' : ''}`;
+  if (encoder.encode(output).length > LIMITS.maxBytes) throw new RangeError('Serialized output exceeds 2 MiB.');
+  return output;
+}