Seletor de saída

O seletor de saída é um recurso do SDK do Cast que permite a transferência perfeita entre a reprodução local e remota de conteúdo no Android 13 e versões mais recentes. O objetivo é ajudar os apps remetentes a controlar com facilidade e rapidez onde o conteúdo é reproduzido. O seletor de saída usa a biblioteca MediaRouter para alternar a reprodução de conteúdo entre o alto-falante do smartphone, dispositivos Bluetooth pareados e dispositivos remotos compatíveis com Cast. Os casos de uso podem ser divididos nos seguintes cenários:

• Local para remoto
• Remoto para local

Faça o download e use a amostra abaixo como referência sobre como implementar o Output Switcher no seu app de áudio. Consulte o README.md incluído para instruções sobre como executar a amostra.

Fazer o download da amostra

Termo-chave :neste guia, o termo local refere-se a qualquer dispositivo móvel ou Bluetooth pareado (como smartphones e tablets) em que o app está sendo iniciado, e o termo remoto refere-se a qualquer dispositivo compatível com Cast.

O switch de saída precisa ser ativado para oferecer suporte de local para remoto e de remoto para local usando as etapas abordadas neste guia. Não há outras etapas necessárias para oferecer suporte à transferência entre os alto-falantes do dispositivo local e dispositivos Bluetooth pareados.

Apps de áudio são apps compatíveis com o Google Cast para áudio nas configurações do app receptor no Console para desenvolvedores do SDK do Google Cast.

interface do seletor de saída

O seletor de saída mostra os dispositivos locais e remotos disponíveis, bem como os estados atuais do dispositivo, incluindo o nível de volume atual, se ele estiver se conectando. Se houver outros dispositivos além do atual, clicar em outro dispositivo permitirá transferir a reprodução de mídia para o dispositivo selecionado.

Problemas conhecidos

• As sessões de mídia criadas para reprodução local serão dispensadas e recriadas ao alternar para a notificação do SDK do Cast.

Pontos de entrada

Notificação de mídia

Se um app postar uma notificação de mídia com MediaSession para reprodução local (reproduzindo localmente), o canto superior direito da notificação exibirá um ícone de notificação com o nome do dispositivo (como alto-falante do smartphone) em que o conteúdo está sendo reproduzido. Tocar no ícone de notificação abre a interface do sistema da caixa de diálogo do seletor de saída.

Configurações de volume

A interface do sistema da caixa de diálogo do seletor de saída também pode ser acionada clicando nos botões de volume físico no dispositivo, tocando no ícone de configurações na parte de baixo e no texto "Reproduzir <nome do app> no <dispositivo de transmissão>".

Resumo das etapas

• Verificar se os pré-requisitos foram atendidos
• Ativar o seletor de saída no AndroidManifest.xml
• Atualizar o SessionManagerListener para transmissão em segundo plano
• Definir a flag setRemoteToLocalEnabled
• Continuar a reprodução localmente

Pré-requisitos

1. Migre seu app Android para o AndroidX.
2. Atualize o build.gradle do app para usar a versão mínima necessária do SDK do Android Sender para o seletor de saída:

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

3. O app oferece suporte a notificações de mídia.
4. Dispositivo com o Android 13.

Configurar notificações de mídia

Para usar o seletor de saída, os apps de áudio e vídeo precisam criar uma notificação de mídia para mostrar o status e os controles da mídia para reprodução local. Para isso, é necessário criar um MediaSession, configurar o MediaStyle com o token do MediaSession e definir os controles de mídia na notificação.

Se você não estiver usando MediaStyle e MediaSession, o snippet abaixo mostra como configurá-los, e há guias disponíveis para configurar os callbacks de sessão de mídia para apps de áudio e vídeo:

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

Além disso, para preencher a notificação com as informações da sua mídia, será necessário adicionar os metadados e o estado da reprodução da mídia ao MediaSession.

Para adicionar metadados ao MediaSession, use setMetaData() e forneça todas as constantes MediaMetadata relevantes para a mídia no MediaMetadataCompat.Builder().

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

Para adicionar o estado de reprodução à MediaSession, use setPlaybackState() e forneça todas as constantes PlaybackStateCompat relevantes para sua mídia no PlaybackStateCompat.Builder().

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

Comportamento de notificação de app de vídeo

Apps de vídeo ou áudio que não oferecem suporte à reprodução local em segundo plano precisam ter um comportamento específico de notificações de mídia para evitar problemas com o envio de comandos de mídia em situações em que a reprodução não tem suporte:

• Poste a notificação de mídia quando a mídia estiver aberta localmente e o app estiver em primeiro plano.
• Pause a reprodução local e dispense a notificação quando o app estiver em segundo plano.
• Quando o app voltar para o primeiro plano, a reprodução local será retomada e a notificação será postada de novo.

Ativar o seletor de saída no AndroidManifest.xml

Para ativar o seletor de saída, o MediaTransferReceiver precisa ser adicionado ao AndroidManifest.xml do app. Caso contrário, o recurso não será ativado e a sinalização de recurso remoto para local também será inválida.

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

O MediaTransferReceiver é um broadcast receiver que permite a transferência de mídia entre dispositivos com a interface do sistema. Consulte a referência MediaTransferReceiver para saber mais.

Local para remoto

Quando o usuário alterna a reprodução do local para o remoto, o SDK do Cast inicia a sessão do Cast automaticamente. No entanto, os apps precisam processar a mudança do local para o remoto, por exemplo, interromper a reprodução local e carregar a mídia no dispositivo de transmissão. Os apps precisam ouvir os callbacks de transmissão SessionManagerListener usando os callbacks onSessionStarted() e onSessionEnded() e processar a ação ao receber os callbacks de transmissão SessionManager. Os apps precisam garantir que esses callbacks ainda estejam ativos quando a caixa de diálogo do seletor de saída estiver aberta e o app não estiver em primeiro plano.

Atualizar o SessionManagerListener para transmissão em segundo plano

Cuidado: devido ao ciclo de vida das atividades, recomendamos que os apps com suporte à reprodução em segundo plano (apps de áudio) usem um serviço em vez de uma atividade para callbacks de SessionManagerListener para evitar que os callbacks necessários sejam cancelados quando uma atividade for interrompida.

A experiência legada do Cast já oferece suporte do local para o remoto quando o app está em primeiro plano. Uma experiência típica do Google Cast começa quando os usuários clicam no ícone do Google Cast no app e escolhem um dispositivo para fazer streaming de mídia. Nesse caso, o app precisa se registrar no SessionManagerListener em onCreate() ou onStart() e cancelar o registro do listener em onStop() ou onDestroy() da atividade do app.

Com a nova experiência de transmissão usando o seletor de saída, os apps podem começar a transmitir quando estiverem em segundo plano. Isso é particularmente útil para apps de áudio que publicam notificações quando são reproduzidos em segundo plano. Os apps podem registrar os listeners SessionManager no onCreate() do serviço e cancelar o registro no onDestroy() do serviço. Dessa forma, os apps sempre precisam receber os callbacks local-remoto (como onSessionStarted) quando o app está em segundo plano.

Se o app usa o MediaBrowserService, é recomendável registrar o SessionManagerListener nele.

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

Com essa atualização, o modo local para remoto funciona da mesma forma que a transmissão tradicional quando o app está em segundo plano e não é necessário trabalho extra para alternar de dispositivos Bluetooth para dispositivos de transmissão.

Observação: para garantir uma transição tranquila do local para o remoto, é recomendável interromper a reprodução no dispositivo local durante o callback onSessionStarted, depois que o SDK do Cast se conecta ao receptor. Isso garante que a reprodução local seja interrompida somente depois que a reprodução for retomada no dispositivo remoto e tiver problemas de tempo devido à latência.

Remoto para local

O seletor de saída oferece a capacidade de transferir da reprodução remota para o alto-falante do smartphone ou para o dispositivo Bluetooth local. Isso pode ser ativado ao definir a flag setRemoteToLocalEnabled como true no CastOptions.

Nos casos em que o dispositivo remetente atual entra em uma sessão com vários remetentes e o app precisa verificar se a mídia atual pode ser transferida localmente, os apps precisam usar o callback onTransferred do SessionTransferCallback para verificar o SessionState.

Definir a flag setRemoteToLocalEnabled

O CastOptions fornece um setRemoteToLocalEnabled para mostrar ou ocultar o alto-falante do smartphone e os dispositivos Bluetooth locais como destinos de transferência para destinos na caixa de diálogo do seletor de saída quando há uma sessão ativa de transmissão.

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

Continuar a reprodução localmente

Os apps compatíveis com o recurso remoto para local precisam registrar o SessionTransferCallback para receber uma notificação quando o evento ocorrer. Assim, eles podem verificar se a mídia tem permissão para transferir e continuar a reprodução localmente.

O CastContext#addSessionTransferCallback(SessionTransferCallback) permite que um app registre o SessionTransferCallback e detecte callbacks onTransferred e onTransferFailed quando um remetente é transferido para a reprodução local.

Depois que o app cancelar o registro do SessionTransferCallback, ele não receberá mais SessionTransferCallbacks.

O SessionTransferCallback é uma extensão dos callbacks de SessionManagerListener atuais e é acionado depois que onSessionEnded é acionado. Portanto, a ordem dos callbacks remotos para o local é:

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

Como o seletor de saída pode ser aberto pelo ícone de notificação de mídia quando o app está em segundo plano e transmitindo, os apps precisam processar a transferência para o local de forma diferente, dependendo se oferecem suporte à reprodução em segundo plano ou não. No caso de uma falha na transferência, onTransferFailed será disparado sempre que o erro ocorrer.

Apps compatíveis com a reprodução em segundo plano

Para apps compatíveis com a reprodução em segundo plano, normalmente de áudio, é recomendável usar um Service (por exemplo, MediaBrowserService). Os serviços precisam ouvir o callback onTransferred e retomar a reprodução localmente quando o app estiver em primeiro ou segundo plano.

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

Apps que não são compatíveis com a reprodução em segundo plano

Para apps que não oferecem suporte à reprodução em segundo plano (geralmente apps de vídeo), é recomendável detectar o callback onTransferred e retomar a reprodução localmente se o app estiver em primeiro plano.

Se o app estiver em segundo plano, ele precisará pausar a reprodução e armazenar as informações necessárias de SessionState (por exemplo, metadados de mídia e posição da reprodução). Quando o app está em primeiro plano em segundo plano, a reprodução local precisa continuar com as informações armazenadas.

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