MediaElement

Article
03/14/2024

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 :

Capture d’écran d’une lecture de vidéo par MediaElement sur Android et iOS.

Remarque

MediaElement est disponible sur iOS, Android, Windows, macOS et Tizen.

MediaElement utilise les implémentations de plateforme suivantes.

Plateforme	Implémentation du lecteur multimédia de la plateforme
Android	ExoPlayer, un grand merci aux chargés de maintenance ExoPlayerXamarin !
iOS/macOS	AVPlayer
Windows	MediaPlayer

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.

Pour initialiser MediaElement sur Android, le LaunchMode des applications Activity doit être défini sur LaunchMode.SingleTask et vous devez ajouter ResizableActivity=true comme dans l’exemple suivant

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

Pour obtenir un exemple complet de cette méthode incluse dans une application, reportez-vous à l’Exemple d’application du kit d’outils de la communauté .NET MAUI.

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.

Plateforme	Lien	Notes
Android	Formats pris en charge par ExoPlayer
iOS/macOS	Formats pris en charge par iOS/macOS	Aucune documentation officielle sur ce sujet n’existe.
Windows	Formats pris en charge par Windows	Sur Windows, les formats pris en charge dépendent beaucoup des codecs installés sur l’ordinateur de l’utilisateur
Tizen	Formats pris en charge par Tizen

Important

Si l’utilisateur utilise une édition Windows N, aucune lecture vidéo n’est prise en charge par défaut. Par conception, les éditions Windows N n’ont aucun format de lecture vidéo installé.

Scénarios courants

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

Contournement du commutateur Silencieux iOS

Sur iOS, l’audio de lecture de MediaElement est désactivé par défaut lorsque l’utilisateur a positionné le commutateur Silencieux de l’appareil sur silence.

Pour contourner le commutateur Silencieux de l’appareil sur iOS, ajoutez les lignes de code suivantes au fichier MauiProgram.cs. Cela garantit que l’utilisateur pourra toujours entendre l’audio de lecture de MediaElement, que le commutateur Silencieux de son appareil soit activé ou non.

public static class MauiProgram
{
    // ... Additonal Code Not Shown ... //

    public static MauiApp CreateMauiApp()
    {
        // ... Additonal Code Not Shown ... //
#if IOS
        AVFoundation.AVAudioSession.SharedInstance().SetActive(true);
        AVFoundation.AVAudioSession.SharedInstance().SetCategory(AVFoundation.AVAudioSessionCategory.Playback);
#endif
        // ... Additonal Code Not Shown ... //
    }
}

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

Important

Lors de la lecture de sources distantes à partir de points de terminaison HTTP, vous devrez probablement désactiver les mesures de sécurité du système d’exploitation qui empêchent l’accès aux points de terminaison web non sécurisés. Cela s’applique au moins à iOS et Android.

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.

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://.

Remarque

Les raccourcis embed:// et filesystem:// fonctionnent uniquement à partir de XAML. Dans le code, utilisez MediaSource.FromResource() et MediaSource.FromFile() respectivement. Avec ces méthodes, vous pouvez omettre les préfixes embed:// et filesystem://. Le reste du chemin doit être le même.

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.

Remarque

Lorsque la propriété Source est définie au format XAML, un convertisseur de type est appelé pour retourner une instance MediaSource à partir de string ou 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.

Remarque

Lorsqu’un objet FileMediaSource est créé au format XAML, un convertisseur de type est appelé pour retourner une instance FileMediaSource à partir de 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.

Remarque

La propriété Volume a un rappel de validation qui garantit que sa valeur est supérieure ou égale à 0,0, et inférieure ou égale à 1,0.

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

Propriété	Type	Description	Valeur par défaut
Aspect	Aspect	Détermine le mode de mise à l’échelle du média (visuel) actuellement chargé. Il s’agit d’une propriété pouvant être liée.	`Aspect.AspectFit`
CurrentState	`MediaElementState`	Indique l’état actuel du contrôle. Il s’agit d’une propriété en lecture seule et pouvant être liée.	`MediaElementState.None`
Durée	`TimeSpan`	Indique la durée du média actuellement ouvert. Il s’agit d’une propriété en lecture seule et pouvant être liée.	`TimeSpan.Zero`
Position	`TimeSpan`	Décrit la progression actuelle par le biais du temps de lecture du média. Il s’agit d’une propriété en lecture seule et pouvant être liée. Si vous souhaitez définir `Position`, utilisez la méthode `SeekTo()`.	`TimeSpan.Zero`
ShouldAutoPlay	`bool`	Indique si la lecture du média commence automatiquement lorsque la propriété `Source` est définie. Il s’agit d’une propriété pouvant être liée.	`false`
ShouldLoopPlayback	`bool`	Décrit si la source multimédia actuellement chargée doit reprendre la lecture du début une fois terminée. Il s’agit d’une propriété pouvant être liée.	`false`
ShouldKeepScreenOn	`bool`	Détermine si l’écran de l’appareil doit rester activé pendant la lecture du média. Il s’agit d’une propriété pouvant être liée.	`false`
ShouldMute	`bool`	Détermine si l’audio est actuellement désactivé. Il s’agit d’une propriété pouvant être liée.	`false`
ShouldShowPlaybackControls	`bool`	Détermine si les contrôles de lecture de la plateforme sont affichés. Il s’agit d’une propriété pouvant être liée. Notez que sur iOS et Windows, les contrôles sont affichés pendant une courte durée suivant l’interaction avec l’écran. Il est impossible de garder les contrôles visibles en tout temps.	`true`
Source	`MediaSource?`	Source du média chargée dans le contrôle.	`null`
Vitesse	`double`	Détermine la vitesse de lecture du média. Il s’agit d’une propriété pouvant être liée.	`1`
MediaHeight	`int`	Hauteur du média chargé en pixels. Il s’agit d’une propriété en lecture seule et pouvant être liée.	`0`
MediaWidth	`int`	Largeur du média chargé en pixels. Il s’agit d’une propriété en lecture seule et pouvant être liée.	`0`
Volume	`double`	Détermine le volume du média, qui est représenté sur une échelle linéaire comprise entre 0 et 1. Il s’agit d’une propriété pouvant être liée.	`1`

Événements

Événement	Description
MediaOpened	Se produit lorsque le flux multimédia a été validé et ouvert.
MediaEnded	Se produit lorsque `MediaElement` termine la lecture du média.
MediaFailed	Se produit lorsqu’une erreur associée à la source multimédia survient.
PositionChanged	Se produit quand la valeur de propriété `Position` a été modifiée.
SeekCompleted	Se produit lorsque le point de recherche d’une opération de recherche demandée est prêt pour la lecture.

Méthodes

Event	Description
Lire	Commence à lire le média chargé.
Pause	Suspend la lecture du média actuel.
Stop	Arrête la lecture et réinitialise la position du média actuel.
SeekTo	Prend une valeur `TimeSpan` pour définir la propriété `Position` et une valeur `CancellationToken` pour annuler `Task`.

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.

MediaElement

Mise en route

Installer le package NuGet

Initialisation du package

Initialisation spécifique à la plateforme

Formats pris en charge

Scénarios courants

Contournement du commutateur Silencieux iOS

Lire le média distant

Lire les médias locaux

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

Comprendre les types MediaSource

Modifier les proportions vidéo

Déterminer l’état `MediaElement`

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

Implémenter un contrôle de volume personnalisé

Nettoyer les ressources `MediaElement`

Propriétés

Événements

Méthodes

Exemples

API

Commentaires

Ressources supplémentaires

MediaElement

Mise en route

Installer le package NuGet

Initialisation du package

Initialisation spécifique à la plateforme

Formats pris en charge

Scénarios courants

Contournement du commutateur Silencieux iOS

Lire le média distant

Lire les médias locaux

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

Comprendre les types MediaSource

Modifier les proportions vidéo

Déterminer l’état MediaElement

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

Implémenter un contrôle de volume personnalisé

Nettoyer les ressources MediaElement

Propriétés

Événements

Méthodes

Exemples

API

Liens connexes

Commentaires

Ressources supplémentaires

Déterminer l’état `MediaElement`

Nettoyer les ressources `MediaElement`