Media playback, start to finish (HTML)

Article
04/19/2016

[ This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation ]

Learn how to create feature-rich media apps for Windows 8.1 that play audio and video and that conserve battery life and optimize rendering.

We'll go over how to create a Windows Store app using JavaScript loaded with media features, from start to finish. There are lots of improvements in Windows 8.1 that make this even easier than before, such as the new msRequestFullscreen API. We'll go over:

Media playback basics like using the audio and video HTML elements, enabling the transport controls, and loading media files from either the device or the network.
Media playback features like properly preventing the screen from dimming, playing audio in the background, interacting with the system media transport controls, resizing video, creating custom transport controls, and enabling full-window rendering.
App basics like preserving app state, creating UI on the app bar, and creating Settings flyouts.

If you're new to developing Windows Store apps using JavaScript, take a look at Create your first Windows Store app using JavaScript to get up to speed.

Each step below links to a how-to topic with examples and code, so dig into those if you want more info.

The Media playback, start to finish sample includes all the things we talk about here. We'll refer to this companion sample often and point you to the places in it where specific features are implemented.

Screen shot of the media playback sample app

Create a media app

Create your sample

If you want to follow the steps here to add media features to your own app, you can start with the Flat navigation, start to finish topic and the associated Flat navigation pattern template. Or you can create a blank Windows Store app project or navigation project in Microsoft Visual Studio. Although the companion sample has a simple navigation structure, it does use some of the helper functions in navigation.js, which is not included in the blank template. So it may be easier to start with one of the navigation templates and remove what you don't need.

Or, skip directly to the Media playback, start to finish companion sample.

The companion sample implements all the steps here, but to keep things moving we won't walk through the code. Each step has a "Find it in the sample" section to help you find the code quickly.

The structure of the sample's source files is simple and flat so you can easily find code without having to drill down through multiple layers of source files. But you may prefer to break up and organize your own project differently.

Media playback basics

	Quickstart: playing video in an app Set up the basics for video in your app. This how-to topic goes into detail about how to do that, but to get basic audio and video playing, just add an audio or video element to your HTML and set the src property to a media file. To control the media playback, use the built-in transport controls by adding the controls attribute to the audio or video element. Enable and disable the controls by setting the controls property to true or false. Transport controls provide common media UI elements like the play button and volume controls. Here's how those controls look in the sample. Find it in the sample: The video element is named mediaVideo and is defined in HTML in the file \pages\mediaPlayer\mediaPlayer.js.
	Supported audio and video formats Windows Store apps using JavaScript support a large number of audio and video formats. Click the link for the complete list.
	How to open local media files using the FileOpenPicker control Now that we have media playing, let's set the media source while the app is running. The FileOpenPicker control lets the user select a file from the local file system or from Microsoft OneDrive. This step shows how to set up the FileOpenPicker and how to set the video.src property to the file returned by the FileOpenPicker. Use StorageApplicationPermissions.futureAccessList to store permissions for files opened with the FileOpenPicker. Your app can then access the files later on, such as when the app is being restored from a termination state. The FileOpenPicker looks like this. The FileOpenPicker doesn't require your app to declare capabilities for system folders such as Music, Videos, and Documents. This is because the user has total control over the FileOpenPicker and over which files are opened. For security and privacy purposes, your app should declare as few capabilities as possible. But if you want your app to have access to the Videos and Music folders without the user's input—to display all the album art in the Music folder, for example—you must declare the corresponding capabilities. For more info, see App capability declarations. Find it in the sample: Look at the `setMediaSourceFromFilePicker` and `setMediaSourceFromFile` functions in \pages\mediaPlayer\mediaPlayer.js and the `browseButton` app bar button in \pages\mediaPlayer\mediaPlayer.html.
	How to open media files from the network The FileOpenPicker control works well for getting a file on the local system, but it won't work for setting the media source to a file on the network. To do this, simply set the src to the path of the media file on the network. Find it in the sample: Look at the `setMediaSourceFromTextBox` and `setMediaSourceFromPath` functions in \pages\mediaPlayer\mediaPlayer.js. Look also at the `txtSourceInput` input element in \pages\mediaPlayer\mediaPlayer.html, which is used to enter the media path.

Media playback features

	How to keep the display on during audio and video playback Typically, when a Windows Store app does not detect user input within a certain period of time, the screen dims and eventually turns off. In most apps this is a good thing, because it conserves energy and battery life. In many media apps, though, we don't want the display to dim because someone is probably watching the video. Use the System.Windows.Display.DisplayRequest class to tell the system to always keep the display on for your app. But be sure to cancel this request as soon as your app no longer needs it, such as when your app is suspending, the media is finished playing, or the media is paused. Not canceling this request wastes battery life. If full-window rendering is enabled through the full-window button on the built-in transport controls or through the msRequestFullscreen function, the system automatically handles disabling and re-enabling screen dimming. So if your app needs to disable screen dimming only in full-window mode, you do not need to manage the DisplayRequest yourself. Find it in the sample: See the `setScreenDimming` function in \pages\mediaPlayer\mediaPlayer.js.
	How to use the system media transport controls Windows 8.1 introduces a new class for interacting with the system media transport controls. From now on, use SystemMediaTransportControls instead of the old MediaControl class. The system media transport controls are different from the transport controls on the HTML media object. These are the controls that pop up when you press hardware media keys, like the volume control on a pair of headphones or the media buttons on some keyboards. Your app can register to use these controls and can even pass back media metadata, such as album art or song titles, to be displayed by them. Here's a look at the controls. Find it in the sample: See the `WinJS.UI.Pages.define`, `setupSystemMediaTransportControls`, and `systemMediaControlsButtonPressed` functions in \pages\mediaPlayer\mediaPlayer.js. As well as the `mediaPlaying`, `mediaPaused`, and `mediaEnded` event handlers in \pages\mediaPlayer\mediaPlayer.js.
	How to play audio in the background. Now let's set up background audio support, so users can listen to music with your app while interacting with a different app. When an app playing audio is moved to the background, such as when the user switches to a different app, the default behavior is for the audio to stop. But a music app can choose to have the audio continue to play. To play audio in the background you must set the background audio task in the app manifest Declarations section. And you must enable the isPlayEnabled and isPauseEnabled properties on the SystemMediaTransportControls and handle the buttonpressed event. This is required so the user has a way to play and stop the audio when your app is not the active app. Find it in the sample: See the video element in \pages\mediaPlayer\mediaPlayer.html, the `setupSystemMediaTransportControls` function in \pages\mediaPlayer\mediaPlayer.html, and look at the Declarations section of package.appmanifest.xml for enabling the background task.
	How to enable full-window rendering The built-in transport controls for the audio and video objects have a full-window button. But if you want to enable or disable full-window rendering programmatically, use the msRequestFullscreen function. Before Windows 8.1, you had to calculate the bounds of the full window and show and hide the other UI yourself. If this wasn't done in the right way, some rendering optimizations might not be enabled. So always use the msRequestFullscreen function to enable and disable full-window rendering. (And it's just easier.) Find it in the sample: See the `fullScreenMedia` function in \pages\mediaPlayer\mediaPlayer.js.
	How to create custom transport controls If you need to expand on the functionality that the audio and video transport controls provide, or if you want to replace them completely, you'll have to create custom transport controls. The Media playback, start to finish sample implements all the custom transport controls on the AppBar but leaves the built-in transport controls enabled. If you are creating your own custom transport controls, you might prefer to simply replace the built-in UI with your own. To turn off the built-in transport controls, set controls to false. This how-to topic covers creating custom transport controls for play, pause, stop, fast forward, rewind, position slider, full window, audio section, mute, and volume. Find it in the sample: See the AppBar elements in \pages\mediaPlayer\mediaPlayer.html, and see \pages\mediaPlayer\mediaPlayer.js for the event handlers that implement the features.

App basics

Adding app bars

Place UI that interacts with the app and the audio and video objects on the app bars using a WinJS.UI.AppBar. The WinJS.UI.AppBarCommand controls are built specifically for the AppBar and work great. The following control types are available: "button", "toggle", "flyout", "separator", and "content".

The WinJS.UI.AppBarIcon enumeration contains a large number of symbols that you can use for the AppBarCommand.icon. You can also supply your own custom Portable Network Graphics (PNG) file.

Here's what the bottom AppBar looks like on the companion sample.

Shows an AppBar with AppBarButtons

The companion sample uses flyouts for the audio-track selection control and the volume control. This helps saves space.

For info about using the AppBar and designing your app, see Guidelines for app bars.

Find it in the sample: See the <div id="appBarTop" and <div id="appBarBottom" elements in \pages\mediaPlayer\mediaPlayer.html. If you want to know how a particular control and feature is implemented, look at the event handlers for the app bar buttons in \pages\mediaPlayer\mediaPlayer.js.

Manage app lifecycle and state

Saving your app state in Windows Store apps is important, because your app can be suspended to the background at any time and terminated by the system. When your app resumes, the user typically expects the media to be at the same place as before and all the app settings to be intact.

You can save the app state either to the isolated storage on the device or to roaming storage. Roaming storage is nice because it lets the user run your app on multiple devices and the state is shared between all of them.

Important video states to save are the src, currentTime, loop, paused, ended, autoplay, and any selected audioTracks.

navigation.js are helper functions that are part of the Visual Studio templates. They are included in all but the blank template. These helper functions simplify the handling of suspend, resume, and resume from termination.

Some media states should be restored after the media has loaded—for example, currentTime.

Find it in the sample: Look at app.oncheckpoint, navigationHelper_SaveState, restoreMediaState, mediaLoaded, and appResumingFromSuspend functions in \pages\mediaPlayer\mediaPlayer.js. In \js\default.js, look at the app.onactivated.

Guidelines for app settings

Use the WinJS.UI.SettingsFlyout control for Windows Store apps using JavaScript.

Settings are for configuration options that affect the behavior of the app as a whole and that are adjusted only occasionally. The Media playback, start to finish sample creates an Audio settings and Video Settings flyout that can be used to store app settings.

Find it in the sample: Look at app.onactivated in \js\default.js. The audio.html, video.html, help.html, and privacy.html setting pages are in the \settings subfolder.

Finish up

Using the Windows App Certification Kit

Recommended. Running the Windows App Certification Kit helps you make sure that your app fulfills Windows Store requirements. We recommend you run it whenever you add major functionality to your app.

You’re finished! Now that you’ve explored different media playback features for your app, you're ready to create an app like the Media playback, start to finish sample.