huashu-art-motion 字体许可清单解读:OFL 1.1、子集化与缺字校验的完整实践
huashu-art-motion 字体许可清单解读:OFL 1.1、子集化与缺字校验的完整实践
本篇技术指南以 scripts/engine/lib/fonts/LICENSES.md 为核心骨架,逐条拆解 huashu-art-motion 仓库内置字体集的许可边界(SIL Open Font License 1.1 的可商用、可再分发与 Reserved Font Name 限制),并结合 scripts/font_subset.py、scripts/engine/lib/fonts.js 与 scripts/engine/lib/util.js 的源码实现,说明子集字体是如何生成、注册并被引擎做缺字校验的。读完你将掌握:这份字体目录为什么不受仓库 MIT 授权覆盖、每一款字体的版权归属与来源、以及新增或替换字体时完整的"子集化—注册—校验"工作流。
1. 为什么字体目录单独维护一份许可清单
huashu-art-motion 仓库整体采用 MIT 许可,但 scripts/engine/lib/fonts/ 目录下的字体文件不属于仓库的 MIT 授权——这是 LICENSES.md 开头第一条声明的内容。每个字体文件各自沿用其原始许可证,本仓库统一收敛为 SIL Open Font License 1.1(全文见同目录 OFL.txt)。
对使用者而言,OFL 1.1 意味着以下权利与边界:
- 可以随软件再分发:字体可以打包、嵌入、随软件(包括商业软件)一起分发,也可以在软件中随附售卖;
- 可以商用:用字体渲染的动画、海报、视频等作品不受限制,OFL 明确"对使用该字体或衍生字体创建的任何文档不适用该许可要求";
- 不能单独售卖字体文件:字体本身或其衍生作品不能被当作独立商品出售;
- 衍生作品必须沿用 OFL:修改版、子集版等衍生字体不能被置于其他任何许可之下;
- Reserved Font Name(保留字体名)限制:声明了保留名的字体,其衍生版本不得沿用保留名(详见第 4 节)。
另外值得注意的是:本目录中部分 woff 文件并非原始字体,而是按 GB2312 字符集或按实际用字抽取出的子集,由 scripts/font_subset.py 生成并转成了 woff 格式。子集化是可控再分发行为,但部分字体(如阿里巴巴普惠体)的许可不允许转换拆分后再分发,这正是开源版将中文黑体替换为思源黑体的原因(见第 5 节)。
2. 完整字体清单与版权归属
LICENSES.md 以表格形式逐条登记了本目录全部字体文件的归属信息。为方便检索,下表将其完整继承并补充了文件数量与字重细节:
| 文件 | 字体 | 版权 | 来源 |
|---|---|---|---|
AlfaSlabOne-400.woff |
Alfa Slab One | © 2016 The Alfa Slab One Project Authors,Reserved Font Name "Alfa Slab" | Google Fonts |
Anton-400.woff |
Anton | © 2020 The Anton Project Authors | Google Fonts |
ArchivoBlack-400.woff |
Archivo Black | © 2017 The Archivo Black Project Authors | Google Fonts |
Bangers-400.woff |
Bangers | © 2010 The Bangers Project Authors | Google Fonts |
Caveat-600.woff |
Caveat | © 2014 The Caveat Project Authors | Google Fonts |
Cinzel-400.woff、Cinzel-700.woff |
Cinzel | © 2020 The Cinzel Project Authors | Google Fonts |
CormorantGaramond-500.woff、-500i、-700 |
Cormorant Garamond | © 2015 The Cormorant Project Authors | Google Fonts |
EBGaramond-400.woff、-400i、-600 |
EB Garamond | © 2017 The EB Garamond Project Authors | Google Fonts |
Exo2-800i.woff |
Exo 2 | © 2013 The Exo 2 Project Authors | Google Fonts |
GochiHand-400.woff |
Gochi Hand | © 2011 Huerta Tipográfica,Reserved Font Names "Gochi" and "Gochi Hand" | Google Fonts |
IMFellEnglish-400.woff、-400i |
IM FELL English | © 2007 Igino Marini,Reserved Font Names "IM FELL English Roman/Italic" | Google Fonts |
Inter-var.woff |
Inter | © 2016 The Inter Project Authors | github.com/rsms/inter |
JosefinSans-700.woff |
Josefin Sans | © 2010 The Josefin Sans Project Authors,Reserved Font Name "Josefin Sans" | Google Fonts |
Kalam-700.woff |
Kalam | © 2014 Indian Type Foundry | Google Fonts |
LibreBaskerville-400.woff、-700 |
Libre Baskerville | © 2012 The Libre Baskerville Project Authors | Google Fonts |
LilitaOne-400.woff |
Lilita One | © 2011 Juan Montoreano,Reserved Font Name "Lilita One" | Google Fonts |
Marcellus-400.woff |
Marcellus | © 2012 Brian J. Bonislawsky (Astigmatic),Reserved Font Name "Marcellus" | Google Fonts |
PlayfairDisplay-400i.woff、-700、-700i |
Playfair Display | © 2017 The Playfair Display Project Authors,Reserved Font Name "Playfair Display" | Google Fonts |
Poppins-600.woff、-700、-800 |
Poppins | © 2020 The Poppins Project Authors | Google Fonts |
PressStart2P-400.woff |
Press Start 2P | © 2012 The Press Start 2P Project Authors,Reserved Font Name "Press Start 2P" | Google Fonts |
Righteous-400.woff |
Righteous | © 2011 Brian J. Bonislawsky (Astigmatic),Reserved Font Name "Righteous" | Google Fonts |
RobotoCondensed-var.woff |
Roboto Condensed | © 2011 The Roboto Project Authors | Google Fonts |
Rye-400.woff |
Rye | © 2010 Sorkin Type Co,Reserved Font Name "Rye" | Google Fonts |
UnifrakturMaguntia-400.woff |
UnifrakturMaguntia | © 2010 j. 'mach' wust,© 2009 Peter Wiegel,Reserved Font Name "UnifrakturMaguntia" | Google Fonts |
cmunrm.woff、cmunti.woff |
CMU Serif(Computer Modern Unicode) | Andrey V. Panov,部分字形来自 AMS Blue Sky fonts | CTAN cm-unicode |
LXGWWenKai-500.woff |
霞鹜文楷 LXGW WenKai(子集) | © 2021-2025 LXGW;© 2020 The Klee Project Authors | github.com/lxgw/LxgwWenKai |
NotoSansSC-500/700/800/900.woff |
思源黑体 Noto Sans SC(按字重实例化后的 GB2312 子集;代码里 family 名是 PuHui-*) |
© 2014-2021 Adobe,Reserved Font Name "Source" | Google Fonts |
NotoSansSC-sub.woff |
思源黑体 Noto Sans SC(按用字子集) | © 2014-2021 Adobe,Reserved Font Name "Source" | Google Fonts |
NotoSerifSC-sub.woff |
思源宋体 Noto Serif SC(按用字子集) | © 2017-2024 Adobe | Google Fonts |
NotoSerifJP-600.woff |
Noto Serif JP | © 2017-2024 Adobe | Google Fonts |
从表格可以归纳出本字体集的几个设计意图:拉丁字体多来自 Google Fonts,负责标题、涂鸦、像素、衬线等不同美术风格;cmunrm.woff/cmunti.woff(LaTeX Computer Modern 正斜体)专门服务于 3Blue1Brown 风格的公式画面;中文侧则由霞鹜文楷(白板语法)、思源黑体/宋体(解说语法)承担。
3. 字体注册机制:family 名 = 文件名去扩展名
字体文件放进目录只是第一步,真正被动画引擎使用前,必须先注册。在 scripts/engine/lib/fonts.js 中,每个文件都注册成独立的 CSS FontFace family,命名规则是文件名去掉扩展名,例如 Cinzel-400.woff 对应 Cinzel-400:
window.FONT_FACES = [
{family:'Cinzel-400', url:'lib/fonts/Cinzel-400.woff'},
{family:'Cinzel-700', url:'lib/fonts/Cinzel-700.woff'},
// ...每个文件一条记录
{family:'Inter', url:'lib/fonts/Inter-var.woff', desc:{weight:'100 900'}},
];
关键细节:
- 可变字体通过
desc:{weight:'100 900'}声明字重范围,用法如'600 220px "Inter"',Inter与RobotoCondensed属于这一类; - 中文黑体是"借名"注册:
NotoSansSC-500.woff等四个文件分别注册为PuHui-Medium/Bold/Heavy/Black。原因是作者原稿使用阿里巴巴普惠体 3.0 四个字重,而普惠体的许可不允许转换、拆分后再分发,无法随开源仓库附带;开源版改用思源黑体按字重实例化后的 GB2312 子集,同时保留PuHui-*的 family 名,使得代码中 97 处既有引用无需改动(scripts/engine/lib/fonts.js 注释明确说明); - 子集区分度:
NotoSansSC-sub.woff/NotoSerifSC-sub.woff是按用字抽取的轻量子集,只含 3b1b/发布会/财经三支示范片用到的字,源文件未随仓库附带;换题目缺字时应改用PuHui-*,或下载 Google Fonts 的NotoSansSC[wght].ttf重新做子集。
引擎启动时,scripts/engine/engine.js 与 scripts/engine/clip.js 会遍历 FONT_FACES,逐个 new FontFace(...) 加载并 document.fonts.add(...)。若新增字体未在 FONT_FACES 注册,即便文件存在于目录中也不会被加载。
4. Reserved Font Name:改动版本不能沿用保留名
LICENSES.md 末尾特别强调:带 Reserved Font Name 的字体,改动过的版本不能沿用保留名。这是 OFL 1.1 的核心条款之一——保留名保护字体品牌,防止修改版与原版混淆。
表格中带保留名的拉丁字体(如 Alfa Slab、Gochi Hand、Playfair Display、Press Start 2P、Rye、UnifrakturMaguntia 等)目前内部字体名都是原名,因为它们直接按 Google Fonts 发行的 woff 原样使用,未做字形改动。但如果你要对它们抽子集或改字形,就必须同时改掉 family 名——这正是子集化工作中最容易踩的许可雷区。
而中文侧的情况恰好相反:Noto Sans SC 带保留名 "Source",仓库提供的已经是子集版。从仓库处理方式看,子集版通常不再沿用原保留名(如代码里用 PuHui-*、按用字抽的 NotoSansSC-sub 等自定义名称),以此满足保留名条款。实际改造时建议对照 OFL.txt 第 3 条 "Reserved Font Name" 的定义逐款核对。
5. 子集化脚本:从 ttf 到几十 KB 的 woff
中文字体动辄数 MB,动画引擎在浏览器里逐帧渲染,不可能全量加载。仓库用 scripts/font_subset.py(基于 fonttools 的 subset 模块)把字体抽成小体积 woff。脚本头部注释给出了完整的命令行用法:
uv run scripts/font_subset.py # 重建预置的霞鹜文楷子集(扫 engine/ 下全部 .js 里的中文+内置常用字)
uv run scripts/font_subset.py --scan <代码工程目录> # 把另一个工程里用到的中文也并进来
uv run scripts/font_subset.py --text "皮影戏蓝色时期" # 追加指定文字
uv run scripts/font_subset.py --font path/to/XXX.ttf --out <工程>/lib/fonts/XXX-400.woff --text "..." # 别的字体
uv run scripts/font_subset.py --gb2312 ... # 再并进 GB2312 全部 6763 个汉字(解说片换题目不用每次补字;单字重约 1MB)
uv run scripts/font_subset.py --fix-widths engine/lib/fonts/PuHui-Medium.woff # 只修字宽为 0 的全角空格(普惠体 Medium/Bold 源字体的 bug)
参数含义与实现要点(对应 main() 与各辅助函数):
| 参数 | 作用 | 实现细节 |
|---|---|---|
--font |
指定源 ttf/otf | 默认指向 ~/Library/Fonts/LXGWWenKai-Medium.ttf;文件不存在则退出并提示下载地址 |
--out |
输出 woff 路径 | 默认 engine/lib/fonts/LXGWWenKai-500.woff,自动创建父目录 |
--scan |
额外扫描目录(可多次) | scan() 只提取 JS 字符串字面量里的中文,注释里的中文不算(否则子集会胖 20 倍);同时跳过以 // 开头的行 |
--text |
追加指定文字 | 直接并入字符集合 |
--no-default-scan |
不扫引擎自身 engine/ |
用于只做预置字集的情况 |
--gb2312 |
并入 GB2312 全部 6763 个汉字 | gb2312_l1() 遍历 0xB0–0xF8 × 0xA1–0xFF 双字节区解码得到一级 3755 常用字+二级 3008 次常用字,另并进全角标点 PUNCT |
--fix-widths |
修复模式,不抽子集 | 处理阿里巴巴普惠体 3.0 Medium/Bold 源字体全角空格 U+3000 字宽为 0 的 bug,将其设为与「一」同宽(fix_blank_widths()) |
字符集合的构成(BASE 常量)非常讲究:预置了数字、标点、年代/朝代、常见风格与画种用字("水墨写意工笔山水花鸟…壁窟敦煌莫高佛飞天供养…"),以及风格相关的艺术家名("八大山人齐白石克里姆特蒙克呐喊草间弥生…莫奈睡莲马蒂斯…")。这些字覆盖了 35 种艺术风格场景的高频文案,子集因此能保持很小(几十 KB)。此外脚本总会带上全部 ASCII(range(0x20, 0x7F)),用于年份数字与英文副标题。
生成过程还包含两道保护:
- 抽取前检查源字体 cmap,报告源字体里没有的字符(
miss),避免静默缺字; - 若源字体全角空格字宽为 0,自动修复后提示。
输出时打印字数与体积:{out} {len(chars)} 字 {size//1024} KB,便于核对子集大小。
6. 引擎侧缺字校验:为什么"缺字会静默回退"是个坑
子集化带来的最大风险是缺字。浏览器在字体缺字时会静默回退到系统字体:measureText 不报错、宽度看起来也对,但换一台机器渲染结果就变了。仓库在 scripts/engine/lib/util.js 注释中明确记录:迁移测试 B、D 都踩过这个坑(全角字母、「▶」、「戏」「蓝」等字符缺失)。
因此引擎不依赖 measureText 对比(实测在 macOS Chromium 上逐字回退会落到不同字体,误判率高),而是采用更底层的做法:
- 启动时读取每个字体文件的 cmap 表(
U.loadCmaps):WOFF1 用DecompressionStream('deflate')解压 zlib 数据,解析 format 4 / 12 / 13 / 0 / 6 五种 cmap 子表,把所有存在的码点收进一个Set; - 按需断言(
U.assertGlyphs(font, text, where)):检查指定文本的每个字符是否在 cmap 中,缺字即console.error; - 集成到 QA 链路:engine.js 启动时会对每个片段的角标文本、年份(含
BCAD后缀)自动断言;自绘角标的字在scene.init里由业务代码自行断言。而 scripts/qa.py 会把页面上的console.error当作失败处理(qa.md记录页面报错),缺字因此会被 QA 拦截,不会带着"换台机器就变样"的隐患交付。
于是形成完整闭环:画面要用的字必须真的在子集里——缺了就用 scripts/font_subset.py --text 补进子集,或改用路径自画;改完子集后重新注册、跑 QA 验证。这也解释了 LICENSES.md 中"部分文件是按 GB2312 或按用字抽出的子集"这句话背后的工程约束。
7. 给二次开发者的实践清单
综合许可清单与源码实现,当你往这个仓库新增或替换字体时,建议按以下顺序操作:
- 确认许可:新字体必须是 OFL 1.1(或至少允许再分发+嵌入+商用)且许可允许转换、拆分后再分发;对照 LICENSES.md 表格格式登记版权与来源;
- 生成子集:用 scripts/font_subset.py 按需抽取。解说片常用方案是
--gb2312(6763 汉字全带上,换题目不用每次补字,单字重约 1MB);风格场景可用默认预置字集保持几十 KB,生僻字用--text追加; - 处理保留名:若新字体带 Reserved Font Name,子集版必须改 family 名;若是对表内拉丁字体做改动,同样不能沿用保留名;
- 注册字体:在 scripts/engine/lib/fonts.js 的
FONT_FACES追加{family:'名字-字重', url:'lib/fonts/对应.woff'},family 名与文件名去扩展名保持一致; - 校验缺字:运行引擎或 scripts/qa.py,确认
console.error无缺字告警;QA 会把页面报错计入失败,这是交付前的最后一道闸。
8. 总结
LICENSES.md 虽是一份许可清单,却是理解 huashu-art-motion 字体基础设施的钥匙:它划定了 MIT 仓库与 OFL 字体的许可边界,登记了 30 余款字体的版权与来源,并提示了 Reserved Font Name 与子集化的耦合关系。配合 scripts/font_subset.py(子集生成)、scripts/engine/lib/fonts.js(注册)与 scripts/engine/lib/util.js(cmap 缺字校验)三份源码,你既能合规地复用这套字体体系,也能安全地扩展自己的字库——这正是"用代码让画动起来"在字体维度上的完整工程闭环。