MediaElement

MediaElement , video ve ses oynatmak için bir denetimdir. Temel alınan platform tarafından desteklenen medya aşağıdaki kaynaklardan oynatılabilir:

• URI (HTTP veya HTTPS) kullanarak web.
• URI şemasını kullanarak platform uygulamasına eklenmiş bir embed:// kaynak.
• URI düzenini kullanarak uygulamanın yerel dosya sisteminden filesystem:// gelen dosyalar.

MediaElement , aktarım denetimleri olarak adlandırılan platform kayıttan yürütme denetimlerini kullanabilir. Ancak, bunlar varsayılan olarak devre dışı bırakılır ve kendi aktarım denetimlerinizle değiştirilebilir. Aşağıdaki ekran görüntüleri, platform taşıma denetimleriyle video yürütmeyi gösterir MediaElement :

aşağıdaki MediaElement platform uygulamalarını kullanır.

Başlarken

.NET MAUI Community Toolkit özelliğini kullanmak MediaElement için aşağıdaki adımlar gereklidir.

NuGet paketini yükleme

Uygulamanızın içinde kullanabilmeniz MediaElement için önce NuGet paketini yüklemeniz CommunityToolkit.Maui.MediaElement ve MauiProgram.cs bir başlatma satırı eklemeniz gerekir. Aşağıdaki gibi:

Paket adı: CommunityToolkit.Maui.MediaElement

Paket url'si:https://www.nuget.org/packages/CommunityToolkit.Maui.MediaElement

Paketi başlatma

İlk olarak using deyiminin MauiProgram.cs dosyanızın en üstüne eklenmesi gerekir

using CommunityToolkit.Maui.MediaElement;

Yönteminin doğru şekilde MediaElement kullanılabilmesi için, MauiProgram.cs dosyasının bir uygulamaya UseMauiCommunityToolkitMediaElement önyüklemesi sırasında sınıfında çağrılmalıdırMauiAppBuilder. Aşağıdaki örnekte bunun nasıl gerçekleştirebileceğiniz gösterilmektedir.

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

Bunun nasıl yapacağı hakkında daha fazla bilgi için lütfen Başlarken sayfasına bakın.

Platforma özgü başlatma

İşlevlere MediaElement erişmek için aşağıdaki platforma özgü kurulum gereklidir.

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

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

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

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

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

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

Desteklenen Biçimler

Desteklenen multimedya biçimleri platform başına farklı olabilir. Bazı durumlarda, uygulamanızı çalıştırırken kullanılan işletim sisteminde hangi kod çözücülerin kullanılabilir veya yüklü olduğuna bile bağlı olabilir. Her platformda hangi biçimlerin desteklendiği hakkında daha ayrıntılı bilgi için lütfen aşağıdaki bağlantılara bakın.

Genel senaryolar

Aşağıdaki bölümlerde için MediaElementyaygın kullanım senaryoları yer almaktadır.

Uzak medya yürütme

, MediaElement HTTP ve HTTPS URI düzenlerini kullanarak uzak medya dosyalarını yürütebilir. Bu, özelliği medya dosyasının Source URI'sine ayarlanarak gerçekleştirilir:

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

Varsayılan olarak, özelliği tarafından Source tanımlanan medya, medya açıldıktan sonra hemen yürütülmeye başlamaz. Otomatik medya kayıttan yürütmeyi ShouldAutoPlay etkinleştirmek için özelliğini olarak trueayarlayın.

Platform tarafından sağlanan medya kayıttan yürütme denetimleri varsayılan olarak etkinleştirilir ve özelliği ShouldShowPlaybackControlsolarak ayarlanarak false devre dışı bırakılabilir.

Meta Verileri Kullanma

, MediaElement ve MediaElement.MetadataTitleiçin MediaElement.MetadataArtistMediaElement.MetadataArtworkUrl meta verileri kullanabilir. Windows, Mac Catalyst, iOS ve Android için kilit ekranı denetimlerinde şu anda nelerin yürütülmekte olduğunu göstermek için başlığı veya sanatçıyı ayarlayabilirsiniz. Kilit ekranı için resim içeren bir yerel veya uzak URL ayarlayabilirsiniz. En iyi kalitenin görüntülenmesi için en az 1080P olmalıdır. Bir URL olmalı ve veya olmalıdır .jpg.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";

Yerel medyayı yürütme

Yerel medya aşağıdaki kaynaklardan oynatılabilir:

• URI şemasını kullanarak platform uygulamasına eklenmiş bir embed:// kaynak.
• URI düzenini kullanarak uygulamanın yerel dosya sisteminden filesystem:// gelen dosyalar.

Uygulama paketine eklenmiş medya yürütme

, MediaElement URI şemasını kullanarak embed:// uygulama paketine eklenmiş medya dosyalarını yürütebilir. Medya dosyaları, platform projesine yerleştirilerek uygulama paketine eklenir.

Yerel kaynaklardan kayıttan yürütme için bir medya dosyasını etkinleştirmek için dosyayı .NET MAUI projenizin Resources/Raw klasörüne ekleyin. Köke bir dosya eklendiğinde, URI olacaktır embed://MyFile.mp4.

Dosyaları alt klasörlere de yerleştirebilirsiniz. eğer MyFile.mp4 içindeyse Resources/Raw/MyVideos , ile MediaElement kullanılacak URI olacaktır embed://MyVideos/MyFile.mp4.

XAML'de bu söz diziminin nasıl kullanılacağına yönelik bir örnek aşağıda görülebilir.

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

MediaSource türlerini anlama

bir MediaElement , özelliğini uzak veya yerel bir medya dosyasına ayarlayarak Source medya yürütebilir. Source özelliği türündedir MediaSourceve bu sınıf üç statik yöntem tanımlar:

• FromFile, bağımsız değişkenden bir FileMediaSourcestring örnek döndürür.
• FromUri, bağımsız değişkenden bir UriMediaSourceUri örnek döndürür.
• FromResource, bağımsız değişkenden bir ResourceMediaSourcestring örnek döndürür.

Ayrıca sınıfı, MediaSource ve MediaSource bağımsız değişkenlerinden string örnekler döndüren Uri örtük işleçlere de sahiptir.

sınıfı da MediaSource şu türetilmiş sınıflara sahiptir:

• FileMediaSource, dosyasından yerel bir medya dosyası stringbelirtmek için kullanılır. Bu sınıfın olarak ayarlanabilen bir Pathstringözelliği vardır. Buna ek olarak, bu sınıfın bir string nesnesine ve nesnesine FileMediaSource dönüştürmek için FileMediaSourcestringörtük işleçleri vardır.
• UriMediaSource, bir URI'den uzak medya dosyası belirtmek için kullanılır. Bu sınıfın olarak ayarlanabilen bir UriUriözelliği vardır.
• ResourceMediaSource, uygulamanın kaynak dosyaları aracılığıyla sağlanan ekli bir dosya belirtmek için kullanılır. Bu sınıfın olarak ayarlanabilen bir Pathstringözelliği vardır.

Video en boy oranını değiştirme

özelliği, Aspect video medyasının görüntü alanına sığacak şekilde nasıl ölçeklendirileceğini belirler. Varsayılan olarak, bu özellik numaralandırma üyesine AspectFit ayarlanır, ancak numaralandırma üyelerinden Aspect herhangi birine ayarlanabilir:

• AspectFit videonun en boy oranını korurken görüntü alanına sığacak şekilde gerekirse letterbox'a alınacağını gösterir.
• AspectFill videonun en boy oranını korurken görüntü alanını dolduracak şekilde kırpılacağını gösterir.
• Fill videonun görüntü alanını dolduracak şekilde uzatılacağını gösterir.

Durumu belirleme MediaElement

MediaElement sınıfı, türünde CurrentStateadlı MediaElementStatesalt okunur bir bağlanabilir özellik tanımlar. Bu özellik, medyanın oynatılıp oynatılmadığı veya duraklatıldığı ya da medyayı yürütmeye henüz hazır olmadığı gibi denetimin geçerli durumunu gösterir.

Numaralandırma MediaElementState aşağıdaki üyeleri tanımlar:

• None , öğesinin MediaElement medya içermediğini gösterir.
• Opening öğesinin doğrulandığını MediaElement ve belirtilen kaynağı yüklemeye çalışıldığını gösterir.
• Buffering , medyayı MediaElement kayıttan yürütme için yüklendiğini gösterir. Özelliği Position bu durum sırasında ilerlemez. MediaElement Video oynatıldıysa, görüntülenen son kareyi görüntülemeye devam eder.
• Playing , öğesinin MediaElement medya kaynağını oynattığını gösterir.
• Paused öğesinin MediaElement özelliğini ilerletmediğini Position gösterir. MediaElement Video oynatıldıysa geçerli çerçeveyi görüntülemeye devam eder.
• Stopped , medya içerdiğini MediaElement ancak oynatılmadığını veya duraklatılmadığını gösterir. Özelliği Position 0'a sıfırlanır ve ilerlemez.
• Failed , medyanın MediaElement yüklenemediği veya oynatılamadığını gösterir. Bu durum, yeni bir medya öğesi yüklenmeye çalışılırken, medya öğesi oynatılmaya çalışılırken veya bir hata nedeniyle medya kayıttan yürütme kesintiye uğradığında oluşabilir. MediaFailed Ek ayrıntıları almak için olayını kullanın.

Genellikle taşıma denetimlerini kullanırken CurrentState özelliğin incelenmesi MediaElement gerekmez. Ancak, bu özellik kendi aktarım denetimlerinizi uygularken önemli hale gelir.

Özel aktarım denetimleri uygulama

Medya oynatıcının aktarım denetimleri Yürüt, Duraklat ve Durdur işlevlerini gerçekleştiren düğmeleri içerir. Bu düğmeler genellikle metin yerine tanıdık simgelerle tanımlanır ve Yürüt ve Duraklat işlevleri genellikle tek bir düğmede birleştirilir.

Varsayılan olarak, MediaElement kayıttan yürütme denetimleri devre dışı bırakılır. Bu, program aracılığıyla veya kendi taşıma denetimlerinizi sağlayarak denetlemenizi sağlar MediaElement . Bunu MediaElement desteklemek için , Playve Pause yöntemlerini içerirStop.

Aşağıdaki XAML örneği ve özel aktarım denetimleri içeren bir MediaElement sayfayı gösterir:

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

Bu örnekte, özel aktarım denetimleri nesne olarak Button tanımlanır. Ancak, ilki Yürüt ve Duraklat'ıButtonButton DataTriggernesneleri, düğmeleri etkinleştirmek ve devre dışı bırakmak ve ilk düğmeyi Yürüt ve Duraklat arasında değiştirmek için kullanılır. Veri tetikleyicileri hakkında daha fazla bilgi için bkz . .NET MAUI Tetikleyicileri.

Arka planda kod dosyasında olaylar için Clicked işleyiciler bulunur:

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

Oynat düğmesine, kayıttan yürütmeye başlamak için etkinleştirildikten sonra basılabilir. Duraklat düğmesine basıldığında kayıttan yürütme duraklatılır. Durdur düğmesine basmak kayıttan yürütmeyi durdurur ve medya dosyasının konumunu en başa döndürür.

Özel birim denetimi uygulama

Her platform tarafından uygulanan medya kayıttan yürütme denetimleri bir ses düzeyi çubuğu içerir. Bu çubuk kaydırıcıya benzer ve medyanın ses düzeyini gösterir. Ayrıca, ses düzeyini artırmak veya azaltmak için ses çubuğunu değiştirebilirsiniz.

Özel birim çubuğu, aşağıdaki örnekte gösterildiği gibi kullanılarak Slideruygulanabilir:

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

Bu örnekte, Slider veriler özelliğini Value özelliğinin özelliğine VolumeMediaElementbağlar. Özelliği bir Volume bağlama kullandığından TwoWay bu mümkündür. Bu nedenle, özelliğin Value değiştirilmesi özelliğin değişmesine Volume neden olur.

Kullanma hakkında Slider daha fazla bilgi için bkz. .NET MAUI Kaydırıcısı

Kaynakları temizleme MediaElement

Bellek sızıntılarını önlemek için kaynaklarını MediaElementboşaltmanız gerekir. Bu, işleyicinin bağlantısını keserek yapılabilir. Bunu nerede yapmanız gerektiği, uygulamanızda nerede ve nasıl kullandığınıza MediaElement bağlıdır, ancak genellikle tek bir sayfanız MediaElement varsa ve arka planda medya oynatmıyorsanız, kullanıcı sayfadan dışarı çıktığında kaynakları serbest bırakabilirsiniz.

Bunun nasıl yapıldığını gösteren örnek kod parçacığını aşağıda bulabilirsiniz. İlk olarak, etkinliği sayfanızda bağladığından Unloaded emin olun.

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

Ardından arka planda kodda işleyicinin bağlantısını kesmek için yöntemini çağırın.

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

İşleyiciler hakkında daha fazla bilgi edinmek için lütfen İşleyiciler hakkındaki .NET MAUI belgelerine bakın.

Özellikler

Ekinlikler

Yöntemler

Örnekler

Bu denetimin örneklerini .NET MAUI Community Toolkit Örnek Uygulaması'nda iş başında bulabilirsiniz.

API

üzerinde için MediaElementkaynak kodunu .NET MAUI Community Toolkit GitHub deposunda bulabilirsiniz.

İlgili bağlantılar

• .NET MAUI Tetikleyicileri
• .NET MAUI Kaydırıcısı
• Android ExoPlayer: Desteklenen medya biçimleri
• iOS: Desteklenen medya biçimleri
• Windows: Desteklenen codec bileşenleri
• Android ExoPlayer Bağlamaları