El selector de salida es una función del SDK de Cast que permite la transferencia sin interrupciones entre la reproducción local y remota de contenido a partir de Android 13. El objetivo es ayudar a las apps emisoras a controlar con facilidad y rapidez dónde se reproduce el contenido.
El selector de salida usa la biblioteca MediaRouter para alternar la reproducción de contenido entre la bocina del teléfono, los dispositivos Bluetooth vinculados y los dispositivos remotos compatibles con Cast. Los casos de uso se pueden dividir en las siguientes situaciones:
Descarga y usa el siguiente ejemplo como referencia para implementar el selector de salida en tu app de audio. Consulta el archivo README.md incluido para obtener instrucciones sobre cómo ejecutar la muestra.
El selector de salida debe estar habilitado para admitir las opciones de local a remoto y de remoto a local a través de los pasos que se indican en esta guía. No se necesitan pasos adicionales para admitir la transferencia entre las bocinas del dispositivo local y los dispositivos Bluetooth vinculados.
Las apps de audio son compatibles con Google Cast para audio en la configuración de la app receptora en la Consola para desarrolladores del SDK de Google Cast.
IU del selector de salida
El selector de salida muestra los dispositivos locales y remotos que están disponibles, así como los estados actuales del dispositivo (si el dispositivo está seleccionado, se está conectando), el nivel de volumen actual. Si hay otros dispositivos además del actual, hacer clic en otro te permite transferir la reproducción de contenido multimedia al dispositivo seleccionado.
Errores conocidos
- Las sesiones multimedia creadas para la reproducción local se descartarán y se volverán a crear cuando se cambie a la notificación del SDK de Cast.
Puntos de entrada
Notificación multimedia
Si una app publica una notificación multimedia con MediaSession para la reproducción local (reproduciendo localmente), la esquina superior derecha de la notificación mostrará un chip de notificación con el nombre del dispositivo (como la bocina del teléfono) en el que se está reproduciendo el contenido en ese momento. Si presionas el chip de notificación, se abre la IU del sistema de diálogo del selector de salida.
Configuración del volumen
También se puede activar la IU del sistema del diálogo Output Switcher si haces clic en los botones de volumen físico del dispositivo, presionas el ícono de configuración en la parte inferior y presionas el texto "Play <App Name> on <Cast Device>".
Resumen de los pasos
- Asegúrate de que se cumplan los requisitos previos
- Habilita el selector de salida en AndroidManifest.xml
- Actualiza SessionManagerListener para la transmisión en segundo plano
- Configura la marca setRemoteToLocalEnabled
- Continúa la reproducción de forma local
Requisitos previos
- Migra tu app para Android existente a AndroidX.
- Actualiza el
build.gradlede tu app para usar la versión mínima requerida del SDK de Android Sender para el selector de salida:dependencies { ... implementation 'com.google.android.gms:play-services-cast-framework:21.2.0' ... } - La app admite notificaciones multimedia.
- Dispositivo con Android 13
Configura las notificaciones multimedia
Para usar el selector de salida, se requiere que las apps de audio y video creen una notificación de contenido multimedia para mostrar el estado y los controles de reproducción de su contenido multimedia para la reproducción local. Para ello, debes crear un MediaSession, configurar el MediaStyle con el token de MediaSession y configurar los controles multimedia en la notificación.
Si actualmente no usas un MediaStyle ni un MediaSession, en el siguiente fragmento, se muestra cómo configurarlos, y hay guías disponibles a fin de configurar las devoluciones de llamada de sesiones multimedia para apps de audio y video:
// 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();
}
Además, para completar la notificación con la información de tu contenido multimedia, deberás agregar el estado de reproducción y los metadatos del contenido a MediaSession.
Para agregar metadatos a MediaSession, usa setMetaData() y proporciona todas las constantes MediaMetadata relevantes para tu contenido multimedia en 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 agregar el estado de reproducción a MediaSession, usa setPlaybackState() y proporciona todas las constantes PlaybackStateCompat relevantes de tu contenido multimedia en 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()
);
}
Comportamiento de las notificaciones de apps de video
Las apps de video o audio que no admiten la reproducción local en segundo plano deben tener un comportamiento específico para las notificaciones de contenido multimedia para evitar problemas con el envío de comandos multimedia en situaciones en las que no se admite la reproducción:
- Publica la notificación multimedia cuando se reproduce contenido multimedia de forma local y la app está en primer plano.
- Pausa la reproducción local y descarta la notificación cuando la app esté en segundo plano.
- Cuando la app vuelve al primer plano, se debe reanudar la reproducción local y volver a publicar la notificación.
Habilita el selector de salida en AndroidManifest.xml
Para habilitar el selector de salida, se debe agregar MediaTransferReceiver al AndroidManifest.xml de la app. De lo contrario, la función no se habilitará y la marca de función de remoto a local tampoco será válida.
<application>
...
<receiver
android:name="androidx.mediarouter.media.MediaTransferReceiver"
android:exported="true">
</receiver>
...
</application>
MediaTransferReceiver es un receptor de emisión que habilita la transferencia de contenido multimedia entre dispositivos con la IU del sistema. Consulta la referencia de MediaTransferReceiver para obtener más información.
De local a remoto
Cuando el usuario cambie la reproducción de local a remoto, el SDK de Cast iniciará la sesión de transmisión automáticamente. Sin embargo, las apps deben controlar el cambio de local a remoto, por ejemplo, detener la reproducción local y cargar el contenido multimedia en el dispositivo de transmisión. Las apps deben escuchar el SessionManagerListener de Cast mediante las devoluciones de llamada de onSessionStarted() y onSessionEnded(), y controlar la acción cuando reciben las devoluciones de llamada de Cast SessionManager. Las apps deben asegurarse de que estas devoluciones de llamada sigan activas cuando se abra el diálogo del Selector de salida y la app no esté en primer plano.
Actualiza SessionManagerListener para la transmisión en segundo plano
La experiencia de transmisión heredada ya admite la conexión local a remota cuando la app está en primer plano. Una experiencia de transmisión típica comienza cuando los usuarios hacen clic en el ícono de transmisión de la app y seleccionan un dispositivo para transmitir contenido multimedia. En este caso, la app debe registrarse en SessionManagerListener, en onCreate() o onStart(), y cancelar el registro del objeto de escucha en onStop() o onDestroy() de la actividad de la app.
Con la nueva experiencia de transmisión con el selector de salida, las apps pueden comenzar a transmitir contenido cuando están en segundo plano. Esto es particularmente útil para las apps de audio que publican notificaciones cuando se reproducen en segundo plano. Las apps pueden registrar los objetos de escucha de SessionManager en el onCreate() del servicio y cancelar el registro en el onDestroy() del servicio. De esta manera, las apps siempre deben recibir las devoluciones de llamada de ubicación local a remota (como onSessionStarted) cuando están en segundo plano.
Si la app usa MediaBrowserService, se recomienda que registres el SessionManagerListener allí.
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);
}
}
}
Con esta actualización, la opción de local a remoto actúa de la misma manera que la transmisión tradicional cuando la app está en segundo plano, y no se requiere trabajo adicional para cambiar de dispositivos Bluetooth a dispositivos de transmisión.
De remoto a local
El selector de salida permite transmitir de la reproducción remota a la bocina del teléfono o a un dispositivo Bluetooth local. Esto se puede habilitar configurando la marca setRemoteToLocalEnabled como true en CastOptions.
En los casos en los que el dispositivo emisor actual se une a una sesión existente con varios remitentes y la app necesita verificar si el contenido multimedia actual se puede transferir de forma local, las apps deben usar la devolución de llamada onTransferred de SessionTransferCallback para verificar SessionState.
Configura la marca setRemoteToLocalEnabled
CastOptions proporciona un setRemoteToLocalEnabled para mostrar u ocultar la bocina del teléfono y los dispositivos Bluetooth locales como destinos de transferencia en el diálogo Output Switcher cuando hay una sesión de transmisión activa.
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 la reproducción de forma local
Las apps que admiten la opción de remoto a local deben registrar el SessionTransferCallback para recibir notificaciones cuando se produce el evento, de modo que puedan verificar si se debe permitir que el contenido multimedia se transfiera y continúe la reproducción de manera local.
CastContext#addSessionTransferCallback(SessionTransferCallback) permite que una app registre su SessionTransferCallback y escuche las devoluciones de llamada onTransferred y onTransferFailed cuando un remitente se transfiera a la reproducción local.
Una vez que la app cancele el registro de su SessionTransferCallback, ya no recibirá SessionTransferCallback.
SessionTransferCallback es una extensión de las devoluciones de llamada existentes de SessionManagerListener y se activa después de que se activa onSessionEnded. Por lo tanto, el orden de las devoluciones de llamada de remoto a local es el siguiente:
onTransferringonSessionEndingonSessionEndedonTransferred
Dado que el selector de salida se puede abrir con el chip de notificación multimedia cuando la app está en segundo plano y transmitiendo, las apps deben controlar la transferencia al entorno local de manera diferente dependiendo de si admiten o no la reproducción en segundo plano. Si una transferencia falla, se activará onTransferFailed cada vez que ocurra el error.
Apps que admiten la reproducción en segundo plano
En el caso de las apps que admiten la reproducción en segundo plano (por lo general, apps de audio), se recomienda usar un Service (por ejemplo, MediaBrowserService). Los servicios deben escuchar la devolución de llamada onTransferred y reanudar la reproducción de forma local cuando la app está en primer o 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 no admiten la reproducción en segundo plano
En el caso de las apps que no admiten la reproducción en segundo plano (por lo general, las apps de video), se recomienda escuchar la devolución de llamada onTransferred y reanudar la reproducción de forma local si la app está en primer plano.
Si la app está en segundo plano, debe pausar la reproducción y almacenar la información necesaria de SessionState (p.ej., los metadatos multimedia y la posición de la reproducción). Cuando la app se ejecuta en primer plano desde el segundo plano, la reproducción local debe continuar con la información almacenada.
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.
}
}
}