O seletor de saída é um recurso do SDK do Cast que permite transferências perfeitas
entre a reprodução local e remota de conteúdo no Android 13 e versões mais recentes. Meta
é ajudar os apps remetentes a controlar com facilidade e rapidez onde o conteúdo é reproduzido.
O seletor de saída usa o
Biblioteca MediaRouter
para
alternar a reprodução do conteúdo entre o alto-falante do smartphone, dispositivos Bluetooth pareados
e dispositivos compatíveis com Cast. Os casos de uso podem ser divididos nas seguintes
cenários:
Faça o download e use o exemplo abaixo como referência sobre como implementar a Saída Seletor no seu app de áudio. Consulte o README.md incluído para instruções sobre como executar a amostra.
O switch de saída precisa ser ativado para oferecer suporte ao local para remoto e do remoto ao local seguindo as etapas deste guia. Não há outras etapas necessárias para oferecer suporte à transferência entre os alto-falantes locais do dispositivo e o Bluetooth pareado dispositivos.
Apps de áudio são apps compatíveis com o Google Cast para áudio no App receptor no SDK do Google Cast para desenvolvedores console
interface do seletor de saída
O seletor de saída mostra os dispositivos locais e remotos disponíveis além dos estados atuais do dispositivo, incluindo se ele está selecionado, está conectando: o nível de volume atual. Se houver outros dispositivos ao dispositivo atual. Ao clicar em outro dispositivo, você transfere a mídia a reprodução no dispositivo selecionado.
Problemas conhecidos
- As sessões de mídia criadas para reprodução local serão dispensadas e recriadas ao mudar 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 de mídia
exibe um ícone de notificação com o nome do dispositivo (como alto-falante do smartphone) que
em que o conteúdo está sendo reproduzido. Tocar no ícone de notificação abre
a IU do sistema da caixa de diálogo do switch de saída.
Configurações de volume
A interface do sistema da caixa de diálogo do switch de saída também pode ser acionada ao clicar no botões de volume físicos do dispositivo, tocando no ícone de configurações na parte inferior e tocar no botão "Jogar <App Name> em <Dispositivo de transmissão>" em textos.
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
- Migre seu app Android 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,
audio e
Apps de vídeo
precisam criar uma notificação de mídia para exibir o status de reprodução e
e controles de mídia para reprodução local. Isso requer a criação de um
MediaSession
,
definindo
MediaStyle
com o token de MediaSession
e definir os controles de mídia no
notificação.
Se você não estiver usando MediaStyle
e MediaSession
, o snippet
abaixo mostra como fazer a configuração e guias estão disponíveis para configurar a mídia
callbacks de sessão para
audio e
vídeo
aplicativos:
// 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 para sua mídia,
você precisará adicionar
metadados e estado de reprodução
ao MediaSession
.
Para adicionar metadados ao MediaSession
, use
setMetaData()
e fornecer todas as informações
Constantes MediaMetadata
para
sua mídia na
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 à MediaSession
, use
setPlaybackState()
e fornecer todas as informações
PlaybackStateCompat
constantes 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ção de app de vídeo
Apps de vídeo ou áudio que não oferecem suporte à reprodução local em segundo plano devem ter um comportamento específico para notificações de mídia a fim de evitar problemas com enviar comandos de mídia em situações em que a reprodução não é compatível:
- Postar a notificação de mídia quando a mídia estiver aberta localmente e o app estiver em primeiro plano.
- Pausar a reprodução local e dispensar a notificação quando o app estiver no plano de fundo.
- 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. Se não estiver, o recurso
não será ativada 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>
A
MediaTransferReceiver
é um broadcast receiver que permite a transferência de mídia entre dispositivos com sistemas
de ML pela UI. Consulte a documentação do MediaTransferReceiver
Referência
para mais informações.
Local para remoto
Quando o usuário alterna a reprodução do local para o remoto, o SDK do Cast é iniciado
a sessão de transmissão automaticamente. No entanto, os apps precisam lidar com a mudança
do local para o remoto. Por exemplo, interromper a reprodução local
e carregue a mídia no dispositivo de transmissão. Os apps precisam ouvir a transmissão
SessionManagerListener
,
usando o método
onSessionStarted()
e
onSessionEnded()
callbacks e processar a ação ao receber a transmissão
SessionManager
. Os apps precisam garantir que esses callbacks ainda estejam ativos quando
a caixa de diálogo do seletor de saída é aberta e o app não está em primeiro plano.
Atualizar o SessionManagerListener para transmissão em segundo plano
A experiência legada do Google 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 botão
no app e escolha um dispositivo para fazer streaming de mídia. Nesse caso, o app precisa
se registrar no
SessionManagerListener
,
em onCreate()
ou
onStart()
cancelar o registro do listener
onStop()
ou
onDestroy()
da atividade do app.
Com a nova experiência de transmissão usando o seletor de saída, os apps podem iniciar
transmitindo quando estão em segundo plano. Isso é particularmente útil para áudios
de apps que postam notificações durante a reprodução em segundo plano. Os apps podem
registre os listeners SessionManager
no onCreate()
do serviço
e cancele o registro no onDestroy()
do serviço. Dessa forma, os apps devem
sempre receberão os callbacks locais para remotos (como onSessionStarted
) quando
que o app esteja 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 conteúdo do local para o remoto funciona da mesma forma que a transmissão tradicional quando o app fica em segundo plano e não exige trabalho extra para mudar do Dispositivos Bluetooth para dispositivos de transmissão.
Remoto para local
O Output Switcher proporciona a capacidade de transferir da reprodução remota para o
alto-falante do smartphone ou dispositivo Bluetooth local. Isso pode ser ativado definindo o
Sinalização setRemoteToLocalEnabled
para 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 tem permissão para
sejam transferidos localmente, os apps devem usar o callback onTransferred
do
SessionTransferCallback
para verificar a SessionState
.
Definir a flag setRemoteToLocalEnabled
O CastOptions
fornece um setRemoteToLocalEnabled
para mostrar ou ocultar a
alto-falante do smartphone e dispositivos Bluetooth locais como alvos de transferência na saída
Caixa de diálogo do seletor quando há uma sessão ativa de transmissão.
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 a reprodução localmente
Apps compatíveis com o recurso remoto para local precisam registrar o SessionTransferCallback
sejam notificados quando o evento ocorrer para que possam verificar se a mídia deve ser
têm permissão para transferir e continuar a reprodução localmente.
CastContext#addSessionTransferCallback(SessionTransferCallback)
permite que um
para registrar o SessionTransferCallback
e detectar onTransferred
e
Callbacks onTransferFailed
quando um remetente é transferido para a reprodução local.
Depois que o app cancelar o registro do SessionTransferCallback
, não será mais possível
receber SessionTransferCallback
s.
O SessionTransferCallback
é uma extensão do modelo
SessionManagerListener
e é acionado depois que onSessionEnded
é acionado. Portanto, a ordem
de callbacks remotos para locais é:
onTransferring
onSessionEnding
onSessionEnded
onTransferred
Como o seletor de saída pode ser aberto pelo ícone de notificação de mídia quando
o app estiver em segundo plano e transmitindo, os apps precisarão lidar com a transferência para
local de maneira diferente, dependendo de eles oferecerem ou não suporte à reprodução em segundo plano. Em
caso de uma transferência com falha, o onTransferFailed
será disparado a qualquer momento que o
ocorre um erro.
Apps compatíveis com a reprodução em segundo plano
Para aplicativos com suporte para reprodução em segundo plano (geralmente aplicativos de áudio), é
recomendado usar um Service
(por exemplo, MediaBrowserService
). Serviços
deve ouvir o callback onTransferred
e retomar a reprodução localmente
quando o app está 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 são compatíveis com a reprodução em segundo plano
Para aplicativos que não são compatíveis com a reprodução em segundo plano (geralmente aplicativos de vídeo), é
recomendado ouvir o callback onTransferred
e retomar a reprodução
localmente se o app estiver em primeiro plano.
Se o app estiver em segundo plano, ele pausará a reprodução e armazenará a
informações necessárias de SessionState
(por exemplo, metadados de mídia e reprodução
posição). Quando o app está em primeiro plano em segundo plano, a reprodução local
deve continuar 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. } } }