ExoPlayer 的主要試用版應用程式有兩個主要用途:
- 提供相對簡單但功能完整的 ExoPlayer 使用範例。將應用程式當做開發應用程式時的簡便起點。
- 這可讓你輕鬆試用 ExoPlayer。除了隨附的範例外,試用版應用程式也能用來測試播放您的內容。
本頁說明如何取得、編譯及執行試用版應用程式,也會說明如何使用這個應用程式播放自己的媒體。
取得程式碼
您可以在 GitHub 專案的 demos/main
資料夾中,找到主要試用版應用程式的原始碼。如果您尚未將專案複製到本機目錄中,請先完成這項操作:
git clone https://github.com/androidx/media.git
接著,在 Android Studio 中開啟專案。Android 專案檢視畫面中應該會顯示以下內容 (試用版應用程式的相關資料夾已展開):
編譯與執行
如要編譯並執行試用版應用程式,請在 Android Studio 選取並執行 demo
設定。試用版應用程式會在已連結的 Android 裝置上安裝及執行。建議您盡可能使用實體裝置。如果您想改用模擬器,請參閱「支援的裝置」的模擬器部分,並確認虛擬裝置使用 API 級別至少為 23 的系統映像檔。
試用版應用程式會顯示範例清單 (SampleChooserActivity
)。選取範例會開啟第二個活動 (PlayerActivity
)。示範模式提供播放控制項及追蹤選取功能。也會使用 ExoPlayer 的 EventLogger
公用程式類別,將實用的偵錯資訊輸出至系統記錄。您可以透過下列指令查看這項記錄 (以及其他標記的錯誤層級記錄):
adb logcat EventLogger:V *:E
啟用套裝組合解碼器
ExoPlayer 有許多擴充功能允許使用套裝軟體解碼器,包括 AV1、VP9、Opus、FLAC 和 FFmpeg (僅限音訊)。您可透過以下方式建構試用版應用程式,加入並使用這些擴充功能:
- 請逐一建立您想納入的擴充功能。請注意,這是手動程序。如需操作說明,請參閱各擴充功能中的
README.md
檔案。 在 Android Studio 的「Build Variants」檢視畫面中,將示範模組的建構變數設為
withDecoderExtensionsDebug
或withDecoderExtensionsRelease
,如下圖所示。照常編譯、安裝並執行
demo
設定。
根據預設,只有在合適的平台解碼器不存在時,系統才會使用擴充功能解碼器。您可以按照下列各節所述,指定建議使用的擴充功能解碼器。
播放自己的內容
在試用版應用程式中,您可以透過多種方式播放自己的內容。
1. 編輯 asset/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
[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
[String] 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