Manatee

An SRT subtitle file that will not load or is rejected as invalid

· 7 min read

An SRT file not working usually has one of four faults. It was saved as rich text instead of plain text, it is a different subtitle format with .srt on the end, its timing lines are malformed, or the player cannot find it because of where it sits or what it is called. An SRT is plain text with a strict layout, so you can look inside and see which fault you have in about a minute.

What a valid SRT file looks like

1
00:00:01,000 --> 00:00:04,000
First line of dialogue.

2
00:00:04,500 --> 00:00:07,250
A second caption, which can
run onto two rows.

Every caption is a block of four things: a number, a timing line, one or more lines of text, and an empty line to close it. The timing is hours, minutes, seconds and milliseconds, with a comma before the milliseconds. The arrow is two hyphens and a greater-than sign with a space on each side. Players and upload forms differ in how forgiving they are, but this layout works in all of them.

Look inside the file

Open Terminal and run these two commands, dragging your own file in place of the example path:

file ~/Movies/film.srt
head -12 ~/Movies/film.srt

file reports what the contents really are, whatever the name says. head prints the first twelve lines. Read the results like this:

  • ASCII text or UTF-8 text, and the layout above. The file is sound. Skip to the section on players.
  • Rich Text Format data, or a first line starting with {\rtf1. It was saved from a word processor as rich text.
  • HTML document. A web page was saved in place of the subtitles, often a download page or an error page. Download the file again.
  • A first line reading WEBVTT. It is a WebVTT file. [Script Info] at the top means ASS or SSA, a timing line like 0:00:01.000,0:00:04.000 means SBV, and frame numbers in curly braces such as {120}{180} mean a SUB file.
  • With CR line terminators. The line endings are in an old style that many players read as one endless line. tr '\r' '\n' < film.srt > film-fixed.srt rewrites them. CRLF line terminators, the Windows style, are fine.
  • Text that looks right except for the accented letters. That is an encoding problem, covered in subtitles that show strange characters on a Mac.

Fix a file saved as rich text

TextEdit starts every new document as rich text, and a rich text file keeps its formatting codes no matter what you name it. Often the real name is film.srt.rtf with the last part hidden: select the file, press Command-I, and look under Name & Extension to see.

One command writes a clean plain text copy and leaves the original alone:

textutil -convert txt -format rtf -encoding UTF-8 -output ~/Movies/film-fixed.srt ~/Movies/film.srt

Or do it in TextEdit:

  1. If the name ends in .srt.rtf, open the file in TextEdit and check that you see captions, not codes.
  2. Choose Format, Make Plain Text.
  3. Hold Option and choose File, Save As. Name it film.srt, set Plain Text Encoding to Unicode (UTF-8), and save.
  4. Check the name with Command-I once more and remove a trailing .txt if one was added.

Then look at the arrows. In a rich text document, Smart Dashes replaces the two hyphens with a single long dash, which breaks every timing line. Use Edit, Find, Find and Replace to put --> back.

Fix a file that is another format in disguise

Renaming a .vtt to .srt changes the label and nothing else. WebVTT has a header line and puts a period before the milliseconds, ASS and SSA wrap every line in styling fields, and SBV has no caption numbers at all. A strict player or upload form sees the mismatch at once.

Converting rewrites the contents. Manatee accepts SRT, VTT, ASS, SSA, SUB and SBV and writes SRT. Rename a copy of the file to its true extension first, so there is no doubt about what is being read. Then drop it onto the menu bar icon or into the window, choose Convert, and pick SRT. The result is a new copy written beside the original, which is never modified, and nothing is uploaded. Every feature is free for 24 hours, then it is $9 once.

To do it by hand, the guides for VTT, ASS or SSA and SBV each walk through the edits.

The honest limits: Manatee converts the format. It does not shift captions that run early or late, it does not translate, and SRT is the only subtitle format it writes, so it cannot help with a site that insists on VTT.

Repair broken timing lines

Hand-edited files tend to break in the same few ways:

  • A period where the comma belongs, as in 00:00:04.500.
  • Missing hours, as in 00:07,500.
  • An arrow typed as ->, or with no spaces around it.
  • No empty line between two captions, or an empty line in the middle of one caption’s text, which ends it early.
  • An end time earlier than the start time.

This command lists the lines that look like timings but do not match the correct pattern, each with its line number:

grep -n -E '[0-9]:[0-9]{2}' film.srt | grep -v -E ':[0-9]{2}:[0-9]{2}:[0-9]{2},[0-9]{3} --> [0-9]{2}:[0-9]{2}:[0-9]{2},[0-9]{3}'

No output means every timing line is well formed. Dialogue that mentions a time of day will show up too; ignore those lines. Fix the rest in TextEdit in plain text mode and save.

When the file is fine but nothing appears

  • QuickTime Player does not load a separate SRT file. Its View, Subtitles menu lists only subtitle tracks stored inside the video. An SRT sitting beside the movie does nothing there. You need a player that reads subtitle files, or a video with the subtitles built in.
  • Players that do read subtitle files look for a matching name. Keep the SRT in the same folder as the video with the same name: film.mp4 and film.srt. A language code before the extension, as in film.en.srt, is widely understood as well.
  • An upload form may not want SRT at all. Read its list of accepted formats before you assume the file is at fault.

Questions

Can I rename a .txt file to .srt? Yes, if the contents already follow the SRT layout. A plain text file with numbered captions and correct timing lines only needs the right extension. A .vtt or .ass file needs converting, not renaming.

Does an SRT file need a special first line? No. SRT has no header, and the file begins with the number of the first caption. If the first line is WEBVTT, the file is not an SRT.

The subtitles load but run a few seconds early or late. Is the file invalid? No. That file was timed for a different cut of the video. The format is fine and the timing is off, which calls for a subtitle editor or a subtitle file made for your version. Converting does not change timing.