Jasna 视频修复 GUI 完整指南：自检、队列到激活排错

Jasna 视频修复 GUI 完整指南：自检、队列到激活排错

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

Jasna 是一款开源的视频修复工具，带图形界面：批量喂入打码或低画质素材，在 GPU 上逐帧修复，产出可用成片。但有一道隐形门槛多数人忽略了——安装位置本身会被启动时逐条盘查，路径里混进一个非英文字符就可能被拦在门外。读完本文，你可以带走三样东西：自检的硬性约束清单、输入/处理/输出三段主线的完整规则，以及支持者模型的激活与名额玩法。

启动自检门槛：硬性条件清单

首启向导会把环境逐项过一遍，结果如下（逻辑在 jasna/gui/system_checks.py 的run_system_checks）：

这套设计有两个值得注意的细节。其一，ASCII 判定不是文本比对，而是直接把安装目录路径做一次path_str.encode("ascii")，编码抛异常即不合规（check_ascii_install_path，jasna/os_utils.py）。其二，检查跑在后台线程，UI 每 100ms 轮询一次结果；驱动查询卡住或冷导入过慢时，向导等满_CHECKS_TIMEOUT_SECONDS = 30.0秒就收手，先展示已完成的部分（jasna/gui/wizard.py）。装到机械盘上不会拦截启动，但install_on_hard_disk会读磁盘类型（Windows 查寻道开销，Linux 读/sys的 rotational 标志），日志面板随后写一条hard_disk_warning——启动和加载模型都会明显变慢，建议迁到 SSD。

⚠️ 最反直觉的一条：从未跑完的检查项会被按失败计，而不是按通过计（evaluate_check_results）。所以看到红行先别换显卡，先确认是不是 30 秒兜底把它"误杀"了。

过了这道线，真正的干活才开始：素材、参数、落盘位置，是三个互不牵连的决定。

输入侧：素材入队的添加方式与排序边界

把素材放进项目列表有三条路（jasna/gui/queue_panel.py）：

1. 点"添加文件"，逐个挑选视频或图片；
2. 点旁边的文件夹按钮，整个目录一次入队；
3. 直接把文件拖到列表上，窗口基于TkinterDnD接住拖放。

处理顺序就是列表从上到下。每个条目（JobListItem，jasna/gui/job_list_item.py）带四个控件：

列表一超过 20 条，底部出现翻页箭头，分页常量_PAGE_SIZE = 20就写在源码里。拖动把手可以调整顺序，但只能在本页内拖；跨页换位得先翻页再拖。翻页只影响显示，处理时会按顺序把每一页全部跑完。

⚠️ 处理途中按"停止"，当前条目回到等待中（_mark_stopped，jasna/gui/processor.py），而写到一半的输出文件原样留在磁盘。下次再跑时它算不算成品，取决于"文件冲突"策略——策略若为覆盖，半成品会成为被替换对象。

素材就位后，问题变成拿什么参数跑。预设管理器是答案。

处理侧：预设保存切换与按视频参数覆盖

设置面板顶部的工具栏（_build_preset_bar，jasna/gui/settings_panel.py）能把当前全部设置存成一个名字。建一个"1080p 快速"、再建一个"4K 最佳质量"，之后一键来回切。底层是PresetManager（jasna/gui/models.py），四个特性值得记住：

• 切换即保存状态，set_last_selected()记录最后一个用的名字，重启后自动回到那里（get_last_selected()）；
• 手动改动任何设置后，面板会标记"已修改"，防止你以为还停在某个出厂档位上；
• 出厂预设与用户预设分开管理，删除出厂预设会被拒绝；
• 预设只管全局参数，下面两类例外归单个视频所有。

全局与按视频的分工：

• 全局参数：挂预设名下，对队列里所有条目生效；
• 按视频覆盖：在区间编辑器里设置的检测模型与检测阈值，只写入当前这一个视频（JobItem.try_set_video_options，jasna/gui/models.py），且仅在条目处于等待状态时生效。同一个列表里完全可以混放"高阈值粗检"和"低阈值精检"的片子，互不干扰。

还有一个隐含限制：点"开始"并不是只跑待处理项——它会处理列表中所有项目，包括已完成和失败的，改完设置无需重新添加，直接再按一次即可。但按钮的可用条件写在源码里，一条都不能少：列表非空、没有模型在下载、修复预览未占用 GPU（can_start = bool(jobs) and not self._preview_gpu_busy and not downloading，jasna/gui/app.py）。

参数侧落定，还差最后一问：文件落在哪、叫什么名字。

输出侧：命名模板与文件冲突策略选择

保存位置由队列上方两个联动控件决定：点"与输入相同"，每个结果存在原片旁边；手动输入或另选文件夹，"与输入相同"会被自动关闭，想回到原片旁再点一次即可。

命名走模板，{original}代表输入文件名（不含扩展名）。默认模板与替换逻辑：

{original}_restored.mp4 output_name = output_pattern.replace("{original}", 输入文件名)

常量DEFAULT_OUTPUT_PATTERN定义在 jasna/gui/models.py，替换发生在folder_output_path（jasna/media/media_files.py）。于是my_video.mp4出片就是my_video_restored.mp4。配套的即时反馈：改保存位置或模板的瞬间，任何会覆盖其他文件的条目会被立即高亮，不用等跑完才发现重名。

同名文件三种处理（下拉框在 jasna/gui/settings_sections/basic.py）：

⚠️ 覆盖不可撤销，界面唯一的防线是 ⚠️ 提示"现有文件将被永久替换"。选它之前先确认目标文件真可以丢，尤其是上次停止留下的半成品。

文件落地的问题解决后，别忘了还有另一种用法：不产出文件，先看效果。

免产出预览：实时预览与静态图单帧精修

实时预览：GPU 互斥与缓冲机制

页眉的"视频播放器"入口有一句硬检查：_preview_gpu_busy为真或处理器在跑时，_open_video_player直接return（jasna/gui/app.py）——玩家器和批量处理互斥，页眉按钮同时置灰。这是硬约束，不是显示 bug。

播放器背后有个追赶机制：后台修复线程把带时间戳的帧写进缓冲，缓冲最多领先播放BUFFER_SECONDS = 3.0秒，预滚PREROLL_SECONDS = 1.5秒后才开声，缓冲溢出时丢旧帧（jasna/gui/raw_player.py）。所以状态栏那个"已提前修复的秒数"若反复掉到零，就是当前设置下 GPU 追不上实时速度——画面卡等、音频暂停，降分辨率或换低一档模型再看即可。

操作上有三个快捷键：空格播放/暂停，←/→前后跳 30 秒；全屏时鼠标移到底边，控制栏自动浮出。改了模型、阈值或二次修复后，管线重建，从当前位置重新播放。

同样是先看效果，但入口与算力开销是两条完全不同的路。

静态图单帧精修：一个数量级的速度差

"图像修复（静态图片）"部分的"交互式处理图片"打开一个左右对比视图（jasna/gui/interactive_image_restore.py）：上一张/下一张逐张浏览；换种子立刻重渲染；原图、遮罩、结果三种视图随时切换；满意才点保存，只留下你想要的那张。

为什么快？整任务重跑像把整卷胶片重新洗一遍——解码、修复、编码全程走一次；单帧精修则像给同张照片重新上色：帧早已备好，后台 worker 线程（_worker_loop）只做同一帧上的一次前向推理。修图这种"多试几把参数"的场景，省掉的就是一个数量级。

效果仍不对时，先别怀疑软件，把目光转向环境与许可，下面这三件套按序使用。

诊断与解锁：日志导出、状态条与激活名额规则

诊断三件套：重跑检查、导出日志、看状态条

• 重跑系统检查：换驱动、换卡、装新 FFmpeg 后从页眉再跑一遍。通过状态按版本记录，某个版本只需强制走一次流程，之后随时可手动重查。
• 导出日志：底部日志按钮展开 LogPanel，可按 debug / info / warning / error 过滤；环形缓冲deque(maxlen=5000)只留最新 5000 行（_MAX_LOG_ENTRIES = 5000，jasna/gui/log_panel.py），导出存为.txt。反馈问题前先导出，能省掉一整轮"复现了吗"。
• 底部状态条：跑任务时显示 GPU 利用率、显存、内存、CPU，采样线程每 1.5 秒轮询一次（jasna/gui/app.py 的read_system_stats循环）。显存吃紧就该降档，数字会先替你说出来。

⚠️ AMD 用户：自检会查 AMF 视频运行库，读写视频都靠它。Linux 上需手动安装一次，docs/zh/gui.md 有现成命令，装完重启 Jasna 再查一次。

激活两条路径：在线、手动与名额规则

支持者模型（UNet 4x、SD 1.5、LTX）需要激活。页眉的"激活 Jasna"里，所有联网与验签都在后台线程执行（jasna/gui/activation_worker.py），界面不卡。

• 在线激活（默认）：填许可证码点"在线激活"，上传的只有许可证码和机器密钥，之后本机完全离线工作；
• 手动激活（断网机器或在线失败时）：复制机器密钥→ 在任意联网设备的激活页面填入机器密钥 + 许可证码 → 把拿到的激活密钥粘回 Jasna 点"激活"。

名额规则：一个许可证码最多覆盖3 台电脑或云工作区（界面提示license_service_slots_full即 3 个名额用满）。

激活密钥被拒时，按顺序过一遍：

1. 机器密钥是否完整复制？
2. 激活密钥是否被截断？重新完整复制一次。
3. 密钥是否为旧版 Jasna 生成？旧版密钥不再通用，回购买渠道换新。

⚠️ 密钥以JW1-开头？那是云端 CLI 专用的身份密钥，GUI 粘贴会被明确拒绝（license_cloud_cli_only，jasna/gui/activation_worker.py），请去对应入口使用。

另外记一条：激活密钥只含许可证码里购买到的模型，不会顺带解锁其他支持者模型。上述规则收敛后，都可以压进一张表。

一页速查：症状到处置动作

装对位置、路径纯英文是全部前提。队列、预设、模板构成流程主线。红行多为兜底误判，非环境损坏。

官方文档：docs/zh/gui.md

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