# Subtitle Studio

> Convert SRT, VTT, ASS and SBV; shift, re-sync, fix overlaps, wrap lines and check CPS. Parses SRT, WebVTT, ASS/SSA (basic) and YouTube SBV subtitles and converts between them. Shift all times, re-sync by two reference points (fixes drifting subtitles), fix overlaps with a minimum gap, wrap or merge lines, remove hearing-impaired tags like [music] or (sighs), and get a reading-speed (characters per second) report and validation errors with line numbers.

Part of usefulweb.site (https://usefulweb.site/). Results are deterministic calculations from the inputs and the listed assumptions; the API returns exactly what the web page shows.

## Use it
- Human interface: https://subtitlestudio.usefulweb.site/ (interactive tool at https://subtitlestudio.usefulweb.site/tool)
- JSON API: POST https://subtitlestudio.usefulweb.site/api/v1/calculate with a JSON object of inputs (schema: https://subtitlestudio.usefulweb.site/api/v1/tool)
- OpenAPI: https://subtitlestudio.usefulweb.site/openapi.json
- MCP (Streamable HTTP): https://subtitlestudio.usefulweb.site/mcp - tool `subtitle_studio`

## Inputs
- text (textarea): Subtitle text - Paste SRT, WebVTT, ASS/SSA or SBV, or upload a file below.
- file (file): Subtitle file - Max 2 MB. UTF-8, UTF-16 (with BOM) or Windows-1252. Used instead of the text when given.
- inputFormat (select): Input format
- outputFormat (select): Output format
- shiftMs (integer): Shift all times - Positive = later, negative = earlier. 1000 ms = 1 s.
- syncCueA (integer): Sync point 1: cue number - Two-point sync fixes subtitles that drift (e.g. 25 vs 23.976 fps). Give two cues and when they should start.
- syncTimeA (text): Sync point 1: should start at
- syncCueB (integer): Sync point 2: cue number
- syncTimeB (text): Sync point 2: should start at
- removeHi (boolean): Remove hearing-impaired tags ([music], (sighs), speaker labels like JOHN:, ♪ lines)
- mergeLines (boolean): Merge multi-line cues into one line when they fit the maximum line length
- maxLineLength (integer): Maximum line length - 0 = no wrapping. 42 is a common limit for TV/streaming subtitles.
- maxLines (integer): Maximum lines per cue - Longer cues are split into several cues, with time shared by text length.
- fixOverlaps (boolean): Fix overlapping cues (shorten the earlier cue)
- minGapMs (integer): Minimum gap between cues - Used with "Fix overlapping cues". 83 ms ≈ 2 frames at 24 fps.
- maxCps (number): Reading speed limit for the report - Cues faster than this are listed. 15–20 characters per second are common guidelines.

## Method
- The format is detected from the content (WEBVTT header, [Script Info]/Dialogue lines, "-->" timing lines, or SBV "start,end" lines). Files are decoded as UTF-8 or UTF-16 with BOM, falling back to Windows-1252.
- Each block is validated: missing or out-of-sequence numbers, malformed timing lines, end before start, empty cues, cues longer than 10 s and overlaps are reported with the line number in your file. Broken blocks are skipped, not guessed.
- Operations run in this order: remove hearing-impaired tags → merge lines → wrap/split long lines → two-point sync → shift → fix overlaps. Two-point sync maps time linearly: t′ = T₁ + (t − S₁) × (T₂ − T₁) ÷ (S₂ − S₁), where S are the current and T the wanted start times of the two reference cues; it corrects both offset and drift (frame-rate mismatch).
- Line wrapping first tries two balanced lines split near the middle, otherwise wraps greedily; cues needing more lines than allowed are split into consecutive cues with time shared by text length.
- Reading speed = visible characters (without markup and line breaks) ÷ display time in seconds. ASS output uses one default style; ASS input styles, positions and effects are dropped (italic/bold are kept as <i>/<b>). SRT keeps <i>, <b> and <u>.