Antarmuka Pemutar

Pemutar adalah komponen aplikasi yang memfasilitasi pemutaran item media. Antarmuka Player Media3 menyiapkan garis batas untuk fungsi yang umumnya ditangani oleh pemutar. Hal ini mencakup:

• Memengaruhi kontrol pemutaran, seperti memutar, menjeda, dan mencari
• Membuat kueri properti media yang sedang diputar, seperti posisi pemutaran
• Mengelola playlist/antrean item media
• Mengonfigurasi properti pemutaran, seperti mengacak, mengulangi, kecepatan, dan volume
• Melakukan rendering video ke layar

Media3 juga menyediakan implementasi antarmuka Player, yang disebut ExoPlayer.

Tips: Jika Anda ingin mengimplementasikan aplikasi pemutar media menggunakan ExoPlayer, lihat panduan Membuat aplikasi pemutar media dasar menggunakan Media3 ExoPlayer.

Antarmuka umum antar komponen

Beberapa komponen di Media3 mengimplementasikan antarmuka Pemutar, misalnya:

Component	Deskripsi & catatan perilaku
ExoPlayer	API pemutar media, dan implementasi default antarmuka Player.
MediaController	Berinteraksi dengan MediaSession untuk mengirim perintah pemutaran. Jika Player dan MediaSession berada di Service yang terpisah dari Activity atau Fragment tempat UI pemain berada, Anda dapat menetapkan MediaController sebagai pemutar untuk UI PlayerView. Panggilan metode pemutaran dan playlist dikirim ke Player melalui MediaSession Anda.
MediaBrowser	Selain fungsi yang ditawarkan oleh MediaController, berinteraksi dengan MediaLibrarySession untuk menjelajahi konten media yang tersedia.
ForwardingPlayer	Implementasi Player yang meneruskan panggilan metode ke Player lain. Gunakan class ini untuk menyembunyikan atau memodifikasi operasi tertentu dengan mengganti metodenya.
SimpleBasePlayer	Implementasi Player yang mengurangi jumlah metode yang diimplementasikan seminimal mungkin. Berguna saat menggunakan pemutar kustom yang ingin Anda hubungkan ke MediaSession.
CastPlayer	Implementasi Player yang berkomunikasi dengan aplikasi penerima Cast. Perilaku bergantung pada sesi Cast yang mendasarinya.

Meskipun tidak mengimplementasikan antarmuka Player, MediaSession memerlukan Player saat membuatnya. Tujuannya adalah untuk memberikan akses ke Player dari proses atau thread lain.

Arsitektur pemutaran Media3

Jika memiliki akses ke Player, Anda harus memanggil metodenya secara langsung untuk memberikan perintah pemutaran. Anda dapat mengiklankan pemutaran dan memberikan kontrol pemutaran sumber eksternal dengan menerapkan MediaSession. Sumber eksternal ini mengimplementasikan MediaController, yang memfasilitasi koneksi ke sesi media dan mengeluarkan permintaan perintah pemutaran.

Saat memutar media di latar belakang, Anda harus menyimpan sesi media dan pemutar dalam MediaSessionService atau MediaLibraryService yang berjalan sebagai layanan latar depan. Jika demikian, Anda dapat memisahkan pemutar dari Aktivitas di aplikasi yang berisi UI untuk kontrol pemutaran. Hal ini mungkin mengharuskan Anda menggunakan pengontrol media.

Gambar 1: Antarmuka Player memainkan peran penting dalam arsitektur Media3.

Status pemutar

Status pemutar media yang mengimplementasikan antarmuka Player pada utamanya terdiri dari 4 kategori informasi:

1. Status pemutaran
   • Diambil dengan getPlaybackState().
   • Nilai status yang ditentukan oleh antarmuka adalah STATE_IDLE, STATE_BUFFERING, STATE_READY, dan STATE_ENDED.
2. Playlist item media
   • Urutan instance MediaItem untuk pemutaran.
   • Diambil dengan getCurrentTimeline()
   • Instance Player dapat menyediakan metode operasi playlist seperti menambahkan atau menghapus MediaItem dan metode praktis seperti getCurrentMediaItem().
3. Properti putar/jeda, seperti:
   • playWhenReady: Indikasi apakah pengguna ingin media diputar jika memungkinkan atau tetap dijeda
   • Alasan penghentian pemutaran: Indikasi alasan pemutaran dihentikan, jika berlaku, meskipun playWhenReady adalah true
   • isPlaying: Indikasi apakah pemutar sedang diputar atau tidak, yang hanya akan berupa true jika status pemutaran adalah STATE_READY, playWhenReady adalah true, dan pemutaran tidak dihentikan
4. Posisi pemutaran, termasuk:
   • Indeks item media saat ini: Indeks MediaItem saat ini dalam playlist.
   • isPlayingAd: Indikasi apakah iklan yang disisipkan sedang diputar.
   • Posisi pemutaran saat ini: Posisi pemutaran saat ini dalam MediaItem saat ini atau iklan yang disisipkan.

Selain itu, antarmuka Player memungkinkan akses ke trek yang tersedia, metadata media, kecepatan pemutaran, volume, dan properti tambahan pemutaran lainnya.

Catatan: Instance Player tidak harus mendukung semua fitur antarmuka. Anda dapat memeriksa perintah yang tersedia untuk melihat fitur mana yang didukung dan metode mana yang diizinkan untuk dipanggil.

Memproses perubahan

Gunakan Player.Listener untuk memproses perubahan di Player. Lihat dokumentasi ExoPlayer tentang Peristiwa pemain untuk mengetahui detail cara membuat dan menggunakan pemroses.

Perhatikan bahwa antarmuka pemroses tidak menyertakan callback untuk melacak progres pemutaran normal. Untuk terus memantau progres pemutaran, seperti untuk menyiapkan UI status progres, Anda harus mengkueri posisi saat ini pada interval yang tepat.

Kotlin

val handler = Handler(Looper.getMainLooper())
fun checkPlaybackPosition(delayMs: Long): Boolean =
  handler.postDelayed(
    {
      val currentPosition = player.currentPosition
      // Update UI based on currentPosition
      checkPlaybackPosition(delayMs)
    },
    delayMs)

Java

Handler handler = new Handler(Looper.getMainLooper());
boolean checkPlaybackPosition(long delayMs) {
    return handler.postDelayed(() -> {
        long currentPosition = player.getCurrentPosition();
        // Update UI based on currentPosition
        checkPlaybackPosition(delayMs);
    }, delayMs);
}

Mengontrol pemutaran

Antarmuka Player menawarkan banyak cara untuk memanipulasi status dan mengontrol pemutaran:

• Kontrol pemutaran dasar seperti play(), pause(), prepare(), dan stop().
• Operasi playlist seperti addMediaItem() atau removeMediaItem().
• Berusaha untuk mengubah item atau posisi saat ini.
• Tetapkan mode pengulangan dan mode acak.
• Perbarui preferensi pemilihan trek.
• Setel kecepatan pemutaran.

Catatan: Instance Player tidak harus mendukung semua fitur antarmuka. Anda dapat memeriksa perintah yang tersedia untuk melihat fitur mana yang didukung dan metode mana yang diizinkan untuk dipanggil.

Implementasi Player kustom

Untuk membuat pemutar kustom, Anda dapat memperluas SimpleBasePlayer yang disertakan di Media3. Class ini menyediakan implementasi dasar antarmuka Player untuk mengurangi jumlah metode yang perlu Anda implementasikan seminimal mungkin.

Mulai dengan mengganti metode getState(). Metode ini harus mengisi status pemutar saat ini saat dipanggil, termasuk:

• Serangkaian perintah yang tersedia
• Properti pemutaran, seperti apakah pemutar harus mulai diputar saat status pemutaran adalah STATE_READY, indeks item media yang sedang diputar, dan posisi pemutaran dalam item saat ini

Kotlin

class CustomPlayer : SimpleBasePlayer(looper) {
  override fun getState(): State {
    return State.Builder()
      .setAvailableCommands(...) // Set which playback commands the player can handle
      // Configure additional playback properties
      .setPlayWhenReady(true, PLAY_WHEN_READY_CHANGE_REASON_USER_REQUEST)
      .setCurrentMediaItemIndex(0)
      .setContentPositionMs(0)
      .build()
  }
}

Java

public class CustomPlayer extends SimpleBasePlayer {
  public CustomPlayer(Looper looper) {
    super(looper);
  }

  @Override
  protected State getState() {
    return new State.Builder()
      .setAvailableCommands(...) // Set which playback commands the player can handle
      // Configure additional playback properties
      .setPlayWhenReady(true, PLAY_WHEN_READY_CHANGE_REASON_USER_REQUEST)
      .setCurrentMediaItemIndex(0)
      .setContentPositionMs(0)
      .build();
  }
}

SimpleBasePlayer akan menerapkan bahwa State dibuat dengan kombinasi nilai status yang valid. API ini juga akan menangani pemroses dan memberi tahu pemroses tentang perubahan status. Jika Anda perlu memicu pembaruan status secara manual, panggil invalidateState().

Selain metode getState(), Anda hanya perlu mengimplementasikan metode yang digunakan untuk perintah yang dinyatakan tersedia oleh pemain. Temukan metode pengendali yang dapat diganti dan sesuai dengan fungsi yang ingin Anda implementasikan. Misalnya, ganti metode handleSeek() untuk mendukung operasi seperti COMMAND_SEEK_IN_CURRENT_MEDIA_ITEM dan COMMAND_SEEK_TO_NEXT_MEDIA_ITEM.