Utilizzare una sessione multimediale

Le sessioni multimediali offrono un modo universale di interagire con un audio o un video un player. Se comunichi ad Android che i contenuti multimediali sono in riproduzione in un'app, la riproduzione i controlli possono essere delegati all'app. L'integrazione con la sessione multimediale consente un'app per pubblicizzare la riproduzione di contenuti multimediali esternamente e per ricevere comandi di riproduzione da fonti esterne. Queste sorgenti possono essere pulsanti fisici (come il pulsante di riproduzione) su un paio di cuffie o un telecomando della TV) oppure comandi indiretti (come indicando "pausa" all'Assistente Google). La sessione multimediale delega quindi all'app che li applica al media player per cui trasparente da dove hanno avuto origine i comandi.

Una sessione multimediale si trova accanto al player che gestisce. Dovresti creare e inizializza una sessione multimediale nel metodo onCreate() dell'attività oppure servizio proprietario della sessione multimediale e del player associato.

Inizializzare la sessione multimediale

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

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

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

Affinché i pulsanti multimediali funzionino, quando l'app viene appena inizializzata (o arrestata), il relativo PlaybackState deve contengono un'azione di riproduzione corrispondente all'intent inviato dal pulsante multimediale. Questo è perché ACTION_PLAY viene assegnato allo stato della sessione durante durante l'inizializzazione. Per ulteriori informazioni, consulta Risposta ai contenuti multimediali. Pulsanti.

Mantenere lo stato di riproduzione e i metadati

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

La PlaybackStateCompat descrive l'attuale stato operativo del player. Ad esempio:

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

MediaMetadataCompat descrive il materiale in riproduzione:

  • Il nome dell'artista, dell'album e della traccia
  • Durata della traccia
  • Copertina dell'album da visualizzare nella schermata di blocco. L'immagine è una bitmap con dimensioni massime di 320 x 320 dp (se più grande, viene ridimensionato).
  • Un'istanza di ContentUris che punta 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 generatore corrispondente per ogni classe, PlaybackStateCompat.Builder() o MediaMetadataCompat.Builder(), quindi passare la nuova istanza alla sessione multimediale chiamando setPlaybackState() o setMetaData(). Per ridurre il consumo di memoria complessivo da queste operazioni frequenti, è consigliabile creare i builder una volta e riutilizzarli durante la vita della sessione.

Stati ed errori

Tieni presente che PlaybackState è un oggetto che contiene valori separati per il parametro 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 si interrompe, dovresti generare un errore irreversibile. Imposta il stato di trasporto a STATE_ERROR e specificare un errore associato a setErrorMessage(int, CharSequence). Se la riproduzione è bloccata dall'errore, PlaybackState dovrebbe continuare per segnalare STATE_ERROR e l'errore.

Un errore non irreversibile si verifica quando la tua app non riesce a gestire una richiesta, ma può continuare a riprodurre quanto segue: Il trasporto rimane in uno "normale" (ad esempio STATE_PLAYING), ma PlaybackState contiene un codice di errore. Ad esempio, se l'ultimo brano è in riproduzione 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 quindi chiama setPlaybackState(). I controller multimediali collegati alla sessione riceveranno il callback onPlaybackStateChanged() e spiega all'utente cosa è successo. Un errore non irreversibile deve essere segnalato una sola volta, nel momento in cui si verifica. Al successivo aggiornamento della sessione, PlaybackState non imposterà 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 alla lo stato di riproduzione e i metadati. Ecco come vengono visualizzati i controlli multimediali nella schermata di blocco e artwork. Il comportamento varia a seconda Versione di Android.

Copertina dell'album

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

Controlli per il trasporto

Da Android 4.0 (livello API 14) 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 visualizza automaticamente i controlli di trasporto.

In Android 5.0 (livello API 21) o versioni successive, il sistema non fornisce il trasporto nella schermata di blocco. Utilizza invece MediaStyle notifica 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 dovrebbe implementare un comportamento completamente nuovo. Cosa fare Non utilizzare un'azione personalizzata al posto di una delle azioni di controllo del trasporto standard definiti 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, vedi 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)) {
        ...
    }
}

Vedi anche Universal Music Player.

Callback delle sessioni multimediali

I principali metodi di callback delle sessioni multimediali sono onPlay(), onPause() e onStop(). Qui puoi aggiungere 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 usano giocatori diversi e scegliere la combinazione appropriata di callback/player in base al dispositivo e/o al livello di sistema. Puoi cambiare il player senza cambiare il resto dell'app. Ad esempio, puoi utilizzare ExoPlayer con Android 4.1 (livello API 16) o versioni successive e MediaPlayer sui sistemi precedenti.

Oltre a controllare il player e gestire le transizioni dello stato delle sessioni multimediali, i callback abilitano e disabilitano anche le funzionalità della tua app e controllano la sua modalità di interazione con altre app e con l'hardware del dispositivo. (vedi Controllo dell'uscita audio).

L'implementazione dei metodi di callback delle sessioni multimediali dipende dalla struttura della tua app. Consulta le pagine separate che descrivono come utilizzare i callback in app audio e app video, descrivere come implementare i callback per ogni tipo di app.