Condividi tramite


MediaElement

MediaElement è un controllo per la riproduzione di video e audio. I supporti supportati dalla piattaforma sottostante possono essere riprodotti dalle origini seguenti:

  • Il Web, usando un URI (HTTP o HTTPS).
  • Una risorsa incorporata nell'applicazione della piattaforma, usando lo embed:// schema URI.
  • File provenienti dal file system locale dell'app, usando lo filesystem:// schema URI.

MediaElement può usare i controlli di riproduzione della piattaforma, detti controlli di trasporto. Tuttavia, sono disabilitati per impostazione predefinita e possono essere sostituiti con i propri controlli di trasporto. Gli screenshot seguenti mostrano MediaElement la riproduzione di un video con i controlli di trasporto della piattaforma:

Screenshot di un oggetto MediaElement che riproduce un video in Android e iOS.

Nota

MediaElement è disponibile in iOS, Android, Windows, macOS e Tizen.

MediaElement usa le implementazioni della piattaforma seguenti.

Piattaforma Implementazione del lettore multimediale della piattaforma
Android exoPlayer, grazie ai gestori librerie Android di!
iOS/macOS AVPlayer
Finestre MediaPlayer

Introduzione

Per usare la MediaElement funzionalità di .NET MAUI Community Toolkit, sono necessari i passaggi seguenti.

Installare il pacchetto NuGet

Prima di poter usare MediaElement all'interno dell'applicazione, è necessario installare il CommunityToolkit.Maui.MediaElement pacchetto NuGet e aggiungere una riga di inizializzazione nel MauiProgram.cs. Come indicato di seguito:

Nome pacchetto: CommunityToolkit.Maui.MediaElement

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

Inizializzazione del pacchetto

Prima di tutto l'istruzione using deve essere aggiunta all'inizio del file MauiProgram.cs

using CommunityToolkit.Maui.MediaElement;

Per usare correttamente il MediaElementUseMauiCommunityToolkitMediaElement metodo deve essere chiamato sulla classe durante il MauiAppBuilder bootstrap di un'applicazione il file MauiProgram.cs . Nell'esempio seguente viene illustrato come eseguire questa operazione.

var builder = MauiApp.CreateBuilder();
builder
    .UseMauiApp<App>()
    .UseMauiCommunityToolkitMediaElement()

Per altre informazioni su come eseguire questa operazione, vedere la pagina Attività iniziali .

Inizializzazione specifica della piattaforma

Per accedere alla MediaElement funzionalità, è necessaria la configurazione specifica della piattaforma seguente.

Quando si usa MediaElement è essenziale eseguire i passaggi seguenti:

1. Aggiungere ResizableActivity e Launchmode all'attività

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

2. Aggiungere quanto segue all'interno AndroidManifest.xml del <application> tag.

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

3. Aggiornare la versione minima dell'API Android

Nel file .csproj del progetto aggiornare la versione minima dell'API Android alla versione 26.

<SupportedOSPlatformVersion Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'android'">26.0</SupportedOSPlatformVersion>

4. Aggiungere le autorizzazioni seguenti per AndroidManifest.xml

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

Di seguito è riportato un esempio di impostazioni obbligatorie in AndroidManifest.xml

<service android:name="communityToolkit.maui.media.services" android:stopWithTask="true" android:exported="false" android:enabled="true" android:foregroundServiceType="mediaPlayback">
    <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"/>

Nota

Questa modifica al manifesto Android abilita la visualizzazione dei metadati durante la riproduzione di un video. Fornisce supporto per le notifiche ed è essenziale per il funzionamento delle notifiche in tutte le API pertinenti. La modifica introduce un servizio e concede le autorizzazioni necessarie.

Per un esempio completo di questo metodo incluso in un'applicazione, vedere l'applicazione di esempio .NET MAUI Community Toolkit

Formati supportati:

I formati multimediali supportati possono essere diversi per ogni piattaforma. In alcuni casi può anche dipendere da quali decodificatori sono disponibili o installati nel sistema operativo usato durante l'esecuzione dell'app. Per informazioni più dettagliate sui formati supportati in ogni piattaforma, vedere i collegamenti seguenti.

Piattaforma Collega Note
Android Formati supportati da ExoPlayer
iOS/macOS Formati supportati per iOS/macOS Nessuna documentazione ufficiale su questo esiste
Finestre Formati supportati da Windows In Windows i formati supportati dipendono molto dai codec installati nel computer dell'utente
Tizen Formati supportati da Tizen

Importante

Se l'utente usa un'edizione di Windows N, per impostazione predefinita non è supportata alcuna riproduzione video. Le edizioni di Windows N non hanno formati di riproduzione video installati dalla progettazione.

Scenari comuni

Le sezioni seguenti illustrano gli scenari di utilizzo comuni per .MediaElement

Riprodurre supporti remoti

Un MediaElement oggetto può riprodurre file multimediali remoti usando gli schemi URI HTTP e HTTPS. Questa operazione viene eseguita impostando la Source proprietà sull'URI del file multimediale:

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

Importante

Quando si giocano origini remote da endpoint HTTP, è probabile che sia necessario disabilitare le misure di sicurezza del sistema operativo che impediscono l'accesso agli endpoint Web non sicuri. Questo vale per almeno iOS e Android.

Per impostazione predefinita, il supporto definito dalla Source proprietà non inizia immediatamente la riproduzione dopo l'apertura del supporto. Per abilitare la riproduzione automatica dei contenuti multimediali, impostare la ShouldAutoPlay proprietà su true.

I controlli di riproduzione multimediale forniti dalla piattaforma sono abilitati per impostazione predefinita e possono essere disabilitati impostando la ShouldShowPlaybackControls proprietà su false.

Uso di metadati

Un MediaElement oggetto può usare i metadati per MediaElement.MetadataTitlee MediaElement.MetadataArtistMediaElement.MetadataArtworkUrl. Puoi impostare il titolo o l'artista per mostrare cosa sta attualmente riproducendo nei controlli lockscreen per Windows, Mac Catalyst, iOS e Android. È possibile impostare un URL locale o remoto con la grafica per la schermata di blocco. Deve essere almeno 1080P per la migliore qualità da visualizzare. Deve essere un URL e essere .jpg o .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";

Importante

È possibile impostare i metadati in XAML o code-behind. Se la si imposta nel code-behind, è necessario impostare l'origine nel code-behind. L'origine deve essere impostata per ultima. Se imposti i metadati in XAML o nel costruttore, questa nota può essere ignorata in modo sicuro.

Riprodurre elementi multimediali locali

I supporti locali possono essere riprodotti dalle origini seguenti:

  • Una risorsa incorporata nell'applicazione della piattaforma, usando lo embed:// schema URI.
  • File provenienti dal file system locale dell'app, usando lo filesystem:// schema URI.

Nota

La sintassi abbreviata embed:// e filesystem:// funziona solo da XAML. Nel codice usare MediaSource.FromResource() e MediaSource.FromFile() rispettivamente. Usando questi metodi, è possibile omettere i embed:// prefissi e filesystem:// . Il resto del percorso deve essere lo stesso.

Riprodurre elementi multimediali incorporati nel pacchetto dell'app

Un MediaElement oggetto può riprodurre file multimediali incorporati nel pacchetto dell'app, usando lo embed:// schema URI. I file multimediali vengono incorporati nel pacchetto dell'app inserendoli nel progetto della piattaforma.

Per abilitare un file multimediale per la riproduzione dalle risorse locali, aggiungere il file alla Resources/Raw cartella del progetto MAUI .NET. Quando un file viene aggiunto nella radice, l'URI sarà embed://MyFile.mp4.

È anche possibile inserire file nelle sottocartelle. Se MyFile.mp4 si trova in Resources/Raw/MyVideos , l'URI da usare con MediaElement sarebbe embed://MyVideos/MyFile.mp4.

Di seguito è riportato un esempio di come usare questa sintassi in XAML.

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

Informazioni sui tipi MediaSource

Un MediaElement oggetto può riprodurre elementi multimediali impostandone la Source proprietà su un file multimediale remoto o locale. La Source proprietà è di tipo MediaSourcee questa classe definisce tre metodi statici:

  • FromFile, restituisce un'istanza FileMediaSource di da un string argomento .
  • FromUri, restituisce un'istanza UriMediaSource di da un Uri argomento .
  • FromResource, restituisce un'istanza ResourceMediaSource di da un string argomento .

Inoltre, la MediaSource classe dispone anche di operatori impliciti che restituiscono MediaSource istanze da string e Uri argomenti.

Nota

Quando la Source proprietà è impostata in XAML, viene richiamato un convertitore di tipi per restituire un'istanza MediaSource da un string oggetto o Uri.

La MediaSource classe include anche queste classi derivate:

  • FileMediaSource, usato per specificare un file multimediale locale da un oggetto string. Questa classe ha una Path proprietà che può essere impostata su .string Inoltre, questa classe include operatori impliciti per convertire un oggetto string in un FileMediaSource oggetto e un FileMediaSource oggetto in un oggetto string.
  • UriMediaSource, usato per specificare un file multimediale remoto da un URI. Questa classe ha una Uri proprietà che può essere impostata su .Uri
  • ResourceMediaSource, usato per specificare un file incorporato fornito tramite i file di risorse dell'app. Questa classe ha una Path proprietà che può essere impostata su .string

Nota

Quando un FileMediaSource oggetto viene creato in XAML, viene richiamato un convertitore di tipi per restituire un'istanza FileMediaSource da un oggetto string.

Modificare le proporzioni video

La Aspect proprietà determina il modo in cui i supporti video verranno ridimensionati per adattarsi all'area di visualizzazione. Per impostazione predefinita, questa proprietà è impostata sul AspectFit membro di enumerazione, ma può essere impostata su uno dei membri dell'enumerazione Aspect :

  • AspectFit indica che il video verrà sottoposto a letterboxing, se necessario, per adattarsi all'area di visualizzazione, mantenendo al tempo stesso le proporzioni.
  • AspectFill indica che il video verrà ritagliato in modo che riempia l'area di visualizzazione, mantenendo al tempo stesso le proporzioni.
  • Fill indica che il video verrà esteso per riempire l'area di visualizzazione.

Determinare MediaElement lo stato

La MediaElement classe definisce una proprietà associabile di sola lettura denominata CurrentState, di tipo MediaElementState. Questa proprietà indica lo stato corrente del controllo, ad esempio se il supporto è in riproduzione o in pausa o se non è ancora pronto per riprodurre il supporto.

L'enumerazione MediaElementState definisce i membri seguenti:

  • None indica che l'oggetto MediaElement non contiene supporti.
  • Opening indica che sta MediaElement convalidando e tentando di caricare l'origine specificata.
  • Buffering indica che sta MediaElement caricando il supporto per la riproduzione. La proprietà Position non avanza durante questo stato. Se il MediaElement video è in riproduzione, continua a visualizzare l'ultimo fotogramma visualizzato.
  • Playing indica che sta MediaElement riproducendo l'origine multimediale.
  • Paused indica che l'oggetto MediaElement non avanza la relativa Position proprietà. Se il MediaElement video è in riproduzione, continua a visualizzare il fotogramma corrente.
  • Stopped indica che contiene MediaElement supporti, ma non viene riprodotto o sospeso. La proprietà Position viene reimpostata su 0 e non avanza.
  • Failed indica che l'oggetto MediaElement non è riuscito a caricare o riprodurre il supporto. Ciò può verificarsi durante il tentativo di caricare un nuovo elemento multimediale quando si tenta di riprodurre l'elemento multimediale o quando la riproduzione multimediale viene interrotta a causa di un errore. Usare l'evento MediaFailed per recuperare dettagli aggiuntivi.

In genere non è necessario esaminare la CurrentState proprietà quando si usano i controlli di MediaElement trasporto. Tuttavia, questa proprietà diventa importante quando si implementano controlli di trasporto personalizzati.

Implementare controlli di trasporto personalizzati

I controlli di trasporto di un lettore multimediale includono i pulsanti che eseguono le funzioni Play, Pause e Stop. Questi pulsanti sono identificati in genere con icone note anziché testo e le funzioni di riproduzione e pausa sono in genere unite in un unico pulsante.

Per impostazione predefinita, i MediaElement controlli di riproduzione sono disabilitati. Ciò consente di controllare l'oggetto a MediaElement livello di codice o fornendo controlli di trasporto personalizzati. A supporto di questo, include MediaElementi Play metodi , Pausee Stop .

L'esempio XAML seguente mostra una pagina che contiene controlli MediaElement di trasporto personalizzati e :

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

In questo esempio i controlli di trasporto personalizzati vengono definiti come Button oggetti . Esistono tuttavia solo due Button oggetti, con il primo Button che rappresenta Play e Pause e il secondo Button che rappresenta Stop. DataTrigger gli oggetti vengono usati per abilitare e disabilitare i pulsanti e per cambiare il primo pulsante tra Play e Pause. Per altre informazioni sui trigger di dati, vedere Trigger MAUI .NET.

Il file code-behind include i gestori per gli Clicked eventi:

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 pulsante Riproduci può essere premuto, una volta abilitato, per avviare la riproduzione. Premendo il pulsante Sospendi si ottiene la sospensione della riproduzione. Premendo il pulsante Arresta la riproduzione viene arrestata e viene restituita la posizione del file multimediale all'inizio.

Implementare un controllo volume personalizzato

I controlli di riproduzione multimediale implementati da ogni piattaforma includono una barra del volume. Questa barra è simile a un dispositivo di scorrimento e mostra il volume dei supporti. Inoltre, è possibile modificare la barra del volume per aumentare o diminuire il volume.

È possibile implementare una barra del volume personalizzata usando un Slideroggetto , come illustrato nell'esempio seguente:

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

In questo esempio, i dati associano la Slider relativa proprietà alla Value proprietà dell'oggetto VolumeMediaElement . Ciò è possibile perché la Volume proprietà utilizza un'associazione TwoWay . Pertanto, la modifica della Value proprietà comporterà la modifica della Volume proprietà.

Nota

La Volume proprietà dispone di un callback di convalida che garantisce che il relativo valore sia maggiore o uguale a 0,0 e minore o uguale a 1,0.

Per altre informazioni sull'uso di un dispositivo di Slider scorrimento MAUI di .NET, vedere .NET MAUI Slider

Pulire le MediaElement risorse

Per evitare perdite di memoria, è necessario liberare le risorse di MediaElement. Questa operazione può essere eseguita disconnettendo il gestore. Dove è necessario eseguire questa operazione dipende da dove e come si usa MediaElement nell'app, ma in genere se si dispone di un MediaElement oggetto in una singola pagina e non si riproduce elementi multimediali in background, si vogliono liberare le risorse quando l'utente si sposta dalla pagina.

Di seguito è riportato un frammento di codice di esempio che illustra come eseguire questa operazione. Prima di tutto, assicurarsi di associare l'evento Unloaded nella pagina.

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

Quindi nel code-behind chiamare il metodo per disconnettere il gestore.

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

Per altre informazioni sui gestori, vedere la documentazione di .NET MAUI sui gestori.

Proprietà

Proprietà Type Descrizione Valore predefinito
Aspetto Aspetto Determina la modalità di ridimensionamento per il supporto (visivo) attualmente caricato. Si tratta di una proprietà associabile. Aspect.AspectFit
CurrentState MediaElementState Indica lo stato corrente del controllo. Si tratta di una proprietà associabile di sola lettura. MediaElementState.None
Durata TimeSpan Indica la durata del supporto attualmente aperto. Si tratta di una proprietà associabile di sola lettura. TimeSpan.Zero
Posizione TimeSpan Descrive lo stato di avanzamento corrente attraverso il tempo di riproduzione del supporto. Si tratta di una proprietà associabile di sola lettura. Se si desidera impostare l'oggetto Position utilizzando il SeekTo() metodo . TimeSpan.Zero
ShouldAutoPlay bool Indica se la riproduzione multimediale inizierà automaticamente quando la Source proprietà è impostata. Si tratta di una proprietà associabile. false
ShouldLoopPlayback bool Descrive se l'origine multimediale attualmente caricata deve riprendere la riproduzione dall'inizio dopo aver raggiunto la fine. Si tratta di una proprietà associabile. false
ShouldKeepScreenOn bool Determina se la schermata del dispositivo deve rimanere attiva durante la riproduzione multimediale. Si tratta di una proprietà associabile. false
ShouldMute bool Determina se l'audio è attualmente disattivato. Si tratta di una proprietà associabile. false
ShouldShowPlaybackControls bool Determina se vengono visualizzati i controlli di riproduzione delle piattaforme. Si tratta di una proprietà associabile. Si noti che in iOS e Windows i controlli vengono visualizzati solo per un breve periodo dopo l'interazione con la schermata. Non è possibile mantenere sempre visibili i controlli. true
Origine MediaSource? Origine del supporto caricato nel controllo. null
Velocità double Determina la velocità di riproduzione del supporto. Si tratta di una proprietà associabile 1
MediaHeight int Altezza del supporto caricato in pixel. Si tratta di una proprietà associabile di sola lettura. Non segnalato per i supporti non visivi e potrebbe non essere sempre popolato in iOS/macOS per contenuti in streaming live. 0
MediaWidth int Larghezza del supporto caricato in pixel. Si tratta di una proprietà associabile di sola lettura. Non segnalato per i supporti non visivi e potrebbe non essere sempre popolato in iOS/macOS per contenuti in streaming live. 0
Volume double Determina il volume del supporto, rappresentato su una scala lineare compresa tra 0 e 1. Si tratta di una proprietà associabile. 1

Eventi

Evento Descrizione
MediaOpened Si verifica quando il flusso multimediale è stato convalidato e aperto.
MediaEnded Si verifica al termine della MediaElement riproduzione dei supporti.
MediaFailed Si verifica quando si verifica un errore associato all'origine multimediale.
PositionChanged Si verifica quando viene modificato il valore della proprietà Position.
SeekCompleted Si verifica quando il punto di ricerca di un'operazione di ricerca richiesta è pronto per la riproduzione.

Metodi

Evento Descrizione
Riproduci Avvia la riproduzione dei supporti caricati.
Sospendi Sospende la riproduzione dei supporti correnti.
Arresta Arresta la riproduzione e reimposta la posizione del supporto corrente.
SeekTo Accetta un TimeSpan valore per impostare la Position proprietà su e accetta un CancellationToken oggetto per annullare l'oggetto Task.

Esempi

È possibile trovare esempi di questo controllo in azione nell'applicazione di esempio .NET MAUI Community Toolkit.

API

È possibile trovare il codice sorgente per MediaElement over nel repository GitHub di .NET MAUI Community Toolkit.