Utilizzare una sessione multimediale

Le sessioni multimediali forniscono un modo universale di interagire con un video player o un lettore audio. Informando Android che i contenuti multimediali sono in riproduzione in un'app, i controlli di riproduzione possono essere delegati all'app. L'integrazione con la sessione multimediale consente a un'app di pubblicizzare la riproduzione di contenuti multimediali esternamente e di ricevere comandi di riproduzione da fonti esterne. Queste sorgenti possono essere pulsanti fisici (come il pulsante di riproduzione su un telecomando TV per cuffie o TV) o comandi indiretti (come l'istruzione "metti in pausa" all'Assistente Google). La sessione multimediale delega quindi questi comandi all'app che li applica al media player, per il quale l'origine dei comandi è trasparente.

Una sessione multimediale esiste insieme al player che gestisce. Devi creare e inizializzare una sessione multimediale nel metodo onCreate() dell'attività o del servizio proprietario della sessione multimediale e del relativo player associato.

Inizializza la sessione multimediale

Una sessione multimediale appena creata non ha funzionalità. Devi inizializzare la sessione seguendo questi passaggi:

  • Imposta i flag in modo che la sessione multimediale possa ricevere callback dai controller e dai pulsanti multimediali.
  • Crea e inizializza un'istanza di PlaybackStateCompat e assegnala alla sessione. Lo stato di riproduzione cambia nel corso della sessione, quindi ti consigliamo di memorizzare nella cache PlaybackStateCompat.Builder per riutilizzarlo.
  • Crea un'istanza di MediaSessionCompat.Callback e assegnala alla sessione (maggiori informazioni sui callback di seguito).

Devi creare e inizializzare una sessione multimediale nel metodo onCreate() dell'attività o del servizio proprietario della sessione.

Affinché i pulsanti multimediali funzionino quando l'app viene inizializzata (o interrotta), il relativo PlaybackState deve contenere un'azione di riproduzione corrispondente all'intent inviato dal pulsante multimediale. Ecco perché ACTION_PLAY viene assegnato allo stato della sessione durante l'inizializzazione. Per saperne di più, consulta Risposta ai pulsanti multimediali.

Mantieni lo stato di riproduzione e i metadati

Esistono due classi che rappresentano lo stato di una sessione multimediale.

La classe PlaybackStateCompat descrive lo stato operativo attuale del player. È incluso quanto segue:

  • Lo stato di trasporto (se il player è in riproduzione/pausa/buffering e così via. Consulta getState())
  • Un codice di errore e un messaggio di errore facoltativo, se applicabile. (consulta getErrorCode() e leggi Stati ed errori di seguito).
  • La posizione del giocatore
  • Le azioni del controller valide che possono essere gestite nello stato attuale

La classe MediaMetadataCompat descrive il materiale in riproduzione:

  • Il nome dell'artista, dell'album e della traccia
  • La durata della traccia
  • Copertina dell'album da visualizzare nella schermata di blocco. L'immagine è una bitmap con una dimensione massima di 320 x 320 dp (se è più grande, viene ridotta).
  • Un'istanza di ContentUris che rimanda a una versione più grande dell'artwork

Lo stato e i metadati del player possono cambiare nel corso di una sessione multimediale. Ogni volta che lo stato o i metadati cambiano, devi utilizzare il builder corrispondente per ogni classe, PlaybackStateCompat.Builder() o MediaMetadataCompat.Builder(), e poi passare la nuova istanza alla sessione multimediale chiamando setPlaybackState() o setMetaData(). Per ridurre il consumo complessivo di memoria dovuto a queste operazioni frequenti, è consigliabile creare i builder una sola volta e riutilizzarli per tutta la durata della sessione.

Stati ed errori

Tieni presente che PlaybackState è un oggetto che contiene valori separati per lo stato di riproduzione della sessione (getState()) e, se necessario, un codice di errore associato (getErrorCode()). Gli errori possono essere irreversibili o non irreversibili:

Ogni volta che la riproduzione viene interrotta, devi generare un errore irreversibile: imposta lo stato di trasporto su STATE_ERROR e specifica un errore associato con setErrorMessage(int, CharSequence). Finché la riproduzione è bloccata dall'errore, PlaybackState deve continuare a segnalare STATE_ERROR e l'errore.

Un errore non irreversibile si verifica quando l'app non può gestire una richiesta, ma può continuare a riprodurre: il trasporto rimane in uno stato "normale" (ad esempio STATE_PLAYING), ma PlaybackState contiene un codice di errore. Ad esempio, se è in riproduzione l'ultimo brano e l'utente richiede di passare al brano successivo, la riproduzione può continuare, ma devi creare un nuovo PlaybackState con il codice di errore ERROR_CODE_END_OF_QUEUE e poi chiamare setPlaybackState(). I controller multimediali collegati alla sessione riceveranno il callback onPlaybackStateChanged() e spiegheranno all'utente cosa è successo. Un errore non irreversibile deve essere segnalato una sola volta, nel momento in cui si verifica. La volta successiva che la sessione aggiorna PlaybackState, non impostare di nuovo lo stesso errore non irreversibile (a meno che l'errore non si sia verificato in risposta a una nuova richiesta).

Schermate di blocco delle sessioni multimediali

A partire da Android 4.0 (livello API 14), il sistema può accedere allo stato di riproduzione e ai metadati di una sessione multimediale. Ecco come la schermata di blocco può mostrare i controlli multimediali e le immagini. Il comportamento varia a seconda della versione di Android.

Copertina dell'album

In Android 4.0 (livello API 14) fino ad Android 10 (livello API 29), lo sfondo della schermata di blocco mostra la copertina dell'album, ma solo se i metadati della sessione multimediale includono una bitmap di sfondo.

Controlli di trasporto

In Android 4.0 (livello API 14) fino ad Android 4.4 (livello API 19), quando una sessione multimediale è attiva e i metadati della sessione multimediale includono una bitmap di sfondo, la schermata di blocco mostra automaticamente i controlli di trasporto.

In Android 5.0 (livello API 21) o versioni successive, il sistema non fornisce controlli di trasporto nella schermata di blocco. Devi invece utilizzare una notifica MediaStyle per visualizzare i controlli di trasporto.

Aggiungi azioni personalizzate

Le applicazioni multimediali possono definire azioni personalizzate, ad esempio: Mi piace, Mi piace o Riavvolgi di 30 secondi. Un'azione personalizzata deve implementare un comportamento completamente nuovo. Non utilizzare un'azione personalizzata per sostituire una delle azioni di controllo del trasporto standard definite in PlaybackStateCompat.

Aggiungi azioni personalizzate con addCustomAction(). L'esempio seguente mostra come aggiungere un controllo per un'azione Mi piace:

Kotlin

stateBuilder.addCustomAction(
        PlaybackStateCompat.CustomAction.Builder(
                CUSTOM_ACTION_THUMBS_UP,
                resources.getString(R.string.thumbs_up),
                thumbsUpIcon
        ).run {
            setExtras(customActionExtras)
            build()
        }
)

Java

stateBuilder.addCustomAction(new PlaybackStateCompat.CustomAction.Builder(
    CUSTOM_ACTION_THUMBS_UP, resources.getString(R.string.thumbs_up), thumbsUpIcon)
    .setExtras(customActionExtras)
    .build());

Per un esempio completo, consulta Universal Music Player.

Rispondi all'azione con onCustomAction().

Kotlin

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

Java

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

Consulta anche Universal Music Player.

Callback delle sessioni multimediali

I principali metodi di callback della sessione multimediale sono onPlay(), onPause() e onStop(). Qui è dove aggiungi il codice che controlla il tuo player.

Poiché crei un'istanza e imposti il callback della sessione in fase di runtime (in onCreate()), la tua app può definire callback alternativi che utilizzano player diversi e scegliere la combinazione appropriata di callback e player a seconda del dispositivo e del livello di sistema. Puoi cambiare il player senza modificare il resto dell'app. Ad esempio, puoi utilizzare ExoPlayer su Android 4.1 (livello API 16) o versioni successive e MediaPlayer su sistemi precedenti.

Oltre a controllare il player e gestire le transizioni di stato della sessione multimediale, i callback attivano e disattivano anche le funzionalità della tua app e controllano il modo in cui interagisce con altre app e con l'hardware del dispositivo. (Vedi Controllo dell'output audio).

L'implementazione dei metodi di callback della sessione multimediale dipende dalla struttura della tua app. Consulta le pagine separate che descrivono come utilizzare i callback nelle app audio e nelle app video, che descrivono come implementare i callback per ogni tipo di app.