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

メディア セッションは音声や動画をユニバーサルな方法で操作できる 表示されます。アプリでメディアを再生していることを Android に通知することで、再生 管理をアプリに委任できます。メディア セッションと統合すると、 メディアの再生を外部にアドバタイズし、再生コマンドを受信するアプリ 外部ソースからのデータですこれらのソースには、物理的なボタン（再生ボタンや ボタン、ヘッドセットやテレビのリモコンのボタン、 「一時停止」するよう指示するGoogle アシスタントへ）。メディア セッションは、これらのデータを 対象のメディア プレーヤーにそれらのコマンドを適用する コマンドの送信元が透過的です

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

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

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

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

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

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

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

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

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

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

MediaMetadataCompat クラスは再生中のマテリアルを記述します。

  • アーティスト名、アルバム名、トラック名
  • トラックの長さ
  • ロック画面に表示されるアルバム アートワーク（画像は最大サイズ 320 x 320 dp のビットマップ。それを超える場合は縮小される）
  • アートワークの拡大版の場所を示す ContentUris のインスタンス

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

状態とエラー

PlaybackState は、サービス アカウントに関する個別の値を含むオブジェクトです。 セッションの再生状態（getState()） 必要に応じて関連するエラーコード（getErrorCode()）を入力します。 致命的なエラーとそうでないエラーがあります。

再生が中断されると、必ず致命的なエラーを発生させる必要があります。つまり、 状態を STATE_ERROR に転送し、関連するエラーを setErrorMessage(int, CharSequence) に指定します。 エラーによって再生がブロックされる限り、PlaybackState は続行されます。 STATE_ERROR とエラーを報告します。

非致命的なエラーは、アプリがリクエストを処理できないものの、再生は続行できる場合に発生します。 トランスポートは「normal」状態（STATE_PLAYING など）ですが、PlaybackState にはエラーコードが保持されます。 たとえば、最後の曲が再生されていて、ユーザーが次の曲へのスキップをリクエストした場合、 エラー コード ERROR_CODE_END_OF_QUEUE を指定して新しい PlaybackState を作成し、 次に、setPlaybackState() を呼び出します。セッションにアタッチされたメディア コントローラがコールバックを受け取る onPlaybackStateChanged() を呼び出して、何が起こったかをユーザーに説明します。非致命的エラーは、発生時に一度だけ報告するようにします。そのセッションで次に 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 を使用するようにできます。

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

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