Çıkış Değiştirici

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

• Yerelden uzaka
• Uzaktan yerele

Sesler uygulamanızda Çıkış Değiştirici'yi nasıl uygulayacağınızla ilgili bilgi edinmek için aşağıdaki örneği indirip kullanın. Örneği nasıl çalıştıracağınıza dair talimatlar için README.md dosyasına göz atın.

Örneği İndirin

Çıkış Değiştirici, bu kılavuzda açıklanan adımlar kullanılarak yerelden uzaka ve uzaktan yerele desteklenecek şekilde etkinleştirilmelidir. Yerel cihaz hoparlörleri ile eşlenen Bluetooth cihazlar arasında 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 for Ses'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ığı bilgisi dahil olmak üzere mevcut cihaz durumunu ve mevcut ses düzeyini gösterir. Geçerli cihaza ek olarak başka cihazlar varsa başka bir cihazı tıklayarak medya oynatmasını seçili cihaza aktarabilirsiniz.

Bilinen sorunlar

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

Giriş noktaları

Medya bildirimi

Bir uygulama, yerel olarak oynatma için (yerel olarak oynatılan) MediaSession ile medya bildirimi yayınlarsa medya bildiriminin sağ üst köşesinde içeriğin oynatıldığı cihaz adını (telefon hoparlörü gibi) içeren bir bildirim çipi gösterilir. Bildirim çipine dokunduğunuzda Çıkış Değiştirici iletişim kutusu kullanıcı arayüzü açılır.

Ses düzeyi ayarları

Ayrıca, Çıkış Değiştirici iletişim sistemi kullanıcı arayüzü, cihazdaki fiziksel ses düğmeleri tıklandığında, alt kısımdaki ayarlar simgesine ve ardından "<Yayın Cihazı> cihazında <Uygulama Adı> oyna" metnine dokunarak da tetiklenebilir.

Adımların özeti

• Ön koşulların yerine getirildiğinden emin olun
• AndroidManifest.xml dosyasında Çıkış Değiştirici'yi etkinleştirme
• Arka planda yayınlama için SessionManagerHearer'ı güncelleme
• setRemoteToLocalEnabled işaretini ayarlama
• Yerel olarak oynatmaya devam edin

Ön koşullar

1. Mevcut Android uygulamanızı AndroidX'e taşıyın.
2. Çıktı Değiştirici için Android Gönderen SDK'sının gerekli minimum sürümünü kullanmak üzere uygulamanızın build.gradle sürümünü güncelleyin:

   dependencies {
     ...
     implementation 'com.google.android.gms:play-services-cast-framework:21.2.0'
     ...
   }

3. Uygulama, medya bildirimlerini destekler.
4. Android 13 çalıştıran cihaz.

Medya Bildirimlerini ayarlama

Çıkış Değiştirici'yi kullanmak için ses ve video uygulamalarının oynatma durumunu ve yerel oynatmaya ilişkin medyalarını kontrol etmek üzere bir medya bildirimi oluşturması gerekir. Bunun için bir MediaSession oluşturmanız, MediaStyle öğesini MediaSession jetonuyla ayarlamanız ve bildirimdeki medya kontrollerini ayarlamanız gerekir.

Şu anda bir MediaStyle ve MediaSession kullanmıyorsanız aşağıdaki snippet'lerin nasıl ayarlanacağı burada açıklanmaktadır ve audio ile video uygulamaları için medya oturumu geri çağırmalarını ayarlama konusunda kılavuzlar 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();
}

Buna ek olarak, 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 sabitlerini MediaMetadataCompat.Builder() içinde 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 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:

• Medya yerel olarak oynatılırken uygulama ön plandayken medya bildirimini yayınlayın.
• Uygulama arka plandayken yerel oynatmayı duraklatın ve bildirimi kapatın.
• Uygulama ön plana geri döndüğünde, yerel oynatma devam ettirilmelidir ve bildirim yeniden yayınlanmalıdır.

AndroidManifest.xml dosyasında Çıkış Değiştirici'yi etkinleştirme

Çı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 işareti de 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 MediaTransferGetr referansına bakın.

Yerelden uzaka

Kullanıcı, oynatma işlemini yerel kanaldan uzaktan kumandaya geçirdiğinde Cast SDK otomatik olarak Cast oturumunu başlatır. Ancak uygulamaların yerelden uzaktan kumandaya geçişi gerçekleştirmesi gerekir. Örneğin, yerel oynatmayı durdurup medyayı Yayın cihazına yükleyin. Uygulamalar, onSessionStarted() ve onSessionEnded() geri çağırmalarını kullanarak Google Cast'i SessionManagerListener dinlemeli ve yayınla ilgili SessionManager geri çağırmalarını alırken işlemi yerine getirmelidir. Uygulamalar, Çıkış Değiştirici iletişim kutusu açıldığında ve uygulama ön plandayken bu geri çağırmaların hâlâ canlı olduğundan emin olmalıdır.

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

Eski yayın deneyimi, uygulama ön plandayken yerelden uzaktan kumandaya zaten destekleniyor. Tipik bir yayınlama deneyimi, kullanıcılar uygulamada yayınla simgesini tıklayıp medya akışı için bir cihaz seçtiklerinde başlar. Bu durumda, uygulamanın SessionManagerListener'e onCreate() veya onStart() üzerinden kaydolup onStop() veya uygulama etkinliğinin onDestroy() üzerinden dinleyicinin kaydını iptal etmesi gerekir.

Çıkış Değiştirici'yi kullanarak yeni bir yayınlama deneyimiyle uygulamalar arka planda çalışırken yayınlamaya başlayabilir. Bu özellik, özellikle arka planda çalarken bildirim yayınlayan ses uygulamaları için yararlıdır. Uygulamalar, SessionManager dinleyicilerini hizmetin onCreate() hizmetinde kaydedebilir ve hizmetin onDestroy() kaydını iptal edebilir. Bu şekilde, uygulamalar arka plandayken her zaman yerelden uzaka geri çağırmaları (onSessionStarted gibi) almalıdır.

Uygulama MediaBrowserService kullanıyorsa SessionManagerListener öğesini burada 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, uygulama arka plandayken yerelden uzaktan kumandaya geleneksel yöntemle aynı şekilde çalışır ve Bluetooth cihazlardan Yayın cihazlarına geçiş için ek işlem yapılması gerekmez.

Uzaktan yerele

Çıkış Değiştirici, uzaktan oynatma özelliğinden telefon hoparlörüne veya yerel Bluetooth cihazına aktarım yapma olanağı sağlar. Bu özellik, CastOptions üzerindeki setRemoteToLocalEnabled işaretinin true olarak ayarlanmasıyla etkinleştirilebilir.

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

setRemoteToLocalEnabled işaretini ayarlayın

CastOptions, aktif bir Yayın oturumu olduğunda telefon hoparlörünü ve yerel Bluetooth cihazları çıkış değiştirici iletişim kutusunda aktarım hedefi 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 yerel modu destekleyen uygulamalar, etkinlik olduğunda bildirim almak için SessionTransferCallback öğesini kaydetmelidir. Böylece, medyanın yerel olarak aktarım ve oynatmaya devam etmesine izin verilip verilmeyeceğini belirleyebilir.

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

Uygulama, SessionTransferCallback kaydının kaydını iptal ettikten sonra SessionTransferCallback öğesini almayacak.

SessionTransferCallback, mevcut SessionManagerListener geri çağırmalarının bir uzantısıdır ve onSessionEnded tetiklendikten sonra tetiklenir. Bu nedenle, uzaktan yerele geri çağırmaların sırası:

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

Çıkış değiştirici, uygulama arka plandayken ve yayınlanırken medya bildirim çipi tarafından açılabileceğinden, uygulamaların arka planda oynatmayı destekleyip desteklemediklerine bağlı olarak yerele aktarımı farklı şekilde ele alması gerekir. Aktarımın başarısız olması durumunda onTransferFailed, hata oluştuğunda etkinleşir.

Arka planda oynatmayı destekleyen uygulamalar

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

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ıdır) uygulama ön plandaysa onTransferred geri çağırmasını dinlemeniz ve yerel olarak oynatmaya devam etmeniz önerilir.

Uygulama arka plandaysa oynatmayı duraklatmalı ve SessionState tarafından sağlanan gerekli bilgileri (ör. medya meta verileri ve oynatma konumu) depolamalıdır. Uygulama ön plana ön plana çıktığında yerel oynatma, saklanan 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.
    }
  }
}