MediaSession — mga pangunahing konsepto, integrasyon, at mekanismo ng paggana sa Android

Ano ang MediaSession?

MediaSession — ay isang system component ng Android na nagpapahintulot sa application na ideklara ang media activity nito at tumanggap ng mga control command mula sa labas. Kapag pinindot ng user ang Play button sa Bluetooth headset, ipinapasa ng system ang event na ito sa aktibong MediaSession, at ang application ay tumutugon sa pamamagitan ng sarili nitong Callback.

Bago ang Android 5.0, ginamit ang RemoteControlClient para sa mga layuning ito, ngunit hindi ito nagbigay ng kinakailangang flexibility at hindi sumusuporta sa mga modernong scenario — Android Auto, smartwatch, smart speaker. Ipinakilala ang MediaSession sa API 21 at naging de facto standard para sa lahat ng Android application na may audio at video playback.

Ayon sa Android Developer Documentation (2026), ang application ay dapat gumawa ng isang MediaSession para sa bawat independiyenteng source ng playback. Sa isang pagkakataon, isa lamang ang aktibong session — bawat bagong session ay awtomatikong nagde-deactivate ng nauna.

MediaSession at MediaBrowserService

Ang kumbinasyon ng MediaSession sa MediaBrowserService ay nagbibigay ng kumpletong cycle ng pamamahala ng media: ang serbisyo ay nagbibigay ng content tree (playlist, catalog), at ang session ay tumatanggap ng navigation at playback command. Ito ang arkitekturang inirerekomenda ng Google para sa mga music player, podcast, at audiobook.

Ang MediaBrowserService ay tumatakbo bilang foreground-service na may notification, na ginagarantiyahan ang paggana ng application kahit na matapos patayin ang Activity. Ito ay kritikal para sa mga audio player na dapat magpatuloy sa pag-playback kapag ang application ay minimize.

Paano gumagana ang MediaSession

Ang session ay sumusuporta sa dalawang uri ng interaksyon: tumatanggap ito ng mga command mula sa MediaController (client side) at nag-broadcast ng estado sa pamamagitan ng PlaybackState. Ang MediaController ay maaaring nasa parehong proseso o sa hiwalay na application — ang system ay nagruruta ng mga request sa pamamagitan ng SessionToken.

Kapag tinawag ng user ang voice assistant ng Android at sinabing “I-play ang susunod na kanta”, hinahanap ng system ang aktibong MediaSession sa pamamagitan ng koneksyon sa MediaBrowserService at nagpapadala ng command na ACTION_SKIP_TO_NEXT. Ang Callback ng application ay tumatanggap ng tawag na onSkipToNext() at ina-update ang PlaybackState.

Ang pag-update ng PlaybackState sa pamamagitan ng setPlaybackState() ay agad na nag-aabiso sa lahat ng konektadong MediaController. Ang system media center, Bluetooth device, at Android Auto ay sabay na tumatanggap ng update — ang delay ay hindi lalampas sa 50 ms sa normal na kondisyon.

PlaybackState at metadata nito

Ang PlaybackState ay naglalaman ng mga key status flag: isPlaying, posisyon, bilis, mga available na action (play, pause, seek, stop). Kung walang tamang pagpuno ng PlaybackState, hindi alam ng system kung anong mga command ang sinusuportahan ng application at hindi nagpapadala ng mga kaukulang event.

Ang metadata (MediaMetadata) ay nagkukumpleto sa estado ng impormasyon tungkol sa kasalukuyang track — title, artist, album art URI. Ginagamit ng Android Auto at wearable device ang MediaMetadata para magpakita ng impormasyon sa screen. Ayon sa Google I/O 2024, ang tamang pagpuno ng MediaMetadata ay nagpapataas ng visibility ng application sa mga third-party launcher ng 40%.

Mga pangunahing component ng MediaSession

Ang arkitektura ng MediaSession ay binubuo ng apat na magkakaugnay na component, bawat isa ay lumulutas ng sarili nitong gawain. Dapat ipatupad ng developer ang lahat ng apat para sa kumpletong integrasyon sa system.

• MediaSessionCompat — pangunahing klase ng session, ginawa gamit ang tag ng application at tumatanggap ng PendingIntent para sa mga media button.
• MediaSession.Callback — handler ng command. Nagpapatupad ng onPlay, onPause, onSkipToNext, onSeekTo at iba pang mga pamamaraan.
• PlaybackStateCompat — kasalukuyang estado ng player. Naglalaman ng mga flag, posisyon, bilis, at listahan ng mga available na action.
• MediaMetadataCompat — metadata ng kasalukuyang media: pamagat, artist, album, cover, tagal.

Lifecycle ng MediaSession

Ang session ay ginagawa sa onCreate ng serbisyo o Activity sa pamamagitan ng pagtawag sa MediaSessionCompat(context, tag). Pagkatapos gawin, dapat tawagan ang setFlags(FLAG_HANDLES_MEDIA_BUTTONS | FLAG_HANDLES_TRANSPORT_CONTROLS). Sa onDestroy tinatawag ang release() para palayain ang mga system resources.

Ang maling pamamahala ng lifecycle ay isa sa mga karaniwang pagkakamali. Kung hindi tatawagin ang release(), mananatili ang session sa system, at ang susunod na application ay maaaring makatanggap ng maling estado. Ang Android 13+ ay nagpapakita ng babala sa Logcat kapag may session leak.

Pagsasama ng MediaSession sa application

Ang pangunahing integrasyon ay nagsisimula sa paggawa ng session at pagpapatupad ng Callback. Inirerekomenda ang paggamit ng MediaSessionCompat mula sa AndroidX media library, na nagbibigay ng pare-parehong API para sa lahat ng bersyon ng Android — mula API 14 hanggang 35.

Paggawa ng MediaSession at Callback

class MusicService : Service() {

    private lateinit var mediaSession: MediaSessionCompat
    private lateinit var stateBuilder: PlaybackStateCompat.Builder

    override fun onCreate() {
        super.onCreate()

        mediaSession = MediaSessionCompat(this, "MusicService")
        mediaSession.setFlags(
            MediaSessionCompat.FLAG_HANDLES_MEDIA_BUTTONS
                or MediaSessionCompat.FLAG_HANDLES_TRANSPORT_CONTROLS
        )
        mediaSession.setCallback(MediaSessionCallback())
        updatePlaybackState(false)
    }

    private inner class MediaSessionCallback : MediaSessionCompat.Callback() {
        override fun onPlay() {
            updatePlaybackState(true)
        }

        override fun onPause() {
            updatePlaybackState(false)
        }
    }

    private fun updatePlaybackState(isPlaying: Boolean) {
        stateBuilder = PlaybackStateCompat.Builder()
            .setState(
                if (isPlaying) PlaybackStateCompat.STATE_PLAYING
                else PlaybackStateCompat.STATE_PAUSED,
                AudioTrackCompat.CURRENT_POSITION_NOT_SET,
                1.0f
            )
            .setActions(
                PlaybackStateCompat.ACTION_PLAY
                    or PlaybackStateCompat.ACTION_PAUSE
                    or PlaybackStateCompat.ACTION_SKIP_TO_NEXT
                    or PlaybackStateCompat.ACTION_SKIP_TO_PREVIOUS
            )
        mediaSession.setPlaybackState(stateBuilder.build())
    }

    override fun onDestroy() {
        mediaSession.release()
        super.onDestroy()
    }
}

Sa halimbawa, ginagawa ang MediaSession na may tag na MusicService at flag para sa pagproseso ng mga media button. Ang Callback ay nagpapatupad ng onPlay at onPause, na ina-update ang PlaybackState. Ang setActions method ay nagdedeklara ng mga available na action na ipinapakita ng system sa lock screen at sa media center.

Pag-set ng MediaMetadata

private fun setMetadata(title: String, artist: String) {
    val metadata = MediaMetadataCompat.Builder()
        .putString(MediaMetadataCompat.METADATA_KEY_TITLE, title)
        .putString(MediaMetadataCompat.METADATA_KEY_ARTIST, artist)
        .putLong(MediaMetadataCompat.METADATA_KEY_DURATION, 300000L)
        .putString(MediaMetadataCompat.METADATA_KEY_ALBUM_ART_URI, albumArtUrl)
        .build()
    mediaSession.setMetadata(metadata)
}

Ang metadata ay dapat i-update sa bawat pagbabago ng track. Ginagamit ng system ang METADATA_KEY_TITLE at METADATA_KEY_ARTIST para magpakita ng impormasyon sa Bluetooth display ng mga sasakyan at wearable device. Kung hindi naka-set ang cover URI, magpapakita ang player ng gray placeholder.

Pagproseso ng mga media command mula sa Bluetooth at headset

Ang mga Bluetooth headset ay nagpapadala ng command sa pamamagitan ng profile na AVRCP 1.6+. Ang Android ay nagpapadala ng mga command na ito sa ACTION_MEDIA_BUTTON intents, na nahaharang ng MediaSession kapag naka-set ang flag na FLAG_HANDLES_MEDIA_BUTTONS.

Kapag pinindot ng user ang Play button sa Bluetooth headphone, gumagawa ang system ng KeyEvent na may code na KEYCODE_MEDIA_PLAY, na idinidispat sa method na onMediaButtonEvent ng Callback. Kung naka-implement ang onPlay() sa Callback, direktang tinatawag ito ng system. Sa isang pagpindot ng button sa headset, ipinapadala ang KEYCODE_MEDIA_PLAY_PAUSE — dapat magpalit ng estado ang player.

Pamamahala ng kumplikadong scenario na may maraming button

Ang modernong Bluetooth headphone ay maaaring magkaroon ng hanggang 5 button: volume +/-, play/pause, next, previous. Bawat button ay gumagawa ng sariling KeyEvent na dapat iproseso nang tama ng Callback. Ang double press ng play/pause ay karaniwang ini-interpret bilang paglipat sa susunod na track (ACTION_SKIP_TO_NEXT) sa maraming headset.

Ayon sa Android Compatibility Definition Document (2026), lahat ng application na may media content ay obligadong iproseso nang tama ang KEYCODE_MEDIA_PLAY_PAUSE. Ang pagbalewala sa requirement na ito ay humahantong sa awtomatikong pagbaba ng rating ng application sa Google Play para sa kategoryang Musika at Audio.

Pag-sync sa system media center

Simula sa Android 11, ang system media center (Media Control Panel) ay nagpapakita ng hanggang 5 kamakailang MediaSession sa notification panel. Maaaring kontrolin ng user ang player nang hindi binubuksan ang application. Para sa tamang display, kinakailangan na i-implement ang MediaBrowserService at tamang punan ang PlaybackState.

Ang Media Control Panel ay nagpapakita: pamagat ng track, artist, cover (mula sa MediaMetadata), control button (mula sa mga pinapayagang action ng PlaybackState). Kung hindi ina-update ng application ang PlaybackState kahit isang beses bawat 10 segundo sa panahon ng aktibong playback, itinatago ng media center ang session mula sa panel.

Foreground-service na may notification

private fun startForegroundService() {
    val notification = NotificationCompat.Builder(this, "media_channel")
        .setSmallIcon(R.drawable.ic_play)
        .setContentTitle("Kasalukuyang nagpe-play")
        .setContentText(currentTrackTitle)
        .setPriority(NotificationCompat.PRIORITY_LOW)
        .setStyle(
            androidx.media.app.NotificationCompat.MediaStyle()
                .setMediaSession(mediaSession.sessionToken)
        )
        .build()
    startForeground(1001, notification)
}

Ang MediaStyle notification ay naka-link sa MediaSession sa pamamagitan ng sessionToken at nagpapakita ng standard media button. Kung walang MediaStyle, ang notification ay magmumukhang ordinaryong alert na walang control button. Ang Android 13+ ay nangangailangan ng tahasang pahintulot na POST_NOTIFICATIONS para magpakita.