Ta strona została przetłumaczona przez Cloud Translation API.

Aplikacja demonstracyjna ExoPlayer

Główna aplikacja demonstracyjna ExoPlayer spełnia 2 główne cele:

Prosty, a jednocześnie w pełni funkcjonalny przykład użycia ExoPlayera. Aplikacja w wersji demonstracyjnej może stanowić wygodny punkt wyjścia do tworzenia własnej aplikacji.
Aby ułatwić wypróbowanie ExoPlayer. Aplikacja demonstracyjna może służyć do testowania odtwarzania własnych treści jako uzupełnienie dołączonych przykładów.

Na tej stronie opisujemy, jak pobrać, skompilować i uruchomić aplikację w wersji demonstracyjnej oraz jak używać jej do odtwarzania własnych multimediów.

Pobieram kod

Kod źródłowy głównej aplikacji demonstracyjnej znajdziesz w folderze demos/main naszego projektu na GitHubie. Jeśli projekt nie został jeszcze skopiowany, skopiuj go do katalogu lokalnego:

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

Następnie otwórz projekt w Android Studio. W widoku projektu Android powinny się pojawić te elementy (odpowiednie foldery aplikacji demonstracyjnej zostały rozwinięte):

Projekt w Android Studio

Kompiluję i uruchamiam

Aby skompilować i uruchomić aplikację demonstracyjną, wybierz i uruchom konfigurację demo w Android Studio. Aplikacja demonstracyjna zostanie zainstalowana i uruchomiona na połączonym urządzeniu z Androidem. Jeśli to możliwe, zalecamy korzystanie z urządzenia fizycznego. Jeśli chcesz użyć emulatora, przeczytaj sekcję dotyczącą emulatorów w artykule Obsługiwane urządzenia i upewnij się, że Twoje urządzenie wirtualne używa obrazu systemu z interfejsem API poziomu co najmniej 23.

SampleChooserActivity i PlayerActivity

Aplikacja demonstracyjna wyświetla listę przykładów (SampleChooserActivity). Wybranie próbki spowoduje otwarcie drugiej aktywności (PlayerActivity) do odtwarzania. Wersja demonstracyjna zawiera elementy sterujące odtwarzaniem i funkcję wyboru ścieżki. Używa też klasy narzędzi EventLogger w programie ExoPlayer, aby przekazywać do dziennika systemowego przydatne informacje na potrzeby debugowania. To logowanie można wyświetlić (wraz z logowaniem na poziomie błędu w przypadku innych tagów) poleceniem:

adb logcat EventLogger:V *:E

Włączanie połączonych dekoderów

ExoPlayer oferuje szereg rozszerzeń, które umożliwiają korzystanie z pakietów dekoderów oprogramowania, np. AV1, VP9, Opus, FLAC i FFmpeg (tylko dźwięk). Aplikację w wersji demonstracyjnej można utworzyć w taki sposób:

Utwórz wszystkie rozszerzenia, które chcesz uwzględnić. Pamiętaj, że to proces wykonywany ręcznie. Instrukcje znajdziesz w pliku README.md w każdym rozszerzeniu.
W widoku Warianty kompilacji w Android Studio ustaw wariant kompilacji modułu demonstracyjnego na withDecoderExtensionsDebug lub withDecoderExtensionsRelease, jak pokazano na ilustracji poniżej.
Skompiluj, zainstaluj i uruchom konfigurację demo w zwykły sposób.

Domyślnie dekoder rozszerzeń będzie używany tylko wtedy, gdy nie istnieje odpowiedni dekoder platformy. Możesz określić, że preferowane powinny być dekodery rozszerzeń zgodnie z opisem w sekcjach poniżej.

Odtwarzanie własnych treści

W aplikacji demonstracyjnej można odtwarzać własne treści na kilka sposobów.

1. Edytowanie zasobów/media.exolist.json

Próbki wymienione w aplikacji demonstracyjnej są wczytywane z assets/media.exolist.json. Edytując ten plik JSON, możesz dodawać i usuwać próbki z aplikacji demonstracyjnej. Schemat jest następujący, gdzie [O] oznacza opcjonalny atrybut.

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

Playlisty z próbkami można określić za pomocą schematu:

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

W razie potrzeby nagłówki żądania klucza są określane jako obiekt zawierający atrybut ciągu znaków dla każdego nagłówka:

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

W przypadku przykładowego selektora rozszerzone menu zawiera opcje umożliwiające określenie, czy preferować dekodery rozszerzeń.

Lokalne identyfikatory URI plików i ograniczenia dotyczące miejsca na dane

Gdy określasz lokalne identyfikatory URI plików, aplikacja w wersji demonstracyjnej wymaga uprawnień dostępu do pamięci potrzebnych do odczytu tych plików. Jednak na Androidzie 13 nie można wczytywać dowolnych plików z typowym rozszerzeniem plików multimedialnych (takim jak .mp4). Jeśli chcesz załadować taki plik, możesz go umieścić w katalogu pamięci przeznaczonym do wersji demonstracyjnej, który nie ma ograniczeń dostępu. Zwykle znajduje się on w: /sdcard/Android/data/androidx.media3.demo.main/files.

2. Wczytuję zewnętrzny plik exolist.json

Aplikacja demonstracyjna może wczytywać zewnętrzne pliki JSON za pomocą powyższego schematu i nazwane zgodnie z konwencją *.exolist.json. Jeśli np. hostujesz taki plik pod adresem https://yourdomain.com/samples.exolist.json, możesz go otworzyć w aplikacji demonstracyjnej, używając:

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

Kliknięcie linku *.exolist.json (np. w przeglądarce lub w kliencie poczty e-mail) na urządzeniu z zainstalowaną aplikacją demonstracyjną spowoduje również jej otwarcie w aplikacji demonstracyjnej. Hostowanie pliku JSON *.exolist.json to prosty sposób na rozpowszechnianie treści, aby inni mogli ją wypróbować w aplikacji demonstracyjnej.

3. Uruchamianie intencji

Intencje mogą służyć do pomijania listy próbek i uruchamiania ich bezpośrednio w trybie odtwarzania. Aby odtworzyć pojedynczy przykład, ustaw działanie intencji na androidx.media3.demo.main.action.VIEW, a jego identyfikator URI danych odpowiada identyfikatorowi próbki do odtworzenia. Taką intencję można uruchomić z terminala za pomocą:

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

Obsługiwane opcjonalne dodatki w jednej przykładowej intencji to:

Przykładowe dodatki do konfiguracji:
- mime_type [String] Przykładowa wskazówka dotycząca typu MIME. Na przykład application/dash+xml w przypadku treści DASH.
- clip_start_position_ms [Long] Punkt początkowy, do którego należy przyciąć próbkę, podany w milisekundach.
- clip_end_position_ms [Long] Punkt końcowy, od którego należy przyciąć próbkę, podany w milisekundach.
- drm_scheme [String] Schemat DRM, jeśli jest chroniony. Prawidłowe wartości to widevine, playready i clearkey. Akceptowane są też identyfikatory UUID schematu DRM.
- drm_license_uri [Ciąg] Identyfikator URI serwera licencji, jeśli jest chroniony.
- drm_force_default_license_uri [Wartość logiczna] Określa, czy wymuszać użycie drm_license_uri w żądaniach kluczy, które zawierają własny identyfikator URI licencji.
- drm_key_request_properties [Tablica ciągu znaków] Nagłówki żądań kluczy w formacie nazwa1, wartość1, nazwa2, wartość2 itd., jeśli są chronione.
- drm_session_for_clear_content [Wartość logiczna] Określa, czy dołączyć sesję DRM, aby usunąć ścieżki wideo i audio.
- drm_multi_session [Wartość logiczna] włącza rotację klucza, jeśli jest chroniona.
- subtitle_uri [String] Identyfikator URI pliku pomocniczego napisów.
- subtitle_mime_type [String] Typ MIME identyfikatora Caption_uri (wymagany, jeśli ustawiony jest element Caption_uri).
- subtitle_language [String] Kod języka BCP47 pliku napisów (ignorowany, jeśli nie ustawiono atrybutu Caption_uri).
- ad_tag_uri [Ciąg] Identyfikator URI tagu reklamy do wczytania za pomocą [rozszerzenia IMA][].
- prefer_extension_decoders [wartość logiczna] Określa, czy dekodery rozszerzeń są preferowane od dekoderów platformy.

Gdy do uruchamiania intencji używasz polecenia adb shell am start, za pomocą elementu --es można dodać opcjonalny ciąg znaków (np. --es extension mpd). Opcjonalny dodatek logiczny można ustawić za pomocą parametru --ez (np. --ez prefer_extension_decoders TRUE). Opcjonalny długi dodatkowy element można ustawić za pomocą parametru --el (np. --el clip_start_position_ms 5000). Opcjonalną tablicę ciągów znaków można ustawić za pomocą parametru --esa (np. --esa drm_key_request_properties name1,value1).

Aby odtworzyć playlistę z samplami, ustaw działanie intencji na androidx.media3.demo.main.action.VIEW_LIST. Przykładowe elementy konfiguracji są takie same jak w przypadku elementu androidx.media3.demo.main.action.VIEW, z wyjątkiem 2 różnic:

Klucze dodatków powinny mieć sufiks jako sufiks, a indeks próbki liczony od 0. Na przykład extension_0 może wskazywać typ pierwszej próbki. drm_scheme_1 ustawiłby schemat DRM dla drugiej próbki.
Identyfikator URI próbki jest przekazywany jako dodatkowy z kluczem uri_<sample-index>.

Inne dodatki, które nie są zależne od przykładu, nie ulegają zmianie. Możesz na przykład uruchomić w terminalu to polecenie, aby odtworzyć playlistę z 2 elementami i zastąpić rozszerzenie drugiego elementu:

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