Создайте базовое приложение медиаплеера с помощью Media3 ExoPlayer.

Jetpack Media3 определяет интерфейс Player , который описывает базовую функциональность для воспроизведения видео- и аудиофайлов. ExoPlayer — это реализация этого интерфейса по умолчанию в Media3. Мы рекомендуем использовать ExoPlayer, так как он предоставляет полный набор функций, которые охватывают большинство вариантов использования воспроизведения и настраивается для обработки любых дополнительных вариантов использования, которые могут у вас возникнуть. ExoPlayer также абстрагируется от фрагментации устройства и ОС, поэтому ваш код работает согласованно во всей экосистеме Android. ExoPlayer включает:

На этой странице вы найдете описание некоторых ключевых этапов создания приложения для воспроизведения, а для получения более подробной информации вы можете обратиться к нашим полным руководствам по 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 включает в себя ряд параметров настройки, которые могут вас заинтересовать, например:

Media3 предоставляет компонент пользовательского интерфейса PlayerView , который можно включить в файл макета вашего приложения. Этот компонент инкапсулирует PlayerControlView для управления воспроизведением, SubtitleView для отображения субтитров и Surface для рендеринга видео.

Подготовка игрока

Добавьте элементы мультимедиа в плейлист для воспроизведения с помощью таких методов, как setMediaItem() и addMediaItem() . Затем вызовите prepare() , чтобы начать загрузку мультимедиа и получить необходимые ресурсы.

Не следует выполнять эти шаги до того, как приложение окажется на переднем плане. Если ваш плеер находится в Activity или Fragment , это означает подготовку плеера в методе жизненного цикла onStart() на уровне API 24 и выше или в методе жизненного цикла onResume() на уровне API 23 и ниже. Для плеера, который находится в Service , вы можете подготовить его в onCreate() .

Управляйте игроком

После подготовки проигрывателя вы можете управлять воспроизведением, вызывая методы проигрывателя, такие как:

Компоненты пользовательского интерфейса, такие как 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 с дополнительными сигналами о типе дерева контента, который интересует клиентское приложение.