MediaSession — kernconcepten, integratie en werkingsmechanisme in Android

Wat is MediaSession?

MediaSession — is een systeemcomponent van Android waarmee een app zijn media-activiteit kan melden en externe bedieningsopdrachten kan ontvangen. Wanneer de gebruiker op de Play-knop op een Bluetooth-headset drukt, geeft het systeem deze gebeurtenis door aan de actieve MediaSession en reageert de app via zijn eigen Callback.

Vóór Android 5.0 werd hiervoor RemoteControlClient gebruikt, maar deze bood niet de nodige flexibiliteit en ondersteunde moderne scenario's niet — Android Auto, smartwatches, slimme luidsprekers. MediaSession werd geïntroduceerd in API 21 en werd de de facto standaard voor alle Android-apps met audio- en video-afspelen.

Volgens Android Developer Documentation (2026) moet de app één MediaSession maken voor elke onafhankelijke afspeelbron. Er kan slechts één actieve sessie tegelijk zijn — elke nieuwe sessie deactiveert automatisch de vorige.

MediaSession en MediaBrowserService

De combinatie van MediaSession met MediaBrowserService biedt een volledige mediabeheercyclus: de service biedt een inhoudsboom (afspeellijsten, catalogi) en de sessie ontvangt navigatie- en afspeelopdrachten. Dit is de door Google aanbevolen architectuur voor muziekspelers, podcasts en audioboeken.

MediaBrowserService wordt gestart als een foreground-service met een melding, wat de werking van de app garandeert, zelfs nadat de Activity is beëindigd. Dit is cruciaal voor audiospelers die moeten blijven afspelen wanneer de app is geminimaliseerd.

Hoe werkt MediaSession

De sessie ondersteunt twee soorten interactie: het ontvangt opdrachten van MediaController (clientzijde) en verzendt de status via PlaybackState. MediaController kan zich in hetzelfde proces of in een aparte app bevinden — het systeem routeert verzoeken via SessionToken.

Wanneer de gebruiker de spraakassistent van Android oproept en zegt “Volgend nummer afspelen”, vindt het systeem de actieve MediaSession via de koppeling met MediaBrowserService en stuurt het commando ACTION_SKIP_TO_NEXT. De Callback van de app ontvangt de aanroep onSkipToNext() en werkt PlaybackState bij.

Het bijwerken van PlaybackState via setPlaybackState() stelt onmiddellijk alle verbonden MediaControllers op de hoogte. Het systeemmediacenter, het Bluetooth-apparaat en Android Auto ontvangen gelijktijdig de update — de vertraging is onder normale omstandigheden niet meer dan 50 ms.

PlaybackState en zijn metadata

PlaybackState bevat de belangrijkste statusvlaggen: isPlaying, positie, snelheid, beschikbare acties (play, pause, seek, stop). Zonder correct ingevulde PlaybackState weet het systeem niet welke opdrachten de app ondersteunt en stuurt het geen overeenkomstige gebeurtenissen.

Metadata (MediaMetadata) vullen de status aan met informatie over het huidige nummer — title, artist, album art URI. Android Auto en draagbare apparaten gebruiken MediaMetadata om informatie op het scherm weer te geven. Volgens Google I/O 2024 verhoogt het correct invullen van MediaMetadata de zichtbaarheid van de app in externe launchers met 40%.

Belangrijkste componenten van MediaSession

De architectuur van MediaSession bestaat uit vier onderling verbonden componenten, die elk hun eigen taak vervullen. De ontwikkelaar moet alle vier implementeren voor volledige integratie met het systeem.

• MediaSessionCompat — de hoofdklasse van de sessie, gemaakt met de app-tag en ontvangt PendingIntent voor mediaknoppen.
• MediaSession.Callback — de opdrachtafhandelaar. Implementeert onPlay, onPause, onSkipToNext, onSeekTo en andere methoden.
• PlaybackStateCompat — de huidige status van de speler. Bevat vlaggen, positie, snelheid en een lijst met beschikbare acties.
• MediaMetadataCompat — metadata van de huidige media: titel, artiest, album, omslag, duur.

Levenscyclus van MediaSession

De sessie wordt gemaakt in onCreate van de service of Activity door MediaSessionCompat(context, tag) aan te roepen. Na het maken moet verplicht setFlags(FLAG_HANDLES_MEDIA_BUTTONS | FLAG_HANDLES_TRANSPORT_CONTROLS) worden aangeroepen. In onDestroy wordt release() aangeroepen om systeembronnen vrij te geven.

Onjuist beheer van de levenscyclus is een veelvoorkomende fout. Als release() niet wordt aangeroepen, blijft de sessie in het systeem en kan de volgende app een valse status krijgen. Android 13+ geeft een waarschuwing in Logcat bij sessielekken.

MediaSession integreren in de app

De basisintegratie begint met het maken van de sessie en het implementeren van de Callback. Het wordt aanbevolen om MediaSessionCompat van de AndroidX media-bibliotheek te gebruiken, die een uniforme API biedt voor alle Android-versies — van API 14 tot 35.

MediaSession en Callback maken

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

In het voorbeeld wordt een MediaSession gemaakt met de tag MusicService en vlaggen voor het verwerken van mediaknoppen. De Callback implementeert onPlay en onPause, waarbij PlaybackState wordt bijgewerkt. De methode setActions declareert de beschikbare acties die het systeem weergeeft op het vergrendelscherm en in het mediacenter.

MediaMetadata instellen

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

Metadata moeten worden bijgewerkt bij elke nummerwissel. Het systeem gebruikt METADATA_KEY_TITLE en METADATA_KEY_ARTIST om informatie weer te geven op Bluetooth-schermen van auto's en draagbare apparaten. Als de omslag-URI niet wordt ingesteld, toont de speler een grijze placeholder.

Mediacommando's van Bluetooth en headsets verwerken

Bluetooth-headsets verzenden opdrachten via het AVRCP 1.6+-profiel. Android zendt deze opdrachten uit naar ACTION_MEDIA_BUTTON-intents, die worden onderschept door MediaSession wanneer de vlag FLAG_HANDLES_MEDIA_BUTTONS is ingesteld.

Wanneer de gebruiker op de Play-knop op Bluetooth-koptelefoon drukt, maakt het systeem een KeyEvent met code KEYCODE_MEDIA_PLAY, dat wordt gedispatched naar de methode onMediaButtonEvent van de Callback. Als onPlay() in de Callback is geïmplementeerd, roept het systeem deze direct aan. Bij een enkele druk op de knop van de headset wordt KEYCODE_MEDIA_PLAY_PAUSE verzonden — de speler moet de status omschakelen.

Complexe scenario's met meerdere knoppen verwerken

Moderne Bluetooth-koptelefoons kunnen tot 5 knoppen hebben: volume +/-, play/pause, next, previous. Elke knop genereert zijn eigen KeyEvent die correct moet worden verwerkt door de Callback. Dubbelklikken op play/pause wordt meestal geïnterpreteerd als overslaan naar het volgende nummer (ACTION_SKIP_TO_NEXT) op veel headsets.

Volgens het Android Compatibility Definition Document (2026) zijn alle apps met mediacontent verplicht om KEYCODE_MEDIA_PLAY_PAUSE correct te verwerken. Het negeren van deze vereiste leidt tot een automatische verlaging van de app-beoordeling in Google Play voor de categorie Muziek en Audio.

Synchronisatie met het systeemmediacenter

Vanaf Android 11 toont het systeemmediacenter (Media Control Panel) tot 5 recente MediaSession in het meldingenpaneel. De gebruiker kan de speler bedienen zonder de app te openen. Voor correcte weergave is het noodzakelijk om MediaBrowserService te implementeren en PlaybackState correct in te vullen.

Het Media Control Panel toont: de titel van het nummer, de artiest, de omslag (van MediaMetadata), bedieningsknoppen (van de toegestane acties van PlaybackState). Als de app PlaybackState niet minstens één keer per 10 seconden bijwerkt tijdens actief afspelen, verbergt het mediacenter de sessie uit het paneel.

Foreground-service met melding

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

De MediaStyle-melding wordt via sessionToken aan MediaSession gekoppeld en toont standaard mediaknoppen. Zonder MediaStyle ziet de melding eruit als een gewone waarschuwing zonder bedieningsknoppen. Android 13+ vereist expliciete toestemming POST_NOTIFICATIONS voor weergave.