Dela via


MediaElement

MediaElement är en kontroll för att spela upp video och ljud. Media som stöds av den underliggande plattformen kan spelas upp från följande källor:

  • Webben, med hjälp av en URI (HTTP eller HTTPS).
  • En resurs som är inbäddad i plattformsprogrammet med hjälp av embed:// URI-schema.
  • Filer som kommer från appens lokala filsystem med hjälp av filesystem:// URI-schema.

MediaElement kan använda plattformsuppspelningskontrollerna, som kallas transportkontroller. De är dock inaktiverade som standard och kan ersättas med dina egna transportkontroller. Följande skärmbilder visar MediaElement spela upp en video med plattformstransportkontrollerna:

Skärmbild av ett MediaElement som spelar upp en video på Android och iOS.

Not

MediaElement finns på iOS, Android, Windows, macOS och Tizen.

MediaElement använder följande plattformsimplementationer.

Plattform Implementering av plattformsmediespelare
Android ExoPlayer, stort tack till Android-biblioteken ansvariga!
iOS/macOS AVPlayer
Windows MediaPlayer

Komma igång

Om du vill använda funktionen MediaElement i .NET MAUI Community Toolkit krävs följande steg.

Installera NuGet-paketet

Innan du kan använda MediaElement i ditt program måste du installera CommunityToolkit.Maui.MediaElement NuGet-paketet och lägga till en initieringsrad i din MauiProgram.cs. På följande sätt:

Paketnamn:CommunityToolkit.Maui.MediaElement

url för -paket:https://www.nuget.org/packages/CommunityToolkit.Maui.MediaElement

Initiera paketet

Först måste using-satsen läggas till överst i din MauiProgram.cs-fil

using CommunityToolkit.Maui.MediaElement;

För att kunna använda MediaElement korrekt måste UseMauiCommunityToolkitMediaElement-metoden anropas på MauiAppBuilder-klassen vid start av ett program MauiProgram.cs filen. I följande exempel visas hur du utför detta.

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

Mer information om hur du gör detta finns på sidan Komma igång.

Plattformsspecifik initiering

För att få åtkomst till MediaElement funktioner krävs följande plattformsspecifika installation.

När du använder MediaElement är det viktigt att utföra följande steg:

1. Lägg till ResizableActivity och Launchmode till aktivitet

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

2. Lägg till följande i AndroidManifest.xml inuti taggen <application>.

 <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. Uppdatera den lägsta android-API-versionen

I projektets .csproj-fil uppdaterar du den lägsta android-API-versionen till 26.

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

4. Lägg till följande behörigheter i 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" />

Här är ett exempel på obligatoriska inställningar i 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"/>

Not

Den här ändringen av Android-manifestet aktiverar metadatavisning när en video spelas upp. Det ger stöd för meddelanden och är viktigt för att meddelanden ska fungera i alla relevanta API:er. Ändringen introducerar en tjänst och ger nödvändiga behörigheter.

Ett fullständigt exempel på den här metoden som ingår i ett program finns i .NET MAUI Community Toolkit Sample Application

Format som stöds

Multimedieformat som stöds kan vara olika per plattform. I vissa fall kan det till och med vara beroende av vilka avkodare som är tillgängliga eller installerade på operativsystemet som används när du kör appen. Mer detaljerad information om vilka format som stöds på varje plattform finns i länkarna nedan.

Plattform Länk Anteckningar
Android ExoPlayer-format som stöds
iOS/macOS format som stöds av iOS/macOS Det finns ingen officiell dokumentation om detta
Windows Windows-format som stöds I Windows är de format som stöds mycket beroende av vilka codecs som är installerade på användarens dator
Tizen Tizen-format som stöds

Viktig

Om användaren använder en Windows N-utgåva stöds ingen videouppspelning som standard. Windows N-utgåvor har inga videouppspelningsformat installerade avsiktligt.

Vanliga scenarier

Följande avsnitt beskriver vanliga användningsscenarier för MediaElement.

Spela upp fjärrmedia

En MediaElement kan spela upp fjärranslutna mediefiler med hjälp av HTTP- och HTTPS-URI-scheman. Detta uppnås genom att ange egenskapen Source till mediefilens URI:

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

Viktig

När du spelar upp fjärrkällor från HTTP-slutpunkter måste du förmodligen inaktivera operativsystemets säkerhetsåtgärder som förhindrar åtkomst till osäkra webbslutpunkter. Detta gäller för minst iOS och Android.

Media som definieras av egenskapen Source börjar som standard inte spelas upp direkt när mediet har öppnats. Om du vill aktivera automatisk medieuppspelning anger du egenskapen ShouldAutoPlay till true.

Plattformsbaserade medieuppspelningskontroller är aktiverade som standard och kan inaktiveras genom att ange egenskapen ShouldShowPlaybackControls till false.

Använda metadata

En MediaElement kan använda metadata för MediaElement.MetadataTitle, MediaElement.MetadataArtist och MediaElement.MetadataArtworkUrl. Du kan ange rubriken eller artisten så att den visar vad som för närvarande spelas upp på låsskärmskontroller för Windows, Mac Catalyst, iOS och Android. Du kan ange en lokal url eller fjärr-URL med konstverk för låsskärmen. Det bör vara minst 1080P för bästa kvalitet som ska visas. Det måste vara en URL och vara antingen .jpg eller .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";

Viktig

Du kan ange metadata i XAML eller bakom koden. Om du ställer in det i den bakomliggande koden måste du ange källan i den bakomliggande koden. Källan ska anges sist. Om du anger metadata i XAML eller konstruktor kan den här anteckningen ignoreras på ett säkert sätt.

Spela upp lokala mediafiler

Lokala medier kan spelas upp från följande källor:

  • En resurs som är inbäddad i plattformsprogrammet med hjälp av embed:// URI-schema.
  • Filer som kommer från appens lokala filsystem med hjälp av filesystem:// URI-schema.

Notera

Förkortningarna embed:// och filesystem:// fungerar bara från XAML. Använd MediaSource.FromResource() respektive MediaSource.FromFile() i kod. Med dessa metoder kan du utelämna prefixen embed:// och filesystem://. Resten av sökvägen bör vara densamma.

Spela upp mediet inbäddat i apppaketet

En MediaElement kan spela upp mediefiler som är inbäddade i apppaketet med hjälp av embed:// URI-schema. Mediefiler bäddas in i apppaketet genom att de placeras i plattformsprojektet.

Om du vill aktivera en mediefil för uppspelning från de lokala resurserna lägger du till filen i mappen Resources/Raw för ditt .NET MAUI-projekt. När en fil läggs till i roten blir URI:n embed://MyFile.mp4.

Du kan också placera filer i undermappar. Om MyFile.mp4 skulle finnas i Resources/Raw/MyVideos skulle URI:n för att använda den med MediaElement vara embed://MyVideos/MyFile.mp4.

Nedan visas ett exempel på hur du använder den här syntaxen i XAML.

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

Förstå MediaSource-typer

En MediaElement kan spela upp media genom att ange egenskapen Source till en fjärr- eller lokal mediefil. Egenskapen Source är av typen MediaSourceoch den här klassen definierar tre statiska metoder:

  • FromFilereturnerar en FileMediaSource instans från ett string argument.
  • FromUrireturnerar en UriMediaSource instans från ett Uri argument.
  • FromResourcereturnerar en ResourceMediaSource instans från ett string argument.

Dessutom har klassen MediaSource implicita operatorer som returnerar MediaSource instanser från string och Uri argument.

Anmärkning

När egenskapen Source anges i XAML anropas en typkonverterare för att returnera en MediaSource instans från en string eller Uri.

Klassen MediaSource har också följande härledda klasser:

  • FileMediaSource, som används för att ange en lokal mediefil från en string. Den här klassen har en Path egenskap som kan anges till en string. Dessutom har den här klassen implicita operatorer för att konvertera en string till ett FileMediaSource-objekt och ett FileMediaSource-objekt till en string.
  • UriMediaSource, som används för att ange en fjärrmediefil från en URI. Den här klassen har en Uri egenskap som kan anges till en Uri.
  • ResourceMediaSource, som används för att ange en inbäddad fil som tillhandahålls via appens resursfiler. Den här klassen har en Path egenskap som kan anges till en string.

Notera

När ett FileMediaSource objekt skapas i XAML anropas en typkonverterare för att returnera en FileMediaSource-instans från en string.

Ändra bildproportionsgrad

Egenskapen Aspect avgör hur videomedia ska skalas för att passa visningsområdet. Som standard är den här egenskapen inställd på AspectFit uppräkningsmedlem, men den kan anges till någon av Aspect uppräkningsmedlemmar:

  • AspectFit anger att videon kommer att infogas med letterbox, om det behövs, för att passa in i visnings-området, samtidigt som bildförhållandet bevaras.
  • AspectFill anger att videon kommer att klippas så att den fyller visningsområdet, samtidigt som bildförhållandet bevaras.
  • Fill anger att videon kommer att sträckas ut för att fylla visningsområdet.

Fastställa status för MediaElement

Klassen MediaElement definierar en skrivskyddad bindbar egenskap med namnet CurrentState, av typen MediaElementState. Den här egenskapen anger kontrollens aktuella status, till exempel om mediet spelas upp eller pausas eller om det ännu inte är redo att spela upp media.

Uppräkningen MediaElementState definierar följande medlemmar:

  • None anger att MediaElement inte innehåller något media.
  • Opening anger att MediaElement verifierar och försöker läsa in den angivna källan.
  • Buffering anger att MediaElement läser in mediet för uppspelning. Dess Position egenskap avancerar inte under det här tillståndet. Om MediaElement spelar upp video fortsätter den att visa den senast visade bildrutan.
  • Playing anger att MediaElement spelar upp mediekällan.
  • Paused anger att MediaElement inte framskrider med sitt Position-attribut. Om MediaElement spelade upp video fortsätter den att visa den aktuella bildrutan.
  • Stopped anger att MediaElement innehåller media men att det varken spelas upp eller pausas. Egenskapen Position återställs till 0 och går inte vidare.
  • Failed anger att MediaElement inte kunde läsa in eller spela upp mediet. Detta kan inträffa när du försöker läsa in ett nytt medieobjekt, när du försöker spela upp medieobjektet eller när medieuppspelningen avbryts på grund av ett fel. Använd händelsen MediaFailed för att hämta ytterligare information.

Det är vanligtvis inte nödvändigt att undersöka egenskapen CurrentState när du använder MediaElement transportkontroller. Den här egenskapen blir dock viktig när du implementerar dina egna transportkontroller.

Implementera anpassade transportkontroller

Transportkontrollerna för en mediaspelare innehåller knapparna som utför funktionerna Play, Pauseoch Stop. Dessa knappar identifieras vanligtvis med välbekanta ikoner snarare än text, och funktionerna Play och Pausa kombineras vanligtvis till en knapp.

Som standard är MediaElement uppspelningskontroller inaktiverade. På så sätt kan du styra MediaElement programmatiskt eller genom att ange egna transportkontroller. Till stöd för detta inkluderar MediaElement metoderna Play, Pauseoch Stop.

I följande XAML-exempel visas en sida som innehåller en MediaElement och anpassade transportkontroller:

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

I det här exemplet definieras de anpassade transportkontrollerna som Button objekt. Det finns dock bara två Button objekt, där den första Button representerar Play och Pauseoch den andra Button som representerar Stop. DataTrigger objekt används för att aktivera och inaktivera knapparna och för att växla den första knappen mellan Spela upp och Pausa. Mer information om datautlösare finns i .NET MAUI-utlösare.

Bakomliggande kodfil har hanterare för Clicked händelser:

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

Knappen Spela upp kan tryckas ned, när den har aktiverats, för att starta uppspelningen. Om du trycker på knappen Pausa pausas uppspelningen. Om du trycker på knappen Stoppa stoppas uppspelningen och mediefilens position returneras till början.

Implementera en anpassad volymkontroll

Medieuppspelningskontroller som implementeras av varje plattform innehåller ett volymfält. Det här fältet liknar ett skjutreglage och visar medievolymen. Dessutom kan du ändra volymfältet för att öka eller minska volymen.

Ett anpassat volymfält kan implementeras med hjälp av en Slider, som du ser i följande exempel:

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

I det här exemplet binder Slider-data sin egenskap Value till egenskapen Volume för MediaElement. Detta är möjligt eftersom egenskapen Volume använder en TwoWay bindning. Om du ändrar egenskapen Value ändras därför egenskapen Volume.

Notera

Egenskapen Volume har ett valideringsåteranrop som säkerställer att dess värde är större än eller lika med 0,0 och mindre än eller lika med 1.0.

Mer information om hur du använder en Slider finns i .NET MAUI Slider

Rensa MediaElement resurser

För att förhindra minnesläckor måste du frigöra resurserna för MediaElement. Detta kan göras genom att koppla från hanteraren. Var du behöver göra detta beror på var och hur du använder MediaElement i din app, men vanligtvis om du har en MediaElement på en enda sida och inte spelar upp media i bakgrunden, vill du frigöra resurserna när användaren navigerar bort från sidan.

Nedan hittar du ett kodfragment med exempelkod som visar hur du gör detta. Först, se till att koppla in händelsen Unloaded på din sida.

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

I koden bakom anropar du sedan metoden för att koppla från hanteraren.

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

Mer information om hanterare finns i .NET MAUI-dokumentationen om -hanterare.

Egenskaper

Egenskap Typ Beskrivning Standardvärde
Aspekt Aspekt Avgör skalningsläget för de (visuella) media som för närvarande läses in. Det här är en bindbar egenskap. Aspect.AspectFit
Nuvarande tillstånd MediaElementState Visar aktuell status för kontrollen. Det här är en skrivskyddad, bindbar egenskap. MediaElementState.None
Varaktighet TimeSpan Anger varaktigheten för den mediafil som är öppnad nu. Det här är en skrivskyddad, bindbar egenskap. TimeSpan.Zero
Position TimeSpan Beskriver det aktuella förloppet genom mediets uppspelningstid. Det här är en skrivskyddad, bindbar egenskap. Om du vill ange Position använder du metoden SeekTo(). TimeSpan.Zero
ShouldAutoPlay bool Anger om medieuppspelningen startar automatiskt när egenskapen Source har angetts. Det här är en bindbar egenskap. false
ShouldLoopPlayback bool Beskriver om den aktuella inlästa mediekällan ska återuppta uppspelningen från början när den har nått sitt slut. Det här är en bindbar egenskap. false
SkaHållaSkärmenPå bool Avgör om enhetens skärm ska vara på under medieuppspelning. Det här är en bindbar egenskap. false
ShouldMute bool Avgör om ljudet för närvarande är avstängt. Det här är en bindbar egenskap. false
SkaVisaUppspelningskontroller bool Avgör om uppspelningskontrollerna för plattformar visas. Det här är en bindbar egenskap. Observera att kontrollerna i iOS och Windows endast visas under en kort period efter att de har interagerat med skärmen. Det går inte att hålla kontrollerna synliga hela tiden. true
Källa MediaSource? Källan för mediet som lästs in i kontrollen. null
Hastighet double Avgör uppspelningshastigheten för mediet. Det här är en bindbar egenskap 1
MediaHeight int Höjden på det inlästa mediet i bildpunkter. Det här är en skrivskyddad, bindbar egenskap. Rapporteras inte för icke-visuella medier och kanske inte alltid fylls i i iOS/macOS för liveuppspelat innehåll. 0
MediaWidth int Bredden på det inlästa mediet i bildpunkter. Det här är en skrivskyddad, bindbar egenskap. Rapporteras inte för icke-visuella medier och kanske inte alltid fylls i i iOS/macOS för liveuppspelat innehåll. 0
Volym double Avgör medievolymen, som representeras på en linjär skala mellan 0 och 1. Det här är en bindbar egenskap. 1

Evenemang

Händelse Beskrivning
MediaOpened Inträffar när medieströmmen har verifierats och öppnats.
Media avslutat Inträffar när MediaElement har spelat upp media.
MediaFailed Inträffar när det finns ett fel som är associerat med mediekällan.
PositionÄndrad Inträffar när Position-egenskapsvärdet har ändrats.
Sökning slutförd Inträffar när sökpunkten för en begärd sökåtgärd är redo för uppspelning.

Metoder

Händelse Beskrivning
Leka Börjar spela upp det inlästa mediet.
Paus Pausar uppspelningen av det aktuella mediet.
Stopp Stoppar uppspelningen och återställer positionen för det aktuella mediet.
SeekTo Tar ett TimeSpan-värde för att ställa in egenskapen Position till ett visst värde och använder en CancellationToken för att avbryta Task.

Exempel

Du hittar exempel på den här kontrollen i praktiken i .NET MAUI Community Toolkit Sample Application.

API

Du hittar källkoden för MediaElement på github-lagringsplatsen .NET MAUI Community Toolkit.