Selettore di uscita

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:

• Da locale a remoto
• Da remoto a locale

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.

Scarica esempio

Termine chiave: in questa guida, il termine locale si riferisce a qualsiasi dispositivo Bluetooth o dispositivo mobile accoppiato (ad esempio smartphone 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 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

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

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

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

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 per i tuoi contenuti multimediali in 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 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

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

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

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

Nota :per garantire una transizione fluida dalla modalità locale a quella remota, ti consigliamo di interrompere la riproduzione sul dispositivo locale durante il callback onSessionStarted, dopo che l'SDK Cast si è connesso al ricevitore. In questo modo ti assicuri che la riproduzione locale venga interrotta solo dopo che è stata ripresa sul dispositivo remoto e che si verifichino problemi di temporizzazione dovuti alla latenza.

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.

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 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 è:

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

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

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