MediaElement

MediaElement est un contrôle permettant de lire les éléments 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 incorporée à l’application de plateforme, à l’aide du schéma d’URI embed://.
• Des fichiers provenant du système de fichiers local de l’application, à l’aide du schéma d’URI filesystem://.

MediaElement peut utiliser les contrôles de lecture de la plateforme, connus sous le nom de contrôles de transport. Toutefois, 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 lisant une vidéo avec les contrôles de transport de la plateforme :

MediaElement utilise les implémentations de plateforme suivantes.

Mise en route

Pour utiliser la fonctionnalité MediaElement du kit d’outils de la communauté .NET MAUI, vous devez effectuer les étapes suivantes.

Installer le package NuGet

Avant de pouvoir utiliser MediaElement au sein de votre application, vous devez installer le package NuGet CommunityToolkit.Maui.MediaElement 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()

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, vous devez appliquer la configuration spécifique à la plateforme suivante.

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

 <service android:name="communityToolkit.maui.media.services" android:exported="false" android:enabled="true" android:foregroundServiceType="mediaPlayback">
   <intent-filter>
     <action android:name="android.intent.action.MEDIA_BUTTON" />
   </intent-filter>
   <intent-filter>
     <action android:name="androidx.media3.session.MediaSessionService"/>
   </intent-filter>
 </service>

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK" />
<uses-permission android:name="android.permission.MEDIA_CONTENT_CONTROL" />

<application android:allowBackup="true" android:icon="@mipmap/appicon" android:enableOnBackInvokedCallback="true" android:supportsRtl="true">
<service android:name="communityToolkit.maui.media.services" android:exported="false" android:enabled="true" android:foregroundServiceType="mediaPlayback">
    <intent-filter>
    <action android:name="android.intent.action.MEDIA_BUTTON" />
    </intent-filter>
    <intent-filter>
    <action android:name="androidx.media3.session.MediaSessionService"/>
    </intent-filter>
</service>
</application>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK" />
<uses-permission android:name="android.permission.MEDIA_CONTENT_CONTROL" />

<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 différer selon la plateforme. 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 plus d’informations sur les formats pris en charge sur chaque plateforme, reportez-vous aux liens ci-dessous.

Scénarios courants

Les sections suivantes couvrent les scénarios d’utilisation courants pour MediaElement.

Lire le média distant

MediaElement peut lire des fichiers multimédias distants à l’aide des schémas d’URI HTTP et HTTPS. Pour ce faire, définissez la propriété Source sur l’URI du fichier multimédia :

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

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

Par défaut, les contrôles de lecture multimédia fournis par la plateforme sont activés. Ils peuvent être désactivés en définissant la propriété ShouldShowPlaybackControls sur false.

Utilisation des métadonnées

Un MediaElement peut utiliser des métadonnées pour MediaElement.MetadataTitle, MediaElement.MetadataArtist et MediaElement.MetadataArtworkUrl. Vous pouvez définir le titre ou l’artiste afin d’afficher ce qui est en cours de lecture 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 des illustrations pour l’écran de verrouillage. La résolution doit être d’au moins 1080P pour obtenir la meilleure qualité d’affichage possible. Il doit s’agir d’une URL. Celle-ci doit correspondre à un fichier .jpg ou .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";

Lire les médias locaux

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

• Une ressource incorporée à l’application de plateforme, à l’aide du schéma d’URI embed://.
• Des fichiers provenant du système de fichiers local de l’application, à l’aide du schéma d’URI filesystem://.

Lire le média incorporé dans le package d’application

MediaElement peut lire des fichiers multimédias incorporés dans le package d’application à l’aide du schéma d’URI embed://. Pour incorporer les fichiers multimédias dans le package d’application, placez-les 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 des fichiers dans les sous-dossiers. Si MyFile.mp4 est dans Resources/Raw/MyVideos, alors l’URI pour l’utiliser avec MediaElement est embed://MyVideos/MyFile.mp4.

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

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

Comprendre les types MediaSource

MediaElement peut lire les médias en définissant sa propriété Source sur un fichier multimédia distant ou local. La propriété Source est de type MediaSource, et cette classe définit trois méthodes statiques :

• FromFile, retourne une instance FileMediaSource à partir d’un argument string.
• FromUri, retourne une instance UriMediaSource à partir d’un argument Uri.
• FromResource, retourne une instance ResourceMediaSource à partir d’un argument string.

En outre, la classe MediaSource a également des opérateurs implicites qui retournent des instances MediaSource à partir des arguments string et Uri.

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

• FileMediaSource, qui est utilisé pour spécifier un fichier multimédia local à partir de string. Cette classe a une propriété Path qui peut être définie sur string. En outre, cette classe a des opérateurs implicites pour convertir string en objet FileMediaSource et un objet FileMediaSource en string.
• UriMediaSource, qui est utilisé pour spécifier un fichier multimédia distant à partir d’un URI. Cette classe a une propriété Uri qui peut être définie sur Uri.
• ResourceMediaSource, qui est utilisé pour spécifier un fichier incorporé fourni via les fichiers de ressources de l’application. Cette classe a une propriété Path qui peut être définie sur string.

Modifier les proportions vidéo

La propriété Aspect détermine la façon 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 d’énumération AspectFit, mais elle peut être définie sur l’un des membres d’énumération Aspect :

• AspectFit indique que la vidéo sera cadrée, si nécessaire, pour s’adapter à la zone d’affichage, tout en préservant les proportions.
• AspectFill indique que la vidéo sera découpée pour remplir la zone d’affichage, tout en conservant les proportions.
• Fill indique que la vidéo sera étirée pour remplir la zone d’affichage.

Déterminer l’état MediaElement

La classe MediaElement définit une propriété pouvant être liée en lecture seule nommée CurrentState et de type MediaElementState. Cette propriété indique l’état actuel du contrôle, par exemple si le média est lu ou mis 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 MediaElement ne contient aucun média.
• Opening indique que MediaElement valide et tente de charger la source spécifiée.
• Buffering indique que MediaElement charge le média pour la lecture. Sa propriété Position n’avance pas pendant cet état. Si MediaElement lisait la vidéo, il poursuit l’affichage du dernier cadre affiché.
• Playing indique que MediaElement lit la source multimédia.
• Paused indique que MediaElement n’avance pas sa propriété Position. Si MediaElement lisait la vidéo, il poursuit l’affichage du cadre actuel.
• Stopped indique que MediaElement contient le média, mais qu’il n’est pas lu ou qu’il est mis en pause. Sa propriété Position est réinitialisée sur 0 et n’avance pas.
• Failed indique que MediaElement n’a pas pu charger ou lire le média. Cela peut se produire lorsque vous essayez de charger un nouvel élément multimédia, lorsque vous essayer de lire l’élément multimédia ou lorsque la lecture du média est interrompue en raison d’un échec. Utilisez l’événement MediaFailed pour récupérer davantage d’informations.

Il n’est généralement pas nécessaire d’examiner la propriété CurrentState lorsque vous utilisez les contrôles de transport MediaElement. Toutefois, cette propriété devient importante lorsque vous implémentez vos propres contrôles de transport.

Implémenter des contrôles de transport personnalisés

Les contrôles de transport d’un lecteur multimédia incluent les boutons qui effectuent les fonctions Lecture, Pause et Arrêt. 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 contrôles de lecture MediaElement sont désactivés. Cela vous permet de contrôler MediaElement par programmation ou en fournissant vos propres contrôles de transport. Afin de prendre cela en charge, MediaElement inclut les méthodes Play, Pause et Stop.

L’exemple XAML suivant montre une page qui contient 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 en tant qu’objets Button. Toutefois, il n’existe que deux objets Button, le premier Button représentant Lecture et Pause, et le deuxième Button représentant Arrêt. Les objets DataTrigger servent à activer et désactiver les boutons, ainsi qu’à basculer le premier bouton entre Lecture et Pause. Pour plus d’informations sur les déclencheurs de données, consultez Déclencheurs .NET MAUI.

Le fichier code-behind contient les gestionnaires pour les é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();
}

Une fois activé, il est possible d’appuyer sur le bouton Lecture pour commencer la lecture. Appuyer sur le bouton Pause suspend la lecture. Appuyer sur le bouton Arrêt interrompt la lecture et rembobine le fichier multimédia jusqu’au début.

Implémenter un contrôle de volume personnalisé

Les contrôles de lecture multimédia implémentés par chaque plateforme incluent une barre de volume. Cette barre ressemble à un curseur et affiche le volume du média. En outre, vous pouvez manipuler la barre de volume pour augmenter ou diminuer le volume.

Comme l’illustre l’exemple suivant, une barre de volume personnalisée peut être implémentée à l’aide de Slider :

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

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

Pour plus d’informations sur l’utilisation de Slider, consultez Curseur .NET MAUI.

Nettoyer les ressources MediaElement

Pour éviter les fuites de mémoire, vous devrez libérer les ressources MediaElement. Pour ce faire, déconnectez le gestionnaire. L’emplacement où vous devez le faire dépend de la manière dont vous utilisez MediaElement et à quel endroit dans votre application, mais, de façon générale, si vous avez un MediaElement sur une seule page et ne lisez pas le média en arrière-plan, il est recommandé de libérer les ressources lorsque l’utilisateur quitte la page.

Vous trouverez ci-dessous un extrait d’exemple de code qui montre comment procéder. Tout d’abord, veillez à raccorder l’événement Unloaded sur votre page.

<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.FreeResourcesPage"
             Title="Free Resources"
             Unloaded="ContentPage_Unloaded">
    
    <toolkit:MediaElement x:Name="mediaElement"
                          ShouldAutoPlay="False"
                          ... />
</ContentPage>

Ensuite, dans le code-behind, appelez la méthode pour déconnecter le gestionnaire.

public partial class FreeResourcesPage : ContentPage
{
    void ContentPage_Unloaded(object? sender, EventArgs e)
    {
        // Stop and cleanup MediaElement when we navigate away
        mediaElement.Handler?.DisconnectHandler();
    }
}

Pour en savoir plus sur les gestionnaires, consultez la documentation .NET MAUI sur les Gestionnaires.

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 .NET MAUI
• Curseur .NET MAUI
• Android ExoPlayer : formats multimédias pris en charge
• iOS : formats multimédias pris en charge
• Windows : codecs pris en charge
• Liaisons ExoPlayer Android