Menambahkan kontrol pemutaran ke aplikasi

Aplikasi yang memutar media memerlukan komponen antarmuka pengguna untuk menampilkan media dan mengontrol pemutaran. Library Media3 menyertakan modul UI yang berisi sejumlah komponen UI. Untuk bergantung pada modul UI, tambahkan dependensi berikut:

Kotlin

implementation("androidx.media3:media3-ui:1.3.1")

Groovy

implementation "androidx.media3:media3-ui:1.3.1"

Komponen terpenting adalah PlayerView, tampilan untuk pemutaran media. PlayerView menampilkan video, subtitel, dan sampul album selama pemutaran, serta kontrol pemutaran.

PlayerView memiliki metode setPlayer untuk melampirkan dan melepaskan (dengan meneruskan null) instance pemain.

TampilanPemutar

PlayerView dapat digunakan untuk pemutaran video dan audio. Library ini merender video dan subtitel saat video diputar, dan dapat menampilkan karya seni yang disertakan sebagai metadata dalam file audio. Anda dapat menyertakannya dalam file tata letak seperti komponen UI lainnya. Misalnya, PlayerView dapat disertakan dengan XML berikut:

<androidx.media3.ui.PlayerView
    android:id="@+id/player_view"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    app:show_buffering="when_playing"
    app:show_shuffle_button="true"/>

Cuplikan di atas mengilustrasikan bahwa PlayerView menyediakan beberapa atribut. Atribut ini dapat digunakan untuk menyesuaikan perilaku tampilan, serta tampilan dan nuansanya. Sebagian besar atribut ini memiliki metode penyetel terkait, yang dapat digunakan untuk menyesuaikan tampilan pada runtime. PlayerView Javadoc mencantumkan atribut dan metode penyetel ini secara lebih mendetail.

Setelah tampilan dideklarasikan dalam file tata letak, tampilan tersebut dapat dicari dalam metode onCreate aktivitas:

Kotlin

override fun onCreate(savedInstanceState: Bundle?) {
  super.onCreate(savedInstanceState)
  // ...
  playerView = findViewById(R.id.player_view)
}

Java

@Override
protected void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
  // ...
  playerView = findViewById(R.id.player_view);
}

Setelah pemutar diinisialisasi, pemutar tersebut dapat dilampirkan ke tampilan dengan memanggil setPlayer:

Kotlin

// Instantiate the player.
val player = ExoPlayer.Builder(context).build()
// Attach player to the view.
playerView.player = player
// Set the media item to be played.
player.setMediaItem(mediaItem)
// Prepare the player.
player.prepare()

Java

// Instantiate the player.
player = new ExoPlayer.Builder(context).build();
// Attach player to the view.
playerView.setPlayer(player);
// Set the media item to be played.
player.setMediaItem(mediaItem);
// Prepare the player.
player.prepare();

Pilih jenis permukaan

Atribut surface_type dari PlayerView memungkinkan Anda menyetel jenis platform yang digunakan untuk pemutaran video. Selain nilai spherical_gl_surface_view (yang merupakan nilai khusus untuk pemutaran video sferikal) dan video_decoder_gl_surface_view (yang untuk rendering video menggunakan perender ekstensi), nilai yang diizinkan adalah surface_view, texture_view, dan none. Jika tampilan hanya untuk pemutaran audio, none harus digunakan untuk menghindari keharusan membuat platform karena hal ini dapat dikenai biaya.

Jika tampilan tersebut untuk pemutaran video reguler, surface_view atau texture_view harus digunakan. SurfaceView memiliki sejumlah manfaat dibandingkan TextureView untuk pemutaran video:

• Mengurangi konsumsi daya secara signifikan di banyak perangkat.
• Pengaturan waktu render frame yang lebih akurat, sehingga menghasilkan pemutaran video yang lebih lancar.
• Dukungan untuk output video HDR berkualitas lebih tinggi pada perangkat yang kompatibel.
• Dukungan untuk output yang aman saat memutar konten yang dilindungi DRM.
• Kemampuan untuk merender konten video pada resolusi penuh tampilan di perangkat Android TV yang meningkatkan kualitas lapisan UI.

Oleh karena itu, SurfaceView harus lebih diprioritaskan daripada TextureView jika memungkinkan. TextureView hanya boleh digunakan jika SurfaceView tidak memenuhi kebutuhan Anda. Salah satu contohnya adalah saat animasi yang lancar atau scroll platform video diperlukan sebelum Android 7.0 (API level 24), seperti yang dijelaskan dalam catatan berikut. Untuk hal ini, sebaiknya gunakan TextureView hanya saat SDK_INT kurang dari 24 (Android 7.0) dan SurfaceView jika tidak.

Catatan: Rendering SurfaceView tidak disinkronkan dengan benar dengan animasi tampilan hingga Android 7.0 (API level 24). Pada rilis sebelumnya, hal ini dapat mengakibatkan efek yang tidak diinginkan saat SurfaceView ditempatkan ke penampung scroll, atau saat menggunakan animasi. Efek tersebut mencakup konten tampilan yang tampak sedikit terlambat di belakang tempatnya ditampilkan, dan tampilan berubah menjadi hitam saat terpengaruh animasi. Untuk mendapatkan animasi atau scroll video yang lancar sebelum Android 7.0, Anda harus menggunakan TextureView, bukan SurfaceView.

Catatan: Siklus proses platform SurfaceView terikat dengan visibilitas tampilan, sedangkan siklus proses platform TextureView terikat dengan lampiran dan pelepasan jendela. Oleh karena itu, dalam UI scroll yang menggunakan SurfaceView, memulai pemutaran dapat memerlukan waktu lebih lama karena platform output tersedia sedikit nanti. Mulai Android 14 dan seterusnya, PlayerView menggunakan SurfaceView.setSurfaceLifecycle(SURFACE_LIFECYCLE_FOLLOWS_ATTACHMENT) untuk menghindari perilaku ini. Jika aplikasi Anda menggunakan SurfaceView secara langsung (tanpa PlayerView), Anda mungkin perlu mengaktifkan mode ini. Sebelum Android 14, Anda dapat mengatasi permukaan yang dihancurkan dengan menerjemahkan tampilan di luar layar saat mendaur ulangnya.

Catatan: Beberapa perangkat Android TV menjalankan lapisan UI-nya pada resolusi yang lebih rendah dari resolusi penuh layar, sehingga meningkatkannya untuk ditampilkan kepada pengguna. Misalnya, lapisan UI dapat dijalankan pada resolusi 1080p di Android TV yang memiliki layar 4K. Pada perangkat tersebut, SurfaceView harus digunakan untuk merender konten pada resolusi tampilan penuh. Resolusi penuh tampilan (dalam mode tampilan saat ini) dapat dikueri menggunakan Util.getCurrentDisplayModeSize. Resolusi lapisan UI dapat dikueri menggunakan Display.getSize API Android.

Navigasi D-pad di Android TV

Remote control Android TV memiliki kontrol D-pad yang mengirimkan perintah yang masuk sebagai peristiwa tombol di dispatchKeyEvent(KeyEvent) dari Activity Anda. Bagian ini harus didelegasikan ke tampilan pemain:

Kotlin

override fun dispatchKeyEvent(event: KeyEvent?): Boolean{
  return playerView.dispatchKeyEvent(event!!) || super.dispatchKeyEvent(event)
}

Java

@Override
public boolean dispatchKeyEvent(KeyEvent event) {
  return playerView.dispatchKeyEvent(event) || super.dispatchKeyEvent(event);
}

Meminta fokus untuk tampilan pemutar penting untuk menavigasi kontrol pemutaran dan melewati iklan. Sebaiknya minta fokus dalam onCreate dari Activity:

Kotlin

override fun onCreate(savedInstanceState: Bundle?) {
  super.onCreate(savedInstanceState)
  // ...
  playerView.requestFocus()
  // ...
}

Java

@Override
public void onCreate(@Nullable Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    // ...
    playerView.requestFocus();
    // ...
}

Jika menggunakan Compose di Android TV, Anda harus membuat AndroidView dapat difokuskan dan mendelegasikan peristiwa dengan meneruskan parameter pengubah ke AndroidView sebagaimana mestinya:

AndroidView(
  modifier = modifier
    .focusable()
    .onKeyEvent { playerView.dispatchKeyEvent(it.nativeKeyEvent) },
  factory = { playerView }
)

Mengganti drawable

Perhatian: Kami tidak menjamin bahwa penyesuaian yang dijelaskan di bagian berikut akan terus berfungsi di versi library mendatang. ID resource dapat mengubah nama, atau beberapa mungkin dihapus sepenuhnya. Hal ini ditunjukkan dengan ID resource yang ditandai sebagai 'pribadi'.

PlayerView menggunakan PlayerControlView untuk menampilkan kontrol pemutaran dan status progres. Drawable yang digunakan oleh PlayerControlView dapat diganti oleh drawable dengan nama yang sama yang ditetapkan dalam aplikasi Anda. Lihat Javadoc PlayerControlView untuk mengetahui daftar drawable kontrol yang dapat diganti.

Penyesuaian lebih lanjut

Jika penyesuaian di luar yang dijelaskan di atas diperlukan, kami berharap developer aplikasi akan mengimplementasikan komponen UI mereka sendiri, bukan menggunakan komponen UI yang disediakan oleh modul UI Media3.