Applicazione demo ExoPlayer

L'app demo principale di ExoPlayer ha due scopi principali:

  1. Per fornire un esempio relativamente semplice ma completo dell'utilizzo di ExoPlayer. L'app demo può essere utilizzata come punto di partenza pratico per sviluppare la tua app.
  2. Per semplificare la prova di ExoPlayer. L'app demo può essere utilizzata per testare la riproduzione dei tuoi contenuti, oltre agli esempi inclusi.

Questa pagina descrive come scaricare, compilare ed eseguire l'app demo. Descrive anche come utilizzarla per riprodurre i tuoi contenuti multimediali.

Recupero del codice

Il codice sorgente dell'app demo principale si trova nella cartella demos/main del nostro progetto GitHub. Se non l'hai ancora fatto, clona il progetto in una directory locale:

git clone https://github.com/androidx/media.git

Dopodiché, apri il progetto in Android Studio. Dovresti visualizzare quanto segue nella visualizzazione Progetto Android (le cartelle pertinenti dell'app demo sono state espanse):

Il progetto in Android Studio

Compilazione ed esecuzione

Per compilare ed eseguire l'app demo, seleziona ed esegui la configurazione demo in Android Studio. L'app demo verrà installata ed eseguita su un dispositivo Android connesso. Se possibile, ti consigliamo di utilizzare un dispositivo fisico. Se preferisci utilizzare un emulatore, leggi la sezione relativa agli emulatori della pagina Dispositivi supportati e assicurati che il tuo dispositivo virtuale utilizzi un'immagine di sistema con un livello API almeno pari a 23.

SampleChooserActivity e PlayerActivity

L'app demo presenta un elenco di campioni (SampleChooserActivity). Se selezioni un campione, si apre una seconda attività (PlayerActivity) per la riproduzione. La demo include i controlli di riproduzione e la funzionalità di selezione delle tracce. Utilizza inoltre la classe di utilità EventLogger di ExoPlayer per restituire informazioni di debug utili al log di sistema. Questa registrazione può essere visualizzata (insieme alla registrazione del livello di errore per altri tag) con il comando:

adb logcat EventLogger:V *:E

Attivazione dei decodificatori in bundle

ExoPlayer dispone di una serie di estensioni che consentono l'utilizzo di decoder software in bundle, tra cui AV1, VP9, Opus, FLAC e FFmpeg (solo audio). L'app demo può essere creata per includere e utilizzare queste estensioni nel seguente modo:

  1. Crea ciascuna delle estensioni che vuoi includere. Tieni presente che si tratta di un processo manuale. Per istruzioni, consulta il file README.md in ogni estensione.

  2. Nella visualizzazione Varianti di build di Android Studio, imposta la variante di build per il modulo demo su withDecoderExtensionsDebug o withDecoderExtensionsRelease come mostrato nell'immagine seguente.

    Selezione della variante di build demo `withDecoderExtensionsDebug`

  3. Compila, installa ed esegui la configurazione di demo come di consueto.

Per impostazione predefinita, un decodificatore di estensione viene utilizzato solo se non esiste un decodificatore di piattaforma adatto. È possibile specificare che i decodificatori delle estensioni devono essere preferiti, come descritto nelle sezioni seguenti.

Riproduzione dei tuoi contenuti

Esistono diversi modi per riprodurre i tuoi contenuti nell'app demo.

1. Modifica di assets/media.exolist.json

Gli esempi elencati nell'app demo vengono caricati da assets/media.exolist.json. Modificando questo file JSON, è possibile aggiungere e rimuovere campioni dall'app demo. Lo schema è il seguente, dove [O] indica un attributo facoltativo.

[
  {
    "name": "Name of heading",
    "samples": [
      {
        "name": "Name of sample",
        "uri": "The URI of the sample",
        "extension": "[O] Sample type hint. Cannot be combined with mime_type. Values: mpd, ism, m3u8",
        "clip_start_position_ms": "[O] A start point to which the sample should be clipped, in milliseconds"
        "clip_end_position_ms": "[O] An end point from which the sample should be clipped, in milliseconds"
        "drm_scheme": "[O] Drm scheme if protected. Values: widevine, playready, clearkey",
        "drm_license_uri": "[O] URI of the license server if protected",
        "drm_force_default_license_uri": "[O] Whether to force use of "drm_license_uri" for key requests that include their own license URI",
        "drm_key_request_properties": "[O] Key request headers if protected",
        "drm_session_for_clear_content": "[O] Whether to attach a DRM session to clear video and audio tracks"
        "drm_multi_session": "[O] Enables key rotation if protected",
        "mime_type": "[O] The MIME type of the sample. Cannot be combined with extension.",
        "subtitle_uri": "[O] The URI of a subtitle sidecar file",
        "subtitle_mime_type": "[O] The MIME type of subtitle_uri (required if subtitle_uri is set)",
        "subtitle_language": "[O] The BCP47 language code of the subtitle file (ignored if subtitle_uri is not set)",
        "ad_tag_uri": "[O] The URI of an ad tag to load via the IMA extension"
      },
      ...etc
    ]
  },
  ...etc
]

Le playlist di campioni possono essere specificate utilizzando lo schema:

[
  {
    "name": "Name of heading",
    "samples": [
      {
        "name": "Name of playlist sample",
        "playlist": [
          {
            "uri": "The URI of the first sample in the playlist",
            "extension": "[O] Sample type hint. Cannot be combined with mime_type. Values: mpd, ism, m3u8"
            "clip_start_position_ms": "[O] A start point to which the sample should be clipped, in milliseconds"
            "clip_end_position_ms": "[O] An end point from which the sample should be clipped, in milliseconds"
            "drm_scheme": "[O] Drm scheme if protected. Values: widevine, playready, clearkey",
            "drm_license_uri": "[O] URI of the license server if protected",
            "drm_force_default_license_uri": "[O] Whether to force use of "drm_license_uri" for key requests that include their own license URI",
            "drm_key_request_properties": "[O] Key request headers if protected",
            "drm_session_for_clear_content": "[O] Whether to attach a DRM session to clear video and audio tracks",
            "drm_multi_session": "[O] Enables key rotation if protected",
            "mime_type": "[O] The MIME type of the sample. Cannot be combined with extension.",
            "subtitle_uri": "[O] The URI of a subtitle sidecar file",
            "subtitle_mime_type": "[O] The MIME type of subtitle_uri (required if subtitle_uri is set)",
            "subtitle_language": "[O] The BCP47 language code of the subtitle file (ignored if subtitle_uri is not set)"
          },
          {
            "uri": "The URI of the second sample in the playlist",
            ...etc
          },
          ...etc
        ]
      },
      ...etc
    ]
  },
  ...etc
]

Se necessario, le intestazioni delle richieste di chiavi vengono specificate come oggetto contenente un attributo stringa per ogni intestazione:

"drm_key_request_properties": {
  "name1": "value1",
  "name2": "value2",
  ...etc
}

Nell'attività di selezione del campione, il menu overflow contiene opzioni per specificare se preferire i decodificatori delle estensioni.

URI dei file locali e limitazioni di archiviazione con ambito

Quando specifichi gli URI dei file locali, l'app demo richiede le autorizzazioni di accesso allo spazio di archiviazione necessarie per leggere questi file. Tuttavia, a partire da Android 13, non è possibile caricare file arbitrari che non terminano con un'estensione di file multimediale tipica (come .mp4). Se devi caricare un file di questo tipo, puoi inserirlo nella directory di archiviazione specifica dell'app demo che non ha restrizioni di accesso. In genere si trova in /sdcard/Android/data/androidx.media3.demo.main/files.

2. Caricamento di un file exolist.json esterno

L'app demo può caricare file JSON esterni utilizzando lo schema riportato sopra e denominati in base alla convenzione *.exolist.json. Ad esempio, se ospiti un file di questo tipo all'indirizzo https://yourdomain.com/samples.exolist.json, puoi aprirlo nell'app demo utilizzando:

adb shell am start -a android.intent.action.VIEW \
    -d https://yourdomain.com/samples.exolist.json

Se fai clic su un link *.exolist.json (ad esempio nel browser o in un client di posta elettronica) su un dispositivo con l'app demo installata, questa si aprirà nell'app demo. Pertanto, l'hosting di un file JSON *.exolist.json offre un modo semplice per distribuire contenuti che altri possono provare nell'app demo.

3. Attivazione di un intent

Gli intent possono essere utilizzati per ignorare l'elenco dei campioni e avviare direttamente la riproduzione. Per riprodurre un singolo campione, imposta l'azione dell'intent su androidx.media3.demo.main.action.VIEW e il relativo URI dati su quello del campione da riprodurre. Un intent di questo tipo può essere attivato dal terminale utilizzando:

adb shell am start -a androidx.media3.demo.main.action.VIEW \
    -d https://yourdomain.com/sample.mp4

Gli extra facoltativi supportati per un singolo intent di esempio sono:

  • Extra di configurazione di esempio:
    • mime_type [Stringa] Suggerimento sul tipo MIME di esempio. Ad esempio, application/dash+xml per i contenuti DASH.
    • clip_start_position_ms [Lungo] Un punto di partenza a cui deve essere tagliato il campione, in millisecondi.
    • clip_end_position_ms [Long] Un punto finale da cui deve essere tagliato il campione, in millisecondi.
    • drm_scheme [String] DRM scheme if protected. I valori validi sono widevine, playready e clearkey. Sono accettati anche gli UUID dello schema DRM.
    • drm_license_uri [String] URI del server delle licenze se protetto.
    • drm_force_default_license_uri [Booleano] Indica se forzare l'utilizzo di drm_license_uri per le richieste di chiavi che includono il proprio URI di licenza.
    • drm_key_request_properties [Array di stringhe] Intestazioni delle richieste di chiavi compresse come name1, value1, name2, value2 e così via, se protette.
    • drm_session_for_clear_content [Valore booleano] Indica se allegare una sessione DRM a tracce video e audio chiare.
    • drm_multi_session [Booleano] Attiva la rotazione della chiave se protetta.
    • subtitle_uri [String] L'URI di un file collaterale di sottotitoli.
    • subtitle_mime_type [Stringa] Il tipo MIME di subtitle_uri (obbligatorio se subtitle_uri è impostato).
    • subtitle_language [Stringa] Il codice lingua BCP47 del file dei sottotitoli codificati (ignorato se subtitle_uri non è impostato).
    • ad_tag_uri [String] L'URI di un tag annuncio da caricare utilizzando l'estensione [IMA][].
    • prefer_extension_decoders [booleano] Indica se i decodificatori delle estensioni sono preferiti a quelli della piattaforma.

Quando utilizzi adb shell am start per attivare un intent, puoi impostare una stringa extra facoltativa con --es (ad es. --es extension mpd). Puoi impostare un'opzione booleana facoltativa con --ez (ad es. --ez prefer_extension_decoders TRUE). Puoi impostare un'opzione long facoltativa con --el (ad es. --el clip_start_position_ms 5000). Puoi impostare un array di stringhe facoltativo con --esa (ad es. --esa drm_key_request_properties name1,value1).

Per riprodurre una playlist di campioni, imposta l'azione dell'intent su androidx.media3.demo.main.action.VIEW_LIST. Gli extra della configurazione di esempio rimangono gli stessi di androidx.media3.demo.main.action.VIEW, ad eccezione di due differenze:

  • Le chiavi degli extra devono avere un trattino basso e l'indice in base zero del campione come suffisso. Ad esempio, extension_0 suggerirebbe il tipo di campione per il primo campione. drm_scheme_1 imposterebbe lo schema DRM per il secondo campione.
  • L'URI del campione viene passato come extra con la chiave uri_<sample-index>.

Gli altri extra, che non dipendono dal campione, non cambiano. Ad esempio, puoi eseguire il seguente comando nel terminale per riprodurre una playlist con due elementi, sostituendo l'estensione del secondo elemento:

adb shell am start -a androidx.media3.demo.main.action.VIEW_LIST \
    --es uri_0 https://a.com/sample1.mp4 \
    --es uri_1 https://b.com/sample2.fake_mpd \
    --es extension_1 mpd