L'application de démonstration principale d'ExoPlayer remplit deux fonctions principales:
- 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 essayer facilement ExoPlayer. Vous pouvez utiliser l'application de démonstration 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 correspondants de l'application de démonstration ont été développés):
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é.
Si possible, nous vous recommandons d'utiliser un appareil physique. Si vous souhaitez utiliser un émulateur, veuillez consulter la section sur les émulateurs de Appareils compatibles et vous assurer que votre appareil virtuel utilise une image système avec un niveau d'API d'au moins 23.
L'application de démonstration présente une liste d'échantillons (SampleChooserActivity). Si vous sélectionnez un échantillon, une deuxième activité (PlayerActivity) s'ouvre pour la lecture. La version de démonstration présente 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 au 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 comporte un certain nombre d'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 conçue 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.mdde 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
withDecoderExtensionsDebugouwithDecoderExtensionsRelease, comme illustré dans l'image suivante.
Compilez, installez et exécutez la configuration
demonormalement.
Par défaut, un décodeur d'extensions n'est utilisé que s'il n'existe pas de décodeur de plate-forme approprié. Il est possible de 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 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, 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'activité du sélecteur d'exemples, le menu à développer contient des options permettant de spécifier si vous préférez utiliser des décodeurs d'extensions.
URI de fichiers locaux et restrictions de stockage cloisonné
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 plus possible de charger des fichiers arbitraires qui ne se terminent pas par une extension de fichier multimédia classique (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 présente aucune restriction d'accès. Il se trouve généralement à l'adresse /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 fichier de ce type 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
Cliquez sur un lien *.exolist.json (dans le navigateur ou un client de messagerie, par exemple) sur un appareil sur lequel l'application de démonstration est installée pour l'ouvrir également dans l'application de démonstration. Héberger un fichier JSON *.exolist.json est donc un moyen simple de distribuer du contenu que d'autres utilisateurs pourront essayer dans l'application de démonstration.
3. Déclencher un intent
Les intents peuvent être utilisés pour contourner la liste des exemples 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
Les extras facultatifs compatibles avec un seul exemple d'intent sont les suivants:
- Exemples de configuration supplémentaire :
mime_type[Chaîne] Exemple d'indication pour le type MIME. Par exemple,application/dash+xmlpour le contenu DASH.clip_start_position_ms[Long] Point de départ auquel l'échantillon doit être rogné, en millisecondes.clip_end_position_ms[Long] Point d'arrivée à partir duquel l'échantillon doit être rogné, en millisecondes.drm_scheme[Chaîne] Schéma DRM s'il est protégé. Les valeurs valides sontwidevine,playreadyetclearkey. Les UUID des schémas de DRM sont également acceptés.drm_license_uri[Chaîne] URI du serveur de licences s'il est protégé.drm_force_default_license_uri[Booléen] Indique si l'utilisation dedrm_license_uridoit ê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êtes de clé empaquetés sous la forme 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 pour effacer les pistes vidéo et audio.drm_multi_session[Booléen] Active la rotation des clés si elles sont protégées.subtitle_uri[Chaîne] 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'emplacement publicitaire à charger à l'aide de l'[extension IMA][].prefer_extension_decoders[booléen] Indique si les décodeurs d'extensions sont privilégiés par rapport à ceux de la plate-forme.
Lorsque vous utilisez adb shell am start pour déclencher un intent, une chaîne supplémentaire facultative peut être définie avec --es (par exemple, --es extension mpd). Vous pouvez également définir une valeur booléenne supplémentaire avec --ez (par exemple, --ez prefer_extension_decoders TRUE). Un extra long facultatif peut être défini avec --el (par exemple, --el clip_start_position_ms 5000). Vous pouvez définir un extra de tableau de chaînes facultatif avec --esa (par exemple,
--esa drm_key_request_properties name1,value1).
Pour lire une playlist d'échantillons, définissez l'action de l'intent 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 différences près:
- Les clés des extras doivent comporter un trait de soulignement et l'index en base 0 de l'échantillon en tant que suffixe. Par exemple,
extension_0indique le type d'échantillon pour le premier échantillon.drm_scheme_1définirait le schéma DRM pour le deuxième exemple. - L'URI de l'échantillon est transmis en tant qu'élément supplémentaire avec la clé
uri_<sample-index>.
Les autres éléments supplémentaires, qui ne dépendent pas de l'échantillonnage, ne sont pas modifiés. 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