| ms.assetid | EFCF84D0-2F4C-454D-97DA-249E9EAA806C |
|---|---|
| description | The SystemMediaTransportControls class enables your app to use the system media transport controls that are built into Windows and to update the metadata that the controls display about the media your app is currently playing. |
| title | Manual control of the System Media Transport Controls |
| ms.date | 02/08/2017 |
| ms.topic | article |
| keywords | windows 10, uwp |
| ms.localizationpriority | medium |
Starting with Windows 10, version 1607, UWP apps that use the MediaPlayer class to play media are automatically integrated with the System Media Transport Controls (SMTC) by default. This is the recommended way of interacting with the SMTC for most scenarios. For more information on customizing the SMTC's default integration with MediaPlayer, see Integrate with the System Media Transport Controls.
There are a few scenarios where you may need to implement manual control of the SMTC. These include if you are using a MediaTimelineController to control playback of one or more media players. Or if you are using multiple media players and only want to have one instance of SMTC for your app. You must manually control the SMTC if you are using MediaElement to play media.
If you are using MediaPlayer to play media, you can get an instance of the SystemMediaTransportControls class by accessing the MediaPlayer.SystemMediaTransportControls property. If you are going to manually control the SMTC, you should disable the automatic integration provided by MediaPlayer by setting the CommandManager.IsEnabled property to false.
Note
If you disable the MediaPlaybackCommandManager of the MediaPlayer by setting IsEnabled to false, it will break the link between the MediaPlayer the TransportControls provided by the MediaPlayerElement, so the built-in transport controls will no longer automatically control the playback of the player. Instead, you must implement your own controls to control the MediaPlayer.
:::code language="csharp" source="~/../snippets-windows/windows-uwp/audio-video-camera/SMTCWin10/cs/MainPage.xaml.cs" id="SnippetInitSMTCMediaPlayer":::
You can also get an instance of the SystemMediaTransportControls by calling GetForCurrentView. You must get the object with this method if you are using MediaElement to play media.
:::code language="csharp" source="~/../snippets-windows/windows-uwp/audio-video-camera/SMTCWin10/cs/MainPage.xaml.cs" id="SnippetInitSMTCMediaElement":::
Enable the buttons that your app will use by setting the corresponding "is enabled" property of the SystemMediaTransportControls object, such as IsPlayEnabled, IsPauseEnabled, IsNextEnabled, and IsPreviousEnabled. See the SystemMediaTransportControls reference documentation for a complete list of available controls.
:::code language="csharp" source="~/../snippets-windows/windows-uwp/audio-video-camera/SMTCWin10/cs/MainPage.xaml.cs" id="SnippetEnableContols":::
Register a handler for the ButtonPressed event to receive notifications when the user presses a button.
:::code language="csharp" source="~/../snippets-windows/windows-uwp/audio-video-camera/SMTCWin10/cs/MainPage.xaml.cs" id="SnippetRegisterButtonPressed":::
The ButtonPressed event is raised by the system transport controls when one of the enabled buttons is pressed. The Button property of the SystemMediaTransportControlsButtonPressedEventArgs passed into the event handler is a member of the SystemMediaTransportControlsButton enumeration that indicates which of the enabled buttons was pressed.
In order to update objects on the UI thread from the ButtonPressed event handler, such as a MediaElement object, you must marshal the calls through the CoreDispatcher. This is because the ButtonPressed event handler is not called from the UI thread and therefore an exception will be thrown if you attempt to modify the UI directly.
:::code language="csharp" source="~/../snippets-windows/windows-uwp/audio-video-camera/SMTCWin10/cs/MainPage.xaml.cs" id="SnippetSystemMediaTransportControlsButtonPressed":::
You should notify the SystemMediaTransportControls when the state of the media has changed so that the system can update the controls to reflect the current state. To do this, set the PlaybackStatus property to the appropriate MediaPlaybackStatus value from within the CurrentStateChanged event of the MediaElement, which is raised when the media state changes.
:::code language="csharp" source="~/../snippets-windows/windows-uwp/audio-video-camera/SMTCWin10/cs/MainPage.xaml.cs" id="SnippetSystemMediaTransportControlsStateChange":::
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 for the currently playing media item. Get an instance of this class with the SystemMediaTransportControls.DisplayUpdater property. For typical scenarios, the recommended way to pass the metadata is to call CopyFromFileAsync, passing in the currently playing media file. The display updater will automatically extract the metadata and thumbnail image from the file.
Call the Update to cause the system media transport controls to update its UI with the new metadata and thumbnail.
:::code language="csharp" source="~/../snippets-windows/windows-uwp/audio-video-camera/SMTCWin10/cs/MainPage.xaml.cs" id="SnippetSystemMediaTransportControlsUpdater":::
If your scenario requires it, you can update the metadata displayed by the system media transport controls manually by setting the values of the MusicProperties, ImageProperties, or VideoProperties objects exposed by the DisplayUpdater class.
:::code language="csharp" source="~/../snippets-windows/windows-uwp/audio-video-camera/SMTCWin10/cs/MainPage.xaml.cs" id="SystemMediaTransportControlsUpdaterManual":::
Note
Apps should set a value for the SystemMediaTransportControlsDisplayUpdater.Type property even if they aren't supplying other media metadata to be displayed by the System Media Transport Controls. This value helps the system handle your media content correctly, including preventing the screen saver from activating during playback.
The system transport controls display information about the timeline of the currently playing media item, including the current playback position, the start time, and the end time of the media item. To update the system transport controls timeline properties, create a new SystemMediaTransportControlsTimelineProperties object. Set the properties of the object to reflect the current state of the playing media item. Call SystemMediaTransportControls.UpdateTimelineProperties to cause the controls to update the timeline.
:::code language="csharp" source="~/../snippets-windows/windows-uwp/audio-video-camera/SMTCWin10/cs/MainPage.xaml.cs" id="SnippetUpdateTimelineProperties":::
-
You must provide a value for the StartTime, EndTime and Position in order for the system controls to display a timeline for your playing item.
-
MinSeekTime and MaxSeekTime allow you to specify the range within the timeline that the user can seek. A typical scenario for this is to allow content providers to include advertisement breaks in their media.
You must set MinSeekTime and MaxSeekTime in order for the PositionChangeRequest to be raised.
-
It is recommended that you keep the system controls in sync with your media playback by updating these properties approximately every 5 seconds during playback and again whenever the state of playback changes, such as pausing or seeking to a new position.
There is a set of system transport controls properties that relate to the current state of the media player itself, rather than the state of the playing media item. Each of these properties is matched with an event that is raised when the user adjusts the associated control. These properties and events include:
| Property | Event |
|---|---|
| AutoRepeatMode | AutoRepeatModeChangeRequested |
| PlaybackRate | PlaybackRateChangeRequested |
| ShuffleEnabled | ShuffleEnabledChangeRequested |
To handle user interaction with one of these controls, first register a handler for the associated event.
:::code language="csharp" source="~/../snippets-windows/windows-uwp/audio-video-camera/SMTCWin10/cs/MainPage.xaml.cs" id="SnippetRegisterPlaybackChangedHandler":::
In the handler for the event, first make sure that the requested value is within a valid and expected range. If it is, set the corresponding property on MediaElement and then set the corresponding property on the SystemMediaTransportControls object.
:::code language="csharp" source="~/../snippets-windows/windows-uwp/audio-video-camera/SMTCWin10/cs/MainPage.xaml.cs" id="SnippetPlaybackChangedHandler":::
- In order for one of these player property events to be raised, you must set an initial value for the property. For example, PlaybackRateChangeRequested will not be raised until after you have set a value for the PlaybackRate property at least one time.
If you are not using the automatic SMTC integration provided by MediaPlayer you must manually integrate with the SMTC to enable background audio. At a minimum, your app must enable the play and pause buttons by setting IsPlayEnabled and IsPauseEnabled to true. Your app must also handle the ButtonPressed event. If your app does not meet these requirements, audio playback will stop when your app moves to the background.
Apps that use the new one-process model for background audio should get an instance of the SystemMediaTransportControls by calling GetForCurrentView. Apps that use the legacy two-process model for background audio must use BackgroundMediaPlayer.Current.SystemMediaTransportControls to get access to the SMTC from their background process.
For more information on playing audio in the background, see Play media in the background.