How to use the system media transport controls (HTML)

[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]

The SystemMediaTransportControls class enables your app to use the system media transport controls provided by Windows and update the media info that is displayed.

To see this feature in action as part of a complete media-playback sample, see Media playback, start to finish.

Introduction

The SystemMediaTransportControls class introduced in Windows 8.1 replaces the old MediaControl class. You should use the new SystemMediaTransportControls instead of MediaControl.

The system transport controls are different than the transport controls on the audio or video objects. The system transport controls are the controls that pop up when hardware media keys are pressed, such as the volume control on a pair of headphones or the media buttons on keyboards. If the user presses the pause key on a keyboard and your app supports the SystemMediaTransportControls, your app is notified and you can take the appropriate action.

Your app can also update the media info, such as the song title and thumbnail image that the SystemMediaTransportControls displays.

Set up transport controls

To get an instance of the SystemMediaTransportControls, call getForCurrentView.

To enable buttons that your app will handle, set the corresponding "is enabled" property, such as isPlayEnabled, isPauseEnabled, isNextEnabled, and isPreviousEnabled, on the SystemMediaTransportControls object. See the SystemMediaTransportControls reference documentation for a complete list.

Here is some code that creates a video object with event handler for paused, playing, and ended events and sets up the SystemMediaTransportControls. It enables the play and pause buttons and adds an event handler for the buttonpressed event. The event handlers for paused, playing, and ended are shown later in this example.

<video id="mediaVideo" 
       controls 
       src="https://www.contoso.com/clip.mp4"
       onpause="mediaPaused(event)"
       onplaying="mediaPlaying(event)"
       onended="mediaEnded(event)" />

var systemMediaControls;

systemMediaControls = Windows.Media.SystemMediaTransportControls.getForCurrentView();

systemMediaControls.addEventListener("buttonpressed", systemMediaControlsButtonPressed, false);

systemMediaControls.isPlayEnabled = true;
systemMediaControls.isPauseEnabled = true;
systemMediaControls.isStopEnabled = true;

systemMediaControls.playbackStatus = Windows.Media.MediaPlaybackStatus.closed;

Communicate with transport controls

There are three communication aspects when using the transport controls:

The SystemMediaTransportControls notifies your app through the buttonpressed event when one of the enabled buttons is pressed. Your app can then control the media, such as pausing or playing, in response to which button was pressed.

Your app notifies the SystemMediaTransportControls, through the SystemMediaTransportControls.playbackStatus property, when the state of the media has changed. This enables the transport controls to update the button states so they correspond with the state of the media source.

You can update the media info that is displayed by the transport controls, such as the song title or the album art, with the SystemMediaTransportControlsDisplayUpdater.

Handle button presses

The buttonpressed event is raised by the system transport controls when one of the enabled buttons is pressed. The button property event arguments specifies which button was pressed.

Here is some code that creates a buttonpressed event handler and helper methods to play and pause the video.

// Event handler for SystemMediaTransportControls' buttonpressed event
function systemMediaControlsButtonPressed(eventIn) {

    var mediaButton = Windows.Media.SystemMediaTransportControlsButton;

    switch (eventIn.button) {
        case mediaButton.play:
            playMedia();
            break;

        case mediaButton.pause:
            pauseMedia();
            break;

        case mediaButton.stop:
            stopMedia();
            break;

        // Insert additional case statements for other buttons you want to handle
    }
}

// Plays the media.
function playMedia() {
    var media = document.getElementById("mediaVideo");
    media.play();
}

// Pauses the media.
function pauseMedia() {
    var media = document.getElementById("mediaVideo");
    media.pause();
}

// Stops the media.
function stopMedia() {
    var media = document.getElementById("mediaVideo");
    media.pause();
    media.currentTime = 0;
}

Update media status

To notify the SystemMediaTransportControls that the state of the media has changed, set the playbackStatus to the appropriate MediaPlaybackStatus value.

Here is the code that handles the media events and updates the playbackStatus property of the SystemMediaTransportControls.

// The media Play event handler.
function mediaPlaying() {
    // Update the SystemMediaTransportControl state.
    systemMediaControls.playbackStatus = Windows.Media.MediaPlaybackStatus.playing;
}

// The media Pause event handler.
function mediaPaused() {
    // Update the SystemMediaTransportControl state.
    systemMediaControls.playbackStatus = Windows.Media.MediaPlaybackStatus.paused;
}

// The media Ended event handler.
function mediaEnded() {
    // Update the SystemMediaTransportControl state.
    systemMediaControls.playbackStatus = Windows.Media.MediaPlaybackStatus.stopped;
}

Update media info and thumbnail

Use the SystemMediaTransportControlsDisplayUpdater class to update the media info that is displayed by the transport controls, such as the song title or the album art.

The displayUpdater property is the SystemMediaTransportControlsDisplayUpdater associated with the SystemMediaTransportControls.

You can update the metadata manually by setting the media properties on the musicProperties, imageProperties, or videoProperties. But it is recommended and much easier to pass the media file to the copyFromFileAsync method which automatically extracts the metadata and thumbnail image from the file.

When you have set all the media info to display, call update. The UI does not update until after update is called.

Windows.Storage.StorageFile and Windows.Storage.Streams.RandomAccessStreamReference provide useful static methods when working with media info.

StorageFile

• getFileFromPathAsync
• getFileFromApplicationUriAsync

RandomAccessStreamReference

• createFromStream
• createFromFile
• createFromUri

Windows: Background audio

To play audio in the background in Windows, an app must enable the play and pause buttons by setting isPlayEnabled and isPauseEnabled to true. The app must also handle the buttonpressed event. For info on all the requirements for playing audio in the background on Windows, see How to play audio in the background.