Menggunakan sesi media

Sesi media memberikan cara universal untuk berinteraksi dengan audio atau video web. Dengan memberi tahu Android bahwa media sedang diputar di aplikasi, dapat didelegasikan ke aplikasi. Integrasi dengan sesi media memungkinkan aplikasi untuk mengiklankan pemutaran media secara eksternal dan untuk menerima perintah pemutaran dari sumber eksternal. Sumber ini dapat berupa tombol fisik (seperti tombol putar, pada headset atau remote control TV) atau perintah tidak langsung (seperti memerintahkan "jeda" ke Asisten Google). Sesi media kemudian mendelegasikan perintah ini untuk aplikasi yang menerapkannya ke pemutar media transparan tempat perintah berasal.

Sesi media berdampingan dengan pemutar yang dikelolanya. Sebaiknya Anda membuat dan lakukan inisialisasi sesi media dalam metode onCreate() aktivitas atau yang memiliki sesi media dan pemutar yang terkait.

Menginisialisasi sesi media

Sesi media yang baru dibuat tidak memiliki kapabilitas. Anda harus menginisialisasi sesi itu dengan melakukan langkah-langkah berikut:

  • Menetapkan tanda agar sesi media dapat menerima callback dari pengontrol media dan tombol media.
  • Membuat dan menginisialisasi instance PlaybackStateCompat dan menetapkannya ke sesi. Status pemutaran akan berubah sepanjang sesi, jadi sebaiknya simpan PlaybackStateCompat.Builder ke dalam cache untuk digunakan kembali.
  • Membuat instance MediaSessionCompat.Callback dan menetapkannya ke sesi (baca selengkapnya tentang callback di bawah).

Anda harus membuat dan melakukan inisialisasi sesi media dalam metode onCreate() metode aktivitas atau layanan yang memiliki sesi tersebut.

Agar tombol media berfungsi saat aplikasi Anda baru diinisialisasi (atau dihentikan), PlaybackState-nya harus berisi aksi putar yang cocok dengan intent yang dikirim tombol media. Ini adalah mengapa ACTION_PLAY ditetapkan ke status sesi selama inisialisasi. Untuk informasi selengkapnya, lihat Merespons Media Tombol.

Mempertahankan status dan metadata pemutaran

Status sesi media diwakili oleh dua class.

Tujuan PlaybackStateCompat menjelaskan status operasional saat ini dari pemutar. Hal ini mencakup:

  • Status transport (apakah pemutar sedang diputar/dijeda/buffering, dll. Lihat getState())
  • Kode error dan pesan error opsional, jika berlaku. (Lihat getErrorCode() dan baca Status dan error di bawah.)
  • Posisi pemutar
  • Tindakan pengontrol yang valid yang dapat ditangani dalam status saat ini

MediaMetadataCompat menjelaskan materi yang sedang diputar:

  • Nama artis, album, dan lagu
  • Durasi lagu
  • Poster album untuk ditampilkan di layar kunci. Gambar ini adalah bitmap dengan ukuran maksimum 320x320 dp (jika lebih besar, filenya akan diperkecil).
  • Instance ContentUris yang mengarah ke versi poster yang lebih besar

Status dan metadata pemutar dapat berubah selama sesi media aktif. Setiap kali status atau metadata berubah, Anda harus menggunakan builder yang sesuai untuk setiap class, PlaybackStateCompat.Builder() atau MediaMetadataCompat.Builder(), lalu meneruskan instance baru ke sesi media dengan memanggil setPlaybackState() atau setMetaData(). Untuk mengurangi konsumsi memori secara keseluruhan dari operasi yang sering dilakukan ini, sebaiknya buat builder satu kali dan gunakan berkali-kali selama masa aktif sesi.

Status dan error

Perlu diketahui bahwa PlaybackState adalah objek yang berisi nilai terpisah untuk status pemutaran sesi (getState()) dan, jika perlu, kode error (getErrorCode()) terkait. Error dapat bersifat fatal atau non-fatal:

Setiap kali pemutaran terganggu, Anda harus memunculkan error fatal: Setel transport status ke STATE_ERROR dan menentukan error yang terkait dengan setErrorMessage(int, CharSequence). Selama pemutaran diblokir oleh error, PlaybackState akan melanjutkan untuk melaporkan STATE_ERROR beserta error-nya.

Error non-fatal terjadi saat aplikasi Anda tidak dapat menangani permintaan, tetapi dapat terus memutar: Transportasi tetap dalam mode "normal" status (seperti STATE_PLAYING), tetapi PlaybackState menyimpan kode error. Misalnya, jika lagu terakhir diputar dan pengguna meminta lewati ke lagu berikutnya, pemutaran dapat dilanjutkan, tetapi Anda harus membuat PlaybackState baru dengan kode error ERROR_CODE_END_OF_QUEUE dan lalu panggil setPlaybackState(). Pengontrol Media yang terpasang ke sesi akan menerima callback onPlaybackStateChanged() dan jelaskan kepada pengguna apa yang terjadi. Kesalahan tidak fatal sebaiknya hanya dilaporkan satu kali, yaitu pada saat terjadinya. Saat berikutnya sesi memperbarui PlaybackState, jangan tetapkan lagi error tidak fatal yang sama (kecuali jika error tersebut terjadi sebagai respons terhadap permintaan baru).

Layar kunci sesi media

Mulai Android 4.0 (API level 14), sistem bisa mengakses sesi media metadata dan status pemutaran. Berikut cara layar kunci menampilkan kontrol media dan karya seni. Perilaku ini bervariasi bergantung pada Versi Android.

Poster album

Di Android 4.0 (API level 14) hingga Android 10 (API level 29), latar belakang layar kunci akan menampilkan gambar album Anda - tetapi hanya jika sesi media metadata menyertakan bitmap latar belakang.

Kontrol transport

Di Android 4.0 hingga 4.4 (API level 14 hingga 19), jika sesi media sedang aktif dan metadata sesi media menyertakan bitmap latar belakang, layar kunci akan otomatis menampilkan kontrol transport.

Di Android 5.0 (API level 21) atau yang lebih tinggi, sistem tidak menyediakan transport pada layar kunci. Sebagai gantinya, Anda harus menggunakan MediaStyle notifikasi untuk menampilkan kontrol transport.

Menambahkan tindakan kustom

Aplikasi media dapat menentukan tindakan kustom; misalnya: suka, suka, atau mundur 30 detik. Tindakan kustom harus mengimplementasikan perilaku yang sama sekali baru. Anjuran tidak menggunakan tindakan kustom untuk menggantikan salah satu tindakan kontrol transport standar didefinisikan dalam PlaybackStateCompat.

Tambahkan tindakan kustom dengan addCustomAction(). Contoh berikut menunjukkan cara menambahkan kontrol untuk tindakan suka:

Kotlin

stateBuilder.addCustomAction(
        PlaybackStateCompat.CustomAction.Builder(
                CUSTOM_ACTION_THUMBS_UP,
                resources.getString(R.string.thumbs_up),
                thumbsUpIcon
        ).run {
            setExtras(customActionExtras)
            build()
        }
)

Java

stateBuilder.addCustomAction(new PlaybackStateCompat.CustomAction.Builder(
    CUSTOM_ACTION_THUMBS_UP, resources.getString(R.string.thumbs_up), thumbsUpIcon)
    .setExtras(customActionExtras)
    .build());

Lihat Universal Music Player untuk contoh lengkap.

Anda merespons tindakan ini dengan onCustomAction().

Kotlin

override fun onCustomAction(action: String, extras: Bundle?) {
    when(action) {
        CUSTOM_ACTION_THUMBS_UP -> {
            ...
        }
    }
}

Java

@Override
public void onCustomAction(@NonNull String action, Bundle extras) {
    if (CUSTOM_ACTION_THUMBS_UP.equals(action)) {
        ...
    }
}

Lihat juga Universal Music Player.

Callback sesi media

Metode callback sesi media utama adalah onPlay(), onPause(), dan onStop(). Di sinilah Anda menambahkan kode yang mengontrol pemutar Anda.

Karena Anda menjalankan dan menetapkan callback sesi saat runtime (dalam onCreate()), aplikasi Anda dapat menentukan callback alternatif yang menggunakan pemutar berbeda dan memilih kombinasi callback/pemutar yang sesuai, bergantung pada perangkat dan/atau level sistem. Anda dapat mengubah pemutar tanpa mengubah bagian lain dari aplikasi. Misalnya, Anda dapat menggunakan ExoPlayer saat menjalankan aplikasi di Android 4.1 (API level 16) atau yang lebih baru, dan menggunakan MediaPlayer di sistem yang lebih lama.

Selain mengontrol pemutar dan mengelola peralihan status sesi media, callback juga mengaktifkan dan menonaktifkan fitur aplikasi Anda serta mengontrol cara aplikasi berinteraksi dengan aplikasi lain dan hardware perangkat. (Lihat Mengontrol Output Audio).

Implementasi metode callback sesi media bergantung pada struktur aplikasi Anda. Lihat halaman terpisah yang menjelaskan cara menggunakan callback di aplikasi audio dan aplikasi video, menjelaskan cara mengimplementasikan callback untuk setiap jenis aplikasi.