SystemMediaTransportControls class

Applies to Windows and Windows Phone

Represents an object that enables integrate with the system media transport controls and support for media commands.

Syntax

Public NotInheritable Class SystemMediaTransportControls

Attributes

[MarshalingBehavior(Agile)]
[Muse()]
[Threading(MTA)]
[Version(0x06030000)]

Members

The SystemMediaTransportControls class has these types of members:

Events

The SystemMediaTransportControls class has these events.

EventDescription
ButtonPressed Occurs when a button is pressed on the SystemMediaTransportControls.
PropertyChanged Occurs when a property on the SystemMediaTransportControls has changed.

 

Methods

The SystemMediaTransportControls class has these methods. With C#, Visual Basic, and C++, it also inherits methods from the Object class.

MethodDescription
GetForCurrentView The system transport controls for the current view.

 

Properties

The SystemMediaTransportControls class has these properties.

PropertyAccess typeDescription

DisplayUpdater

Read-onlyGets the display updater for the SystemMediaTransportControls which enable updating the information displayed about the currently playing song.

IsChannelDownEnabled

Read/writeGets or sets a value that specifies if the channel down button is supported.

IsChannelUpEnabled

Read/writeGets or sets a value that specifies if the channel up button is supported.

IsEnabled

Read/writeEnables and disables the system media transport controls for the app.

IsFastForwardEnabled

Read/writeGets or sets a value that specifies if the fast forward button is supported.

IsNextEnabled

Read/writeGets or sets a value that specifies if the next button is supported.

IsPauseEnabled

Read/writeGets or sets a value that specifies if the pause button is supported.

IsPlayEnabled

Read/writeGets or sets a value that specifies if the play button is supported.

IsPreviousEnabled

Read/writeGets or sets a value that specifies if the previous button is supported.

IsRecordEnabled

Read/writeGets or sets a value that specifies if the record button is supported.

IsRewindEnabled

Read/writeGets or sets a value that specifies if the rewind button is supported.

IsStopEnabled

Read/writeGets or sets a value that specifies if the stop button is supported.

PlaybackStatus

Read/writeGets the playback status of the media.

SoundLevel

Read-onlyGets the sound level of the media for the capture and render streams.

 

Remarks

The SystemMediaTransportControls replaces the MediaControl class. In Windows 8.1 and later, you should use this control instead of MediaControl to interact with the system transport controls.

The system transport controls enable music application developers to hook into a system-wide transport control. The system transport control allows a user to control a music application that is in the background as well as get and set the current information on which track is playing.

Call GetForCurrentView to get an instance of the SystemMediaTransportControls for current view. There is one playback session per view. Apps which support multiple windows can have multiple playback sessions as long as they maintain the rule of 1 view to 1 playback experience.

Register a handler for the ButtonPressed event to integrate the system transport control button events with your app. Also, you must enable support for the individual transport control buttons, such as SystemMediaTransportControls.IsPlayEnabled for handling the play event.

To support playing music in the background when your app has been suspended, you must enable support for the play and pause buttons by setting IsPlayEnabled and IsPauseEnabled to true. See the How to play audio in the background for more info and requirements.

Music and media capture apps should monitor the SoundLevel to determine whether the audio streams on the app have been Muted. For apps using the MediaCapture object, capture will be automatically stopped when the capture streams of the app are muted. Capture is not re-started automatically when the audio streams are unmuted, so the SoundLevel changed notification can be used to restart capture. Use the PropertyChanged event to determine when the SoundLevel property changes.

For more info see How to use the system media transport controls.

Examples

Here is some code that creates a ButtonPressed event handler and helper methods to play and pause a MediaElement. Notices that the calls to Play and Pause are marshaled to the UI thread through the CoreDispatcher using Dispatcher.RunAsync.


<MediaElement x:Name="mediaPlayer" 
              Source="Videos/video1.mp4" 
              Width="400" 
              AutoPlay="False"
              AreTransportControlsEnabled="True" />



void SystemControls_ButtonPressed(SystemMediaTransportControls sender, 
    SystemMediaTransportControlsButtonPressedEventArgs args)
{
    switch (args.Button)
    {
        case SystemMediaTransportControlsButton.Play:
            PlayMedia();
            break;
        case SystemMediaTransportControlsButton.Pause:
            PauseMedia();
            break;
        default:
            break;
    }
}

async void PlayMedia()
{
    await Dispatcher.RunAsync(Windows.UI.Core.CoreDispatcherPriority.Normal, () =>
    {
        musicPlayer.Play();
    });
}

async void PauseMedia()
{
    await Dispatcher.RunAsync(Windows.UI.Core.CoreDispatcherPriority.Normal, () =>
    {
        musicPlayer.Pause();
    });
}


Here is the code that handles the CurrentStateChanged event handler and updates the SystemMediaTransportControls state.


void MusicPlayer_CurrentStateChanged(object sender, RoutedEventArgs e)
{
    switch (musicPlayer.CurrentState)
    {
        case MediaElementState.Playing:
            systemControls.PlaybackStatus = MediaPlaybackStatus.Playing;
            break;
        case MediaElementState.Paused:
            systemControls.PlaybackStatus = MediaPlaybackStatus.Paused;
            break;
        case MediaElementState.Stopped:
            systemControls.PlaybackStatus = MediaPlaybackStatus.Stopped;
            break;
        case MediaElementState.Closed:
            systemControls.PlaybackStatus = MediaPlaybackStatus.Closed;
            break;
        default:
            break;
    }
}


Requirements

Minimum supported client

Windows 8.1 [Windows Store apps only]

Minimum supported server

Windows Server 2012 R2 [Windows Store apps only]

Minimum supported phone

Windows Phone 8.1 [Windows Runtime apps only]

Namespace

Windows.Media
Windows::Media [C++]

Metadata

Windows.winmd

See also

Object

 

 

Show:
© 2014 Microsoft