Media playback, start to finish (HTML)

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.

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.

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.

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 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 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.

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.

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.

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.

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.