Attiva il controllo di riproduzione

Per abilitare la riproduzione di contenuti multimediali in Android Auto e Android Automotive OS (AAOS), implementa i controlli di riproduzione registrando una sessione multimediale e gestendo i relativi metodi di callback. Questa pagina spiega come:

• Registrare un oggetto MediaSessionCompat nel servizio del browser multimediale.

• Implementare i metodi MediaSessionCompat.Callback per rispondere alle richieste di riproduzione degli utenti.

• Configurare le azioni di riproduzione standard e personalizzate.

• Impostare lo stato di riproduzione iniziale per la sessione multimediale.

• Aggiungere icone per indicare il formato audio.

• Creare link da elementi multimediali in riproduzione attiva.

Android Auto e AAOS inviano i comandi di controllo della riproduzione tramite MediaSessionCompat per il tuo servizio. Devi registrare una sessione e implementare i metodi di callback associati.

Registrare una sessione multimediale

Nel metodo onCreate del servizio del browser multimediale, crea un'istanza di MediaSessionCompat, quindi chiama setSessionToken per registrare la sessione multimediale. Questo snippet di codice mostra come creare e registrare una sessione multimediale:

override fun onCreate() {
    super.onCreate()
    ...
    // Start a new MediaSession.
    val session = MediaSessionCompat(this, "session tag").apply {
        // Set a callback object that implements MediaSession.Callback
        // to handle play control requests.
        setCallback(MyMediaSessionCallback())
    }
    sessionToken = session.sessionToken
    ...
}

public void onCreate() {
    super.onCreate();
    ...
    // Start a new MediaSession.
    MediaSessionCompat session = new MediaSessionCompat(this, "session tag");
    setSessionToken(session.getSessionToken());

    // Set a callback object that implements MediaSession.Callback
    // to handle play control requests.
    session.setCallback(new MyMediaSessionCallback());
    ...
}

Quando crei l'oggetto della sessione multimediale, imposti un oggetto di callback utilizzato per gestire le richieste di controllo della riproduzione. Crea questo oggetto di callback fornendo un'implementazione della MediaSessionCompat.Callbackclasse per la tua app. La sezione successiva descrive come implementare questo oggetto.

Implementare i comandi di riproduzione

Quando un utente richiede la riproduzione di un elemento multimediale dalla tua app, Android Automotive OS e Android Auto utilizzano la MediaSessionCompat.Callback classe dall'oggetto MediaSessionCompat della tua app, che il sistema ottiene dal servizio del browser multimediale. Quando un utente vuole controllare la riproduzione, ad esempio mettere in pausa la riproduzione o passare alla traccia successiva, Android Auto e Android Automotive OS richiamano uno dei metodi dell'oggetto di callback.

Per gestire la riproduzione dei contenuti, la tua app deve estendere la classe astratta MediaSessionCompat.Callback e implementare i metodi supportati dall'app.

Implementa ciascuno di questi metodi di callback che hanno senso per il tipo di contenuti offerti dalla tua app:

onPrepare

AAOS richiama questo metodo quando l'origine multimediale cambia.

onPlay

Viene richiamato quando l'utente seleziona la riproduzione senza scegliere un elemento specifico. La tua app deve riprodurre i contenuti predefiniti o, se la riproduzione è stata messa in pausa con onPause, la riprende.

onPlayFromMediaId

Viene richiamato quando l'utente sceglie di riprodurre un elemento specifico. Il metodo riceve l'ID assegnato dal servizio del browser multimediale all'elemento multimediale nella gerarchia dei contenuti.

onPlayFromSearch

Viene richiamato quando l'utente sceglie di riprodurre da una query di ricerca. L'app deve fare una scelta appropriata in base alla stringa di ricerca passata.

onPause

Viene richiamato quando l'utente sceglie di mettere in pausa la riproduzione.

onSkipToNext

Viene richiamato quando l'utente sceglie di passare all'elemento successivo.

onSkipToPrevious

Viene richiamato quando l'utente sceglie di passare all'elemento precedente.

onStop

Viene richiamato quando l'utente sceglie di interrompere la riproduzione. Esegui l'override di questi metodi nella tua app per fornire il risultato scelto. Non è necessario implementare un metodo se la tua app non supporta il suo scopo. Ad esempio, se la tua app riproduce uno streaming live, come una trasmissione sportiva, non devi implementare onSkipToNext. Utilizza invece l'implementazione predefinita di onSkipToNext.

La tua app non ha bisogno di una logica speciale per riprodurre i contenuti tramite gli speaker dell'auto. Quando la tua app riceve una richiesta di riproduzione di contenuti, riproduce l'audio nello stesso modo in cui i contenuti vengono riprodotti tramite gli speaker o le cuffie dello smartphone di un utente. Android Auto e AAOS inviano automaticamente i contenuti audio al sistema dell'auto per la riproduzione tramite gli speaker dell'auto.

Per saperne di più sulla riproduzione di contenuti audio, consulta Panoramica del player multimediale, Panoramica dell'app audio, e la panoramica di ExoPlayer.

Impostare le azioni di riproduzione standard

Android Auto e AAOS mostrano i controlli di riproduzione in base alle azioni abilitate nell'PlaybackStateCompat oggetto. Per impostazione predefinita, la tua app deve supportare le seguenti azioni:

• ACTION_PLAY
• ACTION_PAUSE
• ACTION_STOP
• ACTION_PLAY_FROM_MEDIA_ID
• ACTION_PLAY_FROM_SEARCH

La tua app può supportare anche le seguenti azioni, se pertinenti ai contenuti dell'app:

• ACTION_SKIP_TO_PREVIOUS
• ACTION_SKIP_TO_NEXT

Puoi anche creare una coda di riproduzione da mostrare all'utente. Per farlo, chiama i metodi setQueue e setQueueTitle, abilita l'azione ACTION_SKIP_TO_QUEUE_ITEM e definisci la callback onSkipToQueueItem.

Aggiungi anche il supporto per l'icona In riproduzione , che indica cosa viene riprodotto. Per farlo, chiama il metodo setActiveQueueItemId e passa l'ID dell'elemento in riproduzione nella coda. Devi aggiornare setActiveQueueItemId ogni volta che la coda cambia.

Android Auto e AAOS mostrano i pulsanti per ogni azione abilitata, nonché la coda di riproduzione. Quando gli utenti fanno clic su questi pulsanti, il sistema richiama la callback corrispondente da MediaSessionCompat.Callback.

Riservare spazio inutilizzato

Android Auto e AAOS riservano spazio nell'interfaccia utente per le azioni ACTION_SKIP_TO_PREVIOUS e ACTION_SKIP_TO_NEXT. Se la tua app non supporta una di queste funzioni, Android Auto e AAOS utilizzano lo spazio per visualizzare le azioni personalizzate che crei.

Se non vuoi riempire questi spazi con azioni personalizzate, puoi riservarli in modo che Android Auto e AAOS lascino lo spazio vuoto ogni volta che la tua app non supporta la funzione corrispondente.

Per farlo, chiama il metodo setExtras con un pacchetto di extra contenente costanti che corrispondono alle funzioni riservate. SESSION_EXTRAS_KEY_SLOT_RESERVATION_SKIP_TO_NEXT corrisponde a ACTION_SKIP_TO_NEXT, mentre SESSION_EXTRAS_KEY_SLOT_RESERVATION_SKIP_TO_PREV corrisponde a ACTION_SKIP_TO_PREVIOUS. Utilizza queste costanti come chiavi nel pacchetto e il valore booleano true come valori.

Impostare PlaybackState iniziale

Quando Android Auto e AAOS comunicano con il servizio del browser multimediale, la sessione multimediale comunica lo stato della riproduzione dei contenuti utilizzando PlaybackStateCompat.

La tua app non deve avviare automaticamente la riproduzione di musica quando AAOS o Android Auto si connettono al servizio del browser multimediale. Affidati invece ad Android Auto e AAOS per riprendere o avviare la riproduzione in base allo stato dell'auto o alle azioni dell'utente.

Per farlo, imposta PlaybackStateCompat della sessione multimediale su STATE_STOPPED, STATE_PAUSED, STATE_NONE o STATE_ERROR.

Le sessioni multimediali in Android Auto e AAOS durano solo per la durata della guida, quindi gli utenti avviano e interrompono spesso queste sessioni. Per promuovere un'esperienza senza interruzioni tra le guide, tieni traccia dello stato della sessione precedente dell'utente, in modo che quando l'app multimediale riceve una richiesta di ripresa, l'utente possa riprendere automaticamente da dove aveva interrotto. Questo stato include l'ultimo elemento multimediale riprodotto, l'oggetto PlaybackStateCompat e la coda.

Aggiungere azioni di riproduzione personalizzate

Puoi aggiungere azioni di riproduzione personalizzate per visualizzare azioni aggiuntive supportate dalla tua app multimediale. Se lo spazio lo consente (e non lo riservi), Android aggiunge le azioni personalizzate ai controlli di trasporto. In caso contrario, le azioni personalizzate vengono visualizzate nel menu Overflow. Android visualizza le azioni personalizzate nell'ordine in cui le aggiungi a PlaybackStateCompat.

Utilizza le azioni personalizzate per fornire un comportamento distinto dalle azioni standard. Non utilizzarle per sostituire o duplicare le azioni standard.

Per aggiungere azioni personalizzate, utilizza il addCustomAction metodo nella PlaybackStateCompat.Builder classe. Questo snippet di codice mostra come aggiungere un'azione personalizzata per "Avvia un canale radio":

val customActionExtras = Bundle()
customActionExtras.putInt(
  androidx.media3.session.MediaConstants.EXTRAS_KEY_COMMAND_BUTTON_ICON_COMPAT,
  androidx.media3.session.CommandButton.ICON_RADIO)

stateBuilder.addCustomAction(
    PlaybackStateCompat.CustomAction.Builder(
        CUSTOM_ACTION_START_RADIO_FROM_MEDIA,
        resources.getString(R.string.start_radio_from_media),
        startRadioFromMediaIcon // or R.drawable.media3_icon_radio
    ).run {
        setExtras(customActionExtras)
        build()
    }
)

Bundle customActionExtras = new Bundle();
customActionExtras.putInt(
  androidx.media3.session.MediaConstants.EXTRAS_KEY_COMMAND_BUTTON_ICON_COMPAT,
  androidx.media3.session.CommandButton.ICON_RADIO);

stateBuilder.addCustomAction(
    new PlaybackStateCompat.CustomAction.Builder(
        CUSTOM_ACTION_START_RADIO_FROM_MEDIA,
        resources.getString(R.string.start_radio_from_media),
        startRadioFromMediaIcon) // or R.drawable.media3_icon_radio
    .setExtras(customActionExtras)
    .build());

Per un esempio più dettagliato di questo metodo, consulta il setCustomAction metodo nell'app di esempio Universal Android Music Player su GitHub. Dopo aver creato l'azione personalizzata, la sessione multimediale può rispondere alle azioni eseguendo l'override del metodo onCustomAction.

Questo snippet di codice mostra come la tua app potrebbe rispondere a un'azione "Avvia un canale radio":

override fun onCustomAction(action: String, extras: Bundle?) {
    when(action) {
        CUSTOM_ACTION_START_RADIO_FROM_MEDIA -> {
            ...
        }
    }
}

@Override
public void onCustomAction(@NonNull String action, Bundle extras) {
    if (CUSTOM_ACTION_START_RADIO_FROM_MEDIA.equals(action)) {
        ...
    }
}

Per saperne di più, consulta il metodo onCustomAction nell'app di esempio Universal Android Music Player su GitHub.

Creare icone per le azioni personalizzate

Ogni azione personalizzata che crei richiede un'icona.

Se la descrizione dell'icona corrisponde a una delle CommandButton.ICON_ costanti, imposta il valore intero per la EXTRAS_KEY_COMMAND_BUTTON_ICON_COMPAT chiave degli extra dell'azione personalizzata. Sui sistemi supportati, questa operazione esegue l'override della risorsa icona passata a CustomAction.Builder, consentendo ai componenti di sistema di eseguire il rendering coerente di azione e altre azioni di riproduzione.

Devi anche specificare una risorsa icona. Le app nelle auto possono essere eseguite su molte dimensioni e densità dello schermo diverse, quindi le icone che fornisci devono essere disegnabili vettoriali. Utilizza un elemento disegnabile vettoriale per scalare gli asset senza perdere dettagli. Un elemento disegnabile vettoriale può allineare bordi e angoli ai limiti dei pixel a risoluzioni più piccole.

Se un'azione personalizzata è con stato (se attiva o disattiva un'impostazione di riproduzione), fornisci icone diverse per i diversi stati per aiutare gli utenti a vedere una modifica quando selezionano l'azione.

Fornire stili di icone alternativi per le azioni disattivate

Quando un'azione personalizzata non è disponibile per il contesto corrente, sostituisci l'icona dell'azione personalizzata con un'icona alternativa che mostra l'azione come disattivata.

Indicare il formato audio

Per indicare che i contenuti multimediali in riproduzione utilizzano un formato audio speciale, puoi specificare le icone di cui viene eseguito il rendering nelle auto che supportano questa funzionalità. Puoi impostare KEY_CONTENT_FORMAT_TINTABLE_LARGE_ICON_URI e KEY_CONTENT_FORMAT_TINTABLE_SMALL_ICON_URI nel pacchetto di extra dell' elemento multimediale in riproduzione (passato a MediaSession.setMetadata). Imposta entrambi gli extra per adattarsi ai diversi layout.

Inoltre, puoi impostare l'extra KEY_IMMERSIVE_AUDIO per comunicare agli OEM di auto che si tratta di audio immersivo e che devono prestare molta attenzione quando decidono se applicare effetti audio che potrebbero interferire con i contenuti immersivi.

Aggiungere link dall'elemento in riproduzione

Puoi configurare l'elemento multimediale in riproduzione in modo che il sottotitolo, la descrizione o entrambi siano link ad altri elementi multimediali. In questo modo, l'utente può passare rapidamente agli elementi correlati, ad esempio ad altri brani dello stesso artista o ad altri episodi di un podcast. Se l'auto supporta questa funzionalità, gli utenti possono toccare il link per sfogliare i contenuti.

Per aggiungere link, configura i metadati KEY_SUBTITLE_LINK_MEDIA_ID (per creare un link dal sottotitolo) o KEY_DESCRIPTION_LINK_MEDIA_ID (per creare un link dalla descrizione). Per maggiori dettagli, consulta la documentazione di riferimento per questi campi di metadati.