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 :

Not

MediaElement iOS, Android, Windows, macOS ve Tizen'de kullanılabilir.

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

Platform	Platform medya oynatıcısı uygulaması
Android	ExoPlayer, ExoPlayerXamarin bakımcılarına büyük teşekkür ederiz!
iOS/macOS	AVPlayer
Windows	Mediaplayer

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 UseMauiCommunityToolkitMediaElement kullanılabilmesi için, MauiProgram.cs dosyasının bir uygulamaya önyüklemesi sırasında sınıfında çağrılmalıdırMauiAppBuilder.MediaElement 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.

Android

Android'de uygulamasını başlatmak MediaElement için, uygulamaların Activity değeri olarak ayarlanmalıdır LaunchMode.SingleTask ve aşağıdaki örne göre öğesini eklemeniz ResizableActivity=true gerekir LaunchMode

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

Bir uygulamaya dahil edilen bu yöntemin tam örneği için lütfen .NET MAUI Community Toolkit Örnek Uygulamasına bakın

iOS/Mac Katalizör

Kurulum gerekmez.

Windows

Kurulum gerekmez.

Tizen

Kurulum gerekmez.

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.

Platform	Bağlantı	Notlar
Android	ExoPlayer Desteklenen Biçimler
iOS/macOS	iOS/macOS Desteklenen Biçimler	Bununla ilgili resmi bir belge yok
Windows	Windows Desteklenen Biçimler	Windows'da desteklenen biçimler, kullanıcının makinesine hangi codec bileşenlerinin yüklendiğine çok bağlıdır
Tizen	Desteklenen Tizen Biçimleri

Önemli

Kullanıcı bir Windows N sürümü kullanıyorsa, varsayılan olarak video kayıttan yürütme desteklenmez. Windows N sürümlerinde tasarım gereği yüklenmiş video kayıttan yürütme biçimleri yoktur.

Genel senaryolar

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

iOS Sessiz Anahtarını Atlama

iOS'ta, kullanıcı Donanım Sessiz Anahtarı'nı kapalı olarak değiştirdiğinde MediaElement'in kayıttan yürütme sesi varsayılan olarak kapatılır.

iOS'ta Donanım Sessiz Anahtarı'nı atlamak için aşağıdaki kod satırlarını öğesine MauiProgram.csekleyin. Bu, MediaElement'in kayıttan yürütme sesinin, cihazının Donanım Sessiz Anahtarından bağımsız olarak kullanıcıya her zaman duyulabilmesini sağlar.

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

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

Önemli

HTTP uç noktalarındaki uzak kaynakları yürütürken, güvenli olmayan web uç noktalarına erişimi engelleyen işletim sistemi güvenlik önlemlerini devre dışı bırakmanız gerekebilir. Bu, en az iOS ve Android için geçerlidir.

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 falseolarak ayarlanarak ShouldShowPlaybackControls devre dışı bırakılabilir.

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.

Not

embed:// Kısaltma ve filesystem:// yalnızca XAML'den çalışır. Kodda, lütfen sırasıyla ve MediaSource.FromFile() kullanınMediaSource.FromResource(). Bu yöntemleri kullanarak ve filesystem:// ön eklerini atlayabilirsinizembed://. Yolun geri kalanı aynı olmalıdır.

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ı Resources/Raw .NET MAUI projenizin 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 Uri bağımsız değişkenlerinden string örnekler döndüren MediaSource örtük işleçlere de sahiptir.

Not

Source özelliği XAML'de ayarlandığında, veya Uri'den string bir örneği döndürmek için bir MediaSource tür dönüştürücüsü çağrılır.

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.

Not

XAML'de bir FileMediaSource nesne oluşturulduğunda, bir türünden örnek döndürmek için bir FileMediaSourcestringtür dönüştürücüsü çağrılı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 MediaElementStateadlı CurrentStatesalt 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 MediaElement özelliğin incelenmesi CurrentState 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 , Pauseve Stop yöntemlerini içerirPlay.

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'ı, ikincisi Button de Durdur'u temsil eden iki Button nesne vardır.Button 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 TwoWay bağlama kullandığından Volume bu mümkündür. Bu nedenle, özelliğin Value değiştirilmesi özelliğin değişmesine Volume neden olur.

Not

özelliği, Volume değerinin 0,0'dan büyük veya buna eşit ve 1,0'dan küçük veya 1,0'a eşit olmasını sağlayan bir doğrulama geri çağırmasına sahiptir.

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

Özellik	Türü	Açıklama	Varsayılan Değer
Görünüş	Görünüş	Şu anda yüklü olan (görsel) medya için ölçeklendirme modunu belirler. Bu, bağlanabilir bir özelliktir.	Aspect.AspectFit
Currentstate	MediaElementState	Denetimin geçerli durumunu gösterir. Bu salt okunur, bağlanabilir bir özelliktir.	MediaElementState.None
Süre	TimeSpan	Açık durumdaki medyanın süresini gösterir. Bu salt okunur, bağlanabilir bir özelliktir.	TimeSpan.Zero
Position	TimeSpan	Medyanın kayıttan yürütme süresi boyunca geçerli ilerleme durumunu açıklar. Bu salt okunur, bağlanabilir bir özelliktir. yöntemini ayarlamak PositionSeekTo() istiyorsanız kullanın.	TimeSpan.Zero
ShouldAutoPlay	bool	Özellik ayarlandığında medya kayıttan yürütmenin Source otomatik olarak başlayıp başlamayacağını gösterir. Bu, bağlanabilir bir özelliktir.	false
ShouldLoopPlayback	bool	Şu anda yüklü olan medya kaynağının sonuna ulaştıktan sonra kayıttan yürütmeyi baştan sürdürmesi gerekip gerekmediğini açıklar. Bu, bağlanabilir bir özelliktir.	false
ShouldKeepScreenOn	bool	Medya kayıttan yürütme sırasında cihaz ekranının açık kalıp kalmayacağını belirler. Bu, bağlanabilir bir özelliktir.	false
ShouldMute	bool	Sesin şu anda kapalı olup olmadığını belirler. Bu, bağlanabilir bir özelliktir.	false
ShouldShowPlaybackControls	bool	Platform kayıttan yürütme denetimlerinin görüntülenip görüntülenmeyeceğini belirler. Bu, bağlanabilir bir özelliktir. iOS ve Windows'ta denetimlerin yalnızca ekranla etkileşime geçtikten sonra kısa bir süre boyunca gösterildiğini unutmayın. Denetimleri her zaman görünür tutmanın bir yolu yoktur.	true
Kaynak	MediaSource?	Denetime yüklenen medyanın kaynağı.	null
Hız	double	Medyanın kayıttan yürütme hızını belirler. Bu bağlanabilir bir özelliktir	1
MediaHeight	int	Yüklenen medyanın piksel cinsinden yüksekliği. Bu salt okunur, bağlanabilir bir özelliktir.	0
MediaWidth	int	Yüklenen medyanın piksel cinsinden genişliği. Bu salt okunur, bağlanabilir bir özelliktir.	0
Hacim	double	Medyanın 0 ile 1 arasında doğrusal bir ölçekte temsil edilen hacmini belirler. Bu, bağlanabilir bir özelliktir.	1

Ekinlikler

Olay	Açıklama
MediaOpened	Medya akışı doğrulandığında ve açıldığında gerçekleşir.
MediaEnded	Medya yürütmeyi MediaElement bitirdiğinde gerçekleşir.
MediaFailed	Medya kaynağıyla ilişkilendirilmiş bir hata olduğunda oluşur.
Positionchanged	Özellik değeri değiştiğinde Position gerçekleşir.
SeekCompleted	İstenen arama işleminin arama noktası kayıttan yürütme için hazır olduğunda gerçekleşir.

Yöntemler

Olay	Açıklama
Yürüt	Yüklenen medyayı yürütmeye başlar.
Duraklat	Geçerli medyanın kayıttan yürütülmesini duraklatır.
Durdur	Kayıttan yürütmeyi durdurur ve geçerli medyanın konumunu sıfırlar.
Ara	özelliğini ayarlamak için bir TimeSpan değer alır ve iptal Tasketmek için bir CancellationTokenPosition alır.

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