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

Для включения воспроизведения мультимедиа в 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 для вашего приложения. В следующем разделе будет рассмотрено, как реализовать этот объект.

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

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

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

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

onPrepare

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

onPlay

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

onPlayFromMediaId

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

onPlayFromSearch

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

onPause

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

onSkipToNext

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

onSkipToPrevious

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

onStop

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

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

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

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

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

Вы можете добавить пользовательские действия воспроизведения, чтобы отображать дополнительные действия, поддерживаемые вашим медиаприложением. Если позволяет место (и вы его не резервируете), Android добавляет пользовательские действия к элементам управления воспроизведением. В противном случае пользовательские действия отображаются в меню «Переполнение» . 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 , что позволяет системным компонентам согласованно отображать ваше действие и другие действия воспроизведения.

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

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

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

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

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

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

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

Добавить ссылки из воспроизводимого в данный момент элемента

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

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