Jasna 视频修复 GUI 完整实战指南：六个场景从批量修复到激活支持者模型
【免费下载链接】jasnaVideo restoration tool项目地址: https://gitcode.com/GitHub_Trending/ja/jasna
Jasna 是一款开源视频修复工具，支持 BasicVSR++ 等模型与 LTX 等支持者模型。本指南按六个场景讲它的 GUI 用法：安装自检、批量修复、单视频与静态图精修、实时预览、日志排错、激活。每节给出操作步骤、常见坑与源码位置，新手照着做，老手顺藤摸瓜。
一、跑起来之前的准备
目标：把 Jasna 装到一个能自检通过的位置，让首次启动不返工。
安装位置的两条硬要求
- 只装本地磁盘：Windows 用 NTFS，Linux 用 ext4 / Btrfs / XFS，网络磁盘不支持。
- 路径必须纯 ASCII：中文、日文、带重音的字母都不行。
⚠️ 路径里混进非英文字符，启动自检会直接阻塞，主窗口打不开，只能迁移安装目录后重来。
启动时还会检测磁盘类型（Windows 查驱动器寻道开销，Linux 读/sys的rotational标志，逻辑在install_on_hard_disk）。机械盘上会往日志写一条hard_disk_warning：
⚠️ 这条警告是实测结论：装机械盘的话，启动与加载模型的时间都会明显变长，建议 SSD。
首次启动自检查什么
安装或更新后第一次启动，会先弹一个启动窗口逐项显示进度，主窗口随后才打开。检查在后台线程执行，UI 每 100ms 轮询一次；驱动查询卡住或 torch 冷导入特别慢时，向导等 30 秒就放弃，先展示已完成的项。逐项清单如下（完整逻辑见 jasna/gui/system_checks.py）：
ascii_path：安装路径是否纯英文，失败阻塞启动ffprobe：能否找到 ffprobe 且 FFmpeg 主版本号为 8，失败阻塞启动gpu：是否检测到受支持 GPU（含计算能力），失败阻塞启动cuda：CUDA / ROCm 是否可用，报告版本与计算能力，失败阻塞启动driver：GPU 驱动版本，失败阻塞启动sysmem（仅 Windows）：NVIDIA 共享内存回退策略，仅警告不阻塞amf（仅 AMD）：AMD AMF 视频运行库，读写视频必需，失败阻塞启动
三个容易误判的地方：只有阻塞级检查失败时底部按钮才变"退出"，仅警告可以点"开始使用"；30 秒兜底后未跑完的项按失败处理，看到红行先确认是不是卡住，别急着重试环境；结果按版本记录，每个版本首次启动强制走一遍，之后可从页眉手动重跑。
实现细节：路径判定在 jasna/os_utils.py 的check_ascii_install_path，对安装目录做 ASCII 编码尝试，编码失败即不合规。
二、批量修复主流程
目标：把一批素材丢进队列，统一输出约定，一键跑完。
批量导入视频的三种方式
素材入队三条路（实现集中在 jasna/gui/queue_panel.py）：
- 点添加文件逐个选视频或图片；
- 点旁边的文件夹图标，整文件夹一次进来；
- 把文件直接拖到列表上（基于
TkinterDnD的拖放支持）。
执行顺序从上到下，拖条目把手调序。列表超过 20 条时下方出现翻页箭头，分页常量_PAGE_SIZE = 20；所有页依次处理，但拖动只在同页内生效：
⚠️ 想跨页换顺序，先翻页再拖，直接在原页拖是移不动的。
每条素材（JobListItem）上有四个按钮：✂️ 剪刀打开区间编辑器只修一段；▶️ 播放在内嵌播放器里打开并保持暂停，快速瞄原片；⋮ 三点（或右键）打开所在文件夹、复制路径、打开修复后的输出、重新加入队列（把已完成 / 失败 / 跳过项放回列表末尾）；✕ 移除。
控制按钮：▶ 开始处理列表中所有项目，含已完成与失败的——改完设置不用重新加文件，直接再按一次；按钮可用条件是列表非空、没有模型在下载、修复预览没占 GPU。■ 停止结束本次处理，当前条目回到等待中（_mark_stopped）。"清除已完成"移除完成项，"清空"移除全部。
⚠️ 停止后写到一半的输出文件会留在磁盘上，下次按你选的文件冲突策略处理——"跑到一半就停"与"覆盖"同时开着时，别把半成品当成品。
输出命名模板与保存位置
命名用模板，{original}代表输入文件名（不含扩展名），默认模板{original}_restored.mp4，所以my_video.mp4出片即my_video_restored.mp4。替换逻辑在folder_output_path里就一句output_pattern.replace("{original}", 输入文件名)（jasna/media/media_files.py）。
保存位置由工具栏两个联动控件决定：点与输入相同，结果落在原文件旁边；手动输入路径或点文件夹按钮选别处，会自动关闭"与输入相同"，想回到原片旁再点一次即可。改模板或目录的瞬间，任何会覆盖其他文件的条目会当场高亮，不用等跑完才发现重名。
文件冲突的三种策略
选项在基本处理部分：
| 策略 | 适合场景 | 结果文件名 |
|---|---|---|
| 跳过 | 已有结果的增量补跑 | 保持旧文件不动 |
| 覆盖 | 新结果直接替换旧文件 | 同名，旧文件被永久替换（选中后弹出 ⚠️ 提示） |
| 自动重命名（默认） | 批量出片、不想覆盖任何东西 | 追加_1之类后缀避开冲突 |
预设：一套参数一个名字
设置面板上方工具栏（_build_preset_bar）能把当前全部设置存成名字：建个"1080p 快速"、再建个"4K 最佳质量"，之后一键来回切。底层PresetManager（jasna/gui/models.py）有两点值得知道：get_last_selected()/set_last_selected()让重启后记住上次预设；手动改过设置后面板标记"已修改"，防止你以为还停在某个出厂预设上；出厂预设与用户预设分开管理，删出厂预设会被拒绝。
三、单视频与静态图精修
目标：个别视频和图片不走全局参数，单独伺候。
单视频检测参数只属于它自己
全局参数归预设管，但区间编辑器里设置的检测模型和检测阈值只保存给当前这一个视频，列表里其他条目保留各自的值——同一个列表可以混放"高阈值粗检"和"低阈值精检"的片子，互不干扰。输出模板冲突同样是逐条高亮，不是整列表一刀切。
实现细节：队列条目通过JobItem.try_set_video_options单独记录这些按视频覆盖的值（jasna/gui/models.py）。
交互式修图：换种子只看一帧
修单张图时别用"整任务重跑"的思路。在图像修复（静态图片）部分点交互式处理图片（入口在 jasna/gui/settings_sections/image_restoration.py），打开一个左右对比视图（窗口实现见 jasna/gui/interactive_image_restore.py）：
- 上一张 / 下一张逐张浏览；
- 换种子立刻重新渲染出图；
- 原图、遮罩、结果三种视图切换；
- 满意才点保存，只留你喜欢的。
⚠️ 用整任务重跑去精修单图，速度会差一个数量级——对比视图里换种子才是正路。
快的原因：渲染在后台 worker 线程按单帧进行，帧已预先准备好，换种子只是同一帧上的一次前向推理，不像整任务那样把解码、修复、编码全走一遍。
四、边修边看：实时预览
目标：不产出文件，直接看修复效果。
三步打开实时预览播放器
点页眉里的视频播放器（_open_video_player，见 jasna/gui/app.py）：
- 选检测模型、检测阈值，需要的话再选二次修复（RTX Super Res或UNet 4x）；
- 点选择视频挑片子；
- 按播放。
快捷键：空格播放 / 暂停，左 / 右方向键前后跳 30 秒；全屏时鼠标移到底部边缘，控制栏自动浮出。改了模型、阈值或二次修复后，会从当前位置重新播放（管线重建）。
⚠️ 播放器和批量处理互斥：有项目在处理、或修复预览在跑时，点"视频播放器"没反应且页眉按钮置灰——这是硬性检查，不是显示 bug。
已就绪秒数归零意味着什么
状态栏显示已提前修复好的秒数：后台修复线程往带时间戳的帧缓冲里写帧，缓冲最多领先播放 3 秒（BUFFER_SECONDS = 3.0），预滚 1.5 秒（PREROLL_SECONDS = 1.5）后才真正开声（实现见 jasna/gui/raw_player.py）；缓冲溢出时丢旧帧。
所以这个秒数反复掉到零，就是 GPU 在当前设置下追不上实时播放：画面卡等，音频暂停等你。此时换低一档的分辨率 / 模型再看。另有一条设计决定：播放器永远用 BasicVSR++，不用 LTX。
五、排错与日志
目标：出了问题时，快速定位是系统层、参数层还是运行层。
重跑系统检查
换了驱动、换了显卡、装了新 FFmpeg 之后，从页眉再次运行系统检查（_show_system_check，见 jasna/gui/app.py）。检查按版本记录通过状态，决定某个版本要不要重新走流程。
⚠️ AMD 用户：AMF 运行库缺失时 Linux 上要手动装一次（安装命令见 docs/zh/gui.md），装完重启 Jasna 再查一次，否则读写视频这条检查过不了。
导出日志：反馈前的一分钟
底部工具栏的日志按钮展开 LogPanel（jasna/gui/log_panel.py）：
- 实时滚动，可按 debug / info / warning / error 过滤；
- 导出保存最后 5000 行（环形缓冲
deque(maxlen=5000)，超出自动丢最旧的），写为.txt。
反馈问题前先导出日志，能省掉一大轮"复现了吗"。
读底部状态条
处理时底部显示 GPU 利用率、显存、内存、CPU。数据来自read_system_stats（jasna/gui/system_stats.py：NVIDIA 解析nvidia-smi，AMD 读 sysfs），轮询线程每 1.5 秒采样一次。跑任务时瞄一眼这排数字，显存吃紧就该降档了。
六、激活与支持者模型
目标：解锁 UNet 4x、SD 1.5、LTX 三个支持者模型。
在线与手动两条激活路径
页眉打开激活 Jasna（对话框在 jasna/gui/components.py），所有网络与验签操作都在后台线程执行（jasna/gui/activation_worker.py），不卡 UI。
- 在线激活（默认）：输入许可证码，点在线激活。上传到网络的只有许可证码和机器密钥，之后 Jasna 完全离线工作。
- 手动激活（断网机器或在线失败时）：
- 复制机器密钥（基于本机硬件生成）；
- 在任意联网设备打开激活页面（或点打开激活页面），填入机器密钥 + 许可证码，也可把两者发给你获取许可证码的渠道；
- 拿到激活密钥粘贴回 Jasna，点激活。
名额规则：什么算"新电脑"
一个许可证码最多用于3 台电脑或云工作区；已激活后打开该窗口会联网显示已用名额（如 2 / 3），查不到时重开窗口重试即可，修复功能不依赖这次查询。
占名额：更换主板（Windows）、重新安装 Linux、个别没有真正主板 ID 的 Windows 机换系统盘。
不占名额：重装 Windows、更换显卡 / 硬盘 / 内存、同一台机器重复激活——重新激活即可。
激活密钥被拒的四步排查
按顺序过一遍：
- 机器密钥是不是完整复制的？
- 激活密钥有没有截断？重新完整复制。
- 密钥是不是为旧版 Jasna 生成的？旧版密钥不再通用，需要回购买渠道换新密钥。
- 你手里的密钥是不是以
JW1-开头？那是云端 CLI 专用身份密钥，GUI 直接粘贴会被明确拒绝（license_cloud_cli_only）——请去正确的入口使用。
⚠️ 激活密钥只包含你许可证码里购买的模型，不会顺带解锁其他支持者模型。
许可证码仅能通过官方支持渠道获取；中文界面下，激活对话框和首次启动向导的页脚会出现闲鱼按钮，点一下显示卖家的闲鱼二维码，用闲鱼 App 扫码进卖家主页购买。界面顶部的闲鱼按钮同理。
收尾：症状速查与主线回顾
| 现象 | 第一排查点 | 处理 |
|---|---|---|
| 播放器秒数反复归零 | GPU 修复速度追不上播放 | 降分辨率 / 换模型档位 |
| 点"视频播放器"无反应 | 队列或预览占用 GPU | 等处理结束或按停止 |
输出文件名多了_1后缀 | 文件冲突 = 自动重命名生效中 | 基本处理 → 文件冲突 |
| 列表高亮某条目 | 命名模板会覆盖其他文件 | 改模板或保存位置 |
| 启动窗口卡住后报红行 | 30 秒兜底，检查没跑完 | 页眉重跑系统检查 |
| 首次启动报路径错误 | 安装路径含非英文字符 | 迁移到纯 ASCII 路径 |
启动日志有hard_disk_warning | 装在机械盘上 | 迁到 SSD |
激活提示license_cloud_cli_only | 粘了云端 CLI 密钥（JW1-开头） | 换回本地激活密钥 |
| 日志看不出问题 | 默认缓冲只有 5000 行 | 导出完整.txt再看 |
主线回顾：Jasna 的图形界面是一条"装对位置 → 批量喂入 → 按预设落盘 → 单视频微调 → 静态图精修 → 实时预览 → 日志排错 → 激活解锁"的旅程。界面里的每个约束——分页拖动、玩家器互斥、归零提示、名额校验——都能在其源码里找到一一对应的实现；这份指南既是操作手册，也是排错地图。
官方文档入口：docs/zh/gui.md
【免费下载链接】jasnaVideo restoration tool项目地址: https://gitcode.com/GitHub_Trending/ja/jasna
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
