Qubitlab Offline Lesson Video Resource Governance — Technical Analysis | KeyRotate Technology

一、把课程视频放进应用包，是一笔可以算清的交换

QubitLab 是密旋科技面向 iOS 端的量子物理与 STEM 启蒙沙盒：九十六关闯关、布洛赫球面态矢进动、双比特逻辑门拼装与测量坍缩演示，全部在本机运行。这个产品在打包层面有一处不常见的选择——每一关的导读视频与封面图不是从内容分发网络按需拉取的，而是随应用包一起安装到设备上。

这笔交换的账单可以直接读出来。资源目录里是九十六关各两支视频（英文与中文各一支）与一张封面，合计一百九十二支 mp4 与九十六张 jpg；目录内除这两类文件之外没有第三个来源。视频合计 1436.1 兆字节（英文 751.7、中文 684.3），封面合计 17.6 兆字节。换来的是：关掉网络以后，这套课程的内容一件不少。

流媒体方案不是做不到，它把代价挪到了播放前后：缓冲、弱网降级，以及一次播放行为在网络侧留下的记录。对一个以未成年人为主的端侧教育应用来说，“上课这件事本身出现在别人的日志里”就是要避免的那部分。把媒体放进包里，等于用安装体积与更新方式把这份代价换掉。换得是否划算，取决于通道本身的工程质量是否撑得住这份承诺。

二、包内资源的静态账

先给一份可核对的账。下面每一行都是对包内文件逐支统计出来的，不含估算。

这张账里已经藏着两个后面要用的线索。一是时长区间很窄：最长的成片比最短的只多出约五成；二是体积区间很宽：最重的单支是最轻的约 6.8 倍。两者不成比例，说明体积差异不是内容长短造成的。

三、命名就是交付契约

包内的一致性靠什么守？第一步不是哈希，是命名。资源解析器给出的是两条规则：课程视频叫 level<编号>_lesson_<语言>.mp4，封面叫 level<编号>_cover.jpg。解析时先按首选语言拼名字取文件，取不到就换另一种语言；封面则先试 jpg，再回落到 png——回落分支在当前包里没有命中，因为九十六张封面全是 jpg。

同一个命名规则在打包侧被写成了一道机器核对。包内审计脚本用正则 ^level([1-9][0-9]?)_lesson_(en|zh)\.mp4$ 与 ^level([1-9][0-9]?)_cover\.(jpg|png)$ 去识别文件，再按关号 1 到 96 与两种语言生成一百九十二个期望名字，然后做一次双向差集：缺失的名字与多出来的名字同时报出。这一条值得写清楚——只报缺失的核对，在有人把一批实验素材误放进资源目录时是沉默的；只有集合相等才是真的相等。

同一段脚本还有两处小口径：封面张数必须恰好九十六张，少一张即判失败；审计入口可以指向源码资源目录或编译出来的应用包，通过时会把资源根与总字节数打印出来，交付体积因此是一次审计输出而非文档承诺。

命名规则本身也有边界。[1-9][0-9]? 覆盖的是 1 到 99 的关号，若课程扩展到三位数关号，正则与期望集合必须同时改，否则新关卡会因为名字不匹配而整批落在核对之外，且不会报错。

四、生产目录与交付目录之间隔着一道闸

一支导读视频不是录一遍就能放进包的。它的上游是一条完整的内容流水线：脚本规范定义了每关八个分镜（引子、装置、概念、机制、示例、游戏关联、测验、延伸），每一关有一份双语脚本文件；教学合同清单记录了这一关的真实装置、可控变量、可观察读数、失败反馈、视觉绑定、时长预算与媒体资产名；此外还有反剧透规则与语义审计，要求脚本不朗读题干、不报答案、不给出通关数值，并且必须有可迁移的例子。

这些环节都发生在交付目录之外。包内审计脚本的做法是把它们的名字显式列为禁止项：流水线目录、素材中间目录、工作目录、评审目录、报告目录、抽帧目录与样张目录，只要这些名字出现在资源根路径里，就判失败；证据类文件后缀同样在列，包括溯源清单、轨迹记录与字幕文件。这条规定的意义不是洁癖，而是防止中间产物随包上线——一段未完成的旁白、一张评审样张、一份含内部路径的溯源记录，混进去都是对外可见的。

发布清单是另一道闸。清单里的资产条目必须恰好一百九十二条，每条带有媒体文件的摘要值；审计在核对名字的同时逐条比对摘要，并校验清单自身的摘要完整。于是”包里的这支视频”与”被批准发布的那支视频”之间有一条可核对的链条：名字对得上，字节也对得上。

五、存在不等于可播

打包核对回答的是”该在的都在”，没有回答”能不能播”。这两件事必须分开，因为失败模式完全不同：前者是交付完整性问题，一次打包就能定论；后者取决于设备能否解出这段媒体，只能在运行时判定。

解析层的返回是一个两态结果：要么拿到一个本机文件地址并带上”请求语言”与”实际选中语言”两个字段，要么明确报缺失。校验层更严格，它把结果分成三态：可播、无效、缺失。判定动作是四项探测——把本机文件交给媒体资产对象，异步读取可播标记、时长、视频轨与音频轨；只有可播标记为真、时长是有限值且大于零、视频轨与音频轨都非空，才算可播，否则记为无效。

这里有一条容易忽略的口径：探测要求音轨存在。演示视频若只有画面没有声音，在播放器里可能照样能放，但在这套判定里会被记成无效，因为导读视频的旁白是教学内容本身，没有音轨等于内容不完整。把”能解码”与”内容完整”合成一个条件，是这份判定与通用播放器最不一样的地方。

解析与校验串起来，就形成了播放前的候选链：先按首选语言找文件，命中即用；找不到或校验不通过，再试另一种语言。首个无效候选会被记下来，但不会中断尝试——只要另一语言可用，学生看到的仍然是视频，只是界面上的语言标签会被改成实际播放的那一种。全部候选都失败时，结果优先报”无效”而不是”缺失”，因为一个文件存在却读不出内容，与一个文件根本不在包里，是两条需要不同处置的故障。

三种出口在界面上各有交代，措辞也是分开的：可播放的直接进入播放器；文件存在但未通过音画与时长验证的，提示这支本地视频无法播放；文件不在包内的，提示本机缺少本地课程视频，并明确写出不要依赖网络加载。把”缺文件”与”坏了”写成两句不同的话，是端侧应用的一条基本纪律：没有服务端兜底，用户的下一次动作取决于这句话说得准不准。

六、双语母版与回退

这套视频的双语不是一条音轨加一条字幕，而是两支独立的母版：英文母版与中文母版各自完整，各九十六支。选这个方式的原因很实际：旁白要讲的是同一个物理关系，但语速、停顿与画面停留时长需要各自安排，混音方案会把其中一种语言的节奏强加给另一种。

运行时的语言策略分三层。第一层是首选语言，取自当前界面语言——系统语言属于中文家族时默认中文配音，否则默认英文配音。第二层是回退，首选语言的文件缺失或校验失败时，改用另一语言的母版，并把界面语言标签同步改到实际播放的那一种，避免标签与声音不一致。第三层是切换能力，只有当两种语言的母版都存在时，界面上才会出现语言切换芯片；包内九十六关双向齐备，所以这个芯片在每一关都可用。

解析策略还留了一个工程上的余地：解析器的文件查找函数是可注入的。默认实现读应用包，测试实现读一份夹具目录，于是”首选语言命中即用""首选缺失则回退""两者都没有时报缺失”等策略，可以在不依赖真实包的情况下被断言。把策略与本机包解耦，是这套判定能被测试覆盖的前提。

七、播放侧：会话、结束事件，以及看完不等于通关

播放器本身是一张十六比九的卡片：封面图铺满、中央一枚播放按钮、左上角注明这是核心科学导读、右下角是时长徽章。时长徽章不是写死的常量，它在卡片出现时异步读取本机文件的时长再按分秒格式化；取不到时长就保持在占位形态。播放前有一道防重入闸门，避免连点两次起出两个播放器。

音频会话的处理是一项独立配置。视频开始播放时把会话设为播放类别与影片模式，并降低其他应用的声音；停止播放或页面退出时，把会话交还给其他应用。这条路径与操作反馈音效的路径是分开的：一次点击反馈不该长期占用音频会话。

结束事件的处理最能说明这层设计的口径。播放到末尾时，观察者把本地的一个状态置为已看完，界面随之出现两个按钮：重播，或者进入游戏。这个状态只存在于视图内部，不写入进度，也不产生任何记录——看完整支导读视频不等于完成这一关，关卡完成与否由游戏侧的结算判定。把”看过”与”学会”分开，是让课程度量口径保持干净的前提。

播放器还有一处交互值得记下来：进入游戏之后，关卡页工具栏会保留一枚导读胶囊，可以随时回到视频。导读不是一次性入口，学生可以在操作实验台之后再回看这段解释。

八、覆盖率被写成了断言

资源齐备这件事，最怕靠人工抽查。这个工程把它写成了机器断言：一条单元测试遍历课程目录里的九十六关，逐个检查四件事——关卡标识恰好九十六个且不重复；每关的封面文件存在且能被解码，解出的宽高都大于零；两种语言的母版都能解析到，并且实际选中语言等于请求语言，即终包里不应再需要回退；解析到的文件通过校验层，结果为可播且时长大于零。

第二条断言是四种里最有信息量的：它把”封面图存在”升级成了”封面图能解码”。一张零字节的同名文件或一段被截断的 jpg，在文件名层面完全合格，在断言层面立即失败。第四条同理，它把”命名对得上”再往前推了一步——只有能读出一段有效音频与视频、且时长有意义，才算这支视频在包里。

这类断言的价值不在于它抓过多少次错，而在于它把一条人工纪律变成了打包流程的一部分。

九、内容齐了，参数没齐

回到第二节那张账里的两个区间。成片时长落在 112.8 到 171.4 秒之间，均值 143.7 秒，这个区间很窄；单支体积却落在 3.80 到 25.66 兆字节之间，均值 7.48 兆字节，这个区间很宽。把两组数据放在一起看，结论是清楚的：体积差异几乎全部来自码率与帧率的差异，而不是内容长度。

$S \approx \frac{R \times T}{8 \times 10^{3}}$

式中的 $S$ 是以兆字节计的文件体积，$R$ 是以千比特每秒计的码率，$T$ 是以秒计的时长。代入实测的两端：码率 228 千比特每秒、时长 129 秒的一支约 3.7 兆字节；码率 1410 千比特每秒、时长 140 秒的一支约 24.7 兆字节。两式的时长只差约 8%，体积却差约 6.7 倍。

这不是一个缺陷指控，而是一条可以核对的管理事实：当前包里绝大多数视频码率都在 600 千比特每秒以下，只有第 1 关的两支例外；那两支的帧率是每秒 30 帧，其余各支是每秒 15 帧。也就是说，编码参数在批次之间并不统一，而它对包体总量的影响远比内容长度大。对课堂讲解视频来说，每秒 15 帧与 700 千比特每秒上下的码率已经能承载黑板式动画；把码率与帧率纳入发布门禁，是控制包体最直接的一步。

顺带说明一处口径差异：教学合同清单为每关给出的是脚本朗读时长预算（例如六十到八十五秒这样的区间），而实测值来自成片容器。两者口径不同，对齐情况需要在制作侧核对，本文只报实测。

十、这条通道的能力边界

在这四条之上，还有若干必须写明的边界。

第一，摘要与命名证明的是”交付的是同一份文件”，它不能证明”这份文件的内容是对的”。包内一致性靠机器，内容正确性仍要人工观看与评审脚本共同承担。

第二，资源没有增量通道：文本与字典可以随小版本迭代，包内媒体不行——替换任何一支视频都意味着重新出包与重新上线，视频内容的修订周期因而远长于文案。

第三，包内没有任何字幕文件，字幕后缀在资源目录里属于被排除的类别。视频的教学信息因此主要靠双语旁白承载；双语母版解决的是语言选择，不等同于为听障学习者提供字幕这一条。这是当前形态的一处能力缺口，而不是已经解决的问题。

第四，覆盖率断言检查的是包内文件，不能替代人判断一支视频讲得对不对；四项探测能判定文件可播，不能判定这段讲解对物理关系的表达是否准确。

第五，包体代价是真实存在的。一千四百多兆字节的媒体与十七点六兆字节的封面直接影响安装门槛与设备占用，对存储紧张的低端设备尤其如此——这是”内容随包走”这条路线必须一并接受的成本。

第六，运行的判定全部在本机完成：解析读本机包，校验读本机文件，播放不请求远端资源，也没有任何播放统计上报。代价同样明确——没有远端播放日志，就没有观看完成率这类运营数据。

近七日内入库的共享情报里，教育领域的商用密码应用安全性评估、人工智能与教育新型基础设施建设项目，以及教育考试机构的国产化适配与密码应用采购占据了相当比例。这类采购有一个共同点：把数据边界与合规审计前置为验收条件。对端侧教育应用来说，这条边界的第一站就是内容与学习记录都在设备上——课程视频不进内容分发网络，是本机数据不出设备这条承诺能够成立的前提之一。

十一、结语

这条通道的工程价值，不在”视频能不能放”这一个动作上，而在它把承诺拆成了几件可以核对的事：名字成集合，封面齐备，生产目录不进包，摘要逐条对上；点按播放之后再验一次可播性，并把结果分成三种各有交代的出口。前一组的产物是打包审计的输出，后一组的产物是学生眼前那句准确的提示。

密旋科技在这套端侧教育沙盒里选择把内容随包交付，代价写在体积与更新周期上，收益写在”关掉网络之后一件不少”这句话里。把四道核对与一道判定如实写清楚，比声称流程处处可控更接近工程事实：这里能证明的是交付完整与文件可播，证明不了的是这一节课讲得好不好。

参考文献

[1] Apple Developer Documentation. AVURLAsset — Loading media data asynchronously. https://developer.apple.com/documentation/avfoundation/avurlasset

[2] Apple Developer Documentation. NSNotification.Name.AVPlayerItemDidPlayToEndTime. https://developer.apple.com/documentation/foundation/nsnotification/name-swift.struct/avplayeritemdidplaytoendtime

[3] Apple Developer Documentation. AVAudioSession — Configuring your app’s audio behavior. https://developer.apple.com/documentation/avfaudio/avaudiosession

[4] Apple Developer Documentation. Bundle — url(forResource:withExtension:). https://developer.apple.com/documentation/foundation/bundle/url(forresource:withextension:)

[5] Apple Developer Documentation. Reducing your app’s size. https://developer.apple.com/documentation/xcode/reducing-your-app-s-size

[6] Apple Developer Documentation. On-Demand Resources Guide. https://developer.apple.com/library/archive/documentation/FileManagement/Conceptual/On_Demand_Resources_Guide/index.html

[7] W3C. Web Content Accessibility Guidelines (WCAG) 2.2 — 1.2.2 Captions (Prerecorded). https://www.w3.org/TR/WCAG22/

[8] ITU-T Recommendation H.264 — Advanced video coding for generic audiovisual services. https://www.itu.int/rec/T-REC-H.264/en