このページは Cloud Translation API によって翻訳されました。

ExoPlayer デモアプリケーション

ExoPlayer のメインのデモアプリは、主に次の 2 つの目的を果たします。

比較的シンプルながらも完全な機能を備えた ExoPlayer の使用例を紹介します。このデモアプリは、独自のアプリを開発するための出発点として便利です。
ExoPlayer を簡単に試せるようにするためこのデモアプリを使用すると、付属のサンプルに加えて、独自のコンテンツの再生をテストできます。

このページでは、デモアプリを入手、コンパイル、実行する方法について説明します。また、デモアプリを使用して独自のメディアを再生する方法についても説明します。

コードの取得

メインのデモアプリのソースコードは、GitHub プロジェクトの demos/main フォルダにあります。プロジェクトのクローンを作成していない場合は、ローカルディレクトリにクローンを作成します。

git clone https://github.com/androidx/media.git

次に、Android Studio でプロジェクトを開きます。[Android Project] ビューには次のように表示されます（デモアプリの関連フォルダが展開されています）。

Android Studio のプロジェクト

コンパイルと実行

デモアプリをコンパイルして実行するには、Android Studio で demo 構成を選択して実行します。接続された Android デバイスにデモアプリをインストールして実行します。可能であれば、実機を使用することをおすすめします。代わりにエミュレータを使用する場合は、サポート対象デバイスのエミュレータに関するセクションを参照し、仮想デバイスが API レベル 23 以上のシステムイメージを使用するようにしてください。

SampleChooserActivity と PlayerActivity

デモアプリはサンプルのリスト（SampleChooserActivity）を表示します。サンプルを選択すると、再生用の 2 つ目のアクティビティ（PlayerActivity）が開きます。このデモには、再生コントロールとトラック選択機能があります。また、ExoPlayer の EventLogger ユーティリティクラスを使用して、有用なデバッグ情報をシステムログに出力します。このロギングは、（他のタグのエラーレベルのロギングとともに）次のコマンドで確認できます。

adb logcat EventLogger:V *:E

バンドルされたデコーダを有効にする

ExoPlayer には、AV1、VP9、Opus、FLAC、FFmpeg（音声のみ）など、バンドルされたソフトウェアデコーダを使用できる拡張機能が多数あります。デモアプリは、次のように拡張機能を組み込んで使用するように作成できます。

追加する拡張機能をそれぞれ作成します。これは手動プロセスであることに注意してください。手順については、各拡張機能の README.md ファイルをご覧ください。
次の画像に示すように、Android Studio の [Build Variants] ビューで、デモモジュールのビルドバリアントを withDecoderExtensionsDebug または withDecoderExtensionsRelease に設定します。
通常どおり demo 構成をコンパイル、インストール、実行します。

デフォルトでは、拡張デコーダは適切なプラットフォームデコーダが存在しない場合にのみ使用されます。以降のセクションで説明するように、拡張デコーダが優先されるように指定できます。

自分のコンテンツの再生

デモアプリで独自のコンテンツを再生するには、複数の方法があります。

1. assets/media.exolist.json の編集

デモアプリにリストされているサンプルは、assets/media.exolist.json から読み込まれます。この JSON ファイルを編集することで、デモアプリからサンプルを追加または削除できます。スキーマは次のとおりです。ここで、[O] はオプションの属性を示します。

[
  {
    "name": "Name of heading",
    "samples": [
      {
        "name": "Name of sample",
        "uri": "The URI of the sample",
        "extension": "[O] Sample type hint. Values: mpd, ism, m3u8",
        "clip_start_position_ms": "[O] A start point to which the sample should be clipped, in milliseconds"
        "clip_end_position_ms": "[O] An end point from which the sample should be clipped, in milliseconds"
        "drm_scheme": "[O] Drm scheme if protected. Values: widevine, playready, clearkey",
        "drm_license_uri": "[O] URI of the license server if protected",
        "drm_force_default_license_uri": "[O] Whether to force use of "drm_license_uri" for key requests that include their own license URI",
        "drm_key_request_properties": "[O] Key request headers if protected",
        "drm_session_for_clear_content": "[O] Whether to attach a DRM session to clear video and audio tracks"
        "drm_multi_session": "[O] Enables key rotation if protected",
        "subtitle_uri": "[O] The URI of a subtitle sidecar file",
        "subtitle_mime_type": "[O] The MIME type of subtitle_uri (required if subtitle_uri is set)",
        "subtitle_language": "[O] The BCP47 language code of the subtitle file (ignored if subtitle_uri is not set)",
        "ad_tag_uri": "[O] The URI of an ad tag to load via the IMA extension"
      },
      ...etc
    ]
  },
  ...etc
]

サンプルの再生リストは、次のスキーマを使用して指定できます。

[
  {
    "name": "Name of heading",
    "samples": [
      {
        "name": "Name of playlist sample",
        "playlist": [
          {
            "uri": "The URI of the first sample in the playlist",
            "extension": "[O] Sample type hint. Values: mpd, ism, m3u8"
            "clip_start_position_ms": "[O] A start point to which the sample should be clipped, in milliseconds"
            "clip_end_position_ms": "[O] An end point from which the sample should be clipped, in milliseconds"
            "drm_scheme": "[O] Drm scheme if protected. Values: widevine, playready, clearkey",
            "drm_license_uri": "[O] URI of the license server if protected",
            "drm_force_default_license_uri": "[O] Whether to force use of "drm_license_uri" for key requests that include their own license URI",
            "drm_key_request_properties": "[O] Key request headers if protected",
            "drm_session_for_clear_content": "[O] Whether to attach a DRM session to clear video and audio tracks",
            "drm_multi_session": "[O] Enables key rotation if protected",
            "subtitle_uri": "[O] The URI of a subtitle sidecar file",
            "subtitle_mime_type": "[O] The MIME type of subtitle_uri (required if subtitle_uri is set)",
            "subtitle_language": "[O] The BCP47 language code of the subtitle file (ignored if subtitle_uri is not set)"
          },
          {
            "uri": "The URI of the second sample in the playlist",
            ...etc
          },
          ...etc
        ]
      },
      ...etc
    ]
  },
  ...etc
]

必要に応じて、鍵リクエストヘッダーは、各ヘッダーの文字列属性を含むオブジェクトとして指定されます。

"drm_key_request_properties": {
  "name1": "value1",
  "name2": "value2",
  ...etc
}

サンプル選択ツールのアクティビティでは、オーバーフローメニューに拡張機能デコーダを優先するかどうかを指定するオプションが含まれています。

ローカルファイルの URI と対象範囲別ストレージの制限

ローカルファイルの URI を指定すると、デモアプリは、ローカルファイルの読み取りに必要なストレージアクセス権限をリクエストします。ただし、Android 13 以降では、末尾が一般的なメディアファイル拡張子（.mp4 など）ではない任意のファイルを読み込むことはできません。そのようなファイルを読み込む必要がある場合は、デモアプリ固有のストレージディレクトリ（アクセス制限がない場所）にファイルを配置できます。通常、これは /sdcard/Android/data/androidx.media3.demo.main/files にあります。

2. 外部 exolist.json ファイルの読み込み

デモアプリでは、上記のスキーマを使用して、*.exolist.json の規則に従って名前を付けた外部 JSON ファイルを読み込むことができます。たとえば、このようなファイルを https://yourdomain.com/samples.exolist.json でホストしている場合は、以下を使用してデモアプリで開くことができます。

adb shell am start -a android.intent.action.VIEW \
    -d https://yourdomain.com/samples.exolist.json

デモアプリがインストールされたデバイスで（ブラウザやメールクライアントなどで）*.exolist.json リンクをクリックすると、デモアプリでもリンクが開きます。したがって、*.exolist.json JSON ファイルをホストすると、他のユーザーがデモアプリで試せるコンテンツを配布するための簡単な方法が提供されます。

3. インテントの呼び出し

インテントを使用して、サンプルのリストをバイパスし、直接再生を開始できます。単一のサンプルを再生するには、インテントのアクションを androidx.media3.demo.main.action.VIEW に設定し、そのデータ URI を再生するサンプルのアクションに設定します。このようなインテントは、以下を使用してターミナルから呼び出すことができます。

adb shell am start -a androidx.media3.demo.main.action.VIEW \
    -d https://yourdomain.com/sample.mp4

単一のサンプルインテントでサポートされるオプションのエクストラは次のとおりです。

構成エクストラの例:
- mime_type [文字列] MIME タイプのヒントのサンプル。たとえば、DASH コンテンツの場合は application/dash+xml です。
- clip_start_position_ms（長形式）: サンプルをクリップする開始点（ミリ秒単位）。
- clip_end_position_ms（長整数）: サンプルをクリップする終点（ミリ秒単位）。
- drm_scheme [文字列] DRM スキーム（保護されている場合）。有効な値は widevine、playready、clearkey です。DRM スキームの UUID も使用できます。
- drm_license_uri [文字列] 保護されている場合、ライセンスサーバーの URI。
- drm_force_default_license_uri [ブール値] 独自のライセンス URI を含むキーのリクエストに対して、drm_license_uri を強制的に使用するかどうか。
- drm_key_request_properties [文字列配列] 保護されている場合、name1、value1、name2、value2 などとしてパックされるキーリクエストヘッダー。
- drm_session_for_clear_content（ブール値）DRM セッションをアタッチして動画トラックと音声トラックを消去するかどうか。
- drm_multi_session [ブール値] 保護されている場合、鍵のローテーションを有効にします。
- subtitle_uri [文字列] 字幕サイドカーファイルの URI。
- subtitle_mime_type [文字列] subtitle_uri の MIME タイプ（subtitle_uri が設定されている場合は必須）。
- subtitle_language [文字列] 字幕ファイルの BCP47 言語コード（subtitle_uri が設定されていない場合は無視されます）。
- ad_tag_uri [文字列] [IMA 拡張機能][]を使用して読み込む広告タグの URI。
- prefer_extension_decoders [ブール値] 拡張デコーダがプラットフォームのものより優先されるかどうか。

adb shell am start を使用してインテントを起動する場合、オプションの文字列エクストラを --es で設定できます（例:--es extension mpd）。オプションのブール値のエクストラは、--ez で設定できます（例:--ez prefer_extension_decoders TRUE）。オプションの長いエクストラは、--el で設定できます（例:--el clip_start_position_ms 5000）。省略可能な文字列配列のエクストラは、--esa で設定できます（例:--esa drm_key_request_properties name1,value1）。

サンプルのプレイリストを再生するには、インテントのアクションを androidx.media3.demo.main.action.VIEW_LIST に設定します。サンプル構成エクストラは、次の 2 つの点を除き、androidx.media3.demo.main.action.VIEW の場合と同じです。

エクストラのキーには、アンダースコアと、サフィックスとしてサンプルの 0 から始まるインデックスを含める必要があります。たとえば、extension_0 は、最初のサンプルのサンプルタイプのヒントになります。drm_scheme_1 は、2 番目のサンプルの DRM スキームを設定します。
サンプルの URI が、キー uri_<sample-index> を含むエクストラとして渡されます。

サンプルに依存しないその他のエクストラは、変更しません。たとえば、ターミナルで次のコマンドを実行し、2 つのアイテムを含むプレイリストを再生して、2 番目のアイテムの拡張子をオーバーライドできます。

adb shell am start -a androidx.media3.demo.main.action.VIEW_LIST \
    --es uri_0 https://a.com/sample1.mp4 \
    --es uri_1 https://b.com/sample2.fake_mpd \
    --es extension_1 mpd