ExoPlayer 主演示应用（demos/main）完整指南：构建运行、样本配置与二次开发参考

ExoPlayer 主演示应用demos/main完整指南构建运行、样本配置与二次开发参考【免费下载链接】ExoPlayerAn extensible media player for Android项目地址: https://gitcode.com/gh_mirrors/exop/ExoPlayer本篇技术指南以 ExoPlayer 仓库中 demos/main/README.md 为核心骨架系统讲解主演示应用main demo app的定位、构建运行方式、样本清单media.exolist.json配置规范以及如何通过外部 JSON 文件与 Intent 播放自有内容。读完本文你将掌握把该 Demo 作为 ExoPlayer 二次开发起点工程的完整方法并能独立配置 DRM、字幕、广告、播放列表等复杂样本。Demo 应用的定位可运行的 ExoPlayer 参考工程主演示应用位于仓库的demos/main目录是 ExoPlayer 官方提供的核心示例工程。它有两个核心定位作为参考项目它使用 ExoPlayer 播放大量测试流代码简洁但功能完整可作为开发其他基于 ExoPlayer 应用的起点或参考作为试玩工具除内置样本外它还支持通过外部 JSON 清单和 Intent 直接播放你自己的媒体内容便于快速验证 ExoPlayer 对各种格式、DRM 方案与广告场景的支持情况。从 settings.gradle 可以看到主 Demo 对应 Gradle 工程名demoprojectDir指向demos/main同一demos目录下还包含demo-cast、demo-gl、demo-surface、demo-transformer等其他演示工程。从源码结构看demos/main/src/main/java/com/google/android/exoplayer2/demoDemo 应用由 8 个类组成职责划分清晰类职责SampleChooserActivity样本选择界面从 JSON 清单加载分组样本列表支持下载切换PlayerActivity播放界面负责 ExoPlayer 的创建、生命周期管理与错误处理DemoUtil工具类构建 RenderersFactory、DataSource、DownloadManager 等全局组件IntentUtilIntent 与MediaItem之间的双向转换解析/写入 extraDownloadTracker跟踪样本的离线下载状态DemoDownloadService后台下载服务继承自DownloadService应用包含两个主要 ActivitySampleChooserActivity列出样本点击后进入PlayerActivity进行播放。播放界面提供控制条与轨道选择功能并使用 ExoPlayer 的EventLogger工具类向系统日志输出调试信息。构建与运行构建运行方式在 demos/README.md 中有详细说明支持 Android Studio 与命令行 Gradle 两种途径。从 Android Studio 运行打开 Android Studio选择File - New - Import Project指定 ExoPlayer 仓库根目录在 Run Configuration 下拉框中选择demo点击 Run 即可在已连接的 Android 设备上安装并运行。官方建议优先使用真机测试若使用模拟器请确保 Virtual Device 的系统镜像 API Level 不低于 23。说明本仓库源码类注释标注com.google.android.exoplayer2包已废弃官方推荐迁移至androidx.media3。本文描述的是当前仓库demos/main的实际代码实现供学习与参考。使用命令行 Gradle在仓库根目录打开终端# 列出所有工程Demo 工程以 demo 开头 ./gradlew projects # 查看某个 demo 工程的可用任务重点看 Install tasks ./gradlew :demo name:tasks # 执行安装任务 ./gradlew :demo name:install task例如./gradlew :demo:installNoDecoderExtensionsDebug会以 Debug 模式、不包含解码器扩展的方式安装主 Demo 应用。构建变体Build Variants与解码器扩展从 demos/main/build.gradle 可以看出demo模块定义了decoderExtensions这一 flavor 维度包含两个变体noDecoderExtensionsUSE_DECODER_EXTENSIONS falsewithDecoderExtensionsUSE_DECODER_EXTENSIONS true。DemoUtil.buildRenderersFactory(...)见 DemoUtil.java会据此决定DefaultRenderersFactory的扩展解码器模式未启用扩展时使用EXTENSION_RENDERER_MODE_OFF仅平台解码器启用扩展且用户勾选优先扩展解码器时使用EXTENSION_RENDERER_MODE_PREFER启用扩展但未勾选时使用EXTENSION_RENDERER_MODE_ON平台无合适解码器时才回退到扩展。withDecoderExtensions变体会额外引入 extension-av1、extension-ffmpeg、extension-flac、extension-opus、extension-vp9、extension-rtmp 等模块见 build.gradle。启用步骤为先按各扩展目录下README.md的指引手动构建扩展再在 Android Studio 的 Build Variants 面板中为 demo 模块选择withDecoderExtensionsDebug或withDecoderExtensionsRelease变体最后正常编译安装运行。默认情况下扩展解码器仅在不存在合适平台解码器时使用用户也可在样本选择界面的溢出菜单中勾选优先使用扩展解码器。查看调试日志PlayerActivity通过EventLogger输出调试信息PlayerActivity.java可用如下命令查看同时过滤其他 tag 的错误级日志adb logcat EventLogger:V *:E界面与播放流程的源码实现样本选择SampleChooserActivitySampleChooserActivity启动时会检查 Intent 是否携带 data URI若通过外部*.exolist.json链接打开则只加载该文件SampleChooserActivity.java否则扫描 assets 目录下所有以.exolist.json结尾的资源并排序展示。清单加载在AsyncTaskSampleListLoader中进行使用JsonReader逐字段解析SampleChooserActivity.java。点击某个样本条目后Activity 会把该样本对应的MediaItem列表通过IntentUtil.addToIntent(...)写入 Intent 并启动PlayerActivitySampleChooserActivity.java。播放器初始化PlayerActivityPlayerActivity.initializePlayer()PlayerActivity.java展示了 ExoPlayer 的标准装配流程从 Intent 生成MediaItem列表createMediaItems通过ExoPlayer.Builder构建播放器并设置MediaSource.FactorycreateMediaSourceFactory按prefer_extension_decodersextra 选择 RenderersFactory注册Player.ListenerPlayerEventListener与EventLogger分析监听器设置AudioAttributes.DEFAULT自动处理音频焦点与setPlayWhenReady将播放器绑定到StyledPlayerView并启动DebugTextViewHelper在界面实时刷新调试信息调用player.setMediaItems(...)与player.prepare()开始播放。createMediaSourceFactory()PlayerActivity.java同时装配了 DRMDefaultDrmSessionManagerProvider、客户端广告IMAImaAdsLoader与服务器端广告插入ImaServerSideAdInsertionMediaSource三个能力且服务器端广告加载器的状态可在 Activity 重建时通过 Bundle 保存/恢复。PlayerEventListener还处理了直播落后窗口ERROR_CODE_BEHIND_LIVE_WINDOW自动跳回默认位置、音视频轨道不受支持时弹出 Toast 提示等边界情况PlayerErrorMessageProvider则把DecoderInitializationException等底层异常转换为用户可读的错误文案。网络与缓存DemoUtilDemoUtil中USE_CRONET_FOR_NETWORKING trueDemoUtil.java即默认优先使用 Cronet 作为网络栈对应 extension-cronet若 Cronet 引擎构建失败则回退到DefaultHttpDataSource并配置CookieManagerDemoUtil.java。此外getDataSourceFactory(...)返回的是基于SimpleCacheNoOpCacheEvictor的只读缓存数据源CacheDataSource缓存目录为context.getExternalFilesDir(null)/downloads并设置FLAG_IGNORE_CACHE_ON_ERRORDemoUtil.java。下载管理依赖DownloadManager线程池大小为 6与StandaloneDatabaseProvider示例中的DemoDownloadService在启动时即会尝试拉起下载服务SampleChooserActivity.java。内置样本清单media.exolist.jsonDemo 内置的样本清单位于 demos/main/src/main/assets/media.exolist.json共 701 行覆盖了丰富的测试场景。从清单内容可以看到如下分组Clear DASHH264/H265/VP9 的 HD 与 UHD 清晰流Widevine DASHMP4(H264/H265) 与 WebM(VP9) 的 cenc/cbcs 加密流以及 L3/L1 安全级别、HDCP 各版本、许可过期30s license等策略测试样本60fps DASH1080p/4K 的 60fps 清晰与加密流DASH - Multiple base URLs多 Base URL 与故障切换测试HLSApple 官方 TS/FMP4 示例、多变体 playlist、纯媒体 playlistSmoothStreaming清晰流与 PlayReady 加密流IMA sample ad tagsVAST 线性/可跳过/重定向广告、VMAP 前中后贴片广告、空 midroll、长 ad pod 等IMA DAI streams通过ssai://协议加载的 HLS/DASH VOD 与 Live 服务端广告插入流Playlists混合格式播放列表、加密与清晰交替、手动插播利用clip_start_position_ms/clip_end_position_ms裁剪AV1清晰与 Widevine 加密的 WebM 样本SubtitlesTTML、WebVTT、SubStation Alpha 等多种字幕MiscMP4、AAC、TS、MKV、WebM、MP3、Ogg、Flac、AV1 等杂项格式。配置自有样本编辑 media.exolist.json要在 Demo 中加入你自己的样本直接编辑demos/main/src/main/assets/media.exolist.json即可。其 Schema 如下[O]表示可选属性[ { name: 分组标题, samples: [ { name: 样本名称, uri: 样本 URI, extension: [O] 样本类型提示。取值: mpd, ism, m3u8, clip_start_position_ms: [O] 裁剪起始位置单位毫秒, clip_end_position_ms: [O] 裁剪结束位置单位毫秒, drm_scheme: [O] 受保护时的 DRM 方案。取值: widevine, playready, clearkey, drm_license_uri: [O] 受保护时的许可证服务器 URI, drm_force_default_license_uri: [O] 是否强制对自带许可证 URI 的密钥请求使用 drm_license_uri, drm_key_request_properties: [O] 受保护时的密钥请求头, drm_session_for_clear_content: [O] 是否为清晰音视频轨道附加 DRM 会话, drm_multi_session: [O] 受保护时启用密钥轮换, subtitle_uri: [O] 字幕侧车文件 URI, subtitle_mime_type: [O] subtitle_uri 的 MIME 类型设置 subtitle_uri 时必填, subtitle_language: [O] 字幕文件的 BCP47 语言代码, ad_tag_uri: [O] 通过 IMA 扩展加载的广告 tag URI } ] } ]播放列表形式的样本使用如下 Schemaplaylist中每个条目同样支持上述可选属性[ { name: 分组标题, samples: [ { name: 播放列表样本名称, playlist: [ { uri: 第一个样本的 URI, extension: [O] ... }, { uri: 第二个样本的 URI, ...: ... } ] } ] } ]密钥请求头以字符串对象的形式指定drm_key_request_properties: { name1: value1, name2: value2 }这些 JSON 字段与源码解析逻辑一一对应SampleChooserActivity的readEntry(...)方法SampleChooserActivity.java会读取uri、extension、clip_start_position_ms、clip_end_position_ms、ad_tag_uri、drm_scheme、drm_license_uri兼容旧字段drm_license_url、drm_key_request_properties、drm_session_for_clear_content、drm_multi_session、drm_force_default_license_uri、subtitle_uri、subtitle_mime_type、subtitle_language、playlist等字段并映射为MediaItem.Builder的对应配置。其中extension字段会经Util.inferContentTypeForExtension(...)推断内容类型并设置自适应 MIME 类型如application/dashxml而uri本身无法推断类型时则可借助该提示。播放自有内容三种方式除了直接编辑内置 JSONDemo 还提供另外两种方式播放你自己的内容。方式一加载外部 exolist.json 文件Demo 应用可以通过 Intent 加载遵循上述 Schema 且文件名符合*.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在已安装 Demo 的设备上点击任意*.exolist.json链接例如浏览器或邮件客户端中也会自动在 Demo 中打开。因此托管一个*.exolist.json文件是向他人分发测试内容的最简单方式。这一机制依赖于 AndroidManifest.xml 中为SampleChooserActivity注册的VIEWBROWSABLEIntent 过滤器scheme 支持http/https/content/asset/filepathPattern 匹配.*\.exolist\.json。方式二直接发起 Intent 播放单个样本可通过 Intent 绕过样本列表、直接进入播放。播放单个样本时action 设为com.google.android.exoplayer.demo.action.VIEWdata URI 设为待播放内容地址adb shell am start -a com.google.android.exoplayer.demo.action.VIEW \ -d https://yourdomain.com/sample.mp4单个样本 Intent 支持的可选 extra 如下样本配置类 extramime_type[String]样本 MIME 类型提示例如 DASH 内容填application/dashxmlclip_start_position_ms[Long]裁剪起始位置毫秒clip_end_position_ms[Long]裁剪结束位置毫秒drm_scheme[String]受保护时的 DRM 方案合法值为widevine、playready、clearkey也接受 DRM Scheme UUIDdrm_license_uri[String]受保护时的许可证服务器 URIdrm_force_default_license_uri[Boolean]是否强制对自带许可证 URI 的密钥请求使用drm_license_uridrm_key_request_properties[String 数组]受保护时的密钥请求头按 name1, value1, name2, value2 依次排列drm_session_for_clear_content[Boolean]是否为清晰音视频轨道附加 DRM 会话drm_multi_session[Boolean]受保护时启用密钥轮换subtitle_uri[String]字幕侧车文件 URIsubtitle_mime_type[String]subtitle_uri的 MIME 类型设置subtitle_uri时必填subtitle_language[String]字幕文件的 BCP47 语言代码ad_tag_uri[String]使用 IMA 扩展加载的广告 tag URIprefer_extension_decoders[Boolean]是否优先使用扩展解码器而非平台解码器。使用adb shell am start时各类型 extra 的传参方式为字符串用--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。在源码层面这些 extra 由IntentUtil.createMediaItemsFromIntent(...)IntentUtil.java解析为MediaItem列表其中 DRM 相关 extra 在populateDrmPropertiesFromIntent(...)中处理IntentUtil.javadrm_key_request_properties按两两配对的方式填充请求头 Mapdrm_scheme经Util.getDrmUuid(...)转换为 UUID。方式三发起 Intent 播放播放列表播放样本列表时action 设为com.google.android.exoplayer.demo.action.VIEW_LIST。与VIEW相比有两点差异extra 的 key 需要追加_加样本 0 起始索引作为后缀例如extension_0表示第一个样本的类型提示drm_scheme_1表示第二个样本的 DRM 方案样本的 URI 通过uri_样本索引作为 extra 传入。与样本无关的其他 extra 不变。例如播放两个条目的播放列表并覆盖第二个条目的类型提示adb shell am start -a com.google.android.exoplayer.demo.action.VIEW_LIST \ --es uri_0 https://a.com/sample1.mp4 \ --es uri_1 https://b.com/sample2.fake_mpd \ --es extension_1 mpd注意IntentUtil.addToIntent(...)IntentUtil.java在写入多条目 Intent 时正是采用uri_0、uri_1这类带索引后缀的命名方式因此外部命令与内部跳转使用的是同一套协议。其他功能要点离线下载样本列表条目右侧有下载按钮点击后通过DownloadTracker.toggleDownload(...)触发下载SampleChooserActivity.java。下载受以下限制播放列表多条目不支持下载、带广告配置的样本不支持下载、URI 必须为http/https协议。播放时PlayerActivity.createMediaItems(...)会把已下载样本的DownloadRequest信息媒体 ID、URI、自定义缓存键、MIME 类型、StreamKeys、DRM KeySetId 等合并进MediaItemPlayerActivity.java从而优先播放本地缓存内容。Android 13API 33及以上还需授予POST_NOTIFICATIONS权限才能显示下载进度通知。权限与清单AndroidManifest.xml 声明了INTERNET、ACCESS_NETWORK_STATE、READ_EXTERNAL_STORAGE、RECEIVE_BOOT_COMPLETED、FOREGROUND_SERVICE、POST_NOTIFICATIONS等权限并支持 Android TVLEANBACK_LAUNCHER、android.software.leanback。PlayerActivity还声明了launchModesingleTop并处理onNewIntent从而支持在播放中通过新 Intent 切换内容同时它通过Util.checkCleartextTrafficPermitted(...)检查明文流量是否被允许相关说明见 docs/issues/cleartext-not-permitted.md并通过Util.maybeRequestReadExternalStoragePermission(...)在必要时请求外部存储读取权限。从 Demo 到自有应用迁移建议从源码结构看将demos/main作为起点开发自有播放器应用时可以重点关注以下复用点直接复用PlayerActivity的初始化/释放模板但根据你的业务裁剪createMediaSourceFactory()中不需要的广告ImaAdsLoader或 DRM 组件将DemoUtil中的getHttpDataSourceFactory/getDataSourceFactory抽象为你的全局网络与缓存配置若不需要离线下载可移除DownloadTracker、DemoDownloadService相关代码及AndroidManifest.xml中的 service 声明。需要提醒的是当前仓库中的com.google.android.exoplayer2包已被标注为 deprecated官方推荐迁移到androidx.media3仓库根目录提供 media3-migration.sh 迁移脚本新项目建议直接基于 Media3 的 API 开发同时可继续参考本 Demo 的应用架构与流程设计。延伸阅读全部 Demo 工程说明与运行方式demos/README.mdDemo 应用的官方文档与本文内容相互印证docs/demo-application.md支持的媒体格式总览docs/supported-formats.md支持的设备与模拟器说明docs/supported-devices.md明文流量被禁用的排查指南docs/issues/cleartext-not-permitted.md【免费下载链接】ExoPlayerAn extensible media player for Android项目地址: https://gitcode.com/gh_mirrors/exop/ExoPlayer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考