ExoPlayer 的主演示版应用有两个主要用途:
- 提供一个相对简单但功能齐全的 ExoPlayer 用法示例。您可以参考演示版应用来开发自己的应用。
- 让您轻松试用 ExoPlayer。除随附的示例外,该演示版应用还可用于测试您自己的内容的播放情况。
本页介绍了如何获取、编译和运行演示版应用,还介绍了如何使用该应用播放自己的媒体。
获取代码
主演示版应用的源代码可以在 GitHub 项目的 demos/main
文件夹中找到。如果尚未将项目克隆到本地目录,请执行此操作:
git clone https://github.com/androidx/media.git
接下来,在 Android Studio 中打开项目。您应该会在 Android Project 视图(演示版应用的相关文件夹已展开)中看到以下内容:
编译和运行
如需编译并运行演示版应用,请在 Android Studio 中选择并运行 demo
配置。演示版应用将在已连接的 Android 设备上安装并运行。
我们建议您尽可能使用实体设备。如果您想改用模拟器,请参阅支持的设备的模拟器部分,并确保您的虚拟设备使用的是 API 级别至少为 23 的系统映像。
演示版应用会显示示例列表 (SampleChooserActivity
)。选择示例将打开第二个 activity (PlayerActivity
) 进行播放。该演示版包含播放控件和轨道选择功能。它还使用 ExoPlayer 的 EventLogger
实用程序类将有用的调试信息输出到系统日志。可通过以下命令查看此日志记录(以及其他标记的错误级日志记录):
adb logcat EventLogger:V *:E
启用捆绑解码器
ExoPlayer 有许多允许使用捆绑式软件解码器的扩展程序,包括 AV1、VP9、Opus、FLAC 和 FFmpeg(仅限音频)。您可以构建演示版应用,以包含和使用这些扩展,如下所示:
- 构建要添加的各个附加信息。请注意,这是一个手动过程。如需了解相关说明,请参阅每个扩展程序中的
README.md
文件。 在 Android Studio 的 Build Variants 视图中,将演示模块的 build 变体设置为
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
}
在示例选择器 activity 中,溢出菜单包含用于指定是否首选扩展解码器的选项。
本地文件 URI 和分区存储限制
指定本地文件 URI 时,演示版应用会请求读取这些文件所需的存储空间访问权限。不过,从 Android 13 开始,无法加载不以典型媒体文件文件扩展名结尾的任意文件(如 .mp4
)。如果您需要加载此类文件,可以将其放在演示版应用的无访问权限限制的特定存储目录中。它通常位于 /sdcard/Android/data/androidx.media3.demo.main/files
。
2. 加载外部 exolist.json 文件
演示版应用可以使用上述架构加载外部 JSON 文件,并根据 *.exolist.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. 触发 intent
intent 可用于绕过示例列表并直接启动播放。如需播放单个样本,请将 intent 的操作设置为 androidx.media3.demo.main.action.VIEW
,并将其数据 URI 设置为要播放的样本的数据 URI。可以使用以下代码从终端触发此类 intent:
adb shell am start -a androidx.media3.demo.main.action.VIEW \ -d https://yourdomain.com/sample.mp4
单个示例 intent 支持的可选 extra 如下:
- 示例配置 extra:
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
[字符串] 字幕 Sidecar 文件的 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
触发 intent 时,可以使用 --es
设置可选的字符串 extra(例如,--es extension mpd
)。可使用 --ez
设置可选的布尔型 extra(例如,--ez prefer_extension_decoders TRUE
)。可以使用 --el
设置可选的长 extra(例如,--el clip_start_position_ms 5000
)。可以使用 --esa
设置可选的字符串数组 extra(例如,--esa drm_key_request_properties name1,value1
)。
如需播放示例播放列表,请将 intent 的操作设置为 androidx.media3.demo.main.action.VIEW_LIST
。示例配置 extra 与 androidx.media3.demo.main.action.VIEW
相同,但存在以下两个差异:
- extra 的键应以下划线和从 0 开始的样本索引作为后缀。例如,
extension_0
会提示第一个样本的样本类型。drm_scheme_1
将为第二个样本设置 DRM 方案。 - 示例的 URI 将作为 extra 与键
uri_<sample-index>
一起传递。
其他不依赖于示例的 extra 不会更改。例如,您可以在终端运行以下命令来播放包含两个项的播放列表,替换第二个项的扩展名:
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