Jasna 视频马赛克修复完整指南：GPU 加速流水线、模型选型与排障实战

【免费下载链接】jasnaVideo restoration tool项目地址: https://gitcode.com/GitHub_Trending/ja/jasna

Jasna 是一款免费开源（AGPL-3.0）的 GPU 加速视频马赛克修复工具，支持 NVIDIA（GTX 16 系起）与 AMD（RX 7000/9000，实验性），把"解码 → 检测 → 修复 → 编码"整条链路放在 GPU 上完成，并提供图形界面与命令行两种用法。本文按"先跑通、再选型、后调优"的顺序组织，读完你就能独立完成第一个修复任务，并知道每种配置在显存和耗时上各值多少。

启动前核对与四步跑通第一个任务

跑之前花一分钟核对下面四项，任何一条不满足，程序都会直接停在启动检查里（检查逻辑见 jasna/gui/system_checks.py）。

⚠️ 中文用户名下的C:\Users\张三\Downloads\jasna会直接报错退出，这条最容易被忽略。

GUI 最短路径（4 步）：

1. 下载与系统、显卡匹配的版本包，解压到纯英文路径；
2. 启动：Windows 双击jasna.exe；Linux NVIDIA 运行jasna文件；Linux AMD 先装 AMF 运行库再运行run_jasna_amd.sh；
3. 把视频拖进队列（或点"添加文件"），保持默认设置；
4. 点界面底部的▶，等待完成。

CLI 最短路径（1 条命令）：

jasna --input input.mp4 --output output.mkv

图片输入自动走 SD 1.5 模型，文件夹输入批量处理（先图片后视频）。

⚠️ 首次任务需额外等 15–60 分钟，仅此一次。NVIDIA 上 Jasna 会把检测模型和修复模型编译成专属于你的 GPU 的 TensorRT 引擎（缓存位置由 jasna/engine_paths.py 的configure_torch_compile_cache配置），期间关闭其他应用。编译产物存放在model_weights目录，升级 Jasna 时把这个文件夹复制到新版本目录即可跳过等待。

原理速览：四段并行的 GPU 流水线

整条流水线由 4 个并行线程循环驱动（定义在 jasna/pipeline_threads.py），压缩成四个阶段：

1. GPU 解码：NVIDIA 走 NVDEC、AMD 走 AMF、软件解码兜底，实现在 jasna/media/video_decoder.py 的_setup_nvdec_decoder/_setup_amf_decoder；
2. 检测与跟踪：默认模型rfdetr-v6（常量DEFAULT_DETECTION_MODEL_NAME，注册表在 jasna/mosaic/detection_registry.py）逐帧找马赛克，跟踪器沿时间轴把同一块马赛克归组为"剪辑"，遇硬切镜头强制收尾，见 jasna/tracking/clip_tracker.py；
3. BasicVSR++ 修复：每个剪辑按 256×256 的图像序列修复，相邻剪辑刻意保留少量重叠避免接缝跳变；
4. 合成与编码：只替换马赛克区域，其余像素原样保留（混合掩码与缓冲在 jasna/blend_buffer.py），音频默认直接复制，仅容器装不下原音轨时才重编码（判断逻辑在jasna/media/audio_utils.py的needs_audio_reencode）。

两条补充：

• 显存告急时 Jasna 自动把排队中的帧挪到系统内存、需要时搬回（jasna/vram_offloader.py），无需手动干预；
• LTX 不走这条流水线：它要把视频完整过四遍（找马赛克、准备、扩散修复、保存），慢得多但纹理更真实。

修复模型选型与三档预设

绝大多数视频用免费的BasicVSR++就够；只有对个别关键场景质感要求高、且显卡是 RTX 30/40/50 系（8 GB 显存起）时才上LTX；静态图片自动走SD 1.5。

LTX 常用开关：--restoration-model-name可选ltx（标准）/ltx-4step（良好，慢约 1.5 倍）/ltx-8step（高画质，慢约 2.5 倍）/ltx-undistilled（顶级，慢约 5 倍）；--ltx-fast（仅 RTX 50 系，快约 1.4 倍）；--ltx-trial无需模型和许可证即可实测速度，不产出修复视频——决定上 LTX 前先跑一次。

检测模型决定第 2 阶段"找马赛克"的效果，阈值取自 jasna/mosaic/detection_registry.py：

权重放进model_weights/后自动发现。阈值用--detection-score-threshold（0–1）调整：调低检得更多、调高检得更少。AMD 上 RF-DETR 明显慢于 NVIDIA，检测是瓶颈就换lada-yolo-v4。

调参对象主要是 BasicVSR++（LTX 自管内存），核心变量就三个：最大剪辑大小、时间重叠、交叉淡化，合法性由 jasna/session_config.py 统一校验。

够用的（默认值）：--max-clip-size 90 --temporal-overlap 8，交叉淡化默认开。默认值在 10 GB 级显存的卡上很宽裕。

jasna --input input.mp4 --output output.mkv

追求质量的：--max-clip-size 180是收益拐点（1080p 实测 35 秒 / 5.0 GB，再往上时间不再变好只吃显存），加二次修复与低 CQ：

jasna --input input.mp4 --output output.mkv --max-clip-size 180 --temporal-overlap 8 --secondary-restoration unet-4x --cq 22

资源受限的（4–6 GB 显存）：--max-clip-size 30起步（1080p 实测 51 秒 / 3.4 GB），关二次修复，关闭一切占 GPU 的其他程序；4K 素材同剪辑大小下显存约 ×1.5，再往下压。

剪辑大小扫描数据（1080p、重叠 8、RTX 5090，趋势普适、绝对值因环境而异）：

小剪辑只会更慢：重叠帧在每个剪辑里都要重复处理。交叉淡化复用的是已处理好的帧，零额外开销，保持默认开启。模型编译同理——关掉只省不到 0.5 GB 显存，却让处理慢约 3 倍（同素材对比：编译 33 秒 / 5.0 GB vs 不编译 107 秒 / 4.6 GB），几乎没有正当理由。

⚠️ 时间重叠必须满足2 × temporal_overlap < max_clip_size，否则启动即报错；8–20 是推荐区间，超过 20 通常无收益。

核心参数速查（以jasna --help为准）：

CQ 合法范围：NVIDIA H.264/HEVC 为 1–51、AV1 为 1–63；AMD H.264/HEVC 为 0–51、AV1 为 1–51。Jasna 还会按源码率自动给输出设maxrate（bufsize为其 2 倍）防止低码率源被过度放大，自行指定maxrate可覆盖。

二次修复只在修复块看起来"软"时（大马赛克、特写、4K）才有必要。三个选项：UNet 4x（支援者专属，质量接近 TVAIiris-2且更快）、RTX Super Res（免费、极快，个别视频会闪）、Topaz TVAI（需付费 Topaz Video，仅 Windows）。1080p 实测（耗时 / 显存）：

进阶场景手册

区间处理：只修要修的地方

适用边界：马赛克只出现在部分场景时用；或想用 LTX 但嫌慢，只对关键片段用 LTX。未选中的区间原样复制，速度快且画质无损，输出仍是全片长视频。马赛克遍布全片时别用，直接整片跑更快。

最小操作：GUI 里点队列条目的剪刀按钮打开区间编辑器，按帧选区间、逐区间指定 BasicVSR++ 或 LTX，能开修复预览、用内置马赛克扫描自动定位（RTX 5090 上约 2000 FPS）、用"仅大马赛克用 LTX"（建议从 12% 起步）把慢速 LTX 只集中在大马赛克上。CLI 直接给时间区间（秒或HH:MM:SS.s）：

jasna --input input.mp4 --output output.mp4 --segments "10-25,01:10-01:30.5"

文件夹批量自动分配用--ltx-auto-split 12（大马赛克走 LTX、其余走 BasicVSR++）。

已知代价与坑：一次只能处理单个视频；输入须为恒定帧率的 H.264/HEVC/AV1，输出 MP4/MOV/MKV，输出编解码器恒等于输入；不能与--stream、--retarget-high-fps、--fmp4、--ltx-auto-split组合；区间边界处的少量帧会被重新编码。磁盘紧张时用--working-directory把临时文件指到更快的盘。

浏览器 / Stash 流媒体：边修边看

适用边界：想先确认效果不落盘，或挂在 Stash 里按需修复时用。正式交付文件别用流媒体，它恒用 BasicVSR++ 与 H.264，LTX 不可用。

最小操作：

jasna --stream

启动 HLS 服务并自动打开浏览器播放器，可拖动进度；--stream-port（默认 8765）、--stream-segment-duration（默认 4.0 秒）、--no-browser可调。Stash 需下载专用版本并设置JASNA_CLI_PATH与JASNA_WORKING_DIR两个环境变量。

已知代价与坑：⚠️ 首次必须先用 Stash 里实际会用的相同设置流式跑通一个短视频——第一次要为 GPU 准备文件、耗时很长，跳过这步 Stash 会超时放弃（日志出现timeout waiting for jasna-cli to become healthy就是这个原因）。

VR180 视频：拆开修再拼回

适用边界：VR180 文件通常把左右眼并排放进一个宽帧，Jasna 会拆开分别修复再拼回。注意 LTX 不支持 VR180 并排视频，只能用 BasicVSR++。

最小操作：保持VR180 模式 = 自动（高度 > 1080px 的 2:1 视频如 3840×1920，或文件内 VR 元数据，都会自动识别为并排 VR），检测模型换用内置的rfdetr-vr-v1。自动认不出来时手动指定：

jasna --input input.mp4 --output output.mp4 --vr-mode sbs-fisheye

--vr-mode取值auto（默认）/off/sbs/sbs-fisheye；投影方式（原样/鱼眼/球心投影）按片商自动选择。

已知代价与坑：8K VR 素材耗时约翻倍（基准：8K VR HEVC 60 fps 在 RTX 5090 上约 34.5 秒 / 1080p 3:22 素材 38.6 秒），显存占用也升到约 17.5 GB，8 GB 显存跑 8K VR 会紧张。

排障速查表

官方基准：耗时与显存数据

测试条件：RTX 5090、Linux、BasicVSR++、同一段 3:22 全长视频，时间越短越好。

GPU 显存（典型 / 峰值，GB）：

一句话结论：Jasna v0.9.1 在同硬件上把 1080p 整片修复压到 Lada 的约 1/3.6 时间，同时把 1080p 显存从 9.3 GB 降到 4.8 GB（典型值）。完整测试设置与全编解码器明细见 benchmarks/2026-07-26_release_matrix.md，可用 scripts/benchmark_releases.py 复现。

许可与延伸阅读

确认好显卡与路径、熬过一次 15–60 分钟的编译，剩下的就是按本文三档配置对号入座的事。

• 许可：公开应用源码为 AGPL-3.0，模型与随附依赖各自保留原许可证，详见 LICENSING.md、assets/THIRD_PARTY_LICENSES.md 与 assets/THIRD_PARTY_MODELS.md；从源码运行可使用免费 BasicVSR++，LTX 与支援者模型需官方发行版与许可证码。
• 延伸阅读：docs/zh/models.md（模型选型与 LTX 手动下载）、docs/zh/tuning.md（显存调优）、docs/zh/segments.md（区间处理）、docs/zh/cli.md（全量 CLI 选项）、docs/zh/streaming.md 与 docs/zh/cloud.md。

【免费下载链接】jasnaVideo restoration tool项目地址: https://gitcode.com/GitHub_Trending/ja/jasna