SRT file format: how to write one that players accept

What an SRT file is and where it is used

An SRT file is a plain text file that holds captions as text plus the times they should appear. YouTube's help centre says it plainly: "Subtitle and caption files contain the text of what is said in the video. It also contains timestamps for when each line of text should be displayed" (official, read October 25, 2026).

YouTube accepts several caption formats, and its supported-files page lists SubRip (.srt), SubViewer (.sbv or .sub), WebVTT (.vtt) and TTML (.ttml). For .srt it says: "Only basic versions of these files are supported. No style info (markup) is recognized. The file must be in plain UTF-8" (official, read October 25, 2026). The same page points new caption file writers at SubRip or SubViewer because "They only require basic timing info".

So the promise of this page is narrow and complete: a plain UTF-8 text file, in the shape YouTube asks for, that a renderer reads. Style tags, positions and languages are out of scope here and are covered by our VTT page.

The format, part by part

A caption block has four parts, in this order. Wikipedia's description of the SubRip format matches the file YouTube shows as an example (third party, read October 25, 2026): the subtitles are "numbered sequentially, starting at 1", the timecode is "hours:minutes:seconds,milliseconds" with two-digit units and three-digit fractions, and "The comma (,) is used for the decimal separator between seconds and milliseconds".

1. The cue number, on its own line, starting at 1 and counting up.
2. The timecode line: start time, then --> with spaces around it, then the end time.
3. The caption text, on one or two lines. Two lines of about 40 characters each fit a phone screen.
4. A blank line. It ends the cue. Delete it and the parser cannot tell where one caption stops and the next begins.

1
00:00:00,000 --> 00:00:04,351
A color cycling animation of the Mandelbrot set, a famous fractal shape.

2
00:00:04,830 --> 00:00:08,568
The colors repeat in smooth bands while the picture slowly moves.

3
00:00:09,029 --> 00:00:13,905
This clip is public domain, released under CC0 on Wikimedia Commons.

How to write one: five steps

You can write an SRT file in any plain text editor, and you can get the timings from an automatic captioner or measure them yourself. The five steps below are how we built the file attached to this page, which you can download and test as-is.

1. Write the caption text first, one sentence or one idea per cue. Our file has three cues and 34 words.
2. Find the times. The fastest honest way is to measure the silences in your recording: this command prints every pause longer than 0.12 seconds below -38 dB.
3. Write the cue as number, then the timecode line with a comma before the milliseconds, then the text, then a blank line. Keep the blank line; it is the part people drop.
4. Check the file before you upload it. The free subtitle checker on this site reads it in your browser and reports the cue count, the reading speed and any overlapping cues.
5. Upload it, or convert it if the target wants WebVTT. A browser <track> element needs .vtt; the same page converts the file in one click and keeps your caption text as written.

Our run of that command on October 26, 2026 found five silences. The first, third and fifth are short pauses inside a sentence; the second and fourth are the gaps between our three narration clips, and they became the cue boundaries 00:00:04,830 and 00:00:09,029. The last cue ends at 00:00:13,905 because that is where the recording ends.

ffmpeg -i narration.wav -af "silencedetect=n=-38dB:d=0.12" -f null -

What happened when we broke the file in eight ways

One correct file, eight copies with one thing changed in each. Each copy went through two parsers: the site's own subtitle checker (the live production build, headless Chromium) and ffmpeg 6.1.1 with libass, which is what draws the caption onto the picture.

Source: our own test on October 26, 2026, on the VPS with ffmpeg 6.1.1 (libass) and the live site in headless Chromium. Method: we copied the shipped file, changed exactly one thing in each copy, then ran every copy through both parsers and read the results. The commands, the exact error strings and the checker output for every copy are in the published log.

Read the rows together. A plain dot instead of the comma was accepted by both parsers, so the comma is the rule of the format but not what these two readers insist on; a space in front of the dot was not forgiven by either. The cue number is where they disagree: libass refused the file without it and our checker did not. The blank line is the other disagreement: our checker treats a missing blank line as a broken block and reads only the first cue, while libass carried on. A file that renders in one player and shows nothing in another is usually one of these, so check them first. Overlapping cues render, but libass moved the later caption up by one line and kept it there (frame below), which a bottom-band measurement cannot see.

Proof that the captions land on the right second

A subtitle file that parses is not the same as a subtitle file that is timed right, so we measured the second part too. We burned our file onto the video with ffmpeg and compared the band where the caption is drawn, frame by frame, with the same band of the video without captions.

Source: our own measurement on October 26, 2026. Method: for each second we cut the bottom 44 pixels of the frame, converted them to grey, and took the mean absolute difference per pixel (scale 0 to 255) between the burned video and the same second of the caption-free video. The 00:04.5 row is the control: that second falls in the measured gap between cue 1 and cue 2, and its 3.57 is the noise of re-encoding a busy picture, not a caption. Every second inside a cue differs by 18.8 to 25.4, about five to seven times the control.

A file you can download and test

Everything below was made by us on October 26, 2026. The video is an 8-second excerpt of a CC0 animation from Wikimedia Commons (Mandelbrot Set Color Cycling Video 1080p 4) with our own spoken narration; the subtitle file is the one whose timings we measured; the burned video is the result of running the subtitle filter over the first one.

• Download narration.srt (306 bytes): the subtitle file, in the format above.
• Download narration.vtt (290 bytes): the same three cues converted to WebVTT by the site's own converter, with a WEBVTT header and dot separators.

The two text files are the ones this page describes. Download the .srt, open it in any text editor, and change one number: that is the whole edit loop.

Check your own file before you upload it

The fastest way to know whether your file will work is to read it with a checker. The free Koldflux subtitle checker runs in your browser, so the file never leaves your device, and it reports the things that break captions on a phone: cues that flash past, overlapping timings and lines that are too long.

We ran it on our file on October 26, 2026: it read 3 cues, 34 words, 205 characters, an average reading speed of 15.8 characters per second, 72 characters on the longest line, 0 overlapping cues, and it reported that the last cue ends at 00:00:13,905, which is the same last cue we measured with ffmpeg. Run it on a file you made and compare.

What we did not test

We tested two parsers on one real file, not every player in the world. Here is exactly where the limits are.

We did not test a phone or a desktop player. We did not upload a file to YouTube, Instagram or TikTok, and we did not check how any of them handled our file. We could not find a readable, specific user report on phone playback of a hand-made .srt file, so we do not quote one. VideoLAN's own feature list names SubRIP among the text subtitle formats VLC reads and the project ships separate VLC apps for Android and iOS (official, read October 25, 2026), but that is the vendor's list, not our test.

We did not test style markup, the <b>, <i> and <u> tags that some tools add, positioning, right-to-left scripts, or non-Latin characters. YouTube says it does not recognize markup in .srt files (official, read October 25, 2026).

Our narration is synthetic speech from a local text-to-speech model and our footage is a CC0 animation with the last frame held for 6 seconds, so the timings are clean. A recording with music, room echo or two speakers talking over each other is a harder timing job and we did not test it.

What to do next

The situation you are in decides the next step.

• The platform wants a .vtt file, or your web player shows nothing: convert the file, because a browser <track> element only reads WebVTT.
• Your captions show up but drift out of sync with the speech: the timings are wrong, not the format, so shift them rather than rebuild the file.
• A caption is too long to read on a phone: split the cue into two and shorten the lines, then check the reading speed again.
• The platform accepts the file but shows no captions: check the blank line between cues first, then the comma before the milliseconds.