ExoPlayer HLS 播放接入实战从 MediaItem 到 HlsMediaSource 的完整指南与源码级解析【免费下载链接】ExoPlayerAn extensible media player for Android项目地址: https://gitcode.com/gh_mirrors/exop/ExoPlayerHTTP Live StreamingHLS由 RFC 8216 定义是 Android 端主流的自适应流媒体协议之一。ExoPlayer 内置了完整的 HLS 模块支持 MPEG-TS、FMP4/CMAF、AACADTS、MP3 等多种容器以及自适应码率切换、直播、低延迟 HLS 等能力。本文以仓库中 docs/hls.md 为骨架结合 library/hls 模块源码系统讲解如何接入 HLS 播放、如何读取 Manifest、如何自定义播放行为如禁用 chunkless preparation以及如何产出高质量 HLS 内容。读完本文你将能够把任意.m3u8链接快速接入 ExoPlayer并理解底层HlsMediaSource的关键配置项对播放行为的影响。HLS 模块支持的格式与能力总览ExoPlayer 的 HLS 支持矩阵由 supported-formats-hls.md 完整定义核心结论如下分类能力支持说明容器MPEG-TSYES经典 HLS 分段容器FMP4/CMAFYES现代低延迟 HLS 常用容器ADTSAACYES纯音频分段MP3YES纯音频分段字幕/隐藏字幕CEA-608YES常见于美区电视内容WebVTTYES通过#EXT-X-MEDIA声明的字幕轨元数据ID3YESTS 与 fMP4 内嵌见下文setMetadataTypeSCTE-35NO广告信令需自行扩展内容保护AES-128YESHLS 标准加密Sample AES-128NO部分 Apple 生态场景WidevineYESAPI 19cenc、25cbcsPlayReady SL2000YES仅 Android TV服务端控制Delta updatesYES直播 playlist 增量更新Blocking playlist reloadYES服务端阻塞式重载Blocking load of preload hintsYES除未定义长度的 byterange 外直播播放Regular live playbackYES常规直播Low-latency HLS (Apple)YES苹果生态低延迟方案#EXT-X-PART等Low-latency HLS (Community)NO社区方案如 LHLS注意容器格式支持并不意味着其中任何编码都支持——所含音视频的**样本格式sample formats**仍需受 ExoPlayer 解码能力限制详见 supported-formats.md。最快接入方式使用 MediaItem添加依赖HLS 支持位于独立模块中首先需要在 Gradle 中添加依赖将2.X.X替换为你使用的版本implementation com.google.android.exoplayer:exoplayer-hls:2.X.X最小可运行示例创建播放器实例后直接把 HLS playlist 的 URI 封装成MediaItem交给播放器即可// Create a player instance. ExoPlayer player new ExoPlayer.Builder(context).build(); // Set the media item to be played. player.setMediaItem(MediaItem.fromUri(hlsUri)); // Prepare the player. player.prepare();整个链路无需任何 HLS 特有代码ExoPlayer 会根据 URI 对应的 MIME 类型自动分派到 HLS 模块HlsMediaSource.Factory.getSupportedTypes()返回C.CONTENT_TYPE_HLS参见 HlsMediaSource.java。URI 不以.m3u8结尾时如果 URI 不带.m3u8后缀例如 CDN 签名 URL需要显式声明内容类型否则无法触发 HLS 分派MediaItem mediaItem new MediaItem.Builder() .setUri(hlsUri) .setMimeType(MimeTypes.APPLICATION_M3U8) .build(); player.setMediaItem(mediaItem);多码率自适应MediaItem 的 URI 既可以指向媒体 playlistmedia playlist单个码率的分段列表也可以指向多变体 playlistmultivariant playlist即通常说的 master playlist。当 URI 指向声明了多个#EXT-X-STREAM-INF标签的多变体 playlist 时ExoPlayer 会自动在变体之间自适应切换切换依据是可用带宽与设备能力分辨率、解码器支持等。想快速验证效果可以参考演示应用 media.exolist.json 中内置的 Apple bipbop 示例流TS 版、fMP4 版、纯音频变体均有这些是多码率 HLS 的标准测试资源。进阶接入使用 HlsMediaSource当需要更多自定义时数据源、加载策略、DRM、播放列表解析等可以绕过MediaItem直接构造HlsMediaSource// Create a data source factory. DataSource.Factory dataSourceFactory new DefaultHttpDataSource.Factory(); // Create a HLS media source pointing to a playlist uri. HlsMediaSource hlsMediaSource new HlsMediaSource.Factory(dataSourceFactory) .createMediaSource(MediaItem.fromUri(hlsUri)); // Create a player instance. ExoPlayer player new ExoPlayer.Builder(context).build(); // Set the media source to be played. player.setMediaSource(hlsMediaSource); // Prepare the player. player.prepare();注意HlsMediaSource的构造最终仍需要一个MediaItem内部持有其localConfiguration为空会抛NullPointerException因此两种方式本质是同一体系区别只在于Factory暴露的自定义入口。Factory 的默认组件与配置项从源码 HlsMediaSource.java 可见HlsMediaSource.Factory构造时默认装配了以下组件DefaultDrmSessionManagerProvider—— DRM 会话管理DefaultHlsPlaylistParserFactory—— playlist 解析支持上文表格中各类#EXT-X-*标签见 HlsPlaylistParser.javaDefaultHlsPlaylistTracker.FACTORY—— playlist 跟踪与刷新直播场景的关键HlsExtractorFactory.DEFAULT—— 分段提取器DefaultLoadErrorHandlingPolicy—— 加载错误处理策略DefaultCompositeSequenceableLoaderFactory—— 多流复合加载器allowChunklessPreparation true—— 默认开启无分块准备metadataType METADATA_TYPE_ID3—— 默认提取 ID3 元数据Factory提供了一组链式配置方法按需覆盖默认行为方法作用setExtractorFactory(HlsExtractorFactory)自定义分段提取器默认HlsExtractorFactory.DEFAULTsetPlaylistParserFactory(HlsPlaylistParserFactory)自定义 playlist 解析器setPlaylistTrackerFactory(HlsPlaylistTracker.Factory)自定义 playlist 跟踪器影响直播刷新节奏setLoadErrorHandlingPolicy(LoadErrorHandlingPolicy)自定义加载错误处理与重试策略setDrmSessionManagerProvider(...)自定义 DRM 会话管理器setAllowChunklessPreparation(boolean)开关无分块准备见下文setMetadataType(int)选择元数据类型METADATA_TYPE_ID3默认或METADATA_TYPE_EMSGsetUseSessionKeys(boolean)是否使用多变体 playlist 中的#EXT-X-SESSION-KEY统一解密见下文setCmcdConfigurationFactory(...)配置 CMCDCommon Media Client Data上报setCompositeSequenceableLoaderFactory(...)自定义复合加载器setTimestampAdjusterInitializationTimeoutMs(long)时间戳调节器初始化超时毫秒0 表示无限其中setMetadataType与 TS/fMP4 元数据提取直接相关HlsMediaSource.javaMETADATA_TYPE_ID3默认从 TS 源提取原始 ID3fMP4 流中会将包装在 EMSG box 内的 ID3 数据解包暴露其余带内元数据丢弃METADATA_TYPE_EMSG提取 fMP4 变体流中全部 EMSG 数据TS 流不支持 EMSG因此无元数据输出。setUseSessionKeys(true)时假设多变体 playlist 中声明的单一session key 可用于解密全部媒体分段HlsMediaSource.java若实际内容并非单一 key 覆盖全部分段则不应开启。另外createMediaSource在检测到MediaItem携带streamKeys时会用FilteringHlsPlaylistParserFactory包装默认解析器实现流过滤HlsMediaSource.java这为离线下载只保留部分音轨/码率提供了基础。访问 Manifest读取 HLS 播放列表信息ExoPlayer 通过Player.getCurrentManifest()暴露当前加载的清单。对 HLS 而言返回值需要强转为HlsManifest。HlsManifest由两部分构成HlsManifest.javamultivariantPlaylist多变体 playlist变体列表、媒体声明等mediaPlaylist当前播放的媒体 playlist 快照分段列表、时长等。时机Player.Listener.onTimelineChanged会在 manifest 加载完成时被回调——点播on-demand内容通常只回调一次而直播内容可能回调多次playlist 随内容持续刷新。典型用法player.addListener( new Player.Listener() { Override public void onTimelineChanged( Timeline timeline, Player.TimelineChangeReason int reason) { Object manifest player.getCurrentManifest(); if (manifest ! null) { HlsManifest hlsManifest (HlsManifest) manifest; // Do something with the manifest. } } });从源码调用链看HlsMediaSource.onPrimaryPlaylistRefreshed会在每次主 playlist 刷新后构造新的HlsManifest并重建SinglePeriodTimelineHlsMediaSource.java直播场景走createTimelineForLive处理 live window、#EXT-X-PART分段与 target live offset点播走createTimelineForOnDemand。这也是onTimelineChanged在直播中反复触发、而点播只触发一次的根本原因。自定义播放理解并控制 chunkless preparation什么是 chunkless preparation默认情况下 ExoPlayer 启用chunkless preparation无分块准备仅凭多变体 playlist 中的信息完成流准备无需下载任何媒体分段。其可行性条件是#EXT-X-STREAM-INF标签中带有CODECS属性——解析器据此即可推导出各轨道的格式视频/音频/字幕轨道组。源码中该逻辑位于 HlsMediaPeriod.java只有当CODECS字符串满足恰好一个音频 codec或零音频且无EXT-X-MEDIA声明、至多一个视频 codec、且音视频 codec 总数大于 0时codecsStringAllowsChunklessPreparation才为真配合allowChunklessPreparation标志共同决定是否走无分块路径。文档注释HlsMediaPeriod.java进一步说明无分块准备的行为边界若 codec 列表含音频条目且多变体 playlist 中没有无 URI 的EXT-X-MEDIA音频声明则暴露一条 muxed 音频轨隐藏字幕closed captions只有在多变体 playlist 中显式声明时才会暴露会预先暴露一条 ID3 轨以防分段中实际包含 ID3 数据。何时需要禁用如果你的媒体分段包含未在多变体 playlist 中以#EXT-X-MEDIA:TYPECLOSED-CAPTIONS声明的 muxed 隐藏字幕轨无分块准备将导致这些字幕轨无法被检测和播放。此时需要禁用该特性HlsMediaSource hlsMediaSource new HlsMediaSource.Factory(dataSourceFactory) .setAllowChunklessPreparation(false) .createMediaSource(MediaItem.fromUri(hlsUri));代价禁用后启动时间会变长——ExoPlayer 必须实际下载一个媒体分段才能发现这些额外轨道。因此官方建议的优选方案是在多变体 playlist 中显式声明隐藏字幕轨而非依赖下载分段探测。产出高质量 HLS 内容给内容生产者的建议为了让 ExoPlayer以及其他 HLS 客户端发挥最大效果内容侧应遵循以下准则使用精确的分段时长precise segment durations分段时长漂移会导致时间轴计算误差影响无缝衔接与直播窗口管理保持媒体流连续避免跨分段改变媒体结构如编码参数、采样率变化减少解码器重置使用#EXT-X-INDEPENDENT-SEGMENTS标签声明所有分段均可在无前序分段的情况下独立解码客户端可放心执行关键帧跳转与变体切换。该标签是HlsPlaylistParser明确解析的标签之一HlsPlaylistParser.java优先使用分离流demuxed streams音视频分离独立音轨 独立视频变体优于单一文件中混合音视频便于独立选择、带宽分配与多语言切换在多变体 playlist 中尽可能声明全部信息包括CODECS启用无分块准备的前提、RESOLUTION、BANDWIDTH、FRAME-RATE及各路EXT-X-MEDIA音视频字幕轨。直播场景额外准则使用#EXT-X-PROGRAM-DATE-TIME为分段标注绝对时间ExoPlayer 据此计算 live edge 偏移与墙钟时间对齐是直播时间轴正确的关键使用#EXT-X-DISCONTINUITY-SEQUENCE显式声明断点序列号帮助客户端在广告插播、源切换等 discontinuity 后正确重建时间轴提供足够长的直播窗口一分钟或更长效果更佳。较长的 live window 给客户端更多缓冲余量显著降低卡顿概率。值得补充的是现代低延迟 HLSLL-HLSApple 方案相关的#EXT-X-PART、#EXT-X-SERVER-CONTROL标签同样被HlsPlaylistParser支持HlsPlaylistParser.java配合HlsMediaSource内部的 target live offset 推导逻辑优先使用 playlist 声明的 start offset → part hold back → hold back → 兜底3 × target duration见 HlsMediaSource.javaExoPlayer 能对 LL-HLS 直播流进行低延迟追赶播放。小结接入 HLS 播放的最小路径只需exoplayer-hls依赖 一段MediaItem代码需要精细控制时HlsMediaSource.Factory提供了数据源、解析器、播放列表跟踪、加载错误策略、DRM、元数据类型、session key 等一系列自定义入口。理解 chunkless preparation 的边界依赖CODECS属性、无法发现未声明的隐藏字幕和 Manifest 刷新机制onTimelineChanged在直播中的多次回调是排查实际播放问题的关键。内容生产侧则建议对照格式支持矩阵与分段/标签规范产出流媒体从而最大化兼容性与播放体验。进一步可参考 customization.md 了解播放器级自定义或阅读 dash.md、smoothstreaming.md 对比其他自适应流协议在 ExoPlayer 中的接入方式。【免费下载链接】ExoPlayerAn extensible media player for Android项目地址: https://gitcode.com/gh_mirrors/exop/ExoPlayer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考