Caption Customization

Installation

The Caption Customization assemblies are available in the v1.3.1 vsix download and later. A number of fixes and improvements have been made since that release and are in the source code repository but not yet published in the VSIX installer. If you would like to use the latest version with these fixes and improvements, please download and build the Player Framework.

Compatibility with Existing Captions

Captions that are not created with user-customization in mind may not render correctly when user customizations are applied. An example of this is where the caption data defines the exact position text elements which would overlap with adjacent elements if the user resizes text to be larger than 100%.

Recommendations

  • In TTML, do not define adjacent regions.
  • In TTML, do not put position tt:extent or tt:origin attributes in individual <p> elements.

Assemblies

The Caption Customization assemblies are used to provide user-customization to closed captions for video in the Player Framework.
Platform TTML WebVTT
Windows 8 HTML N/A N/A
Windows 8.1 HTML Internet Explorer 11* Internet Explorer 11*
Windows 8 Xaml TTMLCaptionSettingsPlugin WebVTTCaptionSettingsPlugin
Windows 8.1 Xaml TTMLCaptionSettingsPlugin WebVTTCaptionSettingsPlugin
Windows Phone 8 Xaml TTMLCaptionSettingsPlugin WebVTTCaptionSettingsPlugin

* Windows 8.1 HTML apps get their caption customization from the desktop Internet Explorer 11 accessibility settings in the internet options dialog.

Full Plugin Names

Once a project references the Player Framework TimedText or WebVTT Captions plug-ins, the corresponding CaptionSettings plug-ins will also be included in the project.
  • Microsoft.PlayerFramework.TTML.CaptionSettings.TTMLCaptionSettingsPlugin
  • Microsoft.PlayerFramework.WebVTT.CaptionSettings.WebVTTCaptionSettingsPlugin

Windows 8 and Windows 8.1

  1. Add a reference to the TTML or WebVTT Captions Plug-in to the app.
  2. Add the captions plug-in to MediaPlayer Plugin list
  3. Add the appropriate Caption Settings Plugin to the MediaPlayer Plugin list
  4. Set the optional properties of the plug-in.
  5. Windows 8.1: Styling the Windows 8.1 Settings Pane
A Caption Settings pane will be added to the Settings flyout in Windows when the media player initializes and will be removed from the settings pane when the page is deactivated (navigated away from).

Examples

In the TTML sample, the TTMLCaptionSettingsPlugin is added to the MediaPlayer.Plugins collection in TtmlPage.xaml.cs in the page class's constructor.
public TtmlPage()
{
     this.InitializeComponent();
     this.navigationHelper = new NavigationHelper(this);
     player.Plugins.Add(new Microsoft.PlayerFramework.TimedText.CaptionsPlugin());
     player.SelectedCaption = player.AvailableCaptions.FirstOrDefault();

     player.Plugins.Add(new Microsoft.PlayerFramework.TTML.CaptionSettings.TTMLCaptionSettingsPlugin());
}
In the WebVTT Sample, the WebVTTCaptionSettingsPlugin is added to the MediaPlayer.Plugins collection in WebVTTPage.xaml
xmlns:webvttCaptions="using:Microsoft.PlayerFramework.WebVTT.CaptionSettings"
 
<mmppf:MediaPlayer>
    <mmppf:MediaPlayer.Plugins>
         <webvtt:WebVTTPlugin/>
         <webvttCaptions:WebVTTCaptionSettingsPlugin/>
     </mmppf:MediaPlayer.Plugins>
</mmppf:MediaPlayer>
All of the plug-ins on Windows 8.1 have the same API properties and events:

Events

  • OnLoadCaptionSettings event is called when the plug-in is initialized and gives the app an opportunity to retrieve caption settings from a location other than local storage.
  • OnSaveCaptionSettings event is called when the user changes properties in the settings pane and gives the app an opportunity to save caption settings to a location other than local storage.

Windows 8 Properties

  • Label the label of the caption settings pane (default is "Caption Settings")
  • SettingsCommandId the internal command Id of the caption settings pane (default is "CaptionSettings")
  • SettingsCommandIndex the index that the Caption Settings will be added to the settings list (default is to be added to the end)
  • SettingsFlyoutStyle the style of the SettingsFlyout that can be used to customize the appearance of the caption settings pane. The style can be set inline or it can be referenced as a StaticResource: <Style TargetType="SettingsFlyout"/>

Windows 8.1 Properties

  • SettingsControlStyle the style of the CaptionSettingsControl that can be used to customize the appearance of the caption settings pane. The style can be set inline or it can be referenced as a StaticResource: <Style TargetType="CaptionSettingsControl"/>. See Styling the Windows 8.1 Settings Pane for details on setting the style.
  • IconSource the image source for the icon displayed at the top of the settings flyout

Windows Phone 8 Properties

Windows Phone 8 Methods

  • ShowSettingsPage(System.Windows.Navigation.NavigationService service, Microsoft.PlayerFramework.CaptionSettings.CaptionSettingsPageOptions options = null) Navigate to the captions settings page. Pressing the back button navigates the user back to the current page.
    • service: the NavigationService property of the current PhoneApplicationPage
    • options: the caption settings options for controlling the orientation and system tray visibility
  • ShowSettingsPopup(PhoneApplicationPage page, Panel parent, bool pauseVideo = false) Show the caption settings as a popup over the current page.
    • page: the current PhoneApplicationPage
    • parent: the root parent panel (typically a Grid named LayoutRoot) of the page
    • pauseVideo: true to pause the video when displaying the popup, false otherwise

Windows Phone 8

  1. Add a reference to the TTML or WebVTT Captions Plug-in to the app.
  2. Add the captions plug-in to MediaPlayer Plugin list
  3. Add the appropriate Caption Settings Plugin to the MediaPlayer Plugin list
  4. Set the optional properties of the plug-in.
  5. Add UI like a settings button to call Plugin.Show() to navigate to the caption settings page or call Plugin.ShowPopup() to show the caption settings options as a popup control.
  6. See additional documentation on styling the control: Styling Windows Phone 8 Caption Settings Page

Example

Create a reference to the Caption Settings Plugin and save it as a variable in the page. Call the Plugin.ShowSettingsPage() or Plugin.ShowSettingsPopup() method to show the settings page:
namespace WP8.PlayerFramework.Test.Pages
{
    using System.Linq;
    using System.Windows;
    using Microsoft.Phone.Controls;
    using Microsoft.PlayerFramework.TTML.CaptionSettings;

    public partial class TTMLPage : PhoneApplicationPage
    {
       private TTMLCaptionSettingsPlugin plugin;

        public TTMLPage()
        {
            this.InitializeComponent();

            this.plugin = new Microsoft.PlayerFramework.TTML.CaptionSettings.TTMLCaptionSettingsPlugin();

            this.Player.Plugins.Add(this.plugin);

            this.Player.SelectedCaption = this.Player.AvailableCaptions.First();
        }
 
        // Show the caption settings as a separate page.
        private void OnCaptionSettings(object sender, System.EventArgs e)
        {
            this.plugin.ShowSettingsPage(this.NavigationService);
        }

        // Show the caption settings as a popup over the playing video
        private void OnCaptionSettingsPopup(object sender, System.EventArgs e)
        {
            bool pauseVideo = false;

            this.plugin.ShowSettingsPopup(this, this.LayoutRoot, pauseVideo);
        }
   }
}

Font Selection

The Caption Customization plug-ins allow the user to select a generic font families. The font families in the plug-ins have been selected to best match the user interface styles and fonts available on Windows 8 (see here) and Windows Phone (see here) but developers can override those styles with application settings:
Font Family Windows 8 Windows Phone
Monospace Serif Courier New Courier New
Proportional Serif Times New Roman Times New Roman
Monospace Sans Serif Consolas Calibri
Proporational Sans Serif Tahoma Tahoma
Casual Segoe Print Comic Sans MS
Cursive Segoe Script Calibri Italic Light
Smallcaps Tahoma (with Small-caps style applied) Tahoma (with Small-caps style applied)

To override the font selection in Windows 8 and Windows 8.1 - for the key names, use the values from the FontFamily enumeration:
var localSettings = Windows.Storage.ApplicationData.Current.LocalSettings;

var container = localSettings.CreateContainer(
                     "Font Families", 
                      Windows.Storage.ApplicationDataCreateDisposition.Always);

container["ProportionalSansSerif"] = "My Custom Font Name";
To override the font selection in Windows Phone set values in the isolated storage. Use the values from the FontFamily enumeration with the prefilx "FontFamilies.":
var applicationSettings = System.IO.IsolatedStorage.IsolatedStorageSettings.ApplicationSettings;

applicationSettings["FontFamilies.MonospaceSansSerif"] = "My Custom Font Name";

Last edited May 5, 2014 at 5:46 PM by mscherotter, version 62