Selettore di uscita

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:

• Da locale a remoto
• Da remoto a locale

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.

Scarica anteprima

Termine chiave: in questa guida, il termine locale si riferisce a qualsiasi dispositivo mobile o Bluetooth accoppiato (ad esempio telefoni e tablet) su cui viene lanciata l'app, mentre il termine remoto si riferisce a qualsiasi dispositivo compatibile con Google Cast.

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

1. Esegui la migrazione della tua app per Android esistente ad AndroidX.
2. 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'
     ...
   }

3. L'app supporta le notifiche di contenuti multimediali.
4. 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:

Kotlin

// 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)

Java

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().

Kotlin

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()
)

Java

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().

Kotlin

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()
)

Java

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

Attenzione: a causa del ciclo di vita delle attività, consigliamo alle app che supportano la riproduzione in background (app audio) di utilizzare un servizio anziché un'attività per i callback SessionManagerListener per evitare che i callback necessari vengano annullati quando un'attività viene interrotta.

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ì.

Kotlin

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)
        }
    }
}

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.

Nota: per assicurare una transizione fluida dal locale al telecomando, ti consigliamo di interrompere la riproduzione sul dispositivo locale durante il callback onSessionStarted, dopo che l'SDK Cast si è connesso correttamente al ricevitore. In questo modo la riproduzione locale viene interrotta solo dopo che è stata ripresa la riproduzione sul dispositivo remoto e che si verificano problemi di tempistica dovuti alla latenza.

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.

Kotlin

class CastOptionsProvider : OptionsProvider {
    fun getCastOptions(context: Context?): CastOptions {
        ...
        return Builder()
            ...
            .setRemoteToLocalEnabled(true)
            .build()
    }
}

Java

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:

1. onTransferring
2. onSessionEnding
3. onSessionEnded
4. 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.

Kotlin

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.
        }
    }
}

Java

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.

Kotlin

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.
        }
    }
}

Java

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.
    }
  }
}