Przełącznik wyjścia

Przełącznik wyjścia to funkcja pakietu SDK Cast, która umożliwia płynne przenoszenie treści między odtwarzaniem lokalnym i zdalnym, począwszy od Androida 13. Ma to pomóc aplikacjom nadawcy łatwo i szybko kontrolować miejsce odtwarzania treści. Przełącznik wyjścia korzysta z biblioteki MediaRouter do przełączania odtwarzania treści między głośnikiem telefonu, sparowanymi urządzeniami Bluetooth i zdalnymi urządzeniami obsługującymi Cast. Przypadki użycia można podzielić na następujące scenariusze:

Pobierz ten przykładowy kod i wykorzystaj go, aby dowiedzieć się, jak wdrożyć przełącznik wyjścia w aplikacji audio. Instrukcje uruchamiania tego fragmentu znajdziesz w dołączonym pliku README.md.

Pobierz przykładowy kod

Przełącznik wyjścia powinien być włączony, by obsługiwać połączenia lokalne-zdalne i zdalne do lokalnego, korzystając z czynności opisanych w tym przewodniku. Nie musisz wykonywać żadnych dodatkowych czynności, aby przenieść urządzenie między lokalnymi głośnikami urządzenia a sparowanymi urządzeniami Bluetooth.

Aplikacje audio to aplikacje obsługujące Google Cast for Audio w ustawieniach aplikacji odbiornika w konsoli programisty pakietu Google Cast SDK

Interfejs przełącznika wyjścia

Przełącznik wyjścia wyświetla dostępne urządzenia lokalne i zdalne, a także aktualne stany urządzeń, w tym to, czy jest ono wybrane, czy jest podłączone, oraz aktualny poziom głośności. Jeśli oprócz bieżącego urządzenia istnieją jeszcze inne urządzenia, kliknięcie tego urządzenia umożliwia przeniesienie na nie odtwarzania multimediów.

Znane problemy

  • Sesje multimedialne utworzone na potrzeby odtwarzania lokalnego zostaną odrzucone i utworzone ponownie, gdy przełączysz się na powiadomienie z pakietu Cast SDK.

Punkty wejścia

Powiadomienie o multimediach

Jeśli aplikacja opublikuje powiadomienie o multimediach z oznaczeniem MediaSession, aby umożliwić odtwarzanie lokalne (odtwarzanie lokalne), w prawym górnym rogu powiadomienia o multimediach będzie widoczny element powiadomienia z nazwą urządzenia (np. głośnika telefonu), na którym jest obecnie odtwarzana dana treść. Kliknięcie elementu powiadomienia otwiera interfejs systemu okna przełączania wyjścia.

Ustawienia głośności

Interfejs systemu okna przełączania wyjścia można też aktywować, klikając przyciski głośności fizycznej na urządzeniu, a następnie klikając ikonę ustawień na dole i tekst „Odtwórz <nazwa aplikacji> na <Urządzenie przesyłające>”.

Podsumowanie kroków

Wymagania wstępne

  1. Przeprowadź migrację istniejącej aplikacji na Androida na AndroidaX.
  2. Zaktualizuj build.gradle w swojej aplikacji, aby używała minimalnej wersji pakietu Android Sender SDK na potrzeby przełącznika wyjścia:
    dependencies {
      ...
      implementation 'com.google.android.gms:play-services-cast-framework:21.2.0'
      ...
    }
  3. Aplikacja obsługuje powiadomienia o multimediach.
  4. Urządzenie z Androidem 13.

Skonfiguruj powiadomienia o multimediach

Aby można było używać przełącznika wyjścia, aplikacje audio i wideo muszą utworzyć powiadomienia o multimediach, które będą wyświetlać stan i elementy sterujące ich odtwarzaniem do lokalnego odtwarzania. Wymaga to utworzenia MediaSession, ustawienia MediaStyle za pomocą tokena MediaSession oraz ustawienia opcji sterowania multimediami w powiadomieniu.

Jeśli nie używasz obecnie wywołań MediaStyle ani MediaSession, z poniższego fragmentu dowiesz się, jak je skonfigurować. Dostępne są też przewodniki dotyczące konfigurowania wywołań zwrotnych sesji multimediów w przypadku aplikacji audio i wideo:

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();
}

Dodatkowo, aby podać w powiadomieniu informacje o multimediach, musisz dodać do obiektu MediaSession metadane i stan odtwarzania multimediów.

Aby dodać metadane do obiektu MediaSession, użyj setMetaData() i podaj w MediaMetadataCompat.Builder() wszystkie istotne stałe MediaMetadata dla Twoich multimediów.

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()
    );
}

Aby dodać stan odtwarzania do MediaSession, użyj setPlaybackState() i podaj w PlaybackStateCompat.Builder() wszystkie odpowiednie stałe PlaybackStateCompat dla multimediów.

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()
    );
}

Zachowanie powiadomień z aplikacji wideo

Aplikacje wideo lub audio, które nie obsługują lokalnego odtwarzania w tle, powinny działać w określony sposób w odniesieniu do powiadomień multimedialnych, aby uniknąć problemów z wysyłaniem poleceń multimedialnych w sytuacjach, gdy odtwarzanie nie jest obsługiwane:

  • Publikuj powiadomienie o multimediach podczas lokalnego odtwarzania, gdy aplikacja działa na pierwszym planie.
  • Wstrzymaj odtwarzanie lokalne i zamknij powiadomienie, gdy aplikacja działa w tle.
  • Gdy aplikacja wróci na pierwszy plan, odtwarzanie lokalne powinno zostać wznowione i ponownie opublikowane.

Włącz przełącznik danych wyjściowych w pliku AndroidManifest.xml

Aby włączyć przełącznik wyjścia, musisz dodać MediaTransferReceiver do funkcji AndroidManifest.xml aplikacji. W przeciwnym razie funkcja nie zostanie włączona, a flaga funkcji „zdalnie do lokalnego” także będzie nieprawidłowa.

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

MediaTransferReceiver to odbiornik, który umożliwia przesyłanie multimediów między urządzeniami z systemowym interfejsem. Więcej informacji znajdziesz w dokumentacji MediaTransferReceiver.

Z komputera na zdalny

Gdy użytkownik przełączy odtwarzanie z lokalnego na zdalne, pakiet Cast SDK automatycznie rozpocznie sesję przesyłania. Aplikacje muszą jednak obsługiwać przełączanie się z lokalnego na zdalne, np. zatrzymywać lokalne odtwarzanie i wczytywać multimedia na urządzeniu przesyłającym. Aplikacje powinny nasłuchiwać wywołań przesyłania SessionManagerListener za pomocą wywołań zwrotnych onSessionStarted() i onSessionEnded() oraz wykonywać działanie przy odbieraniu wywołań zwrotnych SessionManager Cast. Aplikacje powinny pilnować, aby wywołania zwrotne były nadal aktywne, gdy jest otwarte okno przełączania danych wyjściowych, a aplikacja nie jest na pierwszym planie.

Zaktualizuj SessionManagerListener do przesyłania w tle

Starsza wersja Cast obsługuje już połączenie lokalne do zdalnego, gdy aplikacja działa na pierwszym planie. Przesyłanie rozpoczyna się zwykle, gdy użytkownik kliknie ikonę Cast w aplikacji i wybierze urządzenie, na którym będzie przesyłać multimedia. W takim przypadku aplikacja musi zarejestrować się w SessionManagerListener, onCreate() lub onStart() i wyrejestrować detektor w onStop() lub onDestroy() aktywności aplikacji.

Nowa funkcja przesyłania za pomocą przełącznika wyjścia pozwala na przesyłanie aplikacji, które działają w tle. Jest to szczególnie przydatne w przypadku aplikacji dźwiękowych, które publikują powiadomienia podczas odtwarzania w tle. Aplikacje mogą zarejestrować detektory SessionManager w onCreate() usługi i wyrejestrować się w onDestroy() usługi. Dzięki temu aplikacje powinny zawsze otrzymywać wywołania zwrotne do serwera lokalnego (np. onSessionStarted), gdy działają w tle.

Jeśli aplikacja używa MediaBrowserService, zalecamy zarejestrowanie tam SessionManagerListener.

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);
    }
  }
}

Po tej aktualizacji połączenie lokalne do zdalnego działania działa tak samo jak tradycyjne przesyłanie, gdy aplikacja działa w tle. Nie trzeba przy tym wykonywać dodatkowych czynności przy przechodzeniu z urządzeń Bluetooth na urządzenia przesyłające.

Zdalnie do lokalnego

Przełącznik wyjścia umożliwia przełączanie sygnału odtwarzania ze zdalnego odtwarzania na głośnik telefonu lub lokalne urządzenie Bluetooth. Aby to zrobić, ustaw flagę setRemoteToLocalEnabled na true w: CastOptions.

W sytuacjach, gdy urządzenie, z którego obecnie jest wysyłane, dołącza do istniejącej sesji z wieloma nadawcami, a aplikacja musi sprawdzić, czy bieżące multimedia mogą być przesyłane lokalnie, aplikacje powinny użyć wywołania zwrotnego onTransferred z SessionTransferCallback, aby sprawdzić SessionState.

Ustawianie flagi setRemoteToLocalEnabled

CastOptions udostępnia przycisk setRemoteToLocalEnabled pozwalający wyświetlić lub ukryć głośnik telefonu i lokalne urządzenia Bluetooth jako cele przekazywania do celu w oknie przełącznika wyjścia, gdy aktywna jest sesja przesyłania.

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()
  }
}

Kontynuuj odtwarzanie lokalnie

Aplikacje obsługujące połączenie zdalne do lokalnego powinny zarejestrować SessionTransferCallback, aby otrzymywać powiadomienia o wystąpieniu zdarzenia i sprawdzić, czy należy zezwolić na przeniesienie multimediów i kontynuować odtwarzanie lokalnie.

Funkcja CastContext#addSessionTransferCallback(SessionTransferCallback) umożliwia aplikacji zarejestrowanie swojego identyfikatora SessionTransferCallback i nasłuchiwanie wywołań zwrotnych onTransferred oraz onTransferFailed, gdy nadawca zostanie przeniesiony do odtwarzania lokalnego.

Gdy aplikacja wyrejestruje swoje elementy SessionTransferCallback, nie będzie już otrzymywać SessionTransferCallbacks.

Obiekt SessionTransferCallback jest rozszerzeniem istniejących wywołań zwrotnych SessionManagerListener i jest aktywowany po wywołaniu funkcji onSessionEnded. W związku z tym kolejność wywołań zwrotnych zdalnie do lokalnego wygląda tak:

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

Ponieważ przełącznik wyjścia można otwierać za pomocą ikony powiadomień o multimediach, gdy aplikacja działa w tle i przesyła treści, aplikacje muszą inaczej obsługiwać przesyłanie danych na format lokalny w zależności od tego, czy obsługują odtwarzanie w tle, czy nie. W przypadku niepowodzenia transferu onTransferFailed uruchamia się za każdym razem, gdy wystąpi błąd.

Aplikacje obsługujące odtwarzanie w tle

W przypadku aplikacji, które obsługują odtwarzanie w tle (zwykle aplikacji audio), zaleca się użycie funkcji Service (np. MediaBrowserService). Usługi powinny nasłuchiwać wywołania zwrotnego onTransferred i wznawiać odtwarzanie lokalnie zarówno wtedy, gdy aplikacja działa na pierwszym planie, jak i w tle.

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

Aplikacje, które nie obsługują odtwarzania w tle

W przypadku aplikacji, które nie obsługują odtwarzania w tle (zwykle aplikacji wideo), zalecamy nasłuchiwanie wywołania zwrotnego onTransferred i wznawianie lokalnie, jeśli aplikacja działa na pierwszym planie.

Jeśli aplikacja działa w tle, powinna wstrzymać odtwarzanie i zapisać niezbędne informacje z SessionState (np. metadane multimediów i pozycję odtwarzania). Gdy aplikacja działa na pierwszym planie w tle, odtwarzanie lokalne powinno być kontynuowane z zapisanymi informacjami.

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