Media Player

Die Medienwiedergabe umfasst das Anschauen und Anhören von Video- und Audiodateien über Inline- (in eine Seite eingebettet oder zusammen mit einer Gruppe anderer Steuerelemente) oder dedizierte Vollbilddarstellungen.

Benutzer erwarten eine Grundausstattung an Steuerelementen, wie z. B. Wiedergabe/Pause, Zurückspringen, Vorwärtsspringen, die Sie nach Bedarf ändern können (einschließlich Schaltflächen des Media Players, Hintergrund der Steuerleiste sowie Anordnung oder Layout der Steuerelemente).

Screenshot eines Media Player-Elements mit Transportsteuerelementen, die ein Video eines Marienkäfers wiedergeben

Ist dies das richtige Steuerelement?

Verwenden Sie einen Mediaplayer, wenn Sie Audio- oder Videodateien in Ihrer App wiedergeben möchten. Verwenden Sie eine Flip-Ansicht, um eine Sammlung von Bildern anzuzeigen.

Empfehlungen

MediaPlayer unterstützt helle und dunkle Designs. Dunkle Designs bieten für die Mehrzahl der Unterhaltungsszenarien jedoch eine bessere Umgebung. Der dunkle Hintergrund bietet einen besseren Kontrast, insbesondere bei schwierigen Lichtbedingungen, und verhindert Beeinträchtigungen der Steuerleiste auf der Benutzeroberfläche.

Unterstützen Sie beim Abspielen von Videoinhalten eine dedizierte Anzeigeumgebung, indem Sie den Vollbildmodus gegenüber dem Inlinemodus bevorzugen. Die Vollbildansicht ist optimal. Die Optionen sind im Inlinemodus eingeschränkt.

Wenn Sie Platz auf dem Bildschirm haben, verwenden Sie das doppelzeilige Layout. Es bietet mehr Platz für Steuerelemente als das kompakte einzeilenbasierte Layout und kann mit einer Vielzahl von Eingaben einfacher zu navigieren sein.

Die Standardsteuerelemente wurden für die Medienwiedergabe optimiert. Sie haben jedoch die Möglichkeit, dem Media Player benutzerdefinierte Optionen hinzuzufügen, die Sie benötigen, um eine optimale Benutzererfahrung für Ihre App zu bieten. Weitere Informationen zum Hinzufügen von benutzerdefinierten Steuerelementen finden Sie unter Erstellen benutzerdefinierter Transportsteuerelemente.

UWP und WinUI 2

Wichtig

Die Informationen und Beispiele in diesem Artikel sind für Apps optimiert, die das Windows App SDK und WinUI 3 verwenden, gelten jedoch allgemein für UWP-Apps, die WinUI 2 verwenden. In der UWP-API-Referenz finden Sie plattformspezifische Informationen und Beispiele.

Dieser Abschnitt enthält Informationen, die Sie zum Verwenden des Steuerelements in einer UWP- oder WinUI 2-App benötigen.

APIs für dieses Steuerelement sind im Windows.UI.Xaml.Controls-Namespace vorhanden.

Es wird empfohlen, die neueste WinUI 2 zu verwenden, um die neuesten Stile und Vorlagen für alle Steuerelemente abzurufen. WinUI 2.2 oder höher enthält eine neue Vorlage für dieses Steuerelement, die abgerundete Ecken verwendet. Weitere Informationen finden Sie unter Eckradius.

Wenn Sie für die 10-Fuß-Benutzeroberfläche entwerfen, verwenden Sie das Layout mit zwei Zeilen. Es bietet mehr Platz für Steuerelemente als das kompakte Einzeilenlayout und es ist einfacher, mit einem Gamepad für 10 Fuß zu navigieren. Weitere Informationen zum Optimieren Ihrer Anwendung für die 10-Fuß-Erfahrung finden Sie im Artikel Entwerfen für Xbox und TV .

MediaPlayerElementist nur in Windows 10 Version 1607 und höher verfügbar. Wenn Sie eine App für eine frühere Version von Windows 10 entwickeln, müssen Sie stattdessen das Steuerelement MediaElement-verwenden. Alle hier abgegebenen Empfehlungen gelten auch für MediaElement .

Erstellen eines Media Players

Die WinUI 3-Katalog-App umfasst interaktive Beispiele für die meisten WinUI 3-Steuerelemente, -Features und -Funktionen. Laden Sie die App aus dem Microsoft Store herunter, oder rufen Sie den Quellcode auf GitHub ab.

Sie fügen Ihrer App Medien hinzu, indem Sie ein MediaElement-Objekt in XAML erstellen und die Source auf eine MediaSource festlegen, die auf eine Audio- oder Videodatei verweist.

Mit diesem XAML-Code wird ein MediaPlayerElement erstellt, dessen Source-Eigenschaft auf den URI einer Videodatei festgelegt wird, bei der es sich um eine lokale Datei der App handelt. Beginnt MediaPlayerElement die Wiedergabe, wenn die Seite geladen wird. Um zu verhindern, dass Medien sofort gestartet werden, können Sie die AutoPlay-Eigenschaft auf falsefestlegen.

<MediaPlayerElement x:Name="mediaPlayerElement"
                    Source="ms-appx:///Videos/video1.mp4"
                    Width="400" AutoPlay="True"/>

Mit diesem XAML-Code wird ein MediaPlayerElement erstellt, wobei die integrierten Transportsteuerelemente aktiviert sind und die AutoPlay-Eigenschaft auf festgelegt ist. false.

<MediaPlayerElement x:Name="mediaPlayerElement"
                    Source="ms-appx:///Videos/video1.mp4"
                    Width="400"
                    AutoPlay="False"
                    AreTransportControlsEnabled="True"/>

Wichtig

Die Einstellung MediaPlayerElement.Source auf einen relativen URI (ms-appx/ms-resource) funktioniert nur in einer App, die mit einem Paketerstellungsprojekt für Windows-Anwendungen gepackt ist. Wenn Ihre App kein Paketerstellungsprojekt für Windows-Anwendungen verwendet, wird empfohlen, den relativen ms-appx:/// URI in einen vollständig aufgelösten file:/// URI zu konvertieren. Weitere Informationen finden Sie weiter unten in diesem Artikel in den Abschnitten Festlegen der Medienquelle und Öffnen lokaler Mediendateien .

Steuerelemente für den Medientransport

MediaPlayerElement verfügt über integrierte Transportsteuerelemente für Wiedergabe, Beenden, Anhalten, Lautstärke, Stummschaltung, Suche/Status, Untertitel und Audiotitelauswahl. Um diese Steuerelemente zu aktivieren, legen Sie AreTransportControlsEnabled auf fest true. Um sie zu deaktivieren, legen Sie auf fest AreTransportControlsEnabledfalse. Die Transportsteuerelemente werden durch die MediaTransportControls-Klasse dargestellt. Sie können die Transportsteuerelemente unverändert verwenden oder auf verschiedene Weise anpassen. Weitere Informationen finden Sie in der Referenz zur MediaTransportControls-Klasse und unter Erstellen von benutzerdefinierten Transportsteuerelementen.

Die Transportsteuerelemente unterstützen Layouts mit einer Zeile und mit Doppelzeile. Im ersten Beispiel sehen Sie ein einzeiliges-Layout mit der Wiedergabe/Pause-Schaltfläche links von der Medienzeitachse. Dieses Layout wird am besten für die Wiedergabe von Inlinemedien und kompakte Bildschirme reserviert.

Beispiel für MTC-Steuerelemente, einzelne Zeile

Das Layout mit doppelzeiligen Steuerelementen (siehe unten) wird für die meisten Nutzungsszenarien empfohlen, insbesondere für größere Bildschirme. Dieses Layout bietet mehr Platz für Steuerelemente und erleichtert dem Benutzer die Bedienung der Zeitachse.

Beispiel für MTC-Steuerelemente, doppelte Zeile

Steuerelemente für den Systemmedientransport

Das MediaPlayerElement ist automatisch in die Medientransportsteuerelemente des Systems integriert. Die Medientransportsteuerelemente des Systems sind die Steuerelemente, die angezeigt werden, wenn Hardwaretasten für Medien betätigt werden, z. B. die Medientasten auf Tastaturen. Weitere Informationen finden Sie unter SystemMediaTransportControls.

Festlegen der Medienquelle

Um Dateien im Netzwerk oder in die App eingebettete Dateien wiederzugeben, legen Sie die Source-Eigenschaft auf eine MediaSource mit dem Pfad der Datei fest.

Tipp

Um Dateien aus dem Internet zu öffnen, müssen Sie die Funktion Internet (Client) im Manifest Ihrer App (Package.appxmanifest) deklarieren. Weitere Informationen zum Deklarieren von Funktionen finden Sie unter Deklaration der App-Funktionen.

Dieser Code versucht, die Source-Eigenschaft des im XAML-Code definierten MediaPlayerElement auf den Pfad einer Datei festzulegen, der in ein TextBox-Element eingegeben wurde.

<TextBox x:Name="txtFilePath" Width="400"
         FontSize="20"
         KeyUp="TxtFilePath_KeyUp"
         Header="File path"
         PlaceholderText="Enter file path"/>
private void TxtFilePath_KeyUp(object sender, KeyRoutedEventArgs e)
{
    if (e.Key == Windows.System.VirtualKey.Enter)
    {
        TextBox tbPath = sender as TextBox;

        if (tbPath != null)
        {
            LoadMediaFromString(tbPath.Text);
        }
    }
}

private void LoadMediaFromString(string path)
{
    try
    {
        Uri pathUri = new Uri(path);
        mediaPlayerElement.Source = MediaSource.CreateFromUri(pathUri);
    }
    catch (Exception ex)
    {
        if (ex is FormatException)
        {
            // handle exception.
            // For example: Log error or notify user problem with file
        }
    }
}

Um die Medienquelle auf eine in die App eingebettete Mediendatei festzulegen, initialisieren Sie einen URI mit dem Pfad mit dem Präfix ms-appx:///, erstellen Sie eine MediaSource mit dem URI, und legen Sie dann source auf den URI fest. Für eine Datei namens video1.mp4 , die sich in einem Unterordner Videos befindet, würde der Pfad beispielsweise wie folgt aussehen: ms-appx:///Videos/video1.mp4

Wichtig

Die Einstellung MediaPlayerElement.Source auf einen relativen URI (ms-appx/ms-resource) funktioniert nur in einer App, die mit einem Paketerstellungsprojekt für Windows-Anwendungen gepackt ist.

Dieser Code legt die Source-Eigenschaft des mediaPlayerElement , das zuvor in XAML definiert wurde, auf fest ms-appx:///Videos/video1.mp4.

private void LoadEmbeddedAppFile()
{
    try
    {
        Uri pathUri = new Uri("ms-appx:///Videos/video1.mp4");
        mediaPlayerElement.Source = MediaSource.CreateFromUri(pathUri);
    }
    catch (Exception ex)
    {
        if (ex is FormatException)
        {
            // handle exception.
            // For example: Log error or notify user problem with file
        }
    }
}

Öffnen von lokalen Mediendateien

Zum Öffnen von Dateien im lokalen System oder aus OneDrive können Sie das FileOpenPicker-Element verwenden, um die Datei abzurufen, und Source, um die Medienquelle festzulegen; alternativ können Sie programmgesteuert auf die Benutzermedienordner zugreifen.

Falls für Ihre App jedoch der Zugriff auf die Musik- oder Videoordner ohne Benutzerinteraktion erforderlich ist (wenn Sie beispielsweise sämtliche Musik- oder Videodateien einer Sammlung des Benutzers aufzählen und in Ihrer App anzeigen), müssen Sie die Funktionen der Musik- und Videobibliothek deklarieren. Weitere Informationen finden Sie unter Dateien und Ordner in den Musik-, Bild- und Videobibliotheken.

Das FileOpenPicker-Element benötigt keine besonderen Funktionen für den Zugriff auf Dateien im lokalen Dateisystem (etwa die Ordner Musik oder Video des Benutzers), da Benutzer die vollständige Kontrolle darüber haben, auf welche Datei zugegriffen wird. Aus Sicherheits- und Datenschutzgründen ist es am sinnvollsten, die Anzahl der von der App verwendeten Funktionen möglichst gering zu halten.

So öffnen Sie lokale Medien mit FileOpenPicker

  1. Rufen Sie FileOpenPicker auf, um dem Benutzer die Auswahl einer Mediendatei zu ermöglichen.

    Verwenden Sie die FileOpenPicker-Klasse, um eine Mediendatei auszuwählen. Legen Sie fileTypeFilter fest, um anzugeben, welche Dateitypen angezeigt FileOpenPicker werden. Rufen Sie PickSingleFileAsync auf, um die Dateiauswahl zu starten und die Datei abzurufen.

  2. Verwenden Sie eine MediaSource, um die ausgewählte Mediendatei als MediaPlayerElement.Source festzulegen.

    Um die von FileOpenPicker zurückgegebene StorageFile-Methode zu verwenden, müssen Sie die CreateFromStorageFile-Methode für MediaSource aufrufen und als Source des MediaPlayerElement festlegen. Rufen Sie dann Play für das MediaElement auf, um die Medien zu starten.

In diesem Beispiel wird veranschaulicht, wie Sie die FileOpenPicker-Klasse verwenden, um eine Datei auszuwählen, und die Datei als Source eines MediaPlayerElement festlegen.

<MediaPlayerElement x:Name="mediaPlayerElement"/>
...
<Button Content="Choose file" Click="Button_Click"/>
private async void Button_Click(object sender, RoutedEventArgs e)
{
    await SetLocalMedia();
}

async private System.Threading.Tasks.Task SetLocalMedia()
{
    var openPicker = new Windows.Storage.Pickers.FileOpenPicker();
    WinRT.Interop.InitializeWithWindow.Initialize(openPicker, WinRT.Interop.WindowNative.GetWindowHandle(this));

    openPicker.FileTypeFilter.Add(".wmv");
    openPicker.FileTypeFilter.Add(".mp4");
    openPicker.FileTypeFilter.Add(".wma");
    openPicker.FileTypeFilter.Add(".mp3");

    var file = await openPicker.PickSingleFileAsync();

    // mediaPlayerElement is a MediaPlayerElement control defined in XAML
    if (file != null)
    {
        mediaPlayerElement.Source = MediaSource.CreateFromStorageFile(file);

        mediaPlayerElement.MediaPlayer.Play();
    }
}

Festlegen der Posterquelle

Mit der PosterSource-Eigenschaft können Sie eine visuelle Darstellung für Ihr MediaPlayerElement bereitstellen, bevor die Medien geladen werden. Ein PosterSource ist ein Bild, z. B. ein Screenshot, ein Filmposter oder ein Albumbild, das anstelle der Medien angezeigt wird. Die PosterSource wird in den folgenden Situationen angezeigt:

  • Wenn keine gültige Quelle festgelegt ist. Beispielsweise ist Source nicht festgelegt, wurde auf nullfestgelegt, Source oder die Quelle ist ungültig (wie bei einem MediaFailed-Ereignis).
  • Während Medien geladen werden. Beispiel: Eine gültige Quelle ist festgelegt, aber das MediaOpened-Ereignis ist noch nicht eingetreten.
  • Beim Streamen von Medien auf ein anderes Gerät.
  • Wenn die Medien nur Audio enthalten.

Dies ist ein MediaPlayerElement, dessen Source auf einen Albumtitel und dessen PosterSource auf ein Bild des Albumcovers festgelegt ist.

<MediaPlayerElement Source="ms-appx:///Media/Track1.mp4" PosterSource="ms-appx:///Media/AlbumCover.png"/>

Abblenden/Ausschalten des Gerätebildschirms verhindern

Normalerweise wird bei einem Gerät das Display abgeblendet (und schließlich ausgeschaltet), um bei Abwesenheit des Benutzers den Akku zu schonen. Bei Video-Apps muss der Bildschirm jedoch eingeschaltet bleiben, damit der Benutzer das Video sehen kann. Um ein Deaktivieren der Anzeige zu verhindern, wenn keine Benutzeraktion mehr festgestellt werden kann (z. B. bei der Wiedergabe eines Videos in einer App), können Sie DisplayRequest.RequestActive aufrufen. Mithilfe der DisplayRequest-Klasse können Sie Windows anweisen, das Display eingeschaltet zu lassen, damit der Benutzer das Video sehen kann.

Um Energie zu sparen und den Akku zu schonen, wird empfohlen, DisplayRequest.RequestRelease aufzurufen und die Displayanforderung freizugeben, wenn diese nicht mehr benötigt wird. Windows deaktiviert automatisch die aktiven Displayanforderungen der App, wenn die App vom Bildschirm entfernt wird, und aktiviert die Displayanforderungen wieder, wenn Ihre App wieder in den Vordergrund gesetzt wird.

Unten sind einige Situationen aufgeführt, in denen Sie die Displayanforderung freigeben sollten:

  • Die Videowiedergabe wird angehalten (beispielsweise durch eine Benutzeraktion, zum Puffern oder für eine Anpassung aufgrund von begrenzter Bandbreite).
  • Die Wiedergabe wird gestoppt. Beispielsweise ist die Wiedergabe des Videos beendet oder die Darstellung vorüber.
  • Ein Wiedergabefehler ist aufgetreten. Es können beispielsweise Probleme mit der Netzwerkverbindung bestehen, oder eine Datei kann beschädigt sein.

So verhindern Sie das Abblenden/Ausschalten des Bildschirms

  1. Erstellen Sie eine globale DisplayRequest-Variable. Initialisieren Sie sie in null.

    private DisplayRequest appDisplayRequest = null;
    
  2. Rufen Sie RequestActive auf, um Windows mitzuteilen, dass für die App das Display eingeschaltet bleiben muss.

  3. Rufen Sie RequestRelease auf, um die Displayanforderung freizugeben, wenn die Videowiedergabe beendet, angehalten oder durch einen Wiedergabefehler unterbrochen wird. Falls für die App keine aktiven Displayanforderungen mehr vorhanden sind, schont Windows den Akku, indem das Display abgeblendet (und schließlich ausgeschaltet) wird, wenn das Gerät nicht verwendet wird.

Jeder MediaPlayerElement.MediaPlayer hat eine PlaybackSession vom Typ MediaPlaybackSession, die verschiedene Aspekte der Medienwiedergabe steuert, wie PlaybackRate, PlaybackState und Position. Hier verwenden Sie das PlaybackStateChanged-Ereignis für MediaPlayer.PlaybackSession , um Situationen zu erkennen, in dem Sie die Anzeigeanforderung freigeben sollten. Verwenden Sie dann die NaturalVideoHeight-Eigenschaft, um festzustellen, ob eine Audio- oder Videodatei wiedergegeben wird, und lassen Sie den Bildschirm nur eingeschaltet, wenn eine Videodatei wiedergegeben wird.

<MediaPlayerElement x:Name="mediaPlayerElement" Source="ms-appx:///Videos/video1.mp4"/>
public sealed partial class MainWindow : Window
{
    public DisplayRequest appDisplayRequest = null;
    // using Microsoft.UI.Dispatching;
    private DispatcherQueue dispatcherQueue = DispatcherQueue.GetForCurrentThread();

    public MainWindow()
    {
        this.InitializeComponent();
        mediaPlayerElement.MediaPlayer.PlaybackSession.PlaybackStateChanged += 
            PlaybackSession_PlaybackStateChanged;
    }

    private void PlaybackSession_PlaybackStateChanged(MediaPlaybackSession sender, object args)
    {
        MediaPlaybackSession playbackSession = sender as MediaPlaybackSession;
        if (playbackSession != null && playbackSession.NaturalVideoHeight != 0)
        {
            if (playbackSession.PlaybackState == MediaPlaybackState.Playing)
            {
                if (appDisplayRequest is null)
                {
                    dispatcherQueue.TryEnqueue(DispatcherQueuePriority.Normal, () =>
                    {
                        appDisplayRequest = new DisplayRequest();
                        appDisplayRequest.RequestActive();
                    });
                }
            }
            else // PlaybackState is Buffering, None, Opening, or Paused.
            {
                if (appDisplayRequest is not null)
                {
                    appDisplayRequest.RequestRelease();
                    appDisplayRequest = null;
                }
            }
        }
    }
}

Programmgesteuertes Steuern der Medienwiedergabe

MediaPlayerElement stellt zahlreiche Eigenschaften, Methoden und Ereignisse zum Steuern der Audio- und Videowiedergabe über die MediaPlayerElement.MediaPlayer-Eigenschaft bereit. Eine vollständige Liste der Eigenschaften, Methoden und Ereignisse finden Sie auf der Referenzseite zu MediaPlayer.

Erweiterte Medienwiedergabeszenarien

Für komplexere Medienwiedergabeszenarien wie das Wiedergeben einer Wiedergabeliste, das Wechseln zwischen Audiosprachen oder das Erstellen benutzerdefinierter Metadatenspuren legen Sie mediaPlayerElement.Source auf ein MediaPlaybackItem oder eine MediaPlaybackList fest. Weitere Informationen dazu, wie Sie verschiedene erweiterte Medienfunktionen aktivieren, finden Sie auf der Seite Medienwiedergabe.

Ändern der Größe und Strecken von Videos

Verwenden Sie die Stretch-Eigenschaft, um zu ändern, wie der Videoinhalt und/oder die PosterSource den Container ausfüllt, in dem er sich befindet. Das Video wird dabei entsprechend dem Stretch-Wert vergrößert bzw. verkleinert oder gestreckt. Die Stretch Zustände ähneln den Bildgrößeneinstellungen bei vielen Fernsehgeräten. Sie können dieses Verhalten mit einer Schaltfläche verknüpfen und dem Benutzer die Auswahl der gewünschten Einstellung ermöglichen.

  • In keiner wird die native Auflösung des Inhalts in seiner ursprünglichen Größe angezeigt. Dies kann dazu führen, dass ein Teil des Videos zugeschnitten oder schwarze Balken an den Rändern des Videos angezeigt werden.
  • Uniform füllt so viel Raum wie möglich aus und behält dabei das Seitenverhältnis und den Videoinhalt bei. Dies kann zu horizontalen oder vertikalen schwarzen Balken an den Rändern des Videos führen. Dieser Zustand ist mit Breitbildmodi vergleichbar.
  • UniformToFill füllt den gesamten Platz unter Beibehaltung des Seitenverhältnisses aus. Dies kann dazu führen, dass ein Teil des Videos zugeschnitten wird. Dieser Zustand ist mit Vollbildmodi vergleichbar.
  • Fill füllt den gesamten Platz aus, ohne das Seitenverhältnis beizubehalten. Kein Video wird zugeschnitten, aber es kann zu einer Dehnung kommen. Dieser Zustand ist mit Streckmodi vergleichbar.

Stretch-Enumerationswerte

In diesem Beispiel werden mit einem AppBarButton-Element die Stretch-Optionen durchlaufen. Eine switch -Anweisung überprüft den aktuellen Zustand der Stretch-Eigenschaft und legt ihn auf den nächsten Wert in der Stretch -Enumeration fest. So kann der Benutzer zwischen verschiedenen Streckungszuständen wechseln.

<AppBarButton Icon="Trim"
              Label="Resize Video"
              Click="PictureSize_Click" />
private void PictureSize_Click(object sender, RoutedEventArgs e)
{
    switch (mediaPlayerElement.Stretch)
    {
        case Stretch.Fill:
            mediaPlayerElement.Stretch = Stretch.None;
            break;
        case Stretch.None:
            mediaPlayerElement.Stretch = Stretch.Uniform;
            break;
        case Stretch.Uniform:
            mediaPlayerElement.Stretch = Stretch.UniformToFill;
            break;
        case Stretch.UniformToFill:
            mediaPlayerElement.Stretch = Stretch.Fill;
            break;
        default:
            break;
    }
}

Aktivieren der Wiedergabe mit geringer Wartezeit

Legen Sie die RealTimePlayback-Eigenschafttrue für ein MediaPlayerElement.MediaPlayer auf fest, damit das Media Player-Element die anfängliche Latenz für die Wiedergabe reduziert. Dies ist von entscheidender Bedeutung für Apps mit bidirektionaler Kommunikation und kann für einige Spieleszenarien erforderlich sein. Beachten Sie, dass dieser Modus viele Ressourcen und eine höhere Leistung benötigt.

In diesem Beispiel wird ein MediaPlayerElement erstellt und RealTimePlayback auf truefestgelegt.

MediaPlayerElement mediaPlayerElement = new MediaPlayerElement();
mediaPlayerElement.MediaPlayer.RealTimePlayback = true;