The Windows 8 JavaScript version of the player framework works much like
other Metro WinJS controls. This is a high level guide to help show you how to define, initialize and style the player framework.
Declaring the player framework in your HTML
Once you’ve added the player framework project reference to your app, the easiest way to start is to add the player framework to your HTML page. You do this by first adding script and css and then adding video tag and wrapping it in a div tag.
See the Getting Started Guide for step by step instructions. Once done, you should have something like this:
<!-- Microsoft.PlayerFramework references -->
<link href="///Microsoft.PlayerFramework.Js/css/PlayerFramework.css" rel="stylesheet" type="text/css" />
<script src="///Microsoft.PlayerFramework.Js/js/PlayerFramework.js"></script>
<div data-win-control="PlayerFramework.MediaPlayer" data-win-options="{
width: 640}">
<video>
<source src="http://smf.blob.core.windows.net/samples/videos/wildlife.mp4" />
</video>
</div>
By default, the js file associated with your html page should already have a call to WinJS.Binding.processAll(...). By calling this, you are telling WinJS to go find all elements with data-win-control attributes and initialize as the appropriate controls. In this case, that control is defined in PlayerFramework.js (exposed via script tag you added). Internally, the player framework expects to find a <video> or <audio> tag as a child of the div tag. You can either set properties on the video or audio tag directly (as we did with the src attribute above), or you can pass these values to the player framework directly and have it pass them onto the underlying video or audio tag.
Initializing the player framework in your HTML
Like other WinJS controls, initialization of the player framework can also be done in HTML via the
data-win-options attribute. This attribute takes a JSON object that contains optional property values to help define how the control should look and behave on startup. Note: You could also set these from code.
The player framework allows you to pass in any property value defined on PlayerFramework.MediaPlayer. See a list of properties in the
Player Framework's JavaScript API reference. For example, there are two properties on MediaPlayer called isRewindVisible & isFastForwardVisible. By default these are both false, but you can set them to true in your JSON options:
<div data-win-control="PlayerFramework.MediaPlayer" data-win-options="{
width: 640, isRewindVisible: true, isFastForwardVisible: true}">
<video>
<source src="http://smf.blob.core.windows.net/samples/videos/wildlife.mp4" />
</video>
</div>
Another important thing to understand is that all
properties, methods, and events available on the video tag are also automatically available on the MediaPlayer object. This means that if you are familiar with the video tag, you already know a large part of the player framework's API. This also means that there is never really a reason to access the video tag DOM element directly.
Plugins
The primary reason the player framework is considered a "framework" vs. a "control" is because it supports an extensible plugin architecture that allows other components to be created and connected to the player framework to add features. In fact, many of the player framework's features are implemented as plugins.
Plugins can have their own APIs but via the dynamic nature of JavaScript, a plugin will often choose to extend the MediaPlayer's API by adding a property to itself on the main MediaPlayer object. For example. You can set the autoAdvance property on the playlistPlugin by calling:
mediaPlayer.playlistPlugin.autoAdvance = true;
This also make it possible to set properties on a plugin through the JSON options just like any other property found on MediaPlayer. For example:
<div data-win-control="PlayerFramework.MediaPlayer" data-win-options="{
width: 640,
playlistPlugin: {
autoAdvance: true,
playlist: [{
src: 'http://smf.blob.core.windows.net/samples/videos/bigbuck.mp4'
}, {
src: 'http://smf.blob.core.windows.net/samples/videos/wildlife.mp4'
}]
}
}">
<video></video>
</div>
Playlists
One special plugin shipped with the player framework is the playlistPlugin. This plugin allows you to create a playlist of media that the user can either play continuously or skip around to. Additionally, we understand that you may want to set certain properties on the MediaPlayer differently depending on which PlaylistItem is actively loaded. To support this, any property that you could normally set through the MediaPlayer's JSON options, you can also set via a special playlist JSON option. For example, here are sample JSON options to show the skip next and previous buttons along with a playlist where the src property is set:
<div data-win-control="PlayerFramework.MediaPlayer" data-win-options="{
width: 640,
isSkipNextVisible: true,
isSkipPreviousVisible: true,
playlistPlugin: {
playlist: [{
src: 'http://smf.blob.core.windows.net/samples/videos/bigbuck.mp4'
}, {
src: 'http://smf.blob.core.windows.net/samples/videos/wildlife.mp4'
}]
}
}">
<video></video>
</div>
But, what if you wanted to hide the skip back button for the first playlist item and show it for the last one. In this example, you could simply move any property in the JSON options into the JSON for a particular playlistitem:
<div data-win-control="PlayerFramework.MediaPlayer" data-win-options="{
width: 640,
playlist: [{
src: 'http://smf.blob.core.windows.net/samples/videos/bigbuck.mp4',
isSkipNextVisible: true,
isSkipPreviousVisible: false,
}, {
src: 'http://smf.blob.core.windows.net/samples/videos/wildlife.mp4',
isSkipNextVisible: false,
isSkipPreviousVisible: true,
}],
}">
<video></video>
</div>
Styling
The player framework exposes as much of it's UI as possible via CSS. This means that you can easily override the default CSS with your own. To find out more about styling via CSS, we recommend a few different resources:
- Download the source and samples zip. This includes a sample player that is a heavily customized and unique from the default look of the player framework.
- Look at the CSS shipped with the player framework. You can easily expand your project reference and double click on the file in Visual Studio to see the source CSS.
- Use the Visual Studio DOM explorer to view and modify the CSS at runtime to see what effect it has.