Çıkış Değiştirici

Çıkış Değiştirici, Android 13'ten itibaren içeriklerin yerel ve uzaktan oynatma arasında sorunsuz şekilde aktarım yapmasını sağlayan bir Cast SDK özelliğidir. Amaç, gönderen uygulamalarının içeriğin nerede oynatıldığını kolay ve hızlı bir şekilde kontrol etmesine yardımcı olmaktır. Çıkış Değiştirici; telefon hoparlörü, eşlenen Bluetooth cihazlar ve Cast uyumlu uzak cihazlar arasında içerik oynatma işlemini değiştirmek için MediaRouter kitaplığını kullanır. Kullanım alanları aşağıdaki senaryolara ayrılabilir:

Çıkış Değiştirici'yi Ses uygulamanızda nasıl uygulayacağınıza ilişkin referans için aşağıdaki örneği indirip kullanın. Örneği çalıştırmaya ilişkin talimatlar için verilen README.md dosyasını inceleyin.

Örneği İndir

Bu kılavuzdaki adımlar kullanılarak yerelden uzaktan yerele ve uzaktan yerele geçiş işlemlerini desteklemek için Çıkış Değiştirici etkinleştirilmelidir. Yerel cihaz hoparlörleri ile eşlenen Bluetooth cihazlar arasındaki aktarımı desteklemek için ek bir işlem yapmanıza gerek yoktur.

Ses uygulamaları, Google Cast SDK Geliştirici Konsolu'ndaki Alıcı Uygulama ayarlarında 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ığı ve bağlanıp bağlanmadığı dahil mevcut cihaz durumlarını da gösterir. Geçerli cihaza ek olarak başka cihazlar varsa diğer cihazı tıklayarak medya oynatmasını seçili cihaza aktarabilirsiniz.

Bilinen sorunlar

  • Yerel oynatma için oluşturulan Medya Oturumları, Cast SDK'sı bildirimine geçildiğinde kapatılır ve yeniden oluşturulur.

Giriş noktaları

Medya bildirimi

Bir uygulama, yerel oynatma için (yerel olarak oynatma) MediaSession ile medya bildirimi yayınlarsa medya bildiriminin sağ üst köşesinde, içeriğin oynatılmakta olduğu cihaz 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ı

Ayrıca, Çıkış Değiştirici iletişim kutusunun sistem kullanıcı arayüzü, cihazdaki fiziksel ses düğmeleri tıklanıp alttaki ayarlar simgesine, ardından "<Yayın Cihazı>"nda <Uygulama Adı> Oynat" metnine dokunarak da tetiklenebilir.

Adımların özeti

Ön koşullar

  1. Mevcut Android uygulamanızı AndroidX'e taşıyın.
  2. Uygulamanızın build.gradle öğesini, Çıktı Değiştirici için Android Sender SDK'nın gerekli en düşük 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 oynatma durumunu ve yerel oynatma için medya 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 bir MediaStyle ve MediaSession kullanmıyorsanız aşağıdaki snippet'te bunların nasıl ayarlanacağı gösterilir ve ses ve video uygulamaları için medya oturumu geri çağırmalarının ayarlanmasıyla ilgili kılavuzlar mevcuttur:

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ızla ilgili bilgilerle 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 medyanızla ilgili tüm MediaMetadata sabit değerlerini MediaMetadataCompat.Builder() içinde 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() öğesini kullanın ve medyanızla alakalı 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 komutları göndermeyle ilgili sorunları önlemek için medya bildirimlerine özel davranışlara 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ınlanmalıdır.

AndroidManifest.xml dosyasında Çıkış Değiştiriciyi etkinleştir

Çıkış Değiştirici'yi etkinleştirmek için MediaTransferReceiver öğesinin uygulamanın AndroidManifest.xml öğesine eklenmesi gerekir. Etkin değilse özellik etkinleştirilmez ve uzaktan yerele özellik bayrağı da geçersiz olur.

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

MediaTransferReceiver, sistem kullanıcı arayüzüne sahip cihazlar arasında medya aktarımını sağlayan bir yayın alıcıdır. Daha fazla bilgi için MediaTransferReceiver referansı bölümüne bakın.

Yerelden Uzaktan Kumandaya

Kullanıcı, oynatma işlemini yerel moddan uzaktan gerçekleştirdiğinde Cast SDK'sı yayınlama oturumunu otomatik olarak başlatır. Bununla birlikte, uygulamaların yerelden uzaktan kumandaya geçiş yapması gerekir. Örneğin, yerel oynatmayı durdurup medyayı yayın cihazına yükleyebilirsiniz. Uygulamalar onSessionStarted() ve onSessionEnded() geri çağırmalarını kullanarak Cast SessionManagerListener'ı dinlemeli ve Cast SessionManager geri çağırmaları geldiğinde işlemi gerçekleştirmelidir. Uygulamalar, Çıkış Değiştirici iletişim kutusu açıldığında ve uygulama ön planda değilken geri çağırmaların hâlâ etkin olduğundan emin olmalıdır.

Arka planda yayınlama için SessionManagerListener'ı güncelleme

Uygulama ön plandayken eski Cast deneyimi yerelden uzaktan kumandaya erişimi zaten desteklemektedir. Tipik bir Cast deneyimi, kullanıcılar uygulamadaki Yayınla simgesini tıkladığında ve medya akışı gerçekleştirmek üzere bir cihaz seçtiğinde başlar. Bu durumda, uygulamanın onCreate() veya onStart() ürününde SessionManagerListener'e kaydolması ve onStop() veya onDestroy() uygulama etkinliğindeki işleyicinin 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 özellikle arka planda oynatırken bildirim yayınlayan sesli uygulamalar için yararlıdır. Uygulamalar SessionManager işleyicilerini hizmetin onCreate() hizmetine kaydedebilir ve hizmetin onDestroy() uygulamasındaki kaydını iptal edebilir. Böylece uygulamalar arka plandayken her zaman yerelden uzaktan geri çağırma (onSessionStarted gibi) almalıdır.

Uygulama MediaBrowserService kullanıyorsa SessionManagerListener öğesini orada 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, uygulama arka plandayken yerelten uzaktan kumandaya geleneksel yayınlama işleviyle aynı şekilde çalışır ve Bluetooth cihazlardan yayın cihazlarına geçiş yapmak için ek bir çalışma gerekmez.

Uzaktan yerele

Çıkış Değiştirici, uzaktan oynatmadan telefonun hoparlörüne veya yerel Bluetooth cihazına aktarım yapabilmenizi sağlar. Bu, CastOptions üzerinde setRemoteToLocalEnabled işareti true olarak ayarlanarak etkinleştirilebilir.

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

setRemoteToLocalEnabled işaretini ayarlama

CastOptions, etkin bir Cast oturumu olduğunda telefonun hoparlörünü ve yerel Bluetooth cihazlarını Çıktı Değiştirici iletişim kutusunda hedef 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ş özelliğini destekleyen uygulamalar, etkinlik gerçekleştiğinde bildirim almak ve böylece medyanın aktarılmasına izin verilip verilmeyeceğini kontrol edip yerel olarak oynatmaya devam etmek için SessionTransferCallback öğesini kaydetmelidir.

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

Uygulama, SessionTransferCallback kaydının kaydını iptal ettikten sonra artık SessionTransferCallback almaz.

SessionTransferCallback, mevcut SessionManagerListener geri çağırmalarının bir uzantısıdır ve onSessionEnded tetiklendikten sonra tetiklenir. Bu nedenle, uzaktan bölgeye geri aramaların sırası şu şekildedir:

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

Çıkış Değiştirici, uygulama arka planda ve yayındayken medya bildirim çipiyle açılabileceğinden, uygulamaların arka planda oynatmayı destekleyip desteklemediklerine bağlı olarak yerel bölgeye aktarımı farklı şekilde gerçekleştirmesi gerekir. Aktarımın başarısız olması durumunda onTransferFailed, her hata meydana geldiğinde etkinleşir.

Arka planda oynatmayı destekleyen uygulamalar

Arka planda oynatmayı destekleyen uygulamalar (genellikle ses uygulamaları) için Service (örneğin, MediaBrowserService) kullanılması önerilir. Hizmetler, onTransferred geri çağırmasını dinlemeli ve hem uygulama ön planda hem de arka plandayken oynatmaya yerel olarak devam etmelidir.

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 uygulamalar için (genellikle video uygulamaları) uygulama ön plandaysa onTransferred geri çağırmasının dinlenmesi ve oynatmaya yerel olarak devam ettirilmesi önerilir.

Uygulama arka plandaysa oynatmayı durdurmalı ve SessionState kaynağından gerekli bilgileri (ör. medya meta verileri ve oynatma konumu) depolamalıdır. Uygulama arka planda ön plana alındığında yerel oynatma saklanan 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.
    }
  }
}