You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: hub/apps/develop/media-playback/system-media-transport-controls.md
+13-10Lines changed: 13 additions & 10 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -20,41 +20,44 @@ If you are using **MediaPlayer** to play media, you can get an instance of the [
20
20
> [!NOTE]
21
21
> If you disable the [**MediaPlaybackCommandManager**](/uwp/api/Windows.Media.Playback.MediaPlaybackCommandManager) of the [**MediaPlayer**](/uwp/api/Windows.Media.Playback.MediaPlayer) by setting [**IsEnabled**](/uwp/api/windows.media.playback.mediaplaybackcommandmanager.isenabled) to false, it will break the link between the **MediaPlayer** the [**TransportControls**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.mediaplayerelement.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**.
Enable the buttons that your app will use by setting the corresponding "is enabled" property of the **SystemMediaTransportControls** object, such as [**IsPlayEnabled**](/uwp/api/windows.media.systemmediatransportcontrols.isplayenabled), [**IsPauseEnabled**](/uwp/api/windows.media.systemmediatransportcontrols.ispauseenabled), [**IsNextEnabled**](/uwp/api/windows.media.systemmediatransportcontrols.isnextenabled), and [**IsPreviousEnabled**](/uwp/api/windows.media.systemmediatransportcontrols.ispreviousenabled). See the **SystemMediaTransportControls** reference documentation for a complete list of available controls.
Register a handler for the [**ButtonPressed**](/uwp/api/windows.media.systemmediatransportcontrols.buttonpressed) event to receive notifications when the user presses a button.
## Handle system media transport controls button presses
34
37
35
38
The [**ButtonPressed**](/uwp/api/windows.media.systemmediatransportcontrols.buttonpressed) event is raised by the system transport controls when one of the enabled buttons is pressed. The [**Button**](/uwp/api/windows.media.systemmediatransportcontrolsbuttonpressedeventargs.button) property of the [**SystemMediaTransportControlsButtonPressedEventArgs**](/uwp/api/Windows.Media.SystemMediaTransportControlsButtonPressedEventArgs) passed into the event handler is a member of the [**SystemMediaTransportControlsButton**](/uwp/api/Windows.Media.SystemMediaTransportControlsButton) enumeration that indicates which of the enabled buttons was pressed.
36
39
37
40
In order to update objects on the UI thread from the [**ButtonPressed**](/uwp/api/windows.media.systemmediatransportcontrols.buttonpressed) event handler, such as a [**MediaPlayerElement**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.mediaplayerelement) object, you must marshal the calls through the [**DispatcherQueue**](/windows/windows-app-sdk/api/winrt/microsoft.ui.dispatching.dispatcherqueue.tryenqueue). 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.
## Update the system media transport controls with the current media status
42
45
43
46
You should notify the [**SystemMediaTransportControls**](/uwp/api/Windows.Media.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**](/uwp/api/windows.media.systemmediatransportcontrols.playbackstatus) property to the appropriate [**MediaPlaybackStatus**](/uwp/api/Windows.Media.MediaPlaybackStatus) value from within the [**CurrentStateChanged**](/uwp/api/windows.media.playback.mediaplayer.currentstatechanged) event of the [**MediaPlayer**](/uwp/api/windows.media.playback.mediaplayer), which is raised when the media state changes.
## Update the system media transport controls with media info and thumbnails
48
51
49
52
Use the [**SystemMediaTransportControlsDisplayUpdater**](/uwp/api/Windows.Media.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**](/uwp/api/windows.media.systemmediatransportcontrols.displayupdater) property. For typical scenarios, the recommended way to pass the metadata is to call [**CopyFromFileAsync**](/uwp/api/windows.media.systemmediatransportcontrolsdisC:\windows-code-snippets-pr\winappsdk\audio-video-camera\media-source-winui\cs\MediaSourceplayupdater.copyfromfileasync), passing in the currently playing media file. The display updater will automatically extract the metadata and thumbnail image from the file.
50
53
51
54
Call the [**Update**](/uwp/api/windows.media.systemmediatransportcontrolsdisplayupdater.update) to cause the system media transport controls to update its UI with the new metadata and thumbnail.
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**](/uwp/api/windows.media.systemmediatransportcontrolsdisplayupdater.musicproperties), [**ImageProperties**](/uwp/api/windows.media.systemmediatransportcontrolsdisplayupdater.imageproperties), or [**VideoProperties**](/uwp/api/windows.media.systemmediatransportcontrolsdisplayupdater.videoproperties) objects exposed by the [**DisplayUpdater**](/uwp/api/windows.media.systemmediatransportcontrols.displayupdater) class.
> Apps should set a value for the [SystemMediaTransportControlsDisplayUpdater.Type](/uwp/api/windows.media.systemmediatransportcontrolsdisplayupdater.type#Windows_Media_SystemMediaTransportControlsDisplayUpdater_Type
@@ -66,7 +69,7 @@ This value helps the system handle your media content correctly, including preve
66
69
67
70
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**](/uwp/api/Windows.Media.SystemMediaTransportControlsTimelineProperties) object. Set the properties of the object to reflect the current state of the playing media item. Call [**SystemMediaTransportControls.UpdateTimelineProperties**](/uwp/api/windows.media.systemmediatransportcontrols.updatetimelineproperties) to cause the controls to update the timeline.
- You must provide a value for the [**StartTime**](/uwp/api/windows.media.systemmediatransportcontrolstimelineproperties.starttime), [**EndTime**](/uwp/api/windows.media.systemmediatransportcontrolstimelineproperties.endtime) and [**Position**](/uwp/api/windows.media.systemmediatransportcontrols.playbackpositionchangerequested) in order for the system controls to display a timeline for your playing item.
72
75
@@ -89,11 +92,11 @@ There is a set of system transport controls properties that relate to the curren
89
92
90
93
To handle user interaction with one of these controls, first register a handler for the associated event.
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 [**MediaPlayer**](/uwp/api/windows.media.playback.mediaplayer) and then set the corresponding property on the [**SystemMediaTransportControls**](/uwp/api/Windows.Media.SystemMediaTransportControls) object.
- In order for one of these player property events to be raised, you must set an initial value for the property. For example, [**PlaybackRateChangeRequested**](/uwp/api/windows.media.systemmediatransportcontrols.playbackratechangerequested) will not be raised until after you have set a value for the [**PlaybackRate**](/uwp/api/windows.media.systemmediatransportcontrols.playbackrate) property at least one time.
0 commit comments