Freigeben über

Media Player

  • Artikel

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 Ladybugs wiedergeben

Ist dies das richtige Steuerelement?

Verwenden Sie einen Media Player, wenn Sie Audio oder Video in Ihrer App wiedergeben möchten. Um eine Sammlung von Bildern anzuzeigen, verwenden Sie eine Flip-Ansicht.

Empfehlungen

Der Media Player unterstützt sowohl helle als auch dunkle Designs, aber dunkles Design bietet für die meisten Unterhaltungsszenarien ein besseres Erlebnis. Der dunkle Hintergrund bietet einen besseren Kontrast, insbesondere bei schlechten Lichtverhältnissen, und schränkt die Steuerungsleiste ein, um die Anzeige zu beeinträchtigen.

Fördern Sie beim Wiedergeben von Videoinhalten eine dedizierte Anzeigeerfahrung, indem Sie den Vollbildmodus über den Inlinemodus bewerben. Die Vollbildanzeige ist optimal, und optionen sind im Inlinemodus eingeschränkt.

Wenn Sie über die Bildschirmfläche verfügen, wechseln Sie mit dem Doppelzeilenlayout. Es bietet mehr Platz für Steuerelemente als das kompakte Einzeilenlayout und kann einfacher mit einer Vielzahl von Eingaben navigieren.

Die Standardsteuerelemente wurden für die Medienwiedergabe optimiert. Sie haben jedoch die Möglichkeit, dem Media Player benutzerdefinierte Optionen hinzuzufügen, um die beste Benutzererfahrung für Ihre App zu bieten. Besuchen Sie " Erstellen benutzerdefinierter Transportsteuerelemente ", um mehr über das Hinzufügen benutzerdefinierter Steuerelemente zu erfahren.

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.

Wir empfehlen die Verwendung der neuesten WinUI 2 zum Abrufen der aktuellsten Stile und Vorlagen für alle Steuerelemente. 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 die 10-Fuß-Oberfläche entwerfen, verwenden Sie das Layout mit doppelter Zeile. 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 ".

MediaPlayerElement ist erst ab Windows 10, Version 1607 und spätere 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 eingegangenen Empfehlungen gelten MediaElement auch für.

Erstellen eines Media Players

Öffnen Sie die WinUI 3 Gallery-App, und sehen Sie das MediaPlayerElement in Aktion.

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. Die MediaPlayerElement Wiedergabe beginnt, wenn die Seite geladen wird. Um Medien sofort zu unterdrücken, können Sie die Eigenschaft "Automatische Wiedergabe " auf " false.

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

Dieser XAML-Code erstellt ein MediaPlayerElement mit aktivierten integrierten Transportsteuerelementen und der Eigenschaft "Automatische Wiedergabe " auf 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 Windows Application Packaging Project verpackt ist. Wenn Ihre App kein Windows Application Packaging Project verwendet, empfiehlt es sich, den relativen ms-appx:/// URI in einen vollständig aufgelösten file:/// URI zu konvertieren. Lesen Sie auch die Abschnitte "Medienquelle festlegen" und "Lokale Mediendateien öffnen" weiter unten in diesem Artikel.

Medientransportsteuerelemente

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 true. Um sie zu deaktivieren, legen Sie diese AreTransportControlsEnabled auf false. Die Transportsteuerelemente werden durch die MediaTransportControls-Klasse dargestellt. Sie können die Transportsteuerelemente wie folgt 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 Ein- und Doppelzeilenlayouts. Das erste Beispiel hier ist ein Einzeilenlayout mit der Schaltfläche "Wiedergabe/Pause" links neben der Medienzeitachse. Dieses Layout ist am besten für die Inlinemedienwiedergabe und kompakte Bildschirme reserviert.

Beispiel für MTC-Steuerelemente, einzelne Zeile

Das Layout für Doppelzeilensteuerelemente (unten) wird für die meisten Verwendungsszenarien empfohlen, insbesondere auf größeren Bildschirmen. Dieses Layout bietet mehr Platz für Steuerelemente und erleichtert 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 Steuerelemente für den Systemmedientransport sind die Steuerelemente, die angezeigt werden, wenn Hardwaremedientasten gedrückt 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 Internetfunktion (Client) im Manifest Ihrer App (Package.appxmanifest) deklarieren. Weitere Informationen zum Deklarieren von Funktionen finden Sie unter App-Funktionsdeklarationen.

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 Pfadpräfix ms-appx:///, erstellen Sie eine MediaSource mit dem URI, und legen Sie dann die Quelle auf den URI fest. For example, for a file called video1.mp4 that is in a Videos subfolder, the path would look like: 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 Windows Application Packaging Project verpackt ist.

Dieser Code legt die Source-Eigenschaft des MediaPlayerElements fest, das zuvor in XAML ms-appx:///Videos/video1.mp4definiert wurde.

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
        }
    }
}

Lokale Mediendateien öffnen

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.

Wenn Ihre App ohne Benutzerinteraktion auf die Musik- oder Videoordner zugreifen muss, z. B. wenn Sie alle Musik- oder Videodateien in der Sammlung des Benutzers aufzählen und in Ihrer App anzeigen, müssen Sie die Funktionen "Musikbibliothek" 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 empfiehlt es sich, die Anzahl der funktionen zu minimieren, die Ihre App verwendet.

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 den 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 vom FileOpenPicker zurückgegebene StorageFile-Datei zu verwenden, müssen Sie die CreateFromStorageFile-Methode für MediaSource aufrufen und als Quelle des MediaPlayerElements 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. A PosterSource ist ein Bild, z. B. ein Screenshot, ein Filmposter oder ein Albumbild, das anstelle der Medien angezeigt wird. Dies PosterSource wird in den folgenden Situationen angezeigt:

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"/>

Bildschirm des Geräts aktiv halten

In der Regel wird das Display von einem Gerät abgeblendet (und schließlich deaktiviert), um die Akkulaufzeit zu sparen, wenn der Benutzer abwesend ist. Video-Apps müssen den Bildschirm jedoch eingeschaltet lassen, 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 Anzeigeanforderungen Ihrer App, wenn Ihre App den Bildschirm auszieht, und aktiviert sie erneut, wenn Ihre App wieder im Vordergrund angezeigt wird.

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

  • Die Videowiedergabe wird z. B. durch Benutzeraktion, Pufferung oder Anpassung aufgrund begrenzter Bandbreite angehalten.
  • 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. Wenn Ihre App keine aktiven Anzeigeanforderungen mehr aufweist, spart Windows die Akkulaufzeit, indem sie die Anzeige abgeblendet (und schließlich deaktiviert) 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 auf MediaPlayer.PlaybackSession, um Situationen zu erkennen, in denen Sie die Displayanforderung 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 des Media Players

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 die Wiedergabe einer Wiedergabeliste, das Wechseln zwischen Audiosprachen oder das Erstellen von benutzerdefinierten Metadatentiteln, 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 auf vielen Fernsehgeräten. Sie können dies mit einer Schaltfläche verknüpfen und dem Benutzer erlauben, auszuwählen, welche Einstellung sie bevorzugen.

  • Keine zeigt die systemeigene Auflösung des Inhalts in seiner ursprünglichen Größe an. Dies kann dazu führen, dass einige der Videoausschnitte oder schwarze Balken an den Rändern des Videos zugeschnitten werden.
  • Uniform füllt so viel Platz wie möglich aus, während das Seitenverhältnis und der Videoinhalt beibehalten werden. Dies kann zu horizontalen oder vertikalen schwarzen Balken an den Rändern des Videos führen. Dies ähnelt den Breitbildmodi.
  • UniformToFill füllt den gesamten Platz unter Beibehaltung des Seitenverhältnisses aus. Dies kann dazu führen, dass ein Teil des Videos zugeschnitten wird. Dies ähnelt den Vollbildmodi.
  • Fill füllt den gesamten Platz aus, ohne das Seitenverhältnis beizubehalten. Kein Video wird zugeschnitten, aber das Strecken kann auftreten. Dies ähnelt den Streckungsmodi.

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. Auf diese Weise kann der Benutzer die verschiedenen Streckungszustände durchlaufen.

<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 Latenz

Legen Sie die RealTimePlayback-Eigenschaft true auf ein MediaPlayerElement.MediaPlayer fest, um das Media Player-Element zu aktivieren, um die anfängliche Latenz für die Wiedergabe zu verringern. Dies ist für bidirektionale Kommunikations-Apps wichtig und kann für einige Spielszenarien anwendbar sein. Beachten Sie, dass dieser Modus ressourcenintensiver und weniger energieeffizient ist.

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

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