Jasna 视频修复 GUI 完全指南：如何搞定系统检查、批量处理与激活排错的 5 个高频问题

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

Jasna 是一个开源的 GPU 视频修复桌面工具，内置 GUI 可批量修复视频与静态图片、实时预览修复效果，并通过激活解锁 UNet 4x、SD 1.5、LTX 等支持者模型。适合需要批量处理大量老旧素材、且出问题想快速定位到源码的用户。实际使用中最容易卡住的 5 个问题：

1. 停止后写到一半的输出文件去哪了，重跑会不会覆盖？
2. 为什么"视频播放器"按钮置灰、点了没反应？
3. 为什么玩家器状态栏的缓冲秒数反复归零？
4. 为什么输出文件名多出 (1) 后缀、队列条目被高亮？
5. 为什么粘贴激活密钥被拒，或提示"名额已满"？

环境预检：7 项检查、30 秒兜底与两类失败

启动向导之前，所有依赖都在后台线程里逐项检查，UI 每 100ms 轮询一次结果；30 秒兜底超时（_CHECKS_TIMEOUT_SECONDS，写在 jasna/gui/wizard.py）到期后直接展示已完成的部分。每项检查的判定口径：

阻塞项与仅警告项的区分写死在源码里：WARNING_ONLY_CHECKS这个集合里只有sysmem一个键，其余任何一项失败，底部按钮都从"开始使用"换成"退出"。机械盘检测（install_on_hard_disk查磁盘寻道开销或 sysfs 的 rotational 标志）不在向导内，只在日志面板写一条hard_disk_warning警告——软警告，不挡启动。

⚠️ 30 秒兜底后，从未跑完的检查项按失败计而不是通过（evaluate_check_results的明确设计：宁读成失败，也不让红行和"开始使用"同时出现）。看到红行先确认是不是卡住了，别急着换环境。

检查结果按版本记录：get_system_check_passed_version()与当前__version__不一致才强制走向导（jasna/gui/app.py），之后随时可从页眉重跑。主窗口打开后还有后台 CUDA 预热（_warm_up_cuda），首次跑任务不会卡冷导入。

环境通了，接下来按出问题的频率从高到低过 5 张任务卡。

按了停止，写到一半的输出文件去哪了？

怎么做：

1. 处理中按停止。stop()只做两件事：置停止标志、取消当前管线，不删任何文件。
2. 当前条目被_mark_stopped打回"等待中"（PENDING），未开始的条目原样留在队列。
3. 已写入的半成品输出文件留在磁盘上，不删不清理。
4. 再按开始：因为was_stopped为 True，_on_start只继续跑列表里的等待项，不会重跑已完成的。
5. 半成品文件重跑时按什么处理，取决于基本处理里的文件冲突策略（见第四张卡）；只想重跑个别失败项，用条目菜单里的"重新加入队列"（_requeue_job，把完成/失败/跳过项挪回列表末尾并置为等待）。

隐藏约束：

• "停止后条目回到等待中"是设计决定，不是回滚失败。
• 三个冲突策略的行为在_process_job里写死：skip记为跳过、auto_rename调unique_path改名、overwrite直接写。
• 队列非空、没有 LTX 模型在下载、预览没占 GPU 时开始按钮才可用（_update_start_button_state）。
• LTX 任务有断点工作目录：重跑时若检测到旧工作目录与当前配置对不上（ResumeMismatchError），会弹确认框问是否丢弃续跑。

去哪验证：jasna/gui/processor.py（_mark_stopped、_process_job）、jasna/gui/app.py（_on_start）。

想先看效果再正式跑，别走整条管线，直接开视频播放器——但它的按钮经常没反应，原因在下面。

为什么"视频播放器"按钮置灰、点了没反应？

怎么做：

1. 先看队列里是否有正在处理的条目，或修复预览是否在跑——这两者占着 GPU 时，点播放器没有任何反馈。
2. 源码里就一句硬检查：_preview_gpu_busy或处理器在跑时_open_video_player直接return（jasna/gui/app.py），按钮置灰由_update_video_player_button_state同步显示。
3. 等处理结束或先按停止，按钮恢复。
4. 打开后：选检测模型、检测阈值，需要时再选二次修复（RTX Super Res 或 UNet 4x）→ 选视频 → 按空格播放。
5. 快捷键：空格播放/暂停，左右方向键各跳 30 秒（_SEEK_STEP_SECONDS），F11 全屏；全屏时鼠标移到底部 8px 边缘（_FULLSCREEN_EDGE_PX）控制栏自动浮出。

隐藏约束：

• 播放器与批量处理互斥是硬约束，静默拒绝、不弹提示（设计决定），不是显示 bug。
• Topaz Video AI 作为二次修复在播放器里不可用：run_raw_restoration_pass（jasna/gui/raw_player.py）直接抛ValueError，这是源码写死的限制。
• 音频播放依赖 python-vlc 和 libVLC 3；缺失时自动退回静音的软件时钟（SoftwareClock），画面照常播。

去哪验证：jasna/gui/app.py（_open_video_player）、jasna/gui/raw_player.py（run_raw_restoration_pass）。

播放器打开后，状态栏那行"已缓冲秒数"就是判断 GPU 是否跟得上的尺子。

为什么玩家器的"缓冲秒数"反复归零？

怎么做：

1. 看状态栏显示的缓冲秒数：后台修复线程往带时间戳的帧缓冲里写帧，这个数表示比当前播放位置多修好了几秒。
2. 缓冲上限 3.0 秒 / 90 帧（BUFFER_SECONDS、BUFFER_FRAMES），要预滚满 1.5 秒（PREROLL_SECONDS）才真正开始播放，显示帧率按 30fps 折算（DISPLAY_FPS）。
3. 秒数反复掉到零，说明 GPU 修复速度低于播放速度：画面等帧、音频暂停。
4. 换低一档的分辨率或模型档位，从当前位置重播（改设置会重建管线）。
5. 同时瞄一眼底部状态条：它每 1.5 秒采样一次 GPU 利用率、显存、内存、CPU（read_system_stats，NVIDIA 解析nvidia-smi，AMD 读 sysfs），显存吃紧就该降档。

隐藏约束：

• 缓冲状态每 0.25 秒刷新一次（_BUFFER_STATUS_INTERVAL_SECONDS），数值跳得快不代表在抖。
• 缓冲写满时是写线程阻塞等待（背压），不丢旧帧——归零不是数据丢失，是修复跟不上。
• 播放器里的模型、阈值、二次修复改动后从当前播放位置重建管线重播，不是整片重跑。

去哪验证：jasna/gui/raw_player.py（TimestampFrameBuffer）、jasna/gui/video_player.py（_update_playing_buffer_status）。

效果确认后准备落盘，下一个问题通常出在文件名上。

为什么输出文件名多出 (1) 后缀、条目还被高亮？

怎么做：

1. 看队列上方工具栏：输出位置留空等价于"与输入相同"，结果落在原文件旁边；手动填路径或选文件夹会自动关掉"与输入相同"。
2. 命名用模板，默认{original}_restored.mp4（DEFAULT_OUTPUT_PATTERN，定义在 jasna/gui/models.py）；{original}被输入文件名替换，替换发生在folder_output_path（jasna/media/media_files.py）。
3. 目标文件已存在且文件冲突策略是默认的auto_rename时，unique_path把名字改成<原名> (1).mp4，最多尝试到 (9999)。
4. 想改行为，去基本处理的文件冲突下拉框：auto_rename（默认）/overwrite/skip（增量补跑用）。
5. 同一个列表里不同视频可以用不同的检测模型和阈值：按视频覆盖的参数由JobItem.try_set_video_options记录，仅在条目处于等待中状态时生效。

隐藏约束：

• 改保存位置或模板的瞬间，_refresh_conflicts（jasna/gui/queue_panel.py）立即重算每个等待条目的预期输出路径，会覆盖已有文件的条目立刻高亮——重名提前暴露，是设计决定。
• 队列每页 20 条（_PAGE_SIZE），超过才出现翻页箭头；拖动排序只能在同一页内完成，跨页调整要先翻页。
• 处理中队列里还能加文件、移除非当前条目，但正在处理的那一条受保护，拖不动也删不掉。

⚠️ 选overwrite时弹出的 ⚠ 是界面唯一的防线：已有文件被永久替换，没有撤销。确认目标文件确实可以丢再选它。

去哪验证：jasna/media/media_files.py（folder_output_path、unique_path）、jasna/gui/queue_panel.py（_refresh_conflicts）。

落盘稳了，最后一类问题通常出在激活支持者模型的时候。

为什么粘贴激活密钥被拒、或提示"名额已满"？

怎么做：

1. 页眉打开激活 Jasna。所有网络与验签操作都在后台线程跑（_start起的守护线程，jasna/gui/activation_worker.py），不卡 UI。
2. 在线激活（默认）：输入许可证码点在线激活，上传的只有许可证码和机器密钥，之后完全离线工作。
3. 断网机器：先复制机器密钥（本机硬件生成），在任意联网设备的激活页面填入机器密钥 + 许可证码，拿到激活密钥粘回来点激活。
4. 提示license_cloud_cli_only时，先检查密钥是否以JW1-开头——那是云端 CLI 专用身份密钥，GUI 直接拒绝。
5. 提示license_service_slots_full（"已用完 3 个注册名额"）时，一个许可证码最多注册 3 台电脑或云工作区，回购买渠道更换一台再激活。

隐藏约束：

• start_activation与start_online_activation都会先判前缀，JW1-开头直接抛ValueError，源码写死。
• 已激活后打开该窗口会联网查询已用名额（start_device_count），查不到时重开窗口重试即可，修复功能不依赖这次查询。
• 激活密钥只包含你许可证码里购买的模型，不会顺带解锁其他支持者模型（实测行为）。
• 读激活状态时JW1-身份同样按"未激活"计（read_license_info）。

⚠️JW1-开头的密钥是给受支持容器里的 Linux 命令行版用的，粘贴到 GUI 必然被拒——去正确的入口使用，别反复重试。

去哪验证：jasna/gui/activation_worker.py（start_activation）、jasna/gui/components.py（激活对话框）。

故障速查表

主线：环境预检（ASCII 路径 + FFmpeg 8 + GPU/驱动）→ 停止后先用文件冲突策略处理半成品 → GPU 空闲时才开播放器（硬互斥）→ 用缓冲秒数判断 GPU 是否跟得上实时 → 模板 + 冲突策略决定落盘 → 激活解锁支持者模型（避开JW1-）。界面里的每个约束都能在上面对应的源码位置找到一一对应实现。

参考入口

• 中文 GUI 文档：docs/zh/gui.md
• 中文 CLI 文档：docs/zh/cli.md
• 英文 GUI 文档：docs/en/gui.md
• GUI 模块：jasna/gui/
• LTX 模型与内核：jasna/ltx/
• 许可证：LICENSE

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