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.4.1")

Groovy

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

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

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

Tampilan Pemutar

PlayerView dapat digunakan untuk pemutaran video, gambar, dan audio. Library ini merender video dan subtitel dalam kasus pemutaran video, bitmap untuk pemutaran gambar, 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 yang sesuai, yang dapat digunakan untuk menyesuaikan tampilan saat runtime. Javadoc PlayerView mencantumkan atribut dan metode penyetel ini secara lebih mendetail.

Setelah 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 diinisialisasi, pemutar 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();

Memilih jenis platform

Atribut surface_type dari PlayerView memungkinkan Anda menetapkan jenis platform yang digunakan untuk pemutaran video. Selain nilai spherical_gl_surface_view (yang adalah nilai khusus untuk pemutaran video sferis) dan video_decoder_gl_surface_view (yang digunakan 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 agar tidak perlu membuat platform karena melakukannya dapat mahal.

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

• Secara signifikan menurunkan konsumsi daya di banyak perangkat.
• Pengaturan waktu frame yang lebih akurat, sehingga menghasilkan pemutaran video yang lebih lancar.
• Dukungan untuk output video HDR berkualitas lebih tinggi di perangkat yang kompatibel.
• Dukungan untuk output yang aman saat memutar konten yang dilindungi DRM.
• Kemampuan untuk merender konten video pada resolusi penuh layar 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 halus atau scroll platform video diperlukan sebelum Android 7.0 (API level 24), seperti dijelaskan dalam catatan berikut. Untuk kasus ini, sebaiknya gunakan TextureView hanya jika 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 menyebabkan efek yang tidak diinginkan saat SurfaceView ditempatkan ke dalam penampung scroll, atau saat dikenai animasi. Efek tersebut mencakup konten tampilan yang tampak sedikit tertunda dari tempat seharusnya ditampilkan, dan tampilan berubah menjadi hitam saat disertai 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 kemudian. 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), sebaiknya aktifkan 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, yang meningkatkan skalanya untuk presentasi 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 penuh layar. Resolusi penuh layar (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 mengirim perintah yang datang sebagai peristiwa tombol di dispatchKeyEvent(KeyEvent) dari Activity Anda. Hal ini perlu didelegasikan ke tampilan pemutar:

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. Pertimbangkan untuk meminta fokus di 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:

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 pada versi library mendatang. ID resource dapat mengubah nama, atau beberapa dapat dihapus sepenuhnya. Hal ini ditunjukkan oleh ID resource yang ditandai 'pribadi'.

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

Penyesuaian lebih lanjut

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