Lecteurs multimédias

La lecture de contenu multimédia consiste à visionner une vidéo et à écouter du son via des expériences en mode intégré (incorporé dans une page ou avec un groupe d’autres contrôles) ou plein écran dédié.

Les utilisateurs s’attendent à disposer d’un jeu de contrôle de base, tel que lecture/pause, piste précédente, piste suivante, que vous pouvez modifier selon vos besoins (notamment les boutons du lecteur multimédia, l’arrière-plan de la barre de contrôle ainsi que l’organisation et la disposition des contrôles).

Est-ce le contrôle approprié ?

Utilisez un lecteur multimédia lorsque vous voulez lire des fichiers audio ou vidéo dans votre application. Pour afficher une collection d’images, utilisez une vue inversée.

Recommandations

Le lecteur multimédia prend en charge les thèmes clairs et sombres, mais un thème sombre offre une meilleure expérience pour la plupart des scénarios de divertissement. L’arrière-plan sombre offre un meilleur contraste, notamment en cas de faible luminosité, et empêche la barre de contrôle de gêner l’affichage.

Quand vous lisez du contenu vidéo, privilégiez un affichage dédié en encourageant l’utilisation du mode plein écran au lieu du mode inséré. L’affichage plein écran offre une expérience optimale, à l’inverse du mode inséré où les options sont limitées.

Si vous avez l’immobilier d’écran, utilisez la disposition à deux lignes. Il offre plus d’espace pour les contrôles que la disposition compacte d’une seule ligne et peut être plus facile à naviguer à l’aide de diverses entrées.

Les contrôles par défaut ont été optimisés pour la lecture multimédia, mais vous avez la possibilité d’ajouter des options personnalisées dont vous avez besoin au lecteur multimédia afin de fournir la meilleure expérience pour votre application. Consultez Créer des contrôles de transport personnalisés pour en savoir plus sur l’ajout de contrôles personnalisés.

UWP et WinUI 2

Important

Les informations et les exemples de cet article sont optimisés pour les applications qui utilisent le SDK d'application Windows et WinUI 3, mais qui s’appliquent généralement aux applications UWP qui utilisent WinUI 2. Consultez la référence API de la plateforme Windows universelle pour obtenir des informations et des exemples spécifiques à la plateforme.

Cette section contient les informations dont vous avez besoin pour utiliser le contrôle dans une application de la plateforme Windows universelle ou de WinUI 2.

Les API de ce contrôle existent dans l’espace de noms Windows.UI.Xaml.Controls .

• API UWP :classe MediaPlayerElement, classe MediaTransportControls
• Ouvrez l’application WinUI 2 Gallery et voyez MediaPlayerElement en action. L’application WinUI 2 Gallery comprend des exemples interactifs de la plupart des contrôles et fonctionnalités WinUI 2. Procurez-vous l’application sur le Microsoft Store ou le code source sur GitHub.

Nous vous recommandons d’utiliser la dernière version de WinUI 2 pour obtenir les styles et modèles les plus récents pour tous les contrôles. WinUI 2.2 ou version ultérieure inclut un nouveau modèle pour ce contrôle qui utilise des coins arrondis. Pour plus d’informations, consultez Rayons des angles.

Si vous concevez pour l’expérience de 10 pieds, utilisez la disposition à deux lignes. Il offre plus d’espace pour les contrôles que la disposition compacte d’une ligne et il est plus facile de naviguer à l’aide d’un boîtier de commande pour 10 pieds. Pour plus d’informations sur l’optimisation de votre application pour l’expérience 10 pieds, consultez l’article Conception pour Xbox et TV .

MediaPlayerElementn’est disponible que dans Windows 10 version 1607 et ultérieure. Si vous développez une application pour une version antérieure de Windows 10, vous devez utiliser le contrôle MediaElement à la place. Toutes les recommandations faites ici s’appliquent également à MediaElement .

Créer un lecteur multimédia

• API importantes : classe MediaPlayerElement class, classe MediaTransportControls

Ouvrez l’application Galerie WinUI 3 et voyez MediaPlayerElement en action.

L’application WinUI 3 Gallery comprend des exemples interactifs de la plupart des contrôles et des fonctionnalités WinUI 3. Procurez-vous l’application sur le Microsoft Store ou le code source sur GitHub.

Ajoutez du contenu multimédia à votre application en créant un objet MediaPlayerElement en XAML et définissez la Source sur un MediaSource qui pointe sur un fichier audio ou vidéo.

Ce code XAML crée un MediaPlayerElement et définit sa propriété Source sur l’URI d’un fichier vidéo stocké localement dans l’application. Commence la MediaPlayerElement lecture lorsque la page se charge. Pour empêcher le média de démarrer immédiatement, vous pouvez définir la propriété Lecture automatique sur false.

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

Ce CODE XAML crée un MediaPlayerElement avec les contrôles de transport intégrés activés et la propriété Lecture automatique définie sur false.

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

Important

La définition MediaPlayerElement.Source d’un URI relatif (ms-appx/ms-resource) fonctionne uniquement dans une application empaquetée avec un projet d’empaquetage d’application Windows. Si votre application n’utilise pas de projet d’empaquetage d’application Windows, la solution de contournement recommandée consiste à convertir l’URI relatif ms-appx:/// en URI entièrement résolu file:/// . Consultez également les sections Définir la source multimédia et Ouvrir des fichiers multimédias locaux plus loin dans cet article.

Contrôles de transport multimédia

MediaPlayerElement intègre des contrôles de transport qui gèrent la lecture, l’arrêt, la mise en pause, la désactivation du micro, la recherche/progression, les sous-titres codés et la sélection de pistes audio. Pour activer ces contrôles, définissez AreTransportControlsEnabled surtrue. Pour les désactiver, définissez sur AreTransportControlsEnabledfalse. Les contrôles de transport sont représentés par la classe MediaTransportControls. Vous pouvez utiliser les contrôles de transport en l’état ou les personnaliser de différentes manières. Pour plus d’informations, consultez les informations de référence de la classe MediaTransportControls et Créer des contrôles de transport personnalisés.

Les contrôles de transport prennent en charge les dispositions sur une seule et deux lignes. Le premier exemple ci-dessous correspond à une disposition sur une ligne, avec le bouton lecture/pause situé à gauche de la chronologie des médias. Cette disposition est réservée à la lecture multimédia insérée et aux écrans compacts.

La disposition des contrôles sur deux lignes (voir ci-dessous) est recommandée pour la plupart des scénarios d’utilisation, en particulier sur les écrans plus grands. Cette disposition offre davantage d’espace pour les contrôles et simplifie l’utilisation de la chronologie.

Contrôles de transport de média système

MediaPlayerElement est automatiquement intégré aux contrôles de transport de média système. Les contrôles de transport de média système sont les contrôles qui s’affichent quand l’utilisateur appuie sur une touche de média matériel, comme les boutons de média d’un clavier. Pour plus d’informations, voir SystemMediaTransportControls.

Définir la source du média

Pour lire des fichiers sur le réseau ou des fichiers incorporés dans l’application, définissez la propriété Source sur un MediaSource avec le chemin du fichier.

Conseil

Pour ouvrir des fichiers à partir d’Internet, vous devez déclarer la fonctionnalité Internet (client) dans le manifeste de votre application (Package.appxmanifest). Pour plus d’informations sur la déclaration des fonctionnalités, voir Déclarations des fonctionnalités d’application.

Ce code tente de définir la propriété Source de MediaPlayerElement défini en XAML sur le chemin d’un fichier entré dans un TextBox.

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

Pour définir la source multimédia sur un fichier multimédia incorporé dans l’application, initialisez un URI avec le chemin d’accès préfixé avec ms-appx:///, créez un MediaSource avec l’URI, puis définissez la source sur l’URI. Par exemple, pour un fichier appelé video1.mp4 qui se trouve dans un sous-dossier Videos , le chemin d’accès se présente comme suit : ms-appx:///Videos/video1.mp4

Important

La définition MediaPlayerElement.Source d’un URI relatif (ms-appx/ms-resource) fonctionne uniquement dans une application empaquetée avec un projet d’empaquetage d’application Windows.

Ce code définit la propriété Source du MediaPlayerElement défini précédemment en XAML sur 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
        }
    }
}

Ouvrir des fichiers multimédias locaux

Pour ouvrir des fichiers sur le système local ou à partir de OneDrive, vous pouvez utiliser FileOpenPicker pour obtenir le fichier et Source pour définir la source du média, ou vous pouvez accéder par programmation aux dossiers de médias de l’utilisateur.

Si votre application a besoin d’accéder aux dossiers Musique ou Vidéo sans l’interaction de l’utilisateur, par exemple, si vous énumérez tous les fichiers de musique ou vidéo de la collection de l’utilisateur pour ensuite les afficher dans votre application, vous devez déclarer les fonctionnalités Music Library et Video Library. Pour plus d’informations, voir Fichiers et dossiers dans les bibliothèques de musique, d’images et de vidéos.

Le contrôle FileOpenPicker ne nécessite pas de fonctionnalités spéciales pour accéder aux fichiers résidant sur le système de fichiers local, comme les dossiers Musique ou Vidéo de l’utilisateur, car ce dernier bénéficie d’un contrôle total sur l’accès aux fichiers. Du point de vue de la sécurité et de la confidentialité, il est préférable de limiter le nombre de fonctionnalités utilisées par votre application.

Pour ouvrir un média local à l’aide de FileOpenPicker

1. Appelez FileOpenPicker pour permettre à l’utilisateur de choisir un fichier multimédia.

   Utilisez la classe FileOpenPicker pour sélectionner un fichier multimédia. Définissez FileTypeFilter pour spécifier les FileOpenPicker types de fichiers affichés. Appelez PickSingleFileAsync pour lancer le sélecteur de fichiers et obtenir le fichier.

2. Utilisez un MediaSource pour définir le fichier multimédia choisi en tant que MediaPlayerElement.Source.

   Pour utiliser le StorageFile retourné à partir de FileOpenPicker, vous devez appeler la méthode CreateFromStorageFile sur MediaSource et la définir comme source du MediaPlayerElement. Ensuite, appelez Play sur MediaPlayerElement.MediaPlayer pour démarrer le média.

Cet exemple montre comment utiliser le FileOpenPicker pour choisir un fichier et définir le fichier en tant que Source d’un 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();
    }
}

Définir la source de l’affiche

La propriété PosterSource vous permet de fournir à votre MediaPlayerElement une représentation visuelle avant le chargement du média. Un PosterSource est une image, telle qu’une capture d’écran, une affiche de film ou une illustration d’album, qui est affichée à la place du média. s’affiche PosterSource dans les situations suivantes :

• Quand aucune source valide n’est définie. Par exemple, Source n’est pas défini, Source a été défini sur null, ou la source n’est pas valide (comme c’est le cas lorsqu’un événement MediaFailed se produit).
• Lors du chargement du média. Par exemple, une source valide est définie mais l’événement MediaOpened ne s’est toujours pas produit.
• Quand le média est diffusé vers un autre appareil.
• Quand le média est un fichier audio uniquement.

Voici un MediaPlayerElement dont la Source est définie sur une piste d’album et PosterSource est défini sur une image de la couverture d’album.

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

Maintenir l’écran de l’appareil actif

Normalement, un appareil estompe l’affichage (et finit par le désactiver) pour préserver l’autonomie de la batterie quand l’utilisateur s’absente, mais les applications vidéo doivent maintenir l’écran allumé pour que l’utilisateur puisse voir la vidéo. Pour empêcher la désactivation de l’affichage quand aucune action de l’utilisateur n’est détectée (par exemple, quand une application lit une vidéo), vous pouvez appeler DisplayRequest.RequestActive. La classe DisplayRequest vous permet d’indiquer à Windows de laisser activé l’affichage pour permettre à l’utilisateur de voir la vidéo.

Pour économiser l’énergie et prolonger l’autonomie de la batterie, vous devez appeler DisplayRequest.RequestRelease pour libérer la demande d’affichage lorsqu’elle n’est plus nécessaire. Windows désactive automatiquement les demandes d’affichage actives de votre application lorsque cette dernière n’est plus à l’écran, et les réactive quand votre application revient au premier plan.

Voici quelques situations où vous devez libérer la demande d’affichage :

• La lecture vidéo est suspendue, par exemple suite à une action de l’utilisateur, une mise en mémoire tampon ou un réglage en raison de la bande passante limitée.
• La lecture s’arrête. Par exemple, la lecture de la vidéo ou la présentation est terminée.
• Une erreur de lecture s’est produite. Il peut s’agir de problèmes de connectivité réseau ou d’un fichier endommagé.

Pour maintenir l’écran actif

1. Créez une variable DisplayRequest globale. Initialisez-le sur null.

   private DisplayRequest appDisplayRequest = null;
   

2. Appelez RequestActive pour signaler à Windows que l’application requiert que l’affichage reste activé.

3. Appelez RequestRelease pour supprimer la demande d’affichage chaque fois que la lecture vidéo est arrêtée, suspendue ou interrompue par une erreur de lecture. Quand votre application n’a plus de demande d’affichage active, Windows préserve l’autonomie de la batterie en estompant l’affichage (et finit par le désactiver) quand l’appareil n’est pas utilisé.

Chaque MediaPlayerElement.MediaPlayer a un PlaybackSession de type MediaPlaybackSession qui contrôle divers aspects de la lecture multimédia comme PlaybackRate, PlaybackState et Position. Ici, vous utilisez l’événement PlaybackStateChanged sur MediaPlayer.PlaybackSession pour détecter les situations où vous devez libérer la demande d’affichage. Utilisez ensuite la propriété NaturalVideoHeight pour déterminer si un fichier audio ou vidéo est en cours de lecture, et maintenez l’écran actif uniquement si une vidéo est en cours de lecture.

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

Contrôler le lecteur multimédia par programmation

MediaPlayerElement propose diverses propriétés, méthodes et événements destinés à contrôler la lecture audio et vidéo par le biais de la propriété MediaPlayerElement.MediaPlayer. Pour obtenir la liste complète des propriétés, méthodes et événements, voir la page de référence de MediaPlayer.

Scénarios de lecture multimédia avancés

Pour des scénarios de lecture multimédia plus complexes tels que la lecture d’une playlist, le basculement entre les langages audio ou la création de pistes de métadonnées personnalisées, définissez MediaPlayerElement.Source sur mediaPlaybackItem ou MediaPlaybackList. Pour plus d’informations sur l’activation de plusieurs fonctionnalités multimédias avancées, consultez la page Lecture multimédia.

Redimensionner et étirer une vidéo

Utilisez la propriété Stretch pour modifier la façon dont le contenu vidéo et/ou le PosterSource remplit son conteneur. Le redimensionnement et l’étirement de la vidéo dépendent de la valeur de Stretch. Les Stretch états sont similaires aux paramètres de taille d’image sur de nombreux téléviseurs. Vous pouvez l’accrocher à un bouton et permettre ainsi à l’utilisateur d’effectuer les réglages de son choix.

• None affiche la résolution native du contenu dans sa taille d’origine. Cela peut entraîner le rognage d’une partie de la vidéo ou des barres noires aux bords de la vidéo.
• Uniform remplit autant d’espace que possible tout en préservant le rapport d’aspect et le contenu vidéo. Des bandes noires horizontales ou verticales peuvent dès lors apparaître sur les bordures de la vidéo. L’effet obtenu est comparable aux modes grand écran.
• UniformToFill remplit l’espace entier tout en préservant les proportions. Cela peut entraîner le rognage d’une partie de la vidéo. L’effet obtenu est comparable aux modes plein écran.
• Fill remplit l’espace entier, mais ne conserve pas les proportions. Aucune vidéo n’est rognée, mais l’étirement peut se produire. L’effet obtenu est comparable aux modes Étirer.

Ici, un AppBarButton est utilisé pour faire défiler les options Stretch. Une switch instruction vérifie l’état actuel de la propriété Stretch et la définit sur la valeur suivante dans l’énumération Stretch . Cela permet à l’utilisateur de parcourir les différents états d’étirement.

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

Activer la lecture à faible latence

Définissez la propriété trueRealTimePlayback sur sur un MediaPlayerElement.MediaPlayer pour permettre à l’élément lecteur multimédia de réduire la latence initiale pour la lecture. Ce mode est essentiel pour les applications de communication bidirectionnelle et peut être appliqué à certains scénarios de jeu. Sachez qu’il consomme plus de ressources et qu’il est moins économique en termes d’énergie.

Cet exemple crée un MediaPlayerElement et définit RealTimePlayback sur true.

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

Articles connexes

• Notions de base de la conception des commandes pour les applications Windows
• Notions de base de la conception de contenu pour les applications Windows