Applicazione demo ExoPlayer

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

1. Per fornire un esempio relativamente semplice, ma con tutte le funzionalità dell'utilizzo di ExoPlayer. L'app demo può essere utilizzata come comodo punto di partenza da cui sviluppare la tua app.
2. Per provare facilmente ExoPlayer. L'app demo può essere usata per testare la riproduzione dei tuoi contenuti oltre ai campioni inclusi.

In questa pagina viene descritto come scaricare, compilare ed eseguire l'app demo e come utilizzarla per riprodurre i tuoi contenuti multimediali.

Recupero del codice in corso...

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

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

Successivamente, apri il progetto in Android Studio. Nella visualizzazione Progetto Android dovresti vedere quanto segue (le cartelle pertinenti dell'app demo sono state espanse):

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. Ti consigliamo di utilizzare un dispositivo fisico, se possibile. Se vuoi utilizzare un emulatore, leggi la sezione degli emulatori della sezione Dispositivi supportati e assicurati che il dispositivo virtuale utilizzi un'immagine di sistema con un livello API di almeno 23.

L'app demo presenta un elenco di esempi (SampleChooserActivity). Se selezioni un campione, verrà aperta una seconda attività (PlayerActivity) per la riproduzione. La demo presenta i controlli di riproduzione e la funzionalità di selezione delle tracce. Utilizza inoltre la classe di utilità EventLogger di ExoPlayer per generare informazioni di debug utili nel log di sistema. Questo logging può essere visualizzato (insieme al logging a livello di errore per altri tag) con il comando:

adb logcat EventLogger:V *:E

Attivazione dei decoder in bundle

ExoPlayer ha una serie di estensioni che consentono l'utilizzo di decodificatori 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 ogni estensione 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.

   

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

Per impostazione predefinita, verrà utilizzato un decodificatore di estensione solo se non esiste un decodificatore di piattaforma adatto. È possibile specificare che i decodificatori di estensione dovrebbero 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 puoi aggiungere e rimuovere esempi 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 degli 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 delle richieste chiave vengono specificate come un oggetto contenente un attributo stringa per ogni intestazione:

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

Nell'attività del selettore di esempio, il menu extra contiene opzioni per specificare se preferisci i decodificatori di estensione.

URI dei file locali e restrizioni di archiviazione con ambito

Quando specifichi gli URI locali dei file, l'app demo 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 un file di questo tipo, puoi inserirlo nella directory di archiviazione specifica dell'app demo che non ha limitazioni di accesso. In genere, si trova all'indirizzo /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 su 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, l'app verrà aperta anche nell'app demo. Di conseguenza, ospitare un file JSON *.exolist.json offre un modo semplice di distribuire contenuti che altri possano provare nell'app demo.

Nota: sui dispositivi Android TV e sugli emulatori con livello API 31 e versioni successive, è necessario usare un'azione alternativa, che è androidx.media3.demo.main.action.BROWSE a causa delle limitazioni su questi dispositivi.

3. Attivazione di un intent

Gli intent possono essere utilizzati per bypassare l'elenco di esempi e avviarli direttamente in 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. Tale intent 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:

• Esempi di configurazioni extra:
  • mime_type [Stringa] Suggerimento per il tipo MIME di esempio. Ad esempio application/dash+xml per i contenuti DASH.
  • clip_start_position_ms [Lungo] Un punto iniziale in millisecondi al quale deve essere tagliato il campione.
  • clip_end_position_ms [Lungo] Il punto finale, in millisecondi, da cui deve essere eseguito il ritaglio del campione.
  • 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 di licenza.
  • drm_key_request_properties [Array di stringhe] Intestazioni delle richieste di chiave pacchettizzate come nome1, valore1, nome2, valore2 e così via, se protette.
  • drm_session_for_clear_content [Booleano] Indica se collegare o meno una sessione DRM per cancellare le tracce video e audio.
  • drm_multi_session [Booleano] Abilita la rotazione della chiave se protetta.
  • subtitle_uri [Stringa] L'URI di un file collaterale dei 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 (ignorato se subtitle_uri non è impostato).
  • ad_tag_uri [Stringa] L'URI di un tag annuncio da caricare utilizzando [l'estensione IMA][].
  • prefer_extension_decoders [Booleano] Indica se i decodificatori di estensione sono preferiti rispetto a quelli di piattaforma.

Quando utilizzi adb shell am start per attivare un intent, puoi impostare una stringa facoltativa aggiuntiva con --es (ad es. --es extension mpd). Puoi impostare un valore booleano facoltativo con --ez (ad es. --ez prefer_extension_decoders TRUE). Un extra lungo facoltativo può essere impostato con --el (ad es. --el clip_start_position_ms 5000). Un array di stringhe facoltativo può essere impostato 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, tranne che per due differenze:

• Le chiavi degli extra devono avere un trattino basso e l'indice in base 0 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, rimangono invariati. 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