HTML 5 Video Player with VTT subtitles + SharePoint 2013 on-prem


Recently I have encountered a strange error using HTML 5 video player and SharePoint 2013. Customers wanted to embed a few video files with subtitles to their portal. They used mp4 videos and WebVVT subtitles. The problem was that they didn't see subtitles in IE.

Html5 Video element is used to embed video content in a document. The video element contains one or more video sources. To specify a video source, use either the src attribute or the source element; the browser will choose the most suitable one.

WebVTT is a format for displaying timed text tracks (e.g. subtitles or captions) with the track element. The primary purpose of WebVTT files is to add text overlays to a video. WebVTT is a text based format, which must be encoded in UTF-8 format. Where you can use spaces you can also use tabs. More information about WebVTT can be found here.


At first I thought there is a problem with their HTML, and I was almost right! They used the following html to embed a video player:

<video width="640" height="480" controls>
    <source src="video.mp4" type="video/mp4" />
    <track src="subtitles.vtt" kind="subtitles" srclang="en" label="English" ></track>
    <!-- ... -->

They didn't know that source and track are empty elements. An empty element is any element that can not, by definition, have any content in between the start and end tags, but the only type of data that empty elements are allowed to have are attributes. Some examples of void elements that you are probably already familiar with include the img (image), br (break), hr (horizontal rule), and meta tags. Of course, all of the tags that we mentioned can have attributes, but the reason they are empty elements is that you will never see any content in between a start and end tag for an empty element.

According to best practices it is recommended to use these elements in the following way:

<video width="640" height="480" controls>
    <source src="video.mp4" type="video/mp4">
    <track src="subtitles.vtt" kind="subtitles" srclang="en" label="English">
    <!-- ... -->

Unfortunately, this was not the cause of the issue :)

I opened the browser console and saw the error:

    MEDIA12604: Text Track: Unknown MIME type. hr=8007000b.

After googling for a couple of minutes I found that IE won't work with WebVTT files if they don't have a correct mime-type set. The MIME type of WebVTT is text/vtt.

We can set a correct mime-type for .vvt file by modifying web.config. There are several ways to do it:

  • Update web.config manually - a very risky way.
  • Use IIS Manager UI - safe and easy to do, but it will has to be done on each WFE server.
  • SPWebConfigModification - can be used from .NET code as well as from PowerShell, a recommended way if it is required to automatically update a few hundreds of WFE servers in your farm.

Customers have only two WFE servers, so I decided to do everything manually through IIS Manager. I selected the corresponding web application in IIS Manager...

... and then added a new mime-type ...

After this, I have checked the web.config, there were the following lines:

        <!-- ... -->
        <remove fileExtension=".vtt" />
        <mimeMap fileExtension=".vtt" mimeType="text/vtt" />
        <!-- ... -->

But nothing changed and it was confusing. I thought I did everything right. After some more googling I realized that SharePoint looks to the Server Level for the MIME Map. So I have set a mime type on a server level and everything works fine now.


Sometimes you need to understand how system works, from bottom to the top. From hardware to javascript in a mobile browser, this skill allows to solve problems very fast and efficiently.