Переезжаем с ExoPlayer 2 на media3

Переезжаем с 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).
Как решаем
  1. Обновить проект до ExoPlayer 2.19.1 и убрать устаревшие вызовы
  2. Прогнать media3-migration.sh по корню Gradle-проекта
  3. Заменить StyledPlayerView на PlayerView в коде и XML
  4. Перевести MediaSessionConnector на MediaSession и MediaSessionService
  5. Разметить нестабильные 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 2media3
com.google.android.exoplayer2androidx.media3.exoplayer и androidx.media3.common
com.google.android.exoplayer2.upstreamandroidx.media3.datasource
StyledPlayerViewPlayerView (androidx.media3.ui)
модуль extension-mediasessionmedia3-session, класс MediaSession

Зависимости тоже меняются. Вместо одного толстого артефакта подключайте только нужные модули:

Kotlin
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, где у них есть подсказки в предупреждениях, чем потом искать замену по документации.

Код плеера до и после#

В простом сценарии разница сводится к импортам и медиасессии. Было:

Kotlin
// 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)

Стало:

Kotlin
// 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 потребуют явного согласия.

Kotlin
@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:

Kotlin
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 году#

Коротко о том, что стоит держать в голове, планируя миграцию сейчас:

  1. Старые туториалы по ExoPlayer 2 по-прежнему полезны: логика плеера та же, меняйте только импорты.
  2. Если в UI проекта Compose, у media3 есть отдельный модуль с Compose-компонентами; классический PlayerView при этом встраивается через AndroidView.
  3. Перед загрузкой обложек и превью не декодируйте картинки целиком: приёмы из заметки про размеры изображения без загрузки в память работают и рядом с плеером.
  4. Не подавляйте @UnstableApi глобально без нужды: лучше помечать конкретные классы, тогда при обновлении видно, что пересматривать.

Другие заметки по платформе собраны в разделе Android.

2.19.1последняя версия ExoPlayer 2
androidx.media3новое пространство пакетов
@UnstableApiаннотация для нестабильных API

«Миграция на media3 это в основном переименование. Руками переписывается только то, что касалось медиасессии.»

Главный вывод заметки

Вопросы и ответы

Вопросы и ответы

Можно ли оставить ExoPlayer 2 и ничего не менять?
Код продолжит работать, но обновлений, исправлений и поддержки новых версий Android ветка 2.x не получает. Чем дольше откладывать, тем больше накопится расхождений с документацией и примерами, поэтому переезд лучше запланировать.
Что делает скрипт media3-migration.sh?
Он заменяет пакеты, имена классов и Gradle-зависимости ExoPlayer 2 на эквиваленты media3 в исходниках Java и Kotlin, XML-разметке и build-файлах. Рассчитан на проект, уже обновлённый до ExoPlayer 2.19.1.
Зачем media3 требует @OptIn(UnstableApi::class)?
Так помечены API, сигнатуры которых могут меняться между версиями: многие классы DataSource, рендереры, расширенные настройки. Аннотация не меняет поведение, она лишь фиксирует, что вы осознанно используете нестабильную часть библиотеки.
Куда делся MediaSessionConnector?
Его больше нет. В media3 класс MediaSession сам принимает объект Player и связывает его с системными элементами управления. Для фонового воспроизведения используйте MediaSessionService, а UI подключайте через MediaController.
Заметка обновлена 12 ноября 2026: код проверен на актуальных версиях, добавлены современные варианты.

Читайте также