Build a WebVTT cue ledger from file blocks

The useful distinctions

• A WebVTT file begins with the WEBVTT signature.
• A blank line separates the header from cue data and separates cue blocks.
• Cue timing uses a start and end separated by -->.

Turn each block into a row

The fictional file contains two cues rather than four independent lines of dialogue. The first lasts from 1.250 to 3.000 seconds and the second from 3.250 to 5.000 seconds. A worksheet with start, end, duration, and text makes the quarter-second gap visible. The durations are each 1.75 seconds. This is a timing inventory, not a judgment that either duration is ideal for a particular reader or programme.

Protect structural whitespace during edits

A blank line ends a cue block, so inserting one into the middle of a payload is different from adding an ordinary line break within that cue. Likewise, removing every empty line as a cleanup step can join blocks and change how a parser understands the file. Store the file as UTF-8 and preserve the distinction between the timing line and payload lines when applying text replacements. If an export loses the signature or uses a comma as a decimal separator copied from another subtitle format, repair the serializer rather than teaching a downstream importer to guess. The sample contains only plain cue text, keeping block structure visible before styling and annotations are introduced.

Worked example · synthetic

Both cue durations are 1.750 seconds. Cue one ends at 3.000 and cue two begins at 3.250, leaving 0.250 seconds without either cue active.

Synthetic text example; no network operation has been performed.

WEBVTT

00:00:01.250 --> 00:00:03.000
Fold the blue sheet.

00:00:03.250 --> 00:00:05.000
Place it beside the red sheet.

Check the interpretation

• Check the WEBVTT signature and blank-line boundaries.
• Convert timestamps to a common unit before subtracting.
• Require each end to be later than its own start.