Jetpack Media3 определяет интерфейс Player
, который описывает базовую функциональность для воспроизведения видео- и аудиофайлов. ExoPlayer
— это реализация этого интерфейса по умолчанию в Media3. Мы рекомендуем использовать ExoPlayer, так как он предоставляет полный набор функций, которые охватывают большинство вариантов использования воспроизведения и настраивается для обработки любых дополнительных вариантов использования, которые могут у вас возникнуть. ExoPlayer также абстрагируется от фрагментации устройства и ОС, поэтому ваш код работает согласованно во всей экосистеме Android. ExoPlayer включает:
- Поддержка плейлистов
- Поддержка различных прогрессивных и адаптивных форматов потоковой передачи
- Поддержка вставки рекламы как на стороне клиента, так и на стороне сервера
- Поддержка воспроизведения с защитой DRM
На этой странице вы найдете описание некоторых ключевых этапов создания приложения для воспроизведения, а для получения более подробной информации вы можете обратиться к нашим полным руководствам по Media3 ExoPlayer .
Начиная
Для начала добавьте зависимость от модулей ExoPlayer, UI и Common Jetpack Media3:
implementation "androidx.media3:media3-exoplayer:1.7.1" implementation "androidx.media3:media3-ui:1.7.1" implementation "androidx.media3:media3-common:1.7.1"
В зависимости от вашего варианта использования вам также могут понадобиться дополнительные модули от Media3, такие как exoplayer-dash
для воспроизведения потоков в формате DASH.
Обязательно замените 1.7.1
на предпочтительную версию библиотеки. Вы можете обратиться к примечаниям к выпуску , чтобы увидеть последнюю версию.
Создание медиаплеера
С Media3 вы можете использовать либо встроенную реализацию интерфейса Player
, ExoPlayer
, либо создать свою собственную реализацию.
Создание ExoPlayer
Самый простой способ создания экземпляра ExoPlayer
выглядит следующим образом:
Котлин
val player = ExoPlayer.Builder(context).build()
Ява
ExoPlayer player = new ExoPlayer.Builder(context).build();
Вы можете создать свой медиаплеер в методе жизненного цикла onCreate()
Activity
, Fragment
или Service
, где он находится.
Builder
включает в себя ряд параметров настройки, которые могут вас заинтересовать, например:
-
setAudioAttributes()
для настройки обработки аудиофокуса -
setHandleAudioBecomingNoisy()
для настройки поведения воспроизведения при отключении устройства вывода звука -
setTrackSelector()
для настройки выбора трека
Media3 предоставляет компонент пользовательского интерфейса PlayerView
, который можно включить в файл макета вашего приложения. Этот компонент инкапсулирует PlayerControlView
для управления воспроизведением, SubtitleView
для отображения субтитров и Surface
для рендеринга видео.
Подготовка игрока
Добавьте элементы мультимедиа в плейлист для воспроизведения с помощью таких методов, как setMediaItem()
и addMediaItem()
. Затем вызовите prepare()
, чтобы начать загрузку мультимедиа и получить необходимые ресурсы.
Не следует выполнять эти шаги до того, как приложение окажется на переднем плане. Если ваш плеер находится в Activity
или Fragment
, это означает подготовку плеера в методе жизненного цикла onStart()
на уровне API 24 и выше или в методе жизненного цикла onResume()
на уровне API 23 и ниже. Для плеера, который находится в Service
, вы можете подготовить его в onCreate()
.
Управляйте игроком
После подготовки проигрывателя вы можете управлять воспроизведением, вызывая методы проигрывателя, такие как:
-
play()
иpause()
для запуска и приостановки воспроизведения -
seekTo()
для поиска позиции в текущем медиа-элементе -
seekToNextMediaItem()
иseekToPreviousMediaItem()
для навигации по плейлисту
Компоненты пользовательского интерфейса, такие как PlayerView
или PlayerControlView
будут обновляться соответствующим образом при привязке к проигрывателю.
Отпустите игрока.
Для воспроизведения могут потребоваться ресурсы, запас которых ограничен, например видеодекодеры, поэтому важно вызывать release()
на проигрывателе, чтобы освободить ресурсы, когда проигрыватель больше не нужен.
Если ваш плеер находится в Activity
или Fragment
, освободите плеер в методе жизненного цикла onStop()
на уровне API 24 и выше или в методе onPause()
на уровне API 23 и ниже. Для плеера, который находится в Service
, вы можете освободить его в onDestroy()
.
Управление воспроизведением с помощью медиа-сеанса
На Android медиа-сессии предоставляют стандартизированный способ взаимодействия с медиа-плеером через границы процесса. Подключение медиа-сессии к вашему плееру позволяет вам рекламировать воспроизведение медиа извне и получать команды воспроизведения из внешних источников, например, для интеграции с системными элементами управления медиа на мобильных устройствах и устройствах с большим экраном.
Чтобы использовать медиа-сессии, добавьте зависимость от модуля Media3 Session:
implementation "androidx.media3:media3-session:1.7.1"
Создать медиа-сессию
Вы можете создать MediaSession
после инициализации проигрывателя следующим образом:
Котлин
val player = ExoPlayer.Builder(context).build() val mediaSession = MediaSession.Builder(context, player).build()
Ява
ExoPlayer player = new ExoPlayer.Builder(context).build(); MediaSession mediaSession = new MediaSession.Builder(context, player).build();
Media3 автоматически синхронизирует состояние Player
с состоянием MediaSession
. Это работает с любой реализацией Player
, включая ExoPlayer
, CastPlayer
или пользовательскую реализацию.
Предоставить контроль другим клиентам
Клиентские приложения могут реализовать медиа-контроллер для управления воспроизведением вашего медиа-сеанса. Чтобы получать эти запросы, установите объект обратного вызова при создании MediaSession
.
Когда контроллер собирается подключиться к вашему сеансу мультимедиа, вызывается метод onConnect()
. Вы можете использовать предоставленный ControllerInfo
, чтобы решить, принять или отклонить запрос. Посмотрите пример этого в демонстрационном приложении Media3 Session .
После подключения контроллер может отправлять команды воспроизведения в сеанс. Затем сеанс делегирует эти команды проигрывателю. Команды воспроизведения и плейлиста, определенные в интерфейсе Player
, автоматически обрабатываются сеансом.
Другие методы обратного вызова позволяют обрабатывать, например, запросы на пользовательские команды воспроизведения и изменение списка воспроизведения . Эти обратные вызовы также включают объект ControllerInfo
, поэтому вы можете определять контроль доступа на основе запроса за запросом.
Воспроизведение медиа в фоновом режиме
Чтобы продолжить воспроизведение мультимедиа, когда ваше приложение не находится на переднем плане, например, для воспроизведения музыки, аудиокниг или подкастов, даже если у пользователя не открыто ваше приложение, ваш Player
и MediaSession
должны быть инкапсулированы в службу переднего плана . Media3 предоставляет интерфейс MediaSessionService
для этой цели.
Реализация MediaSessionService
Создайте класс, расширяющий MediaSessionService
, и создайте экземпляр MediaSession
в методе жизненного цикла onCreate()
.
Котлин
class PlaybackService : MediaSessionService() { private var mediaSession: MediaSession? = null // Create your Player and MediaSession in the onCreate lifecycle event override fun onCreate() { super.onCreate() val player = ExoPlayer.Builder(this).build() mediaSession = MediaSession.Builder(this, player).build() } // Remember to release the player and media session in onDestroy override fun onDestroy() { mediaSession?.run { player.release() release() mediaSession = null } super.onDestroy() } }
Ява
public class PlaybackService extends MediaSessionService { private MediaSession mediaSession = null; @Override public void onCreate() { super.onCreate(); ExoPlayer player = new ExoPlayer.Builder(this).build(); mediaSession = new MediaSession.Builder(this, player).build(); } @Override public void onDestroy() { mediaSession.getPlayer().release(); mediaSession.release(); mediaSession = null; super.onDestroy(); } }
В вашем манифесте класс Service
с фильтром намерений MediaSessionService
и запросите разрешение FOREGROUND_SERVICE
для запуска службы переднего плана:
<service
android:name=".PlaybackService"
android:foregroundServiceType="mediaPlayback"
android:exported="true">
<intent-filter>
<action android:name="androidx.media3.session.MediaSessionService"/>
</intent-filter>
</service>
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
Наконец, в созданном вами классе переопределите метод onGetSession()
для управления доступом клиента к вашему сеансу мультимедиа. Верните MediaSession
, чтобы принять запрос на подключение, или верните null
, чтобы отклонить запрос.
Котлин
// This example always accepts the connection request override fun onGetSession( controllerInfo: MediaSession.ControllerInfo ): MediaSession? = mediaSession
Ява
@Override public MediaSession onGetSession(MediaSession.ControllerInfo controllerInfo) { // This example always accepts the connection request return mediaSession; }
Подключение к вашему пользовательскому интерфейсу
Теперь, когда ваш сеанс мультимедиа находится в Service
отдельно от Activity
или Fragment
, где находится ваш пользовательский интерфейс проигрывателя, вы можете использовать MediaController
, чтобы связать их вместе. В методе onStart()
Activity
или Fragment
с вашим пользовательским интерфейсом создайте SessionToken
для вашего MediaSession
, затем используйте SessionToken
для создания MediaController
. Создание MediaController
происходит асинхронно.
Котлин
override fun onStart() { val sessionToken = SessionToken(this, ComponentName(this, PlaybackService::class.java)) val controllerFuture = MediaController.Builder(this, sessionToken).buildAsync() controllerFuture.addListener( { // Call controllerFuture.get() to retrieve the MediaController. // MediaController implements the Player interface, so it can be // attached to the PlayerView UI component. playerView.setPlayer(controllerFuture.get()) }, MoreExecutors.directExecutor() ) }
Ява
@Override public void onStart() { SessionToken sessionToken = new SessionToken(this, new ComponentName(this, PlaybackService.class)); ListenableFuture<MediaController> controllerFuture = new MediaController.Builder(this, sessionToken).buildAsync(); controllerFuture.addListener(() -> { // Call controllerFuture.get() to retrieve the MediaController. // MediaController implements the Player interface, so it can be // attached to the PlayerView UI component. playerView.setPlayer(controllerFuture.get()); }, MoreExecutors.directExecutor()) }
MediaController
реализует интерфейс Player
, поэтому вы можете использовать те же методы, такие как play()
и pause()
для управления воспроизведением. Подобно другим компонентам, не забудьте освободить MediaController
, когда он больше не нужен, например, метод жизненного цикла onStop()
Activity
, вызвав MediaController.releaseFuture()
.
Публикация уведомления
Для публикации уведомления в активном состоянии требуются службы переднего плана. MediaSessionService
автоматически создаст для вас уведомление MediaStyle
в форме MediaNotification
. Чтобы предоставить пользовательское уведомление, создайте MediaNotification.Provider
с помощью DefaultMediaNotificationProvider.Builder
или создав пользовательскую реализацию интерфейса поставщика. Добавьте поставщика в MediaSession
с помощью setMediaNotificationProvider
.
Реклама вашей библиотеки контента
MediaLibraryService
строится на MediaSessionService
, позволяя клиентским приложениям просматривать медиаконтент, предоставляемый вашим приложением. Клиентские приложения реализуют MediaBrowser
для взаимодействия с вашим MediaLibraryService
.
Реализация MediaLibraryService
похожа на реализацию MediaSessionService
, за исключением того, что в onGetSession()
вы должны вернуть MediaLibrarySession
вместо MediaSession
. По сравнению с MediaSession.Callback
, MediaLibrarySession.Callback
включает дополнительные методы, которые позволяют клиенту браузера перемещаться по контенту, предлагаемому вашей библиотечной службой.
Аналогично MediaSessionService
, объявите MediaLibraryService
в манифесте и запросите разрешение FOREGROUND_SERVICE
для запуска службы переднего плана:
<service
android:name=".PlaybackService"
android:foregroundServiceType="mediaPlayback"
android:exported="true">
<intent-filter>
<action android:name="androidx.media3.session.MediaLibraryService"/>
<action android:name="android.media.browse.MediaBrowserService"/>
</intent-filter>
</service>
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
В приведенном выше примере есть фильтр намерений как для MediaLibraryService
, так и для обратной совместимости с устаревшим MediaBrowserService
. Дополнительный фильтр намерений позволяет клиентским приложениям, использующим API MediaBrowserCompat
распознавать ваш Service
.
MediaLibrarySession
позволяет обслуживать вашу библиотеку контента в древовидной структуре с одним корневым MediaItem
. Каждый MediaItem
в дереве может иметь любое количество дочерних узлов MediaItem
. Вы можете обслуживать другой корень или другое дерево в зависимости от запроса клиентского приложения. Например, дерево, которое вы возвращаете клиенту, ищущему список рекомендуемых элементов мультимедиа, может содержать только корневой MediaItem
и один уровень дочерних узлов MediaItem
, тогда как дерево, которое вы возвращаете другому клиентскому приложению, может представлять более полную библиотеку контента.
Создание сеанса MediaLibrarySession
MediaLibrarySession
расширяет API MediaSession
для добавления API просмотра контента. По сравнению с обратным вызовом MediaSession
, обратный вызов MediaLibrarySession
добавляет такие методы, как:
-
onGetLibraryRoot()
, когда клиент запрашивает корневойMediaItem
дерева контента -
onGetChildren()
, когда клиент запрашивает дочерние элементыMediaItem
в дереве контента -
onGetSearchResult()
, когда клиент запрашивает результаты поиска из дерева контента для заданного запроса
Соответствующие методы обратного вызова будут включать объект LibraryParams
с дополнительными сигналами о типе дерева контента, который интересует клиентское приложение.