Руководство по миграции на AndroidX Media3

Приложения, которые в настоящее время используют автономную библиотеку com.google.android.exoplayer2 и androidx.media должны перейти на androidx.media3 . Используйте сценарий миграции для переноса файлов сборки Gradle, исходных файлов Java и Kotlin, а также файлов макета XML из ExoPlayer 2.19.1 в AndroidX Media3 1.1.1 .

Обзор

Прежде чем выполнять миграцию, просмотрите следующие разделы, чтобы узнать больше о преимуществах новых API, API-интерфейсах, подлежащих миграции, а также предварительных требованиях, которым должен соответствовать проект вашего приложения.

Зачем переходить на Jetpack Media3

  • Это новый дом ExoPlayer , тогда как com.google.android.exoplayer2 прекращена.
  • Получите доступ к API-интерфейсу проигрывателя через компоненты/процессы с помощью MediaBrowser / MediaController .
  • Используйте расширенные возможности API MediaSession и MediaController .
  • Рекламируйте возможности воспроизведения с помощью детального контроля доступа .
  • Упростите свое приложение , удалив MediaSessionConnector и PlayerNotificationManager .
  • Обратная совместимость с клиентскими API-интерфейсами медиа-совместимости ( MediaBrowserCompat / MediaControllerCompat / MediaMetadataCompat )

Медиа API для перехода на AndroidX Media3

  • ExoPlayer и его расширения
    Сюда входят все модули устаревшего проекта ExoPlayer, за исключением модуля mediasession , выпуск которого прекращен. Приложения или модули, зависящие от пакетов в com.google.android.exoplayer2 , можно перенести с помощью сценария миграции.
  • MediaSessionConnector (в зависимости от пакетов androidx.media.* androidx.media:media:1.4.3+ )
    Удалите MediaSessionConnector и вместо него используйте androidx.media3.session.MediaSession .
  • MediaBrowserServiceCompat (в зависимости от пакетов androidx.media.* androidx.media:media:1.4.3+ )
    Перенесите подклассы androidx.media.MediaBrowserServiceCompat в androidx.media3.session.MediaLibraryService и кодируйте с помощью MediaBrowserCompat.MediaItem в androidx.media3.common.MediaItem .
  • MediaBrowserCompat (в зависимости от пакетов android.support.v4.media.* androidx.media:media:1.4.3+ )
    Перенесите клиентский код с помощью MediaBrowserCompat или MediaControllerCompat чтобы использовать androidx.media3.session.MediaBrowser с androidx.media3.common.MediaItem .

Предварительные условия

  1. Убедитесь, что ваш проект находится под контролем исходного кода

    Убедитесь, что вы можете легко отменить изменения, внесенные с помощью скриптовых инструментов миграции. Если ваш проект еще не находится под контролем исходного кода, сейчас самое время начать с этого. Если по какой-то причине вы не хотите этого делать, перед началом миграции сделайте резервную копию проекта.

  2. Обновите свое приложение

    • Мы рекомендуем обновить ваш проект, чтобы использовать самую последнюю версию библиотеки ExoPlayer и удалить все вызовы устаревших методов. Если вы собираетесь использовать сценарий для миграции, вам необходимо сопоставить версию, которую вы обновляете, с версией, обрабатываемой сценарием.

    • Увеличьте значение compileSdkVersion вашего приложения как минимум до 32 .

    • Обновите Gradle и плагин Gradle для Android Studio до последней версии, которая работает с обновленными зависимостями, указанными выше. Например:

      • Версия плагина Android Gradle: 7.1.0
      • Версия Градла: 7.4

    • Замените все операторы импорта с подстановочными знаками , в которых используется звездочка (*), и используйте полные операторы импорта. Удалите операторы импорта с подстановочными знаками и используйте Android Studio для импорта полных операторов (F2 — Alt/Enter, F2 — Alt/Enter,...).

    • Перейдите с com.google.android.exoplayer2.PlayerView на com.google.android.exoplayer2.StyledPlayerView . Это необходимо, поскольку в AndroidX Media3 нет эквивалента com.google.android.exoplayer2.PlayerView .

Миграция ExoPlayer с поддержкой сценариев

Скрипт облегчает переход от com.google.android.exoplayer2 к новой структуре пакета и модуля под androidx.media3 . Сценарий применяет некоторые проверки вашего проекта и печатает предупреждения в случае неудачной проверки. В противном случае он применяет сопоставления переименованных классов и пакетов в ресурсах проекта Android Gradle, написанного на Java или Kotlin.

usage: ./media3-migration.sh [-p|-c|-d|-v]|[-m|-l [-x <path>] [-f] PROJECT_ROOT]
 PROJECT_ROOT: path to your project root (location of 'gradlew')
 -p: list package mappings and then exit
 -c: list class mappings (precedence over package mappings) and then exit
 -d: list dependency mappings and then exit
 -l: list files that will be considered for rewrite and then exit
 -x: exclude the path from the list of file to be changed: 'app/src/test'
 -m: migrate packages, classes and dependencies to AndroidX Media3
 -f: force the action even when validation fails
 -v: print the exoplayer2/media3 version strings of this script
 -h, --help: show this help text

Использование сценария миграции

  1. Загрузите сценарий миграции из тега проекта ExoPlayer на GitHub, соответствующего версии, до которой вы обновили свое приложение:

    curl -o media3-migration.sh \
  "https://raw.githubusercontent.com/google/ExoPlayer/r2.19.1/media3-migration.sh"

  2. Сделайте скрипт исполняемым:

    chmod 744 media3-migration.sh

  3. Запустите сценарий с --help , чтобы узнать о параметрах.

  4. Запустите сценарий с -l , чтобы просмотреть набор файлов, выбранных для миграции (используйте -f , чтобы вывести список без предупреждений):

    ./media3-migration.sh -l -f /path/to/gradle/project/root

  5. Запустите сценарий с -m , чтобы сопоставить пакеты, классы и модули с Media3. Запуск сценария с опцией -m применит изменения к выбранным файлам.

    • Остановиться при ошибке проверки без внесения изменений 
    ./media3-migration.sh -m /path/to/gradle/project/root
    • Принудительное исполнение

    Если сценарий обнаружит нарушение предварительных условий, миграцию можно запустить принудительно с помощью флага -f :

    ./media3-migration.sh -m -f /path/to/gradle/project/root

 # list files selected for migration when excluding paths
 ./media3-migration.sh -l -x "app/src/test/" -x "service/" /path/to/project/root
 # migrate the selected files
 ./media3-migration.sh -m -x "app/src/test/" -x "service/" /path/to/project/root

Выполните эти действия вручную после запуска сценария с опцией -m :

  1. Проверьте, как сценарий изменил ваш код : используйте инструмент сравнения и исправьте потенциальные проблемы (подумайте о том, чтобы сообщить об ошибке, если вы считаете, что в сценарии есть общая проблема, которая возникла без передачи опции -f ).
  2. Создайте проект : либо используйте ./gradlew clean build , либо в Android Studio выберите «Файл» > «Синхронизировать проект с файлами Gradle» , затем «Создать» > «Очистить проект» , а затем «Создать» > «Перестроить проект » (отслеживайте свою сборку на вкладке «Сборка – Вывод сборки» в Android Studio) .

Рекомендуемые последующие действия:

  1. Устраните ошибки, связанные с использованием нестабильных API .
  2. Заменить устаревшие вызовы API . Используйте предложенный API замены. Наведите указатель на предупреждение в Android Studio и обратитесь к JavaDoc устаревшего символа, чтобы узнать, что использовать вместо данного вызова.
  3. Сортировка операторов импорта . Откройте проект в Android Studio, затем щелкните правой кнопкой мыши узел папки пакета в средстве просмотра проекта и выберите «Оптимизировать импорт пакетов, содержащих измененные исходные файлы».

Замените MediaSessionConnector на androidx.media3.session.MediaSession

В устаревшем мире MediaSessionCompat MediaSessionConnector отвечал за синхронизацию состояния проигрывателя с состоянием сеанса и получение команд от контроллеров, которым требовалось делегирование соответствующим методам проигрывателя. В AndroidX Media3 это выполняется напрямую с помощью MediaSession , без необходимости подключения.

  1. Удалите все ссылки и использование MediaSessionConnector. Если вы использовали автоматизированный сценарий для миграции классов и пакетов ExoPlayer, то сценарий, скорее всего, оставил ваш код в некомпилируемом состоянии относительно MediaSessionConnector , которое невозможно разрешить. Android Studio покажет вам неработающий код, когда вы попытаетесь собрать или запустить приложение.

  2. В файле build.gradle , где вы сохраняете свои зависимости, добавьте зависимость реализации к модулю сеанса AndroidX Media3 и удалите устаревшую зависимость:

    implementation "androidx.media3:media3-session:1.6.0"

  3. Замените MediaSessionCompat на androidx.media3.session.MediaSession .

  4. На сайте кода, где вы создали устаревший MediaSessionCompat , используйте androidx.media3.session.MediaSession.Builder для создания MediaSession . Передайте игроку , чтобы построить построитель сеансов.

    val player = ExoPlayer.Builder(context).build()
mediaSession = MediaSession.Builder(context, player)
    .setSessionCallback(MySessionCallback())
    .build()

  5. Реализуйте MySessionCallback в соответствии с требованиями вашего приложения. Это необязательно. Если вы хотите разрешить контроллерам добавлять элементы мультимедиа в проигрыватель, реализуйте MediaSession.Callback.onAddMediaItems() . Он обслуживает различные текущие и устаревшие методы API, которые добавляют элементы мультимедиа в проигрыватель для воспроизведения с обратной совместимостью. Сюда входят методы MediaController.set/addMediaItems() контроллера Media3, а также методы TransportControls.prepareFrom*/playFrom* устаревшего API. Пример реализации onAddMediaItems можно найти в PlaybackService демонстрационного приложения сеанса .

  6. Освободите сеанс мультимедиа на сайте кода, где вы уничтожили сеанс перед миграцией: 

    mediaSession?.run {
  player.release()
  release()
  mediaSession = null
}

Функциональность MediaSessionConnector в Media3

В следующей таблице показаны API-интерфейсы Media3, которые обрабатывают функции, ранее реализованные в MediaSessionConnector .

Медиасессионконнектор AndroidX Media3
CustomActionProvider MediaSession.Callback.onCustomCommand()/ MediaSession.setMediaButtonPreferences()
PlaybackPreparer MediaSession.Callback.onAddMediaItems() ( prepare() вызывается внутри)
QueueNavigator ForwardingSimpleBasePlayer
QueueEditor MediaSession.Callback.onAddMediaItems()
RatingCallback MediaSession.Callback.onSetRating()
PlayerNotificationManager DefaultMediaNotificationProvider/ MediaNotification.Provider

Миграция MediaBrowserService в MediaLibraryService

AndroidX Media3 представляет MediaLibraryService , который заменяет MediaBrowserServiceCompat . JavaDoc MediaLibraryService и его суперкласс MediaSessionService обеспечивают хорошее введение в API и модель асинхронного программирования службы.

MediaLibraryService обратно совместим с MediaBrowserService . Клиентское приложение, использующее MediaBrowserCompat или MediaControllerCompat , продолжает работать без изменений кода при подключении к MediaLibraryService . Для клиента ясно, использует ли ваше приложение MediaLibraryService или устаревший MediaBrowserServiceCompat .

Диаграмма компонентов приложения со службой, активностью и внешними приложениями.
Рисунок 1. Обзор компонента медиа-приложения.

  1. Чтобы обратная совместимость работала, вам необходимо зарегистрировать оба интерфейса службы с вашей службой в AndroidManifest.xml . Таким образом клиент находит ваш сервис по нужному сервисному интерфейсу: 

    <service android:name=".MusicService" android:exported="true">
    <intent-filter>
        <action android:name="androidx.media3.session.MediaLibraryService"/>
        <action android:name="android.media.browse.MediaBrowserService" />
    </intent-filter>
</service>

  2. В файле build.gradle , где вы сохраняете свои зависимости, добавьте зависимость реализации к модулю сеанса AndroidX Media3 и удалите устаревшую зависимость: 

    implementation "androidx.media3:media3-session:1.6.0"

  3. Измените свой сервис, чтобы он наследовался от MediaLibraryService вместо MediaBrowserService Как было сказано ранее, MediaLibraryService совместим с устаревшим MediaBrowserService . Соответственно, более широкий API, который сервис предлагает клиентам, остался прежним. Поэтому вполне вероятно, что приложение сможет сохранить большую часть логики, необходимой для реализации MediaBrowserService , и адаптировать ее для нового MediaLibraryService .

    Основные отличия от устаревшего MediaBrowserServiceCompat заключаются в следующем:

    • Реализуйте методы жизненного цикла службы. Методы, которые необходимо переопределить в самой службе, — это onCreate/onDestroy , где приложение выделяет/освобождает сеанс библиотеки, проигрыватель и другие ресурсы. В дополнение к стандартным методам жизненного цикла службы приложению необходимо переопределить onGetSession(MediaSession.ControllerInfo) чтобы вернуть MediaLibrarySession , встроенный в onCreate .

    • Реализуйте MediaLibraryService.MediaLibrarySessionCallback: для создания сеанса требуется MediaLibraryService.MediaLibrarySessionCallback , который реализует фактические методы API домена. Таким образом, вместо переопределения методов API устаревшей службы вы переопределите методы MediaLibrarySession.Callback .

      Затем обратный вызов используется для создания MediaLibrarySession : 

      mediaLibrarySession =
      MediaLibrarySession.Builder(this, player, MySessionCallback())
         .build()

      Полный API MediaLibrarySessionCallback можно найти в документации API.

    • Реализуйте MediaSession.Callback.onAddMediaItems() : обратный вызов onAddMediaItems(MediaSession, ControllerInfo, List<MediaItem>) обслуживает различные текущие и устаревшие методы API, которые добавляют элементы мультимедиа в проигрыватель для воспроизведения обратно совместимым способом. Сюда входят методы MediaController.set/addMediaItems() контроллера Media3, а также методы TransportControls.prepareFrom*/playFrom* устаревшего API. Пример реализации обратного вызова можно найти в PlaybackService демонстрационного приложения сеанса .

    • AndroidX Media3 использует androidx.media3.common.MediaItem вместо MediaBrowserCompat.MediaItem и MediaMetadataCompat . Части вашего кода, связанные с устаревшими классами, необходимо соответствующим образом изменить или вместо этого сопоставить с Media3 MediaItem .

    • Общая модель асинхронного программирования изменилась на Futures в отличие от подхода с отделяемым Result MediaBrowserServiceCompat . Реализация вашего сервиса может возвращать асинхронный ListenableFuture вместо отсоединения результата или возвращать немедленный Future для прямого возврата значения .

Удалить PlayerNotificationManager

MediaLibraryService автоматически поддерживает мультимедийные уведомления , а PlayerNotificationManager можно удалить при использовании MediaLibraryService или MediaSessionService .

Приложение может настроить уведомление , установив пользовательский MediaNotification.Provider в onCreate() , который заменяет DefaultMediaNotificationProvider . Затем MediaLibraryService по мере необходимости позаботится о запуске службы на переднем плане.

Переопределяя MediaLibraryService.updateNotification() приложение может дополнительно взять на себя полную ответственность за публикацию уведомления и запуск/остановку службы на переднем плане по мере необходимости.

Перенос клиентского кода с помощью MediaBrowser

В AndroidX Media3 MediaBrowser реализует интерфейсы MediaController/Player и может использоваться для управления воспроизведением мультимедиа, помимо просмотра медиатеки. Если вам нужно было создать MediaBrowserCompat и MediaControllerCompat в устаревшем мире, вы можете сделать то же самое, используя только MediaBrowser в Media3.

MediaBrowser можно создать и дождаться установления соединения с устанавливаемым сервисом: 

scope.launch {
    val sessionToken =
        SessionToken(context, ComponentName(context, MusicService::class.java)
    browser =
        MediaBrowser.Builder(context, sessionToken))
            .setListener(BrowserListener())
            .buildAsync()
            .await()
    // Get the library root to start browsing the library.
    root = browser.getLibraryRoot(/* params= */ null).await();
    // Add a MediaController.Listener to listen to player state events.
    browser.addListener(playerListener)
    playerView.setPlayer(browser)
}

Ознакомьтесь с разделом Управление воспроизведением в сеансе мультимедиа , чтобы узнать, как создать MediaController для управления воспроизведением в фоновом режиме.

Дальнейшие действия и очистка

Нестабильные ошибки API

После перехода на Media3 вы можете увидеть ошибки, связанные с нестабильным использованием API. Эти API безопасны в использовании, а ошибки lint являются побочным продуктом наших новых гарантий двоичной совместимости. Если вам не требуется строгая двоичная совместимость, эти ошибки можно безопасно подавить с помощью аннотации @OptIn .

Фон

Ни ExoPlayer v1, ни v2 не давали строгих гарантий бинарной совместимости библиотеки между последующими версиями. Поверхность API ExoPlayer по своей конструкции очень велика, что позволяет приложениям настраивать практически каждый аспект воспроизведения. В последующих версиях ExoPlayer время от времени вносились переименования символов или другие критические изменения (например, новые обязательные методы в интерфейсах). В большинстве случаев эти поломки были устранены путем введения нового символа наряду с прекращением поддержки старого символа в нескольких версиях, чтобы дать разработчикам время на миграцию их использования, но это не всегда было возможно.

Эти критические изменения привели к двум проблемам для пользователей библиотек ExoPlayer v1 и v2:

  1. Обновление до версии ExoPlayer может привести к остановке компиляции кода.
  2. Приложение, которое зависело от ExoPlayer как напрямую, так и через промежуточную библиотеку, должно было гарантировать, что обе зависимости имеют одну и ту же версию, иначе двоичная несовместимость могла привести к сбоям во время выполнения.

Улучшения в Media3

Media3 гарантирует двоичную совместимость для части поверхности API. Части, которые не гарантируют двоичную совместимость, помечены @UnstableApi . Чтобы прояснить это различие, использование нестабильных символов API генерирует ошибку ворса, если они не помечены @OptIn .

После перехода с ExoPlayer v2 на Media3 вы можете увидеть множество нестабильных ошибок проверки API. Из-за этого может показаться, что Media3 «менее стабилен», чем ExoPlayer v2. Это не так. «Нестабильные» части API Media3 имеют тот же уровень стабильности, что и вся поверхность API ExoPlayer v2, а гарантии стабильной поверхности API Media3 вообще недоступны в ExoPlayer v2. Разница лишь в том, что ошибка ворса теперь предупреждает вас о различных уровнях стабильности.

Обработка нестабильных ошибок API

См. раздел устранения неполадок, посвященный этим ошибкам lint, для получения подробной информации о том, как аннотировать использование нестабильных API в Java и Kotlin с помощью @OptIn .

Устаревшие API

Вы можете заметить, что вызовы устаревших API в Android Studio перечеркнуты. Мы рекомендуем заменить такие вызовы соответствующей альтернативой. Наведите указатель мыши на символ, чтобы просмотреть документ JavaDoc, в котором указано, какой API использовать вместо этого.

Снимок экрана: как отобразить JavaDoc с альтернативой устаревшего метода
Рисунок 3. Подсказка JavaDoc в Android Studio предлагает альтернативу любому устаревшему символу.

Примеры кода и демонстрационные приложения

  • Демо-приложение сеанса AndroidX Media3 (мобильное устройство и WearOS)
    • Пользовательские действия
    • Уведомление системного интерфейса, MediaButton/BT
    • Google Ассистент управления воспроизведением
  • UAMP: Android Media Player (ветвь media3) (мобильный, AutomotiveOS)
    • Уведомление системного интерфейса, MediaButton/BT, возобновление воспроизведения
    • Управление воспроизведением Google Assistant/WearOS
    • AutomotiveOS: пользовательская команда и вход в систему
,

Приложения, которые в настоящее время используют автономную библиотеку com.google.android.exoplayer2 и androidx.media должны перейти на androidx.media3 . Используйте сценарий миграции для переноса файлов сборки Gradle, исходных файлов Java и Kotlin, а также файлов макета XML из ExoPlayer 2.19.1 в AndroidX Media3 1.1.1 .

Обзор

Прежде чем выполнять миграцию, просмотрите следующие разделы, чтобы узнать больше о преимуществах новых API, API-интерфейсах, подлежащих миграции, а также предварительных требованиях, которым должен соответствовать проект вашего приложения.

Зачем переходить на Jetpack Media3

  • Это новый дом ExoPlayer , тогда как com.google.android.exoplayer2 прекращена.
  • Получите доступ к API-интерфейсу проигрывателя через компоненты/процессы с помощью MediaBrowser / MediaController .
  • Используйте расширенные возможности API MediaSession и MediaController .
  • Рекламируйте возможности воспроизведения с помощью детального контроля доступа .
  • Упростите свое приложение , удалив MediaSessionConnector и PlayerNotificationManager .
  • Обратная совместимость с клиентскими API-интерфейсами медиа-совместимости ( MediaBrowserCompat / MediaControllerCompat / MediaMetadataCompat )

Медиа API для перехода на AndroidX Media3

  • ExoPlayer и его расширения
    Сюда входят все модули устаревшего проекта ExoPlayer, за исключением модуля mediasession , выпуск которого прекращен. Приложения или модули, зависящие от пакетов в com.google.android.exoplayer2 , можно перенести с помощью сценария миграции.
  • MediaSessionConnector (в зависимости от пакетов androidx.media.* androidx.media:media:1.4.3+ )
    Удалите MediaSessionConnector и вместо него используйте androidx.media3.session.MediaSession .
  • MediaBrowserServiceCompat (в зависимости от пакетов androidx.media.* androidx.media:media:1.4.3+ )
    Перенесите подклассы androidx.media.MediaBrowserServiceCompat в androidx.media3.session.MediaLibraryService и кодируйте с помощью MediaBrowserCompat.MediaItem в androidx.media3.common.MediaItem .
  • MediaBrowserCompat (в зависимости от пакетов android.support.v4.media.* androidx.media:media:1.4.3+ )
    Перенесите клиентский код с помощью MediaBrowserCompat или MediaControllerCompat чтобы использовать androidx.media3.session.MediaBrowser с androidx.media3.common.MediaItem .

Предварительные условия

  1. Убедитесь, что ваш проект находится под контролем исходного кода

    Убедитесь, что вы можете легко отменить изменения, внесенные с помощью скриптовых инструментов миграции. Если ваш проект еще не находится под контролем исходного кода, сейчас самое время начать с этого. Если по какой-то причине вы не хотите этого делать, перед началом миграции сделайте резервную копию проекта.

  2. Обновите свое приложение

    • Мы рекомендуем обновить ваш проект, чтобы использовать самую последнюю версию библиотеки ExoPlayer и удалить все вызовы устаревших методов. Если вы собираетесь использовать сценарий для миграции, вам необходимо сопоставить версию, которую вы обновляете, с версией, обрабатываемой сценарием.

    • Увеличьте значение compileSdkVersion вашего приложения как минимум до 32 .

    • Обновите Gradle и плагин Gradle для Android Studio до последней версии, которая работает с обновленными зависимостями, указанными выше. Например:

      • Версия плагина Android Gradle: 7.1.0
      • Версия Градла: 7.4

    • Замените все операторы импорта с подстановочными знаками , в которых используется звездочка (*), и используйте полные операторы импорта. Удалите операторы импорта с подстановочными знаками и используйте Android Studio для импорта полных операторов (F2 — Alt/Enter, F2 — Alt/Enter,...).

    • Перейдите с com.google.android.exoplayer2.PlayerView на com.google.android.exoplayer2.StyledPlayerView . Это необходимо, поскольку в AndroidX Media3 нет эквивалента com.google.android.exoplayer2.PlayerView .

Миграция ExoPlayer с поддержкой сценариев

Скрипт облегчает переход от com.google.android.exoplayer2 к новой структуре пакета и модуля под androidx.media3 . Сценарий применяет некоторые проверки вашего проекта и печатает предупреждения в случае неудачной проверки. В противном случае он применяет сопоставления переименованных классов и пакетов в ресурсах проекта Android Gradle, написанного на Java или Kotlin.

usage: ./media3-migration.sh [-p|-c|-d|-v]|[-m|-l [-x <path>] [-f] PROJECT_ROOT]
 PROJECT_ROOT: path to your project root (location of 'gradlew')
 -p: list package mappings and then exit
 -c: list class mappings (precedence over package mappings) and then exit
 -d: list dependency mappings and then exit
 -l: list files that will be considered for rewrite and then exit
 -x: exclude the path from the list of file to be changed: 'app/src/test'
 -m: migrate packages, classes and dependencies to AndroidX Media3
 -f: force the action even when validation fails
 -v: print the exoplayer2/media3 version strings of this script
 -h, --help: show this help text

Использование сценария миграции

  1. Загрузите сценарий миграции из тега проекта ExoPlayer на GitHub, соответствующего версии, до которой вы обновили свое приложение:

    curl -o media3-migration.sh \
  "https://raw.githubusercontent.com/google/ExoPlayer/r2.19.1/media3-migration.sh"

  2. Сделайте скрипт исполняемым:

    chmod 744 media3-migration.sh

  3. Запустите сценарий с --help , чтобы узнать о параметрах.

  4. Запустите сценарий с -l , чтобы просмотреть набор файлов, выбранных для миграции (используйте -f , чтобы вывести список без предупреждений):

    ./media3-migration.sh -l -f /path/to/gradle/project/root

  5. Запустите сценарий с -m , чтобы сопоставить пакеты, классы и модули с Media3. Запуск сценария с опцией -m применит изменения к выбранным файлам.

    • Остановиться при ошибке проверки без внесения изменений 
    ./media3-migration.sh -m /path/to/gradle/project/root
    • Принудительное исполнение

    Если сценарий обнаружит нарушение предварительных условий, миграцию можно запустить принудительно с помощью флага -f :

    ./media3-migration.sh -m -f /path/to/gradle/project/root

 # list files selected for migration when excluding paths
 ./media3-migration.sh -l -x "app/src/test/" -x "service/" /path/to/project/root
 # migrate the selected files
 ./media3-migration.sh -m -x "app/src/test/" -x "service/" /path/to/project/root

Выполните эти действия вручную после запуска сценария с опцией -m :

  1. Проверьте, как сценарий изменил ваш код : используйте инструмент сравнения и исправьте потенциальные проблемы (подумайте о том, чтобы сообщить об ошибке, если вы считаете, что в сценарии есть общая проблема, которая возникла без передачи опции -f ).
  2. Создайте проект : либо используйте ./gradlew clean build , либо в Android Studio выберите «Файл» > «Синхронизировать проект с файлами Gradle» , затем «Создать» > «Очистить проект» , а затем «Создать» > «Перестроить проект » (отслеживайте свою сборку на вкладке «Сборка – Вывод сборки» в Android Studio) .

Рекомендуемые последующие действия:

  1. Устраните ошибки, связанные с использованием нестабильных API .
  2. Заменить устаревшие вызовы API . Используйте предложенный API замены. Наведите указатель на предупреждение в Android Studio и обратитесь к JavaDoc устаревшего символа, чтобы узнать, что использовать вместо данного вызова.
  3. Сортировка операторов импорта . Откройте проект в Android Studio, затем щелкните правой кнопкой мыши узел папки пакета в средстве просмотра проекта и выберите «Оптимизировать импорт пакетов, содержащих измененные исходные файлы».

Замените MediaSessionConnector на androidx.media3.session.MediaSession

В устаревшем мире MediaSessionCompat MediaSessionConnector отвечал за синхронизацию состояния проигрывателя с состоянием сеанса и получение команд от контроллеров, которым требовалось делегирование соответствующим методам проигрывателя. В AndroidX Media3 это выполняется напрямую с помощью MediaSession , без необходимости подключения.

  1. Удалите все ссылки и использование MediaSessionConnector. Если вы использовали автоматизированный сценарий для миграции классов и пакетов ExoPlayer, то сценарий, скорее всего, оставил ваш код в некомпилируемом состоянии относительно MediaSessionConnector , которое невозможно разрешить. Android Studio покажет вам неработающий код, когда вы попытаетесь собрать или запустить приложение.

  2. В файле build.gradle , где вы сохраняете свои зависимости, добавьте зависимость реализации к модулю сеанса AndroidX Media3 и удалите устаревшую зависимость:

    implementation "androidx.media3:media3-session:1.6.0"

  3. Замените MediaSessionCompat на androidx.media3.session.MediaSession .

  4. На сайте кода, где вы создали устаревший MediaSessionCompat , используйте androidx.media3.session.MediaSession.Builder для создания MediaSession . Передайте игроку , чтобы построить построитель сеансов.

    val player = ExoPlayer.Builder(context).build()
mediaSession = MediaSession.Builder(context, player)
    .setSessionCallback(MySessionCallback())
    .build()

  5. Реализуйте MySessionCallback в соответствии с требованиями вашего приложения. Это необязательно. Если вы хотите разрешить контроллерам добавлять элементы мультимедиа в проигрыватель, реализуйте MediaSession.Callback.onAddMediaItems() . Он обслуживает различные текущие и устаревшие методы API, которые добавляют элементы мультимедиа в проигрыватель для воспроизведения с обратной совместимостью. Сюда входят методы MediaController.set/addMediaItems() контроллера Media3, а также методы TransportControls.prepareFrom*/playFrom* устаревшего API. Пример реализации onAddMediaItems можно найти в PlaybackService демонстрационного приложения сеанса .

  6. Освободите сеанс мультимедиа на сайте кода, где вы уничтожили сеанс перед миграцией: 

    mediaSession?.run {
  player.release()
  release()
  mediaSession = null
}

Функциональность MediaSessionConnector в Media3

В следующей таблице показаны API-интерфейсы Media3, которые обрабатывают функции, ранее реализованные в MediaSessionConnector .

Медиасессионконнектор AndroidX Media3
CustomActionProvider MediaSession.Callback.onCustomCommand()/ MediaSession.setMediaButtonPreferences()
PlaybackPreparer MediaSession.Callback.onAddMediaItems() ( prepare() вызывается внутри)
QueueNavigator ForwardingSimpleBasePlayer
QueueEditor MediaSession.Callback.onAddMediaItems()
RatingCallback MediaSession.Callback.onSetRating()
PlayerNotificationManager DefaultMediaNotificationProvider/ MediaNotification.Provider

Миграция MediaBrowserService в MediaLibraryService

AndroidX Media3 представляет MediaLibraryService , который заменяет MediaBrowserServiceCompat . JavaDoc MediaLibraryService и его суперкласс MediaSessionService обеспечивают хорошее введение в API и модель асинхронного программирования службы.

MediaLibraryService обратно совместим с MediaBrowserService . Клиентское приложение, использующее MediaBrowserCompat или MediaControllerCompat , продолжает работать без изменений кода при подключении к MediaLibraryService . Для клиента ясно, использует ли ваше приложение MediaLibraryService или устаревший MediaBrowserServiceCompat .

Диаграмма компонентов приложения со службой, активностью и внешними приложениями.
Рисунок 1. Обзор компонента медиа-приложения.

  1. Чтобы обратная совместимость работала, вам необходимо зарегистрировать оба интерфейса службы с вашей службой в AndroidManifest.xml . Таким образом клиент находит ваш сервис по нужному сервисному интерфейсу: 

    <service android:name=".MusicService" android:exported="true">
    <intent-filter>
        <action android:name="androidx.media3.session.MediaLibraryService"/>
        <action android:name="android.media.browse.MediaBrowserService" />
    </intent-filter>
</service>

  2. В файле build.gradle , где вы сохраняете свои зависимости, добавьте зависимость реализации к модулю сеанса AndroidX Media3 и удалите устаревшую зависимость: 

    implementation "androidx.media3:media3-session:1.6.0"

  3. Измените свой сервис, чтобы он наследовался от MediaLibraryService вместо MediaBrowserService Как было сказано ранее, MediaLibraryService совместим с устаревшим MediaBrowserService . Соответственно, более широкий API, который сервис предлагает клиентам, остался прежним. Поэтому вполне вероятно, что приложение сможет сохранить большую часть логики, необходимой для реализации MediaBrowserService , и адаптировать ее для нового MediaLibraryService .

    Основные отличия от устаревшего MediaBrowserServiceCompat заключаются в следующем:

    • Реализуйте методы жизненного цикла службы. Методы, которые необходимо переопределить в самой службе, — это onCreate/onDestroy , где приложение выделяет/освобождает сеанс библиотеки, проигрыватель и другие ресурсы. В дополнение к стандартным методам жизненного цикла службы приложению необходимо переопределить onGetSession(MediaSession.ControllerInfo) чтобы вернуть MediaLibrarySession , встроенный в onCreate .

    • Реализуйте MediaLibraryService.MediaLibrarySessionCallback: для создания сеанса требуется MediaLibraryService.MediaLibrarySessionCallback , который реализует фактические методы API домена. Таким образом, вместо переопределения методов API устаревшей службы вы переопределите методы MediaLibrarySession.Callback .

      Затем обратный вызов используется для создания MediaLibrarySession : 

      mediaLibrarySession =
      MediaLibrarySession.Builder(this, player, MySessionCallback())
         .build()

      Полный API MediaLibrarySessionCallback можно найти в документации API.

    • Реализуйте MediaSession.Callback.onAddMediaItems() : обратный вызов onAddMediaItems(MediaSession, ControllerInfo, List<MediaItem>) обслуживает различные текущие и устаревшие методы API, которые добавляют элементы мультимедиа в проигрыватель для воспроизведения обратно совместимым способом. Сюда входят методы MediaController.set/addMediaItems() контроллера Media3, а также методы TransportControls.prepareFrom*/playFrom* устаревшего API. Пример реализации обратного вызова можно найти в PlaybackService демонстрационного приложения сеанса .

    • AndroidX Media3 использует androidx.media3.common.MediaItem вместо MediaBrowserCompat.MediaItem и MediaMetadataCompat . Части вашего кода, связанные с устаревшими классами, необходимо соответствующим образом изменить или вместо этого сопоставить с Media3 MediaItem .

    • Общая модель асинхронного программирования изменилась на Futures в отличие от подхода с отделяемым Result MediaBrowserServiceCompat . Реализация вашего сервиса может возвращать асинхронный ListenableFuture вместо отсоединения результата или возвращать немедленный Future для прямого возврата значения .

Удалить PlayerNotificationManager

MediaLibraryService автоматически поддерживает мультимедийные уведомления , а PlayerNotificationManager можно удалить при использовании MediaLibraryService или MediaSessionService .

Приложение может настроить уведомление , установив пользовательский MediaNotification.Provider в onCreate() , который заменяет DefaultMediaNotificationProvider . Затем MediaLibraryService по мере необходимости позаботится о запуске службы на переднем плане.

Переопределяя MediaLibraryService.updateNotification() приложение может дополнительно взять на себя полную ответственность за публикацию уведомления и запуск/остановку службы на переднем плане по мере необходимости.

Перенос клиентского кода с помощью MediaBrowser

В AndroidX Media3 MediaBrowser реализует интерфейсы MediaController/Player и может использоваться для управления воспроизведением мультимедиа, помимо просмотра медиатеки. Если вам нужно было создать MediaBrowserCompat и MediaControllerCompat в устаревшем мире, вы можете сделать то же самое, используя только MediaBrowser в Media3.

MediaBrowser может быть построен и ожидает подключения к установленной службе: 

scope.launch {
    val sessionToken =
        SessionToken(context, ComponentName(context, MusicService::class.java)
    browser =
        MediaBrowser.Builder(context, sessionToken))
            .setListener(BrowserListener())
            .buildAsync()
            .await()
    // Get the library root to start browsing the library.
    root = browser.getLibraryRoot(/* params= */ null).await();
    // Add a MediaController.Listener to listen to player state events.
    browser.addListener(playerListener)
    playerView.setPlayer(browser)
}

Посмотрите на воспроизведение управления в медиа -сессии, чтобы узнать, как создать MediaController для контроля воспроизведения на заднем плане.

Дальнейшие шаги и очистить

Нестабильные ошибки API

После перехода на Media3 вы можете увидеть ошибки с жаркой о нестабильных использования API. Эти API безопасны в использовании, а ошибки ворса являются побочным продуктом наших новых гарантий бинарной совместимости. Если вам не требуется строгая бинарная совместимость, эти ошибки могут быть безопасно подавлены аннотацией @OptIn .

Фон

Ни Exoplayer V1, ни V2 не предоставили строгих гарантий о бинарной совместимости библиотеки между последующими версиями. Поверхность API Exoplayer очень большая по дизайну, чтобы позволить приложениям настраивать практически каждый аспект воспроизведения. Последующие версии Exoplayer иногда будут вводить переиме на символы или другие нарушающие изменения (например, новые необходимые методы на интерфейсах). В большинстве случаев эти поломки были смягчены за счет введения нового символа наряду со старым символом для нескольких версий, чтобы дать разработчикам время мигрировать их использование, но это не всегда возможно.

Эти нарушительные изменения привели к двум проблемам для пользователей библиотек Exoplayer V1 и V2:

  1. Обновление от версии Exoplayer может привести к прекращению компиляции кода.
  2. Приложение, которое зависело от Exoplayer как напрямую, так и через промежуточную библиотеку, должно было обеспечить, чтобы обе зависимости были одной и той же версией, в противном случае бинарная несовместимость может привести к сбою времени выполнения.

Улучшения в медиа3

Media3 гарантирует бинарную совместимость для подмножества поверхности API. Части, которые не гарантируют бинарную совместимость, помечены @UnstableApi . Чтобы прояснить это различие, использование нестабильных символов API генерирует ошибку ворса, если они не аннотированы с @OptIn .

После перехода от Exoplayer V2 в Media3 вы можете увидеть много нестабильных ошибок API Lint. Это может показаться, что Media3 «менее стабилен», чем Exoplayer v2. Это не так. «Нестабильные» части API Media3 имеют тот же уровень стабильности, что и вся поверхность API Exoplayer V2, и гарантии поверхности API стабильной среды3 вообще недоступны у Exoplayer V2. Разница в том, что ошибка ворса теперь предупреждает вас о разных уровнях стабильности.

Обрабатывать нестабильные ошибки API Lint

Смотрите раздел по устранению неполадок в этих ошибках с ворсом для получения подробной информации о том, как аннотировать использование Java и Kotlin нестабильных API с @OptIn .

Устаревшие API

Вы можете заметить, что вызовы устаревшего API проходят через Android Studio. Мы рекомендуем заменить такие вызовы соответствующей альтернативой. Наведите на символ, чтобы увидеть Javadoc, который сообщает, какой API вместо этого использовать.

Экриншот: как отобразить Javadoc с альтернативой устаревшего метода
Рисунок 3 : Javadoc Tool Putip в Android Studio предлагает альтернативу для любого устаревшего символа.

Образцы кода и демонстрационные приложения

  • Androidx Media3 Session Demo App (Mobile and Wores)
    • Пользовательские действия
    • Системная UI уведомление, Mediabutton/bt
    • Помощник Google Assistant Control
  • UAMP: Android Media Player (Branch Media3) (Mobile, Automotiveos)
    • Системное уведомление пользовательского интерфейса, Mediabutton/bt, Возобновление воспроизведения
    • Google Assistant/Foros Playback Control
    • Automotiveos: пользовательская команда и вход
,

Приложения, которые в настоящее время используют автономную библиотеку com.google.android.exoplayer2 и androidx.media должны мигрировать в androidx.media3 . Используйте сценарий миграции , чтобы перенести файлы сборки Gradle, исходные файлы Java и Kotlin и файлы макета XML от Exoplayer 2.19.1 до Androidx Media3 1.1.1 .

Обзор

Прежде чем мигрировать, просмотрите следующие разделы, чтобы узнать больше о преимуществах новых API, API для миграции и о предпосылках, которые должен выполнять проект вашего приложения.

Зачем мигрировать на JetPack Media3

  • Это новый дом Exoplayer , тогда как com.google.android.exoplayer2 прекращен.
  • Получите доступ к API Player по компонентам / процессам с помощью MediaBrowser / MediaController .
  • Используйте расширенные возможности API MediaSession и MediaController .
  • Реклама возможностей воспроизведения с мелкозернистым контролем доступа .
  • Упростите свое приложение , удалив MediaSessionConnector и PlayerNotificationManager .
  • Обратно совместимо с API клиентами Compat Compat ( MediaBrowserCompat / MediaControllerCompat / MediaMetadataCompat )

Media API, чтобы перейти на Androidx Media3

  • Exoplayer и его расширения
    Это включает в себя все модули проекта Legacy Exoplayer, кроме модуля MediaSession , который прекращается. Приложения или модули в зависимости от пакетов в com.google.android.exoplayer2 могут быть мигрированы с помощью сценария миграции.
  • MediaSessionConnector (в зависимости от androidx.media.* Пакеты androidx.media:media:1.4.3+ )
    Удалите MediaSessionConnector и используйте androidx.media3.session.MediaSession .
  • MediaBrowserServiceCompat (в зависимости от androidx.media.* Пакеты androidx.media:media:1.4.3+ )
    Мигрировать подклассы androidx.media.MediaBrowserServiceCompat в androidx.media3.session.MediaLibraryService и код с использованием MediaBrowserCompat.MediaItem в androidx.media3.common.MediaItem .
  • MediaBrowserCompat (в зависимости от android.support.v4.media.* Пакеты androidx.media:media:1.4.3+ )
    Перенос клиентского кода, используя MediaBrowserCompat или MediaControllerCompat для использования androidx.media3.session.MediaBrowser с androidx.media3.common.MediaItem .

Предварительные условия

  1. Убедитесь, что ваш проект находится под управлением источника

    Убедитесь, что вы можете легко вернуть изменения, применяемые сценарием инструментов миграции. Если у вас еще нет проекта под управлением источника, сейчас самое время начать с него. Если по какой -то причине вы не хотите этого делать, сделайте резервную копию вашего проекта перед началом миграции.

  2. Обновите свое приложение

    • Мы рекомендуем обновить ваш проект, чтобы использовать самую последнюю версию библиотеки Exoplayer и удалить любые вызовы для устаревших методов. Если вы собираетесь использовать сценарий для миграции, вам нужно соответствовать версии, которую вы обновляете с версией, обрабатываемой сценарием.

    • Увеличьте компилирующие средства вашего приложения как минимум до 32 .

    • Обновите Gradle и плагин Android Studio Gradle до недавней версии, которая работает с обновленными зависимостями сверху. Например:

      • Версия плагина Android Gradle: 7.1.0
      • Градл Версия: 7.4

    • Замените все операторы импорта подстановочного знака , которые используют Asterix (*) и используйте полностью квалифицированные операторы импорта: Удалить операторы импорта подстановочного знака и использовать Android Studio для импорта полностью квалифицированных операторов (F2 - Alt/Enter, F2 - Alt/Enter, ...).

    • Мигрировать из com.google.android.exoplayer2.PlayerView в com.google.android.exoplayer2.StyledPlayerView . Это необходимо, потому что нет эквивалента com.google.android.exoplayer2.PlayerView в Androidx Media3.

Мигрировать экзоплайер с поддержкой сценариев

Скрипт облегчает переход от com.google.android.exoplayer2 к новой структуре пакета и модуля под androidx.media3 . Сценарий применяет некоторые проверки проверки в вашем проекте и печатает предупреждения, если проверка не удается. В противном случае он применяет отображения переименованных классов и пакетов в ресурсах проекта Android Gradle, написанного на Java или Kotlin.

usage: ./media3-migration.sh [-p|-c|-d|-v]|[-m|-l [-x <path>] [-f] PROJECT_ROOT]
 PROJECT_ROOT: path to your project root (location of 'gradlew')
 -p: list package mappings and then exit
 -c: list class mappings (precedence over package mappings) and then exit
 -d: list dependency mappings and then exit
 -l: list files that will be considered for rewrite and then exit
 -x: exclude the path from the list of file to be changed: 'app/src/test'
 -m: migrate packages, classes and dependencies to AndroidX Media3
 -f: force the action even when validation fails
 -v: print the exoplayer2/media3 version strings of this script
 -h, --help: show this help text

Использование сценария миграции

  1. Загрузите сценарий миграции с тега проекта Exoplayer на GitHub, соответствующей версии, которую вы обновили свое приложение:

    curl -o media3-migration.sh \
  "https://raw.githubusercontent.com/google/ExoPlayer/r2.19.1/media3-migration.sh"

  2. Сделайте исполняемый файл сценария:

    chmod 744 media3-migration.sh

  3. Запустите сценарий с помощью --help , чтобы узнать о вариантах.

  4. Запустите скрипт с -l , чтобы перечислить набор файлов, которые выбраны для миграции (используйте -f , чтобы установить листинг без предупреждений):

    ./media3-migration.sh -l -f /path/to/gradle/project/root

  5. Запустите сценарий с -m для картирования пакетов, классов и модулей для Media3. Запуск скрипта с опцией -m будет применять изменения в выбранных файлах.

    • Остановитесь при ошибке проверки без внесения изменений 
    ./media3-migration.sh -m /path/to/gradle/project/root
    • Принудительное исполнение

    Если сценарий находит нарушение предпосылок, миграция может быть вызвана флагом -f :

    ./media3-migration.sh -m -f /path/to/gradle/project/root

 # list files selected for migration when excluding paths
 ./media3-migration.sh -l -x "app/src/test/" -x "service/" /path/to/project/root
 # migrate the selected files
 ./media3-migration.sh -m -x "app/src/test/" -x "service/" /path/to/project/root

Завершите эти ручные шаги после запуска сценария с опцией -m :

  1. Проверьте, как сценарий изменил ваш код : используйте инструмент Diff и исправьте потенциальные проблемы (рассмотрите возможность подачи ошибки , если вы думаете, что у скрипта есть общая проблема, которая была введена без передачи опции -f ).
  2. Создайте проект : либо используйте ./gradlew clean build , либо в Android Studio Выберите File> Sync Project с Files Files , затем Build> Clean Project , а затем Build> Rebuild Project (отслеживайте свою сборку на вкладке «Build - Build Output» Android Studio .

Рекомендуемые последующие шаги:

  1. Установите решение об ошибках в отношении использования нестабильных API .
  2. Замените устаревшие вызовы API : используйте предлагаемый API замены. Установите указатель по предупреждению в Android Studio и проконсультируйтесь с Javadoc устаревшего символа, чтобы выяснить, что использовать, а не данный звонок.
  3. Сортируйте операторы импорта : откройте проект в Android Studio, затем щелкните правой кнопкой мыши на узле папки папки в просмотре проекта и выберите «Оптимизировать импорт» на пакетах, которые содержат измененные исходные файлы.

Заменить MediaSessionConnector на androidx.media3.session.MediaSession

В мире Legacy MediaSessionCompat MediaSessionConnector отвечал за синхронизацию состояния игрока с состоянием сессии и получения команд от контроллеров, которые нуждались в делегировании с соответствующими методами игрока. С помощью Androidx Media3 это делается непосредственно с помощью MediaSession , не требуя разъема.

  1. Удалите все ссылки и использование MediaSessionConnector: Если вы использовали автоматический скрипт для миграции классов и пакетов экзоплал, то, вероятно, сценарий оставил ваш код в невозможности, касающееся MediaSessionConnector , который не может быть разрешен. Android Studio покажет вам разбитый код, когда вы попытаетесь создать или запустить приложение.

  2. В файле build.gradle , где вы поддерживаете свои зависимости, добавьте зависимость реализации в модуль сеанса Androidx Media3 и удалите устаревшую зависимость:

    implementation "androidx.media3:media3-session:1.6.0"

  3. Замените MediaSessionCompat на androidx.media3.session.MediaSession .

  4. На сайте кода вы создали Legacy MediaSessionCompat , используйте androidx.media3.session.MediaSession.Builder для создания MediaSession . Пропустите игрока , чтобы построить сеанс -строитель.

    val player = ExoPlayer.Builder(context).build()
mediaSession = MediaSession.Builder(context, player)
    .setSessionCallback(MySessionCallback())
    .build()

  5. Реализуйте MySessionCallback , как того требует ваше приложение. Это необязательно. Если вы хотите позволить контроллерам добавлять элементы медиа -элементов в игрока, внедрить MediaSession.Callback.onAddMediaItems() . Он обслуживает различные текущие и устаревшие методы API, которые добавляют предметы медиа -элементов игроку для воспроизведения обратно. Это включает в себя методы MediaController.set/addMediaItems() контроллера Media3, а также TransportControls.prepareFrom*/playFrom* Методы API Legacy API. Образец реализации onAddMediaItems можно найти в PlaybackService приложения для демонстрации сессии .

  6. Выпустите сеанс медиа на сайте кода, где вы уничтожили свою сессию до миграции: 

    mediaSession?.run {
  player.release()
  release()
  mediaSession = null
}

Функциональность MediaSessionConnector в Media3

В следующей таблице показаны API Media3, которые обрабатывают функциональность, ранее реализованные в MediaSessionConnector .

MediaSessionConnector Androidx Media3
CustomActionProvider MediaSession.Callback.onCustomCommand()/ MediaSession.setMediaButtonPreferences()
PlaybackPreparer MediaSession.Callback.onAddMediaItems() ( prepare() называется внутренне)
QueueNavigator ForwardingSimpleBasePlayer
QueueEditor MediaSession.Callback.onAddMediaItems()
RatingCallback MediaSession.Callback.onSetRating()
PlayerNotificationManager DefaultMediaNotificationProvider/ MediaNotification.Provider

Мигрировать MediaBrowserService в MediaLibraryService

Androidx Media3 представляет MediaLibraryService , который заменяет MediaBrowserServiceCompat . Javadoc of MediaLibraryService и его супер класс MediaSessionService обеспечивают хорошее вступление в API и асинхронную модель программирования.

MediaLibraryService с обратно, совместим с MediaBrowserService . Клиентское приложение, которое использует MediaBrowserCompat или MediaControllerCompat , продолжает работать без изменений кода при подключении к MediaLibraryService . Для клиента прозрачно, использует ли ваше приложение MediaLibraryService или Legacy MediaBrowserServiceCompat .

Диаграмма компонентов приложения с обслуживанием, деятельностью и внешними приложениями.
Рисунок 1 : Обзор компонента приложения медиа -приложения

  1. Для обратной совместимости для работы вам необходимо зарегистрировать оба сервисных интерфейсов с помощью вашего сервиса в AndroidManifest.xml . Таким образом, клиент находит ваш сервис по требуемому интерфейсу службы: 

    <service android:name=".MusicService" android:exported="true">
    <intent-filter>
        <action android:name="androidx.media3.session.MediaLibraryService"/>
        <action android:name="android.media.browse.MediaBrowserService" />
    </intent-filter>
</service>

  2. В файле build.gradle , где вы поддерживаете свои зависимости, добавьте зависимость реализации в модуль сеанса Androidx Media3 и удалите устаревшую зависимость: 

    implementation "androidx.media3:media3-session:1.6.0"

  3. Измените свой сервис, чтобы унаследовать от MediaLibraryService вместо MediaBrowserService , как было сказано ранее, MediaLibraryService совместим с устаревшим MediaBrowserService . Соответственно, более широкий API, который предлагает услуга клиентам, остается прежним. Таким образом, вполне вероятно, что приложение может сохранить большую часть логики, которая требуется для реализации MediaBrowserService и адаптации его для нового MediaLibraryService .

    Основные различия по сравнению с Legacy MediaBrowserServiceCompat заключаются в следующем:

    • Реализовать методы жизненного цикла обслуживания. Методы, которые необходимо переопределить в самой службе,-это onCreate/onDestroy , где приложение выделяет/выпускает сеанс библиотеки, игрока и другие ресурсы. В дополнение к стандартным методам жизненного цикла обслуживания, приложение должно переопределить onGetSession(MediaSession.ControllerInfo) чтобы вернуть MediaLibrarySession , которая была построена в onCreate .

    • Реализация MedialiabraryService.MedialibrarySessionCallback: Создание сеанса требует MediaLibraryService.MediaLibrarySessionCallback , который реализует фактические методы API домена. Таким образом, вместо того, чтобы переопределить методы API унаследованной службы, вы переопределяете методы MediaLibrarySession.Callback вместо этого.

      Обратный вызов затем используется для построения MediaLibrarySession : 

      mediaLibrarySession =
      MediaLibrarySession.Builder(this, player, MySessionCallback())
         .build()

      Найдите полный API MedialibrarySessionCallback в документации API.

    • Реализация MediaSession.Callback.onAddMediaItems() : обратный вызов onAddMediaItems(MediaSession, ControllerInfo, List<MediaItem>) обслуживает различные текущие и устаревшие методы API, которые добавляют элементы медиа игрока для воспроизведения обратно совместимым образом. Это включает в себя методы MediaController.set/addMediaItems() контроллера Media3, а также TransportControls.prepareFrom*/playFrom* Методы API Legacy API. Образец реализации обратного вызова можно найти в PlaybackService приложения для демонстрации сеанса .

    • Androidx Media3 использует androidx.media3.common.MediaItem вместо mediabrowsercompat.mediaitem и mediaMetAdatacompat . Части вашего кода, привязанные к устаревшим классам, должны быть изменены соответствующим образом или отображать в Media3 MediaItem .

    • Общая асинхронная модель программирования изменилась на Futures в отличие от съемного подхода к Result MediaBrowserServiceCompat . Реализация вашей услуги может вернуть асинхронную ListenableFuture , а не отсоединить результат или вернуть непосредственное будущее, чтобы непосредственно вернуть значение .

Удалить PlayernotificationManager

MediaLibraryService автоматически поддерживает уведомления средств массовой информации , и PlayerNotificationManager может быть удален при использовании MediaLibraryService или MediaSessionService .

Приложение может настроить уведомление , onCreate() DefaultMediaNotificationProvider MediaNotification.Provider . MediaLibraryService затем позаботится о запуске обслуживания на переднем плане по мере необходимости.

Переопределяя MediaLibraryService.updateNotification() приложение может дополнительно принять участие в публикации уведомления и запуска/остановки услуги на переднем плане по мере необходимости.

Мигрируйте клиент -код, используя медиаброуззер

С помощью Androidx Media3 MediaBrowser реализует интерфейсы MediaController/Player и может использоваться для управления воспроизведением медиа, помимо просмотра медиа -библиотеки. Если вам пришлось создать MediaBrowserCompat и MediaControllerCompat в Legacy World, вы можете сделать то же самое, только используя MediaBrowser в Media3.

MediaBrowser может быть построен и ожидает подключения к установленной службе: 

scope.launch {
    val sessionToken =
        SessionToken(context, ComponentName(context, MusicService::class.java)
    browser =
        MediaBrowser.Builder(context, sessionToken))
            .setListener(BrowserListener())
            .buildAsync()
            .await()
    // Get the library root to start browsing the library.
    root = browser.getLibraryRoot(/* params= */ null).await();
    // Add a MediaController.Listener to listen to player state events.
    browser.addListener(playerListener)
    playerView.setPlayer(browser)
}

Посмотрите на воспроизведение управления в медиа -сессии, чтобы узнать, как создать MediaController для контроля воспроизведения на заднем плане.

Дальнейшие шаги и очистить

Нестабильные ошибки API

После перехода на Media3 вы можете увидеть ошибки с жаркой о нестабильных использования API. Эти API безопасны в использовании, а ошибки ворса являются побочным продуктом наших новых гарантий бинарной совместимости. Если вам не требуется строгая бинарная совместимость, эти ошибки могут быть безопасно подавлены аннотацией @OptIn .

Фон

Ни Exoplayer V1, ни V2 не предоставили строгих гарантий о бинарной совместимости библиотеки между последующими версиями. Поверхность API Exoplayer очень большая по дизайну, чтобы позволить приложениям настраивать практически каждый аспект воспроизведения. Последующие версии Exoplayer иногда будут вводить переиме на символы или другие нарушающие изменения (например, новые необходимые методы на интерфейсах). В большинстве случаев эти поломки были смягчены за счет введения нового символа наряду со старым символом для нескольких версий, чтобы дать разработчикам время мигрировать их использование, но это не всегда возможно.

Эти нарушительные изменения привели к двум проблемам для пользователей библиотек Exoplayer V1 и V2:

  1. Обновление от версии Exoplayer может привести к прекращению компиляции кода.
  2. Приложение, которое зависело от Exoplayer как напрямую, так и через промежуточную библиотеку, должно было обеспечить, чтобы обе зависимости были одной и той же версией, в противном случае бинарная несовместимость может привести к сбою времени выполнения.

Улучшения в медиа3

Media3 гарантирует бинарную совместимость для подмножества поверхности API. Части, которые не гарантируют бинарную совместимость, помечены @UnstableApi . Чтобы прояснить это различие, использование нестабильных символов API генерирует ошибку ворса, если они не аннотированы с @OptIn .

После перехода от Exoplayer V2 в Media3 вы можете увидеть много нестабильных ошибок API Lint. Это может показаться, что Media3 «менее стабилен», чем Exoplayer v2. Это не так. «Нестабильные» части API Media3 имеют тот же уровень стабильности, что и вся поверхность API Exoplayer V2, и гарантии поверхности API стабильной среды3 вообще недоступны у Exoplayer V2. Разница в том, что ошибка ворса теперь предупреждает вас о разных уровнях стабильности.

Обрабатывать нестабильные ошибки API Lint

Смотрите раздел по устранению неполадок в этих ошибках с ворсом для получения подробной информации о том, как аннотировать использование Java и Kotlin нестабильных API с @OptIn .

Устаревшие API

Вы можете заметить, что вызовы устаревшего API проходят через Android Studio. Мы рекомендуем заменить такие вызовы соответствующей альтернативой. Наведите на символ, чтобы увидеть Javadoc, который сообщает, какой API вместо этого использовать.

Экриншот: как отобразить Javadoc с альтернативой устаревшего метода
Рисунок 3 : Javadoc Tool Putip в Android Studio предлагает альтернативу для любого устаревшего символа.

Образцы кода и демонстрационные приложения

  • Androidx Media3 Session Demo App (Mobile and Wores)
    • Пользовательские действия
    • Системная UI уведомление, Mediabutton/bt
    • Помощник Google Assistant Control
  • UAMP: Android Media Player (Branch Media3) (Mobile, Automotiveos)
    • Системное уведомление пользовательского интерфейса, Mediabutton/bt, Возобновление воспроизведения
    • Google Assistant/Foros Playback Control
    • Automotiveos: пользовательская команда и вход