Aplikacja demonstracyjna ExoPlayer

Główna aplikacja demonstracyjna ExoPlayer służy do dwóch głównych celów:

1. Aby przedstawić stosunkowo prosty, ale 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.
2. Aby ułatwić wypróbowanie ExoPlayera. Aplikację demo można wykorzystać do testowania odtwarzania własnych treści oprócz dołączonych próbek.

Na tej stronie opisaliśmy, jak pobrać, skompilować i uruchomić aplikację demonstracyjną. Omówiliśmy też, jak używać jej do odtwarzania własnych multimediów.

Pobieranie kodu

Kod źródłowy głównej aplikacji demonstracyjnej znajdziesz w folderze demos/main w naszym projekcie na GitHubie. Jeśli nie masz jeszcze skopiowanego projektu do lokalnego katalogu:

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

Następnie otwórz projekt w Android Studio. W widoku projektu na Androida powinny być widoczne następujące foldery (odpowiednie foldery aplikacji w wersji demonstracyjnej zostały rozwinięte):

Kompilowanie i uruchamianie

Aby skompilować i uruchomić aplikację w wersji demonstracyjnej, wybierz i uruchom konfigurację demo w Android Studio. Aplikacja demonstracyjna zostanie zainstalowana i uruchomiona na połączonym urządzeniu z Androidem. Zalecamy korzystanie z fizycznego urządzenia, jeśli to możliwe. 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 korzysta z obrazu systemu na poziomie API 23 lub wyższym.

Aplikacja demonstracyjna zawiera listę próbek (SampleChooserActivity). Po wybraniu próbki otworzy się druga aktywność (PlayerActivity) do odtwarzania. Demonstracja zawiera elementy sterujące odtwarzaniem i funkcje wyboru utworów. Korzysta też z klasy pomocniczej EventLogger ExoPlayera do wyświetlania przydatnych informacji debugujących w dzienniku systemowym. Logowanie możesz wyświetlić (wraz z logowaniem na poziomie błędu innych tagów) za pomocą polecenia:

adb logcat EventLogger:V *:E

Włączanie pakietów dekoderów

ExoPlayer ma kilka rozszerzeń, które umożliwiają korzystanie z dołączonych dekoderów oprogramowania, w tym AV1, VP9, Opus, FLAC i FFmpeg (tylko audio). Aplikację demonstracyjną można zbudować tak, aby zawierała te rozszerzenia i je używała:

1. Utwórz wszystkie rozszerzenia, które chcesz uwzględnić. Pamiętaj, że jest to proces manualny. Instrukcje znajdziesz w pliku README.md w poszczególnych rozszerzeniach.

2. W widoku Warianty kompilacji w Android Studio ustaw wariant kompilacji modułu demonstracyjnego na withDecoderExtensionsDebug lub withDecoderExtensionsRelease, jak pokazano na ilustracji poniżej.

   

3. Skompiluj, zainstaluj i uruchom konfigurację demo w zwykły sposób.

Domyślnie dekoder rozszerzeń będzie używany tylko wtedy, gdy nie ma odpowiedniego dekodera platformy. Można określić, że dekodery rozszerzeń powinny być preferowane, jak opisano w następnych sekcjach.

Odtwarzanie własnych treści

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

1. Edytowanie pliku assets/media.exolist.json

Przykłady wymienione w aplikacji w wersji demonstracyjnej są wczytywane z okresu assets/media.exolist.json. Poprzez edytowanie tego pliku JSON można dodawać i usuwać próbki z aplikacji demonstracyjnej. Schemat jest następujący, gdzie [O] oznacza atrybut opcjonalny.

[
  {
    "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 kluczowe nagłówki żądań są określone jako obiekt zawierający atrybut ciągu znaków dla każdego nagłówka:

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

W przykładowym działaniu selektora rozszerzone menu zawiera opcje pozwalające określić, czy preferowane są dekodery rozszerzeń.

Identyfikatory URI plików lokalnych i ograniczenia dotyczące miejsca na dane

Podczas podawania identyfikatorów URI plików lokalnych aplikacja demonstracyjna prosi o wymagane uprawnienia dostępu do pamięci masowej, aby móc odczytać te pliki. Jednak od Androida 13 nie można wczytywać dowolnych plików, które nie kończą się typową rozszerzeniem pliku multimedialnego (np. .mp4). Jeśli chcesz wczytać taki plik, możesz go umieścić w specyficznym katalogu pamięci aplikacji demonstracyjnej, który nie ma ograniczeń dostępu. Zwykle znajduje się on w miejscu o adresie /sdcard/Android/data/androidx.media3.demo.main/files.

2. Wczytywanie zewnętrznego pliku exolist.json

Aplikacja demonstracyjna może ładować zewnętrzne pliki JSON przy użyciu powyższego schematu i nazywać je zgodnie z konwencją *.exolist.json. Jeśli na przykład hostujesz taki plik pod adresem https://yourdomain.com/samples.exolist.json, możesz go otworzyć w aplikacji demonstracyjnej za pomocą:

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 kliencie poczty e-mail) na urządzeniu z zainstalowaną aplikacją demonstracyjną spowoduje jej otwarcie. Udostępnianie pliku JSON *.exolist.json to prosty sposób na rozpowszechnianie treści, które inni użytkownicy mogą wypróbować w aplikacji demonstracyjnej.

3. Uruchamianie intencji

Intencje mogą służyć do pominięcia listy próbek i uruchomienia odtwarzania bezpośrednio. Aby odtworzyć 1 próbkę, ustaw działanie intencji na androidx.media3.demo.main.action.VIEW, a identyfikator URI danych na próbkę do odtworzenia. Takie działanie może być wywoływane 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 przypadku pojedynczej przykładowej intencji to:

• Przykładowe dodatki do konfiguracji:
  • mime_type [Ciąg] Przykładowa wskazówka na temat typu MIME. Na przykład application/dash+xml w przypadku treści DASH.
  • clip_start_position_ms [Long] Punkt początkowy, w którym ma zostać przycięta próbka, w milisekundach.
  • clip_end_position_ms [Long] Punkt końcowy, od którego ma być przycinana próbka (w milisekundach).
  • drm_scheme [Ciąg znaków] 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 [String] Identyfikator URI serwera licencji, jeśli jest chroniony.
  • drm_force_default_license_uri [Boolean] Określa, czy należy wymusić użycie parametru drm_license_uri w przypadku żądań kluczy, które zawierają własny identyfikator URI licencji.
  • drm_key_request_properties [Tablica ciągów znaków] Kluczowe nagłówki żądania zapakowane jako nazwa1, wartość1, nazwa2, wartość2 itd., jeśli są chronione.
  • drm_session_for_clear_content [Boolean] Określa, czy załączyć sesję DRM, aby wyczyścić ścieżki wideo i audio.
  • drm_multi_session [Boolean] Włącza rotację kluczy, jeśli jest chroniona.
  • subtitle_uri [Ciąg] Identyfikator URI pliku pomocniczego napisów.
  • subtitle_mime_type [Ciąg] Typ MIME parametru Caption_uri (wymagany, jeśli ustawiono parametr Caption_uri).
  • subtitle_language [String] Kod języka BCP47 pliku napisów (ignorowany, jeśli parametr subtitle_uri nie jest ustawiony).
  • ad_tag_uri [Ciąg] Identyfikator URI tagu reklamy do wczytania za pomocą [rozszerzenia IMA][].
  • prefer_extension_decoders [Wartość logiczna] Określa, czy dekodery w rozszerzeniu są preferowane od dekoderów platformy.

Gdy używasz adb shell am start do wywołania intencji, możesz ustawić opcjonalny ciąg dodatkowych informacji za pomocą --es (np. --es extension mpd). Opcjonalny parametr logiczny można ustawić za pomocą atrybutu --ez (np. --ez prefer_extension_decoders TRUE). Opcjonalnie można ustawić dodatkowy tekst za pomocą parametru --el (np. --el clip_start_position_ms 5000). Opcjonalny dodatkowy ciąg znaków w tablicy można ustawić za pomocą --esa (np. --esa drm_key_request_properties name1,value1).

Aby odtworzyć playlistę z próbkami, ustaw działanie intencji na androidx.media3.demo.main.action.VIEW_LIST. W przykładzie konfiguracji dodatki pozostają takie same jak w przypadku androidx.media3.demo.main.action.VIEW, z 2 wyjątkami:

• Klucze dodatkowych informacji powinny zawierać znak podkreślenia i indeks próbki oparty na 0 jako sufiks. Na przykład extension_0 wskazuje typ próbki dla pierwszej próbki. drm_scheme_1 ustawiłby schemat DRM dla drugiego przykładu.
• Identyfikator URI próbki jest przekazywany jako dodatkowy za pomocą klucza uri_<sample-index>.

Pozostałe dodatki, które nie zależą od próbki, nie ulegają zmianie. Aby odtworzyć playlistę z dwoma elementami, możesz na przykład uruchomić w terminalu to polecenie, zastępując 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