Why WebVTT subtitles in Plex don't work

I recently noticed that some videos I have downloaded from the web show a weird issue when playing them with Plex. As these were playing fine on the webpages I found them, it was odd that there would be any compatibility issue (Plex plays way more formats than what browsers support).

On the other hand, Plex clearly told me this was caused by a transcoder issue:

conversion failed. the transcoder exited due to an error

Changing players didn’t matter, this was an issue affecting all platforms - even when using the web player in the browser! The debug logs also confirmed this was an issue with the transcoder:

Sep 14 11:12:36 localhost PlexMediaServer[34961]: [Transcoder] Decoder (codec none) not found for input stream #0:0

Sep 14 11:12:36 localhost PlexMediaServer[34961]: Transcode runner appears to have died.

So for some reason, Plex tries to decode something with a codec called none? That doesn’t make much sense. I looked at the streams with ffprobe and saw that stream #0:0 was a subtitle stream - and it indeed had no coded defined!

  Stream #0:0(eng): Subtitle: none (default)
    Metadata:
      BPS             : 118
      DURATION        : 01:30:55.025000000
      NUMBER_OF_FRAMES: 1242
      NUMBER_OF_BYTES : 80709

Looking at our video in Plex again showed the same thing: A subtitle track in english with NONE as the format.

And this is the moment I realized I could play this video with a workaround - just disable the subtitle in the UI, and the video plays just fine 🥳.

But why is this happening?

Obviously having to manually deselect subtitles is not great - also, if I have them, why can’t I use the subtitles?

A quick Google research revealed that im not the first one to have this issue ¹ and people already identified some of the root causes. And the best lead I found was that this is related to how ffmpeg handles WebVTT subtitles, but I couldn’t find any further details in the Plex forums and the workarounds weren’t great.

Root Cause

It took me some time to track down the details, but I eventually figured out what is going on:

WebVTT is a standard for encoding subtitles as XML data. It’s a W3C standard and the primary use case is for displaying subtitles (“text tracks”) on web video. So it makes sense I would encounter these in videos I found on the web.

Where this gets complicated is when these subtitles aren’t just loaded as part of a website along the video, but when they are stored in the video file itself. There are two standards of how to include WebVTT subtitles in a container: as D_WEBVTT/SUBTITLES (following WebM specs) or as the more recent S_TEXT/WEBVTT (part of the Matroska spec).

Unfortunately this is where the problems start. The D_WEBVTT/SUBTITLES never really found any adoption so almost all files store these subtitles as S_TEXT/WEBVTT. Unfortunately ffmpeg never implemented the Matroska way. So when trying to load these files ffmpeg simple reads the format as NONE - as in “none of the codecs I support”.

There’s a lot of files floating around with this codec id because youtube-dl (and possibly many other tools) follow the Matroska spec. People even reported this issue to the youtube-dl developers².

The FFmpeg Project is aware of this issue, but unfortunately the bug is still open 4 years after it was opened³.

Workaround

As Plex doesn’t seem to select embedded subtitles automatically if there is an external one present, the easiest way to work around this is to extract the subtitles (and tell ffmpeg the format explicitly) into a external file:

for f in *.mkv; do ffmpeg -c:s webvtt -i "$f" "${f%.mkv}.en.vtt";done

Conclusion

There are multiple ways this could be fixed in Plex:

Wait for FFMPEG to fix this (unlikely, as the ffmpeg bug is already 4 years old)
Plex could blacklist “None” subtitles / don’t index them so the client’s won’t select them under any circumstance. This comes at the cost of not being able to use these subtitles, but that’s already not the case.
As plex itself seems to extract the right codec id in the file details (something I only noticed later, FWIW: mediainfo also shows the correct codec. They could add a flag before calling ffmpeg in the transcoder to manually override the codec type so it’s not None? With #idx being the track with the S_TEXT/WEBVTT subtitles this is a single parameter: ffmpeg -c:#idx webvtt -i $file.
Alternatively plex could also fix the underlying issue in the the embedded ffmpeg in Plex (and hopefulyl share the fix with the ffmpeg project).