FFmpeg: Convert SRT to VTT for the WordPress Video Block

The Video block's text tracks are WebVTT. WordPress's block documentation states it without any alternative: "The tracks are formatted in WebVTT format (.vtt files or Web Video Text Tracks)." So if your captions came out of an editor or a transcription service as .srt, you convert first and upload second.

The conversion itself is one command. The part worth your attention is checking what came out — and for once you can check it against something official, because the same documentation page ships a complete example .vtt file.

The command

ffmpeg -i captions.srt captions.vtt

Two parts, no flags:

• -i captions.srt — the input subtitle file. Run the command from the folder the file is in, or give it a full path.
• captions.vtt — the output path. This is the file you will hand to the Video block.

FFmpeg's own documentation for subtitle muxing is not quoted anywhere on this page, so if you need to pin the encoder explicitly on your build, check FFmpeg's official documentation. For the WordPress case it does not matter much, because the output is plain text you can open and verify by eye — which is exactly what the next section does.

What the output has to look like, per WordPress

Here is the example file from the Video block documentation, verbatim:

WEBVTT

NOTE State of the Word is the annual keynote
address celebrating the progress of the open
source WordPress project and offering a glimpse
into its future.

0:02:14.000 --> 0:02:15.000
Konbanwa

0:02:16.000 --> 0:02:17.000
And howdy.

0:02:18.000 --> 0:02:20.000
And thanks for being here, everyone.

Four things in that sample are worth comparing against your converted file.

1. The first line is WEBVTT. The W3C WebVTT specification (Candidate Recommendation Draft, 20 May 2026) requires the file to open with "The string 'WEBVTT'". An SRT file has no such header, so this line is something the conversion has to add. If the top of your output is a cue number instead, the conversion did not happen.

2. The milliseconds are separated by a period. The W3C spec is explicit about the character: "Two ASCII digits, representing the seconds as a base ten integer in the range 0 ≤ seconds ≤ 59. A U+002E FULL STOP character (.). Three ASCII digits, representing the thousandths of a second". SRT files use a comma in that position. This is the real work of the conversion, and it is why renaming the extension does nothing — the two formats differ at the byte level, not just in the file name.

3. The hour field has no leading zero. WordPress's example writes 0:02:14.000, not 00:02:14.000. Worth knowing before you assume your converter produced something malformed because the digit count differs from your source file.

4. There are no cue numbers. SRT puts a sequential number above every timestamp line; WordPress's example has none. The W3C spec lists the identifier as "Optionally, a WebVTT cue identifier followed by a WebVTT line terminator" — optional, in other words. A converted file that keeps the numbers and one that drops them are both shaped like valid WebVTT.

The NOTE block in WordPress's example is not something a conversion produces. Our own SRT → VTT converter does three things: it prepends WEBVTT, it changes the , in the timestamps to ., and it leaves the rest of the structure alone. Nothing gets added, so nothing is missing if your output has no NOTE block.

Variations

Convert a whole folder at once. One file per language adds up quickly:

for f in *.srt; do ffmpeg -i "$f" "${f%.srt}.vtt"; done

Pull subtitles out of a video container. If the captions are a stream inside the video rather than a separate file, you have to select that stream — and FFmpeg's documentation warns that mapping is all-or-nothing: "When -map is used, only user-mapped streams are included in that output file, with one possible exception for filtergraph outputs."

ffmpeg -i input.mkv -map 0:s:0 captions.vtt

Name the output so WordPress leaves it alone. The WordPress.com upload guidance is specific here: "Name your files using letters and numbers. WordPress replaces other characters with a hyphen (-), so naming files correctly before you upload them keeps their names predictable." Something like captions-en.vtt survives untouched.

Check first whether a track already exists. On a VideoPress video you may not need this command at all: "VideoPress generates a subtitle track automatically for each video you upload, so a video may already carry a track before you add one of your own." The documentation also warns that the transcript is not ready the instant the upload finishes — if the track opens with a single empty subtitle, transcription is still running and you should check again later.

Label the track as Captions, not Subtitles

Once the .vtt is attached, the Kind setting decides how it is presented, and the two obvious candidates mean different things in WordPress's own wording:

• Subtitles — "Translations of the dialogue in the video for when audio is available but not understood. Subtitles are shown over the video."
• Captions — "Transcription of the dialogue, sound effects, musical cues, and other audio information for when the viewer is deaf/hard of hearing or the video is muted."

If your file is a transcript of the original language rather than a translation of it, the definitions above put it under Captions. Pick Subtitles only if you translated the dialogue — and remember that the Source language field is mandatory in that case.

No FFmpeg? Convert it here

If this is a one-off, installing a command-line tool to swap commas for periods is more setup than the job deserves.

This runs inside your browser tab — the file is read and rewritten locally rather than uploaded to a server, which matters when the captions belong to a client video that has not gone live yet. The reverse direction is at VTT to SRT, and SRT vs VTT covers what that direction costs you.

Troubleshooting

The upload is rejected outright. On a self-hosted site, the documented editor message for an unsupported type is "Sorry, this file type is not supported here." On a Multisite network there is a second gate with its own wording — "Sorry, this file type is not permitted for security reasons" — and the official note explains that adding extensions to the network's Upload file types field "will NOT work unless you've added them using the upload_mimes filter". For reference, WordPress core's default MIME map gives vtt its own entry, text/vtt, while srt sits under the generic text/plain.

WordPress.com says "This file cannot be processed by the web server." The help center answers this one directly: "The file type is not supported. This message is not about the file's size." Do not go compress anything — check the extension and the conversion first.

The file uploads but no captions appear. Two documented causes, both in the block settings rather than in your file. On Kind: "If omitted, the default kind is Subtitles. If the attribute contains an invalid value, it will use Metadata." Metadata tracks are described as data "meant for javascript to parse and do something with. These aren't shown to the user." On language: "It must be a valid BCP 47 language tag. If the Kind attribute is set to Subtitles, then the Source language must be defined."

The track is in the Media Library but not on the video. A file sitting in the library is not attached to anything. It has to go in through the block's Text tracks option — the feature that "will allow you to display timed text tracks (such as subtitles or captions) when the media is playing."

FAQ

Can I just rename my .srt file to .vtt? No. WebVTT requires the WEBVTT header line, and the W3C spec calls for a U+002E FULL STOP before the milliseconds where SRT uses a comma. Renaming changes neither.

Does the WordPress Video block accept SRT files? The Video block documentation names only WebVTT for text tracks, and WordPress.com's accepted file types list has exactly one subtitle entry: ".vtt (text captions for video)". The VideoPress subtitle manager is a different tool with a wider list that does include .srt. See adding subtitles to a WordPress video for which path applies to your site.

Does the converted file need to be UTF-8? Yes. The W3C spec states that "A WebVTT file must consist of a WebVTT file body encoded as UTF-8 and labeled with the MIME type text/vtt". The MIME half of that is served by your host, not by your file.

Can WordPress burn the captions into the picture instead? Nothing in WordPress's documentation describes a burn-in feature — subtitles there are always separate text tracks. If you need text baked into the frames, do it before upload with burn subtitles to video.

Which do I upload if I have both formats? The .vtt, for the Video block. Keep the .srt as your working copy rather than deleting it and regenerating it later from the .vtt: the reverse direction is lossy. Our VTT → SRT converter has to drop the cue settings that sit after --> — position, line, align — because SRT has no way to carry them.

Quotes from the WordPress Video block documentation, the WordPress.com help center, WordPress core's wp_get_mime_types(), FFmpeg's documentation, and the W3C WebVTT specification, checked 16 September 2026. More command-line walkthroughs in the FFmpeg hub, and the browser-based converters are at all Clapr tools.