Включить управление воспроизведением

Чтобы включить воспроизведение мультимедиа в Android Auto и Android Automotive OS (AAOS), реализуйте элементы управления воспроизведением, зарегистрировав сеанс мультимедиа и обработав его методы обратного вызова. На этой странице объясняется, как:

• Зарегистрируйте объект MediaSessionCompat в службе вашего медиабраузера.

• Реализуйте методы MediaSessionCompat.Callback для ответа на запросы пользователя на воспроизведение.

• Настройте стандартные и пользовательские действия воспроизведения.

• Установите начальное состояние воспроизведения для вашего медиасеанса.

• Добавьте значки для обозначения аудиоформата.

• Создавайте ссылки из активно воспроизводимых медиа-элементов.

Android Auto и AAOS отправляют команды управления воспроизведением через MediaSessionCompat для вашего сервиса. Вам необходимо зарегистрировать сеанс и реализовать соответствующие методы обратного вызова.

Рекомендации по дизайну: Подробнее см. в разделе Настройка элементов управления воспроизведением .

Зарегистрируйте медиа-сессию

В методе onCreate вашего медиабраузера создайте экземпляр MediaSessionCompat , а затем вызовите setSessionToken для регистрации медиасеанса. Этот фрагмент кода показывает, как создать и зарегистрировать медиасеанс:

Котлин

override fun onCreate() {
    super.onCreate()
    ...
    // Start a new MediaSession.
    val session = MediaSessionCompat(this, "session tag").apply {
        // Set a callback object that implements MediaSession.Callback
        // to handle play control requests.
        setCallback(MyMediaSessionCallback())
    }
    sessionToken = session.sessionToken
    ...
}

Ява

public void onCreate() {
    super.onCreate();
    ...
    // Start a new MediaSession.
    MediaSessionCompat session = new MediaSessionCompat(this, "session tag");
    setSessionToken(session.getSessionToken());

    // Set a callback object that implements MediaSession.Callback
    // to handle play control requests.
    session.setCallback(new MyMediaSessionCallback());
    ...
}

При создании объекта медиасеанса вы устанавливаете объект обратного вызова, который используется для обработки запросов на управление воспроизведением. Этот объект обратного вызова создаётся путём предоставления реализации класса MediaSessionCompat.Callback для вашего приложения. В следующем разделе рассматривается, как реализовать этот объект.

Примечание: для проверки сеанса мультимедиа выполните команду adb shell dumpsys media_session

Реализовать команды воспроизведения

Когда пользователь запрашивает воспроизведение медиафайла из вашего приложения, Android Automotive OS и Android Auto используют класс MediaSessionCompat.Callback из объекта MediaSessionCompat вашего приложения, полученного от службы медиабраузера вашего приложения. Когда пользователь хочет управлять воспроизведением контента, например, приостановить воспроизведение или перейти к следующему треку, Android Auto и Android Automotive OS вызывают один из методов объекта обратного вызова.

Для обработки воспроизведения контента ваше приложение должно расширить абстрактный класс MediaSessionCompat.Callback и реализовать методы, поддерживаемые вашим приложением.

Реализуйте каждый из этих методов обратного вызова, которые имеют смысл для типа контента, предлагаемого вашим приложением:

onPrepare

AAOS вызывает этот метод при изменении источника мультимедиа.

onPlay

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

Примечание: Ваше приложение не должно автоматически запускать воспроизведение музыки при подключении Android Automotive OS или Android Auto к службе медиабраузера. Подробнее см. в разделе Установка начального состояния воспроизведения .

onPlayFromMediaId

Вызывается, когда пользователь выбирает воспроизведение определённого элемента. Метод получает идентификатор , назначенный службой медиабраузера элементу медиа в иерархии контента.

onPlayFromSearch

Вызывается, когда пользователь выбирает воспроизведение по поисковому запросу. Приложение должно сделать соответствующий выбор на основе переданной поисковой строки.

onPause

Вызывается, когда пользователь решает приостановить воспроизведение.

onSkipToNext

Вызывается, когда пользователь решает перейти к следующему элементу.

onSkipToPrevious

Вызывается, когда пользователь решает перейти к предыдущему элементу.

onStop

Вызывается, когда пользователь решает остановить воспроизведение. Переопределите эти методы в своём приложении, чтобы получить выбранный результат. Вам не нужно реализовывать метод, если его назначение не поддерживается вашим приложением. Например, если ваше приложение воспроизводит прямую трансляцию, например, спортивную, вам не нужно реализовывать onSkipToNext . Вместо этого используйте реализацию onSkipToNext по умолчанию.

Вашему приложению не требуется специальная логика для воспроизведения контента через динамики автомобиля. Когда ваше приложение получает запрос на воспроизведение контента, оно воспроизводит аудио так же, как и через динамики телефона или наушники пользователя. Android Auto и AAOS автоматически отправляют аудиоконтент в автомобильную систему для воспроизведения через динамики автомобиля.

Дополнительную информацию о воспроизведении аудиоконтента см. в разделах Обзор Media Player , Обзор аудиоприложения и Обзор ExoPlayer.

Установить стандартные действия воспроизведения

Android Auto и AAOS отображают элементы управления воспроизведением на основе действий, включённых в объекте PlaybackStateCompat . По умолчанию ваше приложение должно поддерживать следующие действия:

• ACTION_PLAY
• ACTION_PAUSE
• ACTION_STOP
• ACTION_PLAY_FROM_MEDIA_ID
• ACTION_PLAY_FROM_SEARCH

Ваше приложение может дополнительно поддерживать следующие действия, если они имеют отношение к содержанию приложения:

• ACTION_SKIP_TO_PREVIOUS
• ACTION_SKIP_TO_NEXT

Кроме того, вы можете опционально создать очередь воспроизведения для отображения пользователю. Для этого вызовите методы setQueue и setQueueTitle , включите действие ACTION_SKIP_TO_QUEUE_ITEM и определите обратный вызов onSkipToQueueItem .

Также добавьте поддержку значка «Сейчас воспроизводится» , который служит индикатором текущего воспроизведения. Для этого вызовите метод setActiveQueueItemId и передайте идентификатор воспроизводимого элемента в очереди. Необходимо обновлять setActiveQueueItemId при каждом изменении очереди.

Примечание: Добавление поддержки значка «Сейчас воспроизводится» требуется только при поддержке очереди воспроизведения.

Android Auto и AAOS отображают кнопки для каждого включённого действия, а также очередь воспроизведения. При нажатии этих кнопок система вызывает соответствующий обратный вызов из MediaSessionCompat.Callback .

Резерв неиспользуемого пространства

Android Auto и AAOS резервируют место в пользовательском интерфейсе для действий ACTION_SKIP_TO_PREVIOUS и ACTION_SKIP_TO_NEXT . Если ваше приложение не поддерживает одну из этих функций, Android Auto и AAOS используют это место для отображения любых созданных вами действий.

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

Для этого вызовите метод setExtras с пакетом extras, содержащим константы, соответствующие зарезервированным функциям. SESSION_EXTRAS_KEY_SLOT_RESERVATION_SKIP_TO_NEXT соответствует ACTION_SKIP_TO_NEXT , а SESSION_EXTRAS_KEY_SLOT_RESERVATION_SKIP_TO_PREV соответствует ACTION_SKIP_TO_PREVIOUS . Используйте эти константы в качестве ключей в пакете, а логическое значение true в качестве значений.

Установить начальное состояние воспроизведения

Поскольку Android Auto и AAOS взаимодействуют со службой вашего медиабраузера, ваш медиасеанс передает статус воспроизведения контента с помощью PlaybackStateCompat .

Ваше приложение не должно автоматически начинать воспроизведение музыки при подключении AAOS или Android Auto к вашему медиабраузеру. Вместо этого полагайтесь на Android Auto и AAOS, которые будут возобновлять или запускать воспроизведение в зависимости от состояния автомобиля или действий пользователя.

Для этого установите начальное значение PlaybackStateCompat вашего медиа-сеанса на STATE_STOPPED , STATE_PAUSED , STATE_NONE или STATE_ERROR .

Примечание: Если для параметра PlaybackStateCompat задано значение STATE_NONE , Android Auto и AAOS делают интерфейс воспроизведения недоступным. Это состояние отправляется только тогда, когда приложению нечего воспроизводить и пользователю необходимо выбрать новый контент для начала воспроизведения.

Медиасеансы в Android Auto и AAOS длятся только в течение поездки, поэтому пользователи часто запускают и останавливают их. Для обеспечения бесперебойной работы между поездками отслеживайте состояние предыдущего сеанса пользователя, чтобы при запросе возобновления приложением для работы с мультимедиа автоматически возобновляло воспроизведение с того места, где остановилось. Например, последний воспроизведенный медиафайл, PlaybackStateCompat и очередь.

Добавить пользовательские действия воспроизведения

Вы можете добавить пользовательские действия воспроизведения, чтобы отобразить дополнительные действия, поддерживаемые вашим медиаприложением. Если позволяет место (и вы его не зарезервировали), Android добавляет пользовательские действия в элементы управления воспроизведением. В противном случае пользовательские действия отображаются в меню Overflow . Android отображает пользовательские действия в том порядке, в котором вы их добавляете в PlaybackStateCompat .

Используйте пользовательские действия для реализации поведения, отличного от стандартных . Не используйте их для замены или дублирования стандартных действий.

Чтобы добавить пользовательские действия, используйте метод addCustomAction в классе PlaybackStateCompat.Builder . Этот фрагмент кода показывает, как добавить пользовательское действие «Запустить радиоканал»:

Котлин

val customActionExtras = Bundle()
customActionExtras.putInt(
  androidx.media3.session.MediaConstants.EXTRAS_KEY_COMMAND_BUTTON_ICON_COMPAT,
  androidx.media3.session.CommandButton.ICON_RADIO)

stateBuilder.addCustomAction(
    PlaybackStateCompat.CustomAction.Builder(
        CUSTOM_ACTION_START_RADIO_FROM_MEDIA,
        resources.getString(R.string.start_radio_from_media),
        startRadioFromMediaIcon // or R.drawable.media3_icon_radio
    ).run {
        setExtras(customActionExtras)
        build()
    }
)

Ява

Bundle customActionExtras = new Bundle();
customActionExtras.putInt(
  androidx.media3.session.MediaConstants.EXTRAS_KEY_COMMAND_BUTTON_ICON_COMPAT,
  androidx.media3.session.CommandButton.ICON_RADIO);

stateBuilder.addCustomAction(
    new PlaybackStateCompat.CustomAction.Builder(
        CUSTOM_ACTION_START_RADIO_FROM_MEDIA,
        resources.getString(R.string.start_radio_from_media),
        startRadioFromMediaIcon) // or R.drawable.media3_icon_radio
    .setExtras(customActionExtras)
    .build());

Более подробный пример этого метода см. в методе setCustomAction в примере приложения Universal Android Music Player на GitHub. После создания настраиваемого действия ваш медиасеанс может реагировать на него, переопределяя метод onCustomAction .

В этом фрагменте кода показано, как ваше приложение может отреагировать на действие «Запустить радиоканал»:

Котлин

override fun onCustomAction(action: String, extras: Bundle?) {
    when(action) {
        CUSTOM_ACTION_START_RADIO_FROM_MEDIA -> {
            ...
        }
    }
}

Ява

@Override
public void onCustomAction(@NonNull String action, Bundle extras) {
    if (CUSTOM_ACTION_START_RADIO_FROM_MEDIA.equals(action)) {
        ...
    }
}

Для получения более подробной информации ознакомьтесь с методом onCustomAction в примере приложения Universal Android Music Player на GitHub.

Создавайте значки для пользовательских действий

Для каждого создаваемого вами пользовательского действия требуется значок.

Если описание этого значка совпадает с одной из констант CommandButton.ICON_ , задайте целочисленное значение для ключа EXTRAS_KEY_COMMAND_BUTTON_ICON_COMPAT дополнительных параметров настраиваемого действия. В поддерживаемых системах это переопределяет ресурс значка, переданный в CustomAction.Builder , что позволяет системным компонентам согласованно отображать ваше действие и другие действия воспроизведения.

Необходимо также указать ресурс значка. Приложения в автомобилях могут работать на экранах с различными размерами и плотностью пикселей, поэтому предоставляемые значки должны быть векторными . Используйте векторные значки для масштабирования объектов без потери детализации. Векторные значки позволяют выравнивать края и углы по границам пикселей при низком разрешении.

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

Предоставить альтернативные стили значков для отключенных действий

Если настраиваемое действие недоступно для текущего контекста, замените значок настраиваемого действия альтернативным значком, показывающим, что действие отключено.

Рисунок 1. Примеры нестандартных значков пользовательских действий.

Укажите аудиоформат

Чтобы указать, что воспроизводимый медиафайл использует специальный аудиоформат, можно указать значки, которые отображаются в автомобилях, поддерживающих эту функцию. Можно задать параметры KEY_CONTENT_FORMAT_TINTABLE_LARGE_ICON_URI и KEY_CONTENT_FORMAT_TINTABLE_SMALL_ICON_URI в пакете дополнительных параметров текущего воспроизводимого медиафайла (передаваемом в MediaSession.setMetadata ). Установите оба параметра для поддержки различных макетов.

Кроме того, вы можете установить дополнительный параметр KEY_IMMERSIVE_AUDIO , чтобы сообщить производителям оригинального оборудования автомобилей, что это иммерсивный звук, и им следует быть очень осторожными, решая, следует ли применять аудиоэффекты, которые могут помешать иммерсивному контенту.

Добавить ссылки из текущего воспроизводимого объекта

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

Чтобы добавить ссылки, настройте метаданные KEY_SUBTITLE_LINK_MEDIA_ID (для ссылки из субтитров) или KEY_DESCRIPTION_LINK_MEDIA_ID (для ссылки из описания). Подробнее см. в справочной документации по этим полям метаданных.