WebVTT Closed caption and subtitling support

The player framework includes support for two different closed captioning standards: TTML and WebVTT (formerly called SRT and WebSRT). This page will describe how to add WebVTT support to your application.

Usage guide (Xaml)

1. Follow the instructions to create a new app that uses the Microsoft Media Platform Player Framework for Xaml.

2. Add 'Microsoft Player Framework WebVTT Plugin' to your project References. Under References --> Microsoft--> Extensions
WebVTT-xaml.png

3. Modify the MediaPlayer control Xaml to adds the WebVTT plugin to the plugins collection on the player framework and enable the "CC" button on the toolbar to allow the user to turn captions on and off or switch between different languages.

For Windows 8, add the namespace:
xmlns:webvtt="using:Microsoft.PlayerFramework.WebVTT"

For Windows Phone 8, add the namespace using Silverlight notation:
xmlns:webvtt="clr-namespace:Microsoft.PlayerFramework.WebVTT;assembly=Microsoft.PlayerFramework.WebVTT"

<mmppf:MediaPlayer Source="http://smf.blob.core.windows.net/samples/win8/captions/movie.mp4" IsCaptionSelectionVisible="True">
    <mmppf:MediaPlayer.Plugins>
        <webvtt:WebVTTPlugin/>
    </mmppf:MediaPlayer.Plugins>
</mmppf:MediaPlayer>
Note: alternatively, you can add the plugin in your code behind

4. Further modify the Xaml by adding Caption objects to the MediaPlayer.AvailableCaptions collection property and provide descriptions and URLs for each WebVTT file.
<mmppf:MediaPlayer x:Name="player" Source="http://smf.blob.core.windows.net/samples/win8/captions/movie.mp4" IsCaptionSelectionVisible="True">
    <mmppf:MediaPlayer.Plugins>
        <webvtt:WebVTTPlugin/>
    </mmppf:MediaPlayer.Plugins>
    <mmppf:MediaPlayer.AvailableCaptions>
        <mmppf:Caption Description="English" Source="http://smf.blob.core.windows.net/samples/win8/captions/captions.vtt"/>
        <mmppf:Caption Description="German" Source="http://smf.blob.core.windows.net/samples/win8/captions/de-captions.vtt"/>
    </mmppf:MediaPlayer.AvailableCaptions>
</mmppf:MediaPlayer>

5. Optionally, if you'd like to set the default caption track (instead of forcing your user to choose one in the UI), from code behind, just set the SelectedCaption property to the desired Caption object:
public MainPage()
{
    this.InitializeComponent();
    player.SelectedCaption = player.AvailableCaptions.FirstOrDefault(c => c.Description == "English");
}

That's all you need to see WebVTT captions in your app.
Warning: In accordance with the WebVTT spec, WebVTT files must be encoded as UTF-8 text files and use the MIME type: "text/vtt".

Usage guide (JavaScript)

For JavaScript, we rely on built in IE10 WebVTT support to do the work for us. This means that there is no extra plugin required to add to your project references and HTML.

1. Add the WebVTT tracks to the MediaPlayer control's data-win-options JSON initialization attribute. Optionally include isCaptionsVisible: true to enable the "CC" button on the toolbar to allow the user to turn captions on and off or switch between different languages.
<div data-win-control="PlayerFramework.MediaPlayer" data-win-options="{
    width: 640,
    height: 360,
    autoplay: true,
    isCaptionsVisible: true,
    src: 'http://smf.blob.core.windows.net/samples/win8/captions/movie.mp4',
    tracks: [
        {
            kind: 'subtitles',
            label: 'English',
            src: 'http://smf.blob.core.windows.net/samples/win8/captions/captions.vtt',
            srclang: 'en',
            default: true
        },
        {
            kind: 'subtitles',
            label: 'German',
            src: 'http://smf.blob.core.windows.net/samples/win8/captions/de-captions.vtt',
            srclang: 'de'
        }
    ]
}"></div>

2. If you using the optional TimedText plugin for TTML support, you will need to disable this as to not interfere with WebVTT.
<div data-win-control="PlayerFramework.MediaPlayer" data-win-options="{
    ...
    captionsPlugin: {
        isEnabled: false
    }
}"></div>

That's all you need to see WebVTT captions in your app.
Warning: In accordance with the WebVTT spec, WebVTT files must be encoded as UTF-8 text files and use the MIME type: "text/vtt".

Caption positioning

Note: currently, only the Xaml version honors custom WebVTT positioning where the captions appear someone other than at the bottom of the video. This is due to the fact that we rely on IE10 for WebVTT rendering (which does not support positioning at this time).

There are two ways to alter the positioning of the captions.
1. Set the positioning tokens in the WebVTT file per cue. These will be honored at runtime to help support custom x/y offsets, line # positioning as well as RTL and vertical layouts.
2. Change the default padding of the caption rendering area by setting the CaptionsPanelStyle property on WebVTTPlugin. For example:
xmlns:webvtt_rt="using:Microsoft.WebVTT"

<mmppf:MediaPlayer.Plugins>
    <webvtt:WebVTTPlugin>
        <webvtt:WebVTTPlugin.CaptionsPanelStyle>
            <Style TargetType="webvtt_rt:WebVTTPanel">
                <Setter Property="PaddingPercent" Value="10,0,10,10"/>
            </Style>
        </webvtt:WebVTTPlugin.CaptionsPanelStyle>    
    </webvtt:WebVTTPlugin>
</mmppf:MediaPlayer.Plugins>
Note: PaddingPercent uses percentage values from 0-100. This allows the padding to change dynamically based on the size of the player.
By default PaddingPercent is set to 0,0,0,10 to create room for the control panel.

Caption styling

Note: currently, only the Xaml version honors custom WebVTT styling where the captions show in different colors, fonts, or use decorations like bold or italics. This is due to the fact that we rely on IE10 for WebVTT rendering (which does not support positioning at this time).

There are many ways to alter the styling of the captions depending on what you are after.
1. Provide styling information in the content of each WebVTT cue. These will be honored at runtime to help support bold, italics, and line breaks.
2. Change the colors, outline and font of all caption by setting the CaptionsPanelStyle property on WebVTTPlugin. For example:
xmlns:webvtt_rt="using:Microsoft.WebVTT"

<mmppf:MediaPlayer.Plugins>
    <webvtt:WebVTTPlugin>
        <webvtt:WebVTTPlugin.CaptionsPanelStyle>
            <Style TargetType="webvtt_rt:WebVTTPanel">
                <Setter Property="FontSizePercent" Value="10"/>
                <Setter Property="OutlineBrush" Value="Blue"/>
                <Setter Property="InnerBrush" Value="Yellow"/>
                <Setter Property="OutlineWidth" Value="1.5"/>
            </Style>
        </webvtt:WebVTTPlugin.CaptionsPanelStyle>
    </webvtt:WebVTTPlugin>
</mmppf:MediaPlayer.Plugins>
Note: OutlineWidth can be set to 0 to disable outlines.
webvtt_styling2.png

3. You can further customize the look and feel of the player through Xaml by modifying the default Box style. This is the control that contains each cue. For example:
<mmppf:MediaPlayer.Plugins>
    <webvtt:WebVTTPlugin>
        <webvtt:WebVTTPlugin.CaptionsPanelStyle>
            <Style TargetType="webvtt_rt:WebVTTPanel">
                <Setter Property="BoxStyle">
                    <Setter.Value>
                        <Style TargetType="webvtt_rt:BoxElement">
                            <Setter Property="HorizontalAlignment" Value="Stretch"/>
                            <Setter Property="VerticalAlignment" Value="Stretch"/>
                            <Setter Property="Padding" Value="3"/>
                            <Setter Property="Background" Value="#88000000"/>
                        </Style>
                    </Setter.Value>
                </Setter>
            </Style>
        </webvtt:WebVTTPlugin.CaptionsPanelStyle>
    </webvtt:WebVTTPlugin>
</mmppf:MediaPlayer.Plugins>
webvtt_styling3.png


4. To go even deeper, you can customize the TextBlock within the box to control things like font family. For example:
<mmppf:MediaPlayer.Plugins>
    <webvtt:WebVTTPlugin>
        <webvtt:WebVTTPlugin.CaptionsPanelStyle>
            <Style TargetType="webvtt_rt:WebVTTPanel">
                <Setter Property="BoxStyle">
                    <Setter.Value>
                        <Style TargetType="webvtt_rt:BoxElement">
                            <Setter Property="BlockStyle">
                                <Setter.Value>
                                    <Style TargetType="TextBlock">
                                        <Setter Property="FontFamily" Value="MS Sans Serif"/>
                                    </Style>
                                </Setter.Value>
                            </Setter>
                        </Style>
                    </Setter.Value>
                </Setter>
            </Style>
        </webvtt:WebVTTPlugin.CaptionsPanelStyle>
    </webvtt:WebVTTPlugin>
</mmppf:MediaPlayer.Plugins>

5. Lastly, you can add an event handler to the WebVTTPlugin.CaptionPanel.NodeRendering event to get code level access to each part (or TextBlock inline) for each cue being rendered. For example:
public WebVTTPage()
{
    this.InitializeComponent();
    player.Initialized += player_Initialized;
}

void player_Initialized(object sender, RoutedEventArgs e)
{
    var webVTT = player.GetWebVTTPlugin();
    webVTT.CaptionsPanel.NodeRendering += CaptionsPanel_NodeRendering;
}

void CaptionsPanel_NodeRendering(object sender, Microsoft.WebVTT.NodeRenderingEventArgs e)
{
    System.Diagnostics.Debug.WriteLine(e.Cue.Begin);
    e.Inline.CharacterSpacing = 5;
}

Last edited Feb 19, 2013 at 1:19 AM by timgreenfield, version 14