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ğindenPlaybackStateCompat.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.