Переезжаем с ExoPlayer 2 на media3пакеты, DataSource и MediaSession без сюрпризов
ExoPlayer 2 больше не развивается, вся работа идёт в androidx.media3. Разбираем, что переименовать, что переписать руками и где миграция обычно спотыкается.
- Раздел
- Android
- Стек
- Kotlinmedia3ExoPlayerMediaSession
- Уровень
- Средний
- Опубликовано
- Обновлено
- Чтение
- 7 мин
- Последний релиз ExoPlayer 2 это 2.19.1, дальше только androidx.media3.
- Пакеты и классы переименовывает официальный скрипт media3-migration.sh.
- MediaSessionConnector убран: MediaSession из media3 принимает Player напрямую.
- Свой DataSource переносится почти без правок, но требует @OptIn(UnstableApi::class).
- Обновить проект до ExoPlayer 2.19.1 и убрать устаревшие вызовы
- Прогнать media3-migration.sh по корню Gradle-проекта
- Заменить StyledPlayerView на PlayerView в коде и XML
- Перевести MediaSessionConnector на MediaSession и MediaSessionService
- Разметить нестабильные API через @OptIn(UnstableApi::class)
Почему переезжать нужно сейчас#
ExoPlayer долго жил отдельным проектом в пространстве com.google.android.exoplayer2. В 2022 году команда перенесла его в Jetpack под именем androidx.media3, и с тех пор новые форматы, исправления и поддержку свежих версий Android получает только media3. Последняя версия старой ветки, 2.19.1, остаётся рабочей, но её никто не обновляет.
Если в проекте живёт код из нашей заметки про проигрывание зашифрованного видео в ExoPlayer, он тоже переезжает: идея с собственным DataSource остаётся, меняются импорты и пара деталей. Хорошая новость: публичный API плеера почти не изменился, ExoPlayer.Builder, MediaItem и Player.Listener выглядят так же.
Мы советуем двигаться в два шага. Сначала обновиться до 2.19.1 и убрать все предупреждения об устаревших методах: скрипт миграции рассчитан именно на эту версию. Потом уже переносить пакеты.
Отдельно оцените, сколько в проекте кода вокруг плеера: кастомные рендереры, свои LoadControl, обработчики ошибок, аналитика через AnalyticsListener. Чем больше расширений, тем больше мест, помеченных как нестабильный API, и тем дольше займёт ревью. Простой экран с одним видео обычно переносится за час, проект с офлайн-загрузкой и DRM за несколько дней.
Что переименовать: пакеты, артефакты, классы#
Основная работа механическая, и её делает официальный скрипт media3-migration.sh из репозитория ExoPlayer. Он умеет показать соответствие пакетов (флаг -p), список затрагиваемых файлов (-l) и выполнить замену (-m) в Gradle-файлах, исходниках на Java и Kotlin и XML-разметке. Перед запуском закоммитьте всё, чтобы диф был чистым.
| ExoPlayer 2 | media3 |
|---|---|
com.google.android.exoplayer2 | androidx.media3.exoplayer и androidx.media3.common |
com.google.android.exoplayer2.upstream | androidx.media3.datasource |
StyledPlayerView | PlayerView (androidx.media3.ui) |
модуль extension-mediasession | media3-session, класс MediaSession |
Зависимости тоже меняются. Вместо одного толстого артефакта подключайте только нужные модули:
dependencies {
val media3 = "1.x.y" // актуальную версию возьмите из release notes
implementation("androidx.media3:media3-exoplayer:$media3")
implementation("androidx.media3:media3-ui:$media3")
implementation("androidx.media3:media3-session:$media3")
// по необходимости: media3-exoplayer-hls, media3-exoplayer-dash
}Версию мы намеренно не пишем: смотрите актуальную в release notes media3 и держите все модули на одной версии, иначе возможны конфликты классов.
После прогона скрипта соберите проект и посмотрите на ошибки компиляции: обычно это классы, которые в media3 переименованы не только по пакету, и удалённые устаревшие методы. Устаревшие методы проще убрать ещё на 2.19.1, где у них есть подсказки в предупреждениях, чем потом искать замену по документации.
Код плеера до и после#
В простом сценарии разница сводится к импортам и медиасессии. Было:
// ExoPlayer 2.x
import com.google.android.exoplayer2.ExoPlayer
import com.google.android.exoplayer2.MediaItem
import com.google.android.exoplayer2.ui.StyledPlayerView
import com.google.android.exoplayer2.ext.mediasession.MediaSessionConnector
val player = ExoPlayer.Builder(context).build()
playerView.player = player
player.setMediaItem(MediaItem.fromUri(uri))
player.prepare()
val connector = MediaSessionConnector(mediaSessionCompat)
connector.setPlayer(player)Стало:
// androidx.media3
import androidx.media3.common.MediaItem
import androidx.media3.exoplayer.ExoPlayer
import androidx.media3.session.MediaSession
import androidx.media3.ui.PlayerView
val player = ExoPlayer.Builder(context).build()
playerView.player = player
player.setMediaItem(MediaItem.fromUri(uri))
player.prepare()
val session = MediaSession.Builder(context, player).build()
// в onDestroy: session.release(); player.release()Обратите внимание: MediaItem переехал в модуль common, потому что им пользуются и плеер, и сессия, и UI. Если раньше вы выносили поиск view по типу в отдельную утилиту (как в заметке про поиск дочерних View по классу), проверьте, что она ищет новый PlayerView, а не удалённый StyledPlayerView.
В XML-разметке замена тоже обязательна: тег com.google.android.exoplayer2.ui.StyledPlayerView превращается в androidx.media3.ui.PlayerView, а атрибуты вроде app:show_buffering и app:resize_mode сохраняют имена. Если вы стилизовали контролы через собственный layout exo_player_control_view, проверьте, что идентификаторы кнопок совпадают с теми, что ожидает новая версия, иначе часть кнопок молча перестанет работать.
DataSource: что поменялось#
Интерфейс DataSource по смыслу остался прежним: open(DataSpec), read(buffer, offset, length), getUri(), close(). Переехал он в androidx.media3.datasource, а большая часть классов этого пакета помечена аннотацией @UnstableApi. Это не значит, что код сломается, это предупреждение, что сигнатуры могут меняться между минорными версиями. Компилятор и lint потребуют явного согласия.
@OptIn(UnstableApi::class)
class CipherDataSource(
private val upstream: DataSource
) : BaseDataSource(/* isNetwork = */ false) {
override fun open(dataSpec: DataSpec): Long {
transferInitializing(dataSpec)
val length = upstream.open(dataSpec)
transferStarted(dataSpec)
return length
}
override fun read(buffer: ByteArray, offset: Int, length: Int): Int {
val read = upstream.read(buffer, offset, length)
if (read > 0) bytesTransferred(read)
return read // расшифровку вставляйте здесь
}
override fun getUri(): Uri? = upstream.uri
override fun close() {
upstream.close()
transferEnded()
}
}
class CipherFactory(private val upstream: DataSource.Factory) : DataSource.Factory {
override fun createDataSource(): DataSource = CipherDataSource(upstream.createDataSource())
}Что проверить при переносе:
- Колбэки
transferInitializing,transferStarted,bytesTransferred,transferEndedнужны, если вы подключаетеTransferListenerдля статистики. DefaultHttpDataSource.FactoryиDefaultDataSource.Factoryостались, но живут в новом пакете.- Фабрику своего источника передавайте через
DefaultMediaSourceFactory(dataSourceFactory)вExoPlayer.Builder.setMediaSourceFactory.
Для настоящей защиты контента клиентское AES-шифрование по-прежнему слабое место: ключ лежит в APK. Для платного видео смотрите в сторону Widevine, который media3 поддерживает штатно.
Аннотацию @OptIn(UnstableApi::class) можно ставить на класс, функцию или файл. В модуле, где работа с плеером сосредоточена в нескольких классах, удобнее помечать их целиком и держать список таких мест коротким. Тогда при следующем обновлении media3 сразу понятно, какой код читать в первую очередь вместе с release notes.
MediaSession вместо MediaSessionConnector#
Это единственная часть, где автоматическая замена не поможет. Модуль mediasession из ExoPlayer 2 в media3 не перенесён: его роль выполняет androidx.media3.session.MediaSession, который сам связывает плеер с системными контролами, Bluetooth-гарнитурой и уведомлением. MediaSessionCompat и коннектор можно удалить.
Для фонового воспроизведения наследуйтесь от MediaSessionService:
class PlaybackService : MediaSessionService() {
private var session: MediaSession? = null
override fun onCreate() {
super.onCreate()
val player = ExoPlayer.Builder(this).build()
session = MediaSession.Builder(this, player).build()
}
override fun onGetSession(controllerInfo: MediaSession.ControllerInfo) = session
override fun onDestroy() {
session?.run { player.release(); release() }
session = null
super.onDestroy()
}
}Сервис нужно объявить в манифесте с intent-filter androidx.media3.session.MediaSessionService и подходящим foregroundServiceType. Уведомление с кнопками media3 строит сам, своё писать не обязательно. UI-сторона подключается через MediaController, который создаётся по SessionToken.
Есть и приятный побочный эффект. Так как MediaSession в media3 принимает любой объект Player, сессия работает не только с ExoPlayer, но и с вашей обёрткой над ним, например с ForwardingPlayer, если нужно скрыть кнопку перемотки для рекламы или переопределить поведение команд. Раньше для этого приходилось настраивать коннектор отдельными провайдерами действий.
Что изменилось к 2026 году#
Коротко о том, что стоит держать в голове, планируя миграцию сейчас:
- Старые туториалы по ExoPlayer 2 по-прежнему полезны: логика плеера та же, меняйте только импорты.
- Если в UI проекта Compose, у media3 есть отдельный модуль с Compose-компонентами; классический
PlayerViewпри этом встраивается черезAndroidView. - Перед загрузкой обложек и превью не декодируйте картинки целиком: приёмы из заметки про размеры изображения без загрузки в память работают и рядом с плеером.
- Не подавляйте
@UnstableApiглобально без нужды: лучше помечать конкретные классы, тогда при обновлении видно, что пересматривать.
Другие заметки по платформе собраны в разделе Android.
«Миграция на media3 это в основном переименование. Руками переписывается только то, что касалось медиасессии.»
Главный вывод заметки


