Jasna 视频马赛克修复：3:22 的 1080p 视频 34 秒修完的 GPU 加速实战指南

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

Jasna 是免费开源的 GPU 加速视频马赛克修复工具，把解码、检测、修复、编码全放到 GPU 上，适合想给视频去马赛克的 NVIDIA/AMD 独显用户。读完能过环境检查、跑通第一个任务，并按自己的显卡调好显存与速度。

🛑 启动前的 4 项硬性门槛

第一次运行前花一分钟核对下面四项，任何一条不达标，启动检查（jasna/gui/system_checks.py）都会直接拦下来。

注意：路径这条最容易被忽略。C:\Users\张三\Downloads\jasna这种中文用户名下的路径会直接报错退出，必须整体搬到英文路径。

📦 三条命令跑通：GUI 与 CLI 并列

图形界面最短路径：解压版本包到纯英文路径 → 启动（Windows 双击jasna.exe；Linux NVIDIA 执行jasna文件；Linux AMD 先装好 AMF 运行库再执行run_jasna_amd.sh）→ 把视频拖进队列并保持默认设置 → 点界面底部的▶等它跑完。

命令行最短路径就是这一条，对单个视频执行默认的 BasicVSR++ 流程：

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

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

jasna --input photo.png --output restored.png jasna --input input_folder --output output_folder

首次任务要等 15–60 分钟，仅此一次。NVIDIA 上 Jasna 会把检测模型和修复模型编译成专属于这块 GPU 的 TensorRT 引擎，期间关闭其他应用、别碰电脑；判断正常的标志是机器负载拉满、model_weights目录持续增长。编译产物存放在model_weights目录（缓存位置由 jasna/engine_paths.py 的configure_torch_compile_cache配置），以后升级 Jasna 时把这个文件夹复制到新版本目录即可跳过等待。

跑完发现显存吃紧时，把最大剪辑大小从90降到60是最直接的手段，调法见后文。

🎯 三种引擎怎么选：BasicVSR++、LTX、SD 1.5

先说结论：绝大多数视频用免费的BasicVSR++就够；只有当你对个别关键场景的质感有更高要求、且显卡是 RTX 30/40/50 系（8 GB 显存起）时，才值得上LTX；静态图片自动走SD 1.5。选型细节见 docs/zh/models.md。

LTX 耗时参考（1 分钟 1080p、马赛克持续出现的素材，标准画质档）：

LTX 常用开关：--restoration-model-name可选ltx（标准）/ltx-4step（良好，慢约 1.5 倍）/ltx-8step（高画质，慢约 2.5 倍）/ltx-undistilled（顶级，慢约 5 倍）；--ltx-large-canvas让大马赛克按 768px 修复（该部分慢约 3 倍，需约 12 GB 空闲显存，不足自动回退）；--experimental-ltx-less-overlap默认开启（马赛克持续超 4 秒的场景约快 13%）；--ltx-seed默认20260923控制可复现性。决定上 LTX 前先跑一次--ltx-trial速度实测（无需模型和许可证，不产出修复视频）：

jasna --input input.mp4 --output output.mkv --restoration-model-name ltx --ltx-trial

注意 LTX 的硬限制：不支持 VR180 左右并排、不支持流媒体，且启用后二次修复与降噪自动关闭。Jasna 0.12 起从 0.11.3 复制过来的 LTX 模型文件需要重新下载，原来的许可证码和共享 VAE 文件仍可复用。

检测模型管的是"找马赛克"这一步，全部选项如下（阈值取自 jasna/mosaic/detection_registry.py）：

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

二次修复只在修复块看起来"软"（大马赛克、特写、4K 素材）时才有必要，且仅限 NVIDIA。1080p 实测（耗时 / 显存）：

jasna --input input.mp4 --output output.mkv --secondary-restoration unet-4x

TVAI 需额外设置环境变量TVAI_MODEL_DATA_DIR与TVAI_MODEL_DIR指向 Topaz Video 的模型目录，相关参数--tvai-model（默认iris-2）、--tvai-scale（默认 4，输出为 256×scale）、--tvai-workers（默认 2）、--tvai-ffmpeg-path见 docs/zh/cli.md。

三档场景推荐：

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

• 追求质量：--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，再往下压。

🧩 帧的旅程：七段 GPU 流水线

源码把整条流水线拆成四个并行线程循环（decode_detect_loop→primary_restore_loop→secondary_restore_loop→blend_encode_loop），定义在 jasna/pipeline_threads.py。七个环节各自吃进什么、做什么、吐出什么：

GPU 解码

• 输入：源文件（H.264 / HEVC / AV1，含 10-bit）
• 处理：NVIDIA 走 NVDEC、AMD 走 AMF，另有软件解码兜底（jasna/media/video_decoder.py 的_setup_nvdec_decoder/_setup_amf_decoder）
• 输出：连续帧流，进入检测队列

逐帧马赛克检测

• 输入：刚解码出的每一帧
• 处理：默认rfdetr-v6，按推荐阈值打分并框出马赛克区域
• 输出：该帧的马赛克框列表与置信度

时间维跟踪分组

• 输入：连续帧的检测框
• 处理：同一块马赛克沿时间轴被跟踪，帧归组为"剪辑"，长度上限即最大剪辑大小；硬切镜头处强制收尾，保证一个剪辑不混入两个镜头（jasna/tracking/clip_tracker.py）
• 输出：一批互不混镜头的剪辑

主修复（BasicVSR++）

• 输入：每个剪辑的 256×256 图像序列
• 处理：按序列做时间维超分重建，相邻剪辑刻意保留少量重叠来隐藏接缝
• 输出：补出纹理的马赛克图块

二次修复（可选，NVIDIA 独占）

• 输入：256×256 修复图块
• 处理：UNet 4x / RTX Super Res / Topaz TVAI 先把图块放大到 512×512 或 1024×1024，再走一遍锐化
• 输出：更清晰的图块（用 LTX 时此环节整体关闭）

合成回原帧

• 输入：修复图块 + 原始帧
• 处理：只替换马赛克区域，其余像素原样保留（混合掩码与缓冲在jasna/blend_buffer.py与jasna/tracking/blending.py）；显存告急时排队中的帧自动挪到系统内存、需要时再搬回（jasna/vram_offloader.py），全程无需手动干预
• 输出：完成混合的完整帧

GPU 编码

• 输入：完整帧 + 原音轨
• 处理：NVENC 或 AMF 编码；音频默认直接复制，仅当输出容器装不下原音轨才重新编码（判断逻辑在jasna/media/audio_utils.py的needs_audio_reencode）
• 输出：最终文件（默认 HEVC）

LTX 不走这条流水线：它要把视频完整过四遍——找马赛克、准备、用扩散模型修复、保存——所以慢得多，但能补出更真实的纹理。

⚡ 速度与显存调优：把显存从 10 GB 压到 3.4 GB 的三档配置

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

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

小剪辑只会更慢：重叠帧在每个剪辑里都要重复处理，剪辑越多重复劳动越多，超过 180 之后时间不再变好、只有显存上升。交叉淡化复用的正是已处理好的帧，零额外开销，保持默认开启即可。模型编译同理——关掉编译开关（--no-compile-basicvsrpp）只省不到 0.5 GB 显存，却让处理慢约 3 倍（同素材对比：编译 33 秒 / 5.0 GB，不编译 107 秒 / 4.6 GB），几乎没有正当理由。

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

按需求查表（编码与画质）：

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

常用默认值速查（以jasna --help为准）：

🚀 四个进阶方向：区间、流媒体、VR180、云 GPU

区间处理（segments）—— 马赛克只出现在部分场景，或想只对关键片段花 LTX 的慢钱：未选中的区间原样复制，快且无损，输出仍是全片长视频。

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

• 一次只能处理单个视频，不支持文件夹/图片/流媒体
• 输入须为恒定帧率的 H.264/HEVC/AV1，输出 MP4/MOV/MKV，且输出编解码器恒等于输入
• 不能与--stream、--retarget-high-fps、--fmp4、--ltx-auto-split组合；区间之间的少量帧会被重新编码（视频只能在特定帧处切开）

GUI 里点队列条目的剪刀按钮打开区间编辑器：按帧选区间、逐区间指定 BasicVSR++ 或 LTX（LTX 区间可先渲染指定种子、比较多个种子）、用内置马赛克扫描（RTX 5090 上约 2000 FPS）自动定位含马赛克的场景，还能开"仅大马赛克用 LTX"把慢速 LTX 集中在收益最大的大马赛克上（建议从 12% 起步）。想让文件夹里每个视频"大马赛克走 LTX、其余走 BasicVSR++"，用自动分配：

jasna --input videos/ --output restored/ --restoration-model-name ltx --ltx-auto-split 12

临时文件默认放输出旁的隐藏文件夹，磁盘紧张时用--working-directory指到更快的盘。

流媒体（Stash / 浏览器）—— 边修边看不落盘，先确认效果，或挂在 Stash 里按需修复。

jasna --stream

• 恒用 BasicVSR++ 与 H.264，LTX 不可用
• 首次必须先用 Stash 里实际会用的相同设置流式跑通一个短视频——第一次要为 GPU 准备文件、耗时很长，跳过这步 Stash 会超时放弃（日志出现timeout waiting for jasna-cli to become healthy就是这个原因）
• Stash 需下载专用的 v0.30.1-jasna 版本，并设置JASNA_CLI_PATH（jasna 可执行文件完整路径）与JASNA_WORKING_DIR（其所在文件夹）两个环境变量

启动后 Jasna 会开 HLS 服务并自动打开浏览器播放器，可拖动进度；--stream-port（默认 8765）、--stream-segment-duration（默认 4.0 秒）、--no-browser可调。

VR180—— VR180 文件通常把左右眼并排放进一个宽帧，Jasna 会拆开分别修复再拼回。保持VR180 模式 = 自动（高度 > 1080px 的 2:1 视频，如 3840×1920、8192×4096，或文件内 VR 元数据、已知片商名，都会自动识别为并排 VR），检测模型换用内置的rfdetr-vr-v1；认不出来时手动指定：

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

• LTX 不支持 VR180 并排视频，只能用 BasicVSR++
• --vr-mode取值：auto（默认）/off/sbs/sbs-fisheye
• 投影方式（原样/鱼眼/球心投影）按片商自动选择，也可在区间编辑器的修复预览旁手动切换

云端 GPU（RunPod / Vast / Docker）—— 本地显卡太慢或没有显卡，租一张云 GPU 跑批量任务。向许可证码来源申请开通"云权限"后，用 Linux NVIDIA 官方版 CLI 在容器内以root登录运行，安装到/root（不要用/workspace，权限不可靠）：

apt-get update && apt-get install -y zstd wget libgl1 libglib2.0-0 # 从官方发布页下载 v0.11.1 的四个分卷包（part000–part003），拼合解压： cat jasna-linux-nvidia-0.11.1.tar.zst.part* | zstd -dc | tar -xpf - --same-owner cd jasna-linux-nvidia-0.11.1 export XDG_CONFIG_HOME=/root/jasna-config ./jasna --license-code YOUR-LICENSE-CODE --cloud-workspace

激活前可花一秒验证硬件编码器是否可用，没打出OK就换机器：

./tools/ffmpeg -loglevel error -f lavfi -i testsrc2=duration=1:size=1280x720 -c:v hevc_nvenc -f null - && echo OK

• 硬性要求：驱动 ≥ 580、磁盘 ≥ 80 GB、设置NVIDIA_DRIVER_CAPABILITIES=all（不加则读不了也存不了视频）、固定的/etc/machine-id
• --pid=host的 Docker 容器不可用；RunPod 上 LTX 暂不可用（会替换 root 用户导致 LTX 校验失败），BasicVSR++ 可用
• 每次启动前先重新export XDG_CONFIG_HOME；删 Pod 前把jasna-config私有备份，否则激活名额就浪费了

📊 官方基准：3.4–4.7 倍提速，显存从 9.3 GB 降到 4.8 GB

测试条件：RTX 5090、Linux、BasicVSR++、同一段 3:22 全长视频。

显存占用演变（典型 / 峰值，GB，H.264 8-bit 输入）：

横向看，v0.9.1 相对 Lada 在同硬件上把 1080p 整片修复压到约 1/3.6 的时间；纵向看，v0.9.1 相比自家旧版本把 1080p 典型显存从 9.3 GB 降到了 4.8 GB。完整测试设置、内存占用与全编解码器明细见 benchmarks/2026-07-26_release_matrix.md，逐项提交的性能演进数据保留在benchmarks/目录的 CSV 中，可用 scripts/benchmark_releases.py 复现。

🩹 踩坑速查：看到什么、为什么、做什么

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