Medya oturumu kullanma

Medya oturumları, bir ses veya video oynatıcı ile etkileşim için evrensel bir yol sunar. Android'e medyanın bir uygulamada oynatıldığını bildirerek oynatma kontrolleri uygulamaya devredilebilir. Medya oturumuyla entegrasyon, bir uygulamanın harici olarak medya oynatmanın reklamını yapmasına ve harici kaynaklardan oynatma komutları almasına olanak tanır. Bu kaynaklar fiziksel düğmeler (ör. mikrofonlu kulaklık veya TV uzaktan kumandasındaki oynat düğmesi) ya da dolaylı komutlar (ör. Google Asistan'a "duraklatma" talimatı vermek) olabilir. Daha sonra medya oturumu, bu komutları medya oynatıcıya uygulayan uygulamaya yetki verir. Bu uygulamalar, komutların kaynaklandığı yeri şeffaf olarak gösterir.

Medya oturumu, yönettiği oynatıcıyla birlikte sunulur. Medya oturumunun ve ilişkili oynatıcısının sahibi olan etkinlik veya hizmetin onCreate() yönteminde bir medya oturumu oluşturup başlatmanız gerekir.

Medya oturumunu başlatma

Yeni oluşturulan bir medya oturumunun özelliği yoktur. Aşağıdaki adımları uygulayarak oturumu başlatmanız gerekir:

  • İşaretleri, medya oturumunun medya denetleyicilerinden ve medya düğmelerinden geri çağırmalar alabileceği şekilde ayarlayın.
  • PlaybackStateCompat örneği oluşturup başlatın ve bunu oturuma atayın. Oynatma durumu oturum boyunca değiştiğinden PlaybackStateCompat.Builder öğesini yeniden kullanmak üzere önbelleğe almanızı öneririz.
  • MediaSessionCompat.Callback örneği oluşturun ve bunu oturuma atayın (geri çağırmalarla ilgili daha fazla bilgiyi aşağıda bulabilirsiniz).

Oturuma sahip 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 öğesinin, medya düğmesinin gönderdiği amaçla eşleşen bir oynatma işlemi içermesi gerekir. Bu nedenle, başlatma sırasında ACTION_PLAY oturum durumuna atanır. Daha fazla bilgi için Medya Düğmelerine Yanıt Verme bölümüne bakın.

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. Bunu başarmak için şunlardan yararlanırız:

  • Aktarım durumu (oynatıcının oynattığı/duraklatıldığı/arabelleğe aldığı vb. Bkz. getState())
  • Varsa bir hata kodu ve isteğe bağlı hata mesajı. (Aşağıdaki getErrorCode() bölümünü inceleyin ve Durumlar ve hatalar'ı okuyun.)
  • Oyuncu konumu
  • Mevcut durumda işlenebilecek geçerli denetleyici işlemleri

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

  • Sanatçının, albümün ve parçanın 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).
  • Posterin daha büyük bir halini gösteren ContentUris örneği

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

Durumlar ve hatalar

PlaybackState öğesinin, oturumun oynatma durumu (getState()) ve gerektiğinde ilişkili bir hata kodu (getErrorCode()) için ayrı değerler içeren bir nesne olduğunu unutmayın. Hatalar önemli veya önemli olmayabilir:

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

Uygulamanız bir isteği işleyemediğinde, ancak oynatmaya devam edebildiğinde önemli olmayan bir hata oluşur: Aktarım "normal" durumda (STATE_PLAYING gibi) kalır ancak PlaybackState hata kodu içerir. Örneğin, son şarkı çalıyorsa ve kullanıcı bir sonraki şarkıya atlamak isterse oynatma devam edebilir, ancak ERROR_CODE_END_OF_QUEUE hata koduyla yeni bir PlaybackState oluşturup setPlaybackState() işlevini çağırmanız gerekir. Oturuma bağlı Medya Denetleyicileri, onPlaybackStateChanged() geri çağırmasını alır ve kullanıcıya ne olduğunu açıklar. Önemli olmayan bir hata, oluştuğu anda yalnızca bir kez bildirilmelidir. Oturumun bir sonraki güncellemesinde, PlaybackState aynı onarılabilir hatayı bir daha ayarlamaz (hata yeni bir isteğe yanıt olarak oluşmadığı sürece).

Medya oturumu kilit ekranları

Sistem, Android 4.0 (API düzeyi 14) sürümünden başlayarak bir medya oturumunun oynatma durumuna ve meta verilerine erişebilir. Medya denetimleri ve çizimler kilit ekranında bu şekilde görüntülenebilir. Bu 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ındaki sürümlerde, yalnızca medya oturumu meta verileri arka plan bit eşlemi içeriyorsa kilit ekranının arka planı albüm resminizi gösterir.

Aktarım denetimleri

Android 4.0 (API düzeyi 14) ile Android 4.4 (API düzeyi 19) arasındaki sürümlerde, bir medya oturumu etkin olduğunda ve medya oturumu meta verileri bir arka plan bit eşlemi içeriyorsa kilit ekranı aktarım denetimlerini otomatik olarak görüntüler.

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

Özel işlemler ekleme

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

addCustomAction() ile özel işlemler ekleyin. Aşağıdaki örnekte, bir 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());

Tam ö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)) {
        ...
    }
}

Ayrıca Evrensel Müzik Oynatıcı'ya da bakın.

Medya oturumu geri çağırmaları

Ana medya oturumu geri çağırma yöntemleri onPlay(), onPause() ve onStop()'dir. Oynatıcınızı kontrol eden kodu buraya eklersiniz.

Çalışma zamanında oturumun geri çağırmasını örnekleyip ayarladığınız için (onCreate() içinde) uygulamanız, farklı oynatıcılar kullanan alternatif geri çağırmalar tanımlayabilir ve cihaza ve/veya sistem seviyesine göre uygun geri çağırma/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 seviyesi 16) veya sonraki bir sürümde çalışırken ExoPlayer'ı, daha önceki sistemlerde ise MediaPlayer'i kullanabilirsiniz.

Geri çağırma işlevi, 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şim kurma şeklini kontrol eder. (Bkz. Ses Çıkışını Kontrol Etme).

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ın açıklandığı ayrı sayfalara bakın, geri çağırmaların her bir uygulama türü için nasıl uygulanması gerektiğini açıklayın.