Создавайте мультимедийные приложения для автомобилей

Android Auto и Android Automotive OS помогут вам донести контент вашего мультимедийного приложения до пользователей в автомобиле. Медиа-приложение для автомобилей должно предоставлять службу медиа-браузера, чтобы Android Auto и ОС Android Automotive или другое приложение с медиа-браузером могли обнаруживать и отображать ваш контент.

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

В этом руководстве описаны обязательные компоненты MediaBrowserService и MediaSession , необходимые вашему приложению для работы в Android Auto или Android Automotive OS. После завершения создания базовой медиа-инфраструктуры вы можете добавить поддержку Android Auto и ОС Android Automotive в свое мультимедийное приложение.

Прежде чем начать

1. Ознакомьтесь с документацией по Android Media API .
2. Ознакомьтесь с рекомендациями по созданию мультимедийных приложений .
3. Ознакомьтесь с ключевыми терминами и понятиями, перечисленными в этом разделе.

Ключевые термины и понятия

Служба медиабраузера

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

Медиа-браузер

API, используемый мультимедийными приложениями для обнаружения служб медиа-браузера и отображения их содержимого. Android Auto и Android Automotive OS используют медиабраузер для поиска службы медиабраузера вашего приложения.

Медиа-элемент

Медиабраузер организует свое содержимое в виде дерева объектов MediaItem . Медиа-элемент может иметь один или оба следующих флага:

• FLAG_PLAYABLE : указывает, что элемент является листом дерева содержимого. Этот элемент представляет собой один звуковой поток, например песню в альбоме, главу аудиокниги или эпизод подкаста.
• FLAG_BROWSABLE : указывает, что элемент является узлом в дереве контента и имеет дочерние элементы. Например, элемент представляет альбом, а его дочерние элементы — это песни в альбоме.

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

Оптимизирован для транспортных средств

Действие для приложения Android Automotive OS, которое соответствует рекомендациям по проектированию Android Automotive OS . Интерфейс для этих действий не создается ОС Android Automotive, поэтому вы должны убедиться, что ваше приложение соответствует рекомендациям по проектированию. Обычно это включает в себя более крупные объекты касания и размеры шрифта, поддержку дневного и ночного режимов и более высокий коэффициент контрастности.

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

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

Настройте файлы манифеста вашего приложения

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

Объявите службу медиабраузера

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

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

<application>
    ...
    <service android:name=".MyMediaBrowserService"
             android:exported="true">
        <intent-filter>
            <action android:name="android.media.browse.MediaBrowserService"/>
        </intent-filter>
    </service>
    ...
</application>

Укажите значки приложений

Вам необходимо указать значки приложений, которые Android Auto и ОС Android Automotive могут использовать для представления вашего приложения в системном пользовательском интерфейсе. Требуются два типа значков:

• Значок запуска
• Значок атрибуции

Значок запуска

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

<application
    ...
    android:icon="@mipmap/ic_launcher"
    ...
/>

Чтобы использовать значок, отличный от значка вашего мобильного приложения, установите свойство android:icon в элементе <service> службы медиабраузера в манифесте:

<application>
    ...
    <service
        ...
        android:icon="@mipmap/auto_launcher"
        ...
    />
</application>

Значок атрибуции

Рис. 1. Значок указания авторства на медиа-карте.

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

<application>
    ...
    <meta-data
        android:name="androidx.car.app.TintableAttributionIcon"
        android:resource="@drawable/ic_status_icon" />
    ...
</application>

Создайте свой сервис медиабраузера

Вы создаете службу медиабраузера, расширяя класс MediaBrowserServiceCompat . И Android Auto, и Android Automotive OS смогут использовать ваш сервис для следующих целей:

• Просмотрите иерархию контента вашего приложения, чтобы представить пользователю меню.
• Получите токен для объекта MediaSessionCompat вашего приложения, чтобы управлять воспроизведением звука.

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

Рабочий процесс службы медиабраузера

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

1. Пользователь запускает ваше приложение на ОС Android Automotive или Android Auto.
2. ОС Android Automotive или Android Auto связывается со службой медиабраузера вашего приложения с помощью метода onCreate() . В вашей реализации метода onCreate() вы должны создать и зарегистрировать объект MediaSessionCompat и его объект обратного вызова.
3. ОС Android Automotive или Android Auto вызывает метод onGetRoot() вашей службы, чтобы получить корневой элемент мультимедиа в иерархии контента. Корневой элемент мультимедиа не отображается; вместо этого он используется для получения большего количества контента из вашего приложения.
4. ОС Android Automotive или Android Auto вызывает метод onLoadChildren() вашей службы, чтобы получить дочерние элементы корневого элемента мультимедиа. Android Automotive OS и Android Auto отображают эти мультимедийные элементы как элементы контента верхнего уровня. См. Структурирование корневого меню на этой странице для получения дополнительной информации о том, что система ожидает на этом уровне.
5. Если пользователь выбирает просматриваемый элемент мультимедиа, метод onLoadChildren() вашего сервиса вызывается снова для получения дочерних элементов выбранного элемента меню.
6. Если пользователь выбирает воспроизводимый элемент мультимедиа, Android Automotive OS или Android Auto вызывает соответствующий метод обратного вызова сеанса мультимедиа для выполнения этого действия.
7. Если это поддерживается вашим приложением, пользователь также может выполнять поиск по вашему контенту. В этом случае Android Automotive OS или Android Auto вызывают метод onSearch() вашей службы.

Создайте свою иерархию контента

Android Auto и Android Automotive OS вызывают службу медиабраузера вашего приложения, чтобы узнать, какой контент доступен. Для поддержки этого вам необходимо реализовать два метода в службе медиабраузера: onGetRoot() и onLoadChildren()

Реализация onGetRoot

Метод onGetRoot() вашего сервиса возвращает информацию о корневом узле вашей иерархии контента. Android Auto и Android Automotive OS используют этот корневой узел для запроса остального контента с помощью метода onLoadChildren() .

В следующем фрагменте кода показана простая реализация метода onGetRoot() :

override fun onGetRoot(
    clientPackageName: String,
    clientUid: Int,
    rootHints: Bundle?
): BrowserRoot? =
    // Verify that the specified package is allowed to access your
    // content. You'll need to write your own logic to do this.
    if (!isValid(clientPackageName, clientUid)) {
        // If the request comes from an untrusted package, return null.
        // No further calls will be made to other media browsing methods.

        null
    } else MediaBrowserServiceCompat.BrowserRoot(MY_MEDIA_ROOT_ID, null)

@Override
public BrowserRoot onGetRoot(String clientPackageName, int clientUid,
    Bundle rootHints) {

    // Verify that the specified package is allowed to access your
    // content. You'll need to write your own logic to do this.
    if (!isValid(clientPackageName, clientUid)) {
        // If the request comes from an untrusted package, return null.
        // No further calls will be made to other media browsing methods.

        return null;
    }

    return new MediaBrowserServiceCompat.BrowserRoot(MY_MEDIA_ROOT_ID, null);
}

Более подробный пример этого метода см. в методе onGetRoot() в примере приложения Universal Android Music Player на GitHub.

Добавить проверку пакета для onGetRoot()

При вызове метода onGetRoot() вашей службы вызывающий пакет передает идентифицирующую информацию вашей службе. Ваша служба может использовать эту информацию, чтобы решить, может ли этот пакет получить доступ к вашему контенту. Например, вы можете ограничить доступ к содержимому вашего приложения списком одобренных пакетов, сравнив clientPackageName со своим белым списком и проверив сертификат, используемый для подписи APK пакета. Если пакет невозможно проверить, верните null , чтобы запретить доступ к вашему контенту.

Чтобы предоставить системным приложениям, таким как Android Auto и Android Automotive OS, доступ к вашему контенту, ваша служба всегда должна возвращать ненулевой BrowserRoot , когда эти системные приложения вызывают метод onGetRoot() . Подпись системного приложения Android Automotive OS может различаться в зависимости от марки и модели автомобиля, поэтому вам необходимо разрешить подключения всех системных приложений для надежной поддержки Android Automotive OS.

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

fun isKnownCaller(
    callingPackage: String,
    callingUid: Int
): Boolean {
    ...
    val isCallerKnown = when {
       // If the system is making the call, allow it.
       callingUid == Process.SYSTEM_UID -> true
       // If the app was signed by the same certificate as the platform
       // itself, also allow it.
       callerSignature == platformSignature -> true
       // ... more cases
    }
    return isCallerKnown
}

Этот фрагмент кода представляет собой отрывок из класса PackageValidator в примере приложения Universal Android Music Player на GitHub. См. этот класс для более подробного примера того, как реализовать проверку пакета для метода onGetRoot() вашего сервиса.

Помимо разрешения системных приложений, вы должны разрешить Google Assistant подключаться к вашему MediaBrowserService . Обратите внимание, что Google Assistant имеет отдельные названия пакетов для телефона, включая Android Auto, и для Android Automotive OS.

Реализация onLoadChildren()

После получения объекта корневого узла Android Auto и Android Automotive OS создают меню верхнего уровня, вызывая onLoadChildren() для объекта корневого узла, чтобы получить его дочерние элементы. Клиентские приложения создают подменю, вызывая тот же метод с использованием объектов дочерних узлов.

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

В следующем фрагменте кода показана простая реализация метода onLoadChildren() :

override fun onLoadChildren(
    parentMediaId: String,
    result: Result<List<MediaBrowserCompat.MediaItem>>
) {
    // Assume for example that the music catalog is already loaded/cached.

    val mediaItems: MutableList<MediaBrowserCompat.MediaItem> = mutableListOf()

    // Check whether this is the root menu:
    if (MY_MEDIA_ROOT_ID == parentMediaId) {

        // Build the MediaItem objects for the top level
        // and put them in the mediaItems list.
    } else {

        // Examine the passed parentMediaId to see which submenu we're at
        // and put the children of that menu in the mediaItems list.
    }
    result.sendResult(mediaItems)
}

@Override
public void onLoadChildren(final String parentMediaId,
    final Result<List<MediaBrowserCompat.MediaItem>> result) {

    // Assume for example that the music catalog is already loaded/cached.

    List<MediaBrowserCompat.MediaItem> mediaItems = new ArrayList<>();

    // Check whether this is the root menu:
    if (MY_MEDIA_ROOT_ID.equals(parentMediaId)) {

        // Build the MediaItem objects for the top level
        // and put them in the mediaItems list.
    } else {

        // Examine the passed parentMediaId to see which submenu we're at
        // and put the children of that menu in the mediaItems list.
    }
    result.sendResult(mediaItems);
}

Полный пример этого метода см. в методе onLoadChildren() в примере приложения Universal Android Music Player на GitHub.

Структурировать корневое меню

Рисунок 2. Корневой контент отображается в виде вкладок навигации.

Android Auto и Android Automotive OS имеют определенные ограничения на структуру корневого меню. Они передаются MediaBrowserService через корневые подсказки, которые можно прочитать с помощью аргумента Bundle переданного в onGetRoot() . Следование этим подсказкам позволяет системе оптимально отображать корневой контент в виде навигационных вкладок. Если вы не последуете этим подсказкам, некоторый корневой контент может быть удален или станет менее доступным для обнаружения системой. Отправляются две подсказки:

• Ограничение на количество корневых дочерних элементов : в большинстве случаев можно ожидать, что это число будет равно четырем. Это означает, что невозможно отобразить более четырех вкладок.
• Поддерживаемые флаги для корневых дочерних элементов : вы можете ожидать, что это значение будет MediaItem#FLAG_BROWSABLE . Это означает, что в виде вкладок могут отображаться только элементы, доступные для просмотра, а не воспроизводимые.

Используйте следующий код, чтобы прочитать соответствующие корневые подсказки:

import androidx.media.utils.MediaConstants

// Later, in your MediaBrowserServiceCompat.
override fun onGetRoot(
    clientPackageName: String,
    clientUid: Int,
    rootHints: Bundle
): BrowserRoot {

  val maximumRootChildLimit = rootHints.getInt(
      MediaConstants.BROWSER_ROOT_HINTS_KEY_ROOT_CHILDREN_LIMIT,
      /* defaultValue= */ 4)
  val supportedRootChildFlags = rootHints.getInt(
      MediaConstants.BROWSER_ROOT_HINTS_KEY_ROOT_CHILDREN_SUPPORTED_FLAGS,
      /* defaultValue= */ MediaItem.FLAG_BROWSABLE)

  // Rest of method...
}

import androidx.media.utils.MediaConstants;

// Later, in your MediaBrowserServiceCompat.
@Override
public BrowserRoot onGetRoot(
    String clientPackageName, int clientUid, Bundle rootHints) {

    int maximumRootChildLimit = rootHints.getInt(
        MediaConstants.BROWSER_ROOT_HINTS_KEY_ROOT_CHILDREN_LIMIT,
        /* defaultValue= */ 4);
    int supportedRootChildFlags = rootHints.getInt(
        MediaConstants.BROWSER_ROOT_HINTS_KEY_ROOT_CHILDREN_SUPPORTED_FLAGS,
        /* defaultValue= */ MediaItem.FLAG_BROWSABLE);

    // Rest of method...
}

Вы можете выбрать разветвление логики структуры иерархии контента на основе значений этих подсказок, особенно если ваша иерархия различается в зависимости от интеграции MediaBrowser за пределами Android Auto и Android Automotive OS. Например, если вы обычно показываете корневой воспроизводимый элемент, вместо этого вы можете захотеть вложить его под корневой просматриваемый элемент из-за значения подсказки поддерживаемых флагов.

Помимо корневых подсказок, есть еще несколько рекомендаций, которые помогут обеспечить оптимальное отображение вкладок:

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

Отображение медиа-иллюстраций

Графическое изображение для элементов мультимедиа должно передаваться как локальный URI с помощью ContentResolver.SCHEME_CONTENT или ContentResolver.SCHEME_ANDROID_RESOURCE . Этот локальный URI должен разрешаться либо в растровое изображение, либо в вектор, который можно нарисовать в ресурсах приложения. Для объектов MediaDescriptionCompat , представляющих элементы в иерархии контента, передайте URI через setIconUri() . Для объектов MediaMetadataCompat , представляющих воспроизводимый в данный момент элемент, передайте URI через putString() , используя любой из следующих ключей:

• MediaMetadataCompat.METADATA_KEY_DISPLAY_ICON_URI
• MediaMetadataCompat.METADATA_KEY_ART_URI
• MediaMetadataCompat.METADATA_KEY_ALBUM_ART_URI

Следующие шаги описывают, как загрузить произведение искусства из веб-URI и предоставить его через локальный URI. Более полный пример см. в реализации openFile() и связанных с ним методов в примере приложения Universal Android Music Player.

1. Создайте URI content:// , соответствующий веб-URI. Служба медиабраузера и медиасеанс передают этот URI контента в Android Auto и Android Automotive OS.

   Котлин

   fun Uri.asAlbumArtContentURI(): Uri {
     return Uri.Builder()
       .scheme(ContentResolver.SCHEME_CONTENT)
       .authority(CONTENT_PROVIDER_AUTHORITY)
       .appendPath(this.getPath()) // Make sure you trust the URI
       .build()
   }
   

   Ява

   public static Uri asAlbumArtContentURI(Uri webUri) {
     return new Uri.Builder()
       .scheme(ContentResolver.SCHEME_CONTENT)
       .authority(CONTENT_PROVIDER_AUTHORITY)
       .appendPath(webUri.getPath()) // Make sure you trust the URI!
       .build();
   }
   

2. В вашей реализации ContentProvider.openFile() проверьте, существует ли файл для соответствующего URI. Если нет, загрузите и кэшируйте файл изображения. В следующем фрагменте кода используется Glide .

   Котлин

   override fun openFile(uri: Uri, mode: String): ParcelFileDescriptor? {
     val context = this.context ?: return null
     val file = File(context.cacheDir, uri.path)
     if (!file.exists()) {
       val remoteUri = Uri.Builder()
           .scheme("https")
           .authority("my-image-site")
           .appendPath(uri.path)
           .build()
       val cacheFile = Glide.with(context)
           .asFile()
           .load(remoteUri)
           .submit()
           .get(DOWNLOAD_TIMEOUT_SECONDS, TimeUnit.SECONDS)
   
       cacheFile.renameTo(file)
       file = cacheFile
     }
     return ParcelFileDescriptor.open(file, ParcelFileDescriptor.MODE_READ_ONLY)
   }
   

   Ява

   @Nullable
   @Override
   public ParcelFileDescriptor openFile(@NonNull Uri uri, @NonNull String mode)
       throws FileNotFoundException {
     Context context = this.getContext();
     File file = new File(context.getCacheDir(), uri.getPath());
     if (!file.exists()) {
       Uri remoteUri = new Uri.Builder()
           .scheme("https")
           .authority("my-image-site")
           .appendPath(uri.getPath())
           .build();
       File cacheFile = Glide.with(context)
           .asFile()
           .load(remoteUri)
           .submit()
           .get(DOWNLOAD_TIMEOUT_SECONDS, TimeUnit.SECONDS);
   
       cacheFile.renameTo(file);
       file = cacheFile;
     }
     return ParcelFileDescriptor.open(file, ParcelFileDescriptor.MODE_READ_ONLY);
   }
   

Дополнительные сведения о поставщиках контента см. в разделе Создание поставщика контента .

Применение стилей контента

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

Вы можете использовать следующие стили контента:

Список элементов

Этот стиль контента отдает приоритет заголовкам и метаданным над изображениями.

Элементы сетки

Этот стиль контента отдает приоритет изображениям над заголовками и метаданными.

Установить стили контента по умолчанию

Вы можете установить глобальные настройки по умолчанию для отображения ваших медиа-элементов, включив определенные константы в пакет дополнительных возможностей BrowserRoot метода onGetRoot() вашей службы. Android Auto и Android Automotive OS читают этот пакет и находят эти константы, чтобы определить подходящий стиль.

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

• DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_BROWSABLE : указывает подсказку представления для всех доступных для просмотра элементов в дереве просмотра.
• DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_PLAYABLE : указывает подсказку представления для всех воспроизводимых элементов в дереве просмотра.

Ключи могут сопоставляться со следующими целочисленными константами, чтобы влиять на представление этих элементов:

• DESCRIPTION_EXTRAS_VALUE_CONTENT_STYLE_LIST_ITEM : соответствующие элементы представлены в виде элементов списка.
• DESCRIPTION_EXTRAS_VALUE_CONTENT_STYLE_GRID_ITEM : соответствующие элементы представлены в виде элементов сетки.
• DESCRIPTION_EXTRAS_VALUE_CONTENT_STYLE_CATEGORY_LIST_ITEM : соответствующие элементы представлены как элементы списка «категории». Они аналогичны обычным элементам списка, за исключением того, что вокруг значков элементов применяются поля, поскольку значки выглядят лучше, когда они маленькие. Значки должны быть раскрашиваемыми векторными изображениями. Ожидается, что эта подсказка будет предоставляться только для элементов, доступных для просмотра.
• DESCRIPTION_EXTRAS_VALUE_CONTENT_STYLE_CATEGORY_GRID_ITEM : соответствующие элементы представлены как элементы сетки «категории». Они аналогичны обычным элементам сетки, за исключением того, что вокруг значков элементов применяются поля, поскольку значки выглядят лучше, когда они маленькие. Значки должны быть раскрашиваемыми векторными изображениями. Ожидается, что эта подсказка будет предоставляться только для элементов, доступных для просмотра.

В следующем фрагменте кода показано, как установить стиль контента по умолчанию для просматриваемых элементов в виде сеток, а для воспроизводимых элементов — в виде списков:

import androidx.media.utils.MediaConstants

@Nullable
override fun onGetRoot(
    @NonNull clientPackageName: String,
    clientUid: Int,
    @Nullable rootHints: Bundle
): BrowserRoot {
    val extras = Bundle()
    extras.putInt(
        MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_BROWSABLE,
        MediaConstants.DESCRIPTION_EXTRAS_VALUE_CONTENT_STYLE_GRID_ITEM)
    extras.putInt(
        MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_PLAYABLE,
        MediaConstants.DESCRIPTION_EXTRAS_VALUE_CONTENT_STYLE_LIST_ITEM)
    return BrowserRoot(ROOT_ID, extras)
}

import androidx.media.utils.MediaConstants;

@Nullable
@Override
public BrowserRoot onGetRoot(
    @NonNull String clientPackageName,
    int clientUid,
    @Nullable Bundle rootHints) {
    Bundle extras = new Bundle();
    extras.putInt(
        MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_BROWSABLE,
        MediaConstants.DESCRIPTION_EXTRAS_VALUE_CONTENT_STYLE_GRID_ITEM);
    extras.putInt(
        MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_PLAYABLE,
        MediaConstants.DESCRIPTION_EXTRAS_VALUE_CONTENT_STYLE_LIST_ITEM);
    return new BrowserRoot(ROOT_ID, extras);
}

Установите стили контента для каждого элемента

API стиля контента позволяет переопределить стиль контента по умолчанию для любого дочернего элемента просматриваемого медиа-элемента, а также для любого самого медиа-элемента.

Чтобы переопределить значение по умолчанию для дочерних элементов просматриваемого элемента мультимедиа, создайте дополнительный пакет в MediaDescription элемента мультимедиа и добавьте те же самые ранее упомянутые подсказки. DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_PLAYABLE применяется к воспроизводимым дочерним элементам этого элемента, а DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_BROWSABLE применяется к доступным для просмотра дочерним элементам этого элемента.

Чтобы переопределить значение по умолчанию для самого конкретного медиа-элемента, а не для его дочерних элементов, создайте дополнительный пакет в MediaDescription медиа-элемента и добавьте подсказку с ключом DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_SINGLE_ITEM . Используйте те же значения, которые были описаны ранее, чтобы указать представление этого элемента.

В следующем фрагменте кода показано, как создать просматриваемый объект MediaItem , который переопределяет стиль контента по умолчанию как для себя, так и для своих дочерних элементов. Он оформляет себя как элемент списка категорий, его просматриваемые дочерние элементы — как элементы списка, а его воспроизводимые дочерние элементы — как элементы сетки:

import androidx.media.utils.MediaConstants

private fun createBrowsableMediaItem(
    mediaId: String,
    folderName: String,
    iconUri: Uri
): MediaBrowser.MediaItem {
    val mediaDescriptionBuilder = MediaDescription.Builder()
    mediaDescriptionBuilder.setMediaId(mediaId)
    mediaDescriptionBuilder.setTitle(folderName)
    mediaDescriptionBuilder.setIconUri(iconUri)
    val extras = Bundle()
    extras.putInt(
        MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_SINGLE_ITEM,
        MediaConstants.DESCRIPTION_EXTRAS_VALUE_CONTENT_STYLE_CATEGORY_LIST_ITEM)
    extras.putInt(
        MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_BROWSABLE,
        MediaConstants.DESCRIPTION_EXTRAS_VALUE_CONTENT_STYLE_LIST_ITEM)
    extras.putInt(
        MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_PLAYABLE,
        MediaConstants.DESCRIPTION_EXTRAS_VALUE_CONTENT_STYLE_GRID_ITEM)
    mediaDescriptionBuilder.setExtras(extras)
    return MediaBrowser.MediaItem(
        mediaDescriptionBuilder.build(), MediaBrowser.MediaItem.FLAG_BROWSABLE)
}

import androidx.media.utils.MediaConstants;

private MediaBrowser.MediaItem createBrowsableMediaItem(
    String mediaId,
    String folderName,
    Uri iconUri) {
    MediaDescription.Builder mediaDescriptionBuilder = new MediaDescription.Builder();
    mediaDescriptionBuilder.setMediaId(mediaId);
    mediaDescriptionBuilder.setTitle(folderName);
    mediaDescriptionBuilder.setIconUri(iconUri);
    Bundle extras = new Bundle();
    extras.putInt(
        MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_SINGLE_ITEM,
        MediaConstants.DESCRIPTION_EXTRAS_VALUE_CONTENT_STYLE_CATEGORY_LIST_ITEM);
    extras.putInt(
        MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_BROWSABLE,
        MediaConstants.DESCRIPTION_EXTRAS_VALUE_CONTENT_STYLE_LIST_ITEM);
    extras.putInt(
        MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_PLAYABLE,
        MediaConstants.DESCRIPTION_EXTRAS_VALUE_CONTENT_STYLE_GRID_ITEM);
    mediaDescriptionBuilder.setExtras(extras);
    return new MediaBrowser.MediaItem(
        mediaDescriptionBuilder.build(), MediaBrowser.MediaItem.FLAG_BROWSABLE);
}

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

Чтобы сгруппировать связанные элементы мультимедиа вместе, вы используете подсказку для каждого элемента. Каждый медиа-элемент в группе должен объявить дополнительный пакет в своем MediaDescription , который включает в себя сопоставление с ключом DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE и идентичным строковым значением. Локализуйте эту строку, которая используется в качестве названия группы.

В следующем фрагменте кода показано, как создать MediaItem с заголовком подгруппы "Songs" :

import androidx.media.utils.MediaConstants

private fun createMediaItem(
    mediaId: String,
    folderName: String,
    iconUri: Uri
): MediaBrowser.MediaItem {
    val mediaDescriptionBuilder = MediaDescription.Builder()
    mediaDescriptionBuilder.setMediaId(mediaId)
    mediaDescriptionBuilder.setTitle(folderName)
    mediaDescriptionBuilder.setIconUri(iconUri)
    val extras = Bundle()
    extras.putString(
        MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE,
        "Songs")
    mediaDescriptionBuilder.setExtras(extras)
    return MediaBrowser.MediaItem(
        mediaDescriptionBuilder.build(), /* playable or browsable flag*/)
}

import androidx.media.utils.MediaConstants;

private MediaBrowser.MediaItem createMediaItem(String mediaId, String folderName, Uri iconUri) {
   MediaDescription.Builder mediaDescriptionBuilder = new MediaDescription.Builder();
   mediaDescriptionBuilder.setMediaId(mediaId);
   mediaDescriptionBuilder.setTitle(folderName);
   mediaDescriptionBuilder.setIconUri(iconUri);
   Bundle extras = new Bundle();
   extras.putString(
       MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE,
       "Songs");
   mediaDescriptionBuilder.setExtras(extras);
   return new MediaBrowser.MediaItem(
       mediaDescriptionBuilder.build(), /* playable or browsable flag*/);
}

Ваше приложение должно передавать все элементы мультимедиа, которые вы хотите сгруппировать в виде непрерывного блока. Например, предположим, что вы хотите отображать две группы медиа-элементов: «Песни» и «Альбомы» в этом порядке, и ваше приложение передает пять медиа-элементов в следующем порядке:

1. Медиа-элемент A с extras.putString(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE, "Songs" )
2. Медиа-элемент B с extras.putString(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE, "Albums" )
3. Медиа-элемент C с extras.putString(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE, "Songs" )
4. Медиа-элемент D с extras.putString(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE, "Songs" )
5. Медиа-элемент E с extras.putString(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE, "Albums" )

Поскольку элементы мультимедиа для групп «Песни» и «Альбомы» не хранятся вместе в смежных блоках, Android Auto и Android Automotive OS интерпретируют это как следующие четыре группы:

• Группа 1 под названием «Песни», содержащая медиа-элемент A.
• Группа 2 под названием «Альбомы» содержит элемент мультимедиа B.
• Группа 3 под названием «Песни» содержит мультимедийные элементы C и D.
• Группа 4 под названием «Альбомы» содержит элемент мультимедиа E.

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

1. Медиа-элемент A с extras.putString(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE, "Songs" )
2. Медиа-элемент C с extras.putString(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE, "Songs" )
3. Медиа-элемент D с extras.putString(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE, "Songs" )
4. Медиа-элемент B с extras.putString(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE, "Albums" )
5. Медиа-элемент E с extras.putString(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE, "Albums" )

Отображение дополнительных индикаторов метаданных

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

Рисунок 3. Представление воспроизведения с метаданными, идентифицирующими песню и исполнителя, а также значком, обозначающим непристойное содержимое.

Рис. 4. Представление просмотра с точкой для невоспроизведенного контента в первом элементе и индикатором выполнения для частично воспроизведенного контента во втором элементе.

Следующие константы можно использовать как в дополнительных описаниях MediaItem , так и в дополнительных компонентах MediaMetadata :

• EXTRA_DOWNLOAD_STATUS : указывает статус загрузки элемента. Используйте эту константу как ключ; Возможными значениями являются следующие длинные константы:
  • STATUS_DOWNLOADED : элемент полностью загружен.
  • STATUS_DOWNLOADING : элемент загружается.
  • STATUS_NOT_DOWNLOADED : элемент не загружен.
• METADATA_KEY_IS_EXPLICIT : указывает, содержит ли элемент явный контент. Чтобы указать, что элемент является явным, используйте эту константу в качестве ключа и длинное METADATA_VALUE_ATTRIBUTE_PRESENT в качестве значения.

Следующие константы можно использовать только в дополнительных описаниях MediaItem :

• DESCRIPTION_EXTRAS_KEY_COMPLETION_STATUS : указывает на состояние завершения длинного контента, например эпизодов подкастов или аудиокниг. Используйте эту константу как ключ; Возможными значениями являются следующие целочисленные константы:
  • DESCRIPTION_EXTRAS_VALUE_COMPLETION_STATUS_NOT_PLAYED : элемент вообще не воспроизводился.
  • DESCRIPTION_EXTRAS_VALUE_COMPLETION_STATUS_PARTIALLY_PLAYED : элемент был воспроизведен частично, и текущая позиция находится где-то посередине.
  • DESCRIPTION_EXTRAS_VALUE_COMPLETION_STATUS_FULLY_PLAYED : элемент выполнен.
• DESCRIPTION_EXTRAS_KEY_COMPLETION_PERCENTAGE : указывает степень выполнения длинного контента в виде двойного значения от 0,0 до 1,0 включительно. Это дополнение предоставляет дополнительную информацию о состоянии PARTIALLY_PLAYING , чтобы Android Auto или Android Automotive OS отображали более значимый индикатор прогресса, например индикатор выполнения. Если вы используете эту дополнительную функцию, см. раздел об обновлении индикатора выполнения в представлении просмотра во время воспроизведения контента в этом руководстве, чтобы узнать, как поддерживать этот индикатор в актуальном состоянии после его первоначального показа.

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

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

import androidx.media.utils.MediaConstants

val extras = Bundle()
extras.putLong(
    MediaConstants.METADATA_KEY_IS_EXPLICIT,
    MediaConstants.METADATA_VALUE_ATTRIBUTE_PRESENT)
extras.putInt(
    MediaConstants.DESCRIPTION_EXTRAS_KEY_COMPLETION_STATUS,
    MediaConstants.DESCRIPTION_EXTRAS_VALUE_COMPLETION_STATUS_PARTIALLY_PLAYED)
extras.putDouble(
    MediaConstants.DESCRIPTION_EXTRAS_KEY_COMPLETION_PERCENTAGE, 0.7)
val description =
    MediaDescriptionCompat.Builder()
        .setMediaId(/*...*/)
        .setTitle(resources.getString(/*...*/))
        .setExtras(extras)
        .build()
return MediaBrowserCompat.MediaItem(description, /* flags */)

import androidx.media.utils.MediaConstants;

Bundle extras = new Bundle();
extras.putLong(
    MediaConstants.METADATA_KEY_IS_EXPLICIT,
    MediaConstants.METADATA_VALUE_ATTRIBUTE_PRESENT);
extras.putInt(
    MediaConstants.DESCRIPTION_EXTRAS_KEY_COMPLETION_STATUS,
    MediaConstants.DESCRIPTION_EXTRAS_VALUE_COMPLETION_STATUS_PARTIALLY_PLAYED);
extras.putDouble(
    MediaConstants.DESCRIPTION_EXTRAS_KEY_COMPLETION_PERCENTAGE, 0.7);
MediaDescriptionCompat description =
    new MediaDescriptionCompat.Builder()
        .setMediaId(/*...*/)
        .setTitle(resources.getString(/*...*/))
        .setExtras(extras)
        .build();
return new MediaBrowserCompat.MediaItem(description, /* flags */);

Чтобы отобразить индикаторы для воспроизводимого в данный момент медиа-элемента, вы можете объявить Long значения для METADATA_KEY_IS_EXPLICIT или EXTRA_DOWNLOAD_STATUS в MediaMetadataCompat вашего mediaSession . Вы не можете отображать индикаторы DESCRIPTION_EXTRAS_KEY_COMPLETION_STATUS или DESCRIPTION_EXTRAS_KEY_COMPLETION_PERCENTAGE в режиме воспроизведения.

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

import androidx.media.utils.MediaConstants

mediaSession.setMetadata(
    MediaMetadataCompat.Builder()
        .putString(
            MediaMetadataCompat.METADATA_KEY_DISPLAY_TITLE, "Song Name")
        .putString(
            MediaMetadataCompat.METADATA_KEY_DISPLAY_SUBTITLE, "Artist name")
        .putString(
            MediaMetadataCompat.METADATA_KEY_ALBUM_ART_URI,
            albumArtUri.toString())
        .putLong(
            MediaConstants.METADATA_KEY_IS_EXPLICIT,
            MediaConstants.METADATA_VALUE_ATTRIBUTE_PRESENT)
        .putLong(
            MediaDescriptionCompat.EXTRA_DOWNLOAD_STATUS,
            MediaDescriptionCompat.STATUS_DOWNLOADED)
        .build())

import androidx.media.utils.MediaConstants;

mediaSession.setMetadata(
    new MediaMetadataCompat.Builder()
        .putString(
            MediaMetadataCompat.METADATA_KEY_DISPLAY_TITLE, "Song Name")
        .putString(
            MediaMetadataCompat.METADATA_KEY_DISPLAY_SUBTITLE, "Artist name")
        .putString(
            MediaMetadataCompat.METADATA_KEY_ALBUM_ART_URI,
            albumArtUri.toString())
        .putLong(
            MediaConstants.METADATA_KEY_IS_EXPLICIT,
            MediaConstants.METADATA_VALUE_ATTRIBUTE_PRESENT)
        .putLong(
            MediaDescriptionCompat.EXTRA_DOWNLOAD_STATUS,
            MediaDescriptionCompat.STATUS_DOWNLOADED)
        .build());

Обновлять индикатор выполнения в режиме просмотра по мере воспроизведения контента.

Как упоминалось ранее, вы можете использовать дополнительную опцию DESCRIPTION_EXTRAS_KEY_COMPLETION_PERCENTAGE , чтобы отображать индикатор выполнения для частично воспроизведенного контента в режиме просмотра. Однако если пользователь продолжает воспроизводить частично воспроизведенный контент из Android Auto или Android Automotive OS, с течением времени этот индикатор становится неточным.

Чтобы Android Auto и Android Automotive OS постоянно обновляли индикатор выполнения, вы можете предоставить дополнительную информацию в MediaMetadataCompat и PlaybackStateCompat , чтобы связать текущий контент с элементами мультимедиа в представлении просмотра. Чтобы элемент мультимедиа имел автоматически обновляемый индикатор выполнения, должны быть выполнены следующие требования:

• При создании MediaItem должен отправить DESCRIPTION_EXTRAS_KEY_COMPLETION_PERCENTAGE в своих дополнительных функциях со значением от 0,0 до 1,0 включительно.
• MediaMetadataCompat должен отправить METADATA_KEY_MEDIA_ID со строковым значением, равным идентификатору носителя, переданному в MediaItem .
• PlaybackStateCompat должен включать дополнительный ключ PLAYBACK_STATE_EXTRAS_KEY_MEDIA_ID , который сопоставляется со строковым значением, равным идентификатору мультимедиа, переданному в MediaItem .

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

import androidx.media.utils.MediaConstants

// When the MediaItem is constructed to show in the browse view.
// Suppose the item was 25% complete when the user launched the browse view.
val mediaItemExtras = Bundle()
mediaItemExtras.putDouble(
    MediaConstants.DESCRIPTION_EXTRAS_KEY_COMPLETION_PERCENTAGE, 0.25)
val description =
    MediaDescriptionCompat.Builder()
        .setMediaId("my-media-id")
        .setExtras(mediaItemExtras)
        // ...and any other setters.
        .build()
return MediaBrowserCompat.MediaItem(description, /* flags */)

// Elsewhere, when the user has selected MediaItem for playback.
mediaSession.setMetadata(
    MediaMetadataCompat.Builder()
        .putString(MediaMetadata.METADATA_KEY_MEDIA_ID, "my-media-id")
        // ...and any other setters.
        .build())

val playbackStateExtras = Bundle()
playbackStateExtras.putString(
    MediaConstants.PLAYBACK_STATE_EXTRAS_KEY_MEDIA_ID, "my-media-id")
mediaSession.setPlaybackState(
    PlaybackStateCompat.Builder()
        .setExtras(playbackStateExtras)
        // ...and any other setters.
        .build())

import androidx.media.utils.MediaConstants;

// When the MediaItem is constructed to show in the browse view.
// Suppose the item was 25% complete when the user launched the browse view.
Bundle mediaItemExtras = new Bundle();
mediaItemExtras.putDouble(
    MediaConstants.DESCRIPTION_EXTRAS_KEY_COMPLETION_PERCENTAGE, 0.25);
MediaDescriptionCompat description =
    new MediaDescriptionCompat.Builder()
        .setMediaId("my-media-id")
        .setExtras(mediaItemExtras)
        // ...and any other setters.
        .build();
return MediaBrowserCompat.MediaItem(description, /* flags */);

// Elsewhere, when the user has selected MediaItem for playback.
mediaSession.setMetadata(
    new MediaMetadataCompat.Builder()
        .putString(MediaMetadata.METADATA_KEY_MEDIA_ID, "my-media-id")
        // ...and any other setters.
        .build());

Bundle playbackStateExtras = new Bundle();
playbackStateExtras.putString(
    MediaConstants.PLAYBACK_STATE_EXTRAS_KEY_MEDIA_ID, "my-media-id");
mediaSession.setPlaybackState(
    new PlaybackStateCompat.Builder()
        .setExtras(playbackStateExtras)
        // ...and any other setters.
        .build());

Отображение доступных для просмотра результатов поиска

Рис. 5. Представление воспроизведения с опцией «Результаты поиска» для просмотра мультимедийных элементов, связанных с голосовым поиском пользователя.

Ваше приложение может предоставлять результаты контекстного поиска, которые отображаются пользователям, когда они инициируют поисковый запрос. Android Auto и Android Automotive OS отображают эти результаты через интерфейсы поисковых запросов или через возможности, которые основаны на запросах, сделанных ранее в сеансе. Дополнительную информацию см. в разделе «Поддержка голосовых действий» данного руководства.

Чтобы отобразить доступные для просмотра результаты поиска, включите постоянный ключ BROWSER_SERVICE_EXTRAS_KEY_SEARCH_SUPPORTED в дополнительный пакет метода onGetRoot() вашей службы, сопоставляя его с логическим значением true .

В следующем фрагменте кода показано, как включить поддержку метода onGetRoot() :

import androidx.media.utils.MediaConstants

@Nullable
fun onGetRoot(
    @NonNull clientPackageName: String,
    clientUid: Int,
    @Nullable rootHints: Bundle
): BrowserRoot {
    val extras = Bundle()
    extras.putBoolean(
        MediaConstants.BROWSER_SERVICE_EXTRAS_KEY_SEARCH_SUPPORTED, true)
    return BrowserRoot(ROOT_ID, extras)
}

import androidx.media.utils.MediaConstants;

@Nullable
@Override
public BrowserRoot onGetRoot(
    @NonNull String clientPackageName,
    int clientUid,
    @Nullable Bundle rootHints) {
    Bundle extras = new Bundle();
    extras.putBoolean(
        MediaConstants.BROWSER_SERVICE_EXTRAS_KEY_SEARCH_SUPPORTED, true);
    return new BrowserRoot(ROOT_ID, extras);
}

Чтобы начать предоставлять результаты поиска, переопределите метод onSearch() в службе медиабраузера. Android Auto и Android Automotive OS перенаправляют условия поиска пользователя в этот метод всякий раз, когда пользователь вызывает интерфейс поискового запроса или функцию «Результаты поиска».

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

В следующем фрагменте кода показана простая реализация метода onSearch() :

fun onSearch(query: String, extras: Bundle) {
  // Detach from results to unblock the caller (if a search is expensive).
  result.detach()
  object:AsyncTask() {
    internal var searchResponse:ArrayList
    internal var succeeded = false
    protected fun doInBackground(vararg params:Void):Void {
      searchResponse = ArrayList()
      if (doSearch(query, extras, searchResponse))
      {
        succeeded = true
      }
      return null
    }
    protected fun onPostExecute(param:Void) {
      if (succeeded)
      {
        // Sending an empty List informs the caller that there were no results.
        result.sendResult(searchResponse)
      }
      else
      {
        // This invokes onError() on the search callback.
        result.sendResult(null)
      }
      return null
    }
  }.execute()
}
// Populates resultsToFill with search results. Returns true on success or false on error.
private fun doSearch(
    query: String,
    extras: Bundle,
    resultsToFill: ArrayList
): Boolean {
  // Implement this method.
}

@Override
public void onSearch(final String query, final Bundle extras,
                        Result<List<MediaItem>> result) {

  // Detach from results to unblock the caller (if a search is expensive).
  result.detach();

  new AsyncTask<Void, Void, Void>() {
    List<MediaItem> searchResponse;
    boolean succeeded = false;
    @Override
    protected Void doInBackground(Void... params) {
      searchResponse = new ArrayList<MediaItem>();
      if (doSearch(query, extras, searchResponse)) {
        succeeded = true;
      }
      return null;
    }

    @Override
    protected void onPostExecute(Void param) {
      if (succeeded) {
       // Sending an empty List informs the caller that there were no results.
       result.sendResult(searchResponse);
      } else {
        // This invokes onError() on the search callback.
        result.sendResult(null);
      }
    }
  }.execute()
}

/** Populates resultsToFill with search results. Returns true on success or false on error. */
private boolean doSearch(String query, Bundle extras, ArrayList<MediaItem> resultsToFill) {
    // Implement this method.
}

Пользовательские действия просмотра

Рисунок 6. Одно настраиваемое действие просмотра

Настраиваемые действия просмотра позволяют добавлять собственные значки и метки к объектам MediaItem вашего приложения в мультимедийном приложении автомобиля и обрабатывать взаимодействие пользователя с этими действиями. Это позволяет вам расширить функциональность мультимедийного приложения различными способами, например добавить действия «Загрузить», «Добавить в очередь», «Воспроизвести радио», «Избранное» или «Удалить».

Рис. 7. Переполнение пользовательского действия просмотра

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

Как они работают?

Каждое пользовательское действие просмотра определяется с помощью:

• Идентификатор действия (уникальный строковый идентификатор)
• Метка действия (текст, отображаемый пользователю)
• URI значка действия (рисуемый вектор, который можно окрашивать)

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

Когда пользователь взаимодействует с настраиваемым действием просмотра, ваше приложение получает обратный вызов в onCustomAction() . Затем вы можете обработать действие и при необходимости обновить список действий для MediaItem . Это полезно для действий с отслеживанием состояния, таких как «Избранное» и «Загрузить». Для действий, которые не требуют обновления, например «Включить радио», список действий обновлять не нужно.

Рис. 8. Панель инструментов «Настраиваемое действие просмотра»

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

Как реализовать пользовательские действия просмотра

Вот шаги по добавлению пользовательских действий просмотра в ваш проект:

1. Переопределите два метода в вашей реализации MediaBrowserServiceCompat :
   • onLoadItem(String itemId, @NonNull Result<MediaBrowserCompat.MediaItem> result)
   • onCustomAction(@NonNull String action, Bundle extras, @NonNull Result<Bundle> result)
2. Анализируйте ограничения действий во время выполнения:
   • В onGetRoot() получите максимальное количество действий, разрешенное для каждого MediaItem , используя ключ BROWSER_ROOT_HINTS_KEY_CUSTOM_BROWSER_ACTION_LIMIT в rootHints Bundle . Ограничение 0 означает, что функция не поддерживается системой.
3. Создайте глобальный список пользовательских действий просмотра:
   • Для каждого действия создайте объект Bundle со следующими ключами: * EXTRAS_KEY_CUSTOM_BROWSER_ACTION_ID : идентификатор действия * EXTRAS_KEY_CUSTOM_BROWSER_ACTION_LABEL : метка действия * EXTRAS_KEY_CUSTOM_BROWSER_ACTION_ICON_URI : URI значка действия * Добавьте все объекты Bundle действия в список.
4. Добавьте глобальный список в свой BrowseRoot :
   • В Bundle дополнительных возможностей BrowseRoot добавьте список действий в виде Parcelable Arraylist , используя ключ BROWSER_SERVICE_EXTRAS_KEY_CUSTOM_BROWSER_ACTION_ROOT_LIST .
5. Добавьте действия к объектам MediaItem :
   • Вы можете добавить действия к отдельным объектам MediaItem , включив список идентификаторов действий в дополнительные элементы MediaDescriptionCompat с помощью ключа DESCRIPTION_EXTRAS_KEY_CUSTOM_BROWSER_ACTION_ID_LIST . Этот список должен быть подмножеством глобального списка действий, определенного вами в BrowseRoot .
6. Обработка действий и возврат прогресса или результатов:
   • В onCustomAction обрабатывайте действие на основе идентификатора действия и любых других необходимых вам данных. Вы можете получить идентификатор MediaItem , который инициировал действие, из дополнений, используя ключ EXTRAS_KEY_CUSTOM_BROWSER_ACTION_MEDIA_ITEM_ID . .
   • Вы можете обновить список действий для MediaItem , включив ключ EXTRAS_KEY_CUSTOM_BROWSER_ACTION_RESULT_REFRESH_ITEM в пакет прогресса или результата.

Вот некоторые изменения, которые вы можете внести в свой BrowserServiceCompat , чтобы начать работу с настраиваемыми действиями просмотра.

Переопределить BrowserServiceCompat

Вам необходимо переопределить следующие методы в MediaBrowserServiceCompat .

public void onLoadItem(String itemId, @NonNull Result<MediaBrowserCompat.MediaItem> result)

public void onCustomAction(@NonNull String action, Bundle extras, @NonNull Result<Bundle> result)

Расположение действий ограничение

Вам следует проверить, сколько поддерживается пользовательским просмотром действий.

public BrowserRoot onGetRoot(@NonNull String clientPackageName, int clientUid, Bundle rootHints) {
    rootHints.getInt(
            MediaConstants.BROWSER_ROOT_HINTS_KEY_CUSTOM_BROWSER_ACTION_LIMIT, 0)
}

Создайте индивидуальный просмотр

Каждое действие должно быть упаковано в отдельный Bundle .

• Идентификатор действия

  bundle.putString(MediaConstants.EXTRAS_KEY_CUSTOM_BROWSER_ACTION_ID,
                  "<ACTION_ID>")
  

• Действие этикетки

  bundle.putString(MediaConstants.EXTRAS_KEY_CUSTOM_BROWSER_ACTION_LABEL,
                  "<ACTION_LABEL>")
  

• Значок действия URI

  bundle.putString(MediaConstants.EXTRAS_KEY_CUSTOM_BROWSER_ACTION_ICON_URI,
                  "<ACTION_ICON_URI>")
  

Добавьте пользовательский просмотр действий в Parceable ArrayList

Добавьте все пользовательские объекты Browse Action Bundle в ArrayList .

private ArrayList<Bundle> createCustomActionsList(
                                        CustomBrowseAction browseActions) {
    ArrayList<Bundle> browseActionsBundle = new ArrayList<>();
    for (CustomBrowseAction browseAction : browseActions) {
        Bundle action = new Bundle();
        action.putString(EXTRAS_KEY_CUSTOM_BROWSER_ACTION_ID,
                browseAction.mId);
        action.putString(EXTRAS_KEY_CUSTOM_BROWSER_ACTION_LABEL,
                getString(browseAction.mLabelResId));
        action.putString(EXTRAS_KEY_CUSTOM_BROWSER_ACTION_ICON_URI,
                browseAction.mIcon);
        browseActionsBundle.add(action);
    }
    return browseActionsBundle;
}

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

public BrowserRoot onGetRoot(@NonNull String clientPackageName, int clientUid,
                             Bundle rootHints) {
    Bundle browserRootExtras = new Bundle();
    browserRootExtras.putParcelableArrayList(
            BROWSER_SERVICE_EXTRAS_KEY_CUSTOM_BROWSER_ACTION_ROOT_LIST,
            createCustomActionsList()));
    mRoot = new BrowserRoot(ROOT_ID, browserRootExtras);
    return mRoot;
}

Добавить действия в MediaItem

MediaDescriptionCompat buildDescription (long id, String title, String subtitle,
                String description, Uri iconUri, Uri mediaUri,
                ArrayList<String> browseActionIds) {

    MediaDescriptionCompat.Builder bob = new MediaDescriptionCompat.Builder();
    bob.setMediaId(id);
    bob.setTitle(title);
    bob.setSubtitle(subtitle);
    bob.setDescription(description);
    bob.setIconUri(iconUri);
    bob.setMediaUri(mediaUri);

    Bundle extras = new Bundle();
    extras.putStringArrayList(
          DESCRIPTION_EXTRAS_KEY_CUSTOM_BROWSER_ACTION_ID_LIST,
          browseActionIds);

    bob.setExtras(extras);
    return bob.build();
}
MediaItem mediaItem = new MediaItem(buildDescription(...), flags);

Построить результат onCustomAction

• Parse MediaId из Bundle extras :

  @Override
  public void onCustomAction(
            @NonNull String action, Bundle extras, @NonNull Result<Bundle> result){
    String mediaId = extras.getString(MediaConstans.EXTRAS_KEY_CUSTOM_BROWSER_ACTION_MEDIA_ITEM_ID);
  }
  

• Для асинхронных результатов отсоедините результат. result.detach()
• Построить пакет результатов
  • Сообщение пользователю

    mResultBundle.putString(EXTRAS_KEY_CUSTOM_BROWSER_ACTION_RESULT_MESSAGE,
              mContext.getString(stringRes))
    

  • Обновите элемент (используйте для обновления действий в элементе)

    mResultBundle.putString(EXTRAS_KEY_CUSTOM_BROWSER_ACTION_RESULT_REFRESH_ITEM, mediaId);
    

  • Открытый вид воспроизведения

    //Shows user the PBV without changing the playback state
    mResultBundle.putString(EXTRAS_KEY_CUSTOM_BROWSER_ACTION_RESULT_SHOW_PLAYING_ITEM, null);
    

  • Обновление узел

    //Change current browse node to mediaId
    mResultBundle.putString(EXTRAS_KEY_CUSTOM_BROWSER_ACTION_RESULT_BROWSE_NODE, mediaId);
    

• Если ошибка, вызовите result.sendError(resultBundle).
• Если обновление прогресса, вызовите result.sendProgressUpdate(resultBundle) .
• Завершить, позвонив в result.sendResult(resultBundle) .

Обновить состояние действия

Используя метод result.sendProgressUpdate(resultBundle) с помощью ключа EXTRAS_KEY_CUSTOM_BROWSER_ACTION_RESULT_REFRESH_ITEM , вы можете обновить MediaItem чтобы отразить новое состояние действия. Это позволяет вам предоставлять обратную связь с пользователем в реальном времени о прогрессе и результате их действия.

Пример: скачать действие

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

1. Скачать: это начальное состояние действия. Когда пользователь выбирает это действие, вы можете поменять его с «загрузкой» и вызовы sendProgressUpdate для обновления пользовательского интерфейса.
2. Загрузка: это состояние указывает, что загрузка находится в процессе. Вы можете использовать это состояние, чтобы показать панель прогресса или другой индикатор для пользователя.
3. Загружено: это состояние указывает, что загрузка завершена. При завершении загрузки вы можете обмениваться «загрузкой» с «загруженным» и позвонить в sendResult с помощью клавиши EXTRAS_KEY_CUSTOM_BROWSER_ACTION_RESULT_REFRESH_ITEM чтобы указать, что элемент должен быть обновлен. Кроме того, вы можете использовать клавишу EXTRAS_KEY_CUSTOM_BROWSER_ACTION_RESULT_MESSAGE чтобы отобразить сообщение успеха пользователю.

Этот подход позволяет предоставить пользователю четкую обратную связь о процессе загрузки и его текущего состояния. Вы можете добавить еще больше деталей со значками, чтобы показать 25%, 50%, 75%состояния загрузки.

Пример: любимое действие

Другой пример - любимое действие с двумя состояниями:

1. Любимое: это действие отображается для элементов, которые не находятся в списке фаворитов пользователя. Когда пользователь выбирает это действие, вы можете поменять его с «любимым» и позвонить в sendResult с помощью клавиши EXTRAS_KEY_CUSTOM_BROWSER_ACTION_RESULT_REFRESH_ITEM для обновления пользовательского интерфейса.
2. Благодаря: это действие отображается для элементов, которые находятся в списке фаворитов пользователя. Когда пользователь выбирает это действие, вы можете поменять его с «любимым» и позвонить sendResult с помощью клавиши EXTRAS_KEY_CUSTOM_BROWSER_ACTION_RESULT_REFRESH_ITEM для обновления пользовательского интерфейса.

Этот подход обеспечивает четкий и последовательный способ для пользователей управлять своими любимыми предметами.

Эти примеры демонстрируют гибкость индивидуальных просмотра действий и то, как вы можете использовать их для реализации различных функций с обратной связью в реальном времени для улучшенного пользовательского опыта в приложении Car's Media.

Для полного примера реализации этой функции вы можете обратиться к проекту TestMediaApp .

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

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

Зарегистрировать сеанс медиа

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

Реализовать команды PLAY

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

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

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

onPrepare()

Призван, когда источник медиа изменяется. Android Automotive OS также вызывает этот метод сразу после загрузки. Ваше медиа -приложение должно реализовать этот метод.

onPlay()

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

ПРИМЕЧАНИЕ. Ваше приложение не должно автоматически начинать воспроизведение музыки, когда Android Automotive OS или Android Auto подключаются к службу вашего браузера. Для получения дополнительной информации см. Раздел о установке начального состояния воспроизведения .

onPlayFromMediaId()

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

onPlayFromSearch()

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

onPause()

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

onSkipToNext()

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

onSkipToPrevious()

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

onStop()

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

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

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

Для получения дополнительной информации о воспроизведении звукового контента см. Обзор MediaPlayer , обзор Audio приложения и обзор Exoplayer.

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

Android Auto и Android Automotive OS -дисплей ОС ОСОБЕНА ОСОБЕННОСТИ ОСОБЕННОСТИ ОСОБЕННОСТЬ ИСПОЛЬЗОВАНИЯ НА ДЕЙСТВИЯХ, которые включены в объект PlaybackStateCompat .

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

• ACTION_PLAY
• ACTION_PAUSE
• ACTION_STOP
• ACTION_PLAY_FROM_MEDIA
• ACTION_PLAY_FROM_SEARCH

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

• ACTION_SKIP_TO_PREVIOUS
• ACTION_SKIP_TO_NEXT

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

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

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

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

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

Если вы не хотите заполнять эти пространства настраиваемыми действиями, вы можете зарезервировать их так, чтобы Android Auto и Android Automotive OS покидает пространство, когда ваше приложение не поддерживает соответствующую функцию. Для этого вызовите метод setExtras() с помощью пакета дополнений, который содержит константы, которые соответствуют зарезервированным функциям. 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 для их значений.

Установите начальный PlaybackState

Поскольку Android Auto и Android Automotive OS общаются с вашей службой Media Browser, ваша медиа -сессия передает статус воспроизведения контента, используя PlaybackStateCompat . Ваше приложение не должно автоматически начинать воспроизведение музыки, когда Android Automotive OS или Android Auto подключаются к служению вашего браузера. Вместо этого полагайтесь на Android Auto и Android Automotive OS, чтобы возобновить или начать воспроизведение на основе состояния автомобиля или действий пользователя.

Чтобы сделать это, установите первоначальный PlaybackStateCompat вашего сеанса медиа в STATE_STOPPED , STATE_PAUSED , STATE_NONE или STATE_ERROR .

Сессии медиа -сеансы в Android Auto и Android Automotive OS длится только на протяжении всего диска, поэтому пользователи часто начинают и останавливают эти сеансы. Чтобы продвигать беспрепятственный опыт между дисками, отслеживайте предыдущее состояние сеанса пользователя, чтобы, когда медиа -приложение получает запрос на резюме, пользователь может автоматически поднять, где они остановились, - например, последний воспроизводимый медиа -элемент, PlaybackStateCompat и очередь.

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

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

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

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

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

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

Поддержать голосовые действия

Ваше медиа -приложение должно поддерживать голосовые действия, чтобы помочь водителям безопасного и удобного опыта, который сводит к минимуму отвлечения. Например, если ваше приложение воспроизводит одну медиа -элементу, пользователь может сказать « Play [Song Tile] », чтобы сказать вашему приложению воспроизвести другую песню, не просмотрев и не касаясь дисплея автомобиля. Пользователи могут инициировать запросы, нажав соответствующие кнопки На их рулевом колесе или высказывается горячие слова « ОК, Google ».

Когда Android Auto или Android Automotive OS обнаруживает и интерпретирует голосовое действие, это голосовое действие доставляется в приложение через onPlayFromSearch() . Получив этот обратный вызов, приложение находит контент, соответствующий строке query и начинает воспроизведение.

Пользователи могут указать различные категории терминов в своем запросе: жанр, исполнитель, альбом, название песни, радиостанция или плейлист, среди прочих. При создании поддержки для поиска учитывайте все категории, которые имеют смысл для вашего приложения. Если Android Auto или Android Automotive OS обнаруживает, что заданный запрос вписывается в определенные категории, он добавляет дополнения в параметр extras . Можно отправить следующие дополнения:

• EXTRA_MEDIA_ALBUM
• EXTRA_MEDIA_ARTIST
• EXTRA_MEDIA_GENRE
• EXTRA_MEDIA_PLAYLIST
• EXTRA_MEDIA_TITLE

Учетная запись для пустой строки query , которая может быть отправлена ​​Android Auto или Android Automotive OS, если пользователь не указывает термины поиска. Например, если пользователь говорит: « Играйте в музыку ». В этом случае ваше приложение может запустить недавно сыгранный или недавно предложенный трек.

Если поиск не может быть обработан быстро, не блокируйте в onPlayFromSearch() . Вместо этого установите состояние воспроизведения в STATE_CONNECTING и выполните поиск в асинхронизированном потоке.

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

В дополнение к « Воспроизведение » запросов, Android Auto и Android Automotive OS распознают голосовые запросы для управления воспроизведением, например, « Music Pause Music » и « Next Song », и сопоставьте эти команды с соответствующими обратными вызовами сеанса медиа, такими как onPause() и onSkipToNext() .

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

Реализовать предотвращение гарантий

Поскольку телефон пользователя подключен к динамикам их автомобиля при использовании Android Auto, вы должны принять дополнительные меры предосторожности, чтобы предотвратить отвлечение водителя.

Подавить тревоги в машине

Приложения Android Auto Media не должны начинать воспроизводить аудио через динамики автомобилей, если пользователь не начнет воспроизведение, например, нажав кнопку воспроизведения. Даже пользовательская запланированная тревога из вашего медиа-приложения не должна начинать воспроизводить музыку через динамики автомобилей.

Чтобы выполнить это требование, ваше приложение может использовать CarConnection в качестве сигнала перед воспроизведением какого -либо звука. Ваше приложение может проверить, проецируется ли телефон на экране автомобиля, наблюдая за LiveData для типа автомобильного соединения и проверив, равно ли он CONNECTION_TYPE_PROJECTION .

Если телефон пользователя проецирует, медиа -приложения, которые поддерживают тревоги, должны делать одну из следующих вещей:

• Отключить сигнал тревоги.
• Воспроизведите сигнал тревоги над STREAM_ALARM и предоставьте пользовательский интерфейс на экране телефона, чтобы отключить сигнал тревоги.

Обрабатывать медиа -рекламу

По умолчанию Android Auto отображает уведомление, когда метаданные мультимедиа меняются во время сеанса воспроизведения звука. Когда медиа -приложение переключается от воспроизведения музыки на запуск рекламы, он отвлекает, чтобы отобразить уведомление пользователю. Чтобы Android Auto отображала уведомление в этом случае, вы должны установить метаданные метаданные средства массовой информации METADATA_KEY_IS_ADVERTISEMENT в METADATA_VALUE_ATTRIBUTE_PRESENT , как показано в следующем фрагменте кода:

import androidx.media.utils.MediaConstants

override fun onPlayFromMediaId(mediaId: String, extras: Bundle?) {
    MediaMetadataCompat.Builder().apply {
        if (isAd(mediaId)) {
            putLong(
                MediaConstants.METADATA_KEY_IS_ADVERTISEMENT,
                MediaConstants.METADATA_VALUE_ATTRIBUTE_PRESENT)
        }
        // ...add any other properties you normally would.
        mediaSession.setMetadata(build())
    }
}

import androidx.media.utils.MediaConstants;

@Override
public void onPlayFromMediaId(String mediaId, Bundle extras) {
    MediaMetadataCompat.Builder builder = new MediaMetadataCompat.Builder();
    if (isAd(mediaId)) {
        builder.putLong(
            MediaConstants.METADATA_KEY_IS_ADVERTISEMENT,
            MediaConstants.METADATA_VALUE_ATTRIBUTE_PRESENT);
    }
    // ...add any other properties you normally would.
    mediaSession.setMetadata(builder.build());
}

Обрабатывать общие ошибки

Когда приложение испытывает ошибку, установите состояние воспроизведения в STATE_ERROR и предоставьте сообщение об ошибке, используя метод setErrorMessage() . См. PlaybackStateCompat для списка кодов ошибок, которые вы можете использовать при настройке сообщения об ошибке. Сообщения об ошибках должны быть пользовательскими и локализованными с текущей локацией пользователя. Android Auto и Android Automotive OS может затем отобразить сообщение об ошибке пользователю.

Например, если содержимое недоступно в текущей области пользователя, вы можете использовать код ошибки ERROR_CODE_NOT_AVAILABLE_IN_REGION при настройке сообщения об ошибке.

mediaSession.setPlaybackState(
    PlaybackStateCompat.Builder()
        .setState(PlaybackStateCompat.STATE_ERROR)
        .setErrorMessage(PlaybackStateCompat.ERROR_CODE_NOT_AVAILABLE_IN_REGION, getString(R.string.error_unsupported_region))
        // ...and any other setters.
        .build())

mediaSession.setPlaybackState(
    new PlaybackStateCompat.Builder()
        .setState(PlaybackStateCompat.STATE_ERROR)
        .setErrorMessage(PlaybackStateCompat.ERROR_CODE_NOT_AVAILABLE_IN_REGION, getString(R.string.error_unsupported_region))
        // ...and any other setters.
        .build());

Для получения дополнительной информации о состояниях ошибок см. В использовании сеанса СМИ: состояния и ошибки .

Если пользователь Android Auto должен открыть ваше телефонное приложение для разрешения ошибки, предоставьте пользователю эту информацию в вашем сообщении. Например, ваше сообщение об ошибке может сказать «Войдите в [имя вашего приложения]» вместо «Пожалуйста, войдите в систему».

Другие ресурсы

• Образец универсального медиаплеера
• Обзор Audio App
• Обзор Exoplayer