自動車向けメディアアプリを作成する

Android Auto と Android Automotive OS は、メディアアプリのコンテンツを自動車に乗っているユーザーに届けます。自動車向けメディアアプリは、Android Auto と Android Automotive OS（またはメディアブラウザ機能を持つ別のアプリ）がコンテンツを見つけて表示できるよう、メディアブラウザサービスを提供する必要があります。

このガイドは、音声を再生するメディアアプリがスマートフォンにすでにインストールされており、そのメディアアプリが Android メディアアプリアーキテクチャに準拠していることを前提としています。

このガイドでは、アプリが Android Auto または Android Automotive OS 上で動作するうえで必須のコンポーネントである MediaBrowserService と MediaSession について説明します。核となるメディアインフラストラクチャが完成すると、Android Auto のサポートおよび Android Automotive OS のサポートをメディアアプリに追加できるようになります。

始める前に

Android メディア API のドキュメントを確認してください。
Android Automotive OS アプリの設計ガイドラインと Android Auto アプリの設計ガイドラインを確認してください。
このセクションに記載されている主な用語と概念を確認してください。

主な用語と概念

メディアブラウザサービス

MediaBrowserServiceCompat API に準拠するメディアアプリによって実装される Android サービス。アプリはこのサービスを使用してコンテンツを公開します。

メディアブラウザ

メディアブラウザサービスを見つけてコンテンツを表示するためにメディアアプリで使用される API。Android Auto と Android Automotive OS は、アプリのメディアブラウザサービスを見つけるためにメディアブラウザを使用します。

メディアアイテム

メディアブラウザはそのコンテンツを MediaItem オブジェクトのツリーにまとめます。メディアアイテムには、次の 2 つのフラグのいずれかまたは両方を含めることができます。

再生可能: このフラグは、アイテムがコンテンツツリーのリーフであることを示します。アイテムは、単一のサウンドストリーム（アルバムの曲、オーディオブックのチャプター、ポッドキャストのエピソードなど）を表します。
ブラウズ可能: このフラグは、アイテムがコンテンツツリーのノードであり、アイテムに子があることを示します（たとえば、アイテムがアルバムを表し、その子がアルバムの曲である場合など）。

ブラウズと再生の両方が可能なメディアアイテムは、プレイリストのような役割を果たします。アイテム自体を選択してそのすべての子を再生することも、アイテムの子をブラウズすることもできます。

自動車向け最適化

Android Automotive OS 設計ガイドラインに従った Android Automotive OS アプリのアクティビティ。このアクティビティのインターフェースは Android Automotive OS によって描画されないため、アプリが設計ガイドラインに従うように注意する必要があります。設計ガイドラインには、通常、タップターゲットとフォントサイズを大きくする、日中モードと夜間モードをサポートする、コントラスト比を大きくする、といったものがあります。

自動車向けに最適化されたユーザーインターフェースは、自動車ユーザーエクスペリエンス制限（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 OS がシステム UI にアプリを表示するために使用できるアプリアイコンを指定する必要があります。

次のマニフェスト宣言を使用して、アプリを表すために使用するアイコンを指定できます。

<!--The android:icon attribute is used by Android Automotive OS-->
<application>
    ...
    android:icon="@mipmap/ic_launcher">
    ...
    <!--Used by Android Auto-->
    <meta-data android:name="com.google.android.gms.car.notification.SmallIcon"
               android:resource="@drawable/ic_auto_icon" />
    ...
</application>

メディアブラウザサービスを作成する

メディアブラウザサービスを作成するには、MediaBrowserServiceCompat クラスを拡張します。これにより、Android Auto と Android Automotive OS の両方で、サービスを使用して次の処理を実行することができます。

ユーザーにメニューを表示するために、アプリのコンテンツ階層を参照する。
音声の再生を制御するために、アプリの MediaSessionCompat オブジェクトのトークンを取得する。

メディアブラウザサービスのワークフロー

このセクションでは、一般的なユーザーワークフローで Android Automotive OS と Android Auto がメディアブラウザサービスと対話する仕組みについて説明します。

ユーザーが Android Automotive OS または Android Auto でアプリを起動します。
Android Automotive OS または Android Auto は、onCreate() メソッドを使用してアプリのメディアブラウザサービスにコンタクトします。onCreate() メソッドの実装では、MediaSessionCompat オブジェクトとそのコールバックオブジェクトを作成して登録する必要があります。
Android Automotive OS または Android Auto は、サービスの onGetRoot() メソッドを呼び出して、コンテンツ階層のルートのメディアアイテムを取得します。ルートのメディアアイテムは表示されませんが、アプリからより多くのコンテンツを取得するために使用されます。
Android Automotive OS または Android Auto は、サービスの onLoadChildren() メソッドを呼び出して、ルートのメディアアイテムの子を取得します。Android Automotive OS と Android Auto は、これらのメディアアイテムを最上位のコンテンツアイテムとして表示します。このレベルでシステムが表示するコンテンツについて詳しくは、ルートメニューを構造化するをご覧ください。
ユーザーがブラウズ可能なメディアアイテムを選択すると、サービスの onLoadChildren() メソッドが再度呼び出され、選択されたメニューアイテムの子が取得されます。
ユーザーが再生可能なメディアアイテムを選択すると、Android Automotive OS または Android Auto は、適切なメディアセッションコールバックメソッドを呼び出して、その操作を実行します。
アプリでサポートされていれば、ユーザーはコンテンツを検索することもできます。この場合、Android Automotive OS または Android Auto は、サービスの onSearch() メソッドを呼び出します。

コンテンツ階層を構築する

Android Auto と Android Automotive OS は、アプリのメディアブラウザサービスを呼び出して、利用可能なコンテンツを見つけます。これをサポートするには、メディアブラウザサービスに onGetRoot() と onLoadChildren() の 2 つのメソッドを実装する必要があります。

onGetRoot を実装する

サービスの onGetRoot() メソッドは、コンテンツ階層のルートノードに関する情報を返します。Android Auto と Android Automotive OS はこのルートノードを使用して、onLoadChildren() メソッドで残りのコンテンツをリクエストします。

次のコードスニペットは、onGetRoot() メソッドの単純な実装を示しています。

Kotlin

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)

Java

@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);
}

このメソッドの詳細な例については、GitHub の Universal Android Music Player サンプルアプリの onGetRoot() メソッドをご覧ください。

onGetRoot() のパッケージ検証を追加する

サービスの onGetRoot() メソッドが呼び出されると、呼び出し元のパッケージは識別情報をサービスに渡します。サービスはこの情報を使用して、そのパッケージがコンテンツにアクセスできるかどうかを判断できます。たとえば、clientPackageName を許可リストと照合して、パッケージの APK の署名に使用される証明書を確認することにより、アプリのコンテンツへのアクセスを承認されたパッケージのリストに限定できます。パッケージを検証できない場合は、null を返してコンテンツへのアクセスを拒否します。

システムアプリ（Android Auto や Android Automotive OS など）にコンテンツへのアクセスを許可するには、システムアプリが onGetRoot() メソッドを呼び出すときに、常にサービスが null でない BrowserRoot を返す必要があります。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
}

このコードスニペットは、GitHub の Universal Android Music Player サンプルアプリの PackageValidator クラスからの抜粋です。サービスの onGetRoot() メソッドのパッケージ検証を実装する方法の詳細な例については、このクラスを参照してください。

システムアプリを許可するだけでなく、Google アシスタントが MediaBrowserService に接続できるようにする必要もあります。Google アシスタントには、スマートフォン（Android Auto を含む）用と Android Automotive OS 用の個別のパッケージ名があります。

onLoadChildren() を実装する

Android Auto と Android Automotive OS は、ルートノードのオブジェクトを受け取った後、そのオブジェクトで onLoadChildren() を呼び出してその子を取得することにより、最上位メニューを構築します。クライアントアプリは、子ノードのオブジェクトを使用してこの同じメソッドを呼び出すことにより、サブメニューを構築します。

コンテンツ階層の各ノードは、MediaBrowserCompat.MediaItem オブジェクトで表されます。これらの各メディアアイテムは、一意の ID 文字列によって識別されます。クライアントアプリは、このような ID 文字列を不透明なトークンとして扱います。クライアントアプリがサブメニューのブラウズまたはメディアアイテムの再生を行いたいときは、トークンを渡します。トークンを適切なメディアアイテムに関連付ける処理はアプリが行います。

注: Android Auto と Android Automotive OS には、メニューの各レベルで表示できるメディアアイテムの数に厳格な制限があります。この制限により、ドライバーが注意散漫になる危険が最小限に抑えられ、音声コマンドによるアプリの操作が容易になります。詳細については、コンテンツの詳細のブラウズとブラウジングビューをご覧ください。

次のコードスニペットは、onLoadChildren() メソッドの単純な実装を示しています。

Kotlin

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 if 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)
}

Java

@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 if 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);
}

このメソッドの完全な例については、GitHub の Universal Android Music Player サンプルアプリの onLoadChildren() メソッドをご覧ください。

図 1. ルートコンテンツがナビゲーションタブとして表示される

Android Auto と Android Automotive OS には、ルートメニューの構造に関する特定の制約があります。これらの制約はルートヒントを介して MediaBrowserService に伝えられます。ルートヒントは、onGetRoot() に渡される Bundle 引数を介して読み取ることができます。これらのヒントに従うことで、システムはルートコンテンツをナビゲーションタブとして最適に表示できます。これらのヒントに従わないと、一部のルートコンテンツが破棄されたり、システムによって検出されにくくなったりすることがあります。 次の 2 つのヒントが送信されます。

ルートの子の上限数: ほとんどの場合、この数は 4 になります。つまり、5 つ以上のタブを表示することはできません。
ルートの子でサポートされるフラグ: この値は MediaItem#FLAG_BROWSABLE になります。つまり、ブラウズ可能なアイテムのみをタブとして表示できます。再生可能なアイテムを表示することはできません。

関連するルートヒントを読み取るには、次のコードを使用します。

Kotlin

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..
}

Java

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...
}

特に、階層の値が Android Auto と Android Automotive OS の外部の MediaBrowser 統合によって異なる場合に、これらのヒントの値に基づいてコンテンツ階層の構造のロジックを分岐することもできます。たとえば、ルートの再生可能なアイテムを通常どおり表示する場合、サポートされるフラグヒントの値に従って、ルートのブラウズ可能なアイテムの下にネストできます。

タブを適切に表示するには、ルートヒントとは別に次のガイドラインにも従う必要があります。

各タブアイテムに、モノクロのアイコン（白を推奨）を付けます。
各タブアイテムに、簡潔でわかりやすいラベルを付けます。ラベルを短くすることにより、文字列が切り捨てられる可能性が低くなります。

メディアのアートワークを表示する

メディアアイテムのアートワークは、ContentResolver.SCHEME_CONTENT または ContentResolver.SCHEME_ANDROID_RESOURCE を使用してローカル URI として渡す必要があります。このローカル URI は、アプリのリソースでビットマップまたはベクター型ドローアブルに解決される必要があります。コンテンツ階層内のアイテムを表す MediaDescription オブジェクトの場合は、setIconUri() を介して URI を渡します。現在再生中のアイテムを表す MediaMetadata オブジェクトの場合は、putString() を介して、次のいずれかのキーを使用して URI を渡します。

ウェブ URI からアートをダウンロードして、ローカル URI で公開する例を次に示します。

画像ファイルをダウンロードします（次のコードスニペットでは Glide を使用しています）。

Kotlin

val artFile = Glide.with(context)
  .downloadOnly()
  .load(imageUri)
  .submit()
  .get()

Java

File artFile = Glide.with(context)
  .downloadOnly()
  .load(imageUri)
  .submit()
  .get();

ファイルの content:// URI を作成します。メディアブラウザサービスとメディアセッションは、この URI を Android Auto と Android Automotive OS に渡す必要があります。

Kotlin

fun File.asAlbumArtContentURI(): Uri {
  return Uri.Builder()
    .scheme(ContentResolver.SCHEME_CONTENT)
    .authority(AUTHORITY)
    .appendPath(this.path)
    .build()
}

Java

public static Uri asAlbumArtContentURI(File file) {
  return Uri.Builder()
    .scheme(ContentResolver.SCHEME_CONTENT)
    .authority(AUTHORITY)
    .appendPath(file.getPath())
    .build();
}

ContentProvider.openFile() メソッドでファイルにアクセスできるようにします。

Kotlin

override fun openFile(uri: Uri, mode: String): ParcelFileDescriptor? {
  val context = this.context ?: return null
  val file = File(uri.path)
  if (!file.exists()) {
    throw FileNotFoundException(uri.path)
  }
  // Only allow access to files under cache path
  val cachePath = context.cacheDir.path
  if (!file.path.startsWith(cachePath)) {
    throw FileNotFoundException()
  }
  return ParcelFileDescriptor.open(file, ParcelFileDescriptor.MODE_READ_ONLY)
}

Java

@Nullable
@Override
public ParcelFileDescriptor openFile(@NonNull Uri uri, @NonNull String mode)
    throws FileNotFoundException {
  Context context = this.getContext();
  File file = new File(uri.getPath());
  if (!file.exists()) {
    throw new FileNotFoundException(uri.getPath());
  }
  // Only allow access to files under cache path
  String cachePath = context.getCacheDir().getPath();
  if (!file.getPath().startsWith(cachePath)) {
    throw new FileNotFoundException();
  }
  return ParcelFileDescriptor.open(file, ParcelFileDescriptor.MODE_READ_ONLY);
}

コンテンツプロバイダについて詳しくは、コンテンツプロバイダの作成をご覧ください。

コンテンツスタイルを適用する

ブラウズ可能または再生可能なアイテムでコンテンツ階層を構築した後、コンテンツスタイルを適用できます。自動車内でアイテムがどのように表示されるかは、このコンテンツスタイルによって決まります。

使用可能なコンテンツスタイルは次のとおりです。

リストアイテム: このコンテンツスタイルは、画像よりもタイトルとメタデータを優先します。
グリッドアイテム: このコンテンツスタイルは、タイトルとメタデータよりも画像を優先します。

デフォルトのコンテンツスタイルを設定する

サービスの onGetRoot() メソッドの BrowserRoot エクストラバンドルに特定の定数を含めることにより、メディアアイテムをどのように表示するかに関するグローバルなデフォルトを設定できます。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: 対応するアイテムは「カテゴリ」グリッドアイテムとして表示されます。これらは通常のグリッドアイテムと同じですが、アイテムのアイコンは小さい方が見栄えがよいため、周囲に余白を付ける必要があります。このヒントはブラウズ可能なアイテムに対してのみ提供されます。

次のコードスニペットは、ブラウズ可能なアイテムと再生可能なアイテムのデフォルトのコンテンツスタイルを、それぞれグリッドとリストに設定する方法を示しています。

Kotlin

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)
}

Java

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);
}

アイテムごとのコンテンツスタイルを設定する

Content Style API を使用すると、ブラウズ可能なメディアアイテムの子のデフォルトのコンテンツスタイルをオーバーライドできます。デフォルトをオーバーライドするには、メディアアイテムの MediaDescription にエクストラバンドルを作成し、前述のヒントと同じヒントを追加します。

次のコードスニペットは、デフォルトのコンテンツスタイルをオーバーライドするブラウズ可能な MediaItem を作成する方法を示しています。

Kotlin

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_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)
}

Java

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_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);
}

タイトルのヒントを使用してアイテムをグループ化する

関連するメディアアイテムをグループ化するには、アイテムごとにヒントを使用します。グループ内のすべてのメディアアイテムで、キー DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE と同一の文字列値を持つマッピングを含む MediaDescription でエクストラバンドルを宣言する必要があります。この文字列はグループのタイトルとして使用され、ローカライズする必要があります。

次のコードスニペットは、サブグループの見出しが "Songs" の MediaItem を作成する方法を示しています。

Kotlin

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*/)
}

Java

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*/);
}

アプリは、連続したブロックとしてグループ化するメディアアイテムをすべて渡す必要があります。たとえば、メディアアイテムの 2 つのグループ「Songs」と「Albums」をこの順序で表示したいとします。そこで、アプリで 5 つのメディアアイテムを次の順序で渡しました。

メディアアイテム A（extras.putString(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE, "Songs") を使用）
メディアアイテム B（extras.putString(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE, "Albums") を使用）
メディアアイテム C（extras.putString(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE, "Songs") を使用）
メディアアイテム D（extras.putString(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE, "Songs") を使用）
メディアアイテム E（extras.putString(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE, "Albums") を使用）

「Songs」グループと「Albums」グループのメディアアイテムは連続したブロックにならないため、Android Auto と Android Automotive OS はこれを次の 4 つのグループと解釈します。

メディアアイテム A を含む「Songs」というグループ 1
メディアアイテム B を含む「Albums」というグループ 2
メディアアイテム C と D を含む「Songs」というグループ 3
メディアアイテム E を含む「Albums」というグループ 4

これらのアイテムを 2 つのグループで表示するには、アプリで次の順序でメディアアイテムを渡します。

メディアアイテム A（extras.putString(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE, "Songs") を使用）
メディアアイテム C（extras.putString(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE, "Songs") を使用）
メディアアイテム D（extras.putString(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE, "Songs") を使用）
メディアアイテム B（extras.putString(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE, "Albums") を使用）
メディアアイテム E（extras.putString(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE, "Albums") を使用）

追加のメタデータインジケーターを表示する

図 2. メタデータで曲とアーティストを識別する再生ビューと、明示的なコンテンツを示すアイコン

追加のメタデータインジケーターを設定して、メディアブラウザツリー内に、またはメディアの再生中に、コンテンツが一目でわかる情報を提供できます。ブラウザツリー内では、Android Auto と Android Automotive OS はアイテムに関連付けられた extras を読み取り、特定の定数を見つけて、表示するインジケーターを決定します。メディアの再生中には、Android Auto と Android Automotive OS はメディアセッションのメタデータを読み取り、特定の定数を見つけて、表示するインジケーターを決定します。

次の定数は、MediaItem ディスクリプションエクストラと MediaMetadata エクストラの両方で使用できます。

EXTRA_DOWNLOAD_STATUS: アイテムのダウンロードステータスを示します。この定数はキーとして使用する必要があり、値は次の long 定数のいずれかです。
- STATUS_DOWNLOADED: アイテムは完全にダウンロードされています
- STATUS_DOWNLOADING: アイテムはダウンロード中です
- STATUS_NOT_DOWNLOADED: アイテムはダウンロードされていません
METADATA_KEY_IS_EXPLICIT: アイテムに露骨な表現のコンテンツが含まれているかどうかを示します。アイテムが露骨な表現であることを示すには、この定数をキーとして使用し、long 型の 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: アイテムは完了しました

ユーザーがメディアブラウズツリーをブラウジングしているときにインジケーターを表示するには、上の定数を 1 つ以上含むエクストラバンドルを作成し、そのバンドルを MediaDescription.Builder.setExtras() メソッドに渡します。

次のコードスニペットは、部分的に再生される露骨な表現のメディアアイテム用のインジケーターを表示する方法を示しています。

Kotlin

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)
val description =
    MediaDescriptionCompat.Builder()
        .setMediaId(/*...*/)
        .setTitle(resources.getString(/*...*/))
        .setExtras(extras)
        .build()
return MediaBrowserCompat.MediaItem(description, /* flags */)

Java

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);
MediaDescriptionCompat description =
    new MediaDescriptionCompat.Builder()
        .setMediaId(/*...*/)
        .setTitle(resources.getString(/*...*/))
        .setExtras(extras)
        .build();
return new MediaBrowserCompat.MediaItem(description, /* flags */);

現在再生中のメディアアイテムのインジケーターを表示するには、METADATA_KEY_IS_EXPLICIT または EXTRA_DOWNLOAD_STATUS の Long 形式の値を mediaSession の MediaMetadata.Builder() メソッドで宣言します。再生ビューに DESCRIPTION_EXTRAS_KEY_COMPLETION_STATUS インジケーターを表示することはできません。

次のコードスニペットは、再生ビュー内の現在の曲が露骨な表現であり、かつダウンロードされていることを示す方法を示しています。

Kotlin

import androidx.media.utils.MediaConstants

mediaSession.setMetadata(
    MediaMetadata.Builder()
        .putString(
            MediaMetadata.METADATA_KEY_DISPLAY_TITLE, "Song Name")
        .putString(
            MediaMetadata.METADATA_KEY_DISPLAY_SUBTITLE, "Artist name")
        .putString(
            MediaMetadata.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())

Java

import androidx.media.utils.MediaConstants;

mediaSession.setMetadata(
    new MediaMetadata.Builder()
        .putString(
            MediaMetadata.METADATA_KEY_DISPLAY_TITLE, "Song Name")
        .putString(
            MediaMetadata.METADATA_KEY_DISPLAY_SUBTITLE, "Artist name")
        .putString(
            MediaMetadata.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());

ブラウズ可能な検索結果を表示する

図 3. ユーザーの音声検索に関連するメディアアイテムを表示できる「検索結果」オプションが表示された再生ビュー

アプリでは、ユーザーが検索クエリを実行するときに表示されるコンテキスト検索の結果を提供できます。Android Auto と Android Automotive OS は、検索クエリインターフェースや、セッション内で前に行われたクエリで決まるアフォーダンスを通じて、検索結果を表示します。

ブラウズ可能な検索結果を表示するには、定数キー BROWSER_SERVICE_EXTRAS_KEY_SEARCH_SUPPORTED をサービスの onGetRoot() メソッドのエクストラバンドルに含めて、ブール値 true にマッピングする必要があります。

次のコードスニペットは、onGetRoot() メソッドでサポートを有効にする方法を示しています。

Kotlin

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)
}

Java

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() メソッドの単純な実装を示しています。

Kotlin

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
}

Java

@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
}

再生コントロールを有効にする

Android Auto と Android Automotive OS は、サービスの MediaSessionCompat を介して再生コントロールコマンドを送信します。セッションを登録し、関連するコールバックメソッドを実装する必要があります。

メディアセッションを登録する

メディアブラウザサービスの onCreate() メソッドで MediaSessionCompat を作成し、setSessionToken() を呼び出してメディアセッションを登録します。

次のコードスニペットは、メディアセッションを作成して登録する方法を示しています。

Kotlin

override fun onCreate() {
    super.onCreate()

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

    ...
}

Java

public void onCreate() {
    super.onCreate();

    ...
    // Start a new MediaSession
    MediaSessionCompat session = new MediaSessionCompat(this, "session tag");
    setSessionToken(session.getSessionToken());

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

    ...
}

メディアセッションオブジェクトを作成する際に、再生コントロールリクエストの処理に使用されるコールバックオブジェクトを設定します。このコールバックオブジェクトを作成するには、アプリの MediaSessionCompat.Callback クラスの実装を提供します。次のセクションで、このオブジェクトを実装する方法を説明します。

再生コマンドを実装する

ユーザーがアプリにメディアアイテムの再生をリクエストすると、Android Automotive OS と Android Auto は、アプリの MediaSessionCompat オブジェクト（アプリのメディアブラウザサービスから取得したオブジェクト）の MediaSessionCompat.Callback クラスを使用します。ユーザーがコンテンツ再生を制御する場合（再生の一時停止や次のトラックへのスキップなど）、Android Auto と Android Automotive OS は、コールバックオブジェクトのメソッドのひとつを呼び出します。

コンテンツ再生を処理するには、アプリで MediaSessionCompat.Callback 抽象クラスを拡張して、アプリがサポートするメソッドを実装する必要があります。

次のコールバックメソッドのうち、アプリが提供するコンテンツのタイプに適したものをすべて実装してください。

onPrepare(): メディアソースが変更されたときに呼び出されます。Android Automotive OS は、起動直後にもこのメソッドを呼び出します。メディアアプリは、このメソッドを実装する必要があります。
onPlay(): ユーザーが特定のアイテムを選択せずに再生を選択したときに呼び出されます。アプリは、デフォルトのコンテンツを再生する必要があります。onPause() で再生が一時停止された場合、アプリは再生を再開する必要があります。
注: Android Automotive OS または Android Auto がメディアブラウザサービスに接続したとき、アプリは自動的に音楽の再生を開始してはなりません。詳細については、最初の PlaybackState を設定するをご覧ください。
onPlayFromMediaId(): ユーザーが特定のアイテムの再生を選択したときに呼び出されます。このメソッドには、メディアブラウザサービスがコンテンツ階層内のメディアアイテムに割り当てた ID が渡されます。
onPlayFromSearch(): ユーザーが検索クエリからの再生を選択したときに呼び出されます。アプリは、渡された検索文字列に基づいて適切な選択を行う必要があります。
onPause(): ユーザーが再生の一時停止を選択したときに呼び出されます。
onSkipToNext(): ユーザーが次のアイテムへのスキップを選択したときに呼び出されます。
onSkipToPrevious(): ユーザーが前のアイテムへのスキップを選択したときに呼び出されます。
onStop(): ユーザーが再生の停止を選択したときに呼び出されます。

アプリはこれらのメソッドをオーバーライドして、必要な機能を提供する必要があります。メソッドがアプリでサポートされていなければ、そのメソッドを実装する必要はありません。たとえば、アプリがライブストリーム（スポーツ放送など）を再生する場合、onSkipToNext() メソッドを実装する意味はありません。代わりに onSkipToNext() のデフォルトの実装を使用できます。

アプリには、車載スピーカーからコンテンツを再生するための特別なロジックは不要です。アプリは、コンテンツ再生リクエストを受信したとき、通常と同じ方法（たとえば、ユーザーのスマートフォンのスピーカーまたはヘッドフォンでコンテンツを再生する）で音声を再生するべきです。Android Auto と Android Automotive OS は、音声コンテンツを車載システムに自動的に送信して、車載スピーカーで再生します。

音声コンテンツの再生の詳細については、メディアの再生、音声再生の管理、ExoPlayer をご覧ください。

標準の再生操作を設定する

Android Auto と Android Automotive OS は、PlaybackStateCompat オブジェクトで有効化されている操作に基づいて再生コントロールを表示します。

デフォルトでは、アプリは次の操作をサポートする必要があります。

アプリのコンテンツに関連する場合、アプリは次の操作もサポートできます。

さらに、ユーザーに表示できる再生キューの作成も可能です。そのためには、setQueue() メソッドと setQueueTitle() メソッドを呼び出し、ACTION_SKIP_TO_QUEUE_ITEM 操作を有効にして、コールバック onSkipToQueueItem() を定義する必要があります。

Android Auto と Android Automotive OS は、有効化された操作ごとにボタンを表示し、再生キューを作成する場合は再生キューも表示します。

未使用のスペースを予約する

Android Auto と Android Automotive OS は、ACTION_SKIP_TO_PREVIOUS アクションと ACTION_SKIP_TO_NEXT アクション用に UI のスペースを予約します。アプリがこれらの機能のいずれかをサポートしていない場合、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 はメディアブラウザサービスと通信するので、メディアセッションは PlaybackState を使用してコンテンツ再生のステータスをやり取りします。Android Automotive OS または Android Auto がメディアブラウザサービスに接続したとき、アプリは自動的に音楽の再生を開始してはなりません。Android Auto と Android Automotive OS に処理をまかせ、車の状態またはユーザーの操作に基づいて再生を再開または開始してください。

これを行うには、メディアセッションの最初の PlaybackState を、STATE_STOPPED、STATE_PAUSED、STATE_NONE、STATE_ERROR のいずれかに設定します。

Android Auto と Android Automotive OS のメディアセッションは運転している間だけ持続するため、ユーザーはこれらのセッションの開始と停止を頻繁に行うことになります。運転再開時のエクスペリエンスをよりシームレスなものにするには、ユーザーの以前のセッションの状態（最後に再生したメディアアイテム、PlaybackState、キューなど）を追跡して、メディアアプリが再開リクエストを受け取ったときに、再生を中断したところから自動的に再開できるようにします。

カスタム再生操作を追加する

カスタム再生操作を追加して、メディアアプリがサポートする追加の操作を表示できます。スペースに余裕がある（予約されていない）場合、Android はトランスポートコントロールにカスタム操作を追加します。それ以外の場合、カスタム操作はオーバーフローメニューに表示されます。カスタム操作は、PlaybackState に追加された順序で表示されます。

カスタム操作は、標準操作とは異なる動作を提供するために使用し、標準操作の置き換えや複製には使用しないでください。

これらの操作は、PlaybackStateCompat.Builder クラスの addCustomAction() メソッドを使用して追加できます。

次のコードスニペットは、カスタムの「ラジオチャンネルの開始」操作を追加する方法を示しています。

Kotlin

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

Java

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

このメソッドの詳細な例については、GitHub の Universal Android Music Player サンプルアプリの setCustomAction() メソッドをご覧ください。

カスタム操作を作成した場合、メディアセッションは onCustomAction() メソッドをオーバーライドすることで操作に応答できます。

次のコードスニペットは、アプリが「ラジオチャンネルの開始」操作に応答する方法を示しています。

Kotlin

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

Java

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

このメソッドの詳細な例については、GitHub の Universal Android Music Player サンプルアプリの onCustomAction メソッドをご覧ください。

カスタム操作のアイコン

作成する各カスタム操作には、アイコンリソースが必要です。車載アプリはさまざまな画面サイズと密度で実行される可能性があるので、提供するアイコンはベクター型ドローアブルでなければなりません。ベクター型ドローアブルを使用すると、細部を犠牲にすることなくアセットを拡大 / 縮小できます。また、低い解像度でも、アイコンの端と隅をピクセル境界に簡単に合わせられます。

カスタム操作がステートフルである場合（再生設定のオンとオフを切り替える場合など）は、ユーザーが操作を選択したときに変化に気付けるように、状態ごとに別々のアイコンを提供します。

無効な操作に対して代替アイコンスタイルを提供する

現在のコンテキストでカスタム操作を使用できない場合は、カスタム操作のアイコンを、操作が無効であることを示す代替アイコンに切り替えます。

図 4. カスタム操作がオフになっていることを示すアイコンスタイルのサンプル。

音声操作をサポートする

メディアアプリでは、ドライバーが注意散漫になる危険を最小限に抑える安全で便利なエクスペリエンスを提供するために、音声操作をサポートする必要があります。たとえば、アプリがあるメディアアイテムを再生しているときに、ユーザーが車載ディスプレイを見たり触れたりせずに、声（「『ボヘミアン・ラプソディ』を再生して」など）で別の曲の再生をアプリに指示できるようにします。

音声対応の再生操作をアプリに実装する方法の詳細な例については、Google アシスタントとメディアアプリをご覧ください。

注意散漫に対する安全保護対策を実装する

Android Auto の使用中、ユーザーのスマートフォンは車載スピーカーに接続されているため、ドライバーが注意散漫になるのを防ぐ追加の予防措置を講じる必要があります。

運転モードを検出する

Android Auto メディアアプリは、ユーザーが意識的に再生を開始した場合（アプリの再生ボタンを押した場合など）を除き、車載スピーカーで音声の再生を開始してはなりません。メディアアプリでユーザーがアラームをスケジュールした場合であっても、それによって車載スピーカーで音楽を再生してはいけません。この要件を満たすために、アプリは音声を再生する前に、スマートフォンが運転モードになっているかどうかを確認する必要があります。スマートフォンが運転モードになっているかどうかを確認するには、getCurrentModeType() メソッドを呼び出します。

ユーザーのスマートフォンが運転モードになっている場合、アラームをサポートするメディアアプリは次のいずれかを実行する必要があります。

アラームを無効にする。
STREAM_ALARM でアラームを再生し、アラームを無効にする UI をスマートフォン画面に表示する。

次のコードスニペットは、アプリが運転モードで実行されているかどうかを確認する方法を示しています。

Kotlin

fun isCarUiMode(c: Context): Boolean {
    val uiModeManager = c.getSystemService(Context.UI_MODE_SERVICE) as UiModeManager
    return if (uiModeManager.currentModeType == Configuration.UI_MODE_TYPE_CAR) {
        LogHelper.d(TAG, "Running in Car mode")
        true
    } else {
        LogHelper.d(TAG, "Running in a non-Car mode")
        false
    }
}

Java

 public static boolean isCarUiMode(Context c) {
      UiModeManager uiModeManager = (UiModeManager) c.getSystemService(Context.UI_MODE_SERVICE);
      if (uiModeManager.getCurrentModeType() == Configuration.UI_MODE_TYPE_CAR) {
            LogHelper.d(TAG, "Running in Car mode");
            return true;
      } else {
          LogHelper.d(TAG, "Running in a non-Car mode");
          return false;
        }
  }

メディア広告を処理する

デフォルトでは、Android Auto は、音声再生セッション中にメディアメタデータが変更されると、通知を表示します。メディアアプリが音楽の再生から広告の掲載に切り替えたときに通知を表示すると、ユーザーの注意が散漫になります（これは不要でもあります）。この場合に Android Auto が通知を表示しないようにするには、次のコードスニペットに示すように、メディアメタデータのキー METADATA_KEY_IS_ADVERTISEMENT を METADATA_VALUE_ATTRIBUTE_PRESENT に設定する必要があります。

Kotlin

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 as you normally would
        mediaSession.setMetadata(build())
    }
}

Java

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 as you normally would
    mediaSession.setMetadata(builder.build());
}

一般的なエラーを処理する

アプリでエラーが発生した場合、再生状態を STATE_ERROR に設定し、setErrorMessage() メソッドを使用してエラーメッセージを提供する必要があります。エラーメッセージはユーザー向けであるため、ユーザーの現在のロケールに合わせてローカライズする必要があります。これにより、Android Auto と Android Automotive OS はユーザーにエラーメッセージを表示できます。

エラー状態の詳細については、メディアセッションの操作: 状態とエラーをご覧ください。

Android Auto ユーザーがエラーを解決するためにスマートフォンアプリを開く必要がある場合、メッセージはその情報をユーザーに提供する必要があります。たとえば、エラーメッセージは、「ログインしてください」ではなく、「[アプリ名] にログインしてください」とします。

その他のリソース

Android Auto のサポートを追加する

自動車向けメディアアプリを作成する

始める前に

主な用語と概念

アプリのマニフェスト ファイルを構成する

メディア ブラウザ サービスを宣言する

アプリアイコンを指定する

メディア ブラウザ サービスを作成する

メディア ブラウザ サービスのワークフロー

コンテンツ階層を構築する

onGetRoot を実装する

Kotlin

Java

onGetRoot() のパッケージ検証を追加する

onLoadChildren() を実装する

Kotlin

Java

ルートメニューを構造化する

Kotlin

Java

メディアのアートワークを表示する

Kotlin

Java

Kotlin

Java

Kotlin

Java

コンテンツ スタイルを適用する

デフォルトのコンテンツ スタイルを設定する

Kotlin

Java

アイテムごとのコンテンツ スタイルを設定する

Kotlin

Java

タイトルのヒントを使用してアイテムをグループ化する

Kotlin

Java

追加のメタデータ インジケーターを表示する

Kotlin

Java

Kotlin

Java

ブラウズ可能な検索結果を表示する

Kotlin

Java

Kotlin

Java

再生コントロールを有効にする

メディア セッションを登録する

Kotlin

Java

再生コマンドを実装する

標準の再生操作を設定する

未使用のスペースを予約する

最初の PlaybackState を設定する

カスタム再生操作を追加する

Kotlin

Java

Kotlin

Java

カスタム操作のアイコン

無効な操作に対して代替アイコン スタイルを提供する

音声操作をサポートする

注意散漫に対する安全保護対策を実装する

運転モードを検出する

Kotlin

Java

メディア広告を処理する

Kotlin

Java

一般的なエラーを処理する

その他のリソース

アプリのマニフェストファイルを構成する

メディアブラウザサービスを宣言する

メディアブラウザサービスを作成する

メディアブラウザサービスのワークフロー

コンテンツスタイルを適用する

デフォルトのコンテンツスタイルを設定する

アイテムごとのコンテンツスタイルを設定する

追加のメタデータインジケーターを表示する

メディアセッションを登録する

無効な操作に対して代替アイコンスタイルを提供する