MediaPlayerElement MediaPlayerElement MediaPlayerElement Class

Represents an object that uses a MediaPlayer to render audio and video to the display.

Syntax

Declaration

public class MediaPlayerElementpublic class MediaPlayerElementPublic Class MediaPlayerElement
<MediaPlayerElement .../>

Inheritance Hierarchy

Inherited Members

, , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , ,
Tag
Tag
Tag
, , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , ,

Remarks

For info about the media formats that MediaPlayerElement supports, see Supported codecs.

Architectural overview

MediaPlayerElement is a lightweight XAML control that serves as a rendering surface for the robust MediaPlayer class, which is part of the Windows.Media.Playback namespace. The majority of the media functionality is located on the underlying MediaPlayer class, which you can access through the MediaPlayer property. To change the underlying MediaPlayer for an instance of MediaPlayerElement, use the SetMediaPlayer(Windows.Media.Playback.MediaPlayer) method.

For more information about the MediaPlayer class, including guidelines on how to transition from MediaElement to MediaPlayerElement, see the Media playback page.

Set the media source

Set the Source property of the MediaPlayerElement to point to an audio or video file. You can set it to a MediaSource, MediaPlaybackItem, or MediaPlaybackList. The media files can be included with the app package or be on a network.

By default, the media that is defined by the Source property does not immediately play after the MediaPlayerElement object has loaded. To start media playback automatically, set the AutoPlay property to true.

Here’s how to create a MediaPlayerElement in XAML with the Source set to the path of a video file that is included in the app and the AutoPlay property explicitly set to true.

<MediaPlayerElement Source="Media/video1.mp4" AutoPlay="True"/>


Here’s how to create the MediaPlayerElement in code.

MediaPlayerElement mediaPlayerElement1 = new MediaPlayerElement();
mediaPlayerElement1.Source = MediaSource.CreateFromUri(new Uri("ms-appx:///Media/video1.mp4"));
mediaPlayerElement1.AutoPlay = true;

Handle media events

You can respond to common media events located on the underlying MediaPlayer such as MediaOpened, MediaEnded, and MediaFailed. If you have set the source to a MediaPlaybackItem or MediaPlaybackList, you should respond to the media events on those classes instead as they provide more information.

Transport controls

Set the AreTransportControlsEnabled property to programmatically enable and disable the built in transport controls for the MediaPlayerElement. The built in transport controls provide UI for playing, stopping, pausing, and seeking the media as well as UI for volume, mute, full window, track selection, closed captions and remaining time.

You can create your own media transport controls by setting AreTransportControlsEnabled to false, and using the Play() and Pause() methods on MediaPlayer. You can also control a rich set of properties by using the underlying MediaPlayer such as Position, Volume, IsMuted, IsLoopingEnabled, and PlaybackRate.

Tip

For better performance, avoid data binding to the Position property to reflect frequent position updates (for example with a progress bar). Instead, use the DispatcherTimer to query the Position property.

For more info and examples, see Create custom transport controls.

Full window playback

Use the IsFullWindow property to enable and disable full window rendering. When in full-window mode the display is automatically prevented from being deactivated when user action is no longer detected.

Note

We recommend that you not use MediaPlayerElement in a Popup control. If a MediaPlayerElement hosted in a Popup is switched to full-window mode, the Popup is rendered on top of the MediaPlayerElement. If you must use a MediaPlayerElement in a Popup, you should collapse the Popup when the MediaPlayerElement enters full-window mode, and restore the Popup when the MediaPlayerElement exits full-window mode. Use RegisterPropertyChangedCallback(Windows.UI.Xaml.DependencyProperty,Windows.UI.Xaml.DependencyPropertyChangedCallback) to be notified when the IsFullWindow property changes. For an example, see the Examples section.

Keep media playing

To prevent the display from being deactivated when MediaPlayerElement is not in full-window mode, you can call RequestActive(). To conserve power and battery life, you should call RequestRelease() to release the display request as soon as it is no longer required.

Here are some situations when you should release the display request:

  • Video playback is paused, for example by user action, buffering, or adjustment due to limited bandwidth.
  • Playback stops. For example, the video is done playing or the presentation is over.
  • A playback error has occurred. For example, network connectivity issues or a corrupted file. Here, you use the PlaybackStateChanged event to detect these situations. Then, use the NaturalVideoHeight property of the PlaybackSession to determine whether an audio or video file is playing, and keep the screen active only if video is playing.
<MediaPlayerElement x:Name="mpe" Source="Media/video1.mp4"/>

// Create this variable at a global scope. Set it to null.
private DisplayRequest appDisplayRequest = null;

protected override void OnNavigatedTo(NavigationEventArgs e)
{
    mpe.MediaPlayer.PlaybackSession.PlaybackStateChanged += MediaPlayerElement_CurrentStateChanged;
    base.OnNavigatedTo(e);
}

private void MediaPlayerElement_CurrentStateChanged(MediaPlaybackSession sender, object args)
{
    MediaPlaybackSession playbackSession = sender as MediaPlaybackSession;
    if (playbackSession != null && playbackSession.NaturalVideoHeight != 0)
    {
        if(playbackSession.PlaybackState == MediaPlaybackState.Playing)
        {
            if(appDisplayRequest == null)
            {
                // This call creates an instance of the DisplayRequest object
                appDisplayRequest = new DisplayRequest();
                appDisplayRequest.RequestActive();
            }
        }
        else // PlaybackState is Buffering, None, Opening, or Paused.
        {
            if(appDisplayRequest != null)
            {
                // Deactivate the display request and set the var to null.
                appDisplayRequest.RequestRelease();
                appDisplayRequest = null;
            }
        }
    }
}

Poster source

You can use the PosterSource property to provide your MediaPlayerElement with a visual representation before the media is loaded or while audio-only media is playing. . A PosterSource is an image, such as a screen shot, movie poster, or album cover, that is displayed in place of the media. The PosterSource is displayed in the following situations:

  • When a valid source is not set. For example, Source is not set, Source was set to Null, or the source is invalid (as is the case when a MediaFailed event fires).
  • While media is loading. For example, a valid source is set, but the MediaOpened event has not fired yet.
  • When media is streaming to another device.
  • When the media is audio only.

Examples

This code creates a MediaElement with the AutoPlay property explicitly set to true and the Source set to the path of a video file that is included in the app.

<MediaElement Source="Media/video1.mp4" AutoPlay="True" />
<MediaElement x:Name="mediaPlayer" 
              Source="Videos/video1.mp4" 
              Width="400" 
              AutoPlay="False"
              AreTransportControlsEnabled="True" />
<Grid>
    <Button Content="Show Popup" Click="ShowPopupClicked"/>
    <Popup x:Name="mediaPlayerPopup">
        <StackPanel Height="1400" Width="1400" Background="Blue">
            <MediaPlayerElement x:Name="mediaPlayer" 
                  AreTransportControlsEnabled="True" 
                  Source="Media/Intro.wmv"/>
            <TextBlock Text="Simple Popup"/>
            <Button Content="Close" Click="ClosePopupClicked"/>
        </StackPanel>
    </Popup>
</Grid>

long token;

protected override void OnNavigatedTo(NavigationEventArgs e)
{
    token = mediaPlayer.RegisterPropertyChangedCallback(MediaPlayerElement.IsFullWindowProperty, OnMPEFullWindowChanged);
    base.OnNavigatedTo(e);
}

protected override void OnNavigatedFrom(NavigationEventArgs e)
{
    mediaPlayer.UnregisterPropertyChangedCallback(MediaPlayerElement.IsFullWindowProperty, token);
}

private void OnMPEFullWindowChanged(DependencyObject sender, DependencyProperty dp)
{
    MediaPlayerElement mpe = (MediaPlayerElement)sender;

    if (mpe != null && dp == MediaPlayerElement.IsFullWindowProperty)
    {
        if (mpe.IsFullWindow == true)
        {
            mediaPlayerPopup.Visibility = Visibility.Collapsed;
        }
        else
        {
            mediaPlayerPopup.Visibility = Visibility.Visible;
        }
    }  
}

private void ClosePopupClicked(object sender, RoutedEventArgs e)
{
    // If the Popup is open, then close it. 
    if (mediaPlayerPopup.IsOpen) { mediaPlayerPopup.IsOpen = false; }
}

// Handles the Click event on the Button on the page and opens the Popup. 
private void ShowPopupClicked(object sender, RoutedEventArgs e)
{
    // Open the Popup if it isn't open already.
    if (!mediaPlayerPopup.IsOpen) { mediaPlayerPopup.IsOpen = true; }
}

Constructors summary

Initializes a new instance of the MediaPlayerElement class.

Properties summary

Gets or sets a value that determines whether the standard transport controls are enabled.

Identifies the AreTransportControlsEnabled dependency property.

Gets or sets a value that indicates whether media will begin playback automatically when the Source property is set.

Identifies the AutoPlay dependency property.

Gets or sets a value that specifies if the MediaPlayerElement is rendering in full window mode.

Identifies the IsFullWindow dependency property.

Gets the MediaPlayer instance used to render media.

Identifies the MediaPlayer dependency property.

Gets or sets the image source that is used for a placeholder image during MediaPlayerElement loading transition states.

Identifies the PosterSource dependency property.

Gets or sets a media source on the MediaElement.

Identifies the Source dependency property.

Gets or sets a value that describes how an MediaPlayerElement should be stretched to fill the destination rectangle.

Identifies the Stretch dependency property.

Gets or sets the transport controls for the media.

Methods summary

Sets the MediaPlayer instance used to render media.

Constructors

  • MediaPlayerElement()
    MediaPlayerElement()
    MediaPlayerElement()
    MediaPlayerElement()

    Initializes a new instance of the MediaPlayerElement class.

    public MediaPlayerElement()public MediaPlayerElement()Public Function MediaPlayerElement() As

Properties

  • AreTransportControlsEnabled
    AreTransportControlsEnabled
    AreTransportControlsEnabled
    AreTransportControlsEnabled

    Gets or sets a value that determines whether the standard transport controls are enabled.

    public bool AreTransportControlsEnabled { get; set; }public bool AreTransportControlsEnabled { get; set; }Public ReadWrite Property AreTransportControlsEnabled As bool
    <MediaPlayerElement AreTransportControlsEnabled="bool"/>
    

    Property Value

    • bool
      bool
      bool

      true if the standard transport controls are enabled; otherwise, false. The default is false.

    Remarks

    The transport controls are exposed as a MediaTransportControls object that you can access through the TransportControls property. See MediaTransportControls for more info.

    If AreTransportControlsEnabled is true, the standard transport controls are enabled and displayed on the MediaPlayerElement. If AreTransportControlsEnabled is false, the standard transport controls are not enabled and are not displayed.

    The transport controls hide themselves after a short period of no user interaction with the MediaPlayerElement. They reappear when the user interacts with the MediaPlayerElement.

    If the Width of MediaPlayerElement is not sufficient to display all of the transport controls, a subset of the controls are displayed.

  • AreTransportControlsEnabledProperty
    AreTransportControlsEnabledProperty
    AreTransportControlsEnabledProperty
    AreTransportControlsEnabledProperty

    Identifies the AreTransportControlsEnabled dependency property.

    public static DependencyProperty AreTransportControlsEnabledProperty { get; }public static DependencyProperty AreTransportControlsEnabledProperty { get; }Public Static ReadOnly Property AreTransportControlsEnabledProperty As DependencyProperty

    Property Value

  • AutoPlay
    AutoPlay
    AutoPlay
    AutoPlay

    Gets or sets a value that indicates whether media will begin playback automatically when the Source property is set.

    public bool AutoPlay { get; set; }public bool AutoPlay { get; set; }Public ReadWrite Property AutoPlay As bool
    <MediaPlayerElement AutoPlay="bool" .../>
    

    Property Value

    • bool
      bool
      bool

      true if playback is automatic; otherwise, false. The default is true.

  • AutoPlayProperty
    AutoPlayProperty
    AutoPlayProperty
    AutoPlayProperty

    Identifies the AutoPlay dependency property.

    public static DependencyProperty AutoPlayProperty { get; }public static DependencyProperty AutoPlayProperty { get; }Public Static ReadOnly Property AutoPlayProperty As DependencyProperty

    Property Value

  • IsFullWindow
    IsFullWindow
    IsFullWindow
    IsFullWindow

    Gets or sets a value that specifies if the MediaPlayerElement is rendering in full window mode.

    public bool IsFullWindow { get; set; }public bool IsFullWindow { get; set; }Public ReadWrite Property IsFullWindow As bool
    <MediaPlayerElement IsFullWindow="bool" />
    

    Property Value

    • bool
      bool
      bool

      true if the MediaPlayerElement is in full window mode; otherwise, false. The default is false.

    Remarks

    Setting and un-setting this property enables and disables full window rendering.

    Always use the IsFullWindow property to enable and disable full window rendering. This ensures system level optimizations are used during media playback.

    When in full-window mode, input events received on the MediaPlayerElement will still route through to the visual tree in the background. For example, if the MediaPlayerElement is in a ListBox, turning the scroll wheel could cause the ListBox to scroll in the background. This can cause unexpected behavior. If input events should not be routed when in full-window mode, the MediaPlayerElement should handle the events.

  • IsFullWindowProperty
    IsFullWindowProperty
    IsFullWindowProperty
    IsFullWindowProperty

    Identifies the IsFullWindow dependency property.

    public static DependencyProperty IsFullWindowProperty { get; }public static DependencyProperty IsFullWindowProperty { get; }Public Static ReadOnly Property IsFullWindowProperty As DependencyProperty

    Property Value

  • MediaPlayer
    MediaPlayer
    MediaPlayer
    MediaPlayer

    Gets the MediaPlayer instance used to render media.

    public MediaPlayer MediaPlayer { get; }public MediaPlayer MediaPlayer { get; }Public ReadOnly Property MediaPlayer As MediaPlayer

    Property Value

    Remarks

    You can use the SetMediaPlayer(Windows.Media.Playback.MediaPlayer) method to change the underlying MediaPlayer instance. Changing the MediaPlayer can cause non-trivial side effects because it can change other properties of the MediaPlayerElement.

  • MediaPlayerProperty
    MediaPlayerProperty
    MediaPlayerProperty
    MediaPlayerProperty

    Identifies the MediaPlayer dependency property.

    public static DependencyProperty MediaPlayerProperty { get; }public static DependencyProperty MediaPlayerProperty { get; }Public Static ReadOnly Property MediaPlayerProperty As DependencyProperty

    Property Value

  • PosterSource
    PosterSource
    PosterSource
    PosterSource

    Gets or sets the image source that is used for a placeholder image during MediaPlayerElement loading transition states.

    public ImageSource PosterSource { get; set; }public ImageSource PosterSource { get; set; }Public ReadWrite Property PosterSource As ImageSource
    <MediaPlayerElement PosterSource="imageUri" />
    

    Property Value

    Remarks

    A PosterSource is an image, such as a album cover or movie poster, that is displayed in place of video. It provides your MediaPlayerElement with a visual representation before the media is loaded, or when the media is audio only.

    The PosterSource is displayed in the following situations:

    • When a valid source is not set. For example, Source is not set, Source is set to Null, or the source is invalid (as is the case when a MediaFailed event fires).
    • While media is loading. For example, a valid source is set, but the MediaOpened event has not fired yet.
    • While media is streaming to another device.
    • When the media is audio only.
  • PosterSourceProperty
    PosterSourceProperty
    PosterSourceProperty
    PosterSourceProperty

    Identifies the PosterSource dependency property.

    public static DependencyProperty PosterSourceProperty { get; }public static DependencyProperty PosterSourceProperty { get; }Public Static ReadOnly Property PosterSourceProperty As DependencyProperty

    Property Value

  • Source
    Source
    Source
    Source

    Gets or sets a media source on the MediaElement.

    public IMediaPlaybackSource Source { get; set; }public IMediaPlaybackSource Source { get; set; }Public ReadWrite Property Source As IMediaPlaybackSource

    Property Value

  • SourceProperty
    SourceProperty
    SourceProperty
    SourceProperty

    Identifies the Source dependency property.

    public static DependencyProperty SourceProperty { get; }public static DependencyProperty SourceProperty { get; }Public Static ReadOnly Property SourceProperty As DependencyProperty

    Property Value

  • Stretch
    Stretch
    Stretch
    Stretch

    Gets or sets a value that describes how an MediaPlayerElement should be stretched to fill the destination rectangle.

    public Stretch Stretch { get; set; }public Stretch Stretch { get; set; }Public ReadWrite Property Stretch As Stretch
    <MediaPlayerElement Stretch="stretchMemberName" />
    

    Property Value

    • A value of the Stretch enumeration that specifies how the source visual media is rendered. The default value is Uniform.

    Remarks

    Here's what the Stretch values represent for MediaPlayerElement content:

    • None: The original size of the content is preserved.
    • Fill: The content is resized to fill the destination dimensions. The aspect ratio of the video is not preserved.
    • UniformToFill: Uniformly stretches the MediaPlayerElement to fill the available layout space while preserving the aspect ratio of the content. If the aspect ratio of the destination rectangle differs from the source, the source content is clipped to fit the destination dimensions.
    • Uniform: Uniformly stretches the MediaPlayerElement to fill the layout space while preserve the aspect ratio of the image. This will ensure that the entire image is displayed, undistorted and not cropped. This may result in letterboxing or pillarboxing on the top or sides of the image, depending on the aspect ratio of the content.
  • StretchProperty
    StretchProperty
    StretchProperty
    StretchProperty

    Identifies the Stretch dependency property.

    public static DependencyProperty StretchProperty { get; }public static DependencyProperty StretchProperty { get; }Public Static ReadOnly Property StretchProperty As DependencyProperty

    Property Value

  • TransportControls
    TransportControls
    TransportControls
    TransportControls

    Gets or sets the transport controls for the media.

    public MediaTransportControls TransportControls { get; set; }public MediaTransportControls TransportControls { get; set; }Public ReadWrite Property TransportControls As MediaTransportControls

    Property Value

Methods

  • SetMediaPlayer(Windows.Media.Playback.MediaPlayer)
    SetMediaPlayer(Windows.Media.Playback.MediaPlayer)
    SetMediaPlayer(Windows.Media.Playback.MediaPlayer)
    SetMediaPlayer(Windows.Media.Playback.MediaPlayer)

    Sets the MediaPlayer instance used to render media.

    public void SetMediaPlayer(Windows.Media.Playback.MediaPlayer mediaPlayer)public void SetMediaPlayer(Windows.Media.Playback.MediaPlayer mediaPlayer)Public Function SetMediaPlayer(mediaPlayer As Windows.Media.Playback.MediaPlayer) As void

    Parameters

    Remarks

    You can use the SetMediaPlayer(Windows.Media.Playback.MediaPlayer) method to change the underlying MediaPlayer instance. Calling this method to change the MediaPlayer can cause non-trivial side effects because it can change other properties of the MediaPlayerElement.

    Use the MediaPlayer property to get the current instance of MediaPlayer.

Device family

Windows 10 Anniversary Edition (introduced v10.0.14393.0)

API contract

Windows.Foundation.UniversalApiContract (introduced v3)

Attributes

Windows.Foundation.Metadata.ContractVersionAttribute
Windows.Foundation.Metadata.StaticAttribute
Windows.Foundation.Metadata.WebHostHiddenAttribute
Windows.Foundation.Metadata.ComposableAttribute
Windows.Foundation.Metadata.MarshalingBehaviorAttribute
Windows.Foundation.Metadata.ThreadingAttribute

Details

Assembly

Windows.UI.Xaml.Controls.dll