Il selettore di output è una funzionalità dell'SDK Cast che consente il trasferimento
senza interruzioni tra la riproduzione locale e quella remota dei contenuti a partire da Android 13. L'obiettivo è aiutare le app dei mittenti a controllare rapidamente e in modo facile la riproduzione dei contenuti.
Il selettore di output utilizza la libreria MediaRouter
per alternare la riproduzione dei contenuti tra l'altoparlante del telefono, i dispositivi Bluetooth accoppiati e i dispositivi remoti compatibili con Google Cast. I casi d'uso possono essere suddivisi
nei seguenti scenari:
Scarica e utilizza l'esempio riportato di seguito come riferimento su come implementare il selettore di output nell'app audio. Consulta il file README.md incluso per istruzioni su come eseguire il Sample.
Il selettore di output deve essere abilitato per supportare il trasferimento da locale a remoto e da remoto a locale seguendo la procedura descritta in questa guida. Non sono necessari ulteriori passaggi per supportare il trasferimento tra gli altoparlanti dei dispositivi locali e i dispositivi Bluetooth accoppiati.
Le app audio sono app che supportano Google Cast for Audio nelle impostazioni dell'app ricevitore nella console per gli sviluppatori dell'SDK Google Cast
UI del selettore di output
Il selettore di output visualizza i dispositivi locali e remoti disponibili, nonché lo stato attuale del dispositivo, incluso se il dispositivo è selezionato, si sta connettendo e il livello di volume corrente. Se ci sono altri dispositivi oltre a quello attuale, facendo clic sull'altro dispositivo puoi trasferire la riproduzione dei contenuti multimediali al dispositivo selezionato.
Problemi noti
- Le sessioni multimediali create per la riproduzione locale vengono ignorate e ricreate quando si passa alla notifica dell'SDK Cast.
Entry point
Notifica multimediale
Se un'app pubblica una notifica di contenuti multimediali con l'icona
MediaSession
per
la riproduzione locale (riproduzione in locale), nell'angolo in alto a destra della notifica dei contenuti multimediali
viene visualizzato un chip di notifica con il nome del dispositivo (ad esempio l'altoparlante del telefono) su cui
i contenuti sono attualmente in riproduzione. Se tocchi il chip di notifica,
si apre l'UI di sistema del Selettore di output.
Impostazioni relative al volume
L'interfaccia utente di sistema del selettore di output può essere attivata anche facendo clic sui pulsanti del volume fisici del dispositivo, toccando l'icona delle impostazioni in basso e toccando il testo "Riproduci <nome app> su <dispositivo di trasmissione>".
Riepilogo dei passaggi
- Assicurarsi che i prerequisiti siano soddisfatti
- Abilita il selettore di output in AndroidManifest.xml
- Aggiornare SessionManagerListener per la trasmissione in background
- Impostare il flag setRemoteToLocalEnabled
- Continuare la riproduzione localmente
Prerequisiti
- Esegui la migrazione della tua app per Android attuale ad AndroidX.
- Aggiorna l'
build.gradle
dell'app per utilizzare la versione minima richiesta dell'SDK Android Sender per il selettore di output:dependencies { ... implementation 'com.google.android.gms:play-services-cast-framework:21.2.0' ... }
- L'app supporta le notifiche multimediali.
- Dispositivo con Android 13.
Configurare le notifiche per i contenuti multimediali
Per utilizzare il selettore di output, le app audio e video devono creare una notifica dei contenuti multimediali per visualizzare lo stato di riproduzione e i controlli dei contenuti multimediali per la riproduzione locale. Devi creare una MediaSession
, impostare il MediaStyle
con il token di MediaSession
e impostare i controlli multimediali nella notifica.
Se al momento non utilizzi MediaStyle
e MediaSession
, lo snippet
di seguito mostra come configurarli e sono disponibili guide per configurare i callback
delle sessioni multimediali per
le app audio e
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(); }
Inoltre, per compilare la notifica con le informazioni relative ai tuoi contenuti multimediali, dovrai aggiungere i metadati e lo stato di riproduzione dei contenuti multimediali a MediaSession
.
Per aggiungere metadati a MediaSession
, utilizza
setMetaData()
e fornisci tutte le costanti
MediaMetadata
pertinenti per
i tuoi contenuti multimediali in
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() ); }
Per aggiungere lo stato di riproduzione a MediaSession
, utilizza
setPlaybackState()
e fornisci tutte le costanti
PlaybackStateCompat
per i tuoi contenuti multimediali in
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 delle notifiche dell'app video
Le app video o audio che non supportano la riproduzione locale in background devono avere un comportamento specifico per le notifiche relative ai contenuti multimediali al fine di evitare problemi con l'invio di comandi multimediali in situazioni in cui la riproduzione non è supportata:
- Pubblica la notifica relativa ai contenuti multimediali quando riproduci contenuti multimediali in locale e l'app è in primo piano.
- Metti in pausa la riproduzione locale e ignora la notifica quando l'app è in background.
- Quando l'app torna in primo piano, dovrebbe riprendere la riproduzione locale e la notifica dovrebbe essere ripubblicata.
Attiva il selettore di output in AndroidManifest.xml
Per attivare il selettore di output, è necessario aggiungere MediaTransferReceiver
al AndroidManifest.xml
dell'app. In caso contrario, la funzionalità non verrà abilitata e anche il flag di caratteristica da remoto a locale non sarà valido.
<application>
...
<receiver
android:name="androidx.mediarouter.media.MediaTransferReceiver"
android:exported="true">
</receiver>
...
</application>
MediaTransferReceiver
è un broadcast receiver che consente il trasferimento di contenuti multimediali tra dispositivi con UI di sistema. Per ulteriori informazioni, consulta il riferimento MediaTransferReceiver.
Da locale a remoto
Quando l'utente passa dalla riproduzione locale a quella remota, l'SDK Cast avvia automaticamente la sessione di trasmissione. Tuttavia, le app devono gestire il passaggio dalla modalità locale a quella remota, ad esempio interrompere la riproduzione locale e caricare i contenuti multimediali sul dispositivo di trasmissione. Le app devono ascoltare la trasmissione SessionManagerListener
, utilizzando i callback onSessionStarted()
e onSessionEnded()
, e gestire l'azione quando ricevono i callback SessionManager
. Le app devono assicurarsi che questi callback siano ancora attivi quando
si apre la finestra di dialogo Selettore di output e l'app non è in primo piano.
Aggiornamento di SessionManagerListener per trasmissione in background
La versione precedente di Google Cast supporta già la trasmissione locale da remoto quando l'app è in primo piano. Un'esperienza di trasmissione tipica inizia quando gli utenti fanno clic sull'icona
Trasmetti nell'app e scelgono un dispositivo per riprodurre contenuti multimediali in streaming. In questo caso, l'app deve
registrarsi in
SessionManagerListener
,
in onCreate()
o
onStart()
e annullare la registrazione del listener in
onStop()
o
onDestroy()
dell'attività dell'app.
Con la nuova esperienza di trasmissione mediante il selettore di output, le app possono iniziare a trasmettere quando sono in background. Ciò è particolarmente utile per le app audio
che pubblicano notifiche quando vengono riprodotte in background. Le app possono
registrare i listener SessionManager
nel onCreate()
del servizio
e annullare la registrazione nel onDestroy()
del servizio. In questo modo, le app devono
ricevere sempre i callback da locale a remoto (ad esempio onSessionStarted
) quando
l'app è in background.
Se l'app utilizza
MediaBrowserService
,
ti consigliamo di registrare SessionManagerListener
lì.
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 questo aggiornamento, la trasmissione da locale a telecomando si comporta come la trasmissione tradizionale quando l'app è in background e non è richiesta ulteriore attività per passare dai dispositivi Bluetooth ai dispositivi di trasmissione.
Da remoto a locale
Il selettore di output consente di passare dalla riproduzione remota
all'altoparlante del telefono o a un dispositivo Bluetooth locale. Questa operazione può essere abilitata impostando il
flag setRemoteToLocalEnabled
su true
in CastOptions
.
Nei casi in cui il dispositivo del mittente attuale partecipa a una sessione esistente con
più mittenti e l'app deve verificare se i contenuti multimediali attuali possono essere
trasferiti localmente, le app devono usare il callback onTransferred
di
SessionTransferCallback
per controllare SessionState
.
Imposta il flag setRemoteToLocalEnabled
Lo CastOptions
fornisce uno setRemoteToLocalEnabled
per mostrare o nascondere
l'altoparlante del telefono e i dispositivi Bluetooth locali come destinazioni di trasferimento nella finestra di dialogo
Selettore di output quando è attiva una sessione di trasmissione.
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() } }
Continua la riproduzione localmente
Le app che supportano la funzionalità remote-to-local devono registrare SessionTransferCallback
per ricevere una notifica quando si verifica l'evento, in modo da poter controllare se i contenuti multimediali
devono essere autorizzati a trasferire e continuare la riproduzione localmente.
CastContext#addSessionTransferCallback(SessionTransferCallback)
consente a
un'app di registrare il proprio SessionTransferCallback
e ascoltare i callback onTransferred
e
onTransferFailed
quando un mittente viene trasferito alla riproduzione locale.
Dopo che l'app ha annullato la registrazione del relativo SessionTransferCallback
, l'app non riceverà più
SessionTransferCallback
.
SessionTransferCallback
è un'estensione dei callback
SessionManagerListener
esistenti e viene attivato dopo l'attivazione di onSessionEnded
. Di conseguenza, l'ordine dei callback da remoto a locale è:
onTransferring
onSessionEnding
onSessionEnded
onTransferred
Poiché il selettore di output può essere aperto dal chip di notifica dei contenuti multimediali quando
l'app è in background e sta trasmettendo, le app devono gestire il trasferimento
in locale in modo diverso a seconda che supportano o meno la riproduzione in background. In caso di trasferimento non riuscito, onTransferFailed
si attiverà in qualsiasi momento in cui si verifica l'errore.
App che supportano la riproduzione in background
Per le app che supportano la riproduzione in background (in genere le app audio), consigliamo
di utilizzare Service
(ad esempio MediaBrowserService
). I servizi
devono ascoltare il callback onTransferred
e riprendere la riproduzione localmente
quando l'app è in primo piano o in background.
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. } } }
App che non supportano la riproduzione in background
Per le app che non supportano la riproduzione in background (in genere le app video), ti consigliamo di ascoltare il callback onTransferred
e riprendere la riproduzione localmente se l'app è in primo piano.
Se l'app è in background, la riproduzione deve essere messa in pausa e dovrebbero essere archiviate le informazioni necessarie di SessionState
(ad esempio, metadati dei contenuti multimediali e posizione di riproduzione). Quando l'app è in primo piano in background, la riproduzione locale
dovrebbe continuare con le informazioni memorizzate.
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. } } }