MediaSession — concetti chiave, integrazione e meccanismo di funzionamento in Android

Cos'è MediaSession?

MediaSession è un componente di sistema in Android che consente a un'app di dichiarare la propria attività multimediale e ricevere comandi di controllo da fonti esterne. Quando l'utente preme il pulsante Play su un auricolare Bluetooth, il sistema trasmette questo evento alla MediaSession attiva e l'app risponde tramite il suo Callback.

Prima di Android 5.0, RemoteControlClient veniva utilizzato per questo scopo, ma non forniva sufficiente flessibilità e non supportava scenari moderni come Android Auto, smartwatch e smart speaker. MediaSession è stato introdotto nell'API 21 ed è diventato lo standard de facto per tutte le app Android con riproduzione audio e video.

Secondo la documentazione per sviluppatori Android (2026), un'app dovrebbe creare una MediaSession per ogni sorgente di riproduzione indipendente. In qualsiasi momento, solo una sessione può essere attiva — qualsiasi nuova sessione disattiva automaticamente la precedente.

MediaSession e MediaBrowserService

La combinazione di MediaSession con MediaBrowserService fornisce un ciclo completo di gestione multimediale: il servizio fornisce un albero di contenuti (playlist, cataloghi) e la sessione accetta comandi di navigazione e riproduzione. Questa è l'architettura raccomandata da Google per lettori musicali, podcast e audiolibri.

MediaBrowserService viene eseguito come servizio in primo piano con una notifica, garantendo che l'app continui a funzionare anche quando l'Activity viene distrutta. Questo è fondamentale per i lettori audio che devono continuare a riprodurre quando l'app è minimizzata.

Come funziona MediaSession

La sessione supporta due tipi di interazione: riceve comandi da MediaController (il lato client) e trasmette lo stato tramite PlaybackState. MediaController può essere nello stesso processo o in un'app separata — il sistema instrada le richieste tramite SessionToken.

Quando l'utente chiama l'assistente vocale Android e dice “Riproduci il brano successivo”, il sistema trova la MediaSession attiva attraverso la connessione a MediaBrowserService e invia il comando ACTION_SKIP_TO_NEXT. Il Callback dell'app riceve la chiamata onSkipToNext() e aggiorna PlaybackState.

L'aggiornamento di PlaybackState tramite setPlaybackState() notifica immediatamente tutte le istanze MediaController connesse. Il centro multimediale di sistema, il dispositivo Bluetooth e Android Auto ricevono l'aggiornamento simultaneamente — il ritardo non supera i 50 ms in condizioni normali.

PlaybackState e i suoi metadati

PlaybackState contiene flag di stato chiave: isPlaying, posizione, velocità, azioni disponibili (play, pause, seek, stop). Senza un PlaybackState correttamente popolato, il sistema non sa quali comandi l'app supporta e non invia gli eventi corrispondenti.

I metadati (MediaMetadata) completano lo stato con informazioni sul brano corrente — titolo, artista, URI della copertina. Android Auto e gli smartwatch utilizzano MediaMetadata per visualizzare informazioni sullo schermo. Secondo Google I/O 2024, il corretto popolamento di MediaMetadata aumenta la visibilità dell'app nei launcher di terze parti del 40%.

Componenti chiave di MediaSession

L'architettura di MediaSession è composta da quattro componenti interconnessi, ciascuno con il proprio ruolo. Lo sviluppatore deve implementarli tutti e quattro per un'integrazione completa con il sistema.

• MediaSessionCompat — la classe principale della sessione, creata con un tag app e che accetta un PendingIntent per i pulsanti multimediali.
• MediaSession.Callback — il gestore dei comandi. Implementa onPlay, onPause, onSkipToNext, onSeekTo e altri metodi.
• PlaybackStateCompat — lo stato corrente del lettore. Contiene flag, posizione, velocità e l'elenco delle azioni disponibili.
• MediaMetadataCompat — metadati del contenuto multimediale corrente: titolo, artista, album, copertina, durata.

Ciclo di vita di MediaSession

La sessione viene creata nel metodo onCreate di un servizio o Activity chiamando MediaSessionCompat(context, tag). Dopo la creazione, è necessario chiamare setFlags(FLAG_HANDLES_MEDIA_BUTTONS | FLAG_HANDLES_TRANSPORT_CONTROLS). In onDestroy, viene chiamato release() per liberare le risorse di sistema.

Una gestione errata del ciclo di vita è uno degli errori più comuni. Se release() non viene chiamato, la sessione rimane nel sistema e l'app successiva potrebbe ricevere uno stato obsoleto. Android 13+ mostra un avviso Logcat per perdite di sessione.

Integrazione di MediaSession nell'app

L'integrazione di base inizia con la creazione di una sessione e l'implementazione di un Callback. Si consiglia di utilizzare MediaSessionCompat dalla libreria AndroidX media, che fornisce un'API unificata per tutte le versioni di Android — dall'API 14 alla 35.

Creazione di MediaSession e 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()
    }
}

In questo esempio, viene creata una MediaSession con il tag MusicService e flag per gestire i pulsanti multimediali. Il Callback implementa onPlay e onPause, aggiornando PlaybackState. Il metodo setActions dichiara le azioni disponibili che il sistema mostra sulla schermata di blocco e nel centro multimediale.

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

I metadati dovrebbero essere aggiornati a ogni cambio di brano. Il sistema utilizza METADATA_KEY_TITLE e METADATA_KEY_ARTIST per visualizzare informazioni sui display Bluetooth delle auto e sui dispositivi indossabili. Se l'URI della copertina non è impostato, il lettore mostrerà un segnaposto grigio.

Gestione dei comandi multimediali da Bluetooth e cuffie

I dispositivi Bluetooth inviano comandi tramite il profilo AVRCP 1.6+. Android trasmette questi comandi come intent ACTION_MEDIA_BUTTON, che vengono intercettati da MediaSession quando è impostato il flag FLAG_HANDLES_MEDIA_BUTTONS.

Quando l'utente preme il pulsante Play su cuffie Bluetooth, il sistema crea un KeyEvent con codice KEYCODE_MEDIA_PLAY, che viene inviato al metodo onMediaButtonEvent del Callback. Se onPlay() è implementato nel Callback, il sistema lo chiama direttamente. Una singola pressione del pulsante della cuffia invia KEYCODE_MEDIA_PLAY_PAUSE — il lettore deve alternare lo stato.

Gestione di scenari complessi con più pulsanti

Le cuffie Bluetooth moderne possono avere fino a 5 pulsanti: volume +/-, play/pause, next, previous. Ogni pulsante genera il proprio KeyEvent, che deve essere gestito correttamente dal Callback. Una doppia pressione di play/pause viene tipicamente interpretata come passaggio al brano successivo (ACTION_SKIP_TO_NEXT) su molte cuffie.

Secondo il Documento di Definizione di Compatibilità Android (2026), tutte le app con contenuti multimediali devono gestire correttamente KEYCODE_MEDIA_PLAY_PAUSE. Ignorare questo requisito porta a una diminuzione automatica della valutazione dell'app in Google Play per la categoria Musica e Audio.

Sincronizzazione con il centro multimediale di sistema

A partire da Android 11, il centro multimediale di sistema (Pannello di Controllo Multimediale) mostra fino a 5 sessioni recenti di MediaSession nel pannello delle notifiche. L'utente può controllare il lettore senza aprire l'app. Per una visualizzazione corretta, è necessario implementare MediaBrowserService e popolare correttamente PlaybackState.

Il Pannello di Controllo Multimediale mostra: titolo del brano, artista, copertina (da MediaMetadata), pulsanti di controllo (dalle azioni disponibili di PlaybackState). Se l'app non aggiorna PlaybackState almeno una volta ogni 10 secondi durante la riproduzione attiva, il centro multimediale nasconde la sessione dal pannello.

Servizio in primo piano con notifica

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

La notifica MediaStyle si collega a MediaSession tramite il sessionToken e mostra i pulsanti multimediali standard. Senza MediaStyle, la notifica apparirà come un avviso normale senza pulsanti di controllo. Android 13+ richiede l'autorizzazione esplicita POST_NOTIFICATIONS per la visualizzazione.