Cast SDK'sının bir özelliği olan Çıkış Değiştirici, Android 13'ten itibaren içeriklerin yerel ve uzaktan oynatılması arasında sorunsuz aktarıma olanak tanır. Amaç, gönderen uygulamaların içeriğin oynatıldığı yeri kolay ve hızlı bir şekilde kontrol etmesine yardımcı olmaktır.
Çıkış Değiştirici, MediaRouter
kitaplığını kullanarak içerik oynatmayı telefon hoparlörü, eşlenmiş Bluetooth cihazlar ve uzak Cast uyumlu cihazlarda değiştirebilir. Kullanım alanları aşağıdaki senaryolara ayrılabilir:
Ses uygulamanıza Çıkış Değiştirici'yi nasıl uygulayacağınızla ilgili referans için aşağıdaki örneği indirin ve kullanın. Örneği çalıştırmayla ilgili talimatlar için, eklenen README.md dosyasına bakın.
Çıkış Değiştirici, bu kılavuzda açıklanan adımlar kullanılarak yerelden uzağa ve uzaktan yerele geçişi destekleyecek şekilde etkinleştirilmelidir. Yerel cihaz hoparlörleri ile eşlenen Bluetooth cihazlar arasındaki aktarımı desteklemek için başka adımlara gerek yoktur.
Ses uygulamaları, Google Cast SDK Geliştirici Konsolu'ndaki Alıcı Uygulaması ayarlarında Ses için Google Cast'i destekleyen uygulamalardır.
Çıkış Değiştirici Kullanıcı Arayüzü
Çıkış Değiştirici, kullanılabilir yerel ve uzak cihazların yanı sıra cihazın seçili olması, bağlanıyor olması ve mevcut ses düzeyi gibi mevcut cihaz durumlarını da gösterir. Mevcut cihaza ek olarak başka cihazlar da varsa diğer cihazı tıkladığınızda medya oynatmasını seçilen cihaza aktarabilirsiniz.
Bilinen sorunlar
- Yerel oynatma için oluşturulan Medya Oturumları, Cast SDK bildirimine geçiş yapılırken kapatılır ve yeniden oluşturulur.
Giriş noktaları
Medya bildirimi
Bir uygulama, yerel oynatma (yerel olarak oynatılıyor) için MediaSession
simgesiyle bir medya bildirimi yayınlarsa medya bildiriminin sağ üst köşesinde, içeriğin oynatıldığı cihazın adının (telefon hoparlörü gibi) yer aldığı bir bildirim çipi gösterilir. Bildirim çipine dokunduğunuzda
Çıkış Değiştirici iletişim kutusu sistem arayüzü açılır.
Ses düzeyi ayarları
Çıkış Değiştirici iletişim sistemi kullanıcı arayüzünü, cihazdaki fiziksel ses düğmeleri tıklandıktan sonra en alttaki ayarlar simgesine, ardından "<Yayın Cihazında <Uygulama Adı> Oynat" metnine dokunarak da tetikleyebilirsiniz.
Adımların özeti
- Ön koşulların karşılandığından emin olma
- AndroidManifest.xml dosyasında Çıkış Değiştirici'yi etkinleştir
- Arka planda yayınlama için SessionManagerListener'ı güncelleme
- setRemoteToLocalEnabled işaretini ayarlama
- Oynatmaya yerel olarak devam etme
Ön koşullar
- Mevcut Android uygulamanızı AndroidX'e taşıyın.
- Uygulamanızın
build.gradle
sürümünü, Exit Switcher için Android Gönderen SDK'sının gereken minimum sürümünü kullanacak şekilde güncelleyin:dependencies { ... implementation 'com.google.android.gms:play-services-cast-framework:21.2.0' ... }
- Uygulama, medya bildirimlerini destekliyor.
- Android 13 çalıştıran cihaz.
Medya Bildirimlerini Ayarlama
Çıkış Değiştirici'yi kullanmak için ses ve video uygulamalarının, yerel oynatma için medyalarının oynatma durumunu ve kontrollerini görüntülemek üzere medya bildirimi oluşturması gerekir. Bunun için bir MediaSession
oluşturulması, MediaStyle
öğesinin MediaSession
jetonuyla ayarlanması ve bildirimdeki medya denetimlerinin ayarlanması gerekir.
Şu anda MediaStyle
ve MediaSession
kullanmıyorsanız aşağıdaki snippet'te bunların nasıl ayarlanacağı gösterilmektedir. ses ve video uygulamaları için medya oturumu geri çağırmalarını ayarlamak üzere kılavuzlar da mevcuttur:
// Create a media session. NotificationCompat.MediaStyle // PlayerService is your own Service or Activity responsible for media playback. val mediaSession = MediaSessionCompat(this, "PlayerService") // Create a MediaStyle object and supply your media session token to it. val mediaStyle = Notification.MediaStyle().setMediaSession(mediaSession.sessionToken) // Create a Notification which is styled by your MediaStyle object. // This connects your media session to the media controls. // Don't forget to include a small icon. val notification = Notification.Builder(this@PlayerService, CHANNEL_ID) .setStyle(mediaStyle) .setSmallIcon(R.drawable.ic_app_logo) .build() // Specify any actions which your users can perform, such as pausing and skipping to the next track. val pauseAction: Notification.Action = Notification.Action.Builder( pauseIcon, "Pause", pauseIntent ).build() notification.addAction(pauseAction)
if (android.os.Build.VERSION.SDK_INT >= android.os.Build.VERSION_CODES.O) { // Create a media session. NotificationCompat.MediaStyle // PlayerService is your own Service or Activity responsible for media playback. MediaSession mediaSession = new MediaSession(this, "PlayerService"); // Create a MediaStyle object and supply your media session token to it. Notification.MediaStyle mediaStyle = new Notification.MediaStyle().setMediaSession(mediaSession.getSessionToken()); // Specify any actions which your users can perform, such as pausing and skipping to the next track. Notification.Action pauseAction = Notification.Action.Builder(pauseIcon, "Pause", pauseIntent).build(); // Create a Notification which is styled by your MediaStyle object. // This connects your media session to the media controls. // Don't forget to include a small icon. String CHANNEL_ID = "CHANNEL_ID"; Notification notification = new Notification.Builder(this, CHANNEL_ID) .setStyle(mediaStyle) .setSmallIcon(R.drawable.ic_app_logo) .addAction(pauseAction) .build(); }
Ayrıca, bildirimi medyanızla ilgili bilgilerle doldurmak için medyanızın meta verilerini ve oynatma durumunu MediaSession
'a eklemeniz gerekir.
MediaSession
öğesine meta veri eklemek için setMetaData()
kullanın ve MediaMetadataCompat.Builder()
içinde medyanızla ilgili tüm MediaMetadata
sabit değerlerini sağlayın.
mediaSession.setMetadata(MediaMetadataCompat.Builder() // Title .putString(MediaMetadata.METADATA_KEY_TITLE, currentTrack.title) // Artist // Could also be the channel name or TV series. .putString(MediaMetadata.METADATA_KEY_ARTIST, currentTrack.artist) // Album art // Could also be a screenshot or hero image for video content // The URI scheme needs to be "content", "file", or "android.resource". .putString( MediaMetadata.METADATA_KEY_ALBUM_ART_URI, currentTrack.albumArtUri) ) // Duration // If duration isn't set, such as for live broadcasts, then the progress // indicator won't be shown on the seekbar. .putLong(MediaMetadata.METADATA_KEY_DURATION, currentTrack.duration) .build() )
if (android.os.Build.VERSION.SDK_INT >= android.os.Build.VERSION_CODES.O) { mediaSession.setMetadata( new MediaMetadataCompat.Builder() // Title .putString(MediaMetadata.METADATA_KEY_TITLE, currentTrack.title) // Artist // Could also be the channel name or TV series. .putString(MediaMetadata.METADATA_KEY_ARTIST, currentTrack.artist) // Album art // Could also be a screenshot or hero image for video content // The URI scheme needs to be "content", "file", or "android.resource". .putString(MediaMetadata.METADATA_KEY_ALBUM_ART_URI, currentTrack.albumArtUri) // Duration // If duration isn't set, such as for live broadcasts, then the progress // indicator won't be shown on the seekbar. .putLong(MediaMetadata.METADATA_KEY_DURATION, currentTrack.duration) .build() ); }
Oynatma durumunu MediaSession
öğesine eklemek için setPlaybackState()
kullanın ve medyanızla ilgili tüm PlaybackStateCompat
sabit değerlerini PlaybackStateCompat.Builder()
içinde sağlayın.
mediaSession.setPlaybackState( PlaybackStateCompat.Builder() .setState( PlaybackStateCompat.STATE_PLAYING, // Playback position // Used to update the elapsed time and the progress bar. mediaPlayer.currentPosition.toLong(), // Playback speed // Determines the rate at which the elapsed time changes. playbackSpeed ) // isSeekable // Adding the SEEK_TO action indicates that seeking is supported // and makes the seekbar position marker draggable. If this is not // supplied seek will be disabled but progress will still be shown. .setActions(PlaybackStateCompat.ACTION_SEEK_TO) .build() )
if (android.os.Build.VERSION.SDK_INT >= android.os.Build.VERSION_CODES.O) { mediaSession.setPlaybackState( new PlaybackStateCompat.Builder() .setState( PlaybackStateCompat.STATE_PLAYING, // Playback position // Used to update the elapsed time and the progress bar. mediaPlayer.currentPosition.toLong(), // Playback speed // Determines the rate at which the elapsed time changes. playbackSpeed ) // isSeekable // Adding the SEEK_TO action indicates that seeking is supported // and makes the seekbar position marker draggable. If this is not // supplied seek will be disabled but progress will still be shown. .setActions(PlaybackStateCompat.ACTION_SEEK_TO) .build() ); }
Video uygulaması bildirim davranışı
Arka planda yerel oynatmayı desteklemeyen video veya ses uygulamaları, oynatmanın desteklenmediği durumlarda medya komutu göndermeyle ilgili sorunları önlemek için medya bildirimleriyle ilgili belirli davranışlara sahip olmalıdır:
- Yerel olarak medya oynatıldığında ve uygulama ön plandayken medya bildirimi yayınlayın.
- Yerel oynatmayı duraklatın ve uygulama arka plandayken bildirimi kapatın.
- Uygulama tekrar ön plana geçtiğinde, yerel oynatma devam ettirilir ve bildirim yeniden yayınlanır.
AndroidManifest.xml dosyasında Çıktı Değiştiriciyi etkinleştir
Çıkış Değiştirici'yi etkinleştirmek için MediaTransferReceiver
, uygulamanın AndroidManifest.xml
bölümüne eklenmelidir. Aksi halde özellik etkinleştirilmez ve uzaktan-yerel özellik bayrağı geçersiz olur.
<application>
...
<receiver
android:name="androidx.mediarouter.media.MediaTransferReceiver"
android:exported="true">
</receiver>
...
</application>
MediaTransferReceiver
, sistem kullanıcı arayüzüyle cihazlar arasında medya aktarımına olanak tanıyan bir yayın alıcısıdır. Daha fazla bilgi için MediaTransferReceiver referansı bölümüne bakın.
Yerelden Uzaktan Kumandaya
Kullanıcı, oynatmayı yerel moddan uzaktan kumandaya geçirdiğinde Cast SDK, Cast oturumunu otomatik olarak başlatır. Ancak uygulamaların, yerelden uzaka geçiş işlemini gerçekleştirmesi gerekir. Örneğin, yerel oynatmayı durdurabilir ve medyayı yayın cihazına yükleyebilirsiniz. Uygulamalar, onSessionStarted()
ve onSessionEnded()
geri çağırmalarını kullanarak Cast'i SessionManagerListener
dinlemeli ve Cast
SessionManager
geri çağırmalarını alırken işlemi gerçekleştirmelidir. Uygulamalar, Çıkış Değiştirici iletişim kutusu açıldığında ve uygulama ön planda değilken bu geri çağırmaların hâlâ etkin olduğundan emin olmalıdır.
Arka planda yayınlama için SessionManagerListener'ı güncelleme
Eski Cast deneyimi, uygulama ön plandayken yerelden uzaktan kumandayı zaten desteklemektedir. Tipik bir Cast deneyimi, kullanıcılar uygulamadaki Cast simgesini
tıklayıp medya akışı için bir cihaz seçtiğinde başlar. Bu durumda, uygulamanın onCreate()
veya onStart()
içinde SessionManagerListener
'e kaydolması ve onStop()
ya da
onDestroy()
uygulama etkinliğindeki dinleyici kaydını iptal etmesi gerekir.
Çıkış Değiştirici'yi kullanarak yeni yayınlama deneyimi sayesinde, uygulamalar arka planda yayın yapmaya başlayabilir. Bu özellik, özellikle arka planda çalarken bildirim gönderen ses uygulamaları için kullanışlıdır. Uygulamalar, SessionManager
işleyicilerini hizmetin onCreate()
bölümüne kaydedebilir ve hizmetin onDestroy()
kaydını iptal edebilir. Bu şekilde, uygulamalar arka plandayken her zaman yerelden uzaktan cihaza geri çağırmaları (onSessionStarted
gibi) almalıdır.
Uygulama MediaBrowserService
kullanıyorsa SessionManagerListener
orada kaydetmeniz önerilir.
class MyService : Service() { private var castContext: CastContext? = null protected fun onCreate() { castContext = CastContext.getSharedInstance(this) castContext .getSessionManager() .addSessionManagerListener(sessionManagerListener, CastSession::class.java) } protected fun onDestroy() { if (castContext != null) { castContext .getSessionManager() .removeSessionManagerListener(sessionManagerListener, CastSession::class.java) } } }
public class MyService extends Service { private CastContext castContext; @Override protected void onCreate() { castContext = CastContext.getSharedInstance(this); castContext .getSessionManager() .addSessionManagerListener(sessionManagerListener, CastSession.class); } @Override protected void onDestroy() { if (castContext != null) { castContext .getSessionManager() .removeSessionManagerListener(sessionManagerListener, CastSession.class); } } }
Bu güncellemeyle birlikte, yerelden uzaktan kumandaya geçiş özelliği, uygulama arka plandayken geleneksel yayın ile aynı şekilde çalışır ve Bluetooth cihazlardan yayın cihazlarına geçiş için ekstra çalışma yapılması gerekmez.
Uzaktan yerele
Çıkış Değiştirici, uzaktan oynatmadan telefon hoparlörüne veya yerel Bluetooth cihazına aktarım imkanı sağlar. Bu özellik, CastOptions
üzerinde setRemoteToLocalEnabled
işaretini true
olarak ayarlayarak etkinleştirilebilir.
Mevcut gönderen cihazın birden fazla gönderenle mevcut bir oturuma katıldığı ve uygulamanın, mevcut medyanın yerel olarak aktarılmasına izin verilip verilmediğini kontrol etmesi gereken durumlarda, uygulamalar SessionState
öğesini kontrol etmek için SessionTransferCallback
onTransferred
geri çağırmasını kullanmalıdır.
setRemoteToLocalEnabled işaretini ayarlayın
CastOptions
, etkin bir Cast oturumu olduğunda Çıktı Değiştirici iletişim kutusunda telefon hoparlörünü ve yerel Bluetooth cihazlarını aktarım hedefleri olarak göstermek veya gizlemek için bir setRemoteToLocalEnabled
sağlar.
class CastOptionsProvider : OptionsProvider { fun getCastOptions(context: Context?): CastOptions { ... return Builder() ... .setRemoteToLocalEnabled(true) .build() } }
public class CastOptionsProvider implements OptionsProvider { @Override public CastOptions getCastOptions(Context context) { ... return new CastOptions.Builder() ... .setRemoteToLocalEnabled(true) .build() } }
Yerel olarak oynatmaya devam et
Uzaktan yerele geçişi destekleyen uygulamalar etkinlik gerçekleştiğinde bildirim almak için SessionTransferCallback
özelliğini kaydetmelidir. Böylece, medya aktarımına izin verilip verilmediğini kontrol edebilir ve yerel olarak oynatmaya devam edebilirler.
CastContext#addSessionTransferCallback(SessionTransferCallback)
, bir
uygulamanın SessionTransferCallback
cihazını kaydetmesine ve gönderen yerel oynatmaya aktarıldığında
onTransferred
ile onTransferFailed
geri aramalarını dinlemesine olanak tanır.
Uygulama, SessionTransferCallback
kaydını iptal ettikten sonra artık SessionTransferCallback
alamaz.
SessionTransferCallback
, mevcut SessionManagerListener
geri çağırmalarının bir uzantısıdır ve onSessionEnded
tetiklendikten sonra tetiklenir. Bu nedenle, uzaktan-yerel geri çağırmaların sırası şu şekildedir:
onTransferring
onSessionEnding
onSessionEnded
onTransferred
Uygulama arka plandayken ve yayın yaparken Çıkış Değiştirici medya bildirim çipi ile açılabildiğinden, uygulamaların arka planda oynatmayı destekleyip desteklemediklerine bağlı olarak yerel ortama aktarımı farklı şekilde işlemesi gerekir. Aktarım başarısız olursa hata meydana geldiği anda onTransferFailed
etkinleşir.
Arka planda oynatmayı destekleyen uygulamalar
Arka planda oynatmayı destekleyen uygulamalarda (genellikle ses uygulamaları) Service
(örneğin MediaBrowserService
) kullanılması önerilir. Hizmetler, hem ön planda hem arka planda çalışırken onTransferred
geri çağırmasını dinlemeli ve oynatmayı yerel olarak devam ettirmelidir.
class MyService : Service() { private var castContext: CastContext? = null private var sessionTransferCallback: SessionTransferCallback? = null protected fun onCreate() { castContext = CastContext.getSharedInstance(this) castContext.getSessionManager() .addSessionManagerListener(sessionManagerListener, CastSession::class.java) sessionTransferCallback = MySessionTransferCallback() castContext.addSessionTransferCallback(sessionTransferCallback) } protected fun onDestroy() { if (castContext != null) { castContext.getSessionManager() .removeSessionManagerListener(sessionManagerListener, CastSession::class.java) if (sessionTransferCallback != null) { castContext.removeSessionTransferCallback(sessionTransferCallback) } } } class MySessionTransferCallback : SessionTransferCallback() { fun onTransferring(@SessionTransferCallback.TransferType transferType: Int) { // Perform necessary steps prior to onTransferred } fun onTransferred(@SessionTransferCallback.TransferType transferType: Int, sessionState: SessionState?) { if (transferType == SessionTransferCallback.TRANSFER_TYPE_FROM_REMOTE_TO_LOCAL) { // Remote stream is transferred to the local device. // Retrieve information from the SessionState to continue playback on the local player. } } fun onTransferFailed(@SessionTransferCallback.TransferType transferType: Int, @SessionTransferCallback.TransferFailedReason transferFailedReason: Int) { // Handle transfer failure. } } }
public class MyService extends Service { private CastContext castContext; private SessionTransferCallback sessionTransferCallback; @Override protected void onCreate() { castContext = CastContext.getSharedInstance(this); castContext.getSessionManager() .addSessionManagerListener(sessionManagerListener, CastSession.class); sessionTransferCallback = new MySessionTransferCallback(); castContext.addSessionTransferCallback(sessionTransferCallback); } @Override protected void onDestroy() { if (castContext != null) { castContext.getSessionManager() .removeSessionManagerListener(sessionManagerListener, CastSession.class); if (sessionTransferCallback != null) { castContext.removeSessionTransferCallback(sessionTransferCallback); } } } public static class MySessionTransferCallback extends SessionTransferCallback { public MySessionTransferCallback() {} @Override public void onTransferring(@SessionTransferCallback.TransferType int transferType) { // Perform necessary steps prior to onTransferred } @Override public void onTransferred(@SessionTransferCallback.TransferType int transferType, SessionState sessionState) { if (transferType==SessionTransferCallback.TRANSFER_TYPE_FROM_REMOTE_TO_LOCAL) { // Remote stream is transferred to the local device. // Retrieve information from the SessionState to continue playback on the local player. } } @Override public void onTransferFailed(@SessionTransferCallback.TransferType int transferType, @SessionTransferCallback.TransferFailedReason int transferFailedReason) { // Handle transfer failure. } } }
Arka planda oynatmayı desteklemeyen uygulamalar
Arka planda oynatmayı desteklemeyen uygulamalarda (genellikle video uygulamaları) onTransferred
geri çağırmasını dinlemeniz ve uygulama ön plandaysa oynatmayı yerel olarak devam ettirmeniz önerilir.
Uygulama arka plandaysa oynatmayı duraklatmalı ve SessionState
kaynağından gerekli bilgileri (ör. medya meta verileri ve oynatma konumu) depolamalıdır. Uygulama arka planda ön planda olduğunda yerel oynatma, depolanan bilgilerle devam etmelidir.
class MyActivity : AppCompatActivity() { private var castContext: CastContext? = null private var sessionTransferCallback: SessionTransferCallback? = null protected fun onCreate() { castContext = CastContext.getSharedInstance(this) castContext.getSessionManager() .addSessionManagerListener(sessionManagerListener, CastSession::class.java) sessionTransferCallback = MySessionTransferCallback() castContext.addSessionTransferCallback(sessionTransferCallback) } protected fun onDestroy() { if (castContext != null) { castContext.getSessionManager() .removeSessionManagerListener(sessionManagerListener, CastSession::class.java) if (sessionTransferCallback != null) { castContext.removeSessionTransferCallback(sessionTransferCallback) } } } class MySessionTransferCallback : SessionTransferCallback() { fun onTransferring(@SessionTransferCallback.TransferType transferType: Int) { // Perform necessary steps prior to onTransferred } fun onTransferred(@SessionTransferCallback.TransferType transferType: Int, sessionState: SessionState?) { if (transferType == SessionTransferCallback.TRANSFER_TYPE_FROM_REMOTE_TO_LOCAL) { // Remote stream is transferred to the local device. // Retrieve information from the SessionState to continue playback on the local player. } } fun onTransferFailed(@SessionTransferCallback.TransferType transferType: Int, @SessionTransferCallback.TransferFailedReason transferFailedReason: Int) { // Handle transfer failure. } } }
public class MyActivity extends AppCompatActivity { private CastContext castContext; private SessionTransferCallback sessionTransferCallback; @Override protected void onCreate() { castContext = CastContext.getSharedInstance(this); castContext .getSessionManager() .addSessionManagerListener(sessionManagerListener, CastSession.class); sessionTransferCallback = new MySessionTransferCallback(); castContext.addSessionTransferCallback(sessionTransferCallback); } @Override protected void onDestroy() { if (castContext != null) { castContext .getSessionManager() .removeSessionManagerListener(sessionManagerListener, CastSession.class); if (sessionTransferCallback != null) { castContext.removeSessionTransferCallback(sessionTransferCallback); } } } public static class MySessionTransferCallback extends SessionTransferCallback { public MySessionTransferCallback() {} @Override public void onTransferring(@SessionTransferCallback.TransferType int transferType) { // Perform necessary steps prior to onTransferred } @Override public void onTransferred(@SessionTransferCallback.TransferType int transferType, SessionState sessionState) { if (transferType==SessionTransferCallback.TRANSFER_TYPE_FROM_REMOTE_TO_LOCAL) { // Remote stream is transferred to the local device. // Retrieve information from the SessionState to continue playback on the local player. } } @Override public void onTransferFailed(@SessionTransferCallback.TransferType int transferType, @SessionTransferCallback.TransferFailedReason int transferFailedReason) { // Handle transfer failure. } } }