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 a partir do Android 13. O objetivo
é ajudar os apps de transmissão 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, os dispositivos Bluetooth pareados
e os dispositivos remotos compatíveis com Cast. Os casos de uso podem ser divididos nos seguintes
cenários:
Faça o download e use o exemplo abaixo como referência sobre como implementar o Output Switcher no seu app de áudio. Consulte o README.md incluído para ver instruções sobre como executar a amostra.
O seletor de saída precisa estar ativado para oferecer suporte ao local para remoto e 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 dos dispositivos locais e os dispositivos Bluetooth pareados.
Os apps de áudio são compatíveis com o Google Cast para áudio nas configurações do app receptor no Console para desenvolvedores do SDK Google Cast.
interface do switch de saída
O seletor de saída mostra os dispositivos locais e remotos disponíveis, bem como os estados atuais do dispositivo, incluindo se o dispositivo está selecionado, está se conectando, o nível de volume atual. Se houver outros dispositivos além do atual, clicar em outro dispositivo vai permitir que você transfira 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 (tocando localmente), o canto superior direito da notificação de mídia
vai mostrar um ícone de notificação com o nome do dispositivo (como alto-falante do smartphone) em que
o conteúdo está sendo reproduzido no momento. 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 "Play <App Name> on <Cast Device>".
Resumo das etapas
- Garantir que os pré-requisitos foram atendidos
- Ativar o seletor de saída no AndroidManifest.xml
- Atualizar SessionManagerListener para transmissão em segundo plano
- Definir a flag setRemoteToLocalEnabled
- Continuar a reprodução localmente
Pré-requisitos
- Migre o app Android existente para o AndroidX.
- 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' ... }
- O app oferece suporte a notificações de mídia.
- 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 de reprodução de mídia local. Isso requer a criação de um
MediaSession
,
a configuração de
MediaStyle
com o token do MediaSession
e 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:
// 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(); }
Além disso, para preencher a notificação com as informações da mídia,
você precisará 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
sua mídia no
MediaMetadataCompat.Builder()
.
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() ); }
Para adicionar o estado de reprodução ao MediaSession
, use
setPlaybackState()
e forneça todas as constantes
PlaybackStateCompat
relevantes para sua mídia no
PlaybackStateCompat.Builder()
.
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() ); }
Comportamento de notificações do app de vídeo
Apps de vídeo ou áudio que não têm suporte à reprodução local em segundo plano precisam ter um comportamento específico para notificações de mídia para evitar problemas com o envio de comandos de mídia em situações em que não há suporte para reprodução:
- Postar a notificação ao reproduzir mídia localmente e o app estiver em primeiro plano.
- Pausar a reprodução local e dispensar 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 novamente.
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 flag 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 interface
do sistema. Consulte a referência de
MediaTransferReceiver
para saber mais.
Local para remoto
Quando o usuário muda a reprodução de local para remoto, o SDK do Cast inicia
a sessão de transmissão automaticamente. No entanto, os apps precisam gerenciar a mudança de
local para remoto, por exemplo, interromper a reprodução local
e carregar a mídia no dispositivo de transmissão. Os apps precisam ouvir o callback
SessionManagerListener
do Cast
usando os callbacks
onSessionStarted()
e
onSessionEnded()
e processar a ação ao receber os callbacks
SessionManager
do Cast. Os apps precisam garantir que esses callbacks ainda estejam ativos quando
a caixa de diálogo do seletor de saída for aberta e o app não estiver em primeiro plano.
Atualização de SessionManagerListener para transmissão em segundo plano
A experiência legada do Cast já oferece suporte ao modo remoto para o local quando o app está
em primeiro plano. Uma experiência típica do Cast começa quando os usuários clicam no ícone do 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 postam 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 precisam
sempre receber os callbacks locais para remotos (como onSessionStarted
) quando
estiverem em segundo plano.
Se o app usa o
MediaBrowserService
,
é recomendável registrar o SessionManagerListener
nele.
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); } } }
Com essa atualização, o local para o 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 com Google Cast.
Remoto para local
O seletor de saída permite fazer a transferência da reprodução remota para o
alto-falante do smartphone ou o dispositivo Bluetooth local. Isso pode ser ativado definindo a
flag setRemoteToLocalEnabled
como true
no CastOptions
.
Nos casos em que o dispositivo remetente atual participa de uma sessão já existente 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 sinalização 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 na caixa de diálogo
do switch de saída quando há uma sessão de transmissão ativa.
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() } }
Continuar reprodução localmente
Os apps com suporte ao protocolo remoto para local precisam registrar o SessionTransferCallback
para receber notificações quando o evento ocorrer. Assim, eles podem verificar se a mídia pode
ser transferida e continuar a reprodução localmente.
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 da SessionTransferCallback
, ele não vai mais
receber SessionTransferCallback
s.
O SessionTransferCallback
é uma extensão dos callbacks de
SessionManagerListener
existentes e é acionado depois que onSessionEnded
é acionado. Portanto, a ordem
das chamadas de retorno remotas para locais é a seguinte:
onTransferring
onSessionEnding
onSessionEnded
onTransferred
Como o seletor de saída pode ser aberto pelo chip 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 maneira diferente, dependendo se oferecem ou não suporte à reprodução em segundo plano. No caso de uma transferência com falha, onTransferFailed
será acionado sempre que o erro ocorrer.
Apps com suporte à reprodução em segundo plano
Para apps com suporte à reprodução em segundo plano, normalmente apps de áudio, é
recomendável usar um Service
(por exemplo, MediaBrowserService
). Os serviços
precisam detectar o callback onTransferred
e retomar a reprodução localmente quando o app estiver em primeiro ou segundo plano.
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. } } }
Apps que não têm suporte à reprodução em segundo plano
Para apps que não oferecem suporte à reprodução em segundo plano (normalmente, 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 vai pausar a reprodução e armazenar as
informações necessárias do SessionState
(por exemplo, metadados de mídia e posição
da reprodução). Quando o app é colocado em primeiro plano em segundo plano, a reprodução local
continua com as informações armazenadas.
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. } } }