SRT to WebVTT for an HTML video track: a minimal working example

lieber — Tue, 20 Oct 2026 13:56:04 +0000

An editor gave you captions.srt, but your web page uses a native HTML <video> player. The missing step is a WebVTT text track. Here is a two-cue example you can inspect without installing a subtitle editor.

This example handles existing subtitles. It does not create captions from an audio recording.

1. Start with a small SRT

Save this as UTF-8 in captions.srt:

1
00:00:01,250 --> 00:00:02,500
Hello, world!

2
00:00:03,000 --> 00:00:05,750
A second cue.
This line stays below it.

The first cue starts 1.25 seconds into the video and lasts 1.25 seconds. The second lasts 2.75 seconds and contains two lines. Those are useful checks after conversion.

2. Write the equivalent WebVTT

For this plain-text example, the complete captions.vtt is:

WEBVTT

00:00:01.250 --> 00:00:02.500
Hello, world!

00:00:03.000 --> 00:00:05.750
A second cue.
This line stays below it.

Notice the WEBVTT header and the empty line below it. Milliseconds now use dots. The SRT sequence numbers have been omitted; WebVTT can use optional cue identifiers. An empty line separates the cues, while the newline inside the second cue remains part of its text.

For these two cues, you can make the changes by hand. Simply renaming an unchanged SRT file to .vtt does not do them.

Keep the original file. Real-world subtitles can contain markup, positioning, styles or metadata that need a format-aware conversion and a check in the destination player. This example makes no promise to preserve advanced formatting.

3. Attach the track to a video

Put a playable MP4 of at least six seconds in the same folder as captions.vtt. Use a clip you own and name it demo.mp4. Save the following as index.html:

<!doctype html>
<html lang="en">
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>WebVTT track example</title>
<main>
  <h1>Two subtitle cues</h1>
  <video controls width="640" style="max-width:100%;height:auto">
    <source src="demo.mp4" type="video/mp4">
    <track default kind="subtitles" src="captions.vtt"
           srclang="en" label="English">
    Your browser does not support HTML video.
  </video>
  <p>Play the video. If needed, enable English in its subtitle menu.</p>
</main>
</html>

The track's src is relative to this HTML file. srclang identifies the language; label is the name offered to the viewer. Choose kind="captions" when your track also represents relevant sounds and other audio information for accessibility. This short example is a text-track plumbing exercise, not a complete accessible media package.

If you already have FFmpeg installed, a silent ten-second background is enough to test the timing without using anyone's footage:

ffmpeg -f lavfi -i color=c=0x244c40:s=640x360:r=25:d=10 -an -c:v libx264 -pix_fmt yuv420p -movflags +faststart demo.mp4

It contains no speech; the two lines are synthetic test data.

4. Serve the folder over HTTP

From that folder, with Python 3 installed:

python -m http.server --bind 127.0.0.1 8000

Open http://127.0.0.1:8000/ on the same computer. Use this server for local development only. Opening the HTML through file:// can introduce local-file restrictions that distract from the conversion check.

In browser developer tools, inspect the captions.vtt request. It should succeed and be served as text/vtt. When deploying, configure that MIME type on your host if necessary. Keep the HTML, MP4 and VTT on the same origin for this first test. A track on another origin needs deliberate CORS configuration, including the parent media element's crossorigin attribute and appropriate server responses; adding the attribute alone is insufficient.

5. Check the result, not just the extension

Play through the first six seconds. Verify that the first cue begins at 1.25 seconds and ends at 2.50, and the second runs from 3.00 to 5.75. Its two lines should remain separate.

Then replace the second cue's text with 第二行 🙂 and a second line, save as UTF-8, and reload. This catches encoding problems that an English-only fixture can hide. The synthetic MP4 cannot test synchronization with speech: check that separately with your actual video.

If nothing appears, check the VTT request, header, blank lines, timestamp punctuation and the player's subtitle selection before changing the video itself.

For an independent file check, FFprobe can inspect the timestamps:

ffprobe -v error -show_packets -show_entries packet=pts_time,duration_time -of json captions.vtt

Expect two packets with starts 1.250000 and 3.000000, and durations 1.250000 and 2.750000. This checks parsed timing, not browser rendering.

Optional conversion tool

Disclosure: I maintain CueFern's SRT-to-VTT tool. It is an optional browser interface for the conversion step above. The current tools are free, require no account, and process subtitle content in your browser. They accept existing UTF-8 SRT/VTT files up to 5 MB; they do not transcribe video or audio. Check any compatibility warnings and test the result in your target player.

References

Disclosure: This article was drafted with AI assistance. Its subtitle examples were checked against the converter and FFprobe; this does not establish compatibility with every player or editor.

DEV Community: lieber