Controllo dei contenuti multimediali tramite MediaSession

1. Introduzione

Ultimo aggiornamento: 09/09/2020

Quali sono i vantaggi dell'aggiunta di una MediaSession durante la riproduzione video?

Le sessioni multimediali sono un collegamento fondamentale tra la piattaforma Android e le app multimediali. Non solo informa Android che i contenuti multimediali vengono riprodotti, in modo che possa inoltrare le azioni multimediali nella sessione corretta, ma informa anche la piattaforma di cosa viene riprodotto e di come può essere controllato.

L'esposizione di una MediaSession tramite la tua app offre vari vantaggi per gli utenti. Ecco alcuni ottimi esempi.

Assistente Google

Gli utenti possono interagire facilmente con i contenuti multimediali nella tua app tramite comandi vocali come "Metti in pausa", "Riprendi" e "Avanti". I metadati dei tuoi contenuti multimediali possono essere utilizzati anche per ottenere risposte su ciò che è attualmente in riproduzione.

Android TV

Nelle esperienze su schermo di casa, l'app per Android TV può utilizzare i telecomandi convenzionali per gli utenti con TV che supportano HDMI-CEC. I comandi emessi dai pulsanti Riproduci/Pausa, Stop, Avanti e Indietro vengono trasmessi alla tua app.

Controlli multimediali sullo schermo

A partire da Android 4.0 (livello API 14), il sistema può accedere allo stato di riproduzione e ai metadati di una sessione multimediale. Questa funzionalità consente alla schermata di blocco di visualizzare i controlli multimediali e le copertine. Questo comportamento varia a seconda della versione di Android.

Background media

I contenuti multimediali possono essere controllati in uno qualsiasi di questi scenari anche se l'app che li riproduce è in esecuzione in background.

Ambient computing

L'esposizione dei tuoi contenuti multimediali con dati su cosa viene riprodotto e su come possono essere controllati può creare un ponte tra i dispositivi, in modo che gli utenti possano interagire con loro in vari modi.

Cosa creerai

In questo codelab, estenderai l'esempio di ExoPlayer esistente per aggiungere il supporto della sessione multimediale. La tua app sarà in grado di:

• Riflettere correttamente lo stato attivo della sessione multimediale
• Inoltrare i controlli multimediali a ExoPlayer
• Trasferire i metadati degli elementi in coda nella sessione multimediale

Cosa imparerai a fare

• Perché le sessioni multimediali offrono agli utenti un'esperienza più ricca
• Come creare una sessione multimediale e gestirne lo stato
• Come connettere una sessione multimediale a ExoPlayer
• Come includere i metadati degli elementi nella coda di riproduzione nella sessione multimediale
• Come aggiungere azioni aggiuntive (personalizzate)

Questo codelab si concentra sull'SDK MediaSession. Concetti e blocchi di codice non pertinenti, inclusi i dettagli sull'implementazione di ExoPlayer, non vengono trattati, ma sono forniti solo per operazioni di copia e incolla.

Che cosa ti serve

• Una versione recente di Android Studio (3.5 o versioni successive)
• Conoscenza di base dello sviluppo di applicazioni per Android

2. Preparazione

Qual è il nostro punto di partenza?

Il nostro punto di partenza è la demo principale di ExoPlayer. Questa demo contiene video con controlli di riproduzione sullo schermo, ma non utilizza sessioni multimediali predefinite. È un ottimo punto di partenza per aggiungerli.

Ottieni l'esempio di ExoPlayer

Per iniziare subito, cominciamo con l'esempio di ExoPlayer. Clona il repository GitHub eseguendo il codice riportato di seguito.

git clone https://github.com/google/ExoPlayer.git

Apri la demo

In Android Studio, apri il progetto demo principale che si trova in demos/main.

Android Studio ti chiederà di impostare il percorso dell'SDK. Se riscontri problemi, ti consigliamo di seguire i suggerimenti per aggiornare l'IDE e gli strumenti SDK.

Se ti viene chiesto di utilizzare l'ultima versione di Gradle, procedi con l'aggiornamento.

Prenditi un momento per comprendere le nozioni di base su come è progettata l'app. Tieni presente che esistono due attività: SampleChooserActivity e PlayerActivity. Trascorreremo il resto del codelab in PlayerActivity, dove vengono riprodotti i contenuti multimediali, quindi apri questa classe e vai alla sezione successiva.

3. Creare una sessione multimediale e gestirne lo stato

Crea la sessione multimediale

Apri PlayerActivity.java. Questa classe crea ExoPlayer e ne gestisce le funzioni, come il rendering del video sullo schermo. In questa attività, collegheremo ExoPlayer a una sessione multimediale.

Dichiara i due campi seguenti nella parte superiore della classe. Utilizzeremo questi campi in tutta questa sezione.

private MediaSessionCompat mediaSession;
private MediaSessionConnector mediaSessionConnector;

Dovrai aggiungere la dipendenza del progetto "extension-mediasession" al file build.gradle a livello di modulo per "Modulo: demo":

implementation project(path: ':extension-mediasession')

Tieni presente che Android Studio può aiutarti ad aggiungere automaticamente questa dipendenza se passi il mouse sopra l'errore relativo alla risoluzione di MediaSessionConnector:

Infine, risolvi le importazioni delle classi aggiungendo quanto segue:

import android.support.v4.media.session.MediaSessionCompat;
import com.google.android.exoplayer2.ext.mediasession.MediaSessionConnector;

Nota:in questo codelab, il termine "sessione multimediale" indica un'istanza di MediaSessionCompat. Questa classe proviene dalla libreria media-compat, consigliata per la scrittura di app multimediali.

Quando viene creata l'attività, vogliamo creare una sessione multimediale e un connettore della sessione multimediale che funga da intermediario tra la sessione multimediale ed ExoPlayer.

Il punto ideale per inserire questo codice è dove viene creato anche ExoPlayer. Nella nostra app demo, possiamo aggiungere il nostro codice alla fine di initializePlayer(). Assicurati di aggiungere questa logica dopo l'istanza del player.

private void initializePlayer() {
  if (player == null) {
    ...
    player = ...
    ...
    mediaSession = new MediaSessionCompat(this, "sample");
    mediaSessionConnector = new MediaSessionConnector(mediaSession);
    mediaSessionConnector.setPlayer(player);
  }
  ...
}

Rilasciare la sessione multimediale

Rilascia la sessione multimediale quando non è più necessaria. Quando rilasceremo ExoPlayer in releasePlayer(), potremo includere anche il seguente codice:

private void releasePlayer() {
  if (mediaSession != null) {
    mediaSession.release();
  }
  ...
}

Gestire lo stato della sessione multimediale

Ora che abbiamo creato un'istanza della sessione multimediale, dobbiamo assicurarci che il suo stato venga riflesso correttamente man mano che l'utente interagisce con l'attività.

Quando l'utente avvia l'attività, la sessione multimediale deve diventare attiva:

@Override
public void onStart() {
  ...
  if (mediaSession != null) {
    mediaSession.setActive(true);
  }
}

Poiché la nostra applicazione non riproduce contenuti multimediali in background, è essenziale assicurarsi che la sessione multimediale diventi inattiva quando l'utente esce dall'attività:

@Override
public void onStop() {
  super.onStop();
  if (mediaSession != null) {
    mediaSession.setActive(false);
  }
  ...
}

Attenzione:se non imposti una sessione multimediale su Inattiva, potresti ottenere risultati indesiderati per gli utenti. Ad esempio, se ExoPlayer viene rilasciato quando un utente esce da un'attività, i controlli di riproduzione non funzionanti potrebbero comunque essere visualizzati nella schermata di blocco dell'utente.

Nota: per scoprire di più su come funzionano insieme il controller multimediale e la sessione multimediale, consulta la guida alla panoramica dell'architettura delle app multimediali.

Eseguiamo la demo

1. Collega un dispositivo Android o avvia un emulatore.
2. Assicurati che "demo" sia selezionato per l'esecuzione dalla barra degli strumenti di Android Studio.
3. Fai clic su nella barra degli strumenti di Android Studio.
4. Una volta avviata l'app sul dispositivo, seleziona uno stream video da riprodurre.
5. Una volta avviata la riproduzione, esplora i seguenti comandi adb per controllare la sessione multimediale:

adb shell media dispatch pause
adb shell media dispatch play
adb shell media dispatch play-pause
adb shell media dispatch fast-forward
adb shell media dispatch rewind

Nota:se il tuo dispositivo non supporta questi comandi, prova a utilizzare un emulatore.

6. Scopri anche come Android vede la tua sessione multimediale. In particolare, puoi controllare quali azioni sono supportate esaminando il campo Azione. Il numero visualizzato qui è una combinazione di ID azione, come dichiarato nell'oggetto PlaybackState. Per vedere l'esecuzione della sessione multimediale: adb shell dumpsys media_session
7. Se utilizzi un dispositivo fisico con un microfono, prova a richiamare l'Assistente Google e a dare comandi vocali, ad esempio "Metti in pausa". "Riprendi." "Vai avanti di 1 minuto."

Esempio di ExoPlayer in esecuzione su Android TV.

Nota:l'utilizzo dei comandi vocali tramite l'Assistente Google potrebbe funzionare solo su Android TV o se i contenuti multimediali continuano a essere riprodotti in background con la sessione multimediale attiva.

4. Includere i metadati degli elementi nella coda di riproduzione

Ora possiamo espandere le funzionalità supportate della nostra sessione multimediale in cui avevamo creato in precedenza il nostro MediaSessionConnector in initializePlayer().

Aggiunta di un TimelineQueueNavigator

ExoPlayer rappresenta la struttura dei contenuti multimediali come una sequenza temporale. Per informazioni dettagliate sul funzionamento, leggi l'articolo sull'oggetto Timeline di ExoPlayer. Sfruttando questa struttura, possiamo essere informati quando i contenuti cambiano ed esporre i metadati di ciò che viene riprodotto al momento della richiesta.

A questo scopo, definiremo un TimelineQueueNavigator. Individua l'istanza di MediaSessionConnector in initializePlayer() e aggiungi un'implementazione di TimelineQueueNavigator dopo l'inizializzazione di mediaSession.

mediaSessionConnector.setQueueNavigator(new TimelineQueueNavigator(mediaSession) {
  @Override
  public MediaDescriptionCompat getMediaDescription(Player player, int windowIndex) {
    return new MediaDescriptionCompat.Builder()
            .setTitle(player.getCurrentMediaItem().mediaMetadata.title)
            .setDescription("MediaDescription description for " + windowIndex)
            .setSubtitle("MediaDescription subtitle")
            .build();
  }
});

Nota:se il titolo fornito qui è nullo, l'Assistente Google non sarà in grado di estrarre queste informazioni da MediaDescription.

Risolvi i problemi di importazione dei corsi aggiungendo:

import android.support.v4.media.MediaDescriptionCompat;
import com.google.android.exoplayer2.ext.mediasession.TimelineQueueNavigator;

Nota che il parametro windowIndex corrisponde all'elemento di quell'indice nella coda di riproduzione.

Nota:i contenuti di questa coda sono determinati dall'origine multimediale del tuo lettore. Nella demo fornita, è possibile selezionare un esempio di playlist dall'attività di selezione del campione, che utilizza un ConcatenatingMediaSource.

Ora che hai aggiunto alcuni metadati, puoi verificare che l'assistente comprenda cosa viene riprodotto. Mentre riproduci un video su Android TV, invoca l'assistente e chiedi "Cosa c'è in riproduzione?"

5. Personalizzare le azioni

Forse il tuo lettore non supporta alcune azioni o vorresti includere il supporto per altre? Ora approfondiamo la sessione multimediale in cui avevamo creato in precedenza il nostro MediaSessionConnector in initializePlayer().

Dichiarare le azioni supportate

Prova a utilizzare mediaSessionConnector.setEnabledPlaybackActions() per personalizzare le azioni che vuoi che la sessione multimediale supporti.

Tieni presente che il set completo è:

mediaSessionConnector.setEnabledPlaybackActions(
        PlaybackStateCompat.ACTION_PLAY_PAUSE
                | PlaybackStateCompat.ACTION_PLAY
                | PlaybackStateCompat.ACTION_PAUSE
                | PlaybackStateCompat.ACTION_SEEK_TO
                | PlaybackStateCompat.ACTION_FAST_FORWARD
                | PlaybackStateCompat.ACTION_REWIND
                | PlaybackStateCompat.ACTION_STOP
                | PlaybackStateCompat.ACTION_SET_REPEAT_MODE
                | PlaybackStateCompat.ACTION_SET_SHUFFLE_MODE
);

Vediamo di nuovo come vengono esposti questi dati alla piattaforma:

1. Come prima, avvia un video.
2. Esplora il modo in cui Android visualizza i metadati della sessione multimediale eseguendo: adb shell dumpsys media_session
3. Individua la riga contenente i metadati e osserva che il titolo e la descrizione sono inclusi e associati a com.google.android.exoplayer2.demo/sample.

Aggiungere azioni aggiuntive

Possiamo espandere la sessione multimediale con alcune azioni aggiuntive. In questa sezione aggiungeremo solo il supporto per i sottotitoli codificati.

Sottotitoli codificati di supporto

L'aggiunta del supporto dei sottotitoli codificati alle sessioni multimediali consente agli utenti di attivarli e disattivarli con i comandi vocali. Dove hai inizializzato il connettore della sessione multimediale, aggiungi quanto segue:

mediaSessionConnector.setCaptionCallback(new MediaSessionConnector.CaptionCallback() {
      @Override
      public void onSetCaptioningEnabled(Player player, boolean enabled) {
        Log.d("MediaSession", "onSetCaptioningEnabled: enabled=" + enabled);
      }

      @Override
      public boolean hasCaptions(Player player) {
        return true;
      }

      @Override
      public boolean onCommand(Player player, ControlDispatcher controlDispatcher, String command, Bundle extras, ResultReceiver cb) {
        return false;
      }
    }
);

Infine, risolvi eventuali importazioni mancanti.

Puoi verificare attivando l'Assistente Google su Android TV e dicendo "Attiva i sottotitoli codificati". Controlla Logcat per i messaggi per vedere come vengono chiamati nel tuo codice.

Nota:l'assistente informerà gli utenti che i sottotitoli codificati non sono supportati quando restituisci il valore false da hasCaptions().

6. Complimenti

Complimenti, hai aggiunto correttamente le sessioni multimediali all'esempio.

Hai ottenuto una quantità enorme di funzionalità:

• aggiungendo una sessione multimediale,
• collegando le sessioni multimediali a un'istanza di ExoPlayer,
• aggiungendo metadati e azioni aggiuntive.

Ora conosci i passaggi chiave necessari per arricchire un'app multimediale e offrire agli utenti un'esperienza più versatile.

Un ultimo commento

Questo codelab è stato creato a partire da un esempio del codice sorgente di ExoPlayer. Non è necessario utilizzare ExoPlayer dall'origine ed è consigliabile estrarre le dipendenze per ExoPlayer e MediaSessionConnector in modo da rimanere aggiornati più facilmente con le ultime versioni.

Per farlo, sostituisci le dipendenze del progetto, ad esempio:

implementation project(modulePrefix + 'library-core')
implementation project(path: ':extension-mediasession')

per eseguire il pull dai repository Maven, ad esempio:

implementation 'com.google.android.exoplayer:exoplayer-core:2.+'
implementation 'com.google.android.exoplayer:extension-mediasession:2.+'

Documentazione di riferimento

• Utilizzo di una sessione multimediale
• Panoramica dell'architettura dell'app multimediale
• Struttura della cronologia di ExoPlayer
• Guida per gli sviluppatori di ExoPlayer
• Riferimento API MediaSessionConnector di ExoPlayer