MediaElement

MediaElement est une commande de lecture vidéo et audio. Les médias pris en charge par la plateforme sous-jacente peuvent être lus à partir des sources suivantes :

• Le Web, à l’aide d’un URI (HTTP ou HTTPS).
• Une ressource intégrée dans l’application de la plate-forme, utilisant le schéma URI embed://.
• Fichiers provenant du système de fichiers local de l’application, utilisant le schéma URI filesystem://.
• Toute source valide via un Stream.

MediaElement peut utiliser les commandes de lecture de la plate-forme, qui sont appelées commandes de transport. Cependant, ils sont désactivés par défaut et peuvent être remplacés par vos propres contrôles de transport. Les captures d’écran suivantes montrent MediaElement en train de lire une vidéo avec les commandes de transport de la plateforme :

Le MediaElement utilise les implémentations de plate-forme suivantes.

Prise en main

Pour utiliser la fonction MediaElement de la boîte à outils communautaire MAUI .NET, vous devez suivre les étapes suivantes.

Installer le package NuGet

Avant de pouvoir utiliser MediaElement au sein de votre application, vous devez installer le package CommunityToolkit.Maui.MediaElementNuGet et ajouter une ligne d’initialisation dans votre fichier MauiProgram.cs. Comme suit :

Nom du package :CommunityToolkit.Maui.MediaElement

URL du package :https://www.nuget.org/packages/CommunityToolkit.Maui.MediaElement

Initialisation du package

Tout d'abord, vous devez ajouter l'instruction « using » en haut de votre fichier MauiProgram.cs.

using CommunityToolkit.Maui.MediaElement;

Pour utiliser MediaElement correctement, la méthode UseMauiCommunityToolkitMediaElement doit être appelée sur la classe MauiAppBuilder lors de l'amorçage du fichier MauiProgram.cs d'une application. L'exemple suivant montre comment effectuer cette opération.

var builder = MauiApp.CreateBuilder();
builder
    .UseMauiApp<App>()
    .UseMauiCommunityToolkitMediaElement(enableForegroundService: true); // Set to `false` if Rich Notifications and background playback is not required

Pour plus d'informations sur la procédure à suivre, reportez-vous à la page Prise en main.

Initialisation spécifique à la plateforme

Pour accéder à la fonctionnalité MediaElement, la configuration suivante spécifique à la plateforme est obligatoire.

[Activity(Theme = "@style/Maui.SplashTheme", ResizeableActivity = true, MainLauncher = true, LaunchMode = LaunchMode.SingleTask)]
public class MainActivity : MauiAppCompatActivity
{
}

<key>UIBackgroundModes</key>
<array>
    <string>bluetooth-central</string>
    <string>audio</string>
</array>
<key>NSLocalNetworkUsageDescription</key>
<string></string>

<key>UIBackgroundModes</key>
<array>
    <string>audio</string>
</array>

Formats pris en charge

Les formats multimédias pris en charge peuvent varier d’une plateforme à l’autre. Dans certains cas, ils peuvent même dépendre des décodeurs disponibles ou installés sur le système d’exploitation utilisé lors de l’exécution de votre application. Pour obtenir des informations plus détaillées sur les formats pris en charge par chaque plateforme, veuillez consulter les liens ci-dessous.

Scénarios courants

Les sections suivantes décrivent les scénarios d’utilisation les plus courants de la fonction MediaElement

Lecture de médias distants

Un MediaElement peut lire des fichiers multimédias distants en utilisant les schémas URI HTTP et HTTPS. Pour ce faire, la propriété Source est remplacée par l’URI du fichier multimédia :

<toolkit:MediaElement Source="https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4"
              ShouldShowPlaybackControls="True" />

Par défaut, la lecture du média défini par la propriété Source ne commence pas immédiatement après l’ouverture du média. Pour activer la lecture automatique des médias, réglez la propriété ShouldAutoPlay sur true.

Les contrôles de lecture multimédia fournis par la plate-forme sont activés par défaut et peuvent être désactivés en définissant la propriété ShouldShowPlaybackControls sur false.

Utiliser des notifications de contenu enrichi

Un MediaElement peut afficher des notifications multimédias enrichies sur Android, iOS, Mac Catalyst et Windows lorsque le média est en cours de lecture en arrière-plan. Pour activer les notifications multimédias enrichies, les étapes suivantes sont requises :

1. Activez la lecture vidéo en arrière-plan en configurant le paramètre enableForegroundService à true lors de l'appel de la méthode UseMauiCommunityToolkitMediaElement dans MauiProgram.cs. Pour plus d’informations, reportez-vous à la section Initialisation du package ci-dessus.
2. Configuration spécifique de la plateforme, comme décrit dans la section d’initialisation spécifique à la plateforme.
3. Définissez les propriétés MetadataTitle, MetadataArtist et MetadataArtworkUrl pour fournir des métadonnées du média en cours de lecture, comme décrit dans la section Utilisation des métadonnées.

Service de premier plan sur Android

Pour activer la lecture en arrière-plan sur Android, définissez le paramètre enableForegroundService sur true lors de l'appel de la méthode UseMauiCommunityToolkitMediaElement dans MauiProgram.cs. MediaElement ne nécessite pas d’ajout d’autorisations supplémentaires AndroidManifest.xml pour le service de premier plan : l’appel de la méthode du générateur avec enableForegroundService: true est suffisant pour activer les fonctionnalités de notification et de lecture en arrière-plan. Quand enableForegroundService est défini à true, la boîte à outils ajoutera automatiquement toutes les entrées de manifeste Android requises pour le service de premier plan et les notifications. Si enableForegroundService est false et que vous tentez d’utiliser des fonctions de lecture en arrière-plan, une exception peut être levée sur Android.

Utilisation des métadonnées

Un MediaElement peut utiliser des métadonnées pour MediaElement.MetadataTitle, MediaElement.MetadataArtist et MediaElement.MetadataArtworkUrl. Vous pouvez ajuster le titre ou l'artiste pour afficher ce qui est actuellement joué sur les contrôles de l'écran de verrouillage pour Windows, Mac Catalyst, iOS et Android. Vous pouvez définir une URL locale ou distante avec une œuvre d’art pour le lockscreen. La qualité d’affichage doit être d’au moins 1080P. Il doit s’agir d’un URL et être soit .jpg, soit .png

<toolkit:MediaElement 
    MetadataTitle="Title"
    MetadataArtist="Artist"
    MetadataArtworkUrl="http://www.myownpersonaldomain.com/image.jpg" />

    MediaElement.MetadataTitle="Title";
    MediaElement.MetadataArtist="Artist";
    MediaElement.MetadataArtworkUrl="http://www.myownpersonaldomain.com/image.jpg";

Utilisation de TextureView

Un MediaElement peut utiliser TextureView sur la plateforme Android. Le comportement par défaut de la plateforme consiste à utiliser SurfaceView. L’utilisation de Texture View permet la prise en charge des transparences et d’autres effets. Cela est défini en modifiant le générateur à utiliser

.UseMauiCommunityToolkitMediaElement(static options => 
{
				options.SetDefaultAndroidViewType(AndroidViewType.TextureView);
})

Vous pouvez également définir TextureView pour chaque élément multimédia que vous utilisez. Cela peut être défini dans XAML et dans le code-behind. L'utilisation de cette manière remplacera la commande builder .UseMauiCommunityToolkitMediaElement().

var mediaElement = new MediaElement
{
    AndroidViewType = AndroidViewType.TextureView
}

<toolkit:MediaElement AndroidViewType="TextureView" />

Lecture de médias locaux

Les médias locaux peuvent être lus à partir des sources suivantes :

• Une ressource intégrée dans l’application de la plate-forme, utilisant le schéma URI embed://.
• Fichiers provenant du système de fichiers local de l’application, utilisant le schéma URI filesystem://.

Lire les médias intégrés dans le package de l’application

Un MediaElement peut lire des fichiers multimédias qui sont intégrés dans le package de l’application, en utilisant le schéma URI embed://. Les fichiers multimédias sont intégrés dans le package de l’application en les plaçant dans le projet de plateforme.

Pour activer un fichier multimédia pour la lecture à partir des ressources locales, ajoutez le fichier au dossier Resources/Raw de votre projet .NET MAUI. Lorsqu’un fichier est ajouté à la racine, l’URI est embed://MyFile.mp4.

Vous pouvez également placer les fichiers dans des sous-dossiers. Si MyFile.mp4 se trouve dans Resources/Raw/MyVideos, l’URI à utiliser avec MediaElement est embed://MyVideos/MyFile.mp4.

Vous trouverez ci-dessous un exemple d’utilisation de cette syntaxe en XAML.

<toolkit:MediaElement Source="embed://MyFile.mp4"
              ShouldShowPlaybackControls="True" />

Lire un média à partir d’un flux

Vous pouvez lire un média à partir d’un Streamscénario qui permet des scénarios où la capture et la lecture de bout en bout restent en mémoire.

Prenons l’exemple de capture d’une vidéo à l’aide MediaPickerde :

var videoResult = await MediaPicker.Default.CaptureVideoAsync(new MediaPickerOptions
{
    Title = "Capture Video"
});

if (videoResult is null)
{
    return;
}

videoResult est un FileResult, et son flux peut être lu par un MediaElement.

<toolkit:MediaElement x:Name="MyMediaElement" />

La copie vers un nouveau flux vous permet de réinitialiser la position sur 0 afin de pouvoir MediaElement la lire correctement. Conservez ce flux actif pendant la durée de lecture et supprimez-le lorsqu’il n’est plus nécessaire.

await using var stream = await videoResult.OpenReadAsync();
var memoryStream = new MemoryStream();
await stream.CopyToAsync(memoryStream);
memoryStream.Position = 0;

MyMediaElement.Source = MediaSource.FromStream(memoryStream);

Cela peut être particulièrement utile pour les scénarios avec des exigences de sécurité qui n’autorisent pas l’enregistrement de données en dehors de l’environnement bac à sable de l’application.

Comprendre les types de sources de médias

Un MediaElement peut lire des médias en définissant sa propriété Source sur un fichier multimédia distant ou local. La Source propriété est de type MediaSourceet cette classe définit quatre méthodes statiques :

• FromFile, renvoie une instance FileMediaSource à partir d’un argument string.
• FromUri, renvoie une instance UriMediaSource à partir d’un argument Uri.
• FromResource, renvoie une instance ResourceMediaSource à partir d’un argument string.
• FromStream, renvoie une instance StreamMediaSource à partir d’un argument Stream.

En outre, la classe MediaSource possède également des opérateurs implicites qui renvoient des instances MediaSource à partir d’arguments string et Uri.

La classe MediaSource possède également ces classes dérivées :

• FileMediaSource, qui est utilisé pour spécifier un fichier multimédia local à partir d’un fichier string. Cette classe possède une propriété Path qui peut être définie comme string. En outre, cette classe dispose d’opérateurs implicites pour convertir un objet string en objet FileMediaSource et un objet FileMediaSource en objet string.
• UriMediaSource, qui permet de spécifier un fichier multimédia distant à partir d’un URI. Cette classe possède une propriété Uri qui peut être définie comme Uri.
• ResourceMediaSource, qui permet de spécifier un fichier intégré fourni par les fichiers de ressources de l’application. Cette classe possède une propriété Path qui peut être définie comme string.
• StreamMediaSource, qui est utilisé pour spécifier un flux lu de manière incrémentielle à partir de la mémoire, d’un fichier ou d’une source distante.

Modifier le rapport d’aspect de la vidéo

La propriété Aspect détermine la manière dont le média vidéo sera mis à l’échelle pour s’adapter à la zone d’affichage. Par défaut, cette propriété est définie sur le membre de l’énumération AspectFit, mais elle peut être définie sur n’importe lequel des membres de l’énumération Aspect :

• AspectFit indique que la vidéo sera au format letterbox, si nécessaire, pour s’adapter à la zone d’affichage, tout en préservant le rapport hauteur/largeur.
• AspectFill indique que la vidéo sera coupée de manière à remplir la zone d’affichage, tout en préservant le rapport hauteur/largeur.
• Fill indique que la vidéo sera étirée pour remplir la zone d’affichage.

Déterminer l’état de MediaElement

La classe MediaElement définit une propriété bindable en lecture seule appelée CurrentState, de type MediaElementState. Cette propriété indique l’état actuel du contrôle, par exemple si le média est en cours de lecture ou en pause, ou s’il n’est pas encore prêt à lire le média.

L'énumération MediaElementState définit les membres suivants :

• None indique que le MediaElement ne contient pas de support.
• Opening indique que le MediaElement est en train de valider et de tenter de charger la source spécifiée.
• Buffering indique que le MediaElement est en train de charger le support pour la lecture. Sa propriété Position ne progresse pas pendant cet état. Si le MediaElement était en train de lire une vidéo, il continue d’afficher la dernière trame affichée.
• Playing indique que le MediaElement est en train de lire la source multimédia.
• Paused indique que le MediaElement ne fait pas progresser sa propriété Position. Si le MediaElement était en train de lire une vidéo, il continue d’afficher la trame en cours.
• Stopped indique que le MediaElement contient un média mais qu’il n’est ni lu ni mis en pause. Sa propriété Position est réinitialisée à 0 et n’avance pas.
• Failed indique que le MediaElement n’a pas réussi à charger ou à lire le média. Cela peut se produire lors de la tentative de chargement d’un nouvel élément multimédia, lors de la tentative de lecture de l’élément multimédia ou lorsque la lecture du média est interrompue en raison d’une défaillance. Utilisez l’événement MediaFailed pour obtenir des informations supplémentaires.

Il n’est généralement pas nécessaire d’examiner la propriété CurrentState lors de l’utilisation des contrôles de transport MediaElement. Cependant, cette propriété devient importante lorsque vous mettez en œuvre vos propres contrôles de transport.

Mise en œuvre de contrôles de transport personnalisés

Les contrôles de transport d’un lecteur multimédia comprennent les boutons qui exécutent les fonctions Lecture, Pause et Stop. Ces boutons sont habituellement identifiés par des icônes familières plutôt que du texte, et les fonctions Lecture et Pause sont généralement combinées en un seul bouton.

Par défaut, les commandes de transport MediaElement sont désactivées. Cela vous permet de contrôler le MediaElement de manière programmatique ou en fournissant vos propres commandes de transport. Pour ce faire, MediaElement comprend les méthodes Play, Pause et Stop.

L’exemple XAML suivant montre une page qui contient un MediaElement et des contrôles de transport personnalisés :

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"
             x:Class="MediaElementDemos.CustomTransportPage"
             Title="Custom transport">
    <Grid>
        ...
        <toolkit:MediaElement x:Name="mediaElement"
                      ShouldAutoPlay="False"
                      ... />
        <HorizontalStackLayout BindingContext="{x:Reference mediaElement}"
                     ...>
            <Button Text="Play"
                    HorizontalOptions="Center"
                    Clicked="OnPlayPauseButtonClicked">
                <Button.Triggers>
                    <DataTrigger TargetType="Button"
                                 Binding="{Binding CurrentState}"
                                 Value="{x:Static toolkit:MediaElementState.Playing}">
                        <Setter Property="Text"
                                Value="Pause" />
                    </DataTrigger>
                    <DataTrigger TargetType="Button"
                                 Binding="{Binding CurrentState}"
                                 Value="{x:Static toolkit:MediaElementState.Buffering}">
                        <Setter Property="IsEnabled"
                                Value="False" />
                    </DataTrigger>
                </Button.Triggers>
            </Button>
            <Button Text="Stop"
                    HorizontalOptions="Center"
                    Clicked="OnStopButtonClicked">
                <Button.Triggers>
                    <DataTrigger TargetType="Button"
                                 Binding="{Binding CurrentState}"
                                 Value="{x:Static toolkit:MediaElementState.Stopped}">
                        <Setter Property="IsEnabled"
                                Value="False" />
                    </DataTrigger>
                </Button.Triggers>
            </Button>
        </HorizontalStackLayout>
    </Grid>
</ContentPage>

Dans cet exemple, les contrôles de transport personnalisés sont définis comme des objets Button. Cependant, il n’y a que deux objets Button, le premier Button représentant la Lecture et la Pause, et le second Button représentant la Arrêt. Les objets DataTrigger sont utilisés pour activer et désactiver les boutons, et pour faire basculer le premier bouton entre Lecture et Pause. Pour plus d’informations sur les déclencheurs de données, voir Déclencheurs .NET MAUI.

Le fichier code-behind contient les gestionnaires des événements Clicked :

void OnPlayPauseButtonClicked(object sender, EventArgs args)
{
    if (mediaElement.CurrentState == MediaElementState.Stopped ||
        mediaElement.CurrentState == MediaElementState.Paused)
    {
        mediaElement.Play();
    }
    else if (mediaElement.CurrentState == MediaElementState.Playing)
    {
        mediaElement.Pause();
    }
}

void OnStopButtonClicked(object sender, EventArgs args)
{
    mediaElement.Stop();
}

Il est possible d’appuyer sur le bouton Lecture, une fois qu’il est activé, pour commencer la lecture. Une pression sur le bouton Pause met la lecture en pause. L’appui sur le bouton Stop arrête la lecture et ramène la position du fichier multimédia au début.

Mettre en œuvre un contrôle de volume personnalisé

Les contrôles de lecture multimédia mis en œuvre par chaque plateforme comprennent une barre de volume. Cette barre ressemble à un curseur et indique le volume du média. En outre, vous pouvez manipuler la barre de volume pour augmenter ou diminuer le volume.

Une barre de volume personnalisée peut être mise en œuvre à l’aide d’un Slider, comme le montre l’exemple suivant :

<VerticalStackLayout>
    <toolkit:MediaElement ShouldAutoPlay="False"
                          Source="{StaticResource AdvancedAsync}" />
    <Slider Maximum="1.0"
            Minimum="0.0"
            Value="{Binding Volume}"
            Rotation="270"
            WidthRequest="100" />
</VerticalStackLayout>

Dans cet exemple, les données Slider lient leur propriété Value à la propriété Volume du MediaElement. Cela est possible parce que la propriété Volume utilise une liaison TwoWay. Par conséquent, la modification de la propriété Value entraînera la modification de la propriété Volume.

Pour plus d’informations sur l’utilisation d’un Slider, voir Slider .NET MAUI

Propriétés

Événements

Méthodes

Exemples

Vous trouverez des exemples de ce contrôle en action dans l'Exemple d'application du kit d'outils de la communauté .NET MAUI.

API

Vous pouvez trouver le code source deMediaElement sur le référentiel du kit de ressources de la communauté .NET MAUI sur GitHub.

Liens connexes

• Déclencheurs MAUI .NET
• Slider .NET MAUI
• Android ExoPlayer : Formats de médias pris en charge
• iOS : Formats de médias pris en charge
• Windows : Codecs pris en charge
• Liaisons ExoPlayer Android