Aplikasi demo ExoPlayer

Aplikasi demo utama ExoPlayer memiliki dua tujuan utama:

  1. Untuk memberikan contoh penggunaan ExoPlayer yang relatif sederhana tetapi berfitur lengkap. Aplikasi demo dapat digunakan sebagai titik awal yang praktis untuk mengembangkan aplikasi Anda sendiri.
  2. Untuk memudahkan saya mencoba ExoPlayer. Selain contoh yang disertakan, aplikasi demo dapat digunakan untuk menguji pemutaran konten Anda sendiri.

Halaman ini menjelaskan cara mendapatkan, mengompilasi, dan menjalankan aplikasi demo. Halaman ini juga menjelaskan cara menggunakannya untuk memutar media Anda sendiri.

Mendapatkan kode

Kode sumber untuk aplikasi demo utama dapat ditemukan di folder demos/main pada project GitHub kami. Jika Anda belum melakukannya, clone project ke direktori lokal:

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

Selanjutnya, buka project di Android Studio. Anda akan melihat berikut ini di tampilan Project Android (folder yang relevan dari aplikasi demo telah diluaskan):

Project di Android Studio

Mengompilasi dan menjalankan

Untuk mengompilasi dan menjalankan aplikasi demo, pilih dan jalankan konfigurasi demo di Android Studio. Aplikasi demo akan diinstal dan berjalan di perangkat Android yang terhubung. Sebaiknya gunakan perangkat fisik jika memungkinkan. Jika Anda ingin menggunakan emulator, baca bagian emulator di Perangkat yang didukung dan pastikan Perangkat Virtual Anda menggunakan image sistem dengan level API minimal 23.

SampleChooserActivity dan PlayerActivity

Aplikasi demo menampilkan daftar contoh (SampleChooserActivity). Memilih contoh akan membuka aktivitas kedua (PlayerActivity) untuk pemutaran. Demo ini menampilkan kontrol pemutaran dan fungsi pemilihan trek. Library ini juga menggunakan class utilitas EventLogger ExoPlayer untuk menghasilkan informasi debug yang berguna ke log sistem. Logging ini dapat dilihat (beserta logging tingkat error untuk tag lainnya) dengan perintah:

adb logcat EventLogger:V *:E

Mengaktifkan decoder yang dipaketkan

ExoPlayer memiliki sejumlah ekstensi yang memungkinkan penggunaan dekoder software yang dipaketkan, termasuk AV1, VP9, Opus, FLAC, dan FFmpeg (khusus audio). Aplikasi demo dapat dibuat untuk menyertakan dan menggunakan ekstensi ini sebagai berikut:

  1. Buat setiap ekstensi yang ingin Anda sertakan. Perhatikan bahwa ini adalah proses manual. Lihat file README.md di setiap ekstensi untuk mengetahui petunjuknya.

  2. Di tampilan Build Variants Android Studio, tetapkan varian build untuk modul demo ke withDecoderExtensionsDebug atau withDecoderExtensionsRelease seperti yang ditunjukkan pada gambar berikut.

    Memilih varian build `withDecoderExtensionsDebug` demo

  3. Kompilasi, instal, dan jalankan konfigurasi demo seperti biasa.

Secara default, decoder ekstensi hanya akan digunakan jika decoder platform yang cocok tidak ada. Anda dapat menentukan bahwa dekoder ekstensi harus lebih disukai, seperti yang dijelaskan di bagian berikut.

Memutar konten Anda sendiri

Ada beberapa cara untuk memutar konten Anda sendiri di aplikasi demo.

1. Mengedit aset/media.exolist.json

Contoh yang tercantum dalam aplikasi demo dimuat dari assets/media.exolist.json. Dengan mengedit file JSON ini, Anda dapat menambahkan dan menghapus sampel dari aplikasi demo. Skemanya adalah sebagai berikut, dengan [O] menunjukkan atribut opsional.

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

Daftar putar contoh dapat ditentukan menggunakan skema:

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

Jika diperlukan, header permintaan kunci ditentukan sebagai objek yang berisi atribut string untuk setiap header:

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

Dalam aktivitas pemilih contoh, menu tambahan berisi opsi untuk menentukan apakah akan lebih memilih dekoder ekstensi.

URI file lokal dan batasan penyimpanan terbatas

Saat menentukan URI file lokal, aplikasi demo akan meminta izin akses penyimpanan yang diperlukan untuk membaca file ini. Namun, mulai Android 13, Anda tidak dapat memuat file arbitrer yang tidak diakhiri dengan ekstensi file media biasa (seperti .mp4). Jika perlu memuat file tersebut, Anda dapat menempatkannya di direktori penyimpanan khusus aplikasi demo yang tidak memiliki pembatasan akses. Ini biasanya terletak di /sdcard/Android/data/androidx.media3.demo.main/files.

2. Memuat file exolist.json eksternal

Aplikasi demo dapat memuat file JSON eksternal menggunakan skema di atas dan diberi nama sesuai dengan konvensi *.exolist.json. Misalnya, jika menghosting file tersebut di https://yourdomain.com/samples.exolist.json, Anda dapat membukanya di aplikasi demo menggunakan:

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

Mengklik link *.exolist.json (misalnya, di browser atau program email) di perangkat yang sudah diinstal aplikasi demo juga akan membukanya di aplikasi demo. Oleh karena itu, menghosting file JSON *.exolist.json akan menyediakan cara mudah mendistribusikan konten kepada orang lain untuk dicoba di aplikasi demo.

3. Mengaktifkan intent

Intent dapat digunakan untuk mengabaikan daftar contoh dan meluncurkan langsung ke pemutaran. Untuk memutar satu contoh, tetapkan tindakan intent ke androidx.media3.demo.main.action.VIEW dan URI datanya ke tindakan contoh yang akan diputar. Intent tersebut dapat dipicu dari terminal menggunakan:

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

Tambahan opsional yang didukung untuk contoh intent tunggal adalah:

  • Contoh tambahan konfigurasi:
    • mime_type [String] Contoh petunjuk jenis MIME. Misalnya, application/dash+xml untuk konten DASH.
    • clip_start_position_ms [Panjang] Titik awal tempat sampel harus dipotong, dalam milidetik.
    • clip_end_position_ms [Panjang] Titik akhir tempat sampel harus dipotong, dalam milidetik.
    • drm_scheme Skema DRM [String] jika dilindungi. Nilai yang valid adalah widevine, playready, dan clearkey. UUID skema DRM juga diterima.
    • drm_license_uri [String] URI server lisensi jika dilindungi.
    • drm_force_default_license_uri [Boolean] Apakah akan memaksa penggunaan drm_license_uri untuk permintaan kunci yang menyertakan URI lisensinya sendiri.
    • drm_key_request_properties [String array] Header permintaan kunci yang dikemas sebagai name1, value1, name2, value2, dst. jika dilindungi.
    • drm_session_for_clear_content [Boolean] Apakah akan melampirkan sesi DRM untuk menghapus trek video dan audio.
    • drm_multi_session [Boolean] Mengaktifkan rotasi kunci jika dilindungi.
    • subtitle_uri [String] URI file bantuan subtitel.
    • subtitle_mime_type [String] Jenis MIME subtitle_uri (wajib jika subtitle_uri disetel).
    • subtitle_language [String] Kode bahasa BCP47 file subtitel (diabaikan jika subtitle_uri tidak ditetapkan).
    • ad_tag_uri [String] URI tag iklan yang akan dimuat menggunakan [ekstensi IMA][].
    • prefer_extension_decoders [Boolean] Apakah dekoder ekstensi lebih disukai daripada dekoder platform.

Saat menggunakan adb shell am start untuk mengaktifkan intent, string tambahan opsional dapat ditetapkan dengan --es (misalnya, --es extension mpd). Tambahan boolean opsional dapat ditetapkan dengan --ez (misalnya, --ez prefer_extension_decoders TRUE). Tambahan panjang opsional dapat ditetapkan dengan --el (misalnya, --el clip_start_position_ms 5000). Tambahan array string opsional dapat ditetapkan dengan --esa (misalnya, --esa drm_key_request_properties name1,value1).

Untuk memutar playlist contoh, tetapkan tindakan intent ke androidx.media3.demo.main.action.VIEW_LIST. Contoh tambahan konfigurasi tetap sama seperti untuk androidx.media3.demo.main.action.VIEW, kecuali untuk dua perbedaan:

  • Kunci tambahan harus memiliki garis bawah dan indeks berbasis 0 dari sampel sebagai akhiran. Misalnya, extension_0 akan mengisyaratkan jenis sampel untuk sampel pertama. drm_scheme_1 akan menetapkan skema DRM untuk sampel kedua.
  • URI sampel diteruskan sebagai tambahan dengan kunci uri_<sample-index>.

Tambahan lainnya, yang tidak bergantung pada sampel, tidak berubah. Misalnya, Anda dapat menjalankan perintah berikut di terminal untuk memutar playlist dengan dua item, yang menggantikan ekstensi item kedua:

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