MediaSession — ключови понятия, интеграция и механизъм на работа в Android

Какво е MediaSession?

MediaSession — е системен компонент на Android, който позволява на приложението да декларира своята медийна активност и да приема управляващи команди отвън. Когато потребителят натисне бутона Play на Bluetooth слушалка, системата предава това събитие на активната MediaSession, а приложението реагира чрез своя Callback.

Преди Android 5.0 за тези цели се използваше RemoteControlClient, но той не осигуряваше необходимата гъвкавост и не поддържаше съвременни сценарии — Android Auto, умни часовници, умни говорители. MediaSession беше въведен в API 21 и стана де факто стандарт за всички Android приложения с аудио и видео възпроизвеждане.

Според Android Developer Documentation (2026), приложението трябва да създаде една MediaSession за всеки независим източник на възпроизвеждане. В даден момент може да има само една активна сесия — всяка нова сесия автоматично деактивира предишната.

MediaSession и MediaBrowserService

Комбинацията от MediaSession с MediaBrowserService осигурява пълен цикъл на управление на медиите: услугата предоставя дърво на съдържанието (плейлисти, каталози), а сесията приема команди за навигация и възпроизвеждане. Това е архитектурата, препоръчана от Google за музикални плейъри, подкасти и аудиокниги.

MediaBrowserService работи като foreground-услуга с известие, което гарантира работа на приложението дори след убиване на Activity. Това е критично важно за аудио плейъри, които трябва да продължат възпроизвеждането, когато приложението е минимизирано.

Как работи MediaSession

Сесията поддържа два типа взаимодействие: приема команди от MediaController (клиентска страна) и излъчва състояние чрез PlaybackState. MediaController може да бъде в същия процес или в отделно приложение — системата насочва заявките чрез SessionToken.

Когато потребителят извика гласовия асистент на Android и каже „Пусни следващата песен“, системата намира активната MediaSession чрез връзката с MediaBrowserService и изпраща команда ACTION_SKIP_TO_NEXT. Callback-ът на приложението получава извикване onSkipToNext() и актуализира PlaybackState.

Актуализацията на PlaybackState чрез setPlaybackState() незабавно уведомява всички свързани MediaController. Системният медиен център, Bluetooth устройството и Android Auto получават актуализацията едновременно — закъснението не надвишава 50 ms при нормални условия.

PlaybackState и неговите метаданни

PlaybackState съдържа ключови флагове на състоянието: isPlaying, позиция, скорост, налични действия (play, pause, seek, stop). Без правилно попълнен PlaybackState системата не знае какви команди поддържа приложението и не изпраща съответните събития.

Метаданните (MediaMetadata) допълват състоянието с информация за текущата песен — title, artist, album art URI. Android Auto и носимите устройства използват MediaMetadata за показване на информация на екрана. Според Google I/O 2024, правилното попълване на MediaMetadata увеличава видимостта на приложението в външни стартери с 40%.

Ключови компоненти на MediaSession

Архитектурата на MediaSession се състои от четири взаимосвързани компонента, всеки от които решава своя задача. Разработчикът трябва да имплементира и четирите за пълна интеграция със системата.

• MediaSessionCompat — основният клас на сесията, създаден с таг на приложението и приемащ PendingIntent за медийни бутони.
• MediaSession.Callback — обработчик на команди. Имплементира onPlay, onPause, onSkipToNext, onSeekTo и други методи.
• PlaybackStateCompat — текущото състояние на плейъра. Съдържа флагове, позиция, скорост и списък на наличните действия.
• MediaMetadataCompat — метаданни на текущото медия: заглавие, изпълнител, албум, корица, продължителност.

Жизнен цикъл на MediaSession

Сесията се създава в onCreate на услугата или Activity чрез извикване на MediaSessionCompat(context, tag). След създаване задължително се извиква setFlags(FLAG_HANDLES_MEDIA_BUTTONS | FLAG_HANDLES_TRANSPORT_CONTROLS). В onDestroy се извиква release() за освобождаване на системни ресурси.

Неправилното управление на жизнения цикъл е една от честите грешки. Ако не се извика release(), сесията остава в системата и следващото приложение може да получи фалшиво състояние. Android 13+ показва предупреждение в Logcat при изтичане на сесии.

Интеграция на MediaSession в приложението

Основната интеграция започва със създаване на сесия и имплементиране на Callback. Препоръчва се използването на MediaSessionCompat от библиотеката AndroidX media, която осигурява единен API за всички версии на Android — от API 14 до 35.

Създаване на MediaSession и 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()
    }
}

В примера се създава MediaSession с таг MusicService и флагове за обработка на медийни бутони. Callback имплементира onPlay и onPause, актуализирайки PlaybackState. Методът setActions декларира наличните действия, които системата показва на заключения екран и в медийния център.

Настройка на 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)
}

Метаданните трябва да се актуализират при всяка смяна на песен. Системата използва METADATA_KEY_TITLE и METADATA_KEY_ARTIST за показване на информация на Bluetooth дисплеи на автомобили и носими устройства. Ако не се зададе URI на корицата, плейърът ще показва сив placeholder.

Обработка на медийни команди от Bluetooth и слушалки

Bluetooth слушалките изпращат команди чрез профил AVRCP 1.6+. Android предава тези команди в ACTION_MEDIA_BUTTON intent-ове, които се прихващат от MediaSession, когато е зададен флаг FLAG_HANDLES_MEDIA_BUTTONS.

Когато потребителят натисне бутона Play на Bluetooth слушалките, системата създава KeyEvent с код KEYCODE_MEDIA_PLAY, който се изпраща до метода onMediaButtonEvent на Callback-а. Ако в Callback-а е имплементиран onPlay(), системата го извиква директно. При единично натискане на бутона на слушалката се изпраща KEYCODE_MEDIA_PLAY_PAUSE — плейърът трябва да превключи състоянието.

Обработка на сложни сценарии с множество бутони

Съвременните Bluetooth слушалки могат да имат до 5 бутона: сила на звука +/-, play/pause, next, previous. Всеки бутон генерира свой KeyEvent, който трябва да бъде правилно обработен от Callback-а. Двойното натискане на play/pause обикновено се интерпретира като преминаване към следващата песен (ACTION_SKIP_TO_NEXT) на много слушалки.

Според Android Compatibility Definition Document (2026), всички приложения с медийно съдържание са задължени да обработват правилно KEYCODE_MEDIA_PLAY_PAUSE. Игнорирането на това изискване води до автоматично понижаване на рейтинга на приложението в Google Play за категория Музика и Аудио.

Синхронизация с системния медиен център

От Android 11 нататък, системният медиен център (Media Control Panel) показва до 5 скорошни MediaSession в панела за известия. Потребителят може да управлява плейъра без да отваря приложението. За правилно показване е необходимо да се имплементира MediaBrowserService и правилно да се попълва PlaybackState.

Media Control Panel показва: заглавие на песен, изпълнител, корица (от MediaMetadata), бутони за управление (от разрешените действия на PlaybackState). Ако приложението не актуализира PlaybackState поне веднъж на всеки 10 секунди по време на активно възпроизвеждане, медийният център скрива сесията от панела.

Foreground-услуга с известие

private fun startForegroundService() {
    val notification = NotificationCompat.Builder(this, "media_channel")
        .setSmallIcon(R.drawable.ic_play)
        .setContentTitle("В момента се възпроизвежда")
        .setContentText(currentTrackTitle)
        .setPriority(NotificationCompat.PRIORITY_LOW)
        .setStyle(
            androidx.media.app.NotificationCompat.MediaStyle()
                .setMediaSession(mediaSession.sessionToken)
        )
        .build()
    startForeground(1001, notification)
}

MediaStyle известието се свързва с MediaSession чрез sessionToken и показва стандартни медийни бутони. Без MediaStyle известието ще изглежда като обикновено предупреждение без бутони за управление. Android 13+ изисква изрично разрешение POST_NOTIFICATIONS за показване.