Move every subtitle cue earlier or later

What this works out

A subtitle sidecar is a sequence of text cues placed on a media timeline. When every caption appears the same amount too soon or too late, the wording is not wrong and the individual cue durations are not wrong — the complete timeline has one constant offset.

This tool measures that offset in whole milliseconds and writes a corrected .srt or .vtt artifact. The media file is not needed because the operation is entirely inside the subtitle timeline: every recognised start and end gets the same signed change.

The method

The arithmetic is deliberately small:

offset_ms = round(offset_seconds × 1,000)

Later:   new_time_ms = old_time_ms + offset_ms
Earlier: new_time_ms = old_time_ms - offset_ms

Applying the same value to both ends preserves a cue’s duration. A cue from 00:00:01,250 to 00:00:03,500 lasts 2.250 seconds; after a two-second delay it runs from 00:00:03,250 to 00:00:05,500 and still lasts 2.250 seconds. The relationship between cues is preserved too: if two cues overlap by half a second before the shift, they overlap by half a second afterwards.

What requires care is recognising where that arithmetic belongs. A blind search for timestamp-shaped text would also change times written in dialogue, comments or CSS. The file is therefore walked as blank-line-separated blocks. For SRT, a cue timing is the first line or the line after its numeric counter. For WebVTT, it is the first line or the line after an optional cue identifier; the WEBVTT header and NOTE, STYLE and REGION blocks are structural and are never treated as cues.

The complete timing line must match before anything changes. SRT uses a comma before milliseconds:

00:01:02,000 --> 00:01:04,250

WebVTT uses a full stop, may omit zero hours, and can carry settings after the end:

01:02.000 --> 01:04.250 position:50% align:middle

The W3C grammar requires whitespace around WebVTT’s -->, an end later than the start, and cues ordered by their start time. Those constraints are checked instead of quietly rewriting a line that only resembles a cue.

Before you read on

A subtitle appears at 00:01.250, but its spoken word begins at 00:03.250. Which change aligns it?

• AMove it earlier by two seconds.

  That would put it at zero and make the early error four seconds wide.

• BMove it later by two seconds.

  Yes. Later adds 2,000 milliseconds, placing the cue at the speech.

• CMake the cue two seconds longer.

  Duration is not the mismatch here; both of the cue boundaries need the same offset.

Move it later by two seconds. Later adds 2,000 milliseconds to the start and end together, so 00:01.250 becomes 00:03.250 without changing how long the subtitle remains visible. Earlier is for the opposite symptom: text that appears after the matching speech.

What happens at the start of the timeline

Adding a delay can never make a timestamp negative. Subtracting one can. The file format has no representation for a cue at minus half a second, so the tool makes that boundary visible instead of wrapping the value or writing an invalid minus sign.

• If the shifted end is at or before zero, none of the cue can appear and the cue is removed.
• If the shifted start is negative but the end is still positive, Clamp its start to 00:00 keeps the visible remainder and shortens only that cue.
• Remove the whole cue discards a crossing cue instead. That is useful when its opening words belong to content that was cut away.

Numeric SRT counters and WebVTT identifiers are not renumbered after a removal. They can be referenced outside the file, and a gap is safer than silently changing those references.

A worked example

interview.srt contains two cues:

1
00:00:01,250 --> 00:00:03,500
The first subtitle.

2
00:01:02,000 --> 00:01:04,250
The second subtitle.

With Later and 2 seconds, interview-shifted.srt is:

1
00:00:03,250 --> 00:00:05,500
The first subtitle.

2
00:01:04,000 --> 00:01:06,250
The second subtitle.

Reading	Value
Cues shifted	2
Cues removed	0
Subtitle format	SubRip (SRT)
Offset applied	2.000 seconds

The formula test asserts the complete output byte for byte, including the CRLF line endings, filename, MIME type and all four readings. A separate test covers WebVTT identifiers, cue settings, comments and style blocks, and boundary tests cover clamping, removal, the one-hour transition, encoding errors, cancellation and malformed timing.

SRT and WebVTT are similar, not interchangeable

The Library of Congress describes SRT as a simple text format built from a counter, start and end, subtitle text and a blank separator. It is widely implemented but not formally standardised, and its historic character encoding is not self-declaring. That is why this tool accepts the common timing grammar but refuses to guess non-UTF-8 text.

WebVTT is specified for HTML text tracks. Its first line is the WEBVTT magic header, its MIME type is text/vtt, its timestamps use a dot, and cues may have identifiers and positioning settings. Comments and style or region blocks are also part of the document. The output stays in the input format; shifting is not conversion, so an SRT remains SRT and a WebVTT file remains WebVTT.

What it does not do

It does not stretch or compress a timeline. If a caption is one second late at the beginning and six seconds late at the end, use a resynchronisation workflow that maps two known points and rescales every timestamp. One constant offset would only move where the growing error begins.

It also does not modify embedded subtitle tracks inside a video container, and it does not inspect the media to discover the offset automatically. The input is the plain-text sidecar file. If the mismatch began because you trim a WAV file, use the exact amount removed as the subtitle offset; if the subtitle text itself needs cleaning, sort lines and other generic text operations are deliberately a separate job.

WebVTT cue payloads can contain inline timestamp tags for karaoke-like word timing. Those inner times are absolute points inside the outer cue. The tool refuses such a cue with an explanation: moving only the outer pair would leave an invalid file, while changing every possible payload construct belongs in a dedicated WebVTT editor rather than a constant-offset shifter.