MediaSession — kulcsfogalmak, integráció és működési mechanizmus Androidon

Mi az a MediaSession?

MediaSession — az Android rendszerkomponense, amely lehetővé teszi az alkalmazás számára, hogy bejelentse médiaaktivitását és kívülről fogadjon vezérlőparancsokat. Amikor a felhasználó megnyomja a Play gombot egy Bluetooth headseten, a rendszer továbbítja ezt az eseményt az aktív MediaSession-nek, és az alkalmazás a saját Callback-jén keresztül reagál.

Az Android 5.0 előtt erre a célra a RemoteControlClient-et használták, de az nem nyújtotta a szükséges rugalmasságot és nem támogatta a modern forgatókönyveket — Android Auto, okosórák, okoshangszórók. A MediaSession-t az API 21-ben vezették be, és ez lett a de facto szabvány minden audio- és videolejátszó Android-alkalmazás számára.

Az Android Developer Documentation (2026) szerint az alkalmazásnak minden független lejátszási forráshoz egy MediaSession-t kell létrehoznia. Egyszerre csak egy aktív munkamenet lehet — minden új munkamenet automatikusan deaktiválja az előzőt.

MediaSession és MediaBrowserService

A MediaSession MediaBrowserService-rel való kombinációja teljes médiamenedzsment ciklust biztosít: a szolgáltatás tartalomfát (lejátszási listák, katalógusok) nyújt, a munkamenet pedig navigációs és lejátszási parancsokat fogad. Ezt az architektúrát ajánlja a Google zenelejátszók, podcastok és hangoskönyvek számára.

A MediaBrowserService foreground-szolgáltatásként indul értesítéssel, ami garantálja az alkalmazás működését még az Activity megszakítása után is. Ez kritikus fontosságú az audiolejátszók számára, amelyeknek folytatniuk kell a lejátszást az alkalmazás minimalizálásakor.

Hogyan működik a MediaSession

A munkamenet kétféle interakciót támogat: parancsokat fogad a MediaController-től (kliens oldal) és állapotot sugároz a PlaybackState-en keresztül. A MediaController lehet ugyanabban a folyamatban vagy külön alkalmazásban — a rendszer a SessionToken-en keresztül irányítja a kéréseket.

Amikor a felhasználó előhívja az Android hangasszisztensét és azt mondja, „Következő szám lejátszása”, a rendszer megtalálja az aktív MediaSession-t a MediaBrowserService-kapcsolaton keresztül, és elküldi a ACTION_SKIP_TO_NEXT parancsot. Az alkalmazás Callback-je megkapja az onSkipToNext() hívást és frissíti a PlaybackState-et.

A PlaybackState setPlaybackState()-en keresztüli frissítése azonnal értesíti az összes csatlakoztatott MediaController-t. A rendszermédia-központ, a Bluetooth-eszköz és az Android Auto egyszerre kapja a frissítést — a késleltetés normál körülmények között nem haladja meg az 50 ms-t.

PlaybackState és metaadatai

A PlaybackState kulcsfontosságú állapotjelzőket tartalmaz: isPlaying, pozíció, sebesség, elérhető műveletek (play, pause, seek, stop). Helyesen kitöltött PlaybackState nélkül a rendszer nem tudja, milyen parancsokat támogat az alkalmazás, és nem küldi el a megfelelő eseményeket.

A metaadatok (MediaMetadata) kiegészítik az állapotot az aktuális szám információival — title, artist, album art URI. Az Android Auto és a viselhető eszközök a MediaMetadata-ot használják az információk képernyőn való megjelenítéséhez. A Google I/O 2024 szerint a MediaMetadata helyes kitöltése 40%-kal növeli az alkalmazás láthatóságát harmadik féltől származó indítóprogramokban.

A MediaSession kulcskomponensei

A MediaSession architektúrája négy egymással összefüggő komponensből áll, amelyek mindegyike a saját feladatát oldja meg. A fejlesztőnek mind a négyet implementálnia kell a teljes rendszerintegrációhoz.

• MediaSessionCompat — a munkamenet fő osztálya, az alkalmazás címkéjével jön létre és PendingIntent-et fogad a média gombokhoz.
• MediaSession.Callback — a parancsok kezelője. Implementálja az onPlay, onPause, onSkipToNext, onSeekTo és más metódusokat.
• PlaybackStateCompat — a lejátszó aktuális állapota. Tartalmazza a jelzőket, pozíciót, sebességet és az elérhető műveletek listáját.
• MediaMetadataCompat — az aktuális média metaadatai: cím, előadó, album, borító, időtartam.

A MediaSession életciklusa

A munkamenet a szolgáltatás vagy Activity onCreate-jében jön létre a MediaSessionCompat(context, tag) hívással. Létrehozás után kötelező meghívni a setFlags(FLAG_HANDLES_MEDIA_BUTTONS | FLAG_HANDLES_TRANSPORT_CONTROLS) metódust. Az onDestroy-ben a release() hívása szabadítja fel a rendszererőforrásokat.

Az életciklus helytelen kezelése az egyik gyakori hiba. Ha a release() nem kerül meghívásra, a munkamenet a rendszerben marad, és a következő alkalmazás hamis állapotot kaphat. Az Android 13+ figyelmeztetést jelenít meg a Logcat-ben munkamenet-szivárgás esetén.

A MediaSession integrálása az alkalmazásba

Az alapintegráció a munkamenet létrehozásával és a Callback implementálásával kezdődik. Ajánlott az AndroidX media könyvtárból származó MediaSessionCompat használata, amely egységes API-t biztosít az Android összes verziójához — API 14-től 35-ig.

MediaSession és Callback létrehozása

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()
    }
}

A példában a MediaSession a MusicService címkével és a média gombok kezeléséhez szükséges jelzőkkel jön létre. A Callback implementálja az onPlay és onPause metódusokat, frissítve a PlaybackState-et. A setActions metódus deklarálja az elérhető műveleteket, amelyeket a rendszer a zárolási képernyőn és a média-központban jelenít meg.

MediaMetadata beállítása

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)
}

A metaadatokat minden számváltáskor frissíteni kell. A rendszer a METADATA_KEY_TITLE és METADATA_KEY_ARTIST segítségével jeleníti meg az információkat az autók Bluetooth kijelzőin és a viselhető eszközökön. Ha a borító URI nincs beállítva, a lejátszó szürke helyőrzőt jelenít meg.

Médiaparancsok feldolgozása Bluetooth-ról és fejhallgatóról

A Bluetooth headsetek az AVRCP 1.6+ profilon keresztül küldenek parancsokat. Az Android továbbítja ezeket a parancsokat ACTION_MEDIA_BUTTON intent-ekbe, amelyeket a MediaSession fog el, ha a FLAG_HANDLES_MEDIA_BUTTONS jelző be van állítva.

Amikor a felhasználó megnyomja a Play gombot a Bluetooth fejhallgatón, a rendszer létrehoz egy KeyEvent-et a KEYCODE_MEDIA_PLAY kóddal, amely a Callback onMediaButtonEvent metódusába kerül. Ha a Callback-ben implementálva van az onPlay(), a rendszer közvetlenül hívja meg. A headset gombjának egyszeri megnyomásakor KEYCODE_MEDIA_PLAY_PAUSE kerül elküldésre — a lejátszónak át kell kapcsolnia az állapotot.

Összetett forgatókönyvek kezelése több gombbal

A modern Bluetooth fejhallgatók akár 5 gombbal is rendelkezhetnek: hangerő +/-, play/pause, next, previous. Minden gomb saját KeyEvent-et generál, amelyet a Callback-nek megfelelően kell kezelnie. A play/pause dupla megnyomása számos fejhallgatón általában a következő számra ugrásként (ACTION_SKIP_TO_NEXT) értelmeződik.

Az Android Compatibility Definition Document (2026) szerint minden médiatartalommal rendelkező alkalmazás köteles megfelelően kezelni a KEYCODE_MEDIA_PLAY_PAUSE-t. E követelmény figyelmen kívül hagyása az alkalmazás értékelésének automatikus csökkenéséhez vezet a Google Play-ben a Zene és Audio kategóriában.

Szinkronizálás a rendszermédia-központtal

Android 11-től kezdve a rendszermédia-központ (Media Control Panel) legfeljebb 5 legutóbbi MediaSession-t jelenít meg az értesítési panelen. A felhasználó az alkalmazás megnyitása nélkül vezérelheti a lejátszót. A helyes megjelenítéshez szükség van a MediaBrowserService implementálására és a PlaybackState megfelelő kitöltésére.

A Media Control Panel megjeleníti: a szám címét, előadót, borítót (MediaMetadata-ból), vezérlőgombokat (a PlaybackState engedélyezett műveleteiből). Ha az alkalmazás nem frissíti a PlaybackState-et legalább 10 másodpercenként egyszer aktív lejátszás során, a médiaközpont elrejti a munkamenetet a panelből.

Foreground-szolgáltatás értesítéssel

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

A MediaStyle értesítés a sessionToken-en keresztül kapcsolódik a MediaSession-hez, és szabványos média gombokat jelenít meg. MediaStyle nélkül az értesítés egy szokásos figyelmeztetésnek fog kinézni vezérlőgombok nélkül. Az Android 13+ explicit POST_NOTIFICATIONS engedélyt követel meg a megjelenítéshez.