Attiva il controllo di riproduzione

Per attivare la riproduzione multimediale 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:

• Registra un oggetto MediaSessionCompat nel servizio del browser multimediale.

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

• Configura le azioni di riproduzione standard e personalizzate.

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

• Aggiungi icone per indicare il formato audio.

• Crea link dagli elementi multimediali in riproduzione.

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 di esplorazione dei contenuti multimediali, crea un'istanza di MediaSessionCompat, quindi chiama setSessionToken per registrare la sessione multimediale. Questo snippet di codice mostra come creare e registrare una sessione media:

Kotlin

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

Java

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 sessione multimediale, imposti un oggetto callback utilizzato per gestire le richieste di controllo della riproduzione. Crea questo oggetto di callback fornendo un'implementazione della classe MediaSessionCompat.Callback per la tua app. La sezione successiva descrive come implementare questo oggetto.

Nota: per esaminare l'esecuzione della sessione multimediale, esegui adb shell dumpsys media_session

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 classe MediaSessionCompat.Callback dell'oggetto MediaSessionCompat della tua app, che hanno ottenuto dal servizio di esplorazione dei contenuti multimediali della tua app. Quando un utente vuole controllare la riproduzione dei contenuti, 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.

Implementa ciascuno di questi metodi di callback pertinenti per il tipo di contenuti offerti dalla tua app:

onPrepare

AAOS richiama questo metodo quando cambia l'origine multimediale.

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

Nota :la tua app non deve avviare automaticamente la riproduzione di musica quando Android Automotive OS o Android Auto si connettono al servizio di navigazione dei contenuti multimediali. Per saperne di più, vedi Impostare PlaybackState iniziale.

onPlayFromMediaId

Viene richiamato quando l'utente sceglie di riprodurre un elemento specifico. Il metodo riceve l'ID che il servizio di esplorazione dei contenuti multimediali ha assegnato all'elemento multimediale nella gerarchia dei contenuti.

onPlayFromSearch

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

onPause

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

onSkipToNext

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

onSkipToPrevious

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 il suo scopo non è supportato dalla tua app. Ad esempio, se la tua app riproduce una live streaming, ad esempio una trasmissione sportiva, non è necessario 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 altoparlanti dell'auto. Quando la tua app riceve una richiesta di riproduzione di contenuti, riproduce l'audio allo stesso modo in cui i contenuti vengono riprodotti tramite gli altoparlanti dello smartphone o le cuffie di un utente. Android Auto e AAOS inviano automaticamente i contenuti audio al sistema dell'auto per la riproduzione dagli altoparlanti.

Per scoprire di più sulla riproduzione di contenuti audio, consulta Panoramica del lettore 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'oggetto PlaybackStateCompat. Per impostazione predefinita, l'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 sono pertinenti ai contenuti dell'app:

• ACTION_SKIP_TO_PREVIOUS
• ACTION_SKIP_TO_NEXT

Inoltre, puoi creare facoltativamente una coda di riproduzione da visualizzare per l'utente. Per farlo, chiama i metodi setQueue e setQueueTitle, attiva l'azione ACTION_SKIP_TO_QUEUE_ITEM e definisci il callback onSkipToQueueItem.

Inoltre, aggiungi il supporto per l'icona Now Playing, che indica i contenuti in riproduzione. Per farlo, chiama il metodo setActiveQueueItemId e trasmetti l'ID dell'elemento in riproduzione nella coda. Devi aggiornare setActiveQueueItemId ogni volta che viene modificata una coda.

Nota: l'aggiunta del supporto per un'icona In riproduzione è necessaria solo quando si supporta una coda di riproduzione.

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 il 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 quando la tua app non supporta la funzione corrispondente.

Per farlo, chiama il metodo setExtras con un pacchetto di componenti aggiuntivi che contiene costanti corrispondenti alle funzioni riservate. SESSION_EXTRAS_KEY_SLOT_RESERVATION_SKIP_TO_NEXT corrisponde a ACTION_SKIP_TO_NEXT e SESSION_EXTRAS_KEY_SLOT_RESERVATION_SKIP_TO_PREV corrisponde a ACTION_SKIP_TO_PREVIOUS. Utilizza queste costanti come chiavi nel bundle e utilizza il valore booleano true come valori.

Imposta PlaybackState iniziale

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

L'app non deve avviare automaticamente la riproduzione di musica quando AAOS o Android Auto si connette al servizio di navigazione 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 l'PlaybackStateCompat iniziale della sessione multimediale su STATE_STOPPED, STATE_PAUSED, STATE_NONE o STATE_ERROR.

Nota: quando PlaybackStateCompat è impostato su STATE_NONE, l'interfaccia utente di riproduzione di Android Auto e AAOS diventa inaccessibile. Invia questo stato solo quando l'app non ha nulla da riprodurre e l'utente deve selezionare nuovi contenuti per avviare la riproduzione.

Le sessioni multimediali in Android Auto e AAOS durano solo per la durata del viaggio, quindi gli utenti le avviano e le interrompono di frequente. Per promuovere un'esperienza fluida tra una guida e l'altra, 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. Ad esempio, l'ultimo elemento multimediale riprodotto, il 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 prenoti), Android aggiunge le azioni personalizzate ai controlli di trasporto. In caso contrario, le azioni personalizzate vengono visualizzate nel menu Altro. Android mostra le azioni personalizzate nell'ordine in cui le aggiungi a PlaybackStateCompat.

Utilizza le azioni personalizzate per fornire un comportamento diverso dalle azioni standard. Non utilizzarli per sostituire o duplicare le azioni standard.

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

Kotlin

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

Java

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 metodo setCustomAction 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":

Kotlin

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

Java

@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 di questa icona corrisponde a una delle costanti CommandButton.ICON_, imposta il valore intero per la chiave EXTRAS_KEY_COMMAND_BUTTON_ICON_COMPAT degli extra dell'azione personalizzata. Sui sistemi supportati, questa operazione sostituisce la risorsa icona passata a CustomAction.Builder, consentendo ai componenti di sistema di eseguire il rendering in modo coerente dell'azione e di altre azioni di riproduzione.

Devi anche specificare una risorsa icona. Le app nelle auto possono essere eseguite su schermi di dimensioni e densità diverse, pertanto le icone che fornisci devono essere risorse grafiche vettoriali. Utilizza una risorsa drawable 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 è stateful (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.

Fornisci stili di icone alternativi per le azioni disattivate

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

Figura 1. Esempi di icone di azioni personalizzate fuori stile.

Indica il formato audio

Per indicare che il media in riproduzione utilizza un formato audio speciale, puoi specificare le icone da visualizzare nelle auto che supportano questa funzionalità. Puoi impostare KEY_CONTENT_FORMAT_TINTABLE_LARGE_ICON_URI e KEY_CONTENT_FORMAT_TINTABLE_SMALL_ICON_URI nel bundle di contenuti aggiuntivi dell'elemento multimediale attualmente in riproduzione (trasmesso a MediaSession.setMetadata). Imposta entrambi i contenuti aggiuntivi in modo da adattarsi ai diversi layout.

Inoltre, puoi impostare l'extra KEY_IMMERSIVE_AUDIO per comunicare ai produttori 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 i sottotitoli codificati, la descrizione o entrambi siano link ad altri elementi multimediali. In questo modo, l'utente può passare rapidamente a elementi correlati, ad esempio ad altre canzoni 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 dai sottotitoli) 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.