Çıkış Değiştirici

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ım sağlar. Amaç, gönderen uygulamalarının içeriğin oynatıldığı yeri kolay ve hızlı bir şekilde kontrol etmesine yardımcı olmaktır. Çıkış Değiştirici, içerikleri telefon hoparlörü, eşlenen Bluetooth cihazlar ve Cast uyumlu uzak cihazlar arasında değiştirmek için MediaRouter kitaplığını kullanır. Kullanım alanları aşağıdaki senaryolara ayrılabilir:

Ses uygulamanızda Çı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 içindeki README.md dosyasına bakın.

Örneği İndir

Çıkış Değiştirici, bu kılavuzda ele alınan adımlar kullanılarak yerelden uzaktan kumandaya ve uzaktan yerele geçişi destekleyecek şekilde etkinleştirilmelidir. Yerel cihaz hoparlörleri ve eşlenen Bluetooth cihazlar arasındaki aktarımı desteklemek için başka bir işlem yapmanıza gerek yoktur.

Ses uygulamaları, Google Cast SDK'sı Developer Console'daki 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ılabilen yerel ve uzak cihazların yanı sıra cihazın seçili olup olmadığı, bağlandığı ve geçerli ses düzeyi gibi geçerli 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 için MediaSession içeren bir medya bildirimi yayınlarsa (yerel olarak oynatılıyor), medya bildiriminin sağ üst köşesinde içeriğin oynatıldığı cihazın adının (ör. telefon hoparlörü) yer aldığı bir bildirim çipi görüntülenir. Bildirim çipine dokunduğunuzda Çıkış Değiştirici iletişim sisteminin kullanıcı 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ı> üzerinde <Uygulama Adı> oynat" metnine dokunarak da tetikleyebilirsiniz.

Adımların özeti

Ön koşullar

  1. Mevcut Android uygulamanızı AndroidX'e taşıyın.
  2. Uygulamanızın build.gradle politikasını, Çıkış Değiştirici için Android Sender SDK'nın gerekli minimum sürümünü kullanacak şekilde güncelleyin:
    dependencies {
      ...
      implementation 'com.google.android.gms:play-services-cast-framework:21.2.0'
      ...
    }
  3. Uygulama, medya bildirimlerini destekliyor.
  4. Android 13 çalıştıran cihaz.

Medya Bildirimleri'ni ayarlayın

Çıkış Değiştirici'yi kullanmak için ses ve video uygulamalarının, yerel oynatma için medya oynatma durumunu ve kontrollerini gösteren bir 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. Ayrıca, ses ve video uygulamaları için medya oturumu geri çağırmalarını ayarlamayla ilgili kılavuzlara da ulaşabilirsiniz:

Kotlin
// 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)
Java
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ızın bilgileriyle doldurmak için medyanızın meta verilerini ve oynatma durumunu MediaSession öğesine eklemeniz gerekir.

MediaSession öğesine meta veri eklemek için setMetaData() kullanın ve MediaMetadataCompat.Builder() içindeki medyanızla ilgili tüm MediaMetadata sabit değerlerini sağlayın.

Kotlin
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()
)
Java
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.

Kotlin
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()
)
Java
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 uygulamaları veya ses uygulamaları, oynatmanın desteklenmediği durumlarda medya komutu göndermeyle ilgili sorunları önlemek için medya bildirimlerinde belirli bir davranışa sahip olmalıdır:

  • Yerel olarak medya oynatırken uygulama ön plandayken medya bildirimini yayınlayın.
  • Yerel oynatmayı duraklatın ve uygulama arka plandayken bildirimi kapatın.
  • Uygulama ön plana geri döndüğünde 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 öğesine eklenmelidir. Aksi takdirde, özellik etkinleştirilmez ve uzaktan yerele özellik bayrağı geçersiz olur.

<application>
    ...
    <receiver
         android:name="androidx.mediarouter.media.MediaTransferReceiver"
         android:exported="true">
    </receiver>
    ...
</application>

MediaTransferReceiver, sistem kullanıcı arayüzü olan cihazlar arasında medya aktarımı sağlayan bir yayın alıcısıdır. Daha fazla bilgi için MediaTransferRecipientr referansına bakın.

Yerelden Uzaktan Kumandaya

Kullanıcı, oynatmayı yerel cihazdan uzaklığa geçirdiğinde Cast SDK'sı otomatik olarak Yayınlama oturumunu başlatır. Ancak uygulamaların yerelden uzaklığa geçiş gerçekleştirmesi gerekir. Örneğin, yerel oynatmayı durdurabilir ve medyayı Cast cihazına yükleyebilirsiniz. Uygulamalar onSessionStarted() ve onSessionEnded() geri çağırmalarını kullanarak Cast'i SessionManagerListener dinlemeli ve Cast SessionManager geri aramalarını aldığında işlemi gerçekleştirmelidir. Uygulamalar, Çıktı 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ın için SessionManagerListener'ı güncelleme

Eski Cast deneyimi, uygulama ön plandayken yerelden uzaktan kumandaya geçişi zaten desteklemektedir. Tipik bir Cast deneyimi, kullanıcılar uygulamadaki Yayınla simgesini tıklayıp medya akışı gerçekleştirecek bir cihaz seçtiğinde başlar. Bu durumda, uygulamanın onCreate() veya onStart() bölgesinde SessionManagerListener'e kaydolması ve onStop() ya da onDestroy() uygulama etkinliğindeki dinleyici kaydını silmesi gerekir.

Çıkış Değiştirici'yi kullanarak yeni yayınlama deneyimi sayesinde, uygulamalar arka planda yayın yapmaya başlayabilir. Bu özellikle arka planda çalarken bildirim yayınlayan sesli 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 yerel-uzaktan geri çağırmaları (onSessionStarted gibi) almalıdır.

Uygulama MediaBrowserService kullanıyorsa SessionManagerListener öğesini oraya kaydetmeniz önerilir.

Kotlin
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)
        }
    }
}
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 uygulama arka plandayken geleneksel yayınla 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 yapabilme olanağı sağlar. Bu özellik, CastOptions üzerinde setRemoteToLocalEnabled işaretini true olarak ayarlayarak etkinleştirilebilir.

Gönderen cihazın mevcut bir oturuma birden fazla gönderenle katıldığı ve uygulamanın mevcut medyanın yerel olarak aktarılmasına izin verilip verilmediğini kontrol etmesi gerektiği durumlarda, uygulamalar SessionState öğesini kontrol etmek için SessionTransferCallback onTransferred geri çağırma işlevini kullanmalıdır.

setRemoteToLocalEnabled işaretini ayarlayın

CastOptions, etkin bir Cast oturumu olduğunda Çıkış 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.

Kotlin
class CastOptionsProvider : OptionsProvider {
    fun getCastOptions(context: Context?): CastOptions {
        ...
        return Builder()
            ...
            .setRemoteToLocalEnabled(true)
            .build()
    }
}
Java
public class CastOptionsProvider implements OptionsProvider {
    @Override
    public CastOptions getCastOptions(Context context) {
        ...
        return new CastOptions.Builder()
            ...
            .setRemoteToLocalEnabled(true)
            .build()
  }
}

Oynatmaya yerel olarak devam et

Uzaktan yerele geçişi destekleyen uygulamalar etkinlik gerçekleştiğinde bildirim almak için SessionTransferCallback özelliğini kaydetmelidir. Böylece, medyanın yerel olarak aktarılmasına ve oynatmaya devam etmesine izin verilip verilmeyeceğini kontrol edebilirler.

CastContext#addSessionTransferCallback(SessionTransferCallback), bir gönderen yerel oynatmaya aktarıldığında bir uygulamanın SessionTransferCallback bilgisini kaydetmesine ve onTransferred ile onTransferFailed geri çağırmalarını dinlemesine izin verir.

Uygulama, SessionTransferCallback kaydını sildikten 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:

  1. onTransferring
  2. onSessionEnding
  3. onSessionEnded
  4. onTransferred

Çıkış Değiştirici, uygulama arka plandayken ve yayın yaparken 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 her meydana geldiğinde onTransferFailed etkinleşir.

Arka planda oynatmayı destekleyen uygulamalar

Arka planda oynatmayı destekleyen uygulamalarda (genellikle sesli uygulamalar) bir Service (örneğin, MediaBrowserService) kullanılması önerilir. Hizmetler, hem uygulama ön plandayken hem de arka plandayken onTransferred geri çağırmayı dinlemeli ve oynatmayı yerel olarak devam ettirmelidir.

Kotlin
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.
        }
    }
}
Java
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 plandayken oynatmayı yerel olarak devam ettirmeniz önerilir.

Uygulama arka plandaysa oynatmayı duraklatmalı ve gerekli bilgileri SessionState kaynağından (ör. medya meta verileri ve oynatma konumu) depolamalıdır. Uygulama arka planda ön planda olduğunda yerel oynatma depolanan bilgilerle devam etmelidir.

Kotlin
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.
        }
    }
}
Java
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.
    }
  }
}