目标与约束#

我给自己定了几条硬约束，后面的设计基本都是从这几条推出来的：

• 全程本地：视频里是别人的脸，不上传任何云服务，没有遥测、没有自动更新、没有运行期下载。
• 用上 Apple Silicon 的硬件：Mac mini M4 的 Neural Engine / GPU 做推理，VideoToolbox 做硬解硬编。所以不用 Docker——macOS 上的容器是个 Linux 虚拟机，里面根本摸不到 ANE、Metal 和 VideoToolbox。
• 输出规格不变：4K60 10-bit 的素材进去，分辨率、帧率、位深、色彩元数据、音轨都要原样出来；没打码的区域像素不能被动。
• 不确定就打码（fail-closed）：漏打一个路人是隐私事故；误打一个朋友只是画质瑕疵，重渲染就行。所有默认值和异常处理都偏向打码。
• 环境可控：项目目录里一个 Python venv，ffmpeg 用本机已有的；不用 brew、不用 sudo、不改 shell 配置，想卸载删几个目录就行。

一张图看懂架构#

FaceBlur 总体架构(点击图片在新标签页打开矢量大图,可无损放大)

整个系统分成两遍（Pass），中间用一组落盘的 JSON 衔接，网页只是在中间让人做决定：

1. Pass 1 · 分析：每个视频只做一次。解码 → 检测 → 切镜头 → 跟踪 → 取脸算 embedding → 聚类 → 和 Gallery 比对。结果全部写进 sidecar 目录。
2. Sidecar 与网页：tracks.json（分析结果）、decisions.json（我的勾选和风格）、edits.json（手动校正）三份文件，加上缩略图和低清代理视频。网页只读写这几份文件。
3. Pass 2 · 渲染：读取三份 JSON，生成逐帧的遮罩计划，硬解原片、只改人脸区域、硬编输出。改风格、改勾选、改校正，都只重跑这一遍，不用重新分析。

这样拆的好处很实际：分析最贵（要跑神经网络），所以只做一次；而「我想换个马赛克强度」「这个人其实要保留」这类操作，只需要重新渲染。

Pass 1：从视频到「人」#

1
providers = [
2
    ("CoreMLExecutionProvider", {
3
        "ModelFormat": "MLProgram",
4
        "MLComputeUnits": "ALL",
5
        "RequireStaticInputShapes": "1",
6
        "ModelCacheDirectory": f"{ROOT}/cache/coreml",
7
    }),
8
    "CPUExecutionProvider",
9
]

Pass 2：渲染#

一帧的遮罩是怎么算出来的(点击图片在新标签页打开矢量大图,可无损放大)

1
# 解码：硬解，原位深直通
2
ffmpeg -hwaccel videotoolbox -i src.mp4 -f rawvideo -pix_fmt yuv420p10le -fps_mode passthrough -
3

4
# 编码：另一个 ffmpeg 子进程从 stdin 读，同时从原片取音轨
5
ffmpeg -f rawvideo -pix_fmt yuv420p10le -s 3840x2160 -framerate 60000/1001 -i - \
6
       -i src.mp4 -map 0:v:0 -map 1:a? -c:a copy \
7
       -c:v hevc_videotoolbox -allow_sw 0 -tag:v hvc1 -profile:v main10 -pix_fmt p010le

打码风格与「安全下限」#

页面里我只保留了三种风格：高斯模糊、马赛克、贴图（后端还支持几种别的，但我自己不会用）。风格看起来是纯审美问题，但它直接关系到隐私，所以我给它加了一道硬性的「安全下限」：

即使是用户能选到的最弱一档，处理后的人脸区域也必须检测不出脸，或者与原脸的 ArcFace 余弦相似度低于 0.3。

这个「反识别回测」用真实人脸跑，渲染前自动执行（结果以 effects 源码、样本和模型做指纹缓存，代码一改就重跑）。不达标就拒绝渲染。

第一版的强度映射是凭直觉定的，结果回测直接打脸：

原因有两个：模糊/马赛克强度偏弱，以及羽化把五官放进了渐变区——羽化最大时全强度核心只有遮罩半径的一半。修正是：加强强度映射；羽化渐变带不允许侵入人脸区域；并把遮罩放大倍数的下限从 1.2 提到 1.4（1.2 时椭圆盖不住人脸框的四个角，头发和衣着会残留身份信息，同一个样本里纯黑块也有 0.26 的残留余弦）。

我还试做过一个「平均色块」（用脸部平均色填一块），回测余弦 0.338，超过了 0.3：一块肤色色块放在头发和衣服的上下文里，检测器照样觉得那是一张脸。所以这个风格被我直接放弃，没有提供。回测的价值就在这里——它能把「看起来很安全」的东西否掉。

记住常出镜的人：Gallery 与三态判定#

Gallery 存的是人脸 embedding（生物特征数据，所以目录权限 700、文件权限 600、导出时会提示风险），每人最多保留 24 条模板，质量最低的先淘汰。

匹配时，对每个人物的每条 track 取它和某位已记住的人全部模板的最大相似度，再按 track 质量加权平均，然后分三态：

• ≥ 0.55 → KEEP（预勾选）
• ≤ 0.35 → BLUR
• 之间 → UNCERTAIN（页面黄色高亮，未处理按打码渲染）

因为「误判 KEEP = 路人被放行」，我又加了两条保守规则：只要有一条 track 低于 0.35，即使加权平均很高也只给 UNCERTAIN（聚类阈值较松，可能把两人并成一个人物）；最像的两位已记住的人相差不到 0.05，也只给 UNCERTAIN。

跨片段实测：把同一段素材切成前后两半，在前半段记住 7 个人，处理后半段——同一位男士自动 KEEP（0.645，我对着缩略图确认是同一个人）；另一位男士和一位女士只有 0.49 / 0.47，被判 UNCERTAIN，交给我确认；两位戴口罩的人被错配成前半段的别人（0.42–0.45），同样只是 UNCERTAIN。全程没有一个错误的 KEEP。代价是需要人工点几下，这是我愿意付的。

网页：把人放进回路#

页面用 FastAPI + 一个原生 JS 单文件，没有构建工具链。三个视图：

• 主页：输入路径或浏览目录选视频，分析时显示进度，下面是「最近处理」。
• 审核页：按出现时长排序的人物列表，头像、出现时段（点一下就渲染那一段预览）、保留/打码开关、「记住此人」、按人物单独指定风格；右侧是风格面板和并排对比（用该人物真实的人脸缩略图，和正式渲染调用同一份效果代码，所见即所得）。
• 校正编辑器：渲染后如果发现漏打或误打，在这里逐帧修。

踩过的坑#

这一节是我觉得最值钱的部分。

1. 重新分析之后，人物编号会变。 我一开始只用 p001、p002 当人物标识，后来发现重新跑一遍分析，编号会重新排——旧的 decisions.json 里的 p002: KEEP 可能就指向了另一个人，等于把一个路人悄悄放行。修法是给每次分析一个 analysis_id，decisions.json 和 edits.json 都绑定它，不一致就直接拒绝渲染。

2. 「马赛克时有时无」的真正原因。 我原本以为是检测漏了，结果查下来那位男士每一帧都被检出了（置信度约 0.85）。问题出在：他的两条 track 之间有大约 1 秒的空档，而我写的「延续」逻辑只在单条 track 内部插值，同一个人的前后两条 track 之间不会被衔接。改成同一人物、同一镜头、空档不超过设定时长就线性过渡之后，同一个人的遮罩覆盖从 11.4 秒涨到 12.6 秒（延续 1.5 秒档）。剩下的空档都恰好落在镜头切换处，那是原理上衔接不了的，交给手动工具。

3. 别信旧文件。 有一次我对着一个成片诊断「主角被误打码」，查了半天，最后发现那个成片的修改时间比保存决策的时间还早——它根本是更早一轮测试的产物，不是按当前决策渲染的。教训：先对时间戳，再查算法。

4. 测试抓到一个越界。 文件浏览的目录列举，在路径非法时我把它回退到了「真实主目录」而不是「允许的根目录」。生产环境里两者重合所以暂时无害，但写测试时把根目录换成临时目录就暴露了。现在非法路径一律回退到受限根。

5. Core ML 的持续吞吐会掉。 embedding 单次测是 7 ms，但连续算近千张脸后降到约 17 ms，和 CPU 差不多（疑似持续负载下的降频）。好在分析只对每条 track 的 Top-K 帧算 embedding，量很小，不是瓶颈。如果要大批量，可以用我导出的 batch=8 版本。

局限与下一步#

• 检测不到就是漏码。 小脸、侧脸、背面、严重模糊——这是整个方案的软肋。同一画面下 960 → 1920 多检出了约 25% 的框，下一步我打算做切块检测（SAHI 式），专门提升远景小脸的召回。
• 手动框是静态的，不做自动跟踪，要跟着人走得自己加关键帧。
• 镜头切换处的遮罩空档无法自动衔接，只能手动补。
• 4K60 10-bit 的完整渲染我还没有用真实素材跑过，目前只用合成素材测过一次硬解到硬编（5 秒素材约 0.9× 实时）。
• 模型许可： 默认的 SCRFD / ArcFace 权重来自 insightface，仅限非商业研究用途。我是个人、不盈利使用；如果将来频道变现，需要换成许可更宽松的模型（比如 OpenCV Zoo 的 YuNet / SFace）或重新评估授权。

技术栈速览#

一个完整的自动打码流程，真正难的不是「把脸打上马赛克」，而是怎么在不确定的时候依然守住底线：默认打码、决策可追溯、出错就停手、给人留一个能修正的入口。这些东西加起来，才让我敢把它放进真实的剪辑流程里。