Aplikasi demo ExoPlayer

Aplikasi demo utama ExoPlayer memiliki dua tujuan utama:

  1. Untuk memberikan contoh penggunaan ExoPlayer yang relatif sederhana namun berfitur lengkap. Aplikasi demo dapat digunakan sebagai titik awal yang mudah untuk mengembangkan aplikasi Anda sendiri.
  2. Untuk memudahkan Anda mencoba ExoPlayer. Aplikasi demo dapat digunakan untuk menguji pemutaran konten Anda sendiri selain contoh yang disertakan.

Halaman ini menjelaskan cara mendapatkan, mengompilasi, dan menjalankan aplikasi demo. 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 kita. Jika Anda belum melakukannya, clone project ke dalam direktori lokal:

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

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

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 Sebagai gantinya, baca bagian emulator dari Perangkat yang didukung dan pastikan bahwa Perangkat Virtual Anda menggunakan image sistem dengan API level minimal 23.

SampleChooserActivity dan PlayerActivity

Aplikasi demo menyajikan daftar contoh (SampleChooserActivity). Memilih contoh akan membuka aktivitas kedua (PlayerActivity) untuk pemutaran. Demo memiliki fitur kontrol pemutaran dan fungsi pemilihan trek. {i>Tcpdump<i} juga menggunakan Class utilitas EventLogger ExoPlayer untuk output informasi debug yang berguna ke log sistem. Pencatatan log ini dapat dilihat (bersamaan dengan pencatatan tingkat {i>error<i} untuk tag lainnya) dengan perintah:

adb logcat EventLogger:V *:E

Mengaktifkan decoder paket

ExoPlayer memiliki sejumlah ekstensi yang memungkinkan penggunaan software yang dipaketkan decoder, 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 petunjuk.

  2. Dalam tampilan Varian Build Android Studio, tetapkan varian build untuk demo modul ke withDecoderExtensionsDebug atau withDecoderExtensionsRelease sebagai yang ditampilkan dalam 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 sesuai tidak ada. Anda dapat menentukan bahwa decoder ekstensi pilihan, seperti yang dijelaskan di bagian berikut.

Memutar konten Anda sendiri

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

1. Mengedit assets/media.exolist.json

Contoh yang tercantum dalam aplikasi demo dimuat dari assets/media.exolist.json. Dengan mengedit file JSON ini, Anda dapat menambah dan menghapus sampel dari 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
]

Playlist sampel 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 ditetapkan sebagai objek yang berisi string untuk setiap {i>header<i}:

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

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

URI file lokal dan batasan penyimpanan terbatas

Saat menentukan URI file lokal, aplikasi demo akan meminta penyimpanan yang diperlukan izin akses untuk membaca file ini. Namun, dari Android 13, dapat digunakan untuk memuat file arbitrer yang tidak diakhiri dengan file media biasa (seperti .mp4). Jika Anda perlu memuat file tersebut, Anda dapat memasukkannya direktori penyimpanan khusus aplikasi demo yang tidak memiliki pembatasan akses. Ini biasanya berlokasi 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 Anda menghosting 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 email di perangkat dengan aplikasi demo yang terinstal juga akan membukanya dalam demo . Oleh karena itu, menghosting file JSON *.exolist.json menyediakan cara yang mudah untuk mendistribusikan konten untuk dicoba orang lain di aplikasi demo.

3. Mengaktifkan intent

Intent dapat digunakan untuk melewati daftar contoh dan meluncurkannya langsung ke pemutaran. Untuk memutar satu contoh, tetapkan tindakan intent ke androidx.media3.demo.main.action.VIEW dan URI datanya ke URL sampel untuk diputar. Intent tersebut dapat diaktifkan 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 satu intent contoh 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 seharusnya terpotong, dalam milidetik.
    • clip_end_position_ms [Panjang] Titik akhir dari mana sampel seharusnya berada terpotong, dalam milidetik.
    • drm_scheme [String] Skema DRM 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 [Array string] Header permintaan kunci dikemas sebagai name1, value1, name2, value2 dll. jika dilindungi.
    • drm_session_for_clear_content [Boolean] Apakah akan melampirkan sesi DRM untuk membersihkan 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 (diperlukan jika subtitle_uri disetel).
    • subtitle_language [String] Kode bahasa BCP47 untuk 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 decoder ekstensi lebih disukai daripada platform.

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

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

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

Tambahan lainnya, yang tidak bergantung pada sampel, tidak berubah. Sebagai contoh, Anda dapat menjalankan perintah berikut di terminal untuk memutar {i>playlist<i} dengan dua item, mengganti ekstensi dari 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