Aplikasi demo ExoPlayer

Aplikasi demo utama ExoPlayer memiliki dua tujuan utama:

  1. Untuk memberikan contoh penggunaan ExoPlayer yang relatif sederhana namun 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 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 project GitHub kami. 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 hal berikut dalam 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, 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 ini menyajikan daftar contoh (SampleChooserActivity). Memilih contoh akan membuka aktivitas kedua (PlayerActivity) untuk pemutaran. Demo ini menampilkan kontrol pemutaran dan fungsi pemilihan lagu. Class ini juga menggunakan class utilitas EventLogger ExoPlayer untuk menghasilkan informasi debug yang berguna ke log sistem. Logging ini dapat dilihat (beserta logging level error untuk tag lain) dengan perintah:

adb logcat EventLogger:V *:E

Mengaktifkan dekoder yang dipaketkan

ExoPlayer memiliki sejumlah ekstensi yang memungkinkan penggunaan decoder 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. Build 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 demo `withDecoderExtensionsDebug`

  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 diprioritaskan, 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

Sampel yang tercantum di 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
]

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 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 memilih dekoder ekstensi.

URI file lokal dan pembatasan penyimpanan terbatas

Saat menentukan URI file lokal, aplikasi demo 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 standar (seperti .mp4). Jika perlu memuat file tersebut, Anda dapat menempatkannya di direktori penyimpanan khusus aplikasi demo yang tidak memiliki batasan akses. Hal 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 menghosting file seperti itu 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 telah menginstal aplikasi demo juga akan membukanya di aplikasi demo. Oleh karena itu, menghosting file JSON *.exolist.json memberikan cara mudah mendistribusikan konten kepada orang lain untuk dicoba di aplikasi demo.

3. Memicu intent

Intent dapat digunakan untuk mengabaikan 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

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 [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 lisensinya sendiri.
    • drm_key_request_properties [Array string] Header permintaan kunci yang dikemas sebagai name1, value1, name2, value2, dll. 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 sidecar subtitel.
    • subtitle_mime_type [String] Jenis MIME subtitle_uri (diperlukan jika subtitle_uri ditetapkan).
    • 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 decoder ekstensi lebih diutamakan daripada decoder platform.

Saat menggunakan adb shell am start untuk mengaktifkan intent, tambahan string 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 sampel, tetapkan tindakan intent ke androidx.media3.demo.main.action.VIEW_LIST. Tambahan konfigurasi contoh 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 contoh kedua.
  • URI sampel diteruskan sebagai tambahan dengan kunci uri_<sample-index>.

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