Ringkasan MediaRouteProvider

Framework router media Android memungkinkan produsen mengaktifkan pemutaran di perangkat mereka melalui antarmuka standar yang disebut MediaRouteProvider. Penyedia rute menentukan antarmuka umum untuk memutar media di perangkat penerima, sehingga memungkinkan pemutaran media di peralatan Anda dari aplikasi Android apa pun yang mendukung rute media.

Panduan ini membahas cara membuat penyedia rute media untuk perangkat penerima dan menyediakannya untuk aplikasi pemutaran media lain yang berjalan di Android. Untuk menggunakan API ini, Anda harus memahami class kunci MediaRouteProvider, MediaRouteProviderDescriptor, dan RouteController.

Ringkasan

Framework router media Android memungkinkan developer aplikasi media dan produsen perangkat pemutaran media terhubung melalui API umum dan antarmuka pengguna umum. Developer aplikasi yang mengimplementasikan antarmuka MediaRouter kemudian dapat terhubung ke framework dan memutar konten ke perangkat yang berpartisipasi dalam framework router media. Produsen perangkat pemutaran media dapat berpartisipasi dalam framework dengan memublikasikan MediaRouteProvider yang memungkinkan aplikasi lain terhubung dan memutar media di perangkat penerima. Gambar 1 mengilustrasikan cara aplikasi terhubung ke perangkat penerima melalui framework router media.

Gambar 1. Ringkasan cara class penyedia rute media menyediakan komunikasi dari aplikasi media ke perangkat penerima.

Saat Anda membuat penyedia rute media untuk perangkat penerima, penyedia tersebut memiliki tujuan berikut:

  • Menjelaskan dan memublikasikan kemampuan perangkat penerima sehingga aplikasi lain dapat menemukannya dan menggunakan fitur pemutarannya.
  • Gabungkan antarmuka pemrograman perangkat penerima dan mekanisme transpor komunikasinya untuk membuat perangkat kompatibel dengan framework router media.

Distribusi penyedia rute

Penyedia rute media didistribusikan sebagai bagian dari aplikasi Android. Penyedia rute Anda dapat tersedia untuk aplikasi lain dengan memperluas MediaRouteProviderService atau menggabungkan implementasi MediaRouteProvider dengan layanan Anda sendiri dan mendeklarasikan filter intent untuk penyedia rute media. Langkah-langkah ini memungkinkan aplikasi lain menemukan dan menggunakan rute media Anda.

Catatan: Aplikasi yang berisi penyedia rute media juga dapat menyertakan antarmuka MediaRouter ke penyedia rute, tetapi ini tidak wajib.

Support library MediaRouter

API router media ditentukan dalam library MediaRouter AndroidX Anda harus menambahkan library ini ke project pengembangan aplikasi. Untuk mengetahui informasi selengkapnya tentang cara menambahkan library dukungan ke project Anda, lihat Penyiapan Support Library.

Perhatian: Pastikan untuk menggunakan implementasi AndroidX framework router media. Jangan gunakan paket android.media yang lama.

Membuat Layanan Penyedia

Framework router media harus dapat menemukan dan terhubung ke penyedia rute media Anda agar aplikasi lain dapat menggunakan rute Anda. Untuk melakukannya, framework router media mencari aplikasi yang mendeklarasikan tindakan intent penyedia rute media. Saat aplikasi lain ingin terhubung ke penyedia Anda, framework harus dapat memanggil dan terhubung ke penyedia tersebut, sehingga penyedia Anda harus dienkapsulasi dalam Service.

Kode contoh berikut menunjukkan deklarasi layanan penyedia rute media dan filter intent dalam manifes, yang memungkinkannya ditemukan dan digunakan oleh framework router media:

<service android:name=".provider.SampleMediaRouteProviderService"
    android:label="@string/sample_media_route_provider_service"
    android:process=":mrp">
    <intent-filter>
        <action android:name="android.media.MediaRouteProviderService" />
    </intent-filter>
</service>

Contoh manifes ini mendeklarasikan layanan yang menggabungkan class penyedia rute media yang sebenarnya. Framework router media Android menyediakan class MediaRouteProviderService untuk digunakan sebagai wrapper layanan bagi penyedia rute media. Kode contoh berikut menunjukkan cara menggunakan class wrapper ini:

class SampleMediaRouteProviderService : MediaRouteProviderService() {

    override fun onCreateMediaRouteProvider(): MediaRouteProvider {
        return SampleMediaRouteProvider(this)
    }
}

Menentukan Kemampuan Rute

Aplikasi yang terhubung ke framework router media dapat menemukan rute media Anda melalui deklarasi manifes aplikasi, tetapi aplikasi tersebut juga perlu mengetahui kemampuan rute media yang Anda sediakan. Rute media dapat memiliki jenis dan fitur yang berbeda, dan aplikasi lain harus dapat menemukan detail ini untuk menentukan apakah aplikasi tersebut kompatibel dengan rute Anda.

Framework router media memungkinkan Anda menentukan dan memublikasikan kemampuan rute media melalui objek IntentFilter, objek MediaRouteDescriptor, dan MediaRouteProviderDescriptor. Bagian ini menjelaskan cara menggunakan class ini untuk memublikasikan detail rute media Anda untuk aplikasi lain.

Kategori rute

Sebagai bagian dari deskripsi terprogram penyedia rute media, Anda harus menentukan apakah penyedia Anda mendukung pemutaran jarak jauh, output sekunder, atau keduanya. Berikut adalah kategori rute yang disediakan oleh framework router media:

  • CATEGORY_LIVE_AUDIO — Output audio ke perangkat output sekunder, seperti sistem musik yang mendukung nirkabel.
  • CATEGORY_LIVE_VIDEO — Output video ke perangkat output sekunder, seperti perangkat Layar Nirkabel.
  • CATEGORY_REMOTE_PLAYBACK — Memutar video atau audio di perangkat terpisah yang menangani pengambilan, dekode, dan pemutaran media, seperti perangkat Chromecast.

Untuk menyertakan setelan ini dalam deskripsi rute media, Anda harus menyisipkannya ke objek IntentFilter, yang nantinya akan Anda tambahkan ke objek MediaRouteDescriptor:

class SampleMediaRouteProvider(context: Context) : MediaRouteProvider(context) {

    companion object {
        private val CONTROL_FILTERS_BASIC: ArrayList<IntentFilter> = IntentFilter().run {
            addCategory(MediaControlIntent.CATEGORY_REMOTE_PLAYBACK)
            arrayListOf(this)
        }
    }
}

Jika menentukan intent CATEGORY_REMOTE_PLAYBACK, Anda juga harus menentukan jenis media dan kontrol pemutaran yang didukung oleh penyedia rute media Anda. Bagian berikutnya menjelaskan cara menentukan setelan ini untuk perangkat Anda.

Jenis media dan protokol

Penyedia rute media untuk perangkat pemutaran jarak jauh harus menentukan jenis media dan protokol transfer yang didukungnya. Anda menentukan setelan ini menggunakan class IntentFilter serta metode addDataScheme() dan addDataType() dari objek tersebut. Cuplikan kode berikut menunjukkan cara menentukan filter intent untuk mendukung pemutaran video jarak jauh menggunakan http, https, dan Real Time Streaming Protocol (RTSP):

class SampleMediaRouteProvider(context: Context) : MediaRouteProvider(context) {

    companion object {

        private fun IntentFilter.addDataTypeUnchecked(type: String) {
            try {
                addDataType(type)
            } catch (ex: IntentFilter.MalformedMimeTypeException) {
                throw RuntimeException(ex)
            }
        }

        private val CONTROL_FILTERS_BASIC: ArrayList<IntentFilter> = IntentFilter().run {
            addCategory(MediaControlIntent.CATEGORY_REMOTE_PLAYBACK)
            addAction(MediaControlIntent.ACTION_PLAY)
            addDataScheme("http")
            addDataScheme("https")
            addDataScheme("rtsp")
            addDataTypeUnchecked("video/*")
            arrayListOf(this)
        }
    }
    // ...
}

Kontrol pemutaran

Penyedia rute media yang menawarkan pemutaran jarak jauh harus menentukan jenis kontrol media yang didukungnya. Berikut adalah jenis kontrol umum yang dapat disediakan oleh rute media:

  • Kontrol pemutaran, seperti putar, jeda, putar ulang, dan maju cepat.
  • Fitur antrean, yang memungkinkan aplikasi pengirim menambahkan dan menghapus item dari playlist yang dikelola oleh perangkat penerima.
  • Fitur sesi, yang mencegah aplikasi pengirim saling mengganggu dengan meminta perangkat penerima memberikan ID sesi ke aplikasi yang meminta, lalu memeriksa ID tersebut dengan setiap permintaan kontrol pemutaran berikutnya.

Contoh kode berikut menunjukkan cara membuat filter intent untuk mendukung kontrol pemutaran rute media dasar:

class SampleMediaRouteProvider(context: Context) : MediaRouteProvider(context) {

    companion object {
        // ...
        private val CONTROL_FILTERS_BASIC: ArrayList<IntentFilter> = run {
            val videoPlayback: IntentFilter = ...
            // ...
            val playControls = IntentFilter().apply {
                addCategory(MediaControlIntent.CATEGORY_REMOTE_PLAYBACK)
                addAction(MediaControlIntent.ACTION_SEEK)
                addAction(MediaControlIntent.ACTION_GET_STATUS)
                addAction(MediaControlIntent.ACTION_PAUSE)
                addAction(MediaControlIntent.ACTION_RESUME)
                addAction(MediaControlIntent.ACTION_STOP)
            }
            arrayListOf(videoPlayback, playControls)
        }
    }
    // ...
}

Untuk mengetahui informasi selengkapnya tentang intent kontrol pemutaran yang tersedia, lihat class MediaControlIntent.

MediaRouteProviderDescriptor

Setelah menentukan kemampuan rute media menggunakan objek IntentFilter, Anda dapat membuat objek deskriptor untuk dipublikasikan ke framework router media Android. Objek deskriptor ini berisi detail kemampuan rute media Anda sehingga aplikasi lain dapat menentukan cara berinteraksi dengan rute media Anda.

Kode contoh berikut menunjukkan cara menambahkan filter intent yang dibuat sebelumnya ke MediaRouteProviderDescriptor dan menetapkan deskriptor untuk digunakan oleh framework router media:

class SampleMediaRouteProvider(context: Context) : MediaRouteProvider(context) {

    init {
        publishRoutes()
    }

    private fun publishRoutes() {
        val resources = context.resources
        val routeName: String = resources.getString(R.string.variable_volume_basic_route_name)
        val routeDescription: String = resources.getString(R.string.sample_route_description)
        // Create a route descriptor using previously created IntentFilters.
        val routeDescriptor: MediaRouteDescriptor =
            MediaRouteDescriptor.Builder(VARIABLE_VOLUME_BASIC_ROUTE_ID, routeName)
                .setDescription(routeDescription)
                .addControlFilters(CONTROL_FILTERS_BASIC)
                .setPlaybackStream(AudioManager.STREAM_MUSIC)
                .setPlaybackType(MediaRouter.RouteInfo.PLAYBACK_TYPE_REMOTE)
                .setVolumeHandling(MediaRouter.RouteInfo.PLAYBACK_VOLUME_VARIABLE)
                .setVolumeMax(VOLUME_MAX)
                .setVolume(mVolume)
                .build()
        // Add the route descriptor to the provider descriptor.
        val providerDescriptor: MediaRouteProviderDescriptor =
            MediaRouteProviderDescriptor.Builder()
                .addRoute(routeDescriptor)
                .build()

        // Publish the descriptor to the framework.
        descriptor = providerDescriptor
    }
    // ...
}

Untuk mengetahui informasi selengkapnya tentang setelan deskriptor yang tersedia, lihat dokumentasi referensi untuk MediaRouteDescriptor dan MediaRouteProviderDescriptor.

Mengontrol Rute

Saat aplikasi terhubung ke penyedia rute media, penyedia akan menerima perintah pemutaran melalui framework router media yang dikirim ke rute Anda oleh aplikasi lain. Untuk menangani permintaan ini, Anda harus menyediakan implementasi class MediaRouteProvider.RouteController, yang memproses perintah dan menangani komunikasi sebenarnya ke perangkat penerima.

Framework router media memanggil metode onCreateRouteController() dari penyedia rute Anda untuk mendapatkan instance class ini, lalu mengarahkan permintaan ke instance tersebut. Berikut adalah metode utama class MediaRouteProvider.RouteController, yang harus Anda implementasikan untuk penyedia rute media:

  • onSelect() — Dipanggil saat aplikasi memilih rute Anda untuk pemutaran. Anda menggunakan metode ini untuk melakukan pekerjaan persiapan apa pun yang mungkin diperlukan sebelum pemutaran media dimulai.
  • onControlRequest() - Mengirimkan perintah pemutaran spesifik ke perangkat penerima.
  • onSetVolume() — Mengirim permintaan ke perangkat penerima untuk menyetel volume pemutaran ke nilai tertentu.
  • onUpdateVolume() — Mengirim permintaan ke perangkat penerima untuk mengubah volume pemutaran dengan jumlah yang ditentukan.
  • onUnselect() - Dipanggil ketika aplikasi batal memilih rute.
  • onRelease() — Dipanggil saat rute tidak lagi diperlukan oleh framework, sehingga dapat mengosongkan resource-nya.

Semua permintaan kontrol pemutaran, kecuali untuk perubahan volume, diarahkan ke metode onControlRequest(). Implementasi metode ini harus mengurai permintaan kontrol dan meresponsnya dengan tepat. Berikut adalah contoh implementasi metode ini yang memproses perintah untuk rute media pemutaran jarak jauh:

private class SampleRouteController : MediaRouteProvider.RouteController() {
    // ...

    override fun onControlRequest(
        intent: Intent,
        callback: MediaRouter.ControlRequestCallback?
    ): Boolean {
        return if (intent.hasCategory(MediaControlIntent.CATEGORY_REMOTE_PLAYBACK)) {
            val action = intent.action
            when (action) {
                MediaControlIntent.ACTION_PLAY -> handlePlay(intent, callback)
                MediaControlIntent.ACTION_ENQUEUE -> handleEnqueue(intent, callback)
                MediaControlIntent.ACTION_REMOVE -> handleRemove(intent, callback)
                MediaControlIntent.ACTION_SEEK -> handleSeek(intent, callback)
                MediaControlIntent.ACTION_GET_STATUS -> handleGetStatus(intent, callback)
                MediaControlIntent.ACTION_PAUSE -> handlePause(intent, callback)
                MediaControlIntent.ACTION_RESUME -> handleResume(intent, callback)
                MediaControlIntent.ACTION_STOP -> handleStop(intent, callback)
                MediaControlIntent.ACTION_START_SESSION -> handleStartSession(intent, callback)
                MediaControlIntent.ACTION_GET_SESSION_STATUS ->
                    handleGetSessionStatus(intent, callback)
                MediaControlIntent.ACTION_END_SESSION -> handleEndSession(intent, callback)
                else -> false
            }.also {
                Log.d(TAG, sessionManager.toString())
            }
        } else {
            false
        }
    }
    // ...
}

Penting untuk dipahami bahwa class MediaRouteProvider.RouteController dimaksudkan untuk bertindak sebagai wrapper untuk API ke peralatan pemutaran media Anda. Implementasi metode di class ini sepenuhnya bergantung pada antarmuka terprogram yang disediakan oleh perangkat penerima.

Kode Contoh

Contoh MediaRouter menunjukkan cara membuat penyedia rute media kustom.