Jasna 视频修复 GUI 实战指南：从首启卡红行到激活支持者模型，一次讲透
【免费下载链接】jasnaVideo restoration tool项目地址: https://gitcode.com/GitHub_Trending/ja/jasna
第一次打开 Jasna，启动窗口卡在"检查中"十几秒，弹出一行红字，主窗口迟迟不出现——多数新手都卡在这里。Jasna 是一个开源视频修复工具，GUI 支持批量喂入素材、实时预览修复效果、单图精修，并可激活解锁 UNet 4x、SD 1.5、LTX 等支持者模型。本文每个约束都能在源码里找到对应实现，出问题你知道往哪儿查。
🧭 首启自检：7 项检查逐项拆解
安装位置的两个硬条件
启动向导出现之前，安装位置必须先过关，两条都是硬性的：
- 装本地磁盘（Windows 用 NTFS，Linux 用 ext4 / Btrfs / XFS），网络磁盘不支持；
- 安装路径必须是纯 ASCII 字符，出现中文、日文或带重音的字母直接判失败。
路径讲究的根源：check_ascii_install_path直接对安装目录做encode("ascii")尝试，编码失败即不合规（逻辑在 jasna/os_utils.py）。
机械盘同理：install_on_hard_disk会判断磁盘类型——Windows 查驱动器的寻道开销，Linux 读/sys的rotational标志（逻辑在 jasna/os_utils.py）。装在机械盘上，日志面板会写一条hard_disk_warning警告："Jasna 安装在机械硬盘（HDD）上，启动和加载模型都很慢。请把 Jasna 文件夹移到固态硬盘（SSD）上"（逻辑在 jasna/gui/app.py）。这是警告不是错误，但启动和加载模型都会明显变慢。
⚠️ 路径装错是"一票否决"型问题：ASCII 检查失败会直接阻塞启动，之后所有操作都无从谈起。先
cd确认路径，再谈其他。
自检项到底在查什么
检查逻辑集中在 jasna/gui/system_checks.py，run_system_checks逐项填入结果，逐项含义如下：
| 检查键 | 查什么 | 失败后果 |
|---|---|---|
ascii_path | 安装路径是否纯英文 | 阻塞启动 |
ffprobe | 能否找到 ffprobe，且 FFmpeg 主版本号必须为 8（check_ffprobe里major != 8即失败） | 阻塞启动 |
gpu | 是否检测到受支持 GPU（架构与计算能力） | 阻塞启动 |
cuda | CUDA / ROCm 是否可用，报告版本与计算能力 | 阻塞启动 |
driver | GPU 驱动版本 | 阻塞启动 |
sysmem（仅 Windows） | NVIDIA 共享内存回退策略 | 仅警告，不阻塞 |
amf（仅 AMD） | AMD AMF 视频运行库，读写视频必需（check_amd_amf_runtime加载libamfrt64.so.1验证） | 阻塞启动 |
注意sysmem是源码里WARNING_ONLY_CHECKS = {"sysmem"}中唯一的键（逻辑在 jasna/gui/system_checks.py）：只有它失败时，底部按钮仍显示"开始使用"；其余任何一项失败，按钮变成"退出"，点击直接关程序。
卡住之后出现的红行是怎么回事
检查在后台线程跑，UI 每 100ms 轮询一次；如果驱动查询卡住或 torch 冷导入特别慢，向导等 30 秒就放弃（_CHECKS_TIMEOUT_SECONDS = 30.0，逻辑在 jasna/gui/wizard.py），先展示已完成的项。
⚠️ 兜底超时后未完成的检查项会被按失败处理而不是通过——
evaluate_check_results的文档写得很明确：从未运行的检查宁可读成失败，也不能"显示红行却放行开始使用"（逻辑在 jasna/gui/system_checks.py）。所以看到红行别急着重装环境，先确认是不是卡住了 30 秒。
检查结果按版本记录：只有该版本首次启动才强制走一遍流程，通过状态由get_system_check_passed_version与__version__对比决定（逻辑在 jasna/gui/app.py），之后可随时从页眉手动重跑，见文末排错部分。
装好跑通之后，第一批素材怎么喂进去？主窗口中间的项目列表就是答案。
📦 素材怎么喂进队列：排序、翻页与单条操作
三种添加方式与分页边界
把素材放进列表有三条路（实现在 jasna/gui/queue_panel.py）：
- 点添加文件按钮选视频或图片（
_on_add_files）； - 点旁边的文件夹图标，整个文件夹一次丢进来（
_on_add_folder，按 jasna/media/media_files.py 的folder_media_in_processing_order递归收集，图片在前、视频在后）； - 直接把文件拖到列表上（
enable_file_drop基于TkinterDnD，拖文件夹会同样递归展开）。
处理顺序就是从上到下：拖动每个条目的把手即可调整。列表超过 20 条时下方出现翻页箭头，分页常量_PAGE_SIZE = 20写在源码里（逻辑在 jasna/gui/queue_panel.py）。所有页都会被依次处理，但拖动只能在同一页内——拖拽重排的代码只按当前页的 widget 计算新位置，跨页换顺序得先翻页再拖。
每个条目上的四个按钮
对单个条目（JobListItem，见 jasna/gui/job_list_item.py）：
- 剪刀：打开区间编辑器，只修复视频里的一段（仅
PENDING状态可编辑）； - 播放：在内置播放器里打开该视频，快速瞄一眼原片（仅列表空闲时可用）；
- 三点（或右键）：打开所在文件夹、复制路径、打开修复后的输出、重新加入队列（把已完成/失败/跳过的项目放回列表末尾，见 jasna/gui/queue_panel.py 的
_requeue_job）； - 叉号：移除该项目。
中途停止后，写到一半的文件去哪了
处理中每个条目实时刷出进度、FPS 和剩余时间。点停止按钮结束本次处理后，当前条目回到等待中状态（_mark_stopped把job.status重置为PENDING，逻辑在 jasna/gui/processor.py），已写入的半成品输出文件则原样留在磁盘上。
⚠️ 半成品文件下次再跑时按什么处理，取决于基本处理里的文件冲突策略。"跑一半就停"和"覆盖"同时开着时，别把上次的半成品当成品——它会被下一次输出直接替换。
开始按钮会处理列表中所有项目，包括已完成和失败的（reset_jobs_for_run把所有 job 重置为PENDING，逻辑在 jasna/gui/queue_panel.py）——改完设置不用重新添加文件，直接再按即可。隐含限制：列表非空、没有模型在下载、修复预览没占用 GPU 时，开始按钮才可用（can_start = bool(jobs) and not self._preview_gpu_busy and not downloading，逻辑在 jasna/gui/app.py）。
⚙️ 输出文件怎么落地：命名模板、冲突策略与预设
命名模板与"与输入相同"的联动
结果放哪，看队列底部工具栏的两个联动控件：点与输入相同，每个结果保存在原文件旁边；手动输入文件夹路径或点文件夹按钮选别处，会自动关闭"与输入相同"。
命名用模板，{original}代表输入文件名（不含扩展名）。默认模板是{original}_restored.mp4（DEFAULT_OUTPUT_PATTERN，定义在 jasna/gui/models.py），所以my_video.mp4出片就是my_video_restored.mp4。替换逻辑很直白：folder_output_path里就是output_pattern.replace("{original}", 输入文件主名)（逻辑在 jasna/media/media_files.py）。
关键体验：改保存位置或模板的瞬间，任何会覆盖其他文件的条目会立即被高亮标出——_refresh_conflicts对每个PENDING条目重算输出路径并检查output_path.exists()（逻辑在 jasna/gui/queue_panel.py），不用等跑完才发现重名。
同名文件三种处理方式
文件冲突选项在基本处理部分（下拉框实现在 jasna/gui/settings_sections/basic.py），默认值file_conflict = "auto_rename"（逻辑在 jasna/gui/models.py）：
| 选项 | 行为 | 备注 |
|---|---|---|
自动重命名（auto_rename） | 输出改名为xxx (1).mp4这类不冲突的名字（unique_path） | 默认值 |
覆盖（overwrite） | 直接替换已有文件 | 选中后弹出 ⚠️ 提示（file_conflict_overwrite_warning） |
跳过（skip） | 已有文件时不动，状态标为SKIPPED | 适合增量补跑 |
⚠️ 选"覆盖"前确认目标文件确实可以丢——这个选项没有撤销，界面给出的唯一防线就是那枚警告图标（
_on_file_conflict_changed，逻辑在 jasna/gui/settings_sections/basic.py）。
预设一键切换，重启还会记住
不同画质的片子参数差很远，手动来回调很痛苦。设置面板上方的工具栏（_build_preset_bar，见 jasna/gui/settings_panel.py）能把当前全部设置存成一个名字：建个"1080p 快速"，再建个"4K 最佳质量"，之后一键来回切。
底层是PresetManager（逻辑在 jasna/gui/models.py），两点值得知道：
- 重启后记住上次预设：
get_last_selected()/set_last_selected()记录你最后一次用的名字，持久化在settings.json； - 手动改过设置后，面板会标记"已修改"（
{name}（已修改）*，见 jasna/gui/locales/zh.py），防止你以为还停在某个出厂预设上。出厂预设（FACTORY_PRESETS = {"Default": ...}）与用户预设分开管理，删除出厂预设会被delete_preset直接拒绝。
全局参数归预设管，但有两类例外只属于单个视频：在区间编辑器里设置的检测模型和检测阈值，只保存给当前这一个视频。队列条目通过JobItem.try_set_video_options单独记录这些按视频覆盖的值（逻辑在 jasna/gui/models.py），且仅在状态为PENDING时生效。也就是说，同一个列表里可以混放"高阈值粗检"和"低阈值精检"的视频，互不干扰。
想不产出文件、直接看效果时，走实时预览这条路。
🔍 不产出文件直接看效果：实时预览与单帧精修
打开播放器：三步操作和一个硬互斥
点页眉里的视频播放器（_open_video_player，逻辑在 jasna/gui/app.py）：
- 选检测模型、检测阈值，需要的话再选二次修复（RTX Super Res或UNet 4x，默认值为
secondary_restoration = "none"，逻辑在 jasna/gui/models.py）； - 点选择视频挑片子；
- 按播放。
⚠️ 播放器和批量处理互斥：只要有项目在处理、或修复预览在跑，点"视频播放器"没反应，页眉按钮也会置灰。源码里就是一句硬检查：
self._preview_gpu_busy或处理器在跑时直接return（逻辑在 jasna/gui/app.py）。它是硬性约束，不是显示 bug。
快捷键：左/右方向键前后跳转 30 秒（_SEEK_STEP_SECONDS = 30.0，逻辑在 jasna/gui/video_player.py）；全屏时鼠标移到底部边缘，控制栏自动浮出。改了模型、阈值或二次修复后，管线会重建并从当前位置重新播放。
秒数反复归零说明什么
状态栏显示已提前修复好的秒数：后台修复线程往带时间戳的帧缓冲里写帧，缓冲最多领先播放 3 秒（BUFFER_SECONDS = 3.0、BUFFER_FRAMES = 90），预滚 1.5 秒（PREROLL_SECONDS = 1.5）后才真正开声，实现见 jasna/gui/raw_player.py。缓冲满了之后写入端会等空位而不是丢帧——所以一旦修复速度跟不上，领先秒数会一路掉光。
所以这个秒数反复掉到零，就是 GPU 在当前设置下追不上实时播放：画面卡顿、音频暂停。此时换低一点的分辨率或模型档位再看，别怀疑软件坏了。
静态图单帧精修：快一个数量级
在图像修复（静态图片）部分点交互式处理图片（_open_interactive_image_restore，逻辑在 jasna/gui/app.py），打开一个左右对比视图（窗口实现在 jasna/gui/interactive_image_restore.py）：
- 上一张 / 下一张逐张浏览；
- 换种子立刻重新渲染出图；
- 原图、遮罩、结果三种视图切换；
- 满意才点保存，只留你喜欢的。
为什么快？渲染在后台 worker 线程按单帧进行，帧已预先准备好，换种子只是同一帧上的一次前向推理——不像整任务那样把解码、修复、编码全走一遍。修图这种"多试几次参数"的场景，快一个数量级。
🚑 出问题往哪儿查：日志、状态条与激活排错
重跑系统检查、导出日志与底部状态条
换了驱动、换了显卡、装了新 FFmpeg 之后，从页眉再次运行系统检查（_show_system_check，逻辑在 jasna/gui/app.py）即可——检查按版本记录通过状态，决定某个版本要不要重新走流程。
⚠️ AMD 用户：系统检查还会查 AMF 视频运行库。Linux 上需要手动安装一次（官方文档 docs/zh/gui.md 给出了
curl下载amf_installer的安装命令），装完重启 Jasna 再查一次。
底部工具栏的日志按钮展开 LogPanel（逻辑在 jasna/gui/log_panel.py）：实时滚动，可按 debug / info / warning / error 过滤；导出保存最后5000 行（环形缓冲deque(maxlen=_MAX_LOG_ENTRIES)，_MAX_LOG_ENTRIES = 5000，超出自动丢最旧的），写为.txt。反馈问题前先导出日志，基本能省掉一大轮"复现了吗"。
处理时底部状态条显示 GPU 利用率、显存、内存、CPU。数据来自read_system_stats（NVIDIA 解析nvidia-smi，AMD 读 sysfs），轮询线程每 1.5 秒采样一次（self._system_stats_stop.wait(1.5)，逻辑在 jasna/gui/app.py）。跑任务时瞄一眼这排数字，显存吃紧就该降档。
激活两条路径：在线与手动
支持者模型（UNet 4x、SD 1.5、LTX）需要激活。页眉打开激活 Jasna（_open_license_dialog，逻辑在 jasna/gui/app.py），所有网络与验签操作都在后台线程执行（_start起 daemon 线程，逻辑在 jasna/gui/activation_worker.py），不卡 UI。
- 在线激活（默认）：输入许可证码，点在线激活。上传的只有许可证码和机器密钥，之后 Jasna 完全离线工作；
- 手动激活（断网机器，或在线失败时）：
- 复制机器密钥（
machine.machine_key(cloud_workspace=False)，基于本机硬件生成）； - 在任意联网设备打开激活页面，填入机器密钥 + 许可证码；
- 拿到激活密钥粘贴回 Jasna，点激活（
start_activation写入本地 license）。
- 复制机器密钥（
名额规则：一个许可证码最多用于3 台电脑或云工作区（界面提示license_service_slots_full即"已用完 3 个注册名额"，见 jasna/gui/locales/zh.py）。占名额：更换主板（Windows）、重新安装 Linux、个别没有真正主板 ID 的 Windows 机换系统盘。不占名额：重装 Windows、更换显卡 / 硬盘 / 内存、同一台机器重复激活。已激活后打开该窗口会联网显示已用名额（如 2 / 3），查不到时重开窗口重试即可，修复功能不依赖这次查询。
激活密钥被拒怎么排查
按顺序过一遍：
- 机器密钥是不是完整复制的？
- 激活密钥有没有截断？重新完整复制。
- 密钥是不是为旧版 Jasna 生成的？旧版密钥不再通用，需回购买渠道换新密钥。
⚠️ 你手里的密钥是不是以
JW1-开头？那是云端 CLI 专用身份密钥，GUI 直接粘贴会被明确拒绝：start_activation和start_online_activation都会检查前缀并抛出license_cloud_cli_only（逻辑在 jasna/gui/activation_worker.py）——请去正确的入口使用。
另外记住一条：激活密钥只包含你许可证码里购买的模型，不会顺带解锁其他支持者模型。
收尾速查：症状 → 原因 → 去哪儿查
| 症状 | 大概率原因 | 去哪儿查 |
|---|---|---|
| 启动窗口卡住后报红行 | 30 秒兜底，检查没跑完被按失败处理 | 页眉重跑系统检查 |
| 首次启动报路径错误 | 安装路径含非英文字符 | 迁移到纯 ASCII 路径 |
启动日志有hard_disk_warning | 装在机械盘上 | 迁到 SSD |
| ffprobe 检查不过 | FFmpeg 主版本号不是 8 | 换装 FFmpeg 8 |
输出文件名带(1)后缀 | 文件冲突=自动重命名生效中 | 基本处理 → 文件冲突 |
| 列表高亮某条目 | 命名模板会覆盖其他文件 | 改模板或保存位置 |
| 停止后磁盘上有半成品文件 | 输出文件残留 | 按文件冲突策略处理后再跑 |
| 播放器秒数反复归零 | GPU 修复速度 < 播放速度 | 降分辨率 / 换模型档位 |
| 点"视频播放器"无反应 | 队列或预览占用 GPU | 等处理结束或停止 |
激活提示license_cloud_cli_only | 粘了云端 CLI 密钥（JW1-开头） | 换回本地激活密钥 |
主线总结：装对位置（ASCII 路径 + SSD）→ 批量喂入队列（分页内拖动排序）→ 按预设落盘（模板 + 冲突策略）→ 单视频微调（按视频覆盖检测参数）→ 实时预览验证效果（注意 GPU 互斥与秒数归零）→ 静态图单帧精修 → 日志/状态条排错 → 激活解锁支持者模型。界面里的每个约束（分页、互斥、归零提示、名额校验）都能在源码里找到一一对应的实现。
官方文档入口：docs/zh/gui.md
【免费下载链接】jasnaVideo restoration tool项目地址: https://gitcode.com/GitHub_Trending/ja/jasna
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
