Aplikacja demonstracyjna ExoPlayer

Główna aplikacja w wersji demonstracyjnej ExoPlayera służy do 2 głównych celów:

1. Aby przedstawić w pełni funkcjonalny przykład użycia ExoPlayera. Aplikacja demonstracyjna może być wygodnym punktem wyjścia do opracowania własnej aplikacji.
2. umożliwiać wypróbowanie ExoPlayera; Aplikacja w wersji demonstracyjnej umożliwia testowanie odtwarzania własnych treści oprócz dołączonych próbek.

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

Pobieranie kodu

Kod źródłowy głównej aplikacji w wersji demonstracyjnej znajdziesz w demos/main folderze naszego projektu GitHub. Jeśli nie masz jeszcze sklonowanego projektu, sklonuj go do katalogu lokalnego:

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

Następnie otwórz projekt w Android Studio. W widoku Projekt Androida powinny być widoczne te elementy (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 w wersji demonstracyjnej zostanie zainstalowana i uruchomiona na podłączonym urządzeniu z Androidem. Jeśli to możliwe, zalecamy używanie urządzenia fizycznego. Jeśli chcesz zamiast tego użyć emulatora, przeczytaj sekcję dotyczącą emulatorów w artykule Obsługiwane urządzenia i upewnij się, że wirtualne urządzenie korzysta z obrazu systemu z poziomem API co najmniej 23.

Aplikacja w wersji demonstracyjnej zawiera listę próbek (SampleChooserActivity). Wybranie próbki spowoduje otwarcie drugiego działania (PlayerActivity) w celu odtworzenia. Wersja demonstracyjna zawiera elementy sterujące odtwarzaniem i funkcję wyboru ścieżki. Korzysta też z klasy narzędziowej EventLogger ExoPlayera, aby przekazywać przydatne informacje do debugowania do logu systemowego. Rejestrowanie to można wyświetlić (wraz z rejestrowaniem poziomu błędów w przypadku innych tagów) za pomocą polecenia:

adb logcat EventLogger:V *:E

Włączanie dekoderów w pakiecie

ExoPlayer ma wiele rozszerzeń, które umożliwiają korzystanie z dołączonych dekoderów oprogramowania, w tym AV1, VP9, Opus, FLAC i FFmpeg (tylko audio). Aplikację w wersji demonstracyjnej można utworzyć tak, aby zawierała te rozszerzenia i z nich korzystała:

1. Utwórz każde rozszerzenie, które chcesz uwzględnić. Pamiętaj, że jest to proces ręczny. Instrukcje znajdziesz w README.md pliku w każdym rozszerzeniu.

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 normalny sposób.

Domyślnie dekoder rozszerzenia jest używany tylko wtedy, gdy nie ma odpowiedniego dekodera platformy. Można określić, że dekodery rozszerzeń powinny być preferowane, jak opisano w sekcjach poniżej.

Odtwarzanie własnych treści

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

1. Edytowanie pliku assets/media.exolist.json

Próbki wymienione w aplikacji w wersji 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 atrybut opcjonalny:

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

Listy odtwarzania próbek można określić za pomocą tego 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. 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
]

W razie potrzeby kluczowe nagłówki żądań 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 aktywności wyboru próbki rozszerzone menu zawiera opcje określania, czy preferować dekodery rozszerzeń.

Identyfikatory URI plików lokalnych i ograniczenia dotyczące ograniczonego dostępu do miejsca na dane

Podczas określania identyfikatorów URI plików lokalnych aplikacja demonstracyjna prosi o niezbędne uprawnienia dostępu do pamięci, aby odczytać te pliki. Jednak od Androida 13 nie można wczytywać dowolnych plików, które nie mają typowego rozszerzenia pliku multimedialnego (np. .mp4). Jeśli chcesz wczytać taki plik, możesz umieścić go w określonym katalogu pamięci aplikacji demonstracyjnej, który nie ma ograniczeń dostępu. Zwykle znajduje się on w lokalizacji /sdcard/Android/data/androidx.media3.demo.main/files.

2. Wczytywanie zewnętrznego pliku exolist.json

Aplikacja w wersji demonstracyjnej może wczytywać zewnętrzne pliki JSON, które są zgodne z powyższym schematem i mają nazwy zgodne 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 w wersji demonstracyjnej za pomocą tego kodu:

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ą w wersji demonstracyjnej spowoduje otwarcie jej w tej aplikacji. Umieszczenie pliku JSON *.exolist.json umożliwia rozpowszechnianie treści, które inni użytkownicy mogą wypróbować w aplikacji w wersji demonstracyjnej.

3. Uruchamianie intencji

Intencje można wykorzystać do pominięcia listy próbek i bezpośredniego uruchomienia odtwarzania. Aby odtworzyć pojedynczą próbkę, ustaw działanie intencji na androidx.media3.demo.main.action.VIEW, a identyfikator URI danych na identyfikator URI próbki do odtworzenia. Taki zamiar można wywołać z terminala za pomocą tego polecenia:

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

Obsługiwane opcjonalne dodatki do pojedynczego przykładowego zamiaru to:

• Dodatki do przykładowej 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ę, w milisekundach.
  • clip_end_position_ms [Long] Punkt końcowy, od którego należy przyciąć próbkę, 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 [String] URI serwera licencji, jeśli jest chroniony.
  • drm_force_default_license_uri [Boolean] Czy wymuszać użycie metody drm_license_uri w przypadku żądań kluczy, które zawierają własny identyfikator URI licencji.
  • drm_key_request_properties [Tablica tekstowa] Nagłówki żądania klucza spakowane jako name1, value1, name2, value2 itp. w przypadku ochrony.
  • drm_session_for_clear_content [Boolean] Określa, czy dołączyć sesję DRM do nieszyfrowanych ścieżek audio i wideo.
  • drm_multi_session [Boolean] Włącza rotację kluczy, jeśli są chronione.
  • subtitle_uri [String] Identyfikator URI pliku z napisami pomocniczymi.
  • subtitle_mime_type [String] Typ MIME atrybutu subtitle_uri (wymagany, jeśli ustawiono atrybut subtitle_uri).
  • subtitle_language [String] Kod języka pliku napisów w standardzie BCP47 (ignorowany, jeśli nie ustawiono parametru subtitle_uri).
  • ad_tag_uri [String] Identyfikator URI tagu reklamy do wczytania za pomocą rozszerzenia IMA.
  • prefer_extension_decoders [Boolean] Określa, czy dekodery rozszerzeń są preferowane w stosunku do dekoderów platformy.

Podczas używania adb shell am start do wywoływania intencji można ustawić opcjonalny dodatkowy ciąg znaków za pomocą --es (np. --es extension mpd). Opcjonalny dodatkowy parametr wartości logicznej można ustawić za pomocą --ez (np. --ez prefer_extension_decoders TRUE). Opcjonalny dodatkowy parametr typu long można ustawić za pomocą --el (np. --el clip_start_position_ms 5000). Opcjonalny dodatkowy parametr w postaci tablicy tekstowej można ustawić za pomocą --esa (np. --esa drm_key_request_properties name1,value1).

Aby odtworzyć playlistę próbek, ustaw działanie intencji na androidx.media3.demo.main.action.VIEW_LIST. Przykładowe konfiguracje dodatkowe pozostają takie same jak w przypadku androidx.media3.demo.main.action.VIEW, z wyjątkiem 2 różnic:

• Klucze dodatkowych informacji powinny mieć w sufiksie znak podkreślenia i indeks próbki liczony od zera. Na przykład extension_0 wskazuje typ próbki dla pierwszej próbki. drm_scheme_1 ustawi schemat DRM dla drugiego próbnego pliku.
• Identyfikator URI próbki jest przekazywany jako dodatkowy element z kluczem uri_<sample-index>.

Inne dodatki, które nie zależą od próbki, nie ulegają zmianie. Na przykład w terminalu możesz uruchomić to polecenie, aby odtworzyć playlistę z 2 elementami, 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