音视频直播移动开发【免费下载链接】pure_live纯粹直播:哔哩哔哩/虎牙/斗鱼/快手/抖音/网易cc/YY直播/Twitch直播/SOOP直播/M38自定义源应有尽有。项目地址https://gitcode.com/gh_mirrors/pur/pure_live点击查看免费下载本篇技术指南围绕 pure_live 开源直播录播项目在 HLS 音视频预取prefetch链路中引入的原子准入机制展开聚焦HlsPrefetchScheduler.selectAll与HlsPrefetchPlan.fromMaster两个核心组件的设计动机、实现细节与验证结果。读者将掌握为什么双路视频 音频预取必须全体先校验、再一次性准入无歧义 master 清单如何被安全识别以及从源码到原生 FFmpeg 实验验证的完整闭环方法可直接复用于自己项目中的 HLS 录制/预取系统设计。该审计文档docs/HLS_PREFETCH_PLAN_AUDIT_2026_09_09.md承接此前的停止冻结审计本轮的核心目标是把完整选择集合的准入变成一个不可拆分的原子操作要么整条 A/V 组合全部通过校验并一次性进入 feed 表要么一条都不进入、调用方保持原有路径。一、背景为什么双路预取需要原子准入HLS 直播录制通常涉及两路媒体流一路视频variant、一路音频独立的 AUDIO 组或伴随流。如果调度器逐路 select——先准入视频、再准入音频——就会产生一个危险的中间态视频已经进入活动状态、开始下载与轮询而音频随后因未支持标签、空/重复 ID、非法来源或集合超限被拒绝。此时视频一路已经先跑起来整个 A/V 集合被拆成了残缺状态录制输入端将丢失音轨。文档明确指出这里的原子语义边界这里的原子是初始元数据与选择状态的原子准入不是承诺未来两路网络请求同时成功。网络失败、运行中清单变化、续签及来源切换仍由后续运行期规则负责。也就是说原子性只覆盖准入决策这个瞬间所有校验都在分配任何下载器或刷新定时器之前完成。网络层面的不确定性断流、清单漂移、密钥续签不属于准入合同的承诺范围由已有的运行期刷新、覆盖缺口检测onCoverageGap与重试策略负责。二、核心实现一HlsPrefetchScheduler.selectAll的原子准入路径源码位于 lib/domains/recorder/data/services/hls_prefetch_scheduler.dart。调度器的设计注释写得很清楚一份录制源代one recording source generation、一个共享池、显式选中的媒体 feed这个 owner 永远不自行切换清晰度或追随 master——选择权完全在调用方。2.1 单路 select 复用同一准入路径原有单路调用通过同一个准入路径继续工作bool select(String id, Uri fetchSource, HlsMediaSnapshot initial) selectAll([(id: id, source: fetchSource, snapshot: initial)]);select只是selectAll的退化形式单路调用方无需改动。2.2 selectAll 的完整校验序列bool selectAll(IterableHlsPrefetchSelection selections) { if (_closed || _finishing) return false; final pending String, _Feed{}; try { for (final selection in selections) { if (pending.length _feeds.length maximumFeeds || selection.id.isEmpty || selection.id.length 256 || pending.containsKey(selection.id) || _feeds.containsKey(selection.id) || !_validSource(selection.source) || !_validSource(selection.snapshot.source)) { return false; } final window HlsRetainedWindow(selection.snapshot.source, maximumSegments: maximumSegments); if (window.merge(selection.snapshot).isNotEmpty) return false; renderHlsRetainedManifest(window, localUri: (uri) uri); final feed _Feed(selection.id, selection.source, window, selection.snapshot.reloadFingerprint); _rebuild(feed); pending[selection.id] feed; } } on FormatException { return false; } if (pending.isEmpty || _closed || _finishing) return false; _feeds.addAll(pending); _pump(); for (final feed in pending.values) { _schedule(feed); } return true; }关键点在于所有校验在构建pending临时表阶段完成任何一条不满足就整体返回false已经构建的 feed 不会被写入_feeds。只有整个集合通过后才执行_feeds.addAll(pending)一次性提交随后才启动_pump()下载泵和_schedule(feed)清单轮询定时器。这从代码结构上保证了第二路被拒时前一路不会先进入活动状态。逐一拆解校验项校验项源码位置说明集合总容量pending.length _feeds.length maximumFeedsmaximumFeeds默认 2构造时被约束在1..2超出即整体拒绝feed ID 合法性selection.id.isEmpty \|\| selection.id.length 256拒绝空 ID 与超长 IDID 冲突pending.containsKey \|\| _feeds.containsKey同一集合内重复 ID、或与既有 feed 冲突均拒绝来源合法性_validSource(selection.source)与_validSource(selection.snapshot.source)同时校验选择来源与快照来源保留窗口完整性window.merge(selection.snapshot).isNotEmpty有片段被逐出即拒绝——准入必须保留初始前缀包括有限媒体窗口太小而静默丢首段不算选择渲染合同renderHlsRetainedManifest(window, localUri: (uri) uri)初始清单必须能通过保留清单渲染器的全部约束属性解析on FormatException解析失败整体回退其中_validSource的实现为static bool _validSource(Uri uri) const {http, https}.contains(uri.scheme) uri.host.isNotEmpty uri.userInfo.isEmpty !uri.hasFragment uri.toString().length 65536;来源必须显式 http/https、主机非空、无内嵌凭据userInfo 为空、无 fragment且序列化长度不超过 64 KiB。2.3 有界迭代输入不无界复制外部 iterable文档特别强调迭代输入按剩余最多两个 feed 的容量检查超限即退出不把外部 iterable 无界复制进内存。selectAll直接消费调用方传入的Iterable在循环内即时检查pending.length _feeds.length maximumFeeds并return false因此外部集合再大也只会被有界遍历符合录制端对内存安全的一贯约束。2.4 准入后的运行期生命周期准入只是起点。一旦提交调度器进入运行期管理_pump()按 feed 轮询round-robin准入下载条目预留pool.maximumEntries / maximumFeeds的配额quota (pool.maximumEntries ~/ maximumFeeds).clamp(1, 32)防止第一条长清单吃光配额而饿死第二路条目总数上限 512池满时返回null形成有界背压而非隐式重试_schedule(feed)按 RFC 8216 6.3.4 的节奏刷新——首次/变化加载用完整 target duration未变化加载用半个 target duration见 hls_prefetch_scheduler.dart 的_schedule_refresh(feed)每次刷新拉取新快照、合并进HlsRetainedWindow、重建 wanted 集合刷新失败则置feed.failed true并上报onRefreshFailure绝不在死循环里反复重试陈旧清单freeze()/stopFetching()/drainPublished()停止阶段先把已发布代冻结出 ENDLIST再在有限时间内排空已准入的缓存体超时则标记输入尾部被丢弃inputTailDiscarded。三、核心实现二HlsPrefetchPlan.fromMaster的无歧义 master 识别源码位于 lib/domains/recorder/data/services/hls_prefetch_plan.dart。它的类注释定义了自己的边界Only describes an unambiguous master; it never chooses a quality, language, subtitle or camera for native. Other masters retain their existing path.它不是一个通用 HLS 解析器也不猜测 native 会选择哪档。生产调用者应整体保留现有路径而不是选第一档或只启用其中一路。3.1 什么 master 会被识别为无歧义fromMaster(String text, Uri source)只接受两种形态唯一视频流无 AUDIO 组引用#EXT-X-STREAM-INF恰好一个且其AUDIO属性缺失返回[video]唯一视频 其唯一明确 AUDIO 组恰好一个#EXT-X-STREAM-INF引用了一个#EXT-X-MEDIA的 AUDIO 组且组内恰好一个成员返回[video, audioUri]。两种形态都要求URI 使用 master 最终地址source.resolve(value)解析来源与媒体协议的 scheme 必须 http/https、host 非空、无 userInfo、无 fragmentHTTPS 引用降级master 是 https 而子 URI 不是会直接抛FormatException使整个计划返回null。返回的sources是List.unmodifiable即不可变集合。3.2 明确的拒绝清单以下任一情形都会让fromMaster返回null无预取计划由调用方回退到原有路径多清晰度多个#EXT-X-STREAM-INF多个语言/音频候选多个#EXT-X-MEDIAAUDIO 组字幕/隐藏字幕组CLOSED-CAPTIONS存在且不为NONEsession key、未知状态标签/属性#EXT开头的未知标签、STREAM-INF 出现白名单外的属性组关联不完整STREAM-INF 引用 AUDIO 组但组缺失或反之重复字段同一属性名出现两次_attributes解析时直接抛FormatException悬空 STREAM-INFpendingVariant为 true 时没有跟随的媒体 URI 行相同 URI 同时作为两路audioUri videomaster 超过 4 MiBtext.length 4 * 1024 * 1024首行不是#EXTM3U。其中#EXT-X-STREAM-INF的属性白名单为BANDWIDTH / AVERAGE-BANDWIDTH / RESOLUTION / CODECS / FRAME-RATE / AUDIO / CLOSED-CAPTIONS且BANDWIDTH必须匹配^[1-9]\d*$正整数#EXT-X-MEDIA的属性白名单为TYPE / GROUP-ID / NAME / URI / DEFAULT / AUTOSELECT / LANGUAGE / CHANNELS / CHARACTERISTICS其中TYPE必须为AUDIOGROUP-ID、NAME、URI均非空DEFAULT/AUTOSELECT只能是YES/NO。这些严格约束正是不猜测、只识别唯一确定组合的体现。3.3 属性解析器_attributes使用([A-Z0-9-])([^]*|[^,\s])正则逐段解析逗号分隔的属性列表遇到重复键、非法分隔符非逗号或结尾悬空逗号都抛出FormatException因此重复字段会被同一机制拦截。四、原生实验适配层从 master 到 selectAll 的一次性接入文档指出原生实验适配层已经使用该计划读取实际源站 master → 获取两份初始媒体 snapshot → selectAll 一次性准入 → 返回 master随后 native 请求子清单时复用已选 feed不重复选择、不重复加载。此前由 native 顺序访问两路后逐个 select 的实验接线已替换。在源码中这一流程对应 lib/domains/recorder/data/services/hls_relay_prefetch.dart 的_preparePrefetchHlsPrefetchPlan.fromMaster(master, source)解析 master若plan null回退为单路root快照HlsMediaSnapshot.parse(master, source)走原有路径若计划有效Future.wait(plan.sources.map(load))并发拉取两份初始媒体快照——注意文档与代码都强调Serial initial reads age the first short live window while waiting for the second因此共享同一个取消令牌cancellation任一加载失败都会cancellation.cancel()使整个准备过程作废为每路生成本地资源 ID取自_localResource的路径末段文件名构建HlsPrefetchSelection列表创建HlsPrefetchPoolmaximumEntries: 32, maximumConcurrent: 16, memoryBytesPerBody: 512 * 1024与HlsPrefetchSchedulermaximumFeeds: selections.lengthcandidate.selectAll(selections)一次性准入失败则整个候选调度器被close()不产生任何部分启用的 A/V 集合准入成功后_prefetch candidate后续请求通过_servePrefetchManifest/_servePrefetchBody复用已选 feed。_servePrefetchBody中的关键语义还包括acquire超时或失败时按失败状态码回 503/410停止阶段未排空则置_inputTailDiscarded trueBYTERANGE 缓存只服务于其声明的切片——若请求的 Range 与资源声明的requestHeader不一致返回 416绝不把缓存切片冒充完整对象。这段适配同时保留了原始 master 和媒体字节不改质量、音轨或时间戳。切换/停止阶段_endedManifest只为媒体清单补#EXT-X-ENDLISTmaster 目录清单原样返回。五、验证范围从定向测试到双场景原生实验5.1 master 计划测试文档列出新增 master 计划测试的覆盖面唯一组合、不可变集合、组错配、多变体/多音轨、重复属性、空/凭据/降级/fragment URI、未知会话/字幕合同等。与之配套的批量测试断言了原子性的可观测结果第二路被拒时feed0、download0、pool 条目0——没有任何一路进入活动状态有效组合第一次 loader 回调必须已观察到feed2——两路在准入瞬间同时可用失败后的重复准入保持既有状态不破坏已经准入的组合。5.2 双场景原生实验原生实验目录controls/scheduled-1788957891514939/使用同一 12 秒视频 body 或 headers、6 秒滚动窗口、34 秒曝光验证真实 TCP native链路场景TS 字节本地完整视频序号视频/音频包探针停止耗时 ms观察峰值条目/下载body 12 秒3,329,6680–13连续840 / 1407216520 / 8headers 12 秒3,300,3400–13连续840 / 1313218019 / 8两场景均code0、正常排空、无强制取消、无完整性错误、无活动覆盖缺口尾部丢弃仍为 true。两路合计 66 次独立刷新关闭后池条目和字节均归 0。视频最大排序包步长 0.033334 秒、音频 0.021334 秒整体仍是约 28 秒视频body 场景音频约 30 秒、headers 场景约 28 秒——文档谨慎声明不据此宣布所有尾部对齐。5.3 全量解码与固定哈希校验CLI 实际以-v error -xerror -map 0:v:0 -map 0:a:0 -f null解码两份 TS均退出 0、无错误文本。body TS SHA-256 为ED27EFDAB0D4DD3944F6AACC10E88B4725B7B8BEFFA0F08AA5CCFE1F1772AFA3headers TS 为54ED2AC7B02BE31D0D09BA81F3372FB8FB163D7C8EFFD1E3057CD1BBFC372098。本地夹具、FFmpegKit DLL、ffprobe 和 CLI 的固定哈希由脚本验证本轮 hook 未取得远端 ZIP SHA故不称作远端包哈希通过——这一表述边界体现了审计对证据等级的严格区分。5.4 资源守卫与构建记录重型验证经共享资源守卫排队未停止其他任务的 Java 进程排队期间没有继续编辑源码。证据根目录local-artifacts/hls-prefetch-plan-20260909/资源记录均位于local-artifacts/build-records/文件前缀 / 阶段秒含排队观察峰值 CPU %峰值工作集 B阶段结束活跃重型进程20260909T124040828Z / atomic-plan188.07715.5711725209600020260909T124630392Z / atomic-fixed295.79175.3914921601024120260909T124702156Z / decode19.7180.11110300733440一个值得注意的工程细节首次atomic-plan在分析阶段因三个多行 if 缺少花括号失败未运行测试补齐花括号后运行atomic-fixed。同时让实验 master 响应头和 body共用同一个响应预算不在读取 body 时重新计时。所有失败、排队与成功记录均被保留。第二阶段结束时另有 Java 进程活跃解码阶段继续在资源守卫中排队该进程随后退出监控值包含可见重型进程不把 75.39% 全部归因于预取代码也未声称第二阶段结束立即全机空闲。最终解码记录为 0两个本任务执行句柄都已收到终态。六、生产接入状态与剩余工作文档明确了当前所处的阶段与边界本轮把完整 A/V 选择接通到真实 TCP native 实验但尚未把预取默认启用于应用的FFmpegHlsInputRelay。下一步复用这个全体先校验的入口接通生产资源 ID/HTTP Range 和失败状态、统一资源预算与停止生命周期而非再叠一层实验 HTTP。结合源码看生产侧的接入点已经就位FFmpegHlsInputRelay在_handleRequest中当resourceId root prefetchEnabled !_finishing时触发_preparePrefetch见 lib/domains/recorder/data/services/ffmpeg_hls_input_relay.dart且enablePrefetch仅在drainOnStop同时开启时才生效prefetchEnabled: enablePrefetch drainOnStop。此外manifestMediaTransform ! null enablePrefetch会被显式拒绝——预取缓存尚未承接 manifest 级媒体前缀变换的所有权因此两者不能同时启用。探针 tool/probes/hls_scheduled_delivery_probe.dart 通过环境变量PURELIVE_HLS_PRODUCTION_PREFETCH_PROBE1选择直接生产预取或历史实验适配器两者均为 opt-in 探针不是默认的应用程序激活。其他明确未完成项多变体等返回无计划不等于这些平台验收通过真实 LL-HLS、尾部完整排空、所有平台/界面功能、稳定版 3.2.0 发布仍属于原目标宏观仍为20 PASS / 32 RUN / 10 NOT RUN42 个验收大项未闭环没有手机操作、构建、版本修改、上游合并或发布。七、相关源码与文档索引关注点路径原子准入调度器selectAll / select / 运行期泵与刷新lib/domains/recorder/data/services/hls_prefetch_scheduler.dart无歧义 master 计划fromMasterlib/domains/recorder/data/services/hls_prefetch_plan.dart有界预取池与票据/租约lib/domains/recorder/data/services/hls_prefetch_pool.dart保留窗口与清单渲染合同lib/domains/recorder/data/services/hls_retained_window.dart、hls_retained_manifest.dart生产 relay 接入与预取服务lib/domains/recorder/data/services/ffmpeg_hls_input_relay.dart、hls_relay_prefetch.dart双场景原生实验探针tool/probes/hls_scheduled_delivery_probe.dart、tool/probes/hls_rolling_delivery_probe_test.dart本轮审计文档docs/HLS_PREFETCH_PLAN_AUDIT_2026_09_09.md承接的上游审计docs/HLS_PREFETCH_FREEZE_AUDIT_2026_09_09.md结语pure_live 的 HLS 预取原子准入为双路 A/V 预取树立了一个可复用的范式把选择权与校验权彻底分离——HlsPrefetchPlan.fromMaster只负责识别无需猜测的确定性组合HlsPrefetchScheduler.selectAll只负责全体先校验、再一次性提交而运行期的一切不确定性网络失败、清单漂移、密钥续签、来源切换都交给既有的刷新、冻结与排空合同。这种设计让录制端在多清晰度、多语言候选的 HLS 世界里既不越权猜测也绝不陷入半套 A/V 流的残缺状态。对任何需要稳定录制 HLS 直播的工程而言这份从设计、实现到原生验证的完整链路都值得对照借鉴。赞分享音视频直播移动开发【免费下载链接】pure_live纯粹直播:哔哩哔哩/虎牙/斗鱼/快手/抖音/网易cc/YY直播/Twitch直播/SOOP直播/M38自定义源应有尽有。项目地址https://gitcode.com/gh_mirrors/pur/pure_live点击查看免费下载相关推荐pure_live 录制链路 HLS 有界预取池未读响应取消修复与读取租约所有权设计pure_live 录制链路 HLS 有界预取池未读响应取消修复与读取租约所有权设计 导读 本文基于 pure_live纯粹直播仓库中 HLS_PREFE音视频直播移动开发pure_live HLS 预取调度器深度解析独立清单刷新、有界分片预取与停止语义审计pure_live HLS 预取调度器深度解析独立清单刷新、有界分片预取与停止语义审计 本文基于 pure_live纯粹直播开源仓库的审计文档 docs/音视频直播移动开发pure_live HLS 明确选流机制剖析从多画质 master 解析到 niconico 双轨短录实战验证pure_live HLS 明确选流机制剖析从多画质 master 解析到 niconico 双轨短录实战验证 导读 本文以 pure_live纯粹直播仓音视频直播移动开发上一篇Matterwiki团队知识管理的简单选择下一篇终极指南Diem Move智能合约测试完整教程 - 单元测试与集成测试实践创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考