Medya oturumu kullanma

Medya oturumları, ses veya video oynatıcıyla etkileşim kurmanın evrensel bir yolunu sunar. Android'e bir uygulamada medya oynatıldığını bildirerek oynatma kontrolleri uygulamaya devredilebilir. Medya oturumuyla entegrasyon, bir uygulamanın medya oynatmayı harici olarak tanıtmasına ve harici kaynaklardan oynatma komutları almasına olanak tanır. Bu kaynaklar fiziksel düğmeler (ör. kulaklık veya TV uzaktan kumandasındaki oynatma düğmesi) ya da dolaylı komutlar (ör. Google Asistan'a "duraklat" talimatı verme) olabilir. Medya oturumu daha sonra bu komutları, komutların nereden geldiğinin şeffaf olduğu medya oynatıcıya uygulayan uygulamaya devreder.

Medya oturumu, yönettiği oynatıcıyla birlikte çalışır. Medya oturumunu ve ilişkili oynatıcısını içeren etkinliğin veya hizmetin onCreate() yönteminde bir medya oturumu oluşturup başlatmanız gerekir.

Medya oturumunu başlatma

Yeni oluşturulan bir medya oturumunun özellikleri yoktur. Şu adımları uygulayarak oturumu başlatmanız gerekir:

  • Medya oturumunun medya kumandalarından ve medya düğmelerinden geri çağırma alabilmesi için işaretleri ayarlayın.
  • PlaybackStateCompat örneği oluşturup başlatın ve oturuma atayın. Oynatma durumu oturum boyunca değiştiğinden, yeniden kullanmak için PlaybackStateCompat.Builder öğesini önbelleğe almanızı öneririz.
  • MediaSessionCompat.Callback örneği oluşturun ve bunu oturuma atayın (geri çağırmalar hakkında daha fazla bilgi aşağıda verilmiştir).

Oturumun sahibi olan etkinliğin veya hizmetin onCreate() yönteminde bir medya oturumu oluşturup başlatmanız gerekir.

Uygulamanız yeni başlatıldığında (veya durdurulduğunda) medya düğmelerinin çalışması için PlaybackState, medya düğmesinin gönderdiği intent ile eşleşen bir oynatma işlemi içermelidir. Bu nedenle, başlatma sırasında oturum durumuna ACTION_PLAY atanır. Daha fazla bilgi için Medya düğmelerine yanıt verme başlıklı makaleyi inceleyin.

Oynatma durumunu ve meta verileri koruma

Medya oturumunun durumunu temsil eden iki sınıf vardır.

PlaybackStateCompat sınıfı, oynatıcının mevcut çalışma durumunu açıklar. Bunlardan bazıları:

  • Aktarım durumu (oynatıcının oynatıp oynatmadığı/duraklatılıp duraklatılmadığı/arabelleğe alıp almadığı vb. getState() bölümüne bakın.)
  • Geçerli olduğunda bir hata kodu ve isteğe bağlı hata mesajı. (Aşağıdaki getErrorCode() bölümüne bakın ve Durumlar ve hatalar bölümünü okuyun.)
  • Oyuncu pozisyonu
  • Mevcut durumda işlenebilecek geçerli denetleyici işlemleri

MediaMetadataCompat sınıfı, oynatılan materyali açıklar:

  • Sanatçı, albüm ve parça adı
  • Parça süresi
  • Kilit ekranında gösterilecek albüm kapağı. Resim, maksimum boyutu 320x320 dp olan bir bit eşlemdir (daha büyükse küçültülür).
  • Albüm kapağının daha büyük bir sürümüne işaret eden bir ContentUris örneği

Oynatıcı durumu ve meta veriler, medya oturumunun ömrü boyunca değişebilir. Durum veya meta veriler her değiştiğinde her sınıf için ilgili oluşturucuyu (PlaybackStateCompat.Builder() veya MediaMetadataCompat.Builder()) kullanmanız ve ardından setPlaybackState() ya da setMetaData() yöntemini çağırarak yeni örneği medya oturumuna iletmeniz gerekir. Bu sık yapılan işlemlerden kaynaklanan genel bellek tüketimini azaltmak için oluşturucuları bir kez oluşturup oturum boyunca yeniden kullanmak iyi bir fikirdir.

Durumlar ve hatalar

PlaybackState, oturumun oynatma durumu (getState()) için ayrı değerler ve gerektiğinde ilişkili bir hata kodu (getErrorCode()) içeren bir nesnedir. Hatalar önemli veya önemsiz olabilir:

Oynatma kesintiye uğradığında önemli bir hata oluşturmanız gerekir: Aktarım durumunu STATE_ERROR olarak ayarlayın ve setErrorMessage(int, CharSequence) ile ilişkili bir hata belirtin. Oynatma hata nedeniyle engellendiği sürece PlaybackState, STATE_ERROR ve hatayı bildirmeye devam etmelidir.

Uygulamanız bir isteği işleyemediğinde ancak oynatmaya devam edebildiğinde önemli olmayan bir hata oluşur: Aktarım "normal" durumda (ör. STATE_PLAYING) kalır ancak PlaybackState bir hata kodu içerir. Örneğin, son şarkı çalarken kullanıcı sonraki şarkıya geçme isteğinde bulunursa oynatma devam edebilir ancak ERROR_CODE_END_OF_QUEUE hata koduyla yeni bir PlaybackState oluşturup setPlaybackState() yöntemini çağırmanız gerekir. Oturuma bağlı medya kumandaları, onPlaybackStateChanged() geri çağırma işlevini alır ve kullanıcıya ne olduğunu açıklar. Önemli olmayan bir hata yalnızca bir kez, oluştuğu anda bildirilmelidir. Oturum, PlaybackState öğesini bir sonraki sefer güncellediğinde aynı önemli olmayan hatayı tekrar ayarlamayın (hata, yeni bir isteğe yanıt olarak oluşmadığı sürece).

Medya oturumu kilit ekranları

Android 4.0 (API düzeyi 14) sürümünden itibaren sistem, medya oturumunun oynatma durumuna ve meta verilerine erişebilir. Kilit ekranında medya kontrolleri ve posterler bu şekilde gösterilebilir. Davranış, Android sürümüne göre değişir.

Albüm kapağı

Android 4.0 (API düzeyi 14) ile Android 10 (API düzeyi 29) arasında, kilit ekranının arka planında albüm kapağınız gösterilir ancak bu yalnızca medya oturumu meta verileri bir arka plan bit eşlemi içeriyorsa geçerlidir.

Taşıma kontrolleri

Android 4.0 (API düzeyi 14) ile Android 4.4 (API düzeyi 19) arasında, bir medya oturumu etkin olduğunda ve medya oturumu meta verileri bir arka plan bitmap'i içerdiğinde kilit ekranı otomatik olarak taşıma kontrollerini gösterir.

Android 5.0 (API düzeyi 21) veya sonraki sürümlerde sistem, kilit ekranında taşıma kontrolleri sağlamaz. Bunun yerine, taşıma kontrollerini görüntülemek için MediaStyle bildirimi kullanmanız gerekir.

Özel işlem ekleme

Medya uygulamaları özel işlemler tanımlayabilir. Örneğin: beğenme, beğenme veya 30 saniye geri sarma. Özel işlem, tamamen yeni bir davranış uygulamalıdır. PlaybackStateCompat içinde tanımlanan standart taşıma kontrolü işlemlerinden birini değiştirmek için özel işlem kullanmayın.

addCustomAction() ile özel işlemler ekleyin. Aşağıdaki örnekte, beğenme işlemi için nasıl kontrol ekleneceği gösterilmektedir:

Kotlin

stateBuilder.addCustomAction(
        PlaybackStateCompat.CustomAction.Builder(
                CUSTOM_ACTION_THUMBS_UP,
                resources.getString(R.string.thumbs_up),
                thumbsUpIcon
        ).run {
            setExtras(customActionExtras)
            build()
        }
)

Java

stateBuilder.addCustomAction(new PlaybackStateCompat.CustomAction.Builder(
    CUSTOM_ACTION_THUMBS_UP, resources.getString(R.string.thumbs_up), thumbsUpIcon)
    .setExtras(customActionExtras)
    .build());

Eksiksiz bir örnek için Universal Music Player'a bakın.

İşleme onCustomAction() ile yanıt verirsiniz.

Kotlin

override fun onCustomAction(action: String, extras: Bundle?) {
    when(action) {
        CUSTOM_ACTION_THUMBS_UP -> {
            ...
        }
    }
}

Java

@Override
public void onCustomAction(@NonNull String action, Bundle extras) {
    if (CUSTOM_ACTION_THUMBS_UP.equals(action)) {
        ...
    }
}

Universal Music Player'a da göz atın.

Medya oturumu geri çağırmaları

Ana medya oturumu geri çağırma yöntemleri onPlay(), onPause() ve onStop() yöntemleridir. Oyuncunuzu kontrol eden kodu buraya eklersiniz.

Oturumun geri çağırmasını çalışma zamanında (onCreate() içinde) örneklendirip ayarladığınız için uygulamanız, farklı oynatıcılar kullanan alternatif geri çağırmalar tanımlayabilir ve cihaza ve sistem düzeyine bağlı olarak uygun geri çağırma ve oynatıcı kombinasyonunu seçebilir. Uygulamanın geri kalanını değiştirmeden oynatıcıyı değiştirebilirsiniz. Örneğin, Android 4.1 (API düzeyi 16) veya sonraki sürümlerde çalışırken ExoPlayer'ı, daha eski sistemlerde ise MediaPlayer'ı kullanabilirsiniz.

Geri çağırmalar, oynatıcıyı kontrol etmenin ve medya oturumu durum geçişlerini yönetmenin yanı sıra uygulamanızın özelliklerini etkinleştirip devre dışı bırakır ve diğer uygulamalarla ve cihaz donanımıyla etkileşimini kontrol eder. (Ses Çıkışını Kontrol Etme bölümüne bakın).

Medya oturumu geri çağırma yöntemlerinin uygulanması, uygulamanızın yapısına bağlıdır. Ses uygulamalarında ve video uygulamalarında geri çağırmaların nasıl kullanılacağını açıklayan ayrı sayfalara bakın. Bu sayfalarda, geri çağırmaların her uygulama türü için nasıl uygulanması gerektiği açıklanmaktadır.