Cette page a été traduite par l'API Cloud Translation.

Application de démonstration ExoPlayer

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

Fournir un exemple d'utilisation d'ExoPlayer relativement simple, mais complet. L'application de démonstration peut être utilisée comme point de départ pratique pour développer votre propre application.
Pour tester facilement 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 ce qui suit dans la vue du projet Android (les dossiers pertinents de l'application de démonstration ont été développés):

Le projet dans Android Studio

Compilation et exécution

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 à la place, consultez la section "É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émonstration présente les commandes de lecture et la fonctionnalité de sélection de titres. 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 au niveau de l'erreur pour les autres balises) à l'aide de la commande suivante:

adb logcat EventLogger:V *:E

Activer les décodeurs groupés

ExoPlayer propose 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:

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.
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.
Compilez, installez et exécutez la configuration demo comme d'habitude.

Par défaut, un décodeur d'extension n'est utilisé que si aucun décodeur de plate-forme approprié n'existe. Vous pouvez spécifier que les décodeurs d'extension doivent être privilégiés, comme décrit dans les sections suivantes.

Lire votre propre contenu

Il existe plusieurs façons de lire vos propres contenus 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, vous pouvez ajouter et 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. 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
]

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. 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
]

Si nécessaire, les en-têtes de requêtes 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'exemple d'activité de sélecteur, le menu à développer contient des options permettant de spécifier si les décodeurs d'extension sont à privilégier.

URI de fichiers locaux et restrictions de stockage ciblées

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 n'est soumis à aucune restriction d'accès. Il se trouve généralement à l'emplacement /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 conformément à la convention *.exolist.json. Par exemple, si vous hébergez un tel fichier à https://yourdomain.com/samples.exolist.json, vous pouvez l'ouvrir dans l'application de démonstration à l'aide de:

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

Cliquez sur un lien *.exolist.json (par exemple, dans le navigateur ou dans un client de messagerie) sur un appareil sur lequel l'application de démonstration est installée pour l'ouvrir dans l'application de démonstration. L'hébergement d'un fichier JSON *.exolist.json permet donc de distribuer facilement du contenu à d'autres utilisateurs pour qu'ils puissent l'essayer dans l'application de démonstration.

3. Déclencher un intent

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

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

Les éléments facultatifs acceptés pour un seul intent d'exemple sont les suivants:

Exemples d'extras de configuration :
- mime_type [Chaîne] Exemple d'indice 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 fin à partir duquel l'échantillon doit être coupé, en millisecondes.
- drm_scheme [Chaîne] 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 [Chaîne] URI du serveur de licence si protégé.
- drm_force_default_license_uri [booléen] Indique si l'utilisation de drm_license_uri doit être forcée pour les requêtes de clé qui incluent leur propre URI de licence.
- drm_key_request_properties [Tableau de chaînes] En-têtes de requête clés empaquetés sous forme de nom1, valeur1, nom2, valeur2, etc. s'ils sont protégés.
- drm_session_for_clear_content [booléen] Indique si une session DRM doit être associée à des pistes vidéo et audio claires.
- drm_multi_session [Booléen] Active la rotation des clés si elle est protégée.
- subtitle_uri [String] URI d'un fichier side-car de sous-titres.
- subtitle_mime_type [Chaîne] Type MIME de subtitle_uri (obligatoire si subtitle_uri est défini).
- subtitle_language [Chaîne] Code de langue BCP47 du fichier de sous-titres (ignoré si subtitle_uri n'est pas défini).
- ad_tag_uri [Chaîne] URI d'un tag d'annonce à charger à l'aide de l'[extension IMA][].
- prefer_extension_decoders [Booléen] Indique si les décodeurs d'extension sont préférés aux décodeurs de la plate-forme.

Lorsque vous utilisez adb shell am start pour déclencher un intent, un élément de chaîne supplémentaire peut être défini avec --es (par exemple, --es extension mpd). Un extra booléen facultatif peut être défini avec --ez (par exemple, --ez prefer_extension_decoders TRUE). Un élément supplémentaire long facultatif peut être défini avec --el (par exemple, --el clip_start_position_ms 5000). Un tableau de chaînes facultatif supplémentaire peut être défini avec --esa (par exemple, --esa drm_key_request_properties name1,value1).

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

Les clés des éléments supplémentaires doivent comporter un trait de soulignement et l'indice de l'échantillon (basé sur 0) comme suffixe. Par exemple, extension_0 indique le type d'échantillon du premier exemple. drm_scheme_1 définit le schéma DRM pour le deuxième échantillon.
L'URI de l'échantillon est transmis en tant qu'élément supplémentaire 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 avec deux éléments, en ignorant 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