Mengaktifkan kontrol pemutaran

Untuk mengaktifkan pemutaran media di Android Auto dan Android Automotive OS (AAOS), terapkan kontrol pemutaran dengan mendaftarkan sesi media dan menangani metode callback-nya. Laman ini menjelaskan cara:

• Daftarkan objek MediaSessionCompat di layanan browser media Anda.

• Terapkan metode MediaSessionCompat.Callback untuk merespons permintaan pemutaran pengguna.

• Mengonfigurasi tindakan pemutaran standar dan kustom.

• Tetapkan status pemutaran awal untuk sesi media Anda.

• Tambahkan ikon untuk menunjukkan format audio.

• Membuat link dari item media yang sedang diputar.

Android Auto dan AAOS mengirimkan perintah kontrol pemutaran melalui MediaSessionCompat untuk layanan Anda. Anda harus mendaftarkan sesi dan menerapkan metode callback yang terkait.

Mendaftarkan sesi media

Dalam metode onCreate layanan browser media Anda, buat instance MediaSessionCompat, lalu panggil setSessionToken untuk mendaftarkan sesi media. Cuplikan kode ini menunjukkan cara membuat dan mendaftarkan sesi media:

override fun onCreate() {
    super.onCreate()
    ...
    // Start a new MediaSession.
    val session = MediaSessionCompat(this, "session tag").apply {
        // Set a callback object that implements MediaSession.Callback
        // to handle play control requests.
        setCallback(MyMediaSessionCallback())
    }
    sessionToken = session.sessionToken
    ...
}

public void onCreate() {
    super.onCreate();
    ...
    // Start a new MediaSession.
    MediaSessionCompat session = new MediaSessionCompat(this, "session tag");
    setSessionToken(session.getSessionToken());

    // Set a callback object that implements MediaSession.Callback
    // to handle play control requests.
    session.setCallback(new MyMediaSessionCallback());
    ...
}

Saat Anda membuat objek sesi media, tetapkan objek callback yang digunakan untuk menangani permintaan kontrol pemutaran. Objek ini dibuat dengan memberikan implementasi class MediaSessionCompat.Callback untuk aplikasi Anda. Bagian selanjutnya membahas cara mengimplementasikan objek ini.

Mengimplementasikan perintah putar

Saat pengguna meminta pemutaran untuk item media dari aplikasi Anda, Android Automotive OS dan Android Auto menggunakan class MediaSessionCompat.Callback dari objek MediaSessionCompat aplikasi Anda yang diperoleh dari layanan browser media aplikasi Anda. Saat pengguna ingin mengontrol pemutaran konten, seperti menjeda pemutaran atau melewati ke lagu berikutnya, Android Auto dan Android Automotive OS akan memanggil salah satu metode objek callback.

Untuk menangani pemutaran konten, aplikasi Anda harus memperluas class MediaSessionCompat.Callback abstrak dan mengimplementasikan metode yang didukung aplikasi Anda.

Implementasikan setiap metode callback berikut yang sesuai untuk jenis konten yang ditawarkan oleh aplikasi Anda:

onPrepare

AAOS memanggil metode ini saat sumber media berubah.

onPlay

Dipanggil saat pengguna memilih putar tanpa memilih item tertentu. Aplikasi Anda harus memutar konten defaultnya atau, jika pemutaran dijeda dengan onPause, aplikasi Anda akan melanjutkan pemutaran.

onPlayFromMediaId

Dipanggil saat pengguna memilih untuk memutar item tertentu. Metode ini menerima ID yang ditetapkan layanan browser media Anda ke item media dalam hierarki konten.

onPlayFromSearch

Dipanggil saat pengguna memilih untuk memutar item media dari kueri penelusuran. Aplikasi harus membuat pilihan yang tepat berdasarkan string penelusuran yang diteruskan.

onPause

Dipanggil saat pengguna memilih untuk menjeda pemutaran.

onSkipToNext

Dipanggil saat pengguna memilih untuk melompat ke item berikutnya.

onSkipToPrevious

Dipanggil saat pengguna memilih untuk melompat ke item sebelumnya.

onStop

Dipanggil saat pengguna memilih untuk menghentikan pemutaran. Ganti metode ini di aplikasi Anda untuk memberikan hasil yang dipilih. Anda tidak perlu mengimplementasikan metode jika tujuannya tidak didukung oleh aplikasi Anda. Misalnya, jika aplikasi Anda memutar livestream, seperti siaran olahraga, Anda tidak perlu mengimplementasikan onSkipToNext. Sebagai gantinya, gunakan implementasi default onSkipToNext.

Aplikasi Anda tidak memerlukan logika khusus untuk memutar konten melalui speaker mobil. Saat menerima permintaan untuk memutar konten, aplikasi Anda akan memutar audio dengan cara yang sama seperti konten diputar melalui speaker ponsel atau headphone pengguna. Android Auto dan AAOS akan otomatis mengirim konten audio ke sistem mobil untuk diputar melalui speaker mobil.

Untuk mempelajari lebih lanjut cara memutar konten audio, lihat Ringkasan Media Player, Ringkasan aplikasi audio, dan ringkasan ExoPlayer.

Menetapkan tindakan pemutaran standar

Android Auto dan AAOS menampilkan kontrol pemutaran berdasarkan tindakan yang diaktifkan dalam objek PlaybackStateCompat. Secara default, aplikasi Anda harus mendukung tindakan berikut:

• ACTION_PLAY
• ACTION_PAUSE
• ACTION_STOP
• ACTION_PLAY_FROM_MEDIA_ID
• ACTION_PLAY_FROM_SEARCH

Aplikasi Anda mungkin juga mendukung tindakan berikut jika relevan dengan konten aplikasi:

• ACTION_SKIP_TO_PREVIOUS
• ACTION_SKIP_TO_NEXT

Selain itu, Anda dapat secara opsional membuat antrean pemutaran untuk ditampilkan kepada pengguna. Untuk melakukannya, panggil metode setQueue dan setQueueTitle, aktifkan tindakan ACTION_SKIP_TO_QUEUE_ITEM, dan tentukan callback onSkipToQueueItem.

Selain itu, tambahkan dukungan untuk ikon Now playing, yang merupakan indikator untuk item yang sedang diputar. Untuk melakukannya, panggil metode setActiveQueueItemId dan teruskan ID item yang sedang diputar dalam antrean. Anda harus memperbarui setActiveQueueItemId setiap kali ada perubahan antrean.

Android Auto dan AAOS menampilkan tombol untuk setiap tindakan yang diaktifkan serta antrean pemutaran. Saat pengguna mengklik tombol ini, sistem akan memanggil callback yang sesuai dari MediaSessionCompat.Callback.

Mencadangkan ruang yang tidak terpakai

Android Auto dan AAOS mencadangkan ruang pada UI untuk tindakan ACTION_SKIP_TO_PREVIOUS dan ACTION_SKIP_TO_NEXT. Jika aplikasi Anda tidak mendukung salah satu fungsi tersebut, Android Auto dan AAOS akan menggunakan ruang itu untuk menampilkan tindakan kustom apa pun yang Anda buat.

Jika tidak ingin mengisi ruang tersebut dengan tindakan kustom, Anda dapat mencadangkannya sehingga Android Auto dan AAOS mengosongkan ruang itu setiap kali aplikasi Anda tidak mendukung fungsi yang sesuai.

Untuk melakukannya, panggil metode setExtras dengan paket tambahan yang berisi konstanta yang terkait dengan fungsi yang dicadangkan. SESSION_EXTRAS_KEY_SLOT_RESERVATION_SKIP_TO_NEXT sesuai dengan ACTION_SKIP_TO_NEXT, dan SESSION_EXTRAS_KEY_SLOT_RESERVATION_SKIP_TO_PREV sesuai dengan ACTION_SKIP_TO_PREVIOUS. Gunakan konstanta ini sebagai kunci dalam paket, dan gunakan boolean true sebagai nilai.

Menetapkan PlaybackState awal

Saat Android Auto dan AAOS berkomunikasi dengan layanan browser media Anda, sesi media Anda mengomunikasikan status pemutaran konten menggunakan PlaybackStateCompat.

Aplikasi Anda tidak boleh otomatis mulai memutar musik saat AAOS atau Android Auto terhubung ke layanan browser media Anda. Sebagai gantinya, andalkan Android Auto dan AAOS untuk melanjutkan atau memulai pemutaran berdasarkan keadaan mobil atau tindakan pengguna.

Untuk melakukannya, tetapkan PlaybackStateCompat awal sesi media ke STATE_STOPPED, STATE_PAUSED, STATE_NONE, atau STATE_ERROR.

Sesi media dalam Android Auto dan AAOS hanya berlangsung selama durasi perjalanan, sehingga pengguna sering memulai dan menghentikan sesi ini. Untuk mempromosikan pengalaman yang lancar di antara perjalanan, lacak status sesi pengguna sebelumnya, sehingga saat aplikasi media menerima permintaan melanjutkan, pengguna dapat secara otomatis melanjutkan dari posisi terakhir yang mereka tinggalkan. Misalnya, item media yang terakhir diputar, PlaybackStateCompat, dan antrean.

Menambahkan tindakan pemutaran kustom

Anda dapat menambahkan tindakan pemutaran kustom untuk menampilkan tindakan tambahan yang didukung aplikasi media Anda. Jika ruangnya memungkinkan (dan Anda tidak mencadangkannya), Android akan menambahkan tindakan kustom ke kontrol transport. Jika tidak, tindakan kustom akan muncul di menu Overflow. Android menampilkan tindakan kustom dalam urutan Anda menambahkannya ke PlaybackStateCompat.

Gunakan tindakan kustom untuk menyediakan perilaku yang berbeda dengan tindakan standar. Jangan menggunakannya untuk mengganti atau menduplikasi tindakan standar.

Untuk menambahkan tindakan kustom, gunakan metode addCustomAction di class PlaybackStateCompat.Builder. Cuplikan kode ini menunjukkan cara menambahkan tindakan kustom ke "Mulai saluran radio":

val customActionExtras = Bundle()
customActionExtras.putInt(
  androidx.media3.session.MediaConstants.EXTRAS_KEY_COMMAND_BUTTON_ICON_COMPAT,
  androidx.media3.session.CommandButton.ICON_RADIO)

stateBuilder.addCustomAction(
    PlaybackStateCompat.CustomAction.Builder(
        CUSTOM_ACTION_START_RADIO_FROM_MEDIA,
        resources.getString(R.string.start_radio_from_media),
        startRadioFromMediaIcon // or R.drawable.media3_icon_radio
    ).run {
        setExtras(customActionExtras)
        build()
    }
)

Bundle customActionExtras = new Bundle();
customActionExtras.putInt(
  androidx.media3.session.MediaConstants.EXTRAS_KEY_COMMAND_BUTTON_ICON_COMPAT,
  androidx.media3.session.CommandButton.ICON_RADIO);

stateBuilder.addCustomAction(
    new PlaybackStateCompat.CustomAction.Builder(
        CUSTOM_ACTION_START_RADIO_FROM_MEDIA,
        resources.getString(R.string.start_radio_from_media),
        startRadioFromMediaIcon) // or R.drawable.media3_icon_radio
    .setExtras(customActionExtras)
    .build());

Untuk contoh selengkapnya dari metode ini, lihat metode setCustomAction pada aplikasi contoh Universal Android Music Player di GitHub. Setelah Anda membuat tindakan kustom, sesi media Anda dapat merespons tindakan tersebut dengan mengganti metode onCustomAction.

Cuplikan kode ini menunjukkan cara aplikasi Anda merespons tindakan "Mulai saluran radio":

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

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

Untuk mempelajari lebih lanjut, lihat metode onCustomAction di aplikasi contoh Universal Android Music Player di GitHub.

Membuat ikon untuk tindakan kustom

Setiap tindakan kustom yang Anda buat memerlukan ikon.

Jika deskripsi ikon tersebut cocok dengan salah satu konstanta CommandButton.ICON_, tetapkan nilai bilangan bulat untuk kunci EXTRAS_KEY_COMMAND_BUTTON_ICON_COMPAT dari ekstra tindakan kustom. Pada sistem yang didukung, tindakan ini akan menggantikan resource ikon yang diteruskan ke CustomAction.Builder, sehingga komponen sistem dapat merender tindakan Anda dan tindakan pemutaran lainnya secara konsisten.

Anda juga harus menentukan resource ikon. Aplikasi untuk mobil dapat berjalan di berbagai ukuran dan kepadatan layar, sehingga ikon yang Anda sediakan harus berupa vector drawable. Gunakan vektor drawable untuk mengubah skala aset tanpa kehilangan detail. Vektor drawable dapat menyelaraskan tepi dan sudut dengan batas piksel pada resolusi yang lebih kecil.

Jika tindakan kustom bersifat stateful (jika tindakan ini mengaktifkan atau menonaktifkan setelan pemutaran), berikan ikon yang berbeda untuk status yang berbeda guna membantu pengguna melihat perubahan saat mereka memilih tindakan.

Menyediakan gaya ikon alternatif untuk tindakan yang dinonaktifkan

Apabila tindakan kustom tidak tersedia untuk konteks yang sedang aktif, tukar ikon tindakan kustom dengan ikon alternatif yang menunjukkan bahwa tindakan dinonaktifkan.

Menunjukkan format audio

Untuk menunjukkan bahwa media yang sedang diputar menggunakan format audio khusus, Anda dapat menentukan ikon yang dirender di mobil yang mendukung fitur ini. Anda dapat menyetel KEY_CONTENT_FORMAT_TINTABLE_LARGE_ICON_URI dan KEY_CONTENT_FORMAT_TINTABLE_SMALL_ICON_URI dalam paket tambahan dari item media yang saat ini diputar (diteruskan ke MediaSession.setMetadata). Tetapkan kedua tambahan untuk mengakomodasi tata letak yang berbeda.

Selain itu, Anda dapat menyetel tambahan KEY_IMMERSIVE_AUDIO untuk memberi tahu OEM mobil bahwa ini adalah audio imersif, dan OEM harus sangat berhati-hati saat memutuskan apakah akan menerapkan efek audio yang mungkin mengganggu konten yang imersif.

Menambahkan link dari item yang sedang diputar

Anda dapat mengonfigurasi item media yang sedang diputar agar subtitel, deskripsi, atau keduanya merupakan link ke item media lain. Hal tersebut memungkinkan pengguna dengan cepat menuju item terkait; misalnya, pengguna dapat melompat ke lagu lain dari artis yang sama atau ke episode lain dari podcast. Jika mobil mendukung fitur ini, pengguna dapat mengetuk link untuk menjelajahi konten tersebut.

Untuk menambahkan link, konfigurasi metadata KEY_SUBTITLE_LINK_MEDIA_ID (untuk menautkan dari subtitel) atau KEY_DESCRIPTION_LINK_MEDIA_ID (untuk menautkan dari deskripsi). Untuk mengetahui detailnya, baca dokumentasi referensi untuk kolom metadata tersebut.