PrivateFrame本地视频处理桌面应用 · CLI · Python模糊与马赛克

PrivateFrame — 安装与使用指南

通过桌面应用开始体验、自动化视频工作流程，或将处理能力集成到 Python 中。

2026-09-08•约 8 分钟

你将完成什么

在自己的设备上检测并跟踪视频中的人脸，再应用模糊或马赛克。可处理所有人脸，也可通过参考照片选择需要保留的人物。

使用 InsightFace 预训练模型进行商业部署，需另行获取商业模型授权。

视频演示

查看 PrivateFrame 的实际效果。

观看不同场景中的人脸跟踪与遮挡效果，以及高斯模糊和马赛克输出。

PrivateFrame 实际输出效果。分享前请检查处理后的视频。

打开视频

音乐：Scott Buckley 创作的 Tears in Rain · CC BY 4.0。已节选并混音。

开始之前

需要 Python 3.10 及以上版本，以及包含 python-package/insightface/app/privateframe/ 的新版 InsightFace 源码。请在该仓库根目录执行安装命令。本指南使用新版源码安装；旧版仓库或已发布的软件包可能尚未包含 PrivateFrame。
准备本地视频和输出目录。将示例中的 /data/... 替换为你设备上的路径。每个示例使用不同的输出目录，以便分别保存结果。
安装依赖和模型后，视频处理在本地运行，不会上传视频或参考照片进行处理。首次使用时可能需要下载缺失的模型。

1. 安装与使用指南

需要 Python 3.10 及以上版本，以及包含 python-package/insightface/app/privateframe/ 的新版 InsightFace 源码。请在该仓库根目录执行安装命令。本指南使用新版源码安装；旧版仓库或已发布的软件包可能尚未包含 PrivateFrame。

需要 Python 3.10 或更高版本。请按指南从更新后的代码仓库安装，首次运行可能需要下载模型。项目提供的预训练模型仅供非商业研究评估；商业部署前请申请模型授权。

桌面应用

python -m pip install "./python-package[gui]"

命令行 / Python API

python -m pip install "./python-package[privateframe]"
insightface-privateframe --help

2. 桌面应用

在 InsightFace Evaluation Studio 中打开 PrivateFrame，选择视频、处理设置和输出文件夹。

在 InsightFace 桌面应用中打开 PrivateFrame，或向 CLI、Python API 传入视频。
选择人物处理模式，按需添加参考照片，再选择模糊或马赛克。
导出新视频与可复用的分析 JSON。分享前请检查输出结果。

桌面应用

insightface-gui

3. 命令行 — 选择需要模糊的人物

用一条命令处理视频，也可将分析与渲染分开，方便检查和多次导出。

使用参考照片的两种模式都需要将清晰的单人 JPG、JPEG、PNG 或 WebP 照片直接放在同一个参考目录下。每张照片仅使用检测到的最大人脸，且目录中至少要有一张可用参考人脸。默认策略下，未匹配或匹配不确定的人脸在 blur_only 模式中保留可见，在 exempt 模式中进行模糊处理。

模糊所有人脸: 遮挡所有检测到的人脸，无需参考照片或身份匹配。
仅模糊选定人物: 模糊与参考照片匹配的人物，保留其他人物的人脸可见。
保留选定人物可见: 保留匹配人物的人脸可见，同时模糊未匹配或匹配不确定的人脸。

模糊所有人脸

insightface-privateframe process \
  --input /data/video.mp4 --output-dir /data/all

仅模糊选定人物

insightface-privateframe process \
  --input /data/video.mp4 --output-dir /data/selected \
  --recognition.mode blur_only \
  --recognition.reference_dir /data/reference_photos

保留选定人物可见

insightface-privateframe process \
  --input /data/video.mp4 --output-dir /data/exempt \
  --recognition.mode exempt \
  --recognition.reference_dir /data/reference_photos

4. 分析一次，多次渲染

复用分析 JSON，即可调整渲染设置或编辑人脸框，无需重复检测与识别。

可以。保留原始视频和分析 JSON，即可用不同的模糊、马赛克或编码设置重新渲染。也可以编辑 JSON 中的人脸框。若要更改检测或身份匹配设置，则需要重新分析。

analyze

insightface-privateframe analyze \
  --input /data/video.mp4 --output-dir /data/review

render · mosaic

insightface-privateframe render \
  --input /data/video.mp4 \
  --result /data/review/video_privateframe.json \
  --redacted /data/review/video_mosaic.mp4 \
  --render.redaction.method mosaic

5. Python API

将分析与渲染集成到自己的应用中，支持进度与取消回调。

Python API

from insightface.app.privateframe import (
    analyze_streaming_pipeline,
    default_output_paths,
    render_streaming_artifacts,
)
from insightface.app.privateframe.base_config import DEFAULT_CONFIG_PATH

paths = default_output_paths("/data/video.mp4", "/data/python_output")

analysis = analyze_streaming_pipeline(
    config_path=DEFAULT_CONFIG_PATH,
    input_path=paths.source,
    workdir=paths.workdir,
    result_path=paths.result_json,
)

rendered = render_streaming_artifacts(
    input_path=paths.source,
    result_path=paths.result_json,
    redacted_path=paths.result_video,
    config_overrides={"render.redaction.method": "mosaic"},
)

6. 处理、检查并分享

导出新视频与可复用的分析 JSON。分享前请检查输出结果。

照片匹配可能漏掉人物。分享前请检查选择性处理的结果；在“仅模糊选定人物”模式下，未匹配到的目标人物可能仍然可见。

不能。检测、跟踪和匹配可能漏掉人脸或出现错误。请检查导出的视频，尤其是短暂出现的人脸、切换镜头和遮挡场景。人脸遮挡不会隐藏声音、姓名、衣着或其他可识别身份的上下文信息。

7. PrivateFrame 可以用于商业用途吗？

InsightFace 代码采用 MIT 许可证。项目提供的预训练模型仅限非商业研究使用；商业使用需要获得相应的模型授权。欢迎联系我们讨论部署需求。

将视频人脸隐私保护融入您的工作流程。

使用 InsightFace 提供的预训练模型进行商业部署，需另行获取商业模型授权。代码采用 MIT 许可证，模型授权与代码许可分别适用。

申请商业授权