Video & subtitles · Subtitle Toolkit
One master subtitle file for every platform: an SRT and WebVTT workflow
· Why it matters
subtitles srt webvtt file-formats browser-processing
Maintaining separate caption files per platform multiplies errors. This post lays out a workflow with one master file, deterministic conversion to each required format and a check before every upload, all done without uploading the captions to a third party.
Six platforms, six slightly different caption files — how small divergences turn into wrong captions
Separate caption files begin to diverge as soon as a typo is corrected in one copy but not the others. A later timing adjustment creates another fork, and soon nobody can say whether “final-web-v2.vtt” contains the wording approved in “platform-final.srt.” The number of destinations is less important than the number of editable sources claiming to be authoritative.
A reliable workflow keeps one editable master and treats every destination file as disposable output. If a platform changes its requirements, generate that output again from the same source instead of repairing yesterday’s derivative. This makes a difference visible: either the master changed, or the delivery recipe did.
Choose a master format — why keeping one canonical file, in UTF-8, prevents drift between versions
Choose the master format your editorial team can review consistently and store it as UTF-8. SRT is simple and broadly exchanged; WebVTT has a defined web shape and can retain cue settings. ToolAcre reads both as UTF-8 and converts both to one internal model of cue text plus integer millisecond boundaries, so either can serve as the source for this narrow workflow.
Canonical means that corrections flow back to this file. It does not mean the format is universally superior. Keep the original in versioned project storage, name it independently of any destination and resist editing downloaded derivatives, because a corrected derivative that never reaches the master is the next inconsistency.
Convert on demand — producing SRT or WebVTT from the master when a platform requires it, rather than editing copies
Convert only when a destination asks for a format. WebVTT output receives the WEBVTT header, full-stop millisecond separator and no cue identifier lines. SRT output omits the header, uses a comma and numbers cues contiguously from one. The conversion round-trip is exact for timings because both writers format the same whole-millisecond values.
Input is deliberately more tolerant than output: the parser accepts either timestamp separator, optional hours, mixed line endings and a leading byte-order mark. It records unreadable blocks rather than throwing. Read that issue list before export, because a malformed cue is skipped and a beautifully formatted delivery file can therefore contain fewer cues than its source.
Retime per delivery — handling a trimmed intro or added bumper on one platform without touching the master
A destination may add an intro, bumper or slate that the canonical lesson does not contain. Apply that destination-specific offset to a copy, never to the master. A fixed shift adds the same millisecond value to each start and end; a scale multiplies timestamps and is reserved for drift that grows over the programme. Checking a line near both ends distinguishes those faults.
Negative results clamp at zero, and the tool reports how many cues were affected. Clamping loses spacing, so use Undo rather than trying to compensate with a forward shift. The delivery copy should be reproducible from a clean master plus a recorded offset or scale, not from a chain of remembered nudges.
Check before upload — a short list of things to verify in the output file
Before uploading, compare the cue count with the expected source, inspect every parse warning and check a clear line near the start and end against the destination video. Confirm the requested extension and open the file to verify its first line: WEBVTT for VTT, a cue number for ordinary SRT. Spot-check non-ASCII names because the reader assumes UTF-8.
Also review what conversion intentionally omits. Cue identifiers are discarded, and NOTE, STYLE and REGION blocks are skipped on load. Cue settings are preserved and written after the end timestamp even in SRT, where they have no defined effect. If those features matter, this converter is not a lossless archive path for the master.
Worked example: publishing one lecture to a web player, a video platform and a learning management system — the conversions and retimes involved
For one lecture, keep an approved UTF-8 SRT master. Generate WebVTT for the site player and verify the header and cue count. Generate SRT for a video platform without editing it. If a learning system wraps the lecture in a three-second bumper, generate another SRT copy, shift it by positive 3000 milliseconds and check its first and final spoken lines.
When a wording correction arrives, change the master and regenerate all three outputs. Do not patch the web file, platform file and shifted learning-system file independently. The repeated conversion is cheap; investigating which of three hand-edited files contains the approved wording is not.
What this does not cover — translation management and multi-language files, which need their own process
This workflow does not manage translation. Each language needs its own authoritative text, review process and relationship to the picture, and machine conversion between SRT and WebVTT does not translate a word. It also does not encode platform-specific line-length or speaker-label policies, which remain editorial requirements outside structural validation.
The tool transforms one loaded cue set and has no translation memory, reviewer assignments or multilingual package manifest. Use a localisation system for those concerns, then bring each approved language file through this deterministic delivery step.
Takeaway: one source of truth, converted as needed — how the Subtitle Toolkit's convert, retime and clean features fit this loop
One source of truth reduces the problem to two controlled operations: convert to the required representation and retime a derivative only when that delivery has a different clock. Subtitle Toolkit makes those operations explicit and reversible before clamping, while the validation list exposes cues that would otherwise disappear or overlap.
Keep the canonical file untouched, record each destination recipe and regenerate outputs whenever the source changes. The clean workflow is not “one file accepted everywhere”; it is one approved source producing as many disposable, checked delivery files as the project actually needs.