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 mempermudah mencoba ExoPlayer. Aplikasi demo dapat digunakan untuk menguji pemutaran konten Anda sendiri selain sampel yang disertakan.

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 dalam 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 tampilan berikut di tampilan Project Android (folder aplikasi demo yang relevan 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 dijalankan 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 sampel (SampleChooserActivity). Memilih sampel akan membuka aktivitas kedua (PlayerActivity) untuk pemutaran. Demo ini menampilkan kontrol pemutaran dan fungsi pemilihan trek. Class ini juga menggunakan class utilitas EventLogger ExoPlayer untuk menghasilkan informasi debug yang berguna ke log sistem. Logging ini dapat dilihat (bersama dengan logging tingkat error untuk tag lain) dengan perintah:

adb logcat EventLogger:V *:E

Mengaktifkan decoder gabungan

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

  1. Bangun setiap ekstensi yang ingin Anda sertakan. Perhatikan bahwa ini adalah proses manual. Lihat file README.md di setiap ekstensi untuk mendapatkan petunjuk.

  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 demo `withDecoderExtensionsDebug`

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

Secara default, decoder ekstensi hanya akan digunakan jika tidak ada decoder platform yang sesuai. Anda dapat menentukan bahwa dekoder ekstensi harus diprioritaskan, 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. 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
]

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

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

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

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

URI file lokal dan batasan penyimpanan tercakup

Saat menentukan URI file lokal, aplikasi demo meminta izin akses penyimpanan yang diperlukan untuk membaca file ini. Namun, mulai Android 13, file arbitrer yang tidak diakhiri dengan ekstensi file media umum (seperti .mp4) tidak dapat dimuat. Jika Anda perlu memuat file tersebut, Anda dapat menempatkannya di direktori penyimpanan khusus aplikasi demo yang tidak memiliki batasan akses. File ini biasanya berada 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 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 klien email) di perangkat yang menginstal aplikasi demo juga akan membukanya di aplikasi demo. Oleh karena itu, menghosting file JSON *.exolist.json memberikan cara sederhana untuk mendistribusikan konten agar dicoba oleh orang lain di aplikasi demo.

3. Memicu intent

Intent dapat digunakan untuk melewati daftar sampel dan langsung meluncurkan pemutaran. Untuk memutar satu sampel, tetapkan tindakan intent ke androidx.media3.demo.main.action.VIEW dan URI datanya ke URI sampel yang akan 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

Ekstra opsional yang didukung untuk satu intent sampel adalah:

  • Contoh ekstra konfigurasi:
    • mime_type [String] Contoh petunjuk jenis MIME. Misalnya, application/dash+xml untuk konten DASH.
    • clip_start_position_ms [Long] Titik awal tempat sampel harus dipangkas, dalam milidetik.
    • clip_end_position_ms [Long] Titik akhir tempat sampel harus dipangkas, 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 lisensi mereka sendiri.
    • drm_key_request_properties [Array string] Header permintaan utama yang dikemas sebagai name1, value1, name2, value2, dll. jika dilindungi.
    • drm_session_for_clear_content [Boolean] Apakah akan melampirkan sesi DRM ke trek video dan audio yang tidak dienkripsi.
    • 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 ditetapkan).
    • subtitle_language [String] Kode bahasa BCP47 dari 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 dipilih daripada dekoder platform.

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

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

  • Kunci ekstra harus memiliki garis bawah dan indeks berbasis 0 dari contoh sebagai akhiran. Misalnya, extension_0 akan menunjukkan 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>.

Ekstra lainnya, yang tidak bergantung pada sampel, tidak berubah. Misalnya, Anda dapat menjalankan perintah berikut di terminal untuk memutar playlist dengan dua item, dengan mengganti 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