Controllo dei contenuti multimediali tramite MediaSession

1. Introduzione

Ultimo aggiornamento: 2020-09-09

Quali sono i vantaggi dell'aggiunta di MediaSession per la riproduzione dei video?

Le sessioni multimediali sono un collegamento integrale tra la piattaforma Android e le app multimediali. Non solo informa Android che i contenuti multimediali sono in riproduzione, in modo da poter inoltrare le azioni multimediali alla sessione corretta, ma informa anche la piattaforma su cosa viene riprodotto e come può essere controllato.

L'esposizione di una sessione MediaSession tramite l'app offre diversi vantaggi agli utenti. Ecco alcuni ottimi esempi.

Assistente Google

Gli utenti possono interagire facilmente con i contenuti multimediali nella tua app tramite comandi vocali, ad esempio "Metti in pausa". "Riprendi" e "Avanti". Puoi anche usare i metadati dei tuoi contenuti multimediali per ricevere risposte sui contenuti in riproduzione.

Android TV

Sullo schermo di casa, l'app Android TV può usare telecomandi convenzionali per gli utenti con TV che supportano la tecnologia HDMI-CEC. I comandi emessi dai pulsanti riproduci/metti in pausa, interrompi, avanti e indietro vengono inoltrati all'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 l'artwork. Questo comportamento varia in base alla versione di Android.

Contenuti multimediali in background

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

Computing ambientale

L'esposizione ai tuoi contenuti multimediali di dati relativi alla riproduzione e al modo in cui può essere controllato può creare un collegamento tra i dispositivi, in modo che gli utenti possano interagire con i contenuti in vari modi a loro piacere.

Cosa creerai

In questo codelab, estenderai l'esempio di Exoplayer esistente per aggiungere il supporto delle sessioni multimediali. La tua app sarà in grado di:

• Rifletti correttamente lo stato attivo della sessione multimediale
• Inoltrare controlli multimediali a ExoPlayer
• Trasmettere i metadati degli elementi in coda alla sessione multimediale

Cosa imparerai a fare

• Perché le sessioni multimediali offrono agli utenti un'esperienza più completa
• 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 altre azioni (personalizzate)

Questo codelab è incentrato sull'SDK MediaSession. I concetti e i 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 app 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 posto per noi per tuffarci e aggiungerli!

Ottenere l'esempio di ExoPlayer

Per iniziare, iniziamo con l'esempio di ExoPlayer. Clona il repository GitHub eseguendo il codice seguente.

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

Apri la demo

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

Android Studio ti chiederà di impostare il percorso dell'SDK. In caso di problemi, ti consigliamo di seguire i consigli per l'aggiornamento degli strumenti IDE e SDK.

Se ti viene chiesto di utilizzare l'ultima versione di Gradle, aggiornala.

Prenditi un momento per acquisire una conoscenza di base di come è progettata l'app. Tieni presente che sono presenti due attività: SampleChooserActivity e PlayerActivity. Spenderemo il resto del codelab in PlayerActivity, dove i contenuti multimediali vengono effettivamente riprodotti, quindi apri questa lezione e passa alla sezione successiva.

3. Creare una sessione multimediale e gestirne lo stato

Creare la sessione multimediale

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

Dichiara i due campi seguenti all'inizio del corso. Useremo questi campi in questa sezione.

private MediaSessionCompat mediaSession;
private MediaSessionConnector mediaSessionConnector;

Dovrai aggiungere il parametro "extension-mediasession" del progetto nell'elemento build.gradle a livello di modulo per "Module: 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 di 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. Questo corso fa parte della libreria media-compat, consigliata per la scrittura di app multimediali.

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

Il punto ideale per inserire questa risorsa è il punto in cui viene creato anche ExoPlayer. Nell'app demo, possiamo aggiungere il codice alla fine di initializePlayer(). Assicurati di aggiungere questa logica dopo aver creato l'istanza del player.

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

Pubblicare la sessione multimediale

Rilascia la sessione multimediale quando non è più necessaria. Quando rilasciamo ExoPlayer in releasePlayer(), possiamo 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 per la sessione multimediale, dobbiamo assicurarci che il suo stato si rifletta correttamente quando 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 abbandona l'attività:

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

Attenzione:se una sessione multimediale non viene impostata su inattiva, gli utenti potrebbero avere risultati indesiderati. Ad esempio, se ExoPlayer viene rilasciato quando un utente esce da un'attività, i controlli di riproduzione non utilizzabili potrebbero comunque essere visualizzati nella schermata di blocco dell'utente.

Nota:per saperne di più sull'interazione tra il controller multimediale e la sessione multimediale, consulta la guida panoramica sull'architettura delle app multimediali.

Eseguiamo la demo

1. Collega un dispositivo Android o avvia un emulatore.
2. Assicurati che la "demo" sia selezionata per eseguirla 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 lo stream video da riprodurre.
5. Dopo l'avvio della riproduzione, prova a usare i seguenti comandi di 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 dispositivo non supporta questi comandi, prova a usare un emulatore.

6. Scopri anche come Android vede la tua sessione multimediale. In particolare, puoi controllare quali azioni sono supportate esaminando il campo delle azioni. Il numero che vedi 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 inviare comandi vocali, ad esempio "Metti in pausa". "Riprendi." "Avanti veloce 1 minuto."

Esempio di ExoPlayer in esecuzione su Android TV.

Nota: i comandi vocali tramite l'Assistente Google potrebbero funzionare solo su Android TV o se la riproduzione dei contenuti multimediali continua in background mentre la sessione multimediale rimane attiva.

4. Inclusione dei metadati degli elementi nella coda di riproduzione

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

Aggiunta di un Spostamenti nella coda

ExoPlayer rappresenta la struttura dei contenuti multimediali come una sequenza temporale. Per informazioni dettagliate su come funziona, leggi informazioni sull'oggetto Timeline di ExoPlayer. Grazie a questa struttura, possiamo essere informati quando i contenuti vengono modificati e visualizzare i metadati di ciò che è attualmente in riproduzione quando richiesto.

A questo scopo, definiamo Spostamenti Coda di navigazione. Individua la creazione di un'istanza di MediaSessionConnector in initializePlayer() e aggiungi un'implementazione di SpostamentiQueueNavigator dopo che mediaSession è stata inizializzata.

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 è null, l'Assistente Google non sarà in grado di estrarre queste informazioni da MediaDescription.

Risolvi le importazioni delle classi aggiungendo:

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

Osserva 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 player. Nella demo fornita, puoi selezionare un esempio di playlist dall'attività di selezione campione, che utilizza un ConcatenatingMediaSource.

Ora che hai aggiunto alcuni metadati, puoi verificare che l'assistente capisca i contenuti in riproduzione. Durante la riproduzione di un video su Android TV, richiama l'assistente e chiedi "Cosa sto ascoltando?".

5. Personalizzazione delle azioni

Forse il tuo player non supporta alcune azioni oppure vorresti includere il supporto di altre azioni? Approfondiamo un po' la sessione multimediale in cui abbiamo precedentemente creato il nostro MediaSessionConnector nel initializePlayer().

Dichiarare le azioni supportate

Prova a usare mediaSessionConnector.setEnabledPlaybackActions() per personalizzare le azioni che la sessione multimediale deve supportare.

Tieni presente che l'insieme 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. Scopri come Android vede i metadati della tua 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.

Aggiunta di altre azioni

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

Sottotitoli codificati di supporto

L'aggiunta del supporto per i sottotitoli codificati alle sessioni multimediali consente agli utenti di attivarli/disattivarli con la voce. Dove hai inizializzato il connettore di 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, correggi eventuali importazioni mancanti.

Puoi verificarlo richiamando l'Assistente Google su Android TV e dicendo "Attiva i sottotitoli". Controlla se in Logcat sono presenti messaggi per vedere come questo comporta la ricezione del tuo codice.

Nota: quando restituisci false da hasCaptions(), l'assistente comunicherà agli utenti che i sottotitoli non sono supportati.

6. Complimenti

Congratulazioni, hai aggiunto correttamente le sessioni multimediali all'anteprima.

Hai ottenuto un'enorme quantità di funzionalità grazie a:

• l'aggiunta di una sessione multimediale,
• connettendo 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 osservazione finale

Questo codelab è stato creato su un esempio del codice sorgente ExoPlayer. Non è necessario utilizzare ExoPlayer dal codice sorgente e ti consigliamo invece di eseguire il pull delle dipendenze per ExoPlayer e MediaSessionConnector in modo che sia più facile rimanere sempre aggiornati con le release più recenti.

Per farlo, basta sostituire le dipendenze del progetto come:

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

per eseguire il pull dai repository Maven, come:

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

Documenti di riferimento

• Utilizzare una sessione multimediale
• Panoramica dell'architettura delle app multimediali
• Struttura della sequenza temporale di ExoPlayer
• Guida per gli sviluppatori di ExoPlayer
• Riferimento API MediaSessionConnector di ExoPlayer