ExoPlayer 試用版應用程式

ExoPlayer 的主要示範應用程式有兩個主要用途：

  1. 提供相對簡單但功能完整的 ExoPlayer 使用範例。您可以使用示範應用程式做為起點，方便您開發自己的應用程式。
  2. 方便您試用 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)。選取範例後，系統會開啟第二個活動 (PlayerActivity) 進行播放。這個示範包含播放控制項和曲目選取功能。它也會使用 ExoPlayer 的 EventLogger 公用程式類別，將有用的偵錯資訊輸出至系統記錄。您可以使用下列指令查看這項記錄 (以及其他代碼的錯誤層級記錄)：

adb logcat EventLogger:V *:E

啟用隨附解碼器

ExoPlayer 提供多種擴充功能，可讓您使用內含的軟體解碼器，包括 AV1、VP9、Opus、FLAC 和 FFmpeg (僅限音訊)。試用版應用程式可以在建構時納入和使用這些擴充功能，如下所示：

  1. 建立要納入的每個擴充功能。請注意，這是一項手動程序。如需操作說明，請參閱各擴充功能中的 README.md 檔案。

  2. 在 Android Studio 的「Build Variants」檢視畫面中，將示範模組的建構變數設為 withDecoderExtensionsDebug 或 withDecoderExtensionsRelease，如以下圖所示。

    選取「withDecoderExtensionsDebug」建構變數示範

  3. 照常編譯、安裝及執行 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 [Long] 應剪輯範例的起點，以毫秒為單位。
    • clip_end_position_ms [Long] 應剪輯樣本的終點，以毫秒為單位。
    • 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。範例設定額外項目與 androidx.media3.demo.main.action.VIEW 相同，但兩個差異除外：

  • 額外項目的鍵應包含底線，並以樣本的 0 為基底索引做為後置字元。例如，extension_0 會提示第一個樣本的樣本類型。drm_scheme_1 會設定第二個樣本的 DRM 配置。
  • 樣本的 URI 會以額外項目的形式傳遞，並使用 uri_<sample-index> 做為鍵。

其他不依附於樣本的額外項目則不會變更。舉例來說，您可以在終端機中執行下列指令，藉此播放含有兩個項目的播放清單，藉此覆寫第二個項目的延伸：

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