Jasna 批量视频修复：从启动卡住到成片落盘的排障手册

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

Jasna 是一款开源视频修复工具，GUI 版把批量队列、实时预览、预设管理和支持者模型激活整合进同一个窗口。本文不按功能清单罗列，而是按你实际会撞见的故障现象组织：启动向导卡住、开始按钮灰着、输出文件名不符合预期、预览追不上、密钥被拒，每种现象先讲会看到什么，再讲背后的机制，最后给出处置路径。核心关键词：Jasna 批量视频修复、Jasna 修复向导、Jasna 输出命名、Jasna 实时预览、Jasna 激活密钥。

⚠️ 启动向导卡在半路或某项不过

现象一：向导打开后一直转，迟迟不出结果。检查线程在后台跑，界面每 100 毫秒轮询一次；超过 30 秒（_CHECKS_TIMEOUT_SECONDS = 30.0）线程还没结束，向导就放弃等待，直接展示已有结果，没跑完的项目一律按失败计，不阻塞你退出。常见诱因是驱动查询挂起或 torch 冷导入慢。

现象二：某一检查项红叉。向导逐项覆盖：

• 安装路径必须是纯 ASCII 本地磁盘路径。检查函数把安装目录做一次 ascii 编码，编码失败即判负，目录里出现中文、日文、带重音字母都会失败。
• ffprobe 必须能调起，且解析出的 FFmpeg 主版本号必须恰好等于 8（if major != 8: return False）。版本 7 或 9 都不行，错误文案会把你机器上的实际版本号显示出来。
• GPU、CUDA/ROCm、驱动是硬性阻塞项；共享内存（sysmem）只进警告名单（WARNING_ONLY_CHECKS），失败也允许进主界面。

处置：对照上表定位红色项；路径含非 ASCII 就迁移安装目录，FFmpeg 版本不对就换 8.x 发行版。装完驱动后不用重装 Jasna，页眉的「系统检查」可以重跑，结果按版本记录，只有当前版本标记为未通过才会再弹向导。

另有一个不弹窗的隐患：安装目录落在机械盘上时，向导不会拦你，但日志面板会落一条hard_disk_warning。判定逻辑读块设备的 rotational 标志（Linux 走/sys/dev/block，Btrfs 匿名设备会回退到 mountinfo 里的真实源设备），Windows 走驱动查询寻道开销。

源码位置：jasna/gui/wizard.py（_poll_checks_thread）、jasna/gui/system_checks.py（check_ffprobe、evaluate_check_results、WARNING_ONLY_CHECKS）、jasna/os_utils.py（check_ascii_install_path、install_on_hard_disk、_parse_ffmpeg_major_version）、jasna/gui/app.py（_warn_if_installed_on_hard_disk）。

🔘 开始按钮为什么是灰的，第一支成片怎么落盘

按钮灰着时，旁边那句话就是诊断结果，三种原因按固定优先级显示：模型下载中 → 修复预览占用 GPU → 队列为空。三者同时不成立按钮才点亮。所以先看提示文案，别盲猜。

往队列加素材有三个入口：「添加文件」按钮（视频或图片）、相邻的整目录导入、直接把文件拖进队列区域（TkinterDnD 的 Drop 事件）。处理顺序固定从上到下；超过 20 条（_PAGE_SIZE = 20）自动分页，拖拽换序只在当前页内有效，翻页不影响执行顺序。

每条队列项上有四个入口：区间编辑器、送入播放器并暂停、三点菜单（打开所在文件夹 / 复制路径 / 打开已修复输出 / 把完成或失败的条目放回队尾）、叉号移除。跑起来后每行实时刷新进度百分比、FPS 与剩余时间。

两个容易误解的行为：

• ■ 停止：正在处理的条目退回等待状态，写了一半的输出文件留在磁盘上。再次按 ▶ 时，程序会识别「上次是被停止」的现场，只挑出等待状态的条目接着跑，已完成的不会重跑一遍。
• 中途改配置不需要重新导入文件：改完直接再按一次开始即可。

输出落盘位置由队列面板上方三个控件决定：「与输入相同」开关、输出文件夹路径、命名模板。模板里的{original}会被替换成输入文件名（不含扩展名），出厂默认是{original}_restored.mp4，所以my_video.mp4得到my_video_restored.mp4。选定输出文件夹会顺手关掉「与输入相同」，想恢复要再点一次开关。

源码位置：jasna/gui/app.py（_update_start_button_state、_on_start）、jasna/gui/queue_panel.py（_PAGE_SIZE、_on_add_files、_on_file_drop）、jasna/gui/job_list_item.py（JobListItem）、jasna/media/media_files.py（folder_output_path）、jasna/gui/models.py（DEFAULT_OUTPUT_PATTERN）。

📁 输出文件命名冲突

现象：队列条目被高亮了。输出路径或命名模板一变，相关条目会立刻被标出潜在撞名，不用等文件写出来才知道会打架。真撞上已有同名文件时，行为由「基本处理」分区的file_conflict下拉框决定，共三档：

处置建议：批量跑老素材时保持自动重命名；确认要刷新旧成片再切覆盖；用跳过可以把队列当「增量补跑器」用——已有的自动跳过，只补新文件。

源码位置：jasna/gui/settings_sections/basic.py（file_conflict下拉与警告图标逻辑）、jasna/gui/queue_panel.py（_refresh_conflicts）。

🔁 批量跑：预设、逐视频参数与图片对比

同一批素材往往需要两套参数。全局配置交给预设：设置面板顶部的预设工具条能把当前全部设置存成一个名字，旧版本存下的预设数据会自动迁移，出厂预设和用户预设分开存放，删出厂预设会被拒绝。预设管理器还会记住你最后用过的预设，重启后自动停在上次的位置。手动改过任意设置后面板会亮「已修改」标记，防止你以为当前仍是某个出厂方案。

有一类参数例外，按视频单独记账：在区间编辑器里设置的检测模型与检测阈值只属于当前这一条素材，队列里可以混放高阈值粗检和低阈值精检，互不干扰。

静态图片走「交互式处理图片」窗口，是左右对比视图：上一张/下一张、换种子立即重看、原图/遮罩/结果三种视图切换、只对满意的结果点保存。它比每次重跑整个任务快，是因为渲染放在后台 worker 线程按单帧执行，换种子只是在同一张已准备好的帧上再做一次前向推理。

源码位置：jasna/gui/settings_panel.py（_build_preset_bar）、jasna/gui/models.py（PresetManager、JobItem.try_set_video_options、_migrate_preset_dict）、jasna/gui/interactive_image_restore.py（_render、_change_seed、_save_current）、分区定义见jasna/gui/settings_sections/image_restoration.py。

🎬 预览播放器「就绪秒数」为什么反复归零

先给结论：这不是 bug，是 GPU 修复速度追不上播放速度。机制在带时间戳的帧缓冲：后台修复最多领先播放 3.0 秒（BUFFER_SECONDS = 3.0），预滚满 1.5 秒（PREROLL_SECONDS = 1.5）才真正开声；修复线程把帧写进环形缓冲，播放端按时间戳弹出到期帧，缓冲溢出时新帧顶掉旧帧。状态栏那个「已提前修复好的秒数」反复掉回零，就是写入速度长期低于消耗速度，音频会停住等画面。处置：降分辨率或减轻修复配置。

播放器交互：空格播放/暂停，左右方向键各跳 30 秒（_SEEK_STEP_SECONDS = 30.0），全屏时鼠标移到底部边缘控制栏自动浮现。修改模型、阈值或二次修复（可选 RTX Super Res 或 UNet 4x）后，管线重建并从当前位置继续。播放器固定走 BasicVSR++，不走 LTX 管线，全程不产生输出文件。

还有一个硬互斥：队列处理或修复预览任一在跑，播放器入口直接打不开，页眉按钮同时置灰。这是设计使然，避免你在点半天没反应时猜不出原因。

源码位置：jasna/gui/raw_player.py（BUFFER_SECONDS、PREROLL_SECONDS、pop_due、_would_overflow_locked）、jasna/gui/video_player.py（_SEEK_STEP_SECONDS、available_player_secondary_restorations）、jasna/gui/app.py（_open_video_player、_update_video_player_button_state）。

🔑 激活密钥被拒与日常维护项

UNet 4x、SD 1.5、LTX 是支持者模型，用前先激活。在线激活是快路径：输入许可证码走start_online_activation，此过程只上传许可证码和机器密钥，完成后离线使用。离线机器的手动路径：复制机器密钥（machine_key(cloud_workspace=False)由本机硬件生成）→ 在联网设备填机器密钥与许可证码（也可以把两个值直接发给出售方）→ 把拿到的激活密钥粘回 Jasna 点激活。

规则与边界：

• 一个许可证码覆盖 3 台电脑或云工作区；同机重复激活不占新名额，释放名额只有所有者能做。
• 换主板（Windows）或重装 Linux 视为新电脑；重装 Windows、换显卡/硬盘/内存不占名额，重新激活即可。
• 以JW1-开头的身份密钥是给云端 CLI 用的，粘进 GUI 会被显式拦截报license_cloud_cli_only。
• 中文界面下，激活对话框与向导页脚会出现「闲鱼」按钮（shows_xianyu_seller按当前语言判定），扫码直达卖家主页。

日常维护三件事，都有数字可依：处理期间底部工具条每 1.5 秒采样一次 GPU、显存、内存与 CPU（NVIDIA 解析nvidia-smi的 CSV，AMD 走 sysfs）；日志环形缓冲只留最后 5000 行（_MAX_LOG_ENTRIES = 5000，底层deque(maxlen=5000)），反馈问题前先点导出（export_log_entries_txt写成.txt），早于 5000 行以外的报错是找不回来的；语言包共 5 套（zh / en / ja / ko / th，位于jasna/gui/locales/），切换后已构建控件的文字立即刷新，完整生效需重启。

源码位置：jasna/gui/activation_worker.py（start_online_activation、start_activation、start_machine_key）、jasna/gui/app.py（系统状态轮询线程）、jasna/gui/log_panel.py（_MAX_LOG_ENTRIES）、jasna/gui/log_export.py、jasna/gui/system_stats.py（read_system_stats）、jasna/gui/components.py（激活对话框）、jasna/gui/locales/。更多细节见 docs/zh/gui.md、docs/zh/cli.md 与 docs/zh/streaming.md。

🩺 故障排查：症状 → 原因 → 处置

Jasna 的批量修复流程在熟悉以上现象后基本是单向的：修好向导、点亮开始按钮、管住命名模板、用预设压掉重复配置，剩下的就是盯着系统状态栏的 1.5 秒采样曲线跑完队列。

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