Delen via

Mediaspelers

Media afspelen omvat het weergeven en luisteren van video en audio via inline (ingesloten in een pagina of met een groep andere besturingselementen) of speciale ervaringen op volledig scherm.

Gebruikers verwachten een basisset besturingselementen, zoals afspelen/pauzeren, terugspringen, vooruitspoelen, die u naar wens kunt wijzigen (inclusief de knoppen van de mediaspeler, de achtergrond van de bedieningsbalk en de indeling of lay-out van de bediening).

Een screenshot van een mediaspelerelement met transportbedieningselementen die een video van een lieveheersbeestje afspelen

Is dit de juiste controle?

Gebruik een mediaspeler wanneer u audio of video wilt afspelen in uw app. Gebruik een bladerweergaveom een verzameling afbeeldingen weer te geven.

Aanbevelingen

De mediaspeler ondersteunt zowel lichte als donkere thema's, maar een donker thema zorgt voor een betere ervaring voor de meeste entertainmentscenario's. De donkere achtergrond biedt een beter contrast, met name voor omstandigheden met weinig licht, en beperkt de besturingsbalk om de kijkervaring te verstoren.

Wanneer je video-inhoud afspeelt, moedig dan een speciale kijkervaring aan door de modus Volledig scherm te verkiezen boven de inlinemodus. De kijkervaring op volledig scherm is optimaal en de opties zijn beperkt in de inline-modus.

Als u over voldoende schermruimte beschikt, kies dan voor de indeling met dubbele rijen. Het biedt meer ruimte voor bedieningselementen dan de compacte lay-out met één rij en kan gemakkelijker worden genavigeerd met behulp van een verscheidenheid aan invoer.

De standaardbesturingselementen zijn geoptimaliseerd voor het afspelen van media, maar u kunt aangepaste opties toevoegen die u nodig hebt aan de mediaspeler om de beste ervaring voor uw app te bieden. Ga naar Aangepaste transportbesturingselementen maken voor meer informatie over het toevoegen van aangepaste besturingselementen.

Een mediaspeler maken

Open de WinUI 3 Gallery-app en zie het MediaPlayerElement in actie

De WinUI 3 Gallery-app bevat interactieve voorbeelden van de meeste Besturingselementen, functies en functionaliteit van WinUI 3. Haal de app op uit de Microsoft Store of haal de broncode op GitHub op

Voeg media toe aan uw app door een MediaPlayerElement-object te maken in XAML en stel de bron in op een mediabron die naar een audio- of videobestand verwijst.

Deze XAML maakt een MediaPlayerElement en stelt de eigenschap Source in op de URI van een videobestand dat lokaal is in de app. De MediaPlayerElement begint te spelen wanneer de pagina wordt geladen. Als u wilt voorkomen dat media meteen worden gestart, kunt u de eigenschap AutoPlay instellen op false.

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

Met deze XAML maakt u een MediaPlayerElement- met de ingebouwde bedieningselementen ingeschakeld en de eigenschap AutoPlay ingesteld op false.

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

Belangrijk

Instellen op MediaPlayerElement.Source een relatieve URI (ms-appx/ms-resource) werkt alleen in een app die is verpakt met een Windows-Application Packaging Project. Als uw app geen gebruikmaakt van een Windows-project voor het verpakken van toepassingen, is de aanbevolen tijdelijke oplossing om de relatieve ms-appx:/// URI te converteren naar een volledig omgezette file:/// URI. Zie ook de secties Mediabron instellen en Lokale mediabestanden openen verder in dit artikel.

Mediabedieningselementen

MediaPlayerElement heeft ingebouwde transportbedieningselementen die afspelen, stoppen, pauzeren, volume, dempen, zoeken/voortgang, ondertiteling en audiotrackselectie afhandelen. Als u deze besturingselementen wilt inschakelen, stelt u AreTransportControlsEnabled in op true. Als u ze wilt uitschakelen, stelt u deze in AreTransportControlsEnabled op false. De transportbesturingen worden vertegenwoordigd door de klasse MediaTransportControls . U kunt de transportbesturingselementen as-isgebruiken of op verschillende manieren aanpassen. Voor meer informatie, zie de MediaTransportControls klassereferentie en Aangepaste transportbesturingselementen maken.

De transportbesturing ondersteunt lay-outs met één of twee rijen. Het eerste voorbeeld hier is een lay-out met één rij, met de afspeel-/pauzeknop aan de linkerkant van de mediatijdlijn. Deze lay-out is het beste gereserveerd voor het afspelen van inline media en compacte schermen.

Voorbeeld van MTC-bedieningselementen, enkele rij

De lay-out van de bedieningselementen met dubbele rij (hieronder) wordt aanbevolen voor de meeste gebruiksscenario's, vooral op grotere schermen. Deze lay-out biedt meer ruimte voor bedieningselementen en maakt de tijdlijn gemakkelijker te bedienen voor de gebruiker.

Voorbeeld van MTC-bedieningselementen, dubbele rij

Systeemmedia bedieningsknoppen

MediaPlayerElement is automatisch geïntegreerd met de mediatransportregelaars van het systeem. De besturingselementen voor het mediatransport van het systeem zijn de besturingselementen die worden weergegeven wanneer hardwarematige mediatoetsen worden ingedrukt, zoals de mediaknoppen op toetsenborden. Zie SystemMediaTransportControls voor meer informatie.

De mediabron instellen

Als u bestanden wilt afspelen op het netwerk of bestanden die zijn ingesloten met de app, stelt u de eigenschap Source in op een MediaSource met het pad van het bestand.

Aanbeveling

Als u bestanden van internet wilt openen, moet u de internetmogelijkheid (client) declareren in het manifest van uw app (Package.appxmanifest). Zie Declaraties van app-mogelijkheden voor meer informatie over het declareren van mogelijkheden.

Met deze code wordt geprobeerd de eigenschap Source van het MediaPlayerElement in te stellen gedefinieerd in XAML op het pad van een bestand dat is ingevoerd in een Tekstvak.

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

Als u de mediabron wilt instellen op een mediabestand dat is ingesloten in de app, initialiseert u een Uri met het pad voorafgegaan door ms-appx:///, maakt u een MediaSource met de Uri en stelt u de Bron in op de Uri. Voor een bestand met de naamvideo1.mp4 dat zich in een submap Video's bevindt, ziet het pad er bijvoorbeeld als volgt uit: ms-appx:///Videos/video1.mp4

Belangrijk

Instellen op MediaPlayerElement.Source een relatieve URI (ms-appx/ms-resource) werkt alleen in een app die is verpakt met een Windows-Application Packaging Project.

Met deze code wordt de eigenschap Source van het MediaPlayerElement dat eerder in XAML is gedefinieerd, ingesteld op 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
        }
    }
}

Open lokale mediabestanden

Als u bestanden wilt openen op het lokale systeem of vanuit OneDrive, kunt u de FileOpenPicker gebruiken om het bestand op te halen en de bron om de mediabron in te stellen, of u kunt programmatisch toegang krijgen tot de mediamappen van de gebruiker.

Als uw app zonder tussenkomst van de gebruiker toegang moet hebben tot de mappen Muziek of Video , bijvoorbeeld als u alle muziek- of videobestanden in de verzameling van de gebruiker opsomt en deze in uw app weergeeft, moet u de mogelijkheden van de muziekbibliotheek en de videobibliotheek declareren. Zie Bestanden en mappen in de bibliotheken Muziek, Afbeeldingen en Video'svoor meer informatie.

De FileOpenPicker vereist geen speciale mogelijkheden om toegang te krijgen tot bestanden op het lokale bestandssysteem, zoals de mappen Muziek of Video van de gebruiker, aangezien de gebruiker volledige controle heeft over welk bestand wordt geopend. Vanuit het oogpunt van beveiliging en privacy is het het beste om het aantal mogelijkheden dat uw app gebruikt te minimaliseren.

Lokale media openen met FileOpenPicker

  1. Roep FileOpenPicker aan om de gebruiker een mediabestand te laten kiezen.

    Gebruik de klasse FileOpenPicker om een mediabestand te selecteren. Stel de FileTypeFilter- in om op te geven welke bestandstypen door de FileOpenPicker worden weergegeven. Roep PickSingleFileAsync aan om de bestandskiezer te starten en het bestand op te halen.

  2. Gebruik een MediaSource om het gekozen mediabestand als de MediaPlayerElement.Sourcein te stellen.

    Als u het StorageFile wilt gebruiken dat wordt geretourneerd door de FileOpenPicker, moet u de methode CreateFromStorageFile op MediaSource aanroepen en deze instellen als de bron van het MediaPlayerElement. Roep vervolgens Play aan op de MediaPlayerElement.MediaPlayer om de media te starten.

In dit voorbeeld ziet u hoe u de FileOpenPicker gebruikt om een bestand te kiezen en het bestand in te stellen als de bron van een MediaPlayerElement.

<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();
    }
}

De posterbron instellen

U kunt de eigenschap PosterSource gebruiken om uw MediaPlayerElement te voorzien van een visuele weergave voordat de media worden geladen. A PosterSource is een afbeelding, zoals een screenshot, filmposter of albumhoes, die wordt weergegeven in plaats van de media. De PosterSource wordt weergegeven in de volgende situaties:

  • Wanneer er geen geldige bron is ingesteld. Bijvoorbeeld, de bron is niet ingesteld, Source werd ingesteld op null, of de bron is ongeldig (zoals het geval is wanneer een MediaFailed gebeurtenis plaatsvindt).
  • Terwijl de media worden geladen. Er is bijvoorbeeld een geldige bron ingesteld, maar de gebeurtenis MediaOpened is nog niet opgetreden.
  • Wanneer media naar een ander apparaat worden gestreamd.
  • Wanneer de media alleen uit audio bestaan.

Hier volgt een MediaPlayerElement met de Source ingesteld op een albumtrack en met de PosterSource ingesteld op een afbeelding van de albumhoes.

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

Houd het scherm van het apparaat actief

Doorgaans dimt een apparaat het scherm (en schakelt het uiteindelijk uit) om de batterij te sparen wanneer de gebruiker weg is, maar video-apps moeten het scherm ingeschakeld houden zodat de gebruiker de video kan zien. Als u wilt voorkomen dat het scherm wordt gedeactiveerd wanneer er geen gebruikersactie meer wordt gedetecteerd, bijvoorbeeld wanneer een app video afspeelt, kunt u DisplayRequest.RequestActive aanroepen. Met de klasse DisplayRequest kunt u Windows laten weten dat het beeldscherm ingeschakeld moet blijven, zodat de gebruiker de video kan zien.

Om energie en batterijduur te besparen, moet u DisplayRequest.RequestRelease aanroepen om de weergaveaanvraag vrij te geven wanneer deze niet langer nodig is. Windows deactiveert automatisch de actieve weergaveverzoeken van uw app wanneer uw app van het scherm verdwijnt en activeert ze opnieuw wanneer uw app weer op de voorgrond komt.

Hier volgen enkele situaties waarin u de weergaveaanvraag moet vrijgeven:

  • Het afspelen van video's wordt bijvoorbeeld onderbroken door actie van de gebruiker, buffering of aanpassing vanwege beperkte bandbreedte.
  • De weergave stopt. De video is bijvoorbeeld klaar met afspelen of de presentatie is voorbij.
  • Er is een afspeelfout opgetreden. Bijvoorbeeld netwerkverbindingsproblemen of een beschadigd bestand.

Het scherm actief houden

  1. Maak een algemene DisplayRequest-variabele . Initialiseer het naar null.

    private DisplayRequest appDisplayRequest = null;

  2. Bel RequestActive aan om Windows te laten weten dat de app vereist dat het scherm ingeschakeld blijft.

  3. OproepverzoekRelease om het weergaveverzoek vrij te geven wanneer het afspelen van video wordt gestopt, onderbroken of onderbroken door een afspeelfout. Wanneer uw app geen actieve weergaveverzoeken meer heeft, bespaart Windows de batterij door het beeldscherm te dimmen (en uiteindelijk uit te schakelen) wanneer het apparaat niet wordt gebruikt.

Elke MediaPlayerElement.MediaPlayer heeft een PlaybackSession van het type MediaPlaybackSession die verschillende aspecten van het afspelen van media regelt, zoals PlaybackRate, PlaybackState en Position. Hier gebruikt u de gebeurtenis PlaybackStateChanged op MediaPlayer.PlaybackSession om situaties te detecteren waarin u de weergaveaanvraag moet vrijgeven. Gebruik vervolgens de eigenschap NaturalVideoHeight om te bepalen of een audio- of videobestand wordt afgespeeld en houd het scherm alleen actief als er video wordt afgespeeld.

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

Bedien de mediaspeler programmatisch

MediaPlayerElement biedt tal van eigenschappen, methoden en gebeurtenissen voor het beheren van het afspelen van audio en video via de eigenschap MediaPlayerElement.MediaPlayer . Voor een volledig overzicht van eigenschappen, methoden en gebeurtenissen, zie de MediaPlayer referentiepagina.

Geavanceerde scenario's voor het afspelen van media

Voor complexere scenario's voor het afspelen van media, zoals het afspelen van een afspeellijst, het schakelen tussen audiotalen of het maken van aangepaste metagegevenstracks, stelt u de MediaPlayerElement.Source in op een MediaPlaybackItem of een MediaPlaybackList. Zie de pagina Media afspelen voor meer informatie over het inschakelen van verschillende geavanceerde mediafunctionaliteiten.

Video vergroten of verkleinen en uitrekken

Gebruik de eigenschap Stretch om te veranderen hoe de video-inhoud en/of de PosterSource de container vult. Hiermee wordt het formaat en de rek van de video aangepast, afhankelijk van de waarde Uitrekken . De Stretch statussen zijn vergelijkbaar met de instellingen voor beeldformaat op veel tv-toestellen. U kunt dit aansluiten op een knop en de gebruiker laten kiezen welke instelling hij verkiest.

  • Geen enkele geeft de native resolutie van de inhoud weer in de oorspronkelijke grootte. Dit kan ertoe leiden dat een deel van de video wordt bijgesneden of dat zwarte balken aan de randen van de video worden weergegeven.
  • Uniform vult zo veel mogelijk ruimte terwijl de hoogte-breedteverhouding en de video-inhoud behouden blijven. Dit kan resulteren in horizontale of verticale zwarte balken aan de randen van de video. Dit is vergelijkbaar met breedbeeldmodi.
  • UniformToFill vult de hele ruimte terwijl de hoogte-breedteverhouding behouden blijft. Dit kan ertoe leiden dat een deel van de video wordt bijgesneden. Dit is vergelijkbaar met modi voor volledig scherm.
  • vult de hele ruimte, maar behoudt de hoogte-breedteverhouding niet. Geen enkele video wordt bijgesneden, maar uitrekken kan plaatsvinden. Dit is vergelijkbaar met stretch-modi.

Stretch-enumeratiewaarden

Hier wordt een AppBarButton- gebruikt om door de Stretch opties te bladeren. Een switch instructie controleert de huidige status van de eigenschap Stretch en stelt deze in op de volgende waarde in de Stretch opsomming. Hierdoor kan de gebruiker door de verschillende stretch-posities bladeren.

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

Afspelen met lage latentie inschakelen

Stel de eigenschap RealTimePlayback in op true op een MediaPlayerElement.MediaPlayer om het mediaspelerelement in te schakelen om de initiële latentie voor het afspelen te verminderen. Dit is van cruciaal belang voor apps voor tweerichtingscommunicatie en kan van toepassing zijn op sommige gamescenario's. Houd er rekening mee dat deze modus arbeidsintensiever en minder energie-efficiënt is.

In dit voorbeeld wordt een MediaPlayerElement gemaakt en wordt RealTimePlayback ingesteld op true.

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

UWP en WinUI 2

Belangrijk

De informatie en voorbeelden in dit artikel zijn geoptimaliseerd voor apps die gebruikmaken van de Windows App SDK en WinUI 3, maar zijn algemeen van toepassing op UWP-apps die gebruikmaken van WinUI 2. Zie de UWP API-referentie voor platformspecifieke informatie en voorbeelden.

Deze sectie bevat informatie die u nodig hebt om het besturingselement te gebruiken in een UWP- of WinUI 2-app.

API's voor deze controle bevinden zich in de Windows.UI.Xaml.Controls naamruimte.

U wordt aangeraden de nieuwste WinUI 2 te gebruiken om de meest recente stijlen en sjablonen voor alle besturingselementen te verkrijgen. WinUI 2.2 of hoger bevat een nieuwe sjabloon voor dit besturingselement dat gebruikmaakt van afgeronde hoeken. Zie Hoekstraal voor meer informatie.

Als u ontwerpt voor de 10-foot gebruikerservaring, kies dan voor de indeling met dubbele rijen. Het biedt meer ruimte voor bedieningselementen dan de compacte lay-out met één rij en het is gemakkelijker te navigeren met behulp van een gamepad voor 10 voet. Zie het artikel Ontwerpen voor Xbox en TV voor meer informatie over het optimaliseren van uw toepassing voor de 10-footinterface.

MediaPlayerElement is alleen beschikbaar in Windows 10, versie 1607 en hoger. Als u een app ontwikkelt voor een eerdere versie van Windows 10, dient u in plaats daarvan het MediaElement-besturingselement te gebruiken. Alle aanbevelingen die hier worden gedaan, zijn ook van MediaElement toepassing.