ExoPlayer-Demoanwendung

Die Hauptdemo-App von ExoPlayer dient zwei Hauptzwecken:

1. Ein relativ einfaches, aber voll funktionsfähiges Beispiel für die Verwendung von ExoPlayer. Die Demo-App kann als praktischer Ausgangspunkt für die Entwicklung Ihrer eigenen App verwendet werden.
2. Damit du ExoPlayer ganz einfach testen kannst. Mit der Demo-App kannst du nicht nur die Wiedergabe der enthaltenen Samples, sondern auch deiner eigenen Inhalte testen.

Auf dieser Seite wird beschrieben, wie Sie die Demo-App herunterladen, kompilieren und ausführen. Außerdem wird beschrieben, wie Sie damit Ihre eigenen Medien abspielen.

Code abrufen

Den Quellcode für die Haupt-Demo-App finden Sie im Ordner demos/main unseres GitHub-Projekts. Klonen Sie das Projekt in ein lokales Verzeichnis, falls Sie dies noch nicht getan haben:

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

Öffnen Sie als Nächstes das Projekt in Android Studio. In der Android-Projektansicht sollte Folgendes zu sehen sein (die relevanten Ordner der Demo-App wurden maximiert):

Kompilieren und Ausführen

Wählen Sie in Android Studio die demo-Konfiguration aus und führen Sie sie aus, um die Demo-App zu kompilieren und auszuführen. Die Demo-App wird auf einem verbundenen Android-Gerät installiert und ausgeführt. Wir empfehlen, nach Möglichkeit ein physisches Gerät zu verwenden. Wenn Sie stattdessen einen Emulator verwenden möchten, lesen Sie den Abschnitt zu den Emulatoren unter Unterstützte Geräte und achten Sie darauf, dass Ihr virtuelles Gerät ein System-Image mit einer API-Ebene von mindestens 23 verwendet.

Die Demo-App enthält eine Liste mit Samples (SampleChooserActivity). Wenn Sie ein Sample auswählen, wird eine zweite Aktivität (PlayerActivity) zur Wiedergabe geöffnet. Die Demo enthält Wiedergabesteuerungen und Funktionen zur Titelauswahl. Außerdem wird die Dienstprogrammklasse EventLogger von ExoPlayer verwendet, um nützliche Debugging-Informationen in das Systemprotokoll auszugeben. Diese Protokollierung kann zusammen mit der Protokollierung auf Fehlerebene für andere Tags mit dem Befehl aufgerufen werden:

adb logcat EventLogger:V *:E

Gebündelte Decoder aktivieren

ExoPlayer hat eine Reihe von Erweiterungen, die die Verwendung von mitgelieferten Software-Decodern ermöglichen, darunter AV1, VP9, Opus, FLAC und FFmpeg (nur Audio). Die Demo-App kann so erstellt werden, dass sie diese Erweiterungen so enthält und verwendet:

1. Erstellen Sie alle Erweiterungen, die Sie einbinden möchten. Hinweis: Dies ist ein manueller Vorgang. Eine Anleitung finden Sie in der Datei README.md in jeder Erweiterung.

2. Legen Sie in Android Studio in der Ansicht „Build-Varianten“ die Build-Variante für das Demomodul auf withDecoderExtensionsDebug oder withDecoderExtensionsRelease fest, wie in der folgenden Abbildung dargestellt.

   

3. Kompilieren, installieren und führen Sie die demo-Konfiguration wie gewohnt aus.

Standardmäßig wird ein Erweiterungs-Decoder nur verwendet, wenn kein geeigneter Plattform-Decoder vorhanden ist. Es ist möglich, anzugeben, dass Erweiterungsdekoder bevorzugt werden sollen, wie in den folgenden Abschnitten beschrieben.

Eigene Inhalte wiedergeben

Es gibt mehrere Möglichkeiten, eigene Inhalte in der Demo-App abzuspielen.

1. assets/media.exolist.json bearbeiten

Die in der Demo-App aufgeführten Samples werden von assets/media.exolist.json geladen. Wenn Sie diese JSON-Datei bearbeiten, können Sie Beispiele zur Demo-App hinzufügen und daraus entfernen. Das Schema sieht so aus, wobei [O] ein optionales Attribut angibt.

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

Playlists mit Samples können mit dem folgenden Schema angegeben werden:

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

Falls erforderlich, werden wichtige Anfrageheader als Objekt mit einem Stringattribut für jeden Header angegeben:

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

In der Aktivität zur Beispielauswahl enthält das Dreipunkt-Menü Optionen, mit denen angegeben werden kann, ob Erweiterungsdecoder bevorzugt werden sollen.

URIs für lokale Dateien und Speicherbeschränkungen

Wenn lokale Datei-URIs angegeben werden, fordert die Demo-App die erforderlichen Berechtigungen für den Speicherzugriff an, um diese Dateien zu lesen. Ab Android 13 ist es jedoch nicht möglich, beliebige Dateien zu laden, die nicht mit einer typischen Dateiendung für Medien wie .mp4 enden. Wenn Sie eine solche Datei laden müssen, können Sie sie im Speicherverzeichnis der Demo-App ohne Zugriffsbeschränkungen ablegen. Dieser befindet sich normalerweise unter /sdcard/Android/data/androidx.media3.demo.main/files.

2. Externe exolist.json-Datei laden

Die Demo-App kann externe JSON-Dateien mit dem obigen Schema und gemäß der *.exolist.json-Konvention laden. Wenn Sie eine solche Datei beispielsweise unter https://yourdomain.com/samples.exolist.json hosten, können Sie sie in der Demo-App mit folgendem Befehl öffnen:

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

Wenn Sie auf einem Gerät, auf dem die Demo-App installiert ist, auf einen *.exolist.json-Link (z. B. im Browser oder in einem E-Mail-Client) klicken, wird dieser auch in der Demo-App geöffnet. Das Hosten einer *.exolist.json-JSON-Datei bietet daher eine einfache Möglichkeit, Inhalte zu verteilen, damit andere sie in der Demo-App ausprobieren können.

3. Intent auslösen

Mithilfe von Intents kannst du die Liste der Samples überspringen und direkt mit der Wiedergabe beginnen. Wenn Sie ein einzelnes Sample abspielen möchten, legen Sie die Aktion des Intents auf androidx.media3.demo.main.action.VIEW und den Daten-URI auf den des abzuspielenden Samples fest. Ein solcher Intent kann mit folgendem Befehl vom Terminal ausgelöst werden:

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

Für einen einzelnen Beispiel-Intent werden folgende optionale Extras unterstützt:

• Beispiele für Konfigurationsvorteile:
  • mime_type [String] Beispiel für einen MIME-Typ-Hinweis. Beispiel: application/dash+xml für DASH-Inhalte.
  • clip_start_position_ms [Long] Ein Startpunkt, bis zu dem das Sample zugeschnitten werden soll, in Millisekunden.
  • clip_end_position_ms [Long] Ein Endpunkt, ab dem die Stichprobe abgeschnitten werden soll, angegeben in Millisekunden.
  • drm_scheme [String] DRM-Schema, falls geschützt. Gültige Werte sind widevine, playready und clearkey. UUIDs für DRM-Schemas werden ebenfalls akzeptiert.
  • drm_license_uri [String] URI des Lizenzservers, falls geschützt.
  • drm_force_default_license_uri [boolescher Wert] Gibt an, ob drm_license_uri für Schlüsselanfragen mit eigener Lizenz-URI erzwungen werden soll.
  • drm_key_request_properties [Stringarray] Schlüssel-Anfrageheader, die als Name1, Wert1, Name2, Wert2 usw. gepackt sind, wenn sie geschützt sind.
  • drm_session_for_clear_content [Boolesch] Gibt an, ob eine DRM-Sitzung zum Löschen von Video- und Audiotracks angehängt werden soll.
  • drm_multi_session [Boolescher Wert] Aktiviert die Schlüsselrotation, wenn geschützt.
  • subtitle_uri [String] Der URI einer Untertitel-Sidecar-Datei.
  • subtitle_mime_type [String] Der MIME-Typ von „subtitle_uri“ (erforderlich, wenn „subtitle_uri“ festgelegt ist).
  • subtitle_language [String] Der BCP47-Sprachcode der Untertiteldatei (wird ignoriert, wenn „subtitle_uri“ nicht festgelegt ist).
  • ad_tag_uri [String] Der URI eines Anzeigen-Tags, das mit der [IMA-Erweiterung][] geladen werden soll.
  • prefer_extension_decoders [Boolescher Wert] Gibt an, ob Erweiterungsdekoder Plattformdekodern vorgezogen werden sollen.

Wenn Sie adb shell am start verwenden, um einen Intent auszulösen, kann mit --es ein optionales String-Extra festgelegt werden (z.B. --es extension mpd). Mit --ez kann ein optionales boolesche Extra festgelegt werden (z.B. --ez prefer_extension_decoders TRUE). Mit --el kann ein optionales langes Extra festgelegt werden (z.B. --el clip_start_position_ms 5000). Mit --esa kann ein optionales Stringarray festgelegt werden (z.B. --esa drm_key_request_properties name1,value1).

Wenn du eine Playlist mit Samples abspielen möchtest, setze die Aktion des Intents auf androidx.media3.demo.main.action.VIEW_LIST. Die Extras in der Beispielkonfiguration bleiben mit zwei Ausnahmen unverändert:androidx.media3.demo.main.action.VIEW

• Die Schlüssel der Extras sollten einen Unterstrich und den Index der Probe (ab 0) als Suffix haben. Beispiel: extension_0 gibt den Sample-Typ für das erste Sample an. drm_scheme_1 würde das DRM-Schema für das zweite Sample festlegen.
• Die URI der Probe wird als Extra mit dem Schlüssel uri_<sample-index> übergeben.

Andere Extras, die nicht von der Stichprobe abhängig sind, ändern sich nicht. So kannst du beispielsweise den folgenden Befehl im Terminal ausführen, um eine Playlist mit zwei Elementen abzuspielen und dabei die Erweiterung des zweiten Elements zu überschreiben:

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