Menambahkan kontrol pemutaran ke aplikasi

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

Kotlin

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

Groovy

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

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

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

Tampilan Pemutar

PlayerView dapat digunakan untuk pemutaran video, gambar, dan audio. Dirender video dan subtitel untuk pemutaran video, bitmap untuk pemutaran gambar dan dapat menampilkan poster yang disertakan sebagai metadata dalam file audio. Anda dapat menyertakannya dalam file tata letak Anda 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 ini dapat digunakan untuk menyesuaikan perilaku tampilan, seperti serta tampilan dan nuansanya. Sebagian besar atribut ini memiliki penyetel terkait , yang dapat digunakan untuk menyesuaikan tampilan saat runtime. Tujuan PlayerView Javadoc mencantumkan atribut dan metode penyetel ini di secara lebih mendetail.

Setelah tampilan dideklarasikan dalam file tata letak, tampilan tersebut dapat dicari di 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 telah diinisialisasi, pemutar dapat dipasang 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 menyetel jenis platform yang digunakan untuk pemutaran video. Selain nilai spherical_gl_surface_view (yang adalah nilai khusus untuk pemutaran video bundar) dan video_decoder_gl_surface_view (untuk rendering video menggunakan ekstensi perender), nilai yang diizinkan adalah surface_view, texture_view, dan none. Jika tampilan ini hanya untuk pemutaran audio, none harus digunakan agar tidak perlu membuat platform karena memerlukan banyak biaya.

Jika penayangan tersebut adalah untuk pemutaran video reguler, berarti surface_view atau texture_view sebaiknya digunakan. SurfaceView memiliki sejumlah manfaat dibandingkan TextureView untuk pemutaran video:

• Secara signifikan menurunkan daya konsumsi konten 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 dari tampilan 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. paket Premium AI misalnya saat animasi yang halus atau scroll permukaan video diperlukan sebelum Android 7.0 (level API 24), seperti dijelaskan dalam catatan berikut. Sebagai dalam hal ini, sebaiknya gunakan TextureView hanya jika SDK_INT lebih jarang dari versi 24 (Android 7.0) dan SurfaceView.

Catatan: Rendering SurfaceView tidak disinkronkan dengan benar dengan animasi tampilan hingga Android 7.0 (level API 24). Pada rilis sebelumnya, hal ini bisa mengakibatkan efek yang tidak diinginkan saat SurfaceView ditempatkan ke dalam penampung scroll, atau saat tunduk animasi. Efek tersebut meliputi konten tampilan yang tampak sedikit tersendat di belakang tempat seharusnya ditampilkan, dan tampilan menjadi hitam saat subjek ditampilkan ke animasi. Untuk mencapai animasi yang mulus atau pengguliran 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 jendela dan pelepasan. Oleh karena itu, dalam men-scroll UI yang menggunakan SurfaceView, mulai pemutaran dapat memakan waktu lebih lama karena platform output menjadi sedikit tersedia nanti. Mulai Android 14 dan seterusnya, PlayerView menggunakan SurfaceView.setSurfaceLifecycle(SURFACE_LIFECYCLE_FOLLOWS_ATTACHMENT) ke menghindari perilaku ini. Jika aplikasi Anda menggunakan SurfaceView secara langsung (tanpa PlayerView), sebaiknya aktifkan mode ini. Sebelum Android 14, mungkin untuk mengatasi permukaan yang dihancurkan dengan menerjemahkan tampilan luar layar saat mendaur ulangnya.

Catatan: Beberapa perangkat Android TV menjalankan lapisan UI-nya pada resolusi yang lebih rendah daripada resolusi penuh layar, meningkatkannya untuk presentasi kepada pengguna. Sebagai misalnya, lapisan UI dapat dijalankan pada resolusi 1080p di Android TV yang memiliki resolusi 4K tampilan. 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 mengirimkan perintah yang tiba sebagai peristiwa utama pada dispatchKeyEvent(KeyEvent) dari Activity Anda. 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 pemutaran mengontrol iklan dan melewatkan iklan. Sebaiknya minta fokus di onCreate 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 dalam AndroidView sesuai dengan:

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 akan dihapus sepenuhnya. Hal ini ditunjukkan oleh ID resource yang ditandai 'pribadi'.

PlayerView menggunakan PlayerControlView untuk menampilkan pemutaran kontrol 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 daftar drawable kontrol yang dapat diganti.

Penyesuaian lebih lanjut

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