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 di dimostrazione può essere utilizzata come comodo punto di partenza per sviluppare la tua app.
  2. Per provare facilmente ExoPlayer. L'app di demo può essere utilizzata per testare la riproduzione dei tuoi contenuti, oltre ai sample inclusi.

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

Ricevere il codice

Il codice sorgente dell'app demo principale è disponibile 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. Nella visualizzazione Progetto Android dovresti vedere quanto segue (le cartelle pertinenti dell'app di demo sono state espanse):

Il progetto in Android Studio

Compilazione ed esecuzione

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

SampleChooserActivity e PlayerActivity

L'app di demo presenta un elenco di sample (SampleChooserActivity). Se selezioni un sample, si aprirà una seconda attività (PlayerActivity) per la riproduzione. La demo include controlli di riproduzione e funzionalità di selezione dei brani. Utilizza inoltre la classe di utilità EventLogger di ExoPlayer per inviare utili informazioni di debug nel log di sistema. Questi log possono essere visualizzati (insieme ai log a livello di errore per altri tag) con il comando:

adb logcat EventLogger:V *:E

Attivazione dei decodificatori in bundle

ExoPlayer ha varie estensioni che consentono l'utilizzo di decodificatori software integrati, tra cui AV1, VP9, Opus, FLAC e FFmpeg (solo audio). L'app demo può essere creata in modo da includere e utilizzare queste estensioni come segue:

  1. Crea ogni estensione che vuoi includere. Tieni presente che si tratta di un processo manuale. Per istruzioni, fai riferimento al file README.md in ciascuna estensione.

  2. Nella visualizzazione Varianti della 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 estensioni verrà utilizzato solo se non esiste un decodificatore della piattaforma adatto. È possibile specificare che i decodificatori di estensioni debbano essere preferiti, come descritto nelle sezioni seguenti.

Riproduzione dei tuoi contenuti

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

1. Modificare 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. 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",
        "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 esempi 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. 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",
            "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 di richiesta principali vengono specificate come oggetto contenente un attributo di stringa per ogni intestazione:

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

Nell'attività del selettore di esempi, il menu extra contiene opzioni per specificare se preferire i decoder delle estensioni.

URI file locali e limitazioni dello spazio di archiviazione basate sugli ambiti

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

2. Caricamento di un file exolist.json esterno

L'app di 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 email) su un dispositivo su cui è installata l'app demo, il link si aprirà anche 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'intenzione

Gli intent possono essere utilizzati per bypassare l'elenco dei sample e avviare direttamente la riproduzione. Per riprodurre un singolo Sample, imposta l'azione dell'intent su androidx.media3.demo.main.action.VIEW e il relativo URI dati su quello del Sample da riprodurre. Un'intenzione di questo tipo può essere attivata 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 intento di esempio sono:

  • Extra di configurazione di esempio:
    • mime_type [Stringa] Suggerimento di tipo MIME di esempio. Ad esempio application/dash+xml per i contenuti DASH.
    • clip_start_position_ms [Long] Un punto iniziale in millisecondi a cui deve essere ritagliato il campione.
    • clip_end_position_ms [Long] Un punto di arrivo da cui deve essere tagliato il sample, in millisecondi.
    • drm_scheme [Stringa] Schema DRM se protetto. I valori validi sono widevine, playready e clearkey. Sono accettati anche gli UUID dello schema DRM.
    • drm_license_uri [Stringa] 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 della licenza.
    • drm_key_request_properties [Array di stringhe] Intestazioni delle richieste principali pacchettizzate come nome1, valore1, nome2, valore2 e così via, se protette.
    • drm_session_for_clear_content [Booleano] Indica se allegare una sessione DRM per cancellare le tracce video e audio.
    • drm_multi_session [booleano] Consente la rotazione della chiave se protetta.
    • subtitle_uri [Stringa] L'URI di un file di sottotitoli collaterali.
    • 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 (ignorato se subtitle_uri non è impostato).
    • ad_tag_uri [Stringa] L'URI di un tag annuncio da caricare utilizzando [estensione IMA][].
    • prefer_extension_decoders [Booleano] Indica se i decoder delle estensioni sono preferiti rispetto a quelli della piattaforma.

Quando utilizzi adb shell am start per attivare un'intenzione, puoi impostare un parametro facoltativo aggiuntivo della stringa con --es (ad es. --es extension mpd). Un valore aggiuntivo booleano facoltativo può essere impostato con --ez (ad es. --ez prefer_extension_decoders TRUE). Un valore extra facoltativo può essere impostato con --el (ad es. --el clip_start_position_ms 5000). È possibile impostare un ulteriore array di stringhe facoltativo con --esa (ad es. --esa drm_key_request_properties name1,value1).

Per riprodurre una playlist di Sample, 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, tranne che per due differenze:

  • Le chiavi degli extra devono avere un trattino basso e l'indice basato su 0 del campione come suffisso. Ad esempio, extension_0 indica il tipo di campione per il primo campione. drm_scheme_1 imposta lo schema DRM per il secondo Sample.
  • 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 questo 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