Sesi media berdampingan dengan pemutar yang dikelolanya. Anda harus membuat dan menginisialisasi sesi media dalam metode onCreate()
aktivitas atau layanan yang memiliki sesi media itu dan pemutar terkaitnya.
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 simpanPlaybackStateCompat.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 menginisialisasi sesi media dalam metode onCreate()
di aktivitas atau layanan yang memiliki sesi itu.
Agar tombol media berfungsi saat aplikasi Anda baru diinisialisasi (atau dihentikan), PlaybackState
-nya harus berisi tindakan putar yang cocok dengan intent yang dikirimkan oleh tombol media itu. Inilah alasan mengapa 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 saat ini dari pemutar. 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
Class MediaMetadataCompat
menjelaskan media 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 itu 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
Perhatikan bahwa PlaybackState
adalah objek yang berisi nilai terpisah untuk status pemutaran sesi (getState()
) dan, jika perlu, kode error (getErrorCode()
) yang terkait. Error dapat bersifat fatal atau tidak fatal:
Setiap kali pemutaran terganggu, sebaiknya Anda membuat kode error fatal: Tetapkan status transport ke STATE_ERROR
dan tentukan error terkait dengan setErrorMessage(int, CharSequence)
.
Selama pemutaran diblokir oleh error ini, PlaybackState
harus terus melaporkan STATE_ERROR
dan error tersebut.
Kesalahan tidak fatal terjadi saat aplikasi Anda tidak dapat menangani permintaan, tetapi dapat melanjutkan pemutaran: Transport tetap berada dalam status "normal" (misalnya STATE_PLAYING
), tetapi PlaybackState
memiliki kode error.
Misalnya, jika lagu terakhir sedang diputar dan pengguna meminta untuk melompat 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 terkait dengan sesi itu akan menerima callback onPlaybackStateChanged()
dan menjelaskan apa yang terjadi kepada pengguna. 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 dari Android 4.0 (API level 14), sistem dapat mengakses status dan metadata pemutaran sesi media. Dengan cara ini, layar kunci dapat menampilkan kontrol dan poster media. Perilaku ini bervariasi bergantung pada versi Android-nya.
Poster album
Di Android 4.0 (API level 14) dan yang lebih baru, latar belakang layar kunci menampilkan poster album - tetapi hanya jika metadata sesi media tersebut 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 baru, sistem tidak menyediakan kontrol transport di layar kunci. Sebagai gantinya, sebaiknya Anda menggunakan notifikasi MediaStyle untuk menampilkan kontrol transport.
Menambahkan tindakan kustom
Anda dapat menambahkan tindakan kustom dengan addCustomAction()
. Misalnya, untuk menambahkan kontrol guna menerapkan tindakan menyukai (jempol ke atas):
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 ini bergantung pada struktur aplikasi Anda. Lihat halaman lain yang menjelaskan cara menggunakan callback di aplikasi audio dan aplikasi video, yang menguraikan cara mengimplementasikan callback untuk setiap jenis aplikasi.