ExoPlayer-Demoanwendung

Die Hauptdemo-App von ExoPlayer dient zwei Hauptzwecken:

  1. Ein relativ einfaches, aber dennoch voll funktionsfähiges Beispiel für die Verwendung von ExoPlayer. Die Demo-App kann als praktischer Ausgangspunkt für die Entwicklung Ihrer eigenen App dienen.
  2. Um das Ausprobieren von ExoPlayer zu vereinfachen. Mit der Demo-App können Sie neben den enthaltenen Beispielen auch die Wiedergabe Ihrer eigenen Inhalte testen.

Auf dieser Seite wird beschrieben, wie Sie die Demo-App abrufen, kompilieren und ausführen und wie Sie damit Ihre eigenen Medien abspielen können.

Code abrufen

Der Quellcode für die Hauptdemo-App befindet sich im Ordner demos/main unseres GitHub-Projekts. Falls noch nicht geschehen, klonen Sie das Projekt in ein lokales Verzeichnis:

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

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

Das Projekt in Android Studio

Kompilieren und Ausführen

Wählen Sie in Android Studio die Konfiguration demo 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, wenn möglich ein physisches Gerät zu verwenden. Wenn Sie stattdessen einen Emulator verwenden möchten, lesen Sie den Abschnitt zu Emulatoren unter Unterstützte Geräte und achten Sie darauf, dass Ihr virtuelles Gerät ein System-Image mit einem API‑Level von mindestens 23 verwendet.

SampleChooserActivity und PlayerActivity

In der Demo-App wird eine Liste mit Beispielen (SampleChooserActivity) angezeigt. Wenn Sie ein Beispiel auswählen, wird eine zweite Aktivität (PlayerActivity) zur Wiedergabe geöffnet. Die Demo bietet Wiedergabesteuerelemente und eine Funktion zur Auswahl von Tracks. Außerdem wird die EventLogger-Hilfsklasse von ExoPlayer verwendet, um nützliche Debugging-Informationen im Systemlog auszugeben. Diese Protokollierung kann zusammen mit der Protokollierung auf Fehlerebene für andere Tags mit dem folgenden Befehl aufgerufen werden:

adb logcat EventLogger:V *:E

Gebündelte Decoder aktivieren

ExoPlayer bietet eine Reihe von Erweiterungen, die die Verwendung von gebündelten Softwaredecodern ermöglichen, darunter AV1, VP9, Opus, FLAC und FFmpeg (nur Audio). Die Demo-App kann so erstellt werden, dass diese Erweiterungen enthalten sind und verwendet werden:

  1. Erstellen Sie jede Erweiterung, die Sie einfügen möchten. Dieser Vorgang erfolgt manuell. Eine Anleitung finden Sie in der Datei README.md der jeweiligen 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 im folgenden Bild dargestellt.

    Auswahl der Build-Variante „withDecoderExtensionsDebug“

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

Standardmäßig wird ein Erweiterungsdecoder nur verwendet, wenn kein geeigneter Plattformdecoder vorhanden ist. Wie in den folgenden Abschnitten beschrieben, kann angegeben werden, dass Erweiterungsdecoder bevorzugt werden sollen.

Eigene Inhalte abspielen

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 Beispiele werden aus assets/media.exolist.json geladen. Durch Bearbeiten dieser JSON-Datei können Sie der Demo-App Beispiele hinzufügen und daraus entfernen. Das Schema ist wie folgt, 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. 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
]

Playlists mit Beispielen 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. 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
]

Bei Bedarf werden Schlüsselanfrageheader als Objekt mit einem Stringattribut für jeden Header angegeben:

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

Im Aktivitätsmenü für die Auswahl von Beispielen enthält das Dreipunkt-Menü Optionen zum Festlegen, ob Erweiterungsdecoder bevorzugt werden sollen.

Lokale Datei-URIs und Einschränkungen für den eingeschränkten Speicher

Wenn Sie lokale Datei-URIs angeben, fordert die Demo-App die erforderlichen Speicherzugriffsberechtigungen zum Lesen dieser Dateien an. Ab Android 13 ist es jedoch nicht mehr möglich, beliebige Dateien zu laden, die nicht mit einer typischen Erweiterung für Mediendateien (z. B. .mp4) enden. Wenn Sie eine solche Datei laden müssen, können Sie sie im spezifischen Speicherverzeichnis der Demo-App platzieren, für das keine Zugriffsbeschränkungen gelten. Sie 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 oben genannten Schema laden, die gemäß der *.exolist.json-Konvention benannt sind. 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 klicken (z. B. im Browser oder in einem E-Mail-Client), wird die Demo-App geöffnet. Das Hosten einer *.exolist.json-JSON-Datei ist daher eine einfache Möglichkeit, Inhalte zu verteilen, die andere in der Demo-App ausprobieren können.

3. Intent auslösen

Mit Intents kann die Liste der Beispiele umgangen und die Wiedergabe direkt gestartet werden. 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 über das Terminal mit folgendem Befehl ausgelöst werden:

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

Unterstützte optionale Extras für einen Intent für ein einzelnes Beispiel:

  • Beispiel für zusätzliche Konfigurationen:
    • mime_type [String] Beispiel für einen MIME-Typ-Hinweis. Zum Beispiel application/dash+xml für DASH-Inhalte.
    • clip_start_position_ms [Long] Ein Startpunkt, auf den die Probe in Millisekunden zugeschnitten werden soll.
    • clip_end_position_ms [Long] Ein Endpunkt, ab dem die Probe in Millisekunden gekürzt werden soll.
    • drm_scheme [String] DRM-Schema, falls geschützt. Gültige Werte sind widevine, playready und clearkey. DRM-Schema-UUIDs werden ebenfalls akzeptiert.
    • drm_license_uri [String] URI des Lizenzservers, falls geschützt.
    • drm_force_default_license_uri [Boolean] Gibt an, ob die Verwendung von drm_license_uri für Schlüsselanfragen, die einen eigenen Lizenz-URI enthalten, erzwungen werden soll.
    • drm_key_request_properties [String-Array] Schlüsselanfrageheader, die als „name1, value1, name2, value2“ usw. gepackt sind, falls sie geschützt sind.
    • drm_session_for_clear_content [Boolean]: Gibt an, ob eine DRM-Sitzung an unverschlüsselte Video- und Audiotracks angehängt werden soll.
    • drm_multi_session [Boolean] Aktiviert die Schlüsselrotation, wenn sie geschützt ist.
    • subtitle_uri [String] Der URI einer Sidecar-Untertiteldatei.
    • 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 [Boolean] Gibt an, ob Erweiterungsdecoder gegenüber Plattformdecodern bevorzugt werden.

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 boolesches Extra festgelegt werden (z.B. --ez prefer_extension_decoders TRUE). Mit --el kann ein optionales Long-Extra festgelegt werden (z.B. --el clip_start_position_ms 5000). Mit --esa kann ein optionales String-Array-Extra festgelegt werden (z.B. --esa drm_key_request_properties name1,value1).

Wenn Sie eine Playlist mit Beispielen abspielen möchten, legen Sie die Aktion des Intents auf androidx.media3.demo.main.action.VIEW_LIST fest. Die Beispielkonfigurationsextras bleiben dieselben wie für androidx.media3.demo.main.action.VIEW, mit zwei Ausnahmen:

  • Die Schlüssel der Extras sollten einen Unterstrich und den nullbasierten Index des Beispiels als Suffix haben. extension_0 würde beispielsweise den Probentyp für die erste Probe angeben. Mit drm_scheme_1 wird das DRM-Schema für das zweite Sample festgelegt.
  • Der URI des Beispiels wird als Extra mit dem Schlüssel uri_<sample-index> übergeben.

Andere Extras, die nicht von der Stichprobe abhängen, bleiben unverändert. Mit dem folgenden Befehl können Sie beispielsweise im Terminal eine Playlist mit zwei Elementen abspielen und dabei die Erweiterung des zweiten Elements ü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