Сеансы мультимедиа обеспечивают универсальный способ взаимодействия с аудио- или видеопроигрывателем. Если сообщить Android, что в приложении воспроизводится медиаконтент, то элементы управления воспроизведением можно делегировать приложению. Интеграция с сеансом мультимедиа позволяет приложению рекламировать воспроизведение мультимедиа извне и получать команды воспроизведения из внешних источников. Это могут быть физические кнопки (например, кнопка воспроизведения на гарнитуре или пульте телевизора) или косвенные команды (например, "пауза" для Google Ассистента). Затем медиасеанс делегирует эти команды приложению, которое применяет их к медиапроигрывателю, для которого прозрачно, откуда поступили команды.
Сеанс мультимедиа существует вместе с проигрывателем, которым он управляет. Создавать и инициализировать сеанс воспроизведения следует в методе onCreate() действия или сервиса, которому принадлежит сеанс и связанный с ним проигрыватель.
Инициализация сеанса воспроизведения медиаконтента
У нового сеанса воспроизведения нет возможностей. Необходимо инициализировать сеанс, выполнив следующие действия:
- Установите флажки, чтобы сеанс мультимедиа мог получать обратные вызовы от контроллеров и кнопок мультимедиа.
- Создайте и инициализируйте экземпляр
PlaybackStateCompatи назначьте его сеансу. Состояние воспроизведения меняется в течение сеанса, поэтому мы рекомендуем кешироватьPlaybackStateCompat.Builderдля повторного использования. - Создайте экземпляр
MediaSessionCompat.Callbackи назначьте его сеансу (подробнее об обратных вызовах рассказывается ниже).
Создавать и инициализировать сеанс воспроизведения следует в методе onCreate() активности или сервиса, которому принадлежит сеанс.
Чтобы кнопки управления мультимедиа работали, когда приложение только инициализировано или остановлено, его объект PlaybackState должен содержать действие воспроизведения, соответствующее намерению, которое отправляет кнопка. Поэтому при инициализации состоянию сеанса присваивается значение ACTION_PLAY. Подробнее о том, как реагировать на нажатие кнопок управления медиаконтентом…
Как поддерживать состояние воспроизведения и метаданные
Состояние сеанса воспроизведения представляют два класса.
Класс PlaybackStateCompat описывает текущее рабочее состояние проигрывателя. Примеры:
- Состояние воспроизведения (воспроизводится, приостановлено, буферизация и т. д.). Подробнее о
getState()… - Код ошибки и сообщение об ошибке (необязательно). (см. раздел
getErrorCode()и Статусы и ошибки ниже). - Позиция игрока
- Допустимые действия контроллера, которые можно обработать в текущем состоянии.
Класс MediaMetadataCompat описывает воспроизводимый контент:
- имя исполнителя, название альбома и трека;
- Продолжительность трека.
- Обложка альбома, которая будет показываться на заблокированном экране. Изображение должно быть растровым, а его размер не должен превышать 320 x 320 dp (в противном случае оно будет уменьшено).
- Экземпляр
ContentUris, указывающий на увеличенную версию изображения.
Состояние проигрывателя и метаданные могут меняться в течение сеанса воспроизведения. Каждый раз, когда состояние или метаданные меняются, вы должны использовать соответствующий конструктор для каждого класса, PlaybackStateCompat.Builder() или MediaMetadataCompat.Builder(), а затем передавать новый экземпляр в сеанс воспроизведения, вызывая setPlaybackState() или setMetaData(). Чтобы снизить общий объем потребляемой памяти, рекомендуется создать объекты Builder один раз и использовать их повторно на протяжении всего сеанса.
Статусы и ошибки
Обратите внимание, что PlaybackState – это объект, который содержит отдельные значения для состояния воспроизведения сеанса (getState()) и, при необходимости, связанный код ошибки (getErrorCode()). Ошибки могут быть критическими и некритическими:
Если воспроизведение прерывается, необходимо сгенерировать критическую ошибку: задать для состояния передачи значение STATE_ERROR и указать связанную ошибку с помощью setErrorMessage(int, CharSequence). Пока воспроизведение заблокировано ошибкой, PlaybackState должен продолжать сообщать о STATE_ERROR и ошибке.
Некритическая ошибка возникает, когда приложение не может обработать запрос, но может продолжить воспроизведение. Транспорт остается в нормальном состоянии (например, STATE_PLAYING), но PlaybackState содержит код ошибки. Например, если пользователь хочет перейти к следующему треку, но играет последний, воспроизведение может продолжаться, но вам нужно создать новый объект PlaybackState с кодом ошибки ERROR_CODE_END_OF_QUEUE, а затем вызвать setPlaybackState(). Контроллеры мультимедиа, подключенные к сеансу, получат обратный вызов onPlaybackStateChanged() и объяснят пользователю, что произошло. О некритической ошибке нужно сообщать только один раз – в момент ее возникновения. При следующем обновлении сеанса PlaybackState не должны снова устанавливать ту же некритическую ошибку (если только она не возникла в ответ на новый запрос).
Заблокированные экраны сеансов воспроизведения медиаконтента
Начиная с Android 4.0 (уровень API 14), система может получать доступ к статусу воспроизведения и метаданным сеанса мультимедиа. Вот как на заблокированном экране могут отображаться элементы управления мультимедиа и обложка. Поведение зависит от версии Android.
Обложки альбомов
В Android 4.0 (уровень API 14) – Android 10 (уровень API 29) на заблокированном экране показывается обложка альбома, но только если в метаданных сеанса воспроизведения есть фоновое растровое изображение.
Элементы управления воспроизведением
В Android 4.0 (API уровня 14) – Android 4.4 (API уровня 19) при активном сеансе воспроизведения и наличии в метаданных фонового растрового изображения на заблокированном экране автоматически появляются элементы управления.
В Android 5.0 (уровень API 21) и более поздних версиях на заблокированном экране нет элементов управления воспроизведением. Вместо этого для отображения элементов управления воспроизведением следует использовать уведомление MediaStyle.
Добавить настраиваемые действия
Мультимедийные приложения могут определять специальные действия, например "Нравится", "Лайк" или "Перемотать на 30 секунд назад". Настраиваемое действие должно реализовывать совершенно новое поведение. Не используйте настраиваемое действие вместо стандартного, определенного в PlaybackStateCompat.
Добавьте настраиваемые действия с помощью addCustomAction(). В примере ниже показано, как добавить элемент управления для действия "Нравится".
Kotlin
stateBuilder.addCustomAction(
PlaybackStateCompat.CustomAction.Builder(
CUSTOM_ACTION_THUMBS_UP,
resources.getString(R.string.thumbs_up),
thumbsUpIcon
).run {
setExtras(customActionExtras)
build()
}
)
Java
stateBuilder.addCustomAction(new PlaybackStateCompat.CustomAction.Builder(
CUSTOM_ACTION_THUMBS_UP, resources.getString(R.string.thumbs_up), thumbsUpIcon)
.setExtras(customActionExtras)
.build());
Полный пример можно найти в Universal Music Player.
Вы отвечаете на действие с помощью onCustomAction().
Kotlin
override fun onCustomAction(action: String, extras: Bundle?) {
when(action) {
CUSTOM_ACTION_THUMBS_UP -> {
...
}
}
}
Java
@Override
public void onCustomAction(@NonNull String action, Bundle extras) {
if (CUSTOM_ACTION_THUMBS_UP.equals(action)) {
...
}
}
Также ознакомьтесь с универсальным музыкальным проигрывателем.
Обратные вызовы мультимедийных сеансов
Основные методы обратного вызова сеанса мультимедиа: onPlay(), onPause() и onStop(). Здесь вы добавляете код, который управляет проигрывателем.
Поскольку вы создаете экземпляр и задаете обратный вызов сеанса во время выполнения (в onCreate()), ваше приложение может определять альтернативные обратные вызовы, которые используют разные проигрыватели, и выбирать подходящую комбинацию обратного вызова и проигрывателя в зависимости от устройства и уровня системы. Вы можете изменить проигрыватель, не меняя остальную часть приложения. Например, можно использовать ExoPlayer на устройствах с Android 4.1 (уровень API 16) или более поздней версии и MediaPlayer на устройствах с более ранними версиями ОС.
Помимо управления проигрывателем и переходами между состояниями сеанса, обратные вызовы также включают и отключают функции вашего приложения и управляют тем, как оно взаимодействует с другими приложениями и аппаратным обеспечением устройства. (см. раздел Управление выводом аудио).
Реализация методов обратного вызова сеанса мультимедиа зависит от структуры приложения. О том, как использовать обратные вызовы в аудиоприложениях и видеоприложениях, рассказывается в отдельных статьях.