計：`HlsPrefetchScheduler.selectAll` 與 `HlsPrefetchPlan.fromMaster` 實戰(zhàn)解析)
音視頻直播移動開發(fā)【免費下載鏈接】pure_live純粹直播:嗶哩嗶哩/虎牙/斗魚/快手/抖音/網(wǎng)易cc/YY直播/Twitch直播/SOOP直播/M38自定義源應(yīng)有盡有。項目地址https://gitcode.com/gh_mirrors/pur/pure_live點擊查看免費下載本篇技術(shù)指南圍繞 pure_live 開源直播錄播項目在 HLS 音視頻預取prefetch鏈路中引入的原子準入機制展開聚焦HlsPrefetchScheduler.selectAll與HlsPrefetchPlan.fromMaster兩個核心組件的設(shè)計動機、實現(xiàn)細節(jié)與驗證結(jié)果。讀者將掌握為什么雙路視頻 音頻預取必須全體先校驗、再一次性準入無歧義 master 清單如何被安全識別以及從源碼到原生 FFmpeg 實驗驗證的完整閉環(huán)方法可直接復用于自己項目中的 HLS 錄制/預取系統(tǒng)設(shè)計。該審計文檔docs/HLS_PREFETCH_PLAN_AUDIT_2026_09_09.md承接此前的停止凍結(jié)審計本輪的核心目標是把完整選擇集合的準入變成一個不可拆分的原子操作要么整條 A/V 組合全部通過校驗并一次性進入 feed 表要么一條都不進入、調(diào)用方保持原有路徑。一、背景為什么雙路預取需要原子準入HLS 直播錄制通常涉及兩路媒體流一路視頻variant、一路音頻獨立的 AUDIO 組或伴隨流。如果調(diào)度器逐路 select——先準入視頻、再準入音頻——就會產(chǎn)生一個危險的中間態(tài)視頻已經(jīng)進入活動狀態(tài)、開始下載與輪詢而音頻隨后因未支持標簽、空/重復 ID、非法來源或集合超限被拒絕。此時視頻一路已經(jīng)先跑起來整個 A/V 集合被拆成了殘缺狀態(tài)錄制輸入端將丟失音軌。文檔明確指出這里的原子語義邊界這里的原子是初始元數(shù)據(jù)與選擇狀態(tài)的原子準入不是承諾未來兩路網(wǎng)絡(luò)請求同時成功。網(wǎng)絡(luò)失敗、運行中清單變化、續(xù)簽及來源切換仍由后續(xù)運行期規(guī)則負責。也就是說原子性只覆蓋準入決策這個瞬間所有校驗都在分配任何下載器或刷新定時器之前完成。網(wǎng)絡(luò)層面的不確定性斷流、清單漂移、密鑰續(xù)簽不屬于準入合同的承諾范圍由已有的運行期刷新、覆蓋缺口檢測onCoverageGap與重試策略負責。二、核心實現(xiàn)一HlsPrefetchScheduler.selectAll的原子準入路徑源碼位于 lib/domains/recorder/data/services/hls_prefetch_scheduler.dart。調(diào)度器的設(shè)計注釋寫得很清楚一份錄制源代one recording source generation、一個共享池、顯式選中的媒體 feed這個 owner 永遠不自行切換清晰度或追隨 master——選擇權(quán)完全在調(diào)用方。2.1 單路 select 復用同一準入路徑原有單路調(diào)用通過同一個準入路徑繼續(xù)工作bool select(String id, Uri fetchSource, HlsMediaSnapshot initial) selectAll([(id: id, source: fetchSource, snapshot: initial)]);select只是selectAll的退化形式單路調(diào)用方無需改動。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; }關(guān)鍵點在于所有校驗在構(gòu)建pending臨時表階段完成任何一條不滿足就整體返回false已經(jīng)構(gòu)建的 feed 不會被寫入_feeds。只有整個集合通過后才執(zhí)行_feeds.addAll(pending)一次性提交隨后才啟動_pump()下載泵和_schedule(feed)清單輪詢定時器。這從代碼結(jié)構(gòu)上保證了第二路被拒時前一路不會先進入活動狀態(tài)。逐一拆解校驗項校驗項源碼位置說明集合總?cè)萘縫ending.length _feeds.length maximumFeedsmaximumFeeds默認 2構(gòu)造時被約束在1..2超出即整體拒絕feed ID 合法性selection.id.isEmpty \|\| selection.id.length 256拒絕空 ID 與超長 IDID 沖突pending.containsKey \|\| _feeds.containsKey同一集合內(nèi)重復 ID、或與既有 feed 沖突均拒絕來源合法性_validSource(selection.source)與_validSource(selection.snapshot.source)同時校驗選擇來源與快照來源保留窗口完整性window.merge(selection.snapshot).isNotEmpty有片段被逐出即拒絕——準入必須保留初始前綴包括有限媒體窗口太小而靜默丟首段不算選擇渲染合同renderHlsRetainedManifest(window, localUri: (uri) uri)初始清單必須能通過保留清單渲染器的全部約束屬性解析on FormatException解析失敗整體回退其中_validSource的實現(xiàn)為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、主機非空、無內(nèi)嵌憑據(jù)userInfo 為空、無 fragment且序列化長度不超過 64 KiB。2.3 有界迭代輸入不無界復制外部 iterable文檔特別強調(diào)迭代輸入按剩余最多兩個 feed 的容量檢查超限即退出不把外部 iterable 無界復制進內(nèi)存。selectAll直接消費調(diào)用方傳入的Iterable在循環(huán)內(nèi)即時檢查pending.length _feeds.length maximumFeeds并return false因此外部集合再大也只會被有界遍歷符合錄制端對內(nèi)存安全的一貫約束。2.4 準入后的運行期生命周期準入只是起點。一旦提交調(diào)度器進入運行期管理_pump()按 feed 輪詢round-robin準入下載條目預留pool.maximumEntries / maximumFeeds的配額quota (pool.maximumEntries ~/ maximumFeeds).clamp(1, 32)防止第一條長清單吃光配額而餓死第二路條目總數(shù)上限 512池滿時返回null形成有界背壓而非隱式重試_schedule(feed)按 RFC 8216 6.3.4 的節(jié)奏刷新——首次/變化加載用完整 target duration未變化加載用半個 target duration見 hls_prefetch_scheduler.dart 的_schedule_refresh(feed)每次刷新拉取新快照、合并進HlsRetainedWindow、重建 wanted 集合刷新失敗則置feed.failed true并上報onRefreshFailure絕不在死循環(huán)里反復重試陳舊清單freeze()/stopFetching()/drainPublished()停止階段先把已發(fā)布代凍結(jié)出 ENDLIST再在有限時間內(nèi)排空已準入的緩存體超時則標記輸入尾部被丟棄inputTailDiscarded。三、核心實現(xiàn)二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 會選擇哪檔。生產(chǎn)調(diào)用者應(yīng)整體保留現(xiàn)有路徑而不是選第一檔或只啟用其中一路。3.1 什么 master 會被識別為無歧義fromMaster(String text, Uri source)只接受兩種形態(tài)唯一視頻流無 AUDIO 組引用#EXT-X-STREAM-INF恰好一個且其AUDIO屬性缺失返回[video]唯一視頻 其唯一明確 AUDIO 組恰好一個#EXT-X-STREAM-INF引用了一個#EXT-X-MEDIA的 AUDIO 組且組內(nèi)恰好一個成員返回[video, audioUri]。兩種形態(tài)都要求URI 使用 master 最終地址source.resolve(value)解析來源與媒體協(xié)議的 scheme 必須 http/https、host 非空、無 userInfo、無 fragmentHTTPS 引用降級master 是 https 而子 URI 不是會直接拋FormatException使整個計劃返回null。返回的sources是List.unmodifiable即不可變集合。3.2 明確的拒絕清單以下任一情形都會讓fromMaster返回null無預取計劃由調(diào)用方回退到原有路徑多清晰度多個#EXT-X-STREAM-INF多個語言/音頻候選多個#EXT-X-MEDIAAUDIO 組字幕/隱藏字幕組CLOSED-CAPTIONS存在且不為NONEsession key、未知狀態(tài)標簽/屬性#EXT開頭的未知標簽、STREAM-INF 出現(xiàn)白名單外的屬性組關(guān)聯(lián)不完整STREAM-INF 引用 AUDIO 組但組缺失或反之重復字段同一屬性名出現(xiàn)兩次_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*$正整數(shù)#EXT-X-MEDIA的屬性白名單為TYPE / GROUP-ID / NAME / URI / DEFAULT / AUTOSELECT / LANGUAGE / CHANNELS / CHARACTERISTICS其中TYPE必須為AUDIOGROUP-ID、NAME、URI均非空DEFAULT/AUTOSELECT只能是YES/NO。這些嚴格約束正是不猜測、只識別唯一確定組合的體現(xiàn)。3.3 屬性解析器_attributes使用([A-Z0-9-])([^]*|[^,\s])正則逐段解析逗號分隔的屬性列表遇到重復鍵、非法分隔符非逗號或結(jié)尾懸空逗號都拋出FormatException因此重復字段會被同一機制攔截。四、原生實驗適配層從 master 到 selectAll 的一次性接入文檔指出原生實驗適配層已經(jīng)使用該計劃讀取實際源站 master → 獲取兩份初始媒體 snapshot → selectAll 一次性準入 → 返回 master隨后 native 請求子清單時復用已選 feed不重復選擇、不重復加載。此前由 native 順序訪問兩路后逐個 select 的實驗接線已替換。在源碼中這一流程對應(yīng) 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))并發(fā)拉取兩份初始媒體快照——注意文檔與代碼都強調(diào)Serial initial reads age the first short live window while waiting for the second因此共享同一個取消令牌cancellation任一加載失敗都會cancellation.cancel()使整個準備過程作廢為每路生成本地資源 ID取自_localResource的路徑末段文件名構(gòu)建HlsPrefetchSelection列表創(chuàng)建HlsPrefetchPoolmaximumEntries: 32, maximumConcurrent: 16, memoryBytesPerBody: 512 * 1024與HlsPrefetchSchedulermaximumFeeds: selections.lengthcandidate.selectAll(selections)一次性準入失敗則整個候選調(diào)度器被close()不產(chǎn)生任何部分啟用的 A/V 集合準入成功后_prefetch candidate后續(xù)請求通過_servePrefetchManifest/_servePrefetchBody復用已選 feed。_servePrefetchBody中的關(guān)鍵語義還包括acquire超時或失敗時按失敗狀態(tài)碼回 503/410停止階段未排空則置_inputTailDiscarded trueBYTERANGE 緩存只服務(wù)于其聲明的切片——若請求的 Range 與資源聲明的requestHeader不一致返回 416絕不把緩存切片冒充完整對象。這段適配同時保留了原始 master 和媒體字節(jié)不改質(zhì)量、音軌或時間戳。切換/停止階段_endedManifest只為媒體清單補#EXT-X-ENDLISTmaster 目錄清單原樣返回。五、驗證范圍從定向測試到雙場景原生實驗5.1 master 計劃測試文檔列出新增 master 計劃測試的覆蓋面唯一組合、不可變集合、組錯配、多變體/多音軌、重復屬性、空/憑據(jù)/降級/fragment URI、未知會話/字幕合同等。與之配套的批量測試斷言了原子性的可觀測結(jié)果第二路被拒時feed0、download0、pool 條目0——沒有任何一路進入活動狀態(tài)有效組合第一次 loader 回調(diào)必須已觀察到feed2——兩路在準入瞬間同時可用失敗后的重復準入保持既有狀態(tài)不破壞已經(jīng)準入的組合。5.2 雙場景原生實驗原生實驗目錄controls/scheduled-1788957891514939/使用同一 12 秒視頻 body 或 headers、6 秒滾動窗口、34 秒曝光驗證真實 TCP native鏈路場景TS 字節(jié)本地完整視頻序號視頻/音頻包探針停止耗時 ms觀察峰值條目/下載body 12 秒3,329,6680–13連續(xù)840 / 1407216520 / 8headers 12 秒3,300,3400–13連續(xù)840 / 1313218019 / 8兩場景均code0、正常排空、無強制取消、無完整性錯誤、無活動覆蓋缺口尾部丟棄仍為 true。兩路合計 66 次獨立刷新關(guān)閉后池條目和字節(jié)均歸 0。視頻最大排序包步長 0.033334 秒、音頻 0.021334 秒整體仍是約 28 秒視頻body 場景音頻約 30 秒、headers 場景約 28 秒——文檔謹慎聲明不據(jù)此宣布所有尾部對齊。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故不稱作遠端包哈希通過——這一表述邊界體現(xiàn)了審計對證據(jù)等級的嚴格區(qū)分。5.4 資源守衛(wèi)與構(gòu)建記錄重型驗證經(jīng)共享資源守衛(wèi)排隊未停止其他任務(wù)的 Java 進程排隊期間沒有繼續(xù)編輯源碼。證據(jù)根目錄local-artifacts/hls-prefetch-plan-20260909/資源記錄均位于local-artifacts/build-records/文件前綴 / 階段秒含排隊觀察峰值 CPU %峰值工作集 B階段結(jié)束活躍重型進程20260909T124040828Z / atomic-plan188.07715.5711725209600020260909T124630392Z / atomic-fixed295.79175.3914921601024120260909T124702156Z / decode19.7180.11110300733440一個值得注意的工程細節(jié)首次atomic-plan在分析階段因三個多行 if 缺少花括號失敗未運行測試補齊花括號后運行atomic-fixed。同時讓實驗 master 響應(yīng)頭和 body共用同一個響應(yīng)預算不在讀取 body 時重新計時。所有失敗、排隊與成功記錄均被保留。第二階段結(jié)束時另有 Java 進程活躍解碼階段繼續(xù)在資源守衛(wèi)中排隊該進程隨后退出監(jiān)控值包含可見重型進程不把 75.39% 全部歸因于預取代碼也未聲稱第二階段結(jié)束立即全機空閑。最終解碼記錄為 0兩個本任務(wù)執(zhí)行句柄都已收到終態(tài)。六、生產(chǎn)接入狀態(tài)與剩余工作文檔明確了當前所處的階段與邊界本輪把完整 A/V 選擇接通到真實 TCP native 實驗但尚未把預取默認啟用于應(yīng)用的FFmpegHlsInputRelay。下一步復用這個全體先校驗的入口接通生產(chǎn)資源 ID/HTTP Range 和失敗狀態(tài)、統(tǒng)一資源預算與停止生命周期而非再疊一層實驗 HTTP。結(jié)合源碼看生產(chǎn)側(cè)的接入點已經(jīng)就位FFmpegHlsInputRelay在_handleRequest中當resourceId root prefetchEnabled !_finishing時觸發(fā)_preparePrefetch見 lib/domains/recorder/data/services/ffmpeg_hls_input_relay.dart且enablePrefetch僅在drainOnStop同時開啟時才生效prefetchEnabled: enablePrefetch drainOnStop。此外manifestMediaTransform ! null enablePrefetch會被顯式拒絕——預取緩存尚未承接 manifest 級媒體前綴變換的所有權(quán)因此兩者不能同時啟用。探針 tool/probes/hls_scheduled_delivery_probe.dart 通過環(huán)境變量PURELIVE_HLS_PRODUCTION_PREFETCH_PROBE1選擇直接生產(chǎn)預取或歷史實驗適配器兩者均為 opt-in 探針不是默認的應(yīng)用程序激活。其他明確未完成項多變體等返回無計劃不等于這些平臺驗收通過真實 LL-HLS、尾部完整排空、所有平臺/界面功能、穩(wěn)定版 3.2.0 發(fā)布仍屬于原目標宏觀仍為20 PASS / 32 RUN / 10 NOT RUN42 個驗收大項未閉環(huán)沒有手機操作、構(gòu)建、版本修改、上游合并或發(fā)布。七、相關(guān)源碼與文檔索引關(guān)注點路徑原子準入調(diào)度器selectAll / select / 運行期泵與刷新lib/domains/recorder/data/services/hls_prefetch_scheduler.dart無歧義 master 計劃fromMasterlib/domains/recorder/data/services/hls_prefetch_plan.dart有界預取池與票據(jù)/租約lib/domains/recorder/data/services/hls_prefetch_pool.dart保留窗口與清單渲染合同lib/domains/recorder/data/services/hls_retained_window.dart、hls_retained_manifest.dart生產(chǎn) relay 接入與預取服務(wù)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結(jié)語pure_live 的 HLS 預取原子準入為雙路 A/V 預取樹立了一個可復用的范式把選擇權(quán)與校驗權(quán)徹底分離——HlsPrefetchPlan.fromMaster只負責識別無需猜測的確定性組合HlsPrefetchScheduler.selectAll只負責全體先校驗、再一次性提交而運行期的一切不確定性網(wǎng)絡(luò)失敗、清單漂移、密鑰續(xù)簽、來源切換都交給既有的刷新、凍結(jié)與排空合同。這種設(shè)計讓錄制端在多清晰度、多語言候選的 HLS 世界里既不越權(quán)猜測也絕不陷入半套 A/V 流的殘缺狀態(tài)。對任何需要穩(wěn)定錄制 HLS 直播的工程而言這份從設(shè)計、實現(xiàn)到原生驗證的完整鏈路都值得對照借鑒。贊分享音視頻直播移動開發(fā)【免費下載鏈接】pure_live純粹直播:嗶哩嗶哩/虎牙/斗魚/快手/抖音/網(wǎng)易cc/YY直播/Twitch直播/SOOP直播/M38自定義源應(yīng)有盡有。項目地址https://gitcode.com/gh_mirrors/pur/pure_live點擊查看免費下載相關(guān)推薦pure_live 錄制鏈路 HLS 有界預取池未讀響應(yīng)取消修復與讀取租約所有權(quán)設(shè)計pure_live 錄制鏈路 HLS 有界預取池未讀響應(yīng)取消修復與讀取租約所有權(quán)設(shè)計 導讀 本文基于 pure_live純粹直播倉庫中 HLS_PREFE音視頻直播移動開發(fā)pure_live HLS 預取調(diào)度器深度解析獨立清單刷新、有界分片預取與停止語義審計pure_live HLS 預取調(diào)度器深度解析獨立清單刷新、有界分片預取與停止語義審計 本文基于 pure_live純粹直播開源倉庫的審計文檔 docs/音視頻直播移動開發(fā)pure_live HLS 明確選流機制剖析從多畫質(zhì) master 解析到 niconico 雙軌短錄實戰(zhàn)驗證pure_live HLS 明確選流機制剖析從多畫質(zhì) master 解析到 niconico 雙軌短錄實戰(zhàn)驗證 導讀 本文以 pure_live純粹直播倉音視頻直播移動開發(fā)上一篇Matterwiki團隊知識管理的簡單選擇下一篇終極指南Diem Move智能合約測試完整教程 - 單元測試與集成測試實踐創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 pure_live HLS 雙路音視頻預取的原子準入設(shè)計：`HlsPrefetchScheduler.selectAll` 與 `HlsPrefetchPlan.fromMaster` 實戰(zhàn)解析
音視頻直播移動開發(fā)【免費下載鏈接】pure_live純粹直播:嗶哩嗶哩/虎牙/斗魚/快手/抖音/網(wǎng)易cc/YY直播/Twitch直播/SOOP直播/M38自定義源應(yīng)有盡有。項目地址https://gitcode.com/gh_mirrors/pur/pure_live點擊查看免費下載本篇技術(shù)指南圍繞 pure_live 開源直播錄播項目在 HLS 音視頻預取prefetch鏈路中引入的原子準入機制展開聚焦HlsPrefetchScheduler.selectAll與HlsPrefetchPlan.fromMaster兩個核心組件的設(shè)計動機、實現(xiàn)細節(jié)與驗證結(jié)果。讀者將掌握為什么雙路視頻 音頻預取必須全體先校驗、再一次性準入無歧義 master 清單如何被安全識別以及從源碼到原生 FFmpeg 實驗驗證的完整閉環(huán)方法可直接復用于自己項目中的 HLS 錄制/預取系統(tǒng)設(shè)計。該審計文檔docs/HLS_PREFETCH_PLAN_AUDIT_2026_09_09.md承接此前的停止凍結(jié)審計本輪的核心目標是把完整選擇集合的準入變成一個不可拆分的原子操作要么整條 A/V 組合全部通過校驗并一次性進入 feed 表要么一條都不進入、調(diào)用方保持原有路徑。一、背景為什么雙路預取需要原子準入HLS 直播錄制通常涉及兩路媒體流一路視頻variant、一路音頻獨立的 AUDIO 組或伴隨流。如果調(diào)度器逐路 select——先準入視頻、再準入音頻——就會產(chǎn)生一個危險的中間態(tài)視頻已經(jīng)進入活動狀態(tài)、開始下載與輪詢而音頻隨后因未支持標簽、空/重復 ID、非法來源或集合超限被拒絕。此時視頻一路已經(jīng)先跑起來整個 A/V 集合被拆成了殘缺狀態(tài)錄制輸入端將丟失音軌。文檔明確指出這里的原子語義邊界這里的原子是初始元數(shù)據(jù)與選擇狀態(tài)的原子準入不是承諾未來兩路網(wǎng)絡(luò)請求同時成功。網(wǎng)絡(luò)失敗、運行中清單變化、續(xù)簽及來源切換仍由后續(xù)運行期規(guī)則負責。也就是說原子性只覆蓋準入決策這個瞬間所有校驗都在分配任何下載器或刷新定時器之前完成。網(wǎng)絡(luò)層面的不確定性斷流、清單漂移、密鑰續(xù)簽不屬于準入合同的承諾范圍由已有的運行期刷新、覆蓋缺口檢測onCoverageGap與重試策略負責。二、核心實現(xiàn)一HlsPrefetchScheduler.selectAll的原子準入路徑源碼位于 lib/domains/recorder/data/services/hls_prefetch_scheduler.dart。調(diào)度器的設(shè)計注釋寫得很清楚一份錄制源代one recording source generation、一個共享池、顯式選中的媒體 feed這個 owner 永遠不自行切換清晰度或追隨 master——選擇權(quán)完全在調(diào)用方。2.1 單路 select 復用同一準入路徑原有單路調(diào)用通過同一個準入路徑繼續(xù)工作bool select(String id, Uri fetchSource, HlsMediaSnapshot initial) selectAll([(id: id, source: fetchSource, snapshot: initial)]);select只是selectAll的退化形式單路調(diào)用方無需改動。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; }關(guān)鍵點在于所有校驗在構(gòu)建pending臨時表階段完成任何一條不滿足就整體返回false已經(jīng)構(gòu)建的 feed 不會被寫入_feeds。只有整個集合通過后才執(zhí)行_feeds.addAll(pending)一次性提交隨后才啟動_pump()下載泵和_schedule(feed)清單輪詢定時器。這從代碼結(jié)構(gòu)上保證了第二路被拒時前一路不會先進入活動狀態(tài)。逐一拆解校驗項校驗項源碼位置說明集合總?cè)萘縫ending.length _feeds.length maximumFeedsmaximumFeeds默認 2構(gòu)造時被約束在1..2超出即整體拒絕feed ID 合法性selection.id.isEmpty \|\| selection.id.length 256拒絕空 ID 與超長 IDID 沖突pending.containsKey \|\| _feeds.containsKey同一集合內(nèi)重復 ID、或與既有 feed 沖突均拒絕來源合法性_validSource(selection.source)與_validSource(selection.snapshot.source)同時校驗選擇來源與快照來源保留窗口完整性window.merge(selection.snapshot).isNotEmpty有片段被逐出即拒絕——準入必須保留初始前綴包括有限媒體窗口太小而靜默丟首段不算選擇渲染合同renderHlsRetainedManifest(window, localUri: (uri) uri)初始清單必須能通過保留清單渲染器的全部約束屬性解析on FormatException解析失敗整體回退其中_validSource的實現(xiàn)為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、主機非空、無內(nèi)嵌憑據(jù)userInfo 為空、無 fragment且序列化長度不超過 64 KiB。2.3 有界迭代輸入不無界復制外部 iterable文檔特別強調(diào)迭代輸入按剩余最多兩個 feed 的容量檢查超限即退出不把外部 iterable 無界復制進內(nèi)存。selectAll直接消費調(diào)用方傳入的Iterable在循環(huán)內(nèi)即時檢查pending.length _feeds.length maximumFeeds并return false因此外部集合再大也只會被有界遍歷符合錄制端對內(nèi)存安全的一貫約束。2.4 準入后的運行期生命周期準入只是起點。一旦提交調(diào)度器進入運行期管理_pump()按 feed 輪詢round-robin準入下載條目預留pool.maximumEntries / maximumFeeds的配額quota (pool.maximumEntries ~/ maximumFeeds).clamp(1, 32)防止第一條長清單吃光配額而餓死第二路條目總數(shù)上限 512池滿時返回null形成有界背壓而非隱式重試_schedule(feed)按 RFC 8216 6.3.4 的節(jié)奏刷新——首次/變化加載用完整 target duration未變化加載用半個 target duration見 hls_prefetch_scheduler.dart 的_schedule_refresh(feed)每次刷新拉取新快照、合并進HlsRetainedWindow、重建 wanted 集合刷新失敗則置feed.failed true并上報onRefreshFailure絕不在死循環(huán)里反復重試陳舊清單freeze()/stopFetching()/drainPublished()停止階段先把已發(fā)布代凍結(jié)出 ENDLIST再在有限時間內(nèi)排空已準入的緩存體超時則標記輸入尾部被丟棄inputTailDiscarded。三、核心實現(xiàn)二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 會選擇哪檔。生產(chǎn)調(diào)用者應(yīng)整體保留現(xiàn)有路徑而不是選第一檔或只啟用其中一路。3.1 什么 master 會被識別為無歧義fromMaster(String text, Uri source)只接受兩種形態(tài)唯一視頻流無 AUDIO 組引用#EXT-X-STREAM-INF恰好一個且其AUDIO屬性缺失返回[video]唯一視頻 其唯一明確 AUDIO 組恰好一個#EXT-X-STREAM-INF引用了一個#EXT-X-MEDIA的 AUDIO 組且組內(nèi)恰好一個成員返回[video, audioUri]。兩種形態(tài)都要求URI 使用 master 最終地址source.resolve(value)解析來源與媒體協(xié)議的 scheme 必須 http/https、host 非空、無 userInfo、無 fragmentHTTPS 引用降級master 是 https 而子 URI 不是會直接拋FormatException使整個計劃返回null。返回的sources是List.unmodifiable即不可變集合。3.2 明確的拒絕清單以下任一情形都會讓fromMaster返回null無預取計劃由調(diào)用方回退到原有路徑多清晰度多個#EXT-X-STREAM-INF多個語言/音頻候選多個#EXT-X-MEDIAAUDIO 組字幕/隱藏字幕組CLOSED-CAPTIONS存在且不為NONEsession key、未知狀態(tài)標簽/屬性#EXT開頭的未知標簽、STREAM-INF 出現(xiàn)白名單外的屬性組關(guān)聯(lián)不完整STREAM-INF 引用 AUDIO 組但組缺失或反之重復字段同一屬性名出現(xiàn)兩次_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*$正整數(shù)#EXT-X-MEDIA的屬性白名單為TYPE / GROUP-ID / NAME / URI / DEFAULT / AUTOSELECT / LANGUAGE / CHANNELS / CHARACTERISTICS其中TYPE必須為AUDIOGROUP-ID、NAME、URI均非空DEFAULT/AUTOSELECT只能是YES/NO。這些嚴格約束正是不猜測、只識別唯一確定組合的體現(xiàn)。3.3 屬性解析器_attributes使用([A-Z0-9-])([^]*|[^,\s])正則逐段解析逗號分隔的屬性列表遇到重復鍵、非法分隔符非逗號或結(jié)尾懸空逗號都拋出FormatException因此重復字段會被同一機制攔截。四、原生實驗適配層從 master 到 selectAll 的一次性接入文檔指出原生實驗適配層已經(jīng)使用該計劃讀取實際源站 master → 獲取兩份初始媒體 snapshot → selectAll 一次性準入 → 返回 master隨后 native 請求子清單時復用已選 feed不重復選擇、不重復加載。此前由 native 順序訪問兩路后逐個 select 的實驗接線已替換。在源碼中這一流程對應(yīng) 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))并發(fā)拉取兩份初始媒體快照——注意文檔與代碼都強調(diào)Serial initial reads age the first short live window while waiting for the second因此共享同一個取消令牌cancellation任一加載失敗都會cancellation.cancel()使整個準備過程作廢為每路生成本地資源 ID取自_localResource的路徑末段文件名構(gòu)建HlsPrefetchSelection列表創(chuàng)建HlsPrefetchPoolmaximumEntries: 32, maximumConcurrent: 16, memoryBytesPerBody: 512 * 1024與HlsPrefetchSchedulermaximumFeeds: selections.lengthcandidate.selectAll(selections)一次性準入失敗則整個候選調(diào)度器被close()不產(chǎn)生任何部分啟用的 A/V 集合準入成功后_prefetch candidate后續(xù)請求通過_servePrefetchManifest/_servePrefetchBody復用已選 feed。_servePrefetchBody中的關(guān)鍵語義還包括acquire超時或失敗時按失敗狀態(tài)碼回 503/410停止階段未排空則置_inputTailDiscarded trueBYTERANGE 緩存只服務(wù)于其聲明的切片——若請求的 Range 與資源聲明的requestHeader不一致返回 416絕不把緩存切片冒充完整對象。這段適配同時保留了原始 master 和媒體字節(jié)不改質(zhì)量、音軌或時間戳。切換/停止階段_endedManifest只為媒體清單補#EXT-X-ENDLISTmaster 目錄清單原樣返回。五、驗證范圍從定向測試到雙場景原生實驗5.1 master 計劃測試文檔列出新增 master 計劃測試的覆蓋面唯一組合、不可變集合、組錯配、多變體/多音軌、重復屬性、空/憑據(jù)/降級/fragment URI、未知會話/字幕合同等。與之配套的批量測試斷言了原子性的可觀測結(jié)果第二路被拒時feed0、download0、pool 條目0——沒有任何一路進入活動狀態(tài)有效組合第一次 loader 回調(diào)必須已觀察到feed2——兩路在準入瞬間同時可用失敗后的重復準入保持既有狀態(tài)不破壞已經(jīng)準入的組合。5.2 雙場景原生實驗原生實驗目錄controls/scheduled-1788957891514939/使用同一 12 秒視頻 body 或 headers、6 秒滾動窗口、34 秒曝光驗證真實 TCP native鏈路場景TS 字節(jié)本地完整視頻序號視頻/音頻包探針停止耗時 ms觀察峰值條目/下載body 12 秒3,329,6680–13連續(xù)840 / 1407216520 / 8headers 12 秒3,300,3400–13連續(xù)840 / 1313218019 / 8兩場景均code0、正常排空、無強制取消、無完整性錯誤、無活動覆蓋缺口尾部丟棄仍為 true。兩路合計 66 次獨立刷新關(guān)閉后池條目和字節(jié)均歸 0。視頻最大排序包步長 0.033334 秒、音頻 0.021334 秒整體仍是約 28 秒視頻body 場景音頻約 30 秒、headers 場景約 28 秒——文檔謹慎聲明不據(jù)此宣布所有尾部對齊。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故不稱作遠端包哈希通過——這一表述邊界體現(xiàn)了審計對證據(jù)等級的嚴格區(qū)分。5.4 資源守衛(wèi)與構(gòu)建記錄重型驗證經(jīng)共享資源守衛(wèi)排隊未停止其他任務(wù)的 Java 進程排隊期間沒有繼續(xù)編輯源碼。證據(jù)根目錄local-artifacts/hls-prefetch-plan-20260909/資源記錄均位于local-artifacts/build-records/文件前綴 / 階段秒含排隊觀察峰值 CPU %峰值工作集 B階段結(jié)束活躍重型進程20260909T124040828Z / atomic-plan188.07715.5711725209600020260909T124630392Z / atomic-fixed295.79175.3914921601024120260909T124702156Z / decode19.7180.11110300733440一個值得注意的工程細節(jié)首次atomic-plan在分析階段因三個多行 if 缺少花括號失敗未運行測試補齊花括號后運行atomic-fixed。同時讓實驗 master 響應(yīng)頭和 body共用同一個響應(yīng)預算不在讀取 body 時重新計時。所有失敗、排隊與成功記錄均被保留。第二階段結(jié)束時另有 Java 進程活躍解碼階段繼續(xù)在資源守衛(wèi)中排隊該進程隨后退出監(jiān)控值包含可見重型進程不把 75.39% 全部歸因于預取代碼也未聲稱第二階段結(jié)束立即全機空閑。最終解碼記錄為 0兩個本任務(wù)執(zhí)行句柄都已收到終態(tài)。六、生產(chǎn)接入狀態(tài)與剩余工作文檔明確了當前所處的階段與邊界本輪把完整 A/V 選擇接通到真實 TCP native 實驗但尚未把預取默認啟用于應(yīng)用的FFmpegHlsInputRelay。下一步復用這個全體先校驗的入口接通生產(chǎn)資源 ID/HTTP Range 和失敗狀態(tài)、統(tǒng)一資源預算與停止生命周期而非再疊一層實驗 HTTP。結(jié)合源碼看生產(chǎn)側(cè)的接入點已經(jīng)就位FFmpegHlsInputRelay在_handleRequest中當resourceId root prefetchEnabled !_finishing時觸發(fā)_preparePrefetch見 lib/domains/recorder/data/services/ffmpeg_hls_input_relay.dart且enablePrefetch僅在drainOnStop同時開啟時才生效prefetchEnabled: enablePrefetch drainOnStop。此外manifestMediaTransform ! null enablePrefetch會被顯式拒絕——預取緩存尚未承接 manifest 級媒體前綴變換的所有權(quán)因此兩者不能同時啟用。探針 tool/probes/hls_scheduled_delivery_probe.dart 通過環(huán)境變量PURELIVE_HLS_PRODUCTION_PREFETCH_PROBE1選擇直接生產(chǎn)預取或歷史實驗適配器兩者均為 opt-in 探針不是默認的應(yīng)用程序激活。其他明確未完成項多變體等返回無計劃不等于這些平臺驗收通過真實 LL-HLS、尾部完整排空、所有平臺/界面功能、穩(wěn)定版 3.2.0 發(fā)布仍屬于原目標宏觀仍為20 PASS / 32 RUN / 10 NOT RUN42 個驗收大項未閉環(huán)沒有手機操作、構(gòu)建、版本修改、上游合并或發(fā)布。七、相關(guān)源碼與文檔索引關(guān)注點路徑原子準入調(diào)度器selectAll / select / 運行期泵與刷新lib/domains/recorder/data/services/hls_prefetch_scheduler.dart無歧義 master 計劃fromMasterlib/domains/recorder/data/services/hls_prefetch_plan.dart有界預取池與票據(jù)/租約lib/domains/recorder/data/services/hls_prefetch_pool.dart保留窗口與清單渲染合同lib/domains/recorder/data/services/hls_retained_window.dart、hls_retained_manifest.dart生產(chǎn) relay 接入與預取服務(wù)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結(jié)語pure_live 的 HLS 預取原子準入為雙路 A/V 預取樹立了一個可復用的范式把選擇權(quán)與校驗權(quán)徹底分離——HlsPrefetchPlan.fromMaster只負責識別無需猜測的確定性組合HlsPrefetchScheduler.selectAll只負責全體先校驗、再一次性提交而運行期的一切不確定性網(wǎng)絡(luò)失敗、清單漂移、密鑰續(xù)簽、來源切換都交給既有的刷新、凍結(jié)與排空合同。這種設(shè)計讓錄制端在多清晰度、多語言候選的 HLS 世界里既不越權(quán)猜測也絕不陷入半套 A/V 流的殘缺狀態(tài)。對任何需要穩(wěn)定錄制 HLS 直播的工程而言這份從設(shè)計、實現(xiàn)到原生驗證的完整鏈路都值得對照借鑒。贊分享音視頻直播移動開發(fā)【免費下載鏈接】pure_live純粹直播:嗶哩嗶哩/虎牙/斗魚/快手/抖音/網(wǎng)易cc/YY直播/Twitch直播/SOOP直播/M38自定義源應(yīng)有盡有。項目地址https://gitcode.com/gh_mirrors/pur/pure_live點擊查看免費下載相關(guān)推薦pure_live 錄制鏈路 HLS 有界預取池未讀響應(yīng)取消修復與讀取租約所有權(quán)設(shè)計pure_live 錄制鏈路 HLS 有界預取池未讀響應(yīng)取消修復與讀取租約所有權(quán)設(shè)計 導讀 本文基于 pure_live純粹直播倉庫中 HLS_PREFE音視頻直播移動開發(fā)pure_live HLS 預取調(diào)度器深度解析獨立清單刷新、有界分片預取與停止語義審計pure_live HLS 預取調(diào)度器深度解析獨立清單刷新、有界分片預取與停止語義審計 本文基于 pure_live純粹直播開源倉庫的審計文檔 docs/音視頻直播移動開發(fā)pure_live HLS 明確選流機制剖析從多畫質(zhì) master 解析到 niconico 雙軌短錄實戰(zhàn)驗證pure_live HLS 明確選流機制剖析從多畫質(zhì) master 解析到 niconico 雙軌短錄實戰(zhàn)驗證 導讀 本文以 pure_live純粹直播倉音視頻直播移動開發(fā)上一篇Matterwiki團隊知識管理的簡單選擇下一篇終極指南Diem Move智能合約測試完整教程 - 單元測試與集成測試實踐創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考