Application de démonstration ExoPlayer

L'application de démonstration principale d'ExoPlayer remplit deux objectifs principaux :

  1. Fournir un exemple d'utilisation d'ExoPlayer relativement simple, mais complet. L'application de démonstration peut servir de point de départ pratique pour développer votre propre application.
  2. Pour faciliter l'essai d'ExoPlayer. L'application de démonstration peut être utilisée pour tester la lecture de votre propre contenu en plus des exemples inclus.

Cette page explique comment obtenir, compiler et exécuter l'application de démonstration. Elle explique également comment l'utiliser pour lire vos propres contenus multimédias.

Obtenir le code

Le code source de l'application de démonstration principale se trouve dans le dossier demos/main de notre projet GitHub. Si vous ne l'avez pas déjà fait, clonez le projet dans un répertoire local :

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

Ouvrez ensuite le projet dans Android Studio. Vous devriez voir les éléments suivants dans la vue "Projet Android" (les dossiers concernés de l'application de démonstration ont été développés) :

Le projet dans Android Studio

Compiler et exécuter

Pour compiler et exécuter l'application de démonstration, sélectionnez et exécutez la configuration demo dans Android Studio. L'application de démonstration s'installe et s'exécute sur un appareil Android connecté. Nous vous recommandons d'utiliser un appareil physique si possible. Si vous souhaitez utiliser un émulateur, veuillez lire la section sur les émulateurs de la page Appareils compatibles et assurez-vous que votre appareil virtuel utilise une image système avec un niveau d'API d'au moins 23.

SampleChooserActivity et PlayerActivity

L'application de démonstration présente une liste d'échantillons (SampleChooserActivity). La sélection d'un échantillon ouvre une deuxième activité (PlayerActivity) pour la lecture. La démo inclut des commandes de lecture et une fonctionnalité de sélection de pistes. Il utilise également la classe utilitaire EventLogger d'ExoPlayer pour générer des informations de débogage utiles dans le journal système. Vous pouvez afficher cette journalisation (ainsi que la journalisation du niveau d'erreur pour d'autres tags) à l'aide de la commande suivante :

adb logcat EventLogger:V *:E

Activer les décodeurs groupés

ExoPlayer dispose de plusieurs extensions qui permettent d'utiliser des décodeurs logiciels groupés, y compris AV1, VP9, Opus, FLAC et FFmpeg (audio uniquement). L'application de démonstration peut être compilée pour inclure et utiliser ces extensions comme suit :

  1. Créez chacune des extensions que vous souhaitez inclure. Notez qu'il s'agit d'un processus manuel. Pour obtenir des instructions, consultez le fichier README.md de chaque extension.

  2. Dans la vue "Build Variants" (Variantes de compilation) d'Android Studio, définissez la variante de compilation du module de démonstration sur withDecoderExtensionsDebug ou withDecoderExtensionsRelease, comme illustré dans l'image suivante.

    Sélection de la variante de compilation de démonstration "withDecoderExtensionsDebug"

  3. Compilez, installez et exécutez la configuration demo normalement.

Par défaut, un décodeur d'extension n'est utilisé que si aucun décodeur de plate-forme approprié n'existe. Il est possible de spécifier que les décodeurs d'extension doivent être préférés, comme décrit dans les sections suivantes.

Lire votre propre contenu

Il existe plusieurs façons de lire votre propre contenu dans l'application de démonstration.

1. Modifier assets/media.exolist.json

Les exemples listés dans l'application de démonstration sont chargés à partir de assets/media.exolist.json. En modifiant ce fichier JSON, il est possible d'ajouter et de supprimer des exemples de l'application de démonstration. Le schéma est le suivant, où [O] indique un attribut facultatif.

[
  {
    "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
]

Vous pouvez spécifier des playlists d'échantillons à l'aide du schéma suivant :

[
  {
    "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
]

Si nécessaire, les en-têtes de requête de clé sont spécifiés en tant qu'objet contenant un attribut de chaîne pour chaque en-tête :

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

Dans l'activité du sélecteur d'échantillons, le menu à développer contient des options permettant de spécifier s'il faut privilégier les décodeurs d'extension.

URI de fichiers locaux et restrictions de stockage étendu

Lorsque vous spécifiez des URI de fichiers locaux, l'application de démonstration demande les autorisations d'accès au stockage nécessaires pour lire ces fichiers. Toutefois, à partir d'Android 13, il n'est pas possible de charger des fichiers arbitraires qui ne se terminent pas par une extension de fichier multimédia typique (comme .mp4). Si vous devez charger un tel fichier, vous pouvez le placer dans le répertoire de stockage spécifique de l'application de démonstration, qui ne comporte aucune restriction d'accès. Il se trouve généralement à l'emplacement suivant : /sdcard/Android/data/androidx.media3.demo.main/files.

2. Charger un fichier exolist.json externe

L'application de démonstration peut charger des fichiers JSON externes à l'aide du schéma ci-dessus et nommés selon la convention *.exolist.json. Par exemple, si vous hébergez un tel fichier sur https://yourdomain.com/samples.exolist.json, vous pouvez l'ouvrir dans l'application de démonstration à l'aide de la commande suivante :

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

Si vous cliquez sur un lien *.exolist.json (par exemple, dans le navigateur ou un client de messagerie) sur un appareil sur lequel l'application de démonstration est installée, il s'ouvrira également dans l'application de démonstration. Par conséquent, l'hébergement d'un fichier JSON *.exolist.json constitue un moyen simple de distribuer du contenu pour que d'autres utilisateurs puissent l'essayer dans l'application de démonstration.

3. Déclencher un intent

Les intents peuvent être utilisés pour contourner la liste des échantillons et lancer directement la lecture. Pour lire un seul échantillon, définissez l'action de l'intent sur androidx.media3.demo.main.action.VIEW et son URI de données sur celui de l'échantillon à lire. Un tel intent peut être déclenché à partir du terminal à l'aide de la commande suivante :

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

Voici les extras facultatifs acceptés pour un intent d'exemple unique :

  • Exemples de configurations supplémentaires :
    • mime_type [String] Exemple d'indication de type MIME. Par exemple, application/dash+xml pour le contenu DASH.
    • clip_start_position_ms [Long] Point de départ auquel l'échantillon doit être coupé, en millisecondes.
    • clip_end_position_ms [Long] Point de terminaison à partir duquel l'échantillon doit être coupé, en millisecondes.
    • drm_scheme [String] Schéma DRM si le contenu est protégé. Les valeurs valides sont widevine, playready et clearkey. Les UUID de schéma DRM sont également acceptés.
    • drm_license_uri [String] URI du serveur de licence si le contenu est protégé.
    • drm_force_default_license_uri [Boolean] Indique s'il faut forcer l'utilisation de drm_license_uri pour les demandes de clé qui incluent leur propre URI de licence.
    • drm_key_request_properties [Tableau de chaînes] En-têtes de requête de clé compressés sous la forme nom1, valeur1, nom2, valeur2, etc. s'ils sont protégés.
    • drm_session_for_clear_content [Boolean] Indique s'il faut associer une session DRM à des pistes vidéo et audio claires.
    • drm_multi_session [Boolean] Active la rotation des clés si elles sont protégées.
    • subtitle_uri [String] URI d'un fichier side-car de sous-titres.
    • subtitle_mime_type [String] Type MIME de subtitle_uri (obligatoire si subtitle_uri est défini).
    • subtitle_language [String] Code de langue BCP47 du fichier de sous-titres (ignoré si subtitle_uri n'est pas défini).
    • ad_tag_uri [String] URI d'un tag d'emplacement publicitaire à charger à l'aide de l'[extension IMA][].
    • prefer_extension_decoders [Boolean] Indique si les décodeurs d'extension sont préférés à ceux de la plate-forme.

Lorsque vous utilisez adb shell am start pour déclencher une intention, vous pouvez définir une chaîne supplémentaire facultative avec --es (par exemple, --es extension mpd). Vous pouvez définir un booléen supplémentaire facultatif avec --ez (par exemple, --ez prefer_extension_decoders TRUE). Vous pouvez définir un long supplémentaire facultatif avec --el (par exemple, --el clip_start_position_ms 5000). Vous pouvez définir un tableau de chaînes supplémentaire facultatif avec --esa (par exemple, --esa drm_key_request_properties name1,value1).

Pour lire une playlist d'échantillons, définissez l'action de l'intention sur androidx.media3.demo.main.action.VIEW_LIST. Les extras de configuration de l'exemple restent les mêmes que pour androidx.media3.demo.main.action.VIEW, à deux exceptions près :

  • Les clés des extras doivent comporter un trait de soulignement et l'index de l'échantillon (base 0) comme suffixe. Par exemple, extension_0 indiquerait le type d'échantillon pour le premier échantillon. drm_scheme_1 définirait le schéma DRM pour le deuxième échantillon.
  • L'URI de l'échantillon est transmis en tant qu'extra avec la clé uri_<sample-index>.

Les autres extras, qui ne dépendent pas de l'échantillon, ne changent pas. Par exemple, vous pouvez exécuter la commande suivante dans le terminal pour lire une playlist comportant deux éléments, en remplaçant l'extension du deuxième élément :

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