Jasna 视频修复 GUI 实战手册：从启动自检到排错全解

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

Jasna 是一个开源的视频修复工具：内置批量任务队列（BasicVSR++ / LTX 双引擎），带实时预览播放器和静态图片交互式精修，还能把整套设置存成预设一键切换。这篇手册面向两类人：第一次上手、想完成第一个修复任务的你；以及已经遇到问题、想定位到具体文件和函数的你。

快速导航：

1. 启动向导卡住或报红行 → 任务 1
2. 把素材批量加入队列并调整顺序 → 任务 2
3. 决定成品放哪、怎么命名、同名怎么办 → 任务 3
4. 跑出第一份成品并处理中途停止 → 任务 4
5. 不出片直接看效果 → 任务 5
6. 解锁 UNet 4x、SD 1.5、LTX → 任务 6
7. 常用设置怎么选 → 「常用选项决策表」
8. 快速定位故障 → 「高频问题五问速答」

任务1｜通过启动自检进入主界面

目标：启动向导每行全绿，进入主窗口；任何一行变红时，你能说出它对应哪个检查函数。

操作：

1. 启动 Jasna，向导在后台线程逐项自检，UI 每 100ms 刷新一次状态。
2. 等全部行判定完成：全绿点开始使用；有红行则按下面对照修复后重跑。
3. 修复对照：路径红行 → 迁到纯英文路径；ffprobe 红行 → 安装 FFmpeg；gpu / cuda / driver 红行 → 升级 GPU 驱动；AMD 的 amf 红行 → 安装 AMF 视频运行库，重启后再查。
4. 重跑入口：页眉系统检查按钮（_show_system_check，逻辑在 jasna/gui/app.py）。

边界：

🔒 安装目录会被直接做 ASCII 编码测试，失败即阻塞启动：check_ascii_install_path，定义于 jasna/os_utils.py。 🔒 ffprobe 主版本号必须等于 8，判定在check_ffprobe，定义于 jasna/gui/system_checks.py。 🔒 GPU 门槛：MIN_GPU_COMPUTE = (7, 5)（计算能力 7.5+）、MIN_DRIVER_VERSION = 580（Linux）/610（其他系统），定义于 jasna/os_utils.py。 🔒 只有sysmem是警告项：WARNING_ONLY_CHECKS = {"sysmem"}，定义于 jasna/gui/system_checks.py。其余任一项失败，底部按钮直接变成"退出"。 🔒 自检总时限_CHECKS_TIMEOUT_SECONDS = 30.0，定义于 jasna/gui/wizard.py。超时后未跑完的项按失败处理，evaluate_check_results的注释写得很明确：宁可显示红行，也不能显示红行还放行"开始使用"。 🔒 装到机械盘不阻塞，只写hard_disk_warning警告，判定函数install_on_hard_disk，定义于 jasna/os_utils.py。 🔒 检查按版本记录：get_system_check_passed_version/set_system_check_passed_version，定义于 jasna/gui/models.py。每个版本只强制走一遍，之后可随时手动重跑。

验证：所有行显示 ✓，开始使用按钮点亮。仍有红行时，对照run_system_checks的键名（ascii_path、ffprobe、gpu、cuda、driver、sysmem、amf）逐个查 jasna/gui/system_checks.py 和 jasna/os_utils.py 里对应的检查函数。

任务2｜把素材批量加入修复队列

目标：把第一批视频或图片放进左侧队列，顺序可调，重复项不会入队两次。

操作：

1. 点添加文件选择视频或图片。支持的扩展名在 jasna/media/media_files.py 中写死：视频.mp4.mkv.avi.mov.wmv.flv.webm，图片.jpg.jpeg.png.bmp.webp.tif.tiff。
2. 点旁边的文件夹图标，整个文件夹一次导入，递归扫描，图片排在视频前面（folder_media_in_processing_order）。
3. 也可以直接把文件拖到列表区域（基于 TkinterDnD，enable_file_drop）。
4. 按住条目左侧把手拖动调整处理顺序；列表底部点清除已完成可只留下未完成项。

边界：

🔒 分页常量_PAGE_SIZE = 20，定义于 jasna/gui/queue_panel.py。超过 20 条才出现翻页箭头，且拖动只能发生在同一页内，跨页换顺序要先翻页。 🔒 同一文件重复添加会被静默忽略，add_job里有any(j.path == path for j in self._jobs)的去重判断。 🔒 处理中（processing）的条目不能拖动，_on_widget_drag_start会直接返回。

验证：列表底部计数实时更新为"已加入 N 项"；新条目状态显示"等待中"。拖不动或文件没出现时，查add_job与_on_file_drop，都在 jasna/gui/queue_panel.py。

任务3｜设定输出命名与冲突策略

目标：在开跑之前确定成品落地位置和命名规则，并让"会覆盖其他文件"的条目当场高亮，而不是跑完才发现重名。

操作：

1. 队列上方点与输入相同，成品保存在原文件旁边。
2. 想换位置：在输出路径框输入文件夹或点文件夹按钮，"与输入相同"会自动取消高亮；想回到原片旁再点一次即可。
3. 修改命名模板，{original}代表输入文件名（不含扩展名）。
4. 在基本处理设置区把文件冲突下拉为三种之一：auto_rename/overwrite/skip（控件在 jasna/gui/settings_sections/basic.py）。

边界：

🔒 默认模板DEFAULT_OUTPUT_PATTERN = "{original}_restored.mp4"，定义于 jasna/gui/models.py。my_video.mp4的成品就是my_video_restored.mp4。 🔒 默认冲突策略file_conflict = "auto_rename"，定义于 jasna/gui/models.py。重命名由unique_path生成带(N)编号的名字，定义于 jasna/media/media_files.py。 🔒 选overwrite后下拉框旁出现 ⚠️ 提示"现有文件将被永久替换"，没有撤销，这是界面唯一的防线。 🔒 改保存位置或模板的瞬间，_refresh_conflicts会立即重算所有 PENDING 条目的冲突高亮，定义于 jasna/gui/queue_panel.py。

验证：小样跑一个文件，成品名字与位置符合预期。名字出现(1)编号说明auto_rename生效；想改策略或模板，改动处都在folder_output_path，定义于 jasna/media/media_files.py。

任务4｜跑完第一个完整修复任务

目标：拿到第一份成品；中途停止后知道半成品去哪了、条目状态为什么变回等待。

操作：

1. 设置面板顶部选预设（出厂预设Default前带 🔒 标记），或直接手动调参数。
2. 点开始，处理中每个条目实时刷出进度条、FPS 与 ETA。
3. 需要叫停就点停止，剩余条目保持等待状态。
4. 完成后，用条目右侧 ⋯ 菜单打开修复后的输出查看成品；失败或跳过的条目可点重新加入队列放回列表末尾（_requeue_job）。

边界：

🔒开始会处理列表里所有项目，包括已完成和失败的：_on_start在 jasna/gui/app.py。改完设置不用重新加文件，直接再按一次即可。 🔒 开始按钮只在三个条件同时满足时可用：列表非空、没有 LTX 模型在下载、预览没占 GPU，判定在_update_start_button_state。 🔒 停止后当前条目回到PENDING：_mark_stopped，定义于 jasna/gui/processor.py。已写入的半成品输出文件原样留在磁盘上，下次按你的文件冲突策略处理。 🔒 按视频覆盖的参数（检测模型、检测阈值、区间）仅在条目为PENDING时生效：try_set_video_options，定义于 jasna/gui/models.py。因此同一个列表可以混放"高阈值粗检"和"低阈值精检"的视频。 🔒 模型按任务类型缓存：连续视频任务复用同一个会话，_ensure_video_session，定义于 jasna/gui/processor.py，切换图片任务时才会卸载。

验证：条目状态变为"已完成"并显示耗时，成品文件能正常播放。任务失败时状态变ERROR并带错误信息，异常分支（skip / error / 停止）都在_process_job，定义于 jasna/gui/processor.py。

任务5｜用实时预览核对修复效果

目标：不产出文件直接看修复效果；秒数表现不对时，能判断是设置问题还是 GPU 追不上。

操作：

1. 点页眉视频播放器按钮，或直接在队列条目上点 ▶。
2. 选择视频后播放；空格播放/暂停，左/右方向键前后跳转。
3. 修改模型、阈值或二次修复后，从当前位置重新播放（管线重建）。
4. 满意后关闭，回到批量处理。

边界：

🔒 播放器与批量处理互斥：_open_video_player在_preview_gpu_busy或处理器运行时直接return，定义于 jasna/gui/app.py。这是源码里的硬性检查，按钮同时会置灰，不是显示 bug。 🔒 帧缓冲最多领先播放 3 秒：BUFFER_SECONDS = 3.0，预滚门槛PREROLL_SECONDS = 1.5，定义于 jasna/gui/raw_player.py。缓冲溢出时丢旧帧。 🔒 跳转步长_SEEK_STEP_SECONDS = 30.0，定义于 jasna/gui/video_player.py。 🔒 Topaz 二次修复（tvai）在播放器内不可用，run_raw_restoration_pass会直接抛错，定义于 jasna/gui/raw_player.py。

验证：状态栏的"已提前修复秒数"持续上升，说明 GPU 跟得上实时播放。它反复掉回零，说明当前设置下修复速度低于播放速度，先降max_clip_size（默认 90，定义于 jasna/gui/models.py）或换更快的模型档位再看。

任务6｜激活解锁支持者模型

目标：完成激活后使用 UNet 4x、SD 1.5、LTX；被拒的激活密钥能按顺序排查。

操作：

1. 页眉打开激活 Jasna对话框，所有网络与验签操作都在后台线程执行，不卡 UI（jasna/gui/activation_worker.py）。
2. 在线激活：输入许可证码，点在线激活。上传的只有许可证码和机器密钥，之后 Jasna 完全离线工作。
3. 手动激活（断网机器或在线失败时）：复制机器密钥→ 在任意联网设备填机器密钥 + 许可证码 → 把拿到的激活密钥粘回 Jasna 点激活。
4. 已激活状态下重开窗口可查已用名额；查询失败就重开窗口重试，修复功能不依赖这次查询。

边界：

🔒JW1-开头的密钥是云端 CLI 专用身份，GUI 粘贴会被明确拒绝：license_cloud_cli_only，判定在 jasna/gui/activation_worker.py。 🔒 一个许可证码最多 3 台设备或云工作区，占满时的提示键license_service_slots_full，定义于 jasna/gui/locales/zh.py。 🔒 激活密钥只解锁许可证码里购买的模型，不会顺带解锁其他支持者模型。

验证：页眉许可证状态芯片更新为已激活（_refresh_license_chip，jasna/gui/app.py）。密钥被拒时按顺序查：机器密钥是否完整复制 → 激活密钥是否截断 → 密钥是否为旧版生成（需回购买渠道换新）→ 是否粘成了JW1-云端密钥。

常用选项决策表

以下取值全部来自AppSettings的真实字段与默认值，定义于 jasna/gui/models.py：

预设工具栏能把当前全部设置存成一个名字（PresetManager，定义于 jasna/gui/models.py），出厂预设FACTORY_PRESETS = {"Default"}不可删改；get_last_selected/set_last_selected让你重启后还停在上次用的预设上。

高频问题五问速答

问：启动向导卡了十几秒后报红行，是环境坏了吗？未必。30 秒兜底超时后，没跑完的检查项按失败处理（evaluate_check_results，jasna/gui/system_checks.py）。先按页眉系统检查重跑一次再下结论。

问：成品文件名多了(1)或_1后缀？文件冲突默认auto_rename生效中，unique_path（jasna/media/media_files.py）自动编号避让。不想编号就去基本处理改策略。

问：点"视频播放器"没反应，按钮也没置灰提示？队列正在处理或预览占着 GPU，_open_video_player（jasna/gui/app.py）直接返回。等本轮处理结束或点停止再开。

问：激活密钥被拒，怎么排查？先看是不是粘了JW1-开头的云端 CLI 密钥（license_cloud_cli_only），再确认机器密钥与激活密钥都完整复制，旧版生成的密钥需回购买渠道更换。

问：日志里看不出问题，反馈前我该给什么？导出日志按钮会把最近 5000 行（_MAX_LOG_ENTRIES = 5000，jasna/gui/log_panel.py）存成 .txt。缓冲超出的最旧行已丢失，先导出再看。

底部状态条的 GPU 利用率、显存、内存、CPU 每 1.5 秒采样一次（轮询在 jasna/gui/app.py，读取逻辑read_system_stats在 jasna/gui/system_stats.py），跑任务时显存吃紧就降档，这是最快的排错信号。

主线收尾：装到纯 ASCII 路径 → 自检全绿 → 队列喂满并分页内排序 → 定模板与冲突策略 → 跑批并处理停止残留 → 实时预览验证（注意互斥与秒数归零）→ 按视频覆盖检测参数精修 → 日志与状态条排错 → 激活解锁支持者模型。界面里的每个约束——分页、互斥、名额校验、超时判败——都能在 jasna/ 目录下找到一一对应的实现。

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