Sesi media menyediakan cara universal untuk berinteraksi dengan pemutar audio atau video. Dengan memberi tahu Android bahwa media sedang diputar di aplikasi, kontrol pemutaran dapat didelegasikan ke aplikasi. Integrasi dengan sesi media memungkinkan aplikasi memberitahukan pemutaran media secara eksternal dan menerima perintah pemutaran dari sumber eksternal. Sumber ini dapat berupa tombol fisik (seperti tombol putar di headset atau remote TV) atau perintah tidak langsung (seperti menginstruksikan "jeda" ke Asisten Google). Sesi media kemudian mendelegasikan perintah ini ke aplikasi yang menerapkannya ke pemutar media yang transparan, tempat perintah berasal.
Sesi media berdampingan dengan pemutar yang dikelolanya. Anda harus membuat
dan melakukan inisialisasi sesi media dalam metode onCreate() aktivitas atau
layanan yang memiliki sesi media dan pemutar terkait.
Menginisialisasi sesi media
Sesi media yang baru dibuat tidak memiliki kapabilitas. Anda harus melakukan inisialisasi sesi dengan melakukan langkah-langkah berikut:
- Setel flag agar sesi media dapat menerima callback dari pengontrol media dan tombol media.
- Buat dan lakukan inisialisasi instance
PlaybackStateCompat, lalu tetapkan ke sesi. Status pemutaran berubah selama sesi, jadi sebaiknya simpanPlaybackStateCompat.Builderdalam cache untuk digunakan kembali. - Buat instance
MediaSessionCompat.Callbackdan tetapkan ke sesi (selengkapnya tentang callback di bawah).
Anda harus membuat dan melakukan inisialisasi sesi media dalam metode onCreate() dari
aktivitas atau layanan yang memiliki sesi tersebut.
Agar tombol media berfungsi saat aplikasi Anda baru diinisialisasi (atau
dihentikan), PlaybackState-nya harus berisi tindakan putar yang cocok dengan intent
yang dikirim tombol media. Inilah alasan ACTION_PLAY ditetapkan ke status sesi selama inisialisasi. Untuk informasi selengkapnya, lihat Merespons
Tombol Media.
Mempertahankan status dan metadata pemutaran
Status sesi media diwakili oleh dua class.
Class PlaybackStateCompat menjelaskan status operasional pemutar
saat ini. Hal ini mencakup:
- Status transport (apakah pemutar sedang memutar/dijeda/melakukan 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
Class MediaMetadataCompat menjelaskan materi yang sedang diputar:
- Nama artis, album, dan lagu
- Durasi lagu
- Poster album untuk ditampilkan di layar kunci. Gambar adalah bitmap dengan ukuran maksimum 320x320 dp (jika lebih besar, ukurannya akan diperkecil).
- Instance
ContentUrisyang 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 sekali dan gunakan kembali selama sesi berlangsung.
Status dan error
Perhatikan bahwa PlaybackState adalah objek yang berisi nilai terpisah untuk
status pemutaran sesi (getState()) dan, jika perlu,
kode error terkait (getErrorCode()). Error dapat bersifat fatal atau
tidak fatal:
Setiap kali pemutaran terganggu, Anda harus membuat error fatal: Setel
status transpor ke STATE_ERROR dan tentukan error terkait dengan
setErrorMessage(int, CharSequence). Selama pemutaran diblokir oleh
error, PlaybackState harus terus melaporkan STATE_ERROR dan
error.
Error non-fatal terjadi saat aplikasi Anda tidak dapat menangani permintaan, tetapi dapat terus
memutar: Transportasi tetap dalam status "normal" (seperti STATE_PLAYING), tetapi
PlaybackState menyimpan kode error. Misalnya, jika lagu terakhir
sedang diputar dan pengguna meminta untuk melewati ke lagu berikutnya, pemutaran dapat dilanjutkan, tetapi
Anda harus membuat PlaybackState baru dengan kode error
ERROR_CODE_END_OF_QUEUE, lalu memanggil setPlaybackState(). Pengontrol Media
yang terpasang ke sesi akan menerima callback
onPlaybackStateChanged() dan menjelaskan kepada pengguna apa yang terjadi. Error
nonfatal hanya boleh dilaporkan sekali, pada saat error tersebut terjadi. Saat berikutnya sesi memperbarui PlaybackState, jangan tetapkan error tidak fatal yang sama lagi (kecuali jika error terjadi sebagai respons terhadap permintaan baru).
Layar kunci sesi media
Mulai Android 4.0 (level API 14), sistem dapat mengakses status pemutaran dan metadata sesi media. Berikut adalah cara layar kunci dapat menampilkan kontrol media dan poster album. Perilaku ini bervariasi bergantung pada versi Android.
Poster album
Di Android 4.0 (level API 14) hingga Android 10 (level API 29), latar belakang layar kunci menampilkan gambar album Anda, tetapi hanya jika metadata sesi media menyertakan bitmap latar belakang.
Kontrol transport
Di Android 4.0 (API level 14) hingga Android 4.4 (API level 19), saat sesi media aktif dan metadata sesi media menyertakan bitmap latar belakang, layar kunci akan otomatis menampilkan kontrol transpor.
Di Android 5.0 (level API 21) atau yang lebih tinggi, sistem tidak menyediakan kontrol transportasi di layar kunci. Sebagai gantinya, Anda harus menggunakan notifikasi MediaStyle untuk menampilkan kontrol transpor.
Menambahkan tindakan kustom
Aplikasi media dapat menentukan tindakan kustom; misalnya: suka, suka, atau putar ulang 30 detik. Tindakan kustom harus menerapkan perilaku yang benar-benar baru. Jangan gunakan tindakan kustom untuk mengganti salah satu tindakan kontrol transpor standar yang ditentukan 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 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 membuat instance dan menetapkan callback sesi saat runtime (di
onCreate()), aplikasi Anda dapat menentukan callback alternatif yang menggunakan pemutar
berbeda dan memilih kombinasi callback dan pemutar yang sesuai, bergantung
pada perangkat dan level sistem. Anda dapat mengubah pemutar tanpa mengubah bagian aplikasi lainnya. Misalnya, Anda dapat menggunakan ExoPlayer saat berjalan di Android 4.1 (level API 16) atau yang lebih tinggi dan menggunakan MediaPlayer pada sistem sebelumnya.
Selain mengontrol pemutar dan mengelola transisi 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, yang menjelaskan cara callback harus diimplementasikan untuk setiap jenis aplikasi.