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, yang merupakan tampilan untuk pemutaran media. PlayerView menampilkan video, subtitel, dan gambar album selama pemutaran, serta kontrol pemutaran.

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

Tampilan Pemutar

PlayerView dapat digunakan untuk pemutaran video dan audio. Library ini merender video dan subtitel untuk pemutaran video, dan dapat menampilkan poster 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 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();

Pilih jenis platform

Atribut surface_type dari PlayerView memungkinkan Anda menetapkan jenis platform yang digunakan untuk pemutaran video. Selain nilai spherical_gl_surface_view (yang merupakan nilai khusus untuk pemutaran video sferis) dan video_decoder_gl_surface_view (yang ditujukan untuk rendering video menggunakan perender ekstensi), nilai yang diizinkan adalah surface_view, texture_view, dan none. Jika tampilan hanya ditujukan untuk pemutaran audio, none harus digunakan agar tidak perlu membuat platform karena akan mahal.

Jika penayangan tersebut adalah 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.
• Waktu render frame yang lebih akurat sehingga pemutaran video lebih lancar.
• Dukungan untuk output video HDR berkualitas lebih tinggi pada perangkat yang mendukung.
• 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 sebaiknya hanya 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 hal 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 (level API 24). Pada rilis sebelumnya, hal ini dapat mengakibatkan efek yang tidak diinginkan saat SurfaceView ditempatkan ke dalam penampung scroll, atau saat diubah menjadi animasi. Efek tersebut mencakup konten tampilan yang tampak sedikit terlambat di belakang tempat seharusnya ditampilkan, dan tampilan menjadi hitam saat dikenai animasi. Untuk mencapai animasi yang lancar atau scroll video sebelum Android 7.0, oleh karena itu 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 menjadi 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 pada resolusi yang lebih rendah dari resolusi penuh layar, sehingga 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 layar 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 pada dispatchKeyEvent(KeyEvent) dari Activity Anda. Video 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. Sebaiknya minta 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 berubah nama, atau beberapa mungkin dihapus sepenuhnya. Hal ini ditunjukkan dengan ID resource yang ditandai '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 penjelasan di atas diperlukan, kami berharap developer aplikasi akan mengimplementasikan komponen UI-nya sendiri, bukan menggunakan komponen yang disediakan oleh modul UI Media3.