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

Android Auto と Android Automotive OS（AAOS）でメディア再生を有効にするには、メディア セッションを登録してそのコールバック メソッドを処理することで、再生コントロールを実装します。このページでは、次の方法について説明します。

  • メディア ブラウザ サービスで MediaSessionCompat オブジェクトを登録します。

  • MediaSessionCompat.Callback メソッドを実装して、ユーザーの再生リクエストに応答します。

  • 標準とカスタムの再生操作を設定します。

  • メディア セッションの最初の再生状態を設定します。

  • 音声形式を示すアイコンを追加しました。

  • 再生中のメディア アイテムからリンクを作成します。

Android Auto と AAOS は、サービスの 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 that implements MediaSession.Callback
        // to handle play control requests.
        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 that implements MediaSession.Callback
    // to handle play control requests.
    session.setCallback(new MyMediaSessionCallback());
    ...
}

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

再生コマンドを実装する

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

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

アプリが提供するコンテンツの種類に応じて、以下のコールバック メソッドをそれぞれ実装します。

onPrepare
メディアソースが変更されると、AAOS はこのメソッドを呼び出します。
onPlay

ユーザーが特定のアイテムを選択せずに再生を選択したときに呼び出されます。アプリはデフォルトのコンテンツを再生する必要があります。また、onPause で再生が一時停止されていた場合、アプリは再生を再開します。

onPlayFromMediaId

ユーザーが特定のアイテムの再生を選択したときに呼び出されます。このメソッドは、メディア ブラウザ サービスがコンテンツ階層内のメディア アイテムに割り当てた ID を受け取ります。

onPlayFromSearch

ユーザーが検索クエリからの再生を選択したときに呼び出されます。アプリは、渡された検索文字列に基づいて適切な選択を行う必要があります。

onPause

ユーザーが再生の一時停止を選択したときに呼び出されます。

onSkipToNext

ユーザーが次のアイテムへのスキップを選択したときに呼び出されます。

onSkipToPrevious

ユーザーが前のアイテムへのスキップを選択したときに呼び出されます。

onStop

ユーザーが再生の停止を選択したときに呼び出されます。アプリでこれらのメソッドをオーバーライドして、選択した結果を提供します。メソッドの目的がアプリでサポートされていなければ、そのメソッドを実装する必要はありません。たとえば、アプリがライブ ストリーム（スポーツ放送など）を再生する場合、onSkipToNext を実装する必要はありません。代わりに、onSkipToNext のデフォルト実装を使用します。

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

音声コンテンツの再生の詳細については、MediaPlayer の概要、オーディオ アプリの概要、ExoPlayer の概要をご覧ください。

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

Android Auto と AAOS は、PlaybackStateCompat オブジェクトで有効化されている操作に基づいて再生コントロールを表示します。デフォルトでは、アプリは次の操作をサポートする必要があります。

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

さらに、ユーザーに表示する再生キューを任意で作成できます。そのためには、setQueue メソッドと setQueueTitle メソッドを呼び出し、ACTION_SKIP_TO_QUEUE_ITEM アクションを有効にして、コールバック onSkipToQueueItem を定義します。

また、再生中の曲のインジケーターである「この曲なに？」アイコンのサポートも追加します。そのためには、setActiveQueueItemId メソッドを呼び出し、キュー内の再生中のアイテムの ID を渡します。キューが変更されるたびに setActiveQueueItemId を更新する必要があります。

Android Auto と AAOS は、有効化された操作ごとにボタンを表示し、再生キューを表示します。ユーザーがこれらのボタンをクリックすると、システムは MediaSessionCompat.Callback から対応するコールバックを呼び出します。

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

Android Auto と AAOS は、ACTION_SKIP_TO_PREVIOUS アクションと ACTION_SKIP_TO_NEXT アクション用に UI のスペースを予約します。アプリがこれらの機能のいずれかをサポートしていない場合、Android Auto と AAOS はこのスペースを使用して、デベロッパーが作成したカスタム アクションを表示します。

このスペースにカスタム アクションを表示しない場合、アプリが対応する機能をサポートしていないときは常に Android Auto と AAOS がスペースを空白のままにしておくように、スペースを予約できます。

そのためには、予約された各機能に対応する定数を含む extras バンドルを指定して、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 と AAOS はメディア ブラウザ サービスと通信するので、メディア セッションは PlaybackStateCompat を使用してコンテンツ再生のステータスをやり取りします。

AAOS または Android Auto がメディア ブラウザ サービスに接続したとき、アプリは自動的に音楽の再生を開始してはなりません。Android Auto と AAOS に処理をまかせ、車の状態またはユーザーの操作に基づいて再生を再開または開始してください。

そのためには、メディア セッションの最初の PlaybackStateCompat を、STATE_STOPPED、STATE_PAUSED、STATE_NONE、STATE_ERROR のいずれかに設定します。

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

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

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

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

カスタム アクションを追加するには、PlaybackStateCompat.Builder クラスの addCustomAction メソッドを使用します。次のコード スニペットは、「ラジオ チャンネルの開始」にカスタム アクションを追加する方法を示しています。

Kotlin

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

Java

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

このメソッドの詳細な例については、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 メソッドをご覧ください。

カスタム アクションのアイコンを作成する

作成する各カスタム操作には、アイコンが必要です。

そのアイコンの説明が CommandButton.ICON_ 定数のいずれかに一致する場合は、カスタム アクションの extras の EXTRAS_KEY_COMMAND_BUTTON_ICON_COMPAT キーの整数値を設定します。サポートされているシステムでは、これにより CustomAction.Builder に渡されたアイコン リソースがオーバーライドされ、システム コンポーネントでアクションや他の再生アクションが常にレンダリングされるようになります。

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

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

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

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

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

音声形式を指定する

再生中のメディアが特別な音声形式を使用していることを示すため、この機能に対応する自動車に表示するアイコンを指定できます。KEY_CONTENT_FORMAT_TINTABLE_LARGE_ICON_URI と KEY_CONTENT_FORMAT_TINTABLE_SMALL_ICON_URI は（MediaSession.setMetadata に渡す）現在再生中のメディア アイテムのエクストラ バンドルで設定できます。さまざまなレイアウトに対応できるよう、これらのエクストラは両方とも設定してください。

さらに、KEY_IMMERSIVE_AUDIO のエクストラを設定すると、これが没入感のある音声であることを自動車の OEM に伝えることができます。自動車の OEM は、没入感のあるコンテンツを妨げる可能性があるオーディオ エフェクトを適用するかどうかを非常に慎重に判断する必要があります。

再生中のメディア アイテムのサブタイトル、説明、またはその両方が他のメディア アイテムへのリンクになるように設定できます。これにより、ユーザーは関連するアイテムにすばやくジャンプできます。たとえば、同じアーティストの他の曲や、ポッドキャストの他のエピソードなどにジャンプできます。車がこの機能をサポートしている場合、ユーザーはリンクをタップしてそのコンテンツを参照できます。

リンクを追加するには、KEY_SUBTITLE_LINK_MEDIA_ID メタデータ（サブタイトルからリンクする場合）または KEY_DESCRIPTION_LINK_MEDIA_ID（説明からリンクする場合）を設定します。詳しくは、これらのメタデータ フィールドの参照ドキュメントをご覧ください。