メディア セッションの使用

MediaSession は、音声や動画のプレーヤーを操作するための汎用的な手段を提供します。アプリでメディアが再生されていることを Android に通知することで、再生コントロールをアプリに委任できます。メディア セッションと統合することで、アプリはメディア再生を外部にアドバタイズし、外部ソースから再生コマンドを受信できます。これらのソースは、物理ボタン（ヘッドセットやテレビのリモコンの再生ボタンなど）または間接的なコマンド（Google アシスタントに「一時停止」を指示するなど）です。メディア セッションは、これらのコマンドをアプリに委任します。アプリは、コマンドの送信元が透過的なメディア プレーヤーにコマンドを適用します。

メディア セッションは、それが管理するプレーヤーとともに存在します。メディア セッションとその関連プレーヤーを所有するアクティビティまたはサービスの onCreate() メソッドで、メディア セッションを作成して初期化する必要があります。

メディア セッションの初期化

作成したばかりのメディア セッションには何の機能もありません。次の手順でセッションを初期化する必要があります。

  • メディア セッションがメディア コントローラとメディアボタンからコールバックを受信できるように、フラグを設定します。
  • PlaybackStateCompat のインスタンスを作成して初期化し、セッションに割り当てます。再生状態はセッション全体で変化するため、PlaybackStateCompat.Builder をキャッシュに保存して再利用することをおすすめします。
  • MediaSessionCompat.Callback のインスタンスを作成し、セッションに割り当てます（コールバックの詳細については後述します）。

メディア セッションは、セッションを所有するアクティビティまたはサービスの onCreate() メソッドで作成して初期化する必要があります。

アプリが新しく初期化（または停止）されたときにメディアボタンが機能するには、メディアボタンが送信するインテントに一致する再生アクションが PlaybackState に含まれている必要があります。そのため、初期化時に ACTION_PLAY がセッション状態に割り当てられます。詳細については、メディアボタンへの応答をご覧ください。

再生状態とメタデータの維持

メディア セッションの状態を表すクラスは 2 種類あります。

PlaybackStateCompat クラスは、プレーヤーの現在の動作状態を表します。以下が該当します。

  • トランスポートの状態（プレーヤーが再生中、一時停止中、バッファリング中など。getState() を参照）
  • エラーコード、および必要に応じてエラー メッセージ（getErrorCode() を参照し、下記の状態とエラーをご覧ください）。
  • プレーヤーの位置
  • 現在の状態で処理できる有効なコントローラ アクション

MediaMetadataCompat クラスは、再生中の素材を記述します。

  • アーティスト名、アルバム名、トラック名
  • トラックの長さ
  • ロック画面に表示されるアルバム アートワーク画像はビットマップで、最大サイズは 320x320 dp です（これより大きい場合は縮小されます）。
  • アートワークの大きいバージョンを指す ContentUris のインスタンス

プレーヤーの状態とメタデータは、メディア セッションの存在期間にわたって変化する可能性があります。状態またはメタデータが変更されるたびに、各クラス（PlaybackStateCompat.Builder() または MediaMetadataCompat.Builder()）に対応するビルダーを使用し、setPlaybackState() または setMetaData() を呼び出して、新しいインスタンスをメディア セッションに渡す必要があります。これらの頻繁なオペレーションによる全体的なメモリ消費量を削減するには、ビルダーを 1 回作成し、セッションの存続期間全体で再利用することをおすすめします。

状態とエラー

PlaybackState は、セッションの再生状態（getState()）と、必要に応じて関連するエラーコード（getErrorCode()）の個別の値を含むオブジェクトです。エラーは、致命的なエラーと致命的でないエラーに分類されます。

再生が中断された場合は、致命的なエラーを生成する必要があります。トランスポート状態を STATE_ERROR に設定し、setErrorMessage(int, CharSequence) で関連するエラーを指定します。エラーによって再生がブロックされている限り、PlaybackState は STATE_ERROR とエラーを報告し続ける必要があります。

致命的でないエラーは、アプリがリクエストを処理できないものの、再生を続行できる場合に発生します。トランスポートは「通常」の状態（STATE_PLAYING など）のままですが、PlaybackState にエラーコードが保持されます。たとえば、最後の曲が再生されているときにユーザーが次の曲へのスキップをリクエストした場合、再生は続行できますが、エラーコード ERROR_CODE_END_OF_QUEUE を含む新しい PlaybackState を作成してから setPlaybackState() を呼び出す必要があります。セッションに接続されているメディア コントローラは、コールバック onPlaybackStateChanged() を受け取り、何が起こったかをユーザーに説明します。致命的でないエラーは、発生時に 1 回だけ報告する必要があります。セッションが次に PlaybackState を更新するときに、同じ致命的でないエラーを再度設定しないでください（エラーが新しいリクエストへのレスポンスで発生した場合を除く）。

メディア セッションのロック画面

Android 4.0（API レベル 14）以降では、システムはメディア セッションの再生状態とメタデータにアクセスできます。ロック画面にメディア コントロールとアートワークを表示する方法は次のとおりです。動作は Android のバージョンによって異なります。

アルバム アートワーク

Android 4.0（API レベル 14）から Android 10（API レベル 29）では、ロック画面の背景にアルバム アートワークが表示されます。ただし、メディア セッションのメタデータに背景ビットマップが含まれている場合に限ります。

トランスポート コントロール

Android 4.0（API レベル 14）から Android 4.4（API レベル 19）では、メディア セッションがアクティブで、メディア セッションのメタデータに背景ビットマップが含まれている場合、ロック画面にトランスポート コントロールが自動的に表示されます。

Android 5.0（API レベル 21）以降では、システムはロック画面にトランスポート コントロールを提供しません。代わりに、MediaStyle 通知を使用してトランスポート コントロールを表示する必要があります。

カスタム アクションを追加する

メディアアプリは、カスタム アクション（高評価、いいね、30 秒巻き戻しなど）を定義できます。カスタム アクションは、まったく新しい動作を実装する必要があります。PlaybackStateCompat で定義されている標準のトランスポート コントロール アクションを置き換えるために、カスタム アクションを使用しないでください。

addCustomAction() を使用してカスタム アクションを追加します。次の例は、高評価アクションのコントロールを追加する方法を示しています。

Kotlin

stateBuilder.addCustomAction(
        PlaybackStateCompat.CustomAction.Builder(
                CUSTOM_ACTION_THUMBS_UP,
                resources.getString(R.string.thumbs_up),
                thumbsUpIcon
        ).run {
            setExtras(customActionExtras)
            build()
        }
)

Java

stateBuilder.addCustomAction(new PlaybackStateCompat.CustomAction.Builder(
    CUSTOM_ACTION_THUMBS_UP, resources.getString(R.string.thumbs_up), thumbsUpIcon)
    .setExtras(customActionExtras)
    .build());

完全な例については、Universal Music Playerをご覧ください。

onCustomAction() を使用してアクションに応答します。

Kotlin

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

Java

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

Universal Music Player もご覧ください。

メディア セッション コールバック

主なメディア セッション コールバック メソッドは、onPlay()、onPause()、onStop() です。この中に、プレーヤーを制御するコードを追加します。

セッションのコールバックは実行時（onCreate() 内）にインスタンス化して設定するため、アプリは、異なるプレーヤーを使用する代替コールバックを定義し、デバイスとシステムレベルに応じてコールバックとプレーヤーの適切な組み合わせを選択できます。アプリの他の部分を変更することなく、プレーヤーを変更できます。たとえば、Android 4.1（API レベル 16）以降で実行する場合は ExoPlayer を使用し、それ以前のシステムでは MediaPlayer を使用できます。

コールバックは、プレーヤーの制御やメディア セッションの状態遷移の管理だけでなく、アプリの機能の有効化と無効化、他のアプリやデバイス ハードウェアとのやり取りの制御も行います。（オーディオ出力の制御をご覧ください）。

メディア セッションのコールバック メソッドの実装は、アプリの構造によって異なります。オーディオ アプリと動画アプリでコールバックを使用する方法を説明する別のページで、アプリの種類ごとにコールバックを実装する方法を説明しています。