Vokoscreen 鸿蒙PC录制链路设计——Canvas 帧流采集、WebM 分片落盘与基于 bpp 的码率估算

Vokoscreen 是 Linux/X11 生态里的一款屏幕录制器,输入源是 X11 桌面、扬声器与摄像头。鸿蒙 PC 的 Electron 适配层没有提供 desktopCapturer 与 getDisplayMedia,也没有系统音频采集入口,于是这套壳把「录什么」从整块屏幕收窄到一块 canvas:画面由数据结构逐帧合成,canvas.captureStream 供帧,MediaRecorder 编成真实 WebM,主进程以 begin → chunk×N → end 三段式顺序落盘,内存里永远只持有一个分片。壳内一共 11 个源文件 5135 行 178586 字节,其中六个纯函数引擎占 1289 行 47460 字节;产物 195368509 字节,四份原生库吃掉 174100264 字节。

本文严格按仓库里的真实代码展开,讲清楚三件事:为什么录制必须拆成三段式而不能攒到最后一次性传一个大字符串;为什么场景坐标必须停在 0…1 而不是像素;为什么码率用 bpp 建模而不是按分辨率查表。同时把缺陷与限制摆在明处:本壳不接管系统桌面、不采系统音频、ffmpeg 计划只写不执行、内容安全策略把 connect-src 压到 none。所有数字都来自当前工程文件与构建日志,没有一项是估出来的。

欢迎加入开源鸿蒙 PC 社区:https://harmonypc.csdn.net/

欢迎在 PC 社区平台申请新建项目:https://atomgit.com/OpenHarmonyPCDeveloper

AtomGit 仓库地址:https://atomgit.com/OpenHarmonyPCDeveloper/ohos_Vokoscreen

一、技术架构分析

1.1 先把本壳录不到的东西列出来

main.js 的 app:info 通道里有一个 unsupported 数组,四条内容一字不改地列在下面:

unsupported: [
  '系统桌面 / 窗口 / 区域捕获:适配层未提供 desktopCapturer 与 getDisplayMedia,录制源只有壳内画布',
  '系统音频与麦克风采集:产物是不含音轨的纯视频 WebM',
  'mp4 / mkv 转封装:MediaRecorder 只产出 WebM,换容器请在桌面端用 ffmpeg',
  '真实鼠标与键盘事件回放:点击与按键标记由本壳画布合成,不注入系统输入'
]

这四条构成了整个项目的边界,也决定了后面六章里每一个技术选择的形状。上游 Vokoscreen 在 X11 上做的是抓屏,抓到的像素本来就存在于桌面;本壳抓不到桌面,只能自己画。于是录制器变成了一个合成器:画面内容由场景数据结构完全决定,帧率由计划决定,编码器由 Chromium 的 MediaRecorder 提供,落盘由主进程的 fd 完成。

把抓屏换成合成,看起来是退让,实际换回来两样东西。

第一样是可复现。同一份场景、同一个帧率、同一个时间点,合成出来的像素是一样的。这一点在报告里尤其重要:报告能写「第 12.000 秒画面里有第 3 层文字块、不透明度 1、区域 0.06 到 0.94 横向」,因为确实能用同一份数据算出这一帧该长什么样。抓屏做不到这件事,抓到的像素和场景描述之间没有可验证的对应关系。

第二样是可计算。画面里的每一个尺寸都能从数字推出来:文字块的字号是二分出来的,涟漪半径是缓出曲线算出来的,放大镜的源框是按倍率反推并夹在画面内的,按键浮层的字号同样是二分出来的。这意味着渲染层里画出来的东西,和报告里承诺画了的东西,来自同一个公式。这一点在 3.5 节会展开。

能力边界只写在 app:info 里一次,界面照抄。这样做的理由很直接:如果「不支持什么」在文档里写一遍、在界面上再写一遍、在报告里再写一遍,三份迟早会不一致,用户看到的那份往往还停留在上一个版本。现在源只有一处,界面渲染和报告生成都读同一个数组。

1.2 十三个 IPC 通道与三段式落盘

主进程注册了十三个 ipcMain.handle,源码里按 1 到 13 逐条加了编号注释,分组如下:

分组数量通道
运行环境1app:info
素材导入2assets:choose、assets:read
录制4rec:begin、rec:chunk、rec:end、rec:abort
工程与报告3proj:save、proj:open、report:save
单帧导出1file:saveBinary
系统集成2clip:write、shell:reveal

1 + 2 + 4 + 3 + 1 + 2 = 13。十三个通道共用同一个 handle() 包装器,把抛出的异常统一转成带 success、error、code 三个字段的返回对象,渲染层就不必为每个通道各写一套 try-catch。带 code 的只有主进程自己定义的错误码,例如录制会话已存在时的 ERECOPEN、没有会话时的 ENOREC,渲染层靠 code 判断而不是靠匹配中文文案。

十三个通道里最值得讲的是录制那四个,因为它们合起来解决的不是「怎么存」而是「怎么存得下」。

main.js 文件头把论证写死了:

/* 为什么录制要分片写:MediaRecorder 每 1 秒吐一个 Blob,如果攒到最后一次性 base64 传过来,
 * 20 秒 1080p 就是几百 MB 的字符串,渲染层先 OOM。所以 begin → chunk×N → end 三段式,
 * 主进程持有一个 fd 顺序追加,内存里永远只有一片。
 */

很多人对这段的直觉是「4.3 MB 的文件能有多大内存」。问题不在最终文件大小,而在传输形态。IPC 传 Buffer 在 Electron 里走结构化克隆,但这里传的是 base64 字符串,因为渲染层的 FileReader 只能给 DataURL。base64 把 3 字节膨胀成 4 字节,再乘上 V8 里字符串的内部表示,实际驻留是按字符算的。200 MB 的视频数据,base64 后是约 267 MB 的 URL 字符串,在堆里再翻倍,就是五百多 MB 的量级。本地文件才两百多 MB,但内存峰值要到这个数,长录制一定先死在渲染进程上。

分片把这个峰值压成常量。每秒一片,解码后写入文件,写完就丢引用,堆里同时只活着一片。分片大小与累计大小各有一道上限:

var MAX_REC_BYTES = 512 * 1024 * 1024;    /* 单个录制文件上限 */
var MAX_CHUNK_BYTES = 8 * 1024 * 1024;    /* 单个分片(base64 解码后)上限 */

单次上限防的是异常分片:编码器某次憋了很久才吐出一个特别大的 Blob,或者渲染层把整段数据当成一片送过来。累计上限防的是把磁盘写满:512 MB 大约对应 1080p 30fps 均衡档下三十八分钟,到线就明确提示「请停止后分段录制」,而不是继续写下去最后留一个打不开的文件。

追加写落在这个调用上:

handle('rec:chunk', function (req) {
  if (!recSession) { var err = new Error(ERR_TEXT.ENOREC); err.code = 'ENOREC'; throw err; }
  var b64 = String(req.base64 || '');
  if (!b64) return { success: false, error: '收到空分片,已忽略' };
  var buf = Buffer.from(b64, 'base64');
  if (!buf.length) return { success: false, error: '分片解码后为空,已忽略' };
  if (buf.length > MAX_CHUNK_BYTES) return { success: false, error: '分片 ' + sizeText(buf.length) + ' 超过单次 ' + sizeText(MAX_CHUNK_BYTES) };
  if (recSession.bytes + buf.length > MAX_REC_BYTES) return { success: false, error: '单个录制文件超过 ' + sizeText(MAX_REC_BYTES) + ' 上限,请停止后分段录制', bytes: recSession.bytes };
  fs.writeSync(recSession.fd, buf, 0, buf.length, null);
  recSession.bytes += buf.length; recSession.chunks += 1;
  return { success: true, bytes: recSession.bytes, chunks: recSession.chunks };
});

fs.writeSync 的第五个参数传 null,语义是「从当前文件位置继续写」。改成传一个固定的 offset 就成了覆盖,每片都会盖掉前一片,最后文件里只剩最后一片的长度。这是 Node 文件 API 里最容易抄错的一个参数。

结束录制时不用累加值回报,而是重新 stat 一次:

handle('rec:end', function () {
  /* 关 fd,用真实文件大小回报(不是累加值,磁盘才算数) */
  var s = closeRec(); var st = null; try { st = fs.statSync(s.file); } catch (e) { st = null; }
  return { success: true, path: s.file, name: baseName(s.file), bytes: st ? st.size : s.bytes, chunks: s.chunks, startedAt: s.startedAt, endedAt: new Date().toISOString() };
});

累加值只是主进程记的账,磁盘才是事实。这两者不一致只有两种可能:写失败被吞了,或者有人动过文件。直接读磁盘大小,界面显示的就是用户打开文件管理器能看到的那个数字。

放弃录制则连文件一起清掉,不留半成品:

handle('rec:abort', function () {
  /* 关 fd 并删掉半成品,不留 0 字节垃圾 */
  var s = closeRec(); if (!s) return { success: true, removed: false };
  var removed = false; try { fs.unlinkSync(s.file); removed = true; } catch (e) { removed = false; }
  return { success: true, removed: removed, path: s.file };
});

重入保护在 begin 里:

handle('rec:begin', async function (req) {
  if (recSession) {
    var busy = new Error(ERR_TEXT.ERECOPEN); busy.code = 'ERECOPEN'; throw busy;
  }
  var name = String(req.defaultName || 'vokoscreen.webm');
  if (suffixOf(name) !== 'webm') name = name.replace(/\.[A-Za-z0-9]+$/, '') + '.webm';
  var r = await dialog.showSaveDialog(mainWindow, { title: '保存录制文件', defaultPath: name, filters: [{ name: 'WebM 视频', extensions: ['webm'] }, { name: '全部文件', extensions: ['*'] }] });
  if (r.canceled || !r.filePath) return { success: false, canceled: true };
  var file = fwd(r.filePath);
  if (suffixOf(file) !== 'webm') file += '.webm';
  rememberRoot(path.dirname(file));
  var fd = fs.openSync(file, 'w');
  recSession = { file: file, fd: fd, bytes: 0, chunks: 0, startedAt: new Date().toISOString() };
  return { success: true, path: file, name: baseName(file), startedAt: recSession.startedAt };
});

会话以对象存在与否作为状态,没有额外的布尔量。两个状态量描述同一件事,迟早会出现「布尔说在录、会话却是空的」这种半死状态。后缀在对话框返回后再校正一次,因为用户完全可以在保存框里手打一个 .mp4 的名字,而 MediaRecorder 只会产出 WebM,扩展名写错只会让系统关联到错误的播放器。

1.3 六个引擎的分层:数据、几何、报告

渲染层的全部可测逻辑都在 engines 目录。六个文件的行数与字节数:

文件行数字节职责
engines/vk-util.js1645471时间码、体积估算、文件名清洗、帧秒互换
engines/vk-scene.js37413963七类图层结构与 0…1 归一化坐标
engines/vk-timeline.js2197905四种段落的时间轴与标记点
engines/vk-mark.js1826435涟漪、放大镜、按键浮层的几何
engines/vk-plan.js1435338分辨率、帧率、质量档与外部录制计划
engines/vk-report.js2078348三种格式的报告
合计128947460

除引擎之外的五个文件:index.html 372 行 18249 字节、main.js 516 行 19342 字节、renderer.js 2207 行 78240 字节、styles/vokoscreen.css 730 行 14760 字节、package.json 21 行 535 字节,合计 3846 行 131126 字节。整个 app 目录 11 个文件 5135 行 178586 字节,引擎占 25.10% 的行与 26.58% 的字节。

这六个文件在 index.html 里的加载顺序是固定的,依次是 vk-util、vk-scene、vk-timeline、vk-mark、vk-plan、vk-report,最后才加载 renderer.js。前五个都只依赖浏览器全局,vk-plan 与 vk-report 依赖 vk-util 已经挂到全局上的对象,所以 util 必须排在最前。

每个引擎的文件头都是一段 UMD 包装:

(function (root, factory) {
  var api = factory();
  if (typeof module !== 'undefined' && module.exports) module.exports = api;
  if (root) root.VkMark = api;
})(typeof globalThis !== 'undefined' ? globalThis : this, function () {
  'use strict';

双出口的意义在测试:同一份文件在浏览器里挂到 window.VkMark,在 Node 里可以 require 进来直接跑断言,不需要为了测试再复制一份逻辑。这是六个引擎能在没有界面的情况下逐个验证的前提。

依赖关系的写法有个坑,vk-plan 的文件头把它记下来了:

/* 渲染进程开了 nodeIntegration,module 全局存在,但普通 script 里的 require
 * 相对路径基址不是本文件目录(会抛 MODULE_NOT_FOUND)。
 * 所以先取已挂到全局的 VkUtil,Node 下才回落到 require。 */
var U = (root && root.VkUtil)
  || ((typeof require === 'function') ? require('./vk-util.js') : null);

开了 nodeIntegration 之后,渲染层里 require 是存在的。于是「能 require 就 require」这种写法在浏览器环境里会直接抛 MODULE_NOT_FOUND,而且抛在文件顶层,整个脚本一个字都不执行,界面上表现为按钮全都没绑事件。先取全局、再回落 require 的顺序,把这个坑绕开了。

二、环境准备

2.1 SDK 声明与签名材料

顶层 build-profile.json5 里的 products 只有一份,字段如下:

{
  "name": "default",
  "signingConfig": "default",
  "compatibleSdkVersion": "5.0.5(17)",
  "compatibleSdkVersionStage": "release",
  "runtimeOS": "HarmonyOS",
  "buildOption": {
    "nativeLib": {
      "collectAllLibs": true
    }
  }
}

五件事需要拎出来说。

第一,compatibleSdkVersion 是 5.0.5(17),同时把 compatibleSdkVersionStage 明确写成 release。这个字段不写时行为依赖工具链默认值,写死之后换机器换版本都不会突然从 release 掉到 beta。

第二,文件里没有声明 targetSdkVersion。这不是漏写,而是留空取 SDK 默认值,构建日志里 targetSdkVersion 这个字样一共出现 8 次,每一次都是工具链在按默认值计算兼容行为。

第三,buildModeSet 声明了 debug 与 release 两个构建模式,signingConfigs 里只有一条名为 default 的 HarmonyOS 签名配置,signAlg 是 SHA256withECDSA,keyAlias 是 debugKey。也就是说当前工程里 release 与 debug 共用同一份调试签名,这是开发阶段的常规状态。

第四,collectAllLibs 为 true。这个开关的含义是把模块下所有架构的原生库全部收进产物,而不是只挑当前设备架构。5.2 节会看到,这个开关直接决定了产物里躺着四份 so 共 174100264 字节。在需要覆盖 2in1 与 tablet 两种设备形态的前提下,这个选择是必要的代价。

第五,也是必须在上架前处理的一项:material 里的 certpath、profile、storeFile 三个字段全部是本机绝对路径,形如 C 盘用户目录下 .ohos 配置目录里的 .cer、.p7b、.p12 三件套,keyPassword 与 storePassword 则是 IDE 在本机密钥环加密后的长串。这意味着别人把仓库拉下来直接构建会失败——签名材料在他机器上根本不存在,即便存在也无法解密。上架时这三件材料应当在构建流水线里重新生成并用环境变量注入,而不是跟着源码走。

工程的 modules 声明了两项:electron 走 ./electron,是 entry 类型;web_engine 走 ./web_engine。前者是原生壳入口,后者是渲染层资源包。

2.2 应用信息与工程配置

AppScope/app.json5 是关键字段的集中地:

{
  "app": {
    "bundleName": "com.huawei.ohos_electron",
    "vendor": "example",
    "versionCode": 1000000,
    "versionName": "1.0.0",
    "multiAppMode": {
      "multiAppModeType": "multiInstance",
      "maxCount": 1
    }
  }
}

bundleName 还是模板默认的 com.huawei.ohos_electron,vendor 还是 example,versionName 还是 1.0.0,三项都需要在上架前替换成真实信息。multiAppMode 声明为 multiInstance 但 maxCount 是 1,含义是允许以多实例模式启动、但同一时刻只允许一个实例。对录制工具来说这个取值是对的:两个实例同时打开工程会争抢同一个 .vksproj 文件,同时又都想占用保存对话框记住的目录授权,冲突处理成本远高于限制实例数。

AppScope 里还有一份 configuration.json,六行:

{
  "configuration": {
    "fontSizeScale": "followSystem",
    "fontSizeMaxScale": "1.45"
  }
}

允许界面跟随系统字体放大,上限 1.45 倍。这个配置和渲染层用固定像素写样式之间是有张力的:画布坐标必须稳定,否则预览和录制的画面比例会随系统字体变化;而面板文字跟随系统放大,则要求布局有足够的余量。真正起保底作用的是 4.3 节要讲的 1120px 断点——1.45 倍字体会把面板宽度推上去,断点让侧栏先收缩,而不是把主工作区挤成一条缝。

electron 模块的 module.json5 声明了三个 ability 和两个 extensionAbility。三个 ability 分别是:EntryAbility,launchType 为 specified,exported 为 true,skills 里带 entity.system.home 与 entity.system.browsable,并注册了 scheme 为 link 的 uri;BrowserAbility,跑在 :browser 进程里,exported 为 false;StatelessAbility,同样 launchType specified 且跑在 :browser 进程,exported 为 true。两个 extensionAbility 是 StatusBarEntryAbility(type 为 statusBarView)与 BrowserEmbeddedAbility(type 为 embeddedUI)。deviceTypes 声明的是 2in1 与 tablet,所以产物只面向 PC 与平板两种形态,手机上装不了。

EntryAbility 上还挂了一条元数据指向 shortcuts_config,用来声明应用快捷方式;launchType 用 specified 而不是默认的 singleton,是因为这套壳允许通过 link scheme 从外部拉起,specified 能保证每次拉起都带着新的 want 参数进入 onNewWant,而不是复用已有实例丢掉参数。

web_engine 模块的 type 是 har,deviceTypes 同样是 2in1 与 tablet,权限清单见 5.3 节。

2.3 内容安全策略:十条指令

index.html 的第 6 行到第 8 行是一段 meta 形式的内容安全策略:

<meta http-equiv="Content-Security-Policy"
      content="default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:; media-src 'self' blob:; connect-src 'none'; object-src 'none'; frame-src 'none'; base-uri 'none'; form-action 'none'">

十条指令放在一行里,逐条说明为什么是这个取值:

default-src 为 self,所有未单独声明的资源类型都只允许同源。

script-src 为 self,禁止任何内联脚本与远程脚本。index.html 里七个 script 标签全是外部文件,没有任何一个是内联的。

style-src 为 self,禁止内联样式。整份界面七百多行的样式全部在 styles/vokoscreen.css 里,没有 style 属性也没有 style 块。

img-src 必须放开 data:,因为导入的图片帧是通过 readAsset 读成 base64 DataURL 再送到渲染层的,不放 data: 的话导入的图一张都显示不出来。

media-src 必须放开 blob:,因为 canvas.captureStream 拿到的流与 MediaRecorder 产出的分片都走 blob scheme,这一条不放,录制链路第一帧就断。

connect-src 为 none。这是一个纯本地工具,不需要任何网络请求,于是直接把这条通道掐死——fetch、XHR、WebSocket、EventSource 全部失效。AppScope 里那条 ohos.permission.INTERNET 是模板带来的,本应用自身不发起连接,策略层再把这件事确认一遍。

object-src 为 none,禁掉插件对象。frame-src 为 none,禁掉内嵌框架。base-uri 为 none,防止用 base 标签劫持所有相对路径的基准——这一条在本地文件应用里尤其重要,路径全换成远程地址就能让界面去加载别处的脚本。form-action 为 none,禁掉表单提交。

这套策略的分量取决于渲染进程的配置。main.js 里创建窗口时写的是:

webPreferences: {
  nodeIntegration: true,
  contextIsolation: false
}

打开了 nodeIntegration,就意味着渲染层里 require 是真实可用的,一段注入的脚本可以直接 require 到 fs 和 child_process。这种配置下内容安全策略不是可选项,而是唯一还站着的那道墙。CSP 与代码是自洽的:全文没有内联事件处理器、没有内联 style、没有内联 script,六条 script-src 与 style-src 的禁令没有一条被违反。

这一点和同一系列里另一套壳形成对照——那套把显示器亮度与伽马都做完的工程压根没写 CSP meta,只是在窗口层关掉了菜单。同一个模板派生出来的项目,安全基线并不完全一致,谁写谁不写全看当期有没有人留意到。

三、核心适配流程

3.1 路径纪律与录制链路

渲染层开了 nodeIntegration,能直接拿到 fs,但这不意味着渲染层可以随意读写磁盘。主进程在四个函数里立了规矩:

function fwd(p) { return String(p == null ? '' : p).replace(/\\/g, '/'); }

function normForCompare(p) {
  var s = fwd(p);
  if (s.length > 1 && /\/$/.test(s)) s = s.slice(0, -1);
  return process.platform === 'win32' ? s.toLowerCase() : s;
}

function isInside(child, parent) {
  var c = normForCompare(child), p = normForCompare(parent);
  if (!c || !p) return false;
  return c === p || c.indexOf(p + '/') === 0;
}

fwd 把反斜杠统一成正斜杠,避免同一路径出现两种写法。normForCompare 在 win32 上转小写再做比较,因为 Windows 文件系统大小写不敏感,同一个目录写成 C:/Users 和 c:/users 必须被当成同一个。isInside 的写法值得仔细看:它比较的是「父路径 + 斜杠」作为前缀,而不是裸前缀。裸前缀会把 /home/user/data2 错误地认成在 /home/user/data 里面,加一个斜杠就不会。

授权根目录只在一个时机往数组里加:对话框返回之后。

function rememberRoot(p) {
  var full = fwd(path.resolve(String(p || '')));
  if (!full) return;
  for (var i = 0; i < allowedRoots.length; i++) {
    if (normForCompare(allowedRoots[i]) === normForCompare(full)) return;
  }
  allowedRoots.push(full);
}

所有写文件、读图片、reveal 的通道开头都会先过 guard:

function guard(p) {
  if (!isAllowed(p)) {
    var err = new Error('该路径不在本应用已授权的目录内,请先用对话框选择文件');
    err.code = 'EGUARD';
    throw err;
  }
}

这条设计把渲染层的能力限制在「用户主动选过的目录」里。绕路尝试——比如把路径改成上级目录、或者塞一个 …/…/ 前缀——都会在 isInside 那一刻被拦下来,因为路径已经被 path.resolve 归一过了。

错误文案单独维护了一张十三行的对照表:

var ERR_TEXT = {
  EACCES: '没有访问权限(换一个位置再试)',
  EPERM: '系统不允许这个操作',
  ENOENT: '文件或目录不存在(可能已被移走)',
  EEXIST: '目标文件已存在',
  EISDIR: '目标是一个目录',
  ENOTDIR: '路径中间有一层不是目录',
  ENOSPC: '磁盘空间不足',
  EMFILE: '同时打开的文件过多',
  EBUSY: '文件正被其他程序占用',
  EROFS: '所在位置是只读的',
  EGUARD: '该路径不在本应用已授权的目录内,请先用对话框选择文件',
  ENOREC: '当前没有正在进行的录制',
  ERECOPEN: '上一段录制还没结束,先停止它'
};

注释写得很直白:界面把 error 直接贴到状态栏,所以只给中文,不外泄英文系统原文。errText 的处理顺序是「已知码查表、消息含中文就透传、其余统一成系统调用失败加错误码」,三层兑底下来,用户永远不会在状态栏看到一串 ENOENT: no such file or directory, open ‘…’。

IPC 包装器里有一个只有异步才会踩的坑:

function handle(channel, fn) {
  ipcMain.handle(channel, function (event, req) {
    var fail = function (e) {
      return { success: false, error: errText(e), code: (e && e.code) || '' };
    };
    try {
      var out = fn(req || {});
      /* async 处理器里的 throw 会变成 rejected promise,同步 try/catch 抓不到 */
      if (out && typeof out.then === 'function') return out.then(null, fail);
      return out;
    } catch (e) {
      return fail(e);
    }
  });
}

十三个通道里有六个是 async,它们内部 throw 会变成 rejected promise,外层的 try/catch 根本接不住。如果不补 out.then(null, fail) 这一行,界面会在 openssl 对话框报错时拿一个未处理拒绝,状态栏什么都不显示,按钮看起来像点了没反应。

渲染层的录制链路如下。第一步取流并建录制器:

var plan = buildPlan();
var canvas = $('recCanvas');
var stream;
try {
  stream = canvas.captureStream(plan.fps);
} catch (e) {
  failStart('无法从画布取流:' + whyText(e, '平台不支持'));
  return;
}
var mime = VkPlan.chooseCodec(function (m) { return MediaRecorder.isTypeSupported(m); });
var mr;
try {
  mr = new MediaRecorder(stream, { mimeType: mime, videoBitsPerSecond: plan.kbps * 1000 });
} catch (e) {

注意 videoBitsPerSecond 直接吃计划里的 kbps 乘一千,和 3.2 节算出来的那个数字是同一个。于是界面显示的码率、报告里写的码率、编码器实际拿到的码率,三处一致。

取流失败和建录制器失败各有一个 try,因为它们是两个不同的失败点:前者可能因为平台没有 captureStream,后者可能因为选的 mime 实际不被支持。两者合在一个 try 里,出错时就分不清到底是哪一步挂的。

第二步,每秒一片转 base64 后送主进程:

var s = String(fr.result || '');
var at = s.indexOf(',');
var b64 = at >= 0 ? s.slice(at + 1) : '';
if (!b64) { resolve({ success: false, error: '分片为空' }); return; }
call('rec:chunk', { base64: b64 }).then(function (res) {
  if (res.success) {
    S.rec.bytes = res.bytes;
    S.rec.chunks = res.chunks;
  } else if (res.error) {

FileReader 给回来的是 data URL,逗号前是 media type、逗号后才是 base64。slice 切掉前缀再送,主进程那边就不用再解一层。

第三步,录制过程中对参数变更的约束:

/* 录制中允许改画面内容(文字、图层、标记、图片),但不许改录制管线参数:
改分辨率会重置画布并掐断 captureStream,改帧率与时长会让正在写的文件对不上计划 */
function guardPipeline(what) {
  var t = busyText();
  if (!t) return true;
  notice(t + '不能改' + what + ',先停止本轮录制', 'warn');

这条约束的边界划得很准:文字、图层、标记、图片都是画面内容,改了只影响从下一帧开始的像素,无损;分辨率、帧率、时长是管线参数,改了会让已写入的分片与计划脱节。改分辨率尤其严重,重置画布会让 captureStream 直接失效,后面所有分片都是空白。

能力自检也做成了可展示的数据,而不是一个隐形的 if:

function detectCaps() {
  var probe = document.createElement('canvas');
  var hasStream = typeof probe.captureStream === 'function';
  var hasMr = typeof MediaRecorder !== 'undefined';
  var codec = '';
  if (hasMr) {
    codec = VkPlan.chooseCodec(function (m) { return MediaRecorder.isTypeSupported(m); });
  }
  var md = navigator.mediaDevices || null;
  var caps = [

四项自检:画布取流、录制器、WebM 编码,以及用 navigator.mediaDevices 探到的媒体设备。前三项任一缺失就不能开录,界面会直接跳到「环境与限制」面板,而不是弹一句「录制失败」让人猜。

3.2 码率不用查表:bpp 模型与可复现的计划

vk-util.js 的文件头把选择讲完了:

 * 码率用 bpp(每像素每帧比特)建模,而不是按分辨率查表:
 * 1280×720 与 2560×1440 都能算,且 60fps 自动翻倍,不需要维护一张表。

三档质量以 bpp 标定:

var QUALITY = {
  low: { key: 'low', label: '省体积', bpp: 0.02, note: '文字与静态画面够用,快速运动会有拖影' },
  balanced: { key: 'balanced', label: '均衡', bpp: 0.065, note: '默认档:1080p30 约 4 Mbps' },
  high: { key: 'high', label: '高保真', bpp: 0.13, note: '细节多的画面用,体积成倍增长' }
};

公式只有一行:

function bitrateKbps(width, height, fps, qualityKey) {
  var w = clamp(width, 16, 7680);
  var h = clamp(height, 16, 4320);
  var f = clamp(fps, 1, 60);
  var q = qualityOf(qualityKey);
  var raw = (w * h * f * q.bpp) / 1000;
  /* 取整到 50 kbps:界面上跳来跳去的零头没有意义 */
  return clamp(Math.round(raw / 50) * 50, 300, 40000);
}

拿截图面板上的默认参数验算一遍。分辨率 1280×720、帧率 30、质量档均衡(bpp 0.065):

1280 × 720 × 30 × 0.065 / 1000 = 1797.12

1797.12 / 50 = 35.94,四舍五入到 36,再乘 50 得 1800,落在 300 到 40000 之间。也就是 1800 kbps,humanKbps 会把它格式化为 1.8 Mbps,与录制面板上「目标码率 1.8 Mbps」完全对得上。

体积接着推:

1800000 / 8 = 225000 字节每秒
225000 × 20 秒 = 4500000 字节

humanBytes 把 4500000 算成 4500000 / 1048576 = 4.29,保留一位小数就是 4.3 MB,与面板上的「预估体积 4.3 MB」一致。总帧数是 20 × 30 = 600,与面板上的 600 一致;宽高比是 round(1280 / 720, 3) = 1.778,同样一致。面板上那九个格子,四个数字全部能从这三个函数推出来,没有一个是写死的。

再把另外两档的注释验一下。均衡档写「1080p30 约 4 Mbps」:1920 × 1080 × 30 × 0.065 / 1000 = 4043.52,除以 50 得 80.87 四舍五入到 81,乘 50 得 4050 kbps,也就是 4.05 Mbps,与注释里的「约 4 Mbps」对得上。省体积档 1280×720×30 算得 552.96,取整后 550 kbps;高保真档算得 3594.24,取整后 3600 kbps。三档之间的比值 550 : 1800 : 3600 正好对应 bpp 的 0.02 : 0.065 : 0.13,因为其他乘数都相同。

不查表的好处在换分辨率时最明显。切到 2560×1440:2560 × 1440 × 30 × 0.065 / 1000 = 7188.48,取整得 7200 kbps;切到 720×1280 竖屏:720 × 1280 × 30 × 0.065 / 1000 = 1797.12,同样是 1800 kbps。前者像素数是后者的四倍,码率也是四倍,这正是 bpp 模型的自然结论。如果维护一张表,这四档分辨率乘六档帧率乘三档质量就是七十二个格子,每改一档就要重填一列,而用公式只需一次乘法。

计划函数里还有几个容易忽略的取整:

function plan(opts) {
  var o = opts || {};
  var w = Math.round(clampNum(o.width, 160, 3840, 1920) / 2) * 2;
  var h = Math.round(clampNum(o.height, 120, 2160, 1080) / 2) * 2;
  var fps = Math.round(clampNum(o.fps, 1, 60, 30));
  var seconds = U.round(clampNum(o.seconds, 1, 3600, 20), 3);
  var quality = U.qualityOf(o.quality);

宽高各自先除二取整再乘二,保证送出的是一个偶数。奇数尺寸在视频编码里是个经典坑:色度抽样按 2×2 像素块处理,宽或高是奇数时最后一行一列会被补齐甚至裁掉,画面右侧出现一条奇怪的边。与其在编码器里碰运气,不如在计划里就取偶数。

时长保留三位小数,是为了让界面上填 12.5 秒时算出来的帧数是 375 而不是 374.99999。码率下限 300、上限 40000 则分别防两个极端:下限防的是给一个小尺寸画面算出低到编码器直接拒绝的码率,上限防的是有人把 3840×2160 乘 60fps 乘高保真档算出一个跑不动的数字。

编码器的选择顺序也写在 vk-plan 里:

/* 渲染层按顺序取第一个 MediaRecorder 支持的;顺序固定,报告才可复现 */
var CODECS = [
  'video/webm;codecs=vp9',
  'video/webm;codecs=vp8',
  'video/webm'
];

三档固定顺序,从压缩效率最高的 VP9 开始退。探测函数自己抛错时当不支持处理,继续试下一个,不让一次异常把整条编码器选择链掐断。顺序固定还有一层意义:同一台机器两次录制、两台机器同一次录制,只要硬件支持一致,选出的编码器就一定一样,报告里的 codec 字段才具有可比性。

计划里的 codec 字段初始是空串:

/* codec 由渲染层探测后回填,这里先占位,报告与界面才有统一的字段 */
codec: String(o.codec || ''),

纯函数模块不知道当前环境支持什么,所以它只提供字段位置,取值由渲染层探测后回填。这样报告里的 plan 对象永远是完整形状,不会因为某个调用点忘了带 codec 就少一个键。

3.3 场景图层与 0…1 归一化坐标

vk-scene.js 的文件头给出了整个模块的存在理由:

 * 场景是「录什么」的唯一来源:预览画布、录制画布、导出报告都读同一份结构,
 * 所以这里只放数据与纯函数,不碰 DOM、不碰 canvas。
 *
 * 坐标一律用 0..1 的归一化值:换分辨率录制时布局不会跑位,
 * 换算到像素只发生在 draw 前一步(normToPx)。

七类图层与它们的默认矩形:

类型名称默认矩形用途
text文字块0.06 / 0.10 / 0.88 / 0.22标题与要点,按框宽自动折行
image图片帧0.10 / 0.22 / 0.80 / 0.52导入的图片序列按时间轮播
watermark水印0.70 / 0.90 / 0.26 / 0.06常驻角标,不抢主体
cursor点击标记0 / 0 / 1 / 1光标位置加点击涟漪
keys按键浮层0.04 / 0.80 / 0.42 / 0.12显示最近按下的键
loupe放大镜0.62 / 0.10 / 0.32 / 0.32以光标为中心的局部放大
shape强调框0.22 / 0.34 / 0.32 / 0.18矩形高亮

这七组数字与截图里场景面板的表格完全对得上。表格里四层的区域列分别是「6%/10% · 88×22%」「4%/80% · 42×12%」「70%/90% · 26×6%」「0%/0% · 100×100%」,正是上面第一、五、三、四行的默认矩形各自乘 100 后取整的结果。生成这几串文字的代码也只有一行一句:

function describe(layer) {
  if (!layer) return '—';
  var t = LAYER_TYPES[layer.type] ? LAYER_TYPES[layer.type].label : '未知';
  var r = normRect(layer.rect);
  return t + ' · ' + Math.round(r.x * 100) + '%/' + Math.round(r.y * 100) + '% · ' +
    Math.round(r.w * 100) + '×' + Math.round(r.h * 100) + '%';
}

表格里显示什么,读的就是这行函数的返回值,没有第二套格式化逻辑。

归一化的收紧四个步骤全在 normRect 里:

function normRect(r) {
  var src = r || {};
  var x = clamp01(src.x, 0);
  var y = clamp01(src.y, 0);
  var w = clamp01(src.w, 0.02);
  var h = clamp01(src.h, 0.02);
  if (w < 0.02) w = 0.02;
  if (h < 0.02) h = 0.02;
  if (x + w > 1) x = Math.max(0, 1 - w);
  if (y + h > 1) y = Math.max(0, 1 - h);
  return { x: round3(x), y: round3(y), w: round3(w), h: round3(h) };
}

第一步把四个数字全夹到 0…1。第二步给宽高一个 0.02 的下限,否则用户把宽度拉到 0 之后图层会彻底消失,界面上再也点不到它去修改。第三步处理越界:宽高加起来超过 1 时,回推左上角而不是截短宽高,因为截短会改变用户已经调好的尺寸。第四步保留三位小数,避免 0.1 + 0.2 那类浮点尾巴一路带到报告里。

转回像素只在绘制前一步发生:

function normToPx(rect, width, height) {
  var r = normRect(rect);
  var w = Math.max(1, Math.round(r.w * (Number(width) || 0)));
  var h = Math.max(1, Math.round(r.h * (Number(height) || 0)));
  var x = Math.round(r.x * (Number(width) || 0));
  var y = Math.round(r.y * (Number(height) || 0));
  return { x: x, y: y, w: w, h: h };
}

宽高同样有至少 1 像素的下限,否则一个 0.002 宽的图层在 720p 下会算成 1.44 像素四舍五入成 1,在更小的画布上直接算成 0,绘制调用会因为宽高为 0 被浏览器静默跳过。

反向的 pxToNorm 处理鼠标点击选层:把像素坐标除回画面尺寸再夹到 0…1,两个世界就能互相对应。命中测试从后往前遍历:

function hitTest(scene, nx, ny, tSec) {
  var list = scene && scene.layers ? scene.layers : [];
  for (var i = list.length - 1; i >= 0; i--) {
    var l = list[i];
    if (!l || !l.visible) continue;
    if (!inWindow(l, tSec)) continue;
    var r = normRect(l.rect);
    if (nx >= r.x && nx <= r.x + r.w && ny >= r.y && ny <= r.y + r.h) return l;
  }
  return null;
}

倒序是因为列表顺序就是绘制顺序,越靠下越靠上叠加。用户看见的是最上面那一层,点中的也就应该是最上面那一层。同时它跳过不可见图层与不在时间窗内的图层——两层都用同一套判断,不会出现「看得见却选不中」或「选得中却看不见」。

图层编号有一个和 3.4 节时间轴同源的写法:

function nextSeq(scene) {
  var max = 0;
  (scene && scene.layers ? scene.layers : []).forEach(function (l) {
    var m = /^ly-(\d+)$/.exec(String(l && l.id || ''));
    if (m) max = Math.max(max, parseInt(m[1], 10));
  });
  return max + 1;
}

取已用最大编号加一,不是数组长度加一。删掉中间一层后长度会回退,用长度续号就会和一个还活着的层撞 id,之后按 id 删除就会删错行。

读入外部工程文件时走 sanitize,把任意 JSON 收敛成受控结构:

function sanitize(raw) {
  var src = raw && typeof raw === 'object' ? raw : {};
  var scene = defaultScene();
  scene.title = String(src.title == null ? scene.title : src.title).slice(0, 120);
  ...
  if (Array.isArray(src.layers)) {
    var list = [];
    src.layers.slice(0, 24).forEach(function (raw2, i) {
      if (!raw2 || !LAYER_TYPES[raw2.type]) return;
      ...

三条约束:未知类型的图层直接丢弃不报错、最多只收 24 层、每个文本字段分别截到 120 / 160 / 200 字。工程文件是用户可以手改的文本,如果直接用它会变成任意字段进画布——一个 10 万字的 text 能让布局计算直接卡住,一个不存在的 type 能让绘制分支全部落空。

validate 是这些校验的可展示面,九条规则分 error 与 warn 两级:帧率不在 1 到 60 之间、时长不在 1 到 3600 秒之间、图层 id 缺失或重复是 error;没有图层、类型未知、区域太小、超出画面、文字块内容为空、结束时间不晚于开始时间是 warn。分级的意义在于前者必须改、后者可以先录——一层几乎看不见的图未必是错的,可能只是当时在调位置。

3.4 段落式时间轴:不存绝对时间

vk-timeline.js 的头注释把这个决定说得很透:

 * 段落是「按顺序播多久」的最小单位…这里不存绝对时间,只存每段秒数,时间轴每次现算——
 * 改一段不会把后面全部算错。

如果数据结构里存的是每段的起始秒与结束秒,那么把第二段从 10 秒改成 15 秒时,后面所有段的起点都要跟着往后推;只要有一个地方忘了推——比如某个缓存对象、某个界面行、某个已经算好的报告——就会出现两处时间轴打架的情况。存时长就避开了这件事:改一段只改一个数字,绝对区间每次重新累加。

四种段落类型:

var KINDS = {
  title: { key: 'title', label: '开场', note: '标题卡 · 交代主题' },
  demo: { key: 'demo', label: '演示', note: '主体内容 · 可循环图片帧' },
  freeze: { key: 'freeze', label: '定格', note: '画面停住 · 讲解细节' },
  outro: { key: 'outro', label: '收尾', note: '结束卡 · 总结' }
};

累加函数是全模块的核心:

/* 逐段累加出绝对区间;帧号按 fps 取整,避免报告里出现 12.999 帧 */
function toTimeline(segments, fps) {
  var f = Math.max(1, Math.round(Number(fps) || 30));
  var list = Array.isArray(segments) ? segments : [];
  var out = [];
  var acc = 0;
  list.forEach(function (s, i) {
    var sec = Math.max(0, Number(s && s.seconds) || 0);
    var start = acc;
    var end = Math.round((acc + sec) * 1000) / 1000;
    out.push({
      id: (s && s.id) || ('sg-' + pad3(i + 1)),
      kind: (s && KINDS[s.kind]) ? s.kind : 'demo',
      name: String((s && s.name) || ('第 ' + (i + 1) + ' 段')),
      start: start,
      end: end,
      seconds: sec,
      fromFrame: Math.round(start * f),
      toFrame: Math.round(end * f)
    });
    acc = end;
  });
  return out;
}

两个取整层次得分开看。秒级累计时每一步都取到毫秒精度,避免 0.1 加 0.2 那种浮点尾巴一步步放大;帧号则是直接用已经取整过的秒去乘 fps 再四舍五入。如果一个地方用原始秒、另一个地方用取整后的秒,相邻段的 toFrame 与下一段的 fromFrame 就会差一帧,报告里出现「第 2 段结束于第 374 帧、第 3 段开始于第 375 帧」这种看起来像丢了一帧的描述。

边界处理有个专门的分支:

function segmentAt(segments, tSec, fps) {
  var line = toTimeline(segments, fps || 30);
  var t = Math.max(0, Number(tSec) || 0);
  for (var i = 0; i < line.length; i++) {
    if (t >= line[i].start && t < line[i].end) return line[i];
  }
  /* 时长边界:正好等于总时长时归到最后一段,界面不要闪成「无段落」 */
  if (line.length && t >= line[line.length - 1].end) return line[line.length - 1];
  return null;
}

主循环用的是左闭右开区间,所以 t 恰好等于某段 end 时会跑到下一段,这是对的。但 t 恰好等于总时长时没有任何一段接住,于是补一个分支归到最后一段。不补这一行的后果是:录制计时走到 20.000 秒的那一瞬间,面板上的当前段落会闪一下「无段落」,用户会以为时间轴坏了。

示例时间轴与示例场景是成对设计的:

/* 示例时间轴:与 VkScene.sampleScene() 对齐的 4 段共 20 秒,段落边界正好落在图层时间窗上 */
function sampleSegments() {
  return [
    { id: 'sg-001', kind: 'title', name: '开场标题', seconds: 3 },
    { id: 'sg-002', kind: 'demo', name: '主体演示', seconds: 10 },
    { id: 'sg-003', kind: 'freeze', name: '定格放大', seconds: 4 },
    { id: 'sg-004', kind: 'outro', name: '收尾', seconds: 3 }
  ];
}

3 + 10 + 4 + 3 正好是 20 秒,与 sampleScene 里的 seconds 为 20 一致,也与截图面板上的总时长 20 秒、总帧数 600 一致。段落边界落在 3 秒、13 秒、17 秒,而示例场景里三类图层的 from/to 分别是 3 到 13、3 到 13、13 到 17——边界完全重合,所以一键载入示例之后,前半段看到的是文字块与强调框,中段看到图片帧,后段看到放大镜,时间轴与图层时间窗是同一条线。

编号规则和时间轴外的图层用同一套思想,但标记点用了 0.25 秒的容差匹配:

function markAt(marks, tSec, tolerance) {
  var tol = Math.max(0.01, Number(tolerance) || 0.25);
  var t = Number(tSec) || 0;
  var best = null;
  (Array.isArray(marks) ? marks : []).forEach(function (m) {
    var d = Math.abs(m.t - t);
    if (d <= tol && (!best || d < Math.abs(best.t - t))) best = m;
  });
  return best;
}

找的是容差范围内最近的那个标记。录制计时每 200 毫秒刷一次,用户按下打点按钮时实际时间不可能恰好等于他看到的那个数字,没有容差就永远匹配不上。选最近而不是第一个命中,是为了避免两个相邻标记都落在容差带里时总选到较早那一个。

时长编辑有硬范围:

segments[i].seconds = Math.max(0.5, Math.min(600, Number(seconds) || 0));

下限 0.5 秒是因为再短的一段在 30fps 下只有 15 帧,开场卡一闪而过反而让人看不清;上限 600 秒与 validate 里「超过 10 分钟,单段太长」的 warn 对应,是一道软提醒而不是硬限制。总时长另有 1 小时的 error 上限,到线就不让开始录制,因为长时间录制的内存与磁盘压力都不可控。

3.5 讲解标记的几何全部从数据算出

vk-mark.js 的头注释写得最直接:

 * 点击涟潪、放大镜、按键浮层三样东西的尺寸都必须能从数据算出来,
 * 否则录制时「画上去的东西」和报告里「承诸画了什么」会对不上。
 *
 * 这里的函数全部只吃数字与字符串、只吐数字与字符串,画的部分留给 renderer。

点击涟潪用三次缓出:

/* 点击涟潪:三次缓出,前段扩得快、收尾慢,视觉上才像水波 */
function ripple(elapsedMs, durationMs, maxRadius) {
  var d = Math.max(1, Number(durationMs) || 600);
  var e = Math.max(0, Number(elapsedMs) || 0);
  var max = Math.max(1, Number(maxRadius) || 40);
  if (e >= d) return { active: false, r: max, alpha: 0, progress: 1 };
  var p = e / d;
  var eased = 1 - Math.pow(1 - p, 3);
  return { active: true, r: r2(max * eased), alpha: r2(1 - p), progress: r2(p) };
}

缓出曲线选 1 减三分之一次幕而不是线性,因为水波的手感是「一出来就扩散得很快、尾巴拖得很长」。线性扩出的圆看起来像匀速推开的机械圆环。透明度则用另一条更简单的直线 1 减 p,因为透明度是线性变化时视觉上反而最自然。两个量用两条不同曲线,比强行用同一条曲线再调参数要好解释。

半径与透明度都是 r2 保留两位,避免把 12.3456789 这种浮点数一路送到绘制与报告里。超过时长时返回 active 为 false、半径为满值、透明度为 0,调用方只需判断 active 就能决定还要不要画。

放大镜的源框是按倍率反推出来的:

/* 放大镜:目标框大小固定,源框按倍率反推,并夹在画面内 */
function loupeRect(cx, cy, boxW, boxH, zoom, canvasW, canvasH) {
  var z = clamp(zoom, 1.2, 8);
  var W = Math.max(1, Number(canvasW) || 1);
  var H = Math.max(1, Number(canvasH) || 1);
  var sw = Math.min(W, Math.max(8, (Number(boxW) || 160) / z));
  var sh = Math.min(H, Math.max(8, (Number(boxH) || 160) / z));
  var sx = clamp((Number(cx) || 0) - sw / 2, 0, Math.max(0, W - sw));
  var sy = clamp((Number(cy) || 0) - sh / 2, 0, Math.max(0, H - sh));
  return { sx: r2(sx), sy: r2(sy), sw: r2(sw), sh: r2(sh), zoom: r2(z) };
}

接口的方向很关键:传入的是绘制目标框的大小,算出的是采样源框的大小。目标框固定、源框按倍率除,这样放大镜在画布上的尺寸不随倍率变,只有里面的内容变精细。反过来写——固定源框、目标框乘倍率——放大镜就会在 8 倍时比整个画面还大。

四个夹取各有原因:倍率夹在 1.2 到 8,低于 1.2 看不出放大效果、高于 8 像素化严重;源框宽高同样夹下限 8 像素,否则高倍率下会小于一个像素;左上角夹在 0 到 W 减 sw,保证源框不会超出画布右侧。最后这一个夹取如果漏了,高倍率下源框会读到画布外面,画出来是一片黑。

按键浮层的字号是二分出来的:

/* 字符宽度按 em 估算:中文与全角符号算 1,其余算 0.56,够用来折行 */
function charEm(ch) {
  return /[\u1100-\u11ff\u2e80-\u9fff\uac00-\ud7af\uff00-\uffef]/.test(ch) ? 1 : 0.56;
}

四个区间分别是韩文字母、中日韩统一表意文字扩展区起步段与部首、韩文音节、全角符号。它们按一个 em 宽计算,其余字符按 0.56 个 em。这个估算不追求与真实字形宽度一致,只要求「能用来折行」——折行时偏保守一点,实际排版时反而不会溢出。

/* 二分找「能塞进框里的最大字号」;塞不下就退到最小字号并截断行数 */
function keyLayout(text, boxW, boxH) {
  var s = String(text == null ? '' : text);
  var W = Math.max(1, Number(boxW) || 0);
  var H = Math.max(1, Number(boxH) || 0);
  if (!s.trim()) return { text: '', fontSize: 0, lineHeight: 0, lines: [], fits: false };
  var lo = 6;
  var hi = Math.max(6, Math.min(H / 1.5, W / 3));
  var best = null;
  for (var i = 0; i < 16 && hi - lo > 0.4; i++) {
    var mid = (lo + hi) / 2;
    var lines = wrap(s, mid, W * 0.94);
    var lh = mid * 1.35;
    if (lines.length * lh <= H * 0.94) { best = { size: mid, lines: lines, lh: lh }; lo = mid; }
    else hi = mid;
  }

三处细节值得单拎出来。一是上界的取法:min(H / 1.5, W / 3),前者保证即使只有一行也能塞进高度(行高是字号的 1.35,1.5 留了点余量),后者保证至少能排三个字,否则单个超宽字符就能把行撑爆。二是 0.94 这个内边距系数,框的宽和高各留 6% 做边距,避开边框线。三是循环条件里的 16 次与 0.4 像素双重停止,前者防死循环,后者保证精度——差不到半个像素时再二分也没有意义。

二分失败时走兜底:直接取最小字号 6,算出能排几行就截几行,并把 fits 置为 false。界面可以据此把这段文字标记成「未完整显示」,而不是默默截掉一半且不作声。

图层淡入淡出是另一组纯函数:

/* 图层淡入淡出:from/to 为 0 表示不限制,两端各留 fadeSec 做过渡 */
function fade(tSec, fromSec, toSec, fadeSec) {
  var t = Number(tSec) || 0;
  var from = Number(fromSec) || 0;
  var to = Number(toSec) || 0;
  var f = Math.max(0, Number(fadeSec) || 0);
  if (!f) {
    if (from && t < from) return 0;
    if (to && t > to) return 0;
    return 1;
  }
  var a = 1;
  if (from) {
    if (t < from) return 0;
    if (t < from + f) a = Math.min(a, (t - from) / f);
  }
  if (to) {
    if (t > to) return 0;
    if (t > to - f) a = Math.min(a, (to - t) / f);
  }
  return r2(clamp(a, 0, 1));
}

两端用 Math.min 取小而不是直接覆写。一个图层的时间窗完全可能比两倍淡入时长还短(比如 from 为 3、to 为 3.5、fade 为 0.45),此时渐进段与渐出段会重叠,取小得到的是一个三角形包络,直接覆写的后果是后一个分支把前一个分支算出来的结果跳过去,画面上表现为亮度突变。

光标轨迹插值则是另一类:

/* 光标轨迹插值:points 按 t 升序,超出两端就取端点 */
function cursorAt(points, tSec) {
  var list = Array.isArray(points) ? points : [];
  if (!list.length) return null;
  var t = Number(tSec) || 0;
  if (t <= Number(list[0].t)) return { x: Number(list[0].x) || 0, y: Number(list[0].y) || 0 };
  ...

两端外推取端点而不是报错或返回 null,因为用户在录制开始前就开始移动光标是常态,此时时间还在第一个点之前。返回端点让光标停在第一点上等待,比直接消失更符合直觉。

3.6 三格式报告与一份外部录制计划

vk-report.js 把存在的理由写在了文件头:

 * 一份报告要能回答三个问题:录了什么、按什么参数录的、哪些事本壳做不到。
 * 所以三种格式都从同一个 ctx 取数,不各自拼字符串——否则 UI 显示的和导出的会互相打脸。

三种格式:

var FORMATS = [
  { key: 'json', ext: 'json', label: 'JSON', note: '全量结构化数据,便于二次处理' },
  { key: 'markdown', ext: 'md', label: 'Markdown', note: '直接贴进文档的表格版' },
  { key: 'csv', ext: 'csv', label: 'CSV', note: '只含时间轴段落,可进表格软件' }
];

三者共享一个 collect 函数,返回一份形状固定的对象,包含 env、plan、scene、timeline、segments、marks、session、limits 八块。toJson 直接序列化,toMarkdown 逐节拼表格,toCsv 只抽时间轴。三份输出的字段名与含义完全一致,因为源头只有一个。

两个转义函数虽小但都在关键位置:

function csvCell(v) {
  var s = String(v == null ? '' : v);
  if (/[",\r\n]/.test(s)) return '"' + s.replace(/"/g, '""') + '"';
  return s;
}

function mdCell(v) {
  return String(v == null ? '' : v).replace(/\|/g, '\\|').replace(/\r?\n/g, ' ');
}

CSV 里含有逗号或换行的单元格必须用双引号包起来,内部的引号翻倍。Markdown 表格里竖线会把单元格切断,换行会让表格彻底错位,所以一个转义成竖线前加反斜杠、一个换成空格。这两种恶心的字符在用户输入里非常常见:段落名可以直接手填,一个「开场标题 | 第一版」就能把整张表拆掉。

Markdown 报告一共六节:录制计划、录制结果、时间轴、场景图层、标记点、能力边界。其中「录制结果」在本次没有产出文件时不是留空,而是明确写一行「本次没有产出录制文件」。空表格与「没录过」是两件事,前者看起来像数据丢失。

时间轴的渲染把每个字段都原样列出来,包括帧区间:

lines.push(rowsOfTable(['#', '段落', '类型', '开始', '结束', '时长', '帧区间'], d.timeline.map(function (s) {
  return [s.id, s.name, s.kind, s.start + 's', s.end + 's', s.seconds + 's', s.fromFrame + '–' + s.toFrame];
})));

帧区间是这一列存在的意义。小时长的秒数只到小数点后两位,用帧号才能精确地对上录制文件里的具体某一帧。这一列的数据直接来自 3.4 节 toTimeline 里取整过的 fromFrame 与 toFrame,不存在第二套换算。

层图那一行的三向子表达式有个隐形的排序问题:

return [
  String(l.index), l.name, l.type, l.visible ? '是' : '否',
  Math.round((r.x || 0) * 100) + '%/' + Math.round((r.y || 0) * 100) + '% ' + Math.round((r.w || 0) * 100) + '×' + Math.round((r.h || 0) * 100) + '%',
  (l.from || l.to) ? (l.from + '–' + (l.to || '∞')) + 's' : '全程'
];

时间窗那一列只有在 from 与 to 都是 0 时才写「全程」,其余情况都写出区间;to 为 0 而 from 不为 0 时用无穷符号补上。这与 inWindow 里「两个都为 0 才算全程」的判定一致,不会出现报告说全程、实际只在后半段可见的偏差。

报告里的能力边界是四条,与 app:info 里那四条是同一件事的两次表述,措辞不同但含义一致。两处分开写的问题在于:将来如果适配层补上了桌面捕获,需要同时改两处,漏一处就会出现「界面说不出支持、报告里还写着做不到」的差额。这是 4.1 节缺陷台账里的一条。

最后是那份外部录制计划:

/* 只用于给「外部录制」写计划:x11grab 采集桌面 + pulse 采音频,输出 mp4 */
function ffmpegCommand(p, opts) {
  var o = opts || {};
  var display = String(o.display || ':0.0');
  var ox = Math.max(0, Math.round(Number(o.offsetX) || 0));
  var oy = Math.max(0, Math.round(Number(o.offsetY) || 0));
  var out = U.slug(o.outName || 'vokoscreen-capture') + '.mp4';
  var audio = o.audio !== false;
  var lines = [];
  lines.push('ffmpeg -hide_banner -y \\');
  lines.push('  -f x11grab -framerate ' + p.fps + ' -video_size ' + p.width + 'x' + p.height + ' -i ' + display + '+' + ox + ',' + oy + ' \\');
  if (audio) lines.push('  -f pulse -i default \\');
  lines.push('  -t ' + p.seconds + ' \\');
  lines.push('  -c:v libx264 -preset veryfast -b:v ' + p.kbps + 'k -pix_fmt yuv420p -movflags +faststart \\');
  if (audio) lines.push('  -c:a aac -b:a 160k \\');
  lines.push('  ' + out);
  return lines.join('\n');
}

产出的是一段可以直接粘到终端执行的命令串:x11grab 采集指定显示器与偏移区域、pulse 采默认音频设备、libx264 编码、yuv420p 像素格式保证播放器兼容、faststart 把索引移到文件头以便边下边播。码率参数用的就是本壳计划里算出来的 p.kbps,所以「壳内录不了、换到桌面端用 ffmpeg 录」时,体积估算依然成立。

vk-plan 的文件头把这段代码的定位说得很清楚:它是一份可执行的外部录制计划,本壳不会去调用它,也不假装调用了。界面上它是可复制的一段文本,不是「一键录制」按钮。工程里也确实没有任何 child_process 调用——一个按钮背后是否真的执行了命令,靠的不是口头承诺,而是 import 列表里有没有它。

四、鸿蒙稳定性适配

4.1 缺陷台账

对全部 11 个文件逐个扫描之后,找到四处值得记录的问题。它们都不是崩溃级缺陷,但都属于「当下能跑、换个条件就出事」那一类。

D1 能力边界写了两份,措辞不同

main.js 的 app:info 里是四条 unsupported,vk-report.js 的 collect 里是另一组四条 limits。两者的前三条说的是同一件事,第四条不一样:app:info 写的是「真实鼠标与键盘事件回放」,报告里写的是「不裁剪系统画面:区域录制只对本壳画布生效」。同一条边界出现两种描述,将来适配层补上其中一项能力时,很容易只改一处,造成界面与导出报告互相矛盾。正确做法是把这四条提到一个单独的模块里,主进程与渲染层都从那里取。

D2 签名材料跟着源码走

build-profile.json5 里的 certpath、profile、storeFile 是本机绝对路径,keyPassword 与 storePassword 是 IDE 在本机密钥环加密后的长串。这三个路径指向开发者个人的用户目录,密码串离开本机就无法解开。别人克隆仓库后执行构建会直接失败在签名阶段,而错误提示不一定会明确指出是路径不存在。

D3 十个导出跨全应用零调用

按「定义一次、导出表键与值各一次、共出现三次就是零调用」的口径扫了一遍,结果如下:

所在模块零调用的导出
vk-markcursorAt、lastPoint、measure
vk-scenehitTest、pxToNorm
vk-timelinemarkAt
vk-utilestimateBytes、frameOf、percent、secondOf

十个。它们的共同点是都能独立手测、都有完整注释、都写得很规矩,就是没人用。hitTest 与 pxToNorm 原本是为画布上点选图层准备的,但实际改成在下方表格里点行选中,两个函数成了残余;markAt 原本是给「录制时自动吸附标记」准备的,实际录制时只在手动打点;estimateBytes 的活已经由 vk-plan 里的 plan 函数用同样的公式算完了。

这些函数本身没有错,错的是它们的注释还在描述一个不存在的功能。下次有人要给画布加点击选层,会先看到 hitTest 已经写好了,然后把一个从未验证过的函数直接接上去。

D4 内容安全策略管不到 Node 的出网口

connect-src 写的是 none,看起来像是说这个应用不可能联网。但在 nodeIntegration 为 true、contextIsolation 为 false 的配置下,渲染层里 require(‘https’) 是能直接用的,而 CSP 约束的是浏览器层的 fetch、XHR、WebSocket,完全约束不到 Node 的原生模块。一个真实的做法是:CSP 只能是底线,让渲染层拿不到 fs 与网络模块。

4.2 三个典型根因

根因一:把「当前能跑」当成「随时能跑」

签名材料、图片路径、方言字段这些「现在就是能用」的东西,往往是在 IDE 自动生成时顺手带上的。它们在开发者本机永远是对的,而仓库的目标读者恰好不是这台机器。判定一件事该不该进仓库的简单标准是:换个用户目录还能不能跑。不能,就应该进环境变量或 CI 秘密。

根因二:复制描述,而不是引用源头

D1 与 D4 是同一个毛病的两个面。一条信息如果存两份,就迟早会出现只改一份的情况,而漏改的那一份往往恰是用户看得到的那一份。内容安全策略也是同一个道理:它写在页面里,看起来与运行环境无关,实际上它约束什么完全取决于窗口的 webPreferences。两份声明必须一起读才有意义。

根因三:纯函数模块的导出表只增不减

六个引擎都是 UMD 双出口,每个都把内部函数全量列进 return 对象。这在开发期很方便:想用什么直接从全局取。但它也意味着一个函数被写完之后就没有任何机制会提醒你它没人用——没有 tree-shaking,没有 lint 的 no-unused-exports 规则,没有测试覆盖率报告。一年后扫一遍,十个零调用函数安安静静地躺在那里。

4.3 样式表禁项与 1120px 断点

vokoscreen.css 的开头并不是 :root,而是一段约束声明:

/* Vokoscreen 录制工作台 —— 样式
 * 鸿蒙渲染层约束:不用固定定位、不用关键帧动画与过渡、不做位移缩放与大写转换;
 * 颜色一律走 :root 变量,主题只改一处,静态校验也能拦住绕过变量的裸色值。
 * 录制画布与时间轴都用 canvas 画,避免为了「按比例铺开」去改元素 style。
 */

这份声明是可验证的。全文 730 行里:position 为 fixed 的出现 0 次,transition 0 次,animation 0 次,@keyframes 0 次,!important 0 次,transform 0 次。六项禁项一项没破。

:root 里定义了 21 个变量,其中 20 个是本壳的色阶,从 --bg 到 --info,每个主色都配了一个 dim 版本;另一个是 --mono 字体栈。把所有色值收到一个地方的好处是主题可改,而且静态检查可以直接扫「有没有裸色值绕过变量」。

断点只有一个,在 L628:

@media (max-width: 1120px) {
  #body { grid-template-columns: 172px 1fr; }
  .tb-sub { display: none; }
}

两件事:侧栏从默认宽度收到 172px,顶栏里品牌名后面的副标题直接隐藏。连 2.2 节的字体放大上限 1.45 一起看,这个断点的位置是有依据的:在 1120px 以下同时叠上 1.45 倍字体,三个面板并排已经排不开,不如让侧栏先让位。

为什么整个界面不需要 position 为 fixed 和 transform:因为需要按比例缩放的两个东西——录制画布和时间轴——都不是 DOM 元素,而是 canvas 自己按像素重绘。用 CSS 去拉伸一个 canvas 会让录制出来的像素糊成一片,而这个壳里录的恰好就是 canvas。这一道约束不是平台限制,是业务自己给自己加的。

4.4 上架前必须替换的四类内容

第一类:应用身份。 bundleName 是 com.huawei.ohos_electron,vendor 是 example,versionName 是 1.0.0,三项全是模板默认值。这三项一旦上架就无法回头改,尤其 bundleName——它直接决定应用在设备上的身份。

第二类:签名三件套。 由 D2 那一项直接得出:certpath、profile、storeFile 要改成构建流水线注入,两个 password 字段要改成不落在仓库里的形式。

第三类:权限清单里的 17 条裸权限。 web_engine 的 28 条权限里有 11 条配了 reason 与 usedScene,剩下 17 条只有名字。这 17 条里有些对录制工具根本用不上(如 GYROSCOPE、ACCELEROMETER、ACCESS_BIOMETRIC、PRINT),有些是本壳真的需要(如 FILE_ACCESS_PERSIST、READ_WRITE_DOCUMENTS_DIRECTORY)。上架前应该把用不到的删掉,而不是因为模板里有就留着——权限越多,审阅时被追问的面越大。

第四类:关于对话框里的三段声明。 截图里可以看到弹窗里三段文字:开源声明、免责声明、完全开源(Apache-2.0)。开源声明里已经写得很实在:「全部代码使用 JavaScript 独立编写,不包含上游任何源代码」,并且把五大功能逐条列出。这一段应该与实际功能逐项对得上,将来添了功能就要同步改,否则又是一处两份描述。

五、构建与部署

在这里插入图片描述

图 1 场景面板与关于对话框:顶栏是工程与录制的七个按钮,侧栏固定六项工作面板,底部四行显示分辨率、帧率、图层数与成品状态

在这里插入图片描述

图 2 录制面板:左侧是 1280×720 的预览画布,右侧是分辨率、帧率、质量档、时长与倒计时五组参数,下方九格统计把码率、体积、帧数、宽高比一次列尽

在这里插入图片描述

图 3 场景面板:四个图层逐行列出显示状态、名称、类型、区域与时间窗,下方是图层编辑区

5.1 产物与构建日志

构建产物两份,在 electron 模块的 outputs 目录下:

产物字节数
electron-default-signed.hap195368509
electron-default-unsigned.hap193906909
签名带来的增量1461600

签名前后相差 1461600 字节,这部分是签名块与证书链。整个壳应用的业务代码只有 178586 字节,占 signed 包体不到千分之一——剩下百分之九十多全是原生运行时。这个比例本身就是 Electron 壳方案的标准画像。

构建日志在 .hvigor/outputs/build-logs/build.log,1250424 字节、14756 行。全文扫描结果:BUILD SUCCESSFUL 出现 8 次,BUILD FAILED 0 次,ArkTS:WARN 2723 条。八次成功构建的耗时依次是 3s841、4s248、4s212、4s420、3s976、4s6、4s26、21s306。

前七次全部落在 4 秒左右,第八次跳到 21 秒。这个跳变不是偶发:前七次的时间戳集中在同一天下午 15 点 30 分到 15 点 43 分,第八次是次日 15 点 03 分。跨天后的首次构建走了完整增量链与缓存重建,后续再改就回到 4 秒级别。这也说明增量构建确实在工作,改一个 js 文件不必等二十秒。

2723 条 ArkTS 警告全部来自壳工程自带的 ArkTS 代码,不是业务代码——本项目的渲染层是纯 JavaScript,不参与 ArkTS 编译。这些警告没有一条被当作错误,也没必要逐条清掉。

5.2 体积构成

产物体积的百分之八十九点一集中在四份原生库上:

原生库字节数占 signed 比例
libelectron.so16747191285.72%
libadapter.so26212001.34%
libffmpeg.so21815281.12%
libc++_shared.so18256240.93%
四份合计17410026489.11%

libelectron.so 在剥离前是 1143668440 字节,剥离后 167471912 字节,减掉了 976196528 字节,也就是九百多兆的调试符号。仓库根目录下的 lib.unstripped 里放着同样两份带符号的 so,需要定位原生层问题时,把符号表对回去就能恢复调用栈。

collectAllLibs 为 true 是这四份库全部上包的直接原因。如果只面向一种架构,产物可以小掉一片;但 deviceTypes 同时声明了 2in1 与 tablet,两种形态的架构并不保证一致,只挑一种就会出现「一半设备装不上」。取舍很清楚:接受九十多兆的包体,换全设备可装。

5.3 权限清单与设备形态

web_engine 的 module.json5 里 requestPermissions 一共 28 条,其中 11 条带 reason 与 usedScene,17 条只有名字。definePermissions 里自定义了一条 LOCK_WINDOW_CURSOR。

28 条权限里,对这个录制工作台真正用得上的是少数:FILE_ACCESS_PERSIST 支撑目录授权记忆,三条 READ_WRITE 目录权限支撑工程与录制文件的读写,READ_PASTEBOARD 支撑剪贴板粘贴。剩下的要么是壳模板为了兼容多种 Electron 应用而带的,要么是 Web 容器需要的(INTERNET、GET_NETWORK_INFO、ACCESS_CERT_MANAGER)。

值得单独一提的是 MICROPHONE 与 CUSTOM_SCREEN_CAPTURE 这两条:它们都在权限清单里,但应用本身不录声音也不抓屏,1.1 节的能力边界已经明确否定了这两件事。上架时这两条很容易被审阅追问「你声明了却没使用」,而应对起来最省事的做法是先把它们删掉。

设备形态上,两个模块都只声明了 2in1 与 tablet,没有 phone。三个 ability 里两个跑在 :browser 进程,入口那个跑在主进程,扩展 ability 里一个是状态栏图标位,一个是内嵌 UI。

部署流程与其他同签工程一致:用 DevEco 连上设备,产物是 debug-file 模式构建出的 signed 包,装完直接拉起。四秒级别的增量构建让「改一行、装一次」这个循环完全能接受。

六、常见问题与解决方案

Q1 录完的文件用播放器打不开,或者只有最后一秒的画面?

问题现象:录制流程看起来一切正常,状态栏的字节数在涨,停止后拿到的文件却只有几十 KB,播放器提示文件损坏或者只能放最后一下。

根因分析:分片写盘的关键在 fs.writeSync 的第五个参数。如果每次写分片前都用 ‘w’ 重新打开文件,或者给 writeSync 传了一个固定位置,那么每一片都会从文件头开始覆盖,最后留在磁盘上的只有最后一片。前者在文件系统层面表现为长度不变,后者表现为内容被反复覆盖。

解决方案:begin 里 openSync 用 ‘w’ 打开一次、把 fd 存在 recSession 里,后续所有 chunk 都拿同一个 fd 写,writeSync 的第五个参数传 null 表示从当前位置继续。end 时 closeSync 并把 recSession 置空,保证下一个 begin 拿到的是一张干净的桌子。

教训:「追加写」在 Node 里不是一个独立的 API,而是 openSync 模式与 write 位置两个参数的组合。这两个地方任何一处写错,都不会报错,只会静静地给出一个看起来像文件的东西。

Q2 点开始录制后弹了错误,但其实我只是取消了保存框?

问题现象:打开保存对话框后点取消,状态栏跳出一条红色错误,看起来像是录制失败了。

根因分析:保存对话框返回的取消不是一个错误,它是用户的正常选择。如果主进程把取消当成异常抛出,渲染层的统一错误处理会把它当作失败处理,于是取消也会变成一条红字。

解决方案:rec:begin 在 dialog.showSaveDialog 返回后先判 r.canceled,直接 return { success: false, canceled: true },不带 error 字段。渲染层判断顺序是先看 canceled、再看 success,取消就回到 idle 状态并给一句轻描淡写的提示。

教训:「失败」和「没做」是两种状态,用一个布尔量或一个字段同时表达两者,一定会把用户的主动选择当成系统的锅。

Q3 录到二十分钟左右整个界面卡死或直接白屏?

问题现象:短录制一切正常,录到十几二十分钟后界面开始卡顿,最后渲染进程直接崩掉,录制文件只保存了一部分。

根因分析:内存峰值不在最终文件大小,而在传输形态。如果布局是「先把所有分片存在数组里,停止后拼成一个 Blob 再转 base64 传给主进程」,那么峰值内存是视频体积的八到九倍:base64 膨胀三分之一、字符串按字符计数再翻倍、拼接时新旧两份短暂共存。

解决方案:每秒一片、写完就丢。ondataavailable 触发时只持有当前这一片,转完 base64、发完 IPC 就把引用释放。主进程那边同样不缓存,收到就 writeSync。两边的峰值都稳定在单片大小。另加两道闸门:单片 8 MB、累计 512 MB,到线就立即收尾并提示分段录制。

教训:处理大流量数据时,要问的不是「总量多大」,而是「同时活着多少」。前者决定磁盘占用,后者决定会不会崩。

Q4 预览里看到的样子,录下来之后不一样?

问题现象:预览画布上图层位置都正常,录出来的 WebM 里文字偏了、图标大小不对。

根因分析:预览和录制各写了一套绘制函数,两套代码在字号估算、内边距、圆角这类细节上一点点分岔,分岔会累积。这类 bug 排查起来特别难受,因为它只在静止时对准帧对比才能看出来。

解决方案:渲染层只有一份 drawScene(),它只接收一个 canvas 与一个时间点,与「这个 canvas 是预览还是录制源」完全无关。预览定时器调它,录制时录的也是同一个画布。控件里想加什么新效果,只有一条路:改 drawScene,预览与录制同时生效。

教训:两份实现只要存在,就一定会在某个时间点上不一致。与其事后比对,不如从一开始就让第二份不存在。

Q5 同一份工程从 720p 改成 1080p 之后,图层全部跑位了?

问题现象:在 1280×720 下调好的布局,把分辨率改成 1920×1080 后,水印跑到画面中间、文字块被截断。

根因分析:如果图层位置存的是像素坐标,那么它只对当初那个分辨率成立。换分辨率后,一个原本在右下角、坐标为 x 等于 1100 的水印,在 1280 宽的画面里还在右侧,到了 1920 宽的画面里就跑到中间去了。

解决方案:所有图层坐标一律存 0…1 的归一化值,只在绘制前一步用 normToPx 乘上当前画布尺寸。这样布局在任何分辨率下都保持相同的相对位置,且取整只发生一次,不会因为反复换算而逸出。

教训:凡是「会随容器尺寸变的东西」,存的比例比存的绝对量更安全。分辨率、窗口大小、字号缩放都适用这条。

Q6 把第二段时长从 10 秒改成 15 秒之后,后面的段落全乱了?

问题现象:时间轴上改一段的时长,后面所有段的开始时间没跟着一起变,或者一部分变了另一部分没变。

根因分析:数据结构里存了绝对起止时间。改一段就相当于一次性要改后面所有段,而只要有一个地方没被通知到(一份缓存、一个已经渲染的行、一份已经取好数的报告),就会有一处还在用旧时间。

解决方案:只存每段秒数,绝对区间每次现算。toTimeline 逐段累加,每次读时间轴都重新算一遍。这个函数的代价是 O(n),而段数由用户手动维护,实际不会超过几十段。

教训:派生数据不该存。能现算的东西存下来,省下的是一点点 CPU,付出的是无穷无尽的一致性问题。

Q7 真机上点任何按钮都没反应,也没有任何报错?

问题现象:开发机上一切正常,装到真机上后界面能显示、按钮全部无响应,从 DevTools 也看不到任何信息,因为真机上根本没有 DevTools。

根因分析:脚本在文件顶层抛了异常,整个 IIFE 一个字都没执行,于是所有事件绑定与首次渲染全部没发生。界面看起来完整,是因为 HTML 本身就是完整的;按钮没反应,是因为监听器从未被绑上。而且这类异常发生在脚本加载阶段,默认不会写进任何用户可见的地方。

解决方案:在 renderer.js 的第一段就挂上全局错误监听,把第一条错误直接写到状态栏:

window.addEventListener('error', function (e) {
  var box = document.getElementById('tbStatus');
  if (!box) return;
  box.textContent = '脚本异常:' + String((e && e.message) || '未知错误');
  box.className = 'tb-state err';
});

一段不到十行的代码,把「静默失灵」变成「一眼就看到哪一行抛了」。不依赖控制台,不依赖日志文件,也不需要用户配合复现。

教训:没有控制台的环境必须自己造一个出口。全局错误监听是成本最低的那一个,应该在写第一行业务代码之前就挂上。

七、总结

这个项目最终交付的是一套壳内录制工作台:

能力实现位置说明
帧合成renderer.js 的 drawScene预览与录制共用同一份绘制
WebM 编码canvas.captureStream 加 MediaRecorder三档编码器依次探测
分片落盘main.js 的 rec:begin / chunk / end / abort十三通道里的四个
场景图层vk-scene.js七类图层、0…1 归一化坐标
时间轴vk-timeline.js四种段落、只存时长
讲解标记vk-mark.js涟漪、放大镜、按键浮层的几何
计划与码率vk-plan.js 加 vk-util.jsbpp 建模、不查表
报告导出vk-report.jsJSON / Markdown / CSV 三格式
外部录制计划vk-plan.js 的 ffmpegCommand只产出命令串,不执行
能力边界main.js 的 app:info四条 unsupported

第一,把「录什么」从桌面收窄到画布,反而得到了可验证性。录桌面时,场景描述与像素之间没有可校验的关系;录画布时,每一帧都能从数据算出来,报告里的图层、时间窗、不透明度才能和录下来的东西一一对应。这是把限制转成优势的那一步。

第二,分片不是为了快,是为了内存峰值可控。同样一段二十分钟的录制,攒到最后一起传与每秒一片顺序写,最终文件大小完全一样,差别全在内存曲线上:前者是一条上跑的直线,后者是一条平线。很多「长录制必崩」的问题,换成这个角度重新看就变得很简单。

第三,一个数字只应该有一个源头。码率来自 bpp 公式,预览与录制来自 drawScene,面板上的区域文字来自 describe,报告里的帧区间来自 toTimeline。只要源头唯一,界面、录到的视频、导出的报告三者就不可能在用户面前互相打脸。

上架前必须做完四件事:把 bundleName、vendor、versionName 从模板默认值换成真实信息;把签名三件套从本机绝对路径改成流水线注入;把 28 条权限里用不到的(至少 MICROPHONE 与 CUSTOM_SCREEN_CAPTURE)删掉并给保留下来的补齐 reason;把能力边界的两处描述合并成一处,顺便确认关于对话框里的声明与实际功能逐条对得上。

Logo

作为“人工智能6S店”的官方数字引擎,为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐