Il selettore di output è una funzionalità dell'SDK Cast che consente il trasferimento continuo tra la riproduzione locale e quella remota di contenuti, a partire da Android 13. L'obiettivo è aiutare le app del mittente a controllare in modo facile e veloce dove vengono riprodotti i contenuti.
Il selettore di output utilizza la raccolta MediaRouter
per riprodurre i 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 di seguito come riferimento su come implementare Output Switcher nella tua app audio. Consulta il file README.md incluso per istruzioni su come eseguire l'esempio.
Il selettore di output deve essere abilitato per supportare il passaggio 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 speaker dei dispositivi locali e i dispositivi Bluetooth accoppiati.
Le app audio sono app che supportano Google Cast per l'audio nelle impostazioni dell'app ricevitore nella Console per gli sviluppatori dell'SDK Google Cast
UI Selettore di output
Il selettore di output mostra i dispositivi locali e remoti disponibili e gli stati attuali dei dispositivi, inclusi il livello di volume attuale se il dispositivo è selezionato e si connette. Se ci sono altri dispositivi oltre al dispositivo attuale, fai clic su un altro dispositivo per trasferire la riproduzione dei contenuti multimediali al dispositivo selezionato.
Problemi noti
- Le sessioni multimediali create per la riproduzione locale verranno ignorate e ricreate quando si passa alla notifica dell'SDK Cast.
Entry point
Notifica contenuti multimediali
Se un'app pubblica una notifica di contenuti multimediali con MediaSession
per la riproduzione locale (riproduzione locale), nell'angolo in alto a destra della notifica relativa ai 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. Toccando il chip di notifica si apre
l'interfaccia utente di sistema del selettore di output.
Impostazioni relative al volume
L'interfaccia utente del sistema della finestra di dialogo del selettore di output può essere attivata anche facendo clic sui pulsanti del volume fisico del dispositivo, toccando l'icona delle impostazioni in basso e poi il testo "Riproduci <nome app> su <dispositivo di trasmissione>".
Riepilogo dei passaggi
- Verificare che i prerequisiti siano soddisfatti
- Abilita il selettore di output in AndroidManifest.xml
- Aggiornamento SessionManagerListener per trasmissione in background
- Imposta il flag setRemoteToLocalEnabled
- Continuare la riproduzione in locale
Prerequisiti
- Esegui la migrazione della tua app per Android esistente ad AndroidX.
- Aggiorna
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 di contenuti multimediali.
- Dispositivo con Android 13.
Configura le notifiche di contenuti multimediali
Per utilizzare il selettore di output, le app
audio e
video
devono creare una notifica per i contenuti multimediali per visualizzare lo stato di riproduzione e i controlli
per i contenuti multimediali per la riproduzione locale. Ciò richiede la creazione di una MediaSession
, l'impostazione di MediaStyle
con il token di MediaSession
e l'impostazione dei controlli multimediali nella notifica.
Se al momento non utilizzi MediaStyle
e MediaSession
, lo snippet riportato di seguito mostra come configurarli e sono disponibili guide per la configurazione dei callback della sessione multimediale 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 completare la notifica con le informazioni relative ai contenuti multimediali, dovrai aggiungere i metadati e lo stato di riproduzione del contenuto multimediale in MediaSession
.
Per aggiungere metadati a MediaSession
, utilizza
setMetaData()
e fornisci tutte le costanti
MediaMetadata
pertinenti per
i tuoi contenuti multimediali nella
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
pertinenti per i tuoi contenuti multimediali nella
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 multimediali al fine di evitare problemi con l'invio di comandi multimediali quando la riproduzione non è supportata:
- Pubblica la notifica dei contenuti multimediali quando vengono riprodotti contenuti multimediali localmente e l'app è in primo piano.
- Metti in pausa la riproduzione locale e chiudi la notifica quando l'app è in background.
- Quando l'app torna in primo piano, la riproduzione locale dovrebbe riprendere e la notifica dovrebbe essere ripubblicata.
Attiva il selettore di output in AndroidManifest.xml
Per abilitare il selettore di output, è necessario aggiungere MediaTransferReceiver
al valore AndroidManifest.xml
dell'app. In caso contrario, la funzionalità non verrà abilitata e anche il flag funzionalità da remoto a locale non sarà valido.
<application>
...
<receiver
android:name="androidx.mediarouter.media.MediaTransferReceiver"
android:exported="true">
</receiver>
...
</application>
MediaTransferReceiver
è un ricevitore di trasmissione che consente il trasferimento di contenuti multimediali tra dispositivi con l'UI di sistema. Consulta la documentazione di riferimento MediaTransferFetchr per ulteriori informazioni.
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 da una modalità locale a una da remoto, 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 Cast
SessionManager
. Le app dovrebbero garantire che questi callback siano ancora attivi quando la finestra di dialogo del selettore di output viene aperta e l'app non è in primo piano.
Aggiornamento SessionManagerListener per trasmissione in background
L'esperienza di trasmissione precedente supporta già il servizio da locale a remoto quando l'app è in primo piano. Un'esperienza di trasmissione tipica inizia quando gli utenti fanno clic
sull'icona Trasmetti nell'app e selezionano un dispositivo per lo streaming di contenuti multimediali. In questo caso, l'app deve registrarsi in SessionManagerListener
, in onCreate()
o onStart()
e annullare la registrazione dell'ascoltatore in onStop()
o onDestroy()
nell'attività dell'app.
Grazie alla nuova esperienza di trasmissione mediante il selettore di output, le app possono iniziare a trasmettere contenuti quando sono in background. Questa funzionalità è particolarmente utile per le app audio
che pubblicano notifiche durante la riproduzione in background. Le app possono
registrare i listener SessionManager
in onCreate()
del servizio
e annullare la registrazione in onDestroy()
del servizio. In questo modo, le app devono ricevere sempre i callback da locale a remoto (ad esempio onSessionStarted
) quando sono in background.
Se l'app utilizza MediaBrowserService
, si consiglia di registrare il 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 funzionalità da locale a remoto funziona come la trasmissione tradizionale quando l'app è in background e non è necessario un lavoro aggiuntivo per passare dai dispositivi Bluetooth ai dispositivi di trasmissione.
Da remoto a locale
Il selettore di output consente di trasferire i contenuti dalla riproduzione remota all'altoparlante del telefono o al dispositivo Bluetooth locale. Questa opzione può essere attivata impostando il flag setRemoteToLocalEnabled
su true
in CastOptions
.
Per i casi in cui il dispositivo del mittente corrente 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
dell'SessionTransferCallback
per controllare SessionState
.
Imposta il flag setRemoteToLocalEnabled
L'CastOptions
fornisce un 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 il trasferimento da remoto a locale devono registrare SessionTransferCallback
per ricevere una notifica quando si verifica l'evento, in modo da poter verificare se consentire il trasferimento dei contenuti multimediali e continuare la riproduzione localmente.
CastContext#addSessionTransferCallback(SessionTransferCallback)
consente a un'app di registrare il suo SessionTransferCallback
e di ascoltare i callback onTransferred
e onTransferFailed
quando un mittente viene trasferito alla riproduzione locale.
Dopo che l'app ha annullato la registrazione dei relativi SessionTransferCallback
, non riceverà più SessionTransferCallback
.
SessionTransferCallback
è un'estensione dei callback di
SessionManagerListener
esistenti e viene attivato dopo l'attivazione di onSessionEnded
. Di conseguenza, l'ordine
delle chiamate da remoto a locale è il seguente:
onTransferring
onSessionEnding
onSessionEnded
onTransferred
Dal momento che il selettore di output può essere aperto dal chip di notifica dei contenuti multimediali quando l'app è in background e durante la trasmissione, le app devono gestire il trasferimento verso il locale in modo diverso a seconda che supportano o meno la riproduzione in background. In caso di trasferimento non riuscito, onTransferFailed
si attiverà ogni volta che si verifica l'errore.
App che supportano la riproduzione in background
Per le app che supportano la riproduzione in background (generalmente le app audio) consigliamo di utilizzare Service
(ad esempio MediaBrowserService
). I servizi
devono ascoltare il callback onTransferred
e riprendere la riproduzione localmente sia
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), consigliamo di ascoltare il callback onTransferred
e riprendere la riproduzione localmente se l'app è in primo piano.
Se l'app è in background, deve mettere in pausa la riproduzione e memorizzare le informazioni necessarie da SessionState
(ad esempio, metadati dei contenuti multimediali e posizione di riproduzione). Quando l'app viene messa in primo piano rispetto allo sfondo, la riproduzione locale deve 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. } } }