MediaSession — concepte cheie, integrare și mecanismul de funcționare în Android

Ce este MediaSession?

MediaSession — este o componentă de sistem Android care permite aplicației să-și declare activitatea media și să primească comenzi de control din exterior. Când utilizatorul apasă butonul Play pe o cĉștă Bluetooth, sistemul transmite acest eveniment către MediaSession activă, iar aplicația reacționează prin propriul Callback.

Înainte de Android 5.0, în acest scop se folosea RemoteControlClient, dar acesta nu asigura flexibilitatea necesară și nu suporta scenariile moderne — Android Auto, ceasuri inteligente, difuzoare inteligente. MediaSession a fost introdus în API 21 și a devenit standardul de facto pentru toate aplicațiile Android cu redare audio și video.

Conform Android Developer Documentation (2026), aplicația ar trebui să creeze o singură MediaSession pentru fiecare sursă independentă de redare. Însă, la un moment dat poate exista doar o sesiune activă — orice sesiune nouă dezactivează automat pe cea anterioară.

MediaSession și MediaBrowserService

Combinația MediaSession cu MediaBrowserService asigură un ciclu complet de gestionare a media: serviciul oferă un arbore de conținut (liste de redare, cataloage), iar sesiunea primește comenzi de navigare și redare. Aceasta este arhitectura recomandată de Google pentru playerele muzicale, podcasturi și cărți audio.

MediaBrowserService rulează ca un foreground-service cu notificare, ceea ce garantează funcționarea aplicației chiar și după uciderea Activity. Acest lucru este critic pentru playerele audio care trebuie să continue redarea când aplicația este minimizată.

Cum funcționează MediaSession

Sesiunea suportă două tipuri de interacțiune: primește comenzi de la MediaController (partea client) și transmite starea prin PlaybackState. MediaController se poate afla în același proces sau într-o aplicație separată — sistemul direcționează cererile prin SessionToken.

Când utilizatorul cheamă asistentul vocal Android și spune „Redă următoarea piesă”, sistemul găsește MediaSession activă prin legătura cu MediaBrowserService și trimite comanda ACTION_SKIP_TO_NEXT. Callback-ul aplicației primește apelul onSkipToNext() și actualizează PlaybackState.

Actualizarea PlaybackState prin setPlaybackState() notifică imediat toate MediaController-urile conectate. Centrul media al sistemului, dispozitivul Bluetooth și Android Auto primesc actualizarea simultan — întârzierea nu depășește 50 ms în condiții normale.

PlaybackState și metadatele sale

PlaybackState conține flag-uri cheie de stare: isPlaying, poziție, viteză, acțiuni disponibile (play, pause, seek, stop). Fără un PlaybackState completat corect, sistemul nu știe ce comenzi suportă aplicația și nu trimite evenimentele corespunzătoare.

Metadatele (MediaMetadata) completează starea cu informații despre piesa curentă — title, artist, album art URI. Android Auto și dispozitivele purtabile folosesc MediaMetadata pentru afișarea informațiilor pe ecran. Conform Google I/O 2024, completarea corectă a MediaMetadata crește vizibilitatea aplicației în lansatoare terțe cu 40%.

Componentele cheie ale MediaSession

Arhitectura MediaSession constă din patru componente interconectate, fiecare rezolvând propria sarcină. Dezvoltatorul trebuie să implementeze toate cele patru pentru o integrare completă cu sistemul.

• MediaSessionCompat — clasa principală a sesiunii, creată cu tag-ul aplicației și care primește PendingIntent pentru butoanele media.
• MediaSession.Callback — handler-ul de comenzi. Implementează onPlay, onPause, onSkipToNext, onSeekTo și alte metode.
• PlaybackStateCompat — starea curentă a playerului. Conține flag-uri, poziție, viteză și lista acțiunilor disponibile.
• MediaMetadataCompat — metadatele media curente: titlu, artist, album, copertă, durată.

Ciclul de viață al MediaSession

Sesiunea este creată în onCreate al serviciului sau Activity prin apelul MediaSessionCompat(context, tag). După creare, trebuie neapărat să se apeleze setFlags(FLAG_HANDLES_MEDIA_BUTTONS | FLAG_HANDLES_TRANSPORT_CONTROLS). În onDestroy se apelează release() pentru eliberarea resurselor sistemului.

Gestionarea incorectă a ciclului de viață este una dintre greșelile frecvente. Dacă nu se apelează release(), sesiunea rămâne în sistem, iar următoarea aplicație poate primi o stare falsă. Android 13+ afișează un avertisment în Logcat la scurgeri de sesiune.

Integrarea MediaSession în aplicație

Integrarea de bază începe cu crearea sesiunii și implementarea Callback-ului. Se recomandă utilizarea MediaSessionCompat din biblioteca AndroidX media, care asigură o API unică pentru toate versiunile Android — de la API 14 la 35.

Crearea MediaSession și a Callback-ului

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

În exemplu, se creează o MediaSession cu tag-ul MusicService și flag-uri pentru gestionarea butoanelor media. Callback-ul implementează onPlay și onPause, actualizând PlaybackState. Metoda setActions declară acțiunile disponibile pe care sistemul le afișează pe ecranul de blocare și în centrul media.

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

Metadatele trebuie actualizate la fiecare schimbare de piesă. Sistemul folosește METADATA_KEY_TITLE și METADATA_KEY_ARTIST pentru afișarea informațiilor pe ecranele Bluetooth ale mașinilor și dispozitivelor purtabile. Dacă nu se setează URI-ul copertei, playerul va afișa un placeholder gri.

Procesarea comenzilor media de pe Bluetooth și cĉști

Cĉștile Bluetooth trimit comenzi prin profilul AVRCP 1.6+. Android transmite aceste comenzi în intent-uri ACTION_MEDIA_BUTTON, care sunt interceptate de MediaSession când flag-ul FLAG_HANDLES_MEDIA_BUTTONS este setat.

Când utilizatorul apasă butonul Play pe cĉștile Bluetooth, sistemul creează un KeyEvent cu codul KEYCODE_MEDIA_PLAY, care este distribuit metodei onMediaButtonEvent a Callback-ului. Dacă în Callback este implementat onPlay(), sistemul îl apelează direct. La apăsarea unică a butonului pe cască, se trimite KEYCODE_MEDIA_PLAY_PAUSE — playerul trebuie să comute starea.

Procesarea scenariilor complexe cu mai multe butoane

Cĉștile Bluetooth moderne pot avea până la 5 butoane: volum +/-, play/pause, next, previous. Fiecare buton generează propriul KeyEvent care trebuie procesat corect de Callback. Apăsarea dublă a butonului play/pause este de obicei interpretată ca trecere la următoarea piesă (ACTION_SKIP_TO_NEXT) pe multe cĉști.

Conform Android Compatibility Definition Document (2026), toate aplicațiile cu conținut media sunt obligate să proceseze corect KEYCODE_MEDIA_PLAY_PAUSE. Ignorarea acestei cerințe duce la scăderea automată a ratingului aplicației în Google Play pentru categoria Muzică și Audio.

Sincronizarea cu centrul media al sistemului

începând cu Android 11, centrul media al sistemului (Media Control Panel) afișează până la 5 sesiuni MediaSession recente în panoul de notificări. Utilizatorul poate controla playerul fără a deschide aplicația. Pentru o afișare corectă, este necesară implementarea MediaBrowserService și completarea corectă a PlaybackState.

Media Control Panel arată: titlul piesei, artistul, coperta (din MediaMetadata), butoanele de control (din acțiunile permise ale PlaybackState). Dacă aplicația nu actualizează PlaybackState cel puțin o dată la 10 secunde în timpul redării active, centrul media ascunde sesiunea din panou.

Foreground-service cu notificare

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

Notificarea MediaStyle este legată de MediaSession prin sessionToken și afișează butoanele media standard. Fără MediaStyle, notificarea va arăta ca o alertă obișnuită fără butoane de control. Android 13+ necesită permisiunea explicită POST_NOTIFICATIONS pentru afișare.