Aplikacja demonstracyjna ExoPlayer

Główna aplikacja w wersji demonstracyjnej ExoPlayera służy dwóm głównym celom:

Przedstawienie stosunkowo prostego, ale w pełni funkcjonalnego przykładu użycia ExoPlayera. Aplikacja w wersji demonstracyjnej może być wygodnym punktem wyjścia do opracowania własnej aplikacji.
Aby ułatwić 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 na GitHubie. 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 aplikacji na Androida powinny być widoczne te elementy (odpowiednie foldery aplikacji w wersji demonstracyjnej zostały rozwinięte):

Projekt w Android Studio

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 użyć emulatora, zapoznaj się z sekcją emulatorów na stronie Obsługiwane urządzenia i upewnij się, że wirtualne urządzenie korzysta z obrazu systemu z poziomem API co najmniej 23.

SampleChooserActivity i PlayerActivity

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 na poziomie błędu 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:

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.
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 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
]

Wymagane 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 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 w wersji demonstracyjnej 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 musisz 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 za pomocą powyższego schematu i nazwane 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 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 go w tej aplikacji w wersji demonstracyjnej. Dlatego hosting pliku JSON *.exolist.json to prosty sposób na rozpowszechnianie treści, które inni mogą wypróbować w aplikacji w wersji demonstracyjnej.

3. Wywoływanie intencji

Intencje mogą służyć do pomijania listy próbek i bezpośredniego uruchamiania 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] Identyfikator URI serwera licencji, jeśli jest chroniony.
- drm_force_default_license_uri [Boolean] Czy wymusić 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 itd. w przypadku zabezpieczenia.
- 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ą one chronione.
- subtitle_uri [String] Identyfikator URI pliku z napisami pomocniczymi.
- subtitle_mime_type [String] Typ MIME parametru subtitle_uri (wymagany, jeśli ustawiony jest parametr subtitle_uri).
- subtitle_language [String] Kod języka pliku napisów w formacie BCP47 (ignorowany, jeśli nie ustawiono parametru subtitle_uri).
- ad_tag_uri [String] Adres URI tagu reklamy do wczytania za pomocą [rozszerzenia IMA][].
- prefer_extension_decoders [Boolean] Czy dekodery rozszerzeń mają pierwszeństwo przed dekoderami 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 logiczny 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. Dodatkowe elementy przykładowej konfiguracji pozostają takie same jak w przypadku androidx.media3.demo.main.action.VIEW, z wyjątkiem 2 różnic:

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

Inne dodatki, które nie zależą od próbki, nie ulegną 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