VideoEnhancer

VideoEnhancer 是一个面向 Windows 的视频增强工具，作为 3FUI 插件和命令行程序使用。它负责连接 FFmpeg、RVE 后端、推理模型与任务队列，提供视频超分辨率、运动补帧、RTX VSR / RTX Video HDR、图片推理和批处理能力。 原作者：user-wing

当前稳定版本及发行日期以 GitHub Releases 为准。

• 通过 3FUI 图形界面管理视频增强任务、模型、推理后端和处理顺序。
• 通过 videoenhancer.exe 提供命令行处理入口，适合脚本和批量任务。
• 支持视频超分辨率、仅补帧、超分与补帧组合处理，以及 NVIDIA RTX VSR 和 RTX Video HDR。
• 支持图片单张推理和图片文件夹处理；FlashVSR 与 BasicVSR++ 通过无损单帧视频桥处理图片。图片超分已独立为专用页，引擎与模型沿用超分工作台的当前选择。
• 支持 NCNN/Vulkan、CUDA/PyTorch、TensorRT、ONNX、FlashVSR、BasicVSR++ 和 RTX VSR 超分后端。
• 支持为 Windows 图片文件注册“超分辨率 → 模型”当前用户级联右键菜单，结果固定输出为 PNG。
• 支持按视频保存“分段超分”配置；默认按秒设置断点并自动吸附附近关键帧，仍可切换到精确帧模式。默认要求 NCNN/CUDA/TensorRT/ONNX 单帧模型保持同一模型后端；跨模型后端混用作为实验功能，需手动开启。FFmpeg 缩放与 Anime4K 可正常参与分段；固定倍率模型存在时由模型倍率统一决定整片输出尺寸。
• 支持 NCNN、CUDA/PyTorch 和 TensorRT 补帧后端；RIFE TensorRT Engine 会按当前设备自动构建。
• 支持 upscale-first 与 interp-first 两种组合顺序；跨后端阶段使用临时无损中间文件。
• TensorRT Engine 按 GPU、运行时版本、输入尺寸、倍率、分块、精度和转换配置隔离缓存，并在失效时重建。
• 模型列表支持从 ModelScope 镜像读取、下载、校验和解压。
• RTX 任务支持暂停与恢复，输出容器按输出扩展名直连（mkv/mp4/webm 等全部 FFmpeg 封装器），3FUI 编码参数（预设、调优、码率、CQ）直接传入 RTX 编码器。
• 插件更新检查使用 GitHub Release 首选、ModelScope 兜底；更新包下载使用 ModelScope 首选、GitHub 兜底，均带 SHA-256 校验，由 videoenhancer.exe 自行升级和回滚。

• 本体发布：https://github.com/maxzrb/VideoEnhancer/releases
• 本体镜像：VideoEnhancer-Releases
• 模型镜像：VideoEnhancer-Models

每个 Release 分别发布运行时更新包、首次安装器、手动安装 ZIP、更新清单及第三方组件对应源码：

VideoEnhancer-<version>-win-x64.exe
VideoEnhancerInstaller-<version>-win-x64.exe
VideoEnhancer-<version>-manual-install.zip
aria2-next-2.5.6-source.tar.gz
stable.json

VideoEnhancer-<version>-win-x64.exe 是内嵌插件 DLL 的运行时更新包；VideoEnhancerInstaller-<version>-win-x64.exe 是首次安装器，内含插件 DLL、运行 EXE、独立的 aria2-next 及许可材料。模型、Python、FFmpeg 和其他大型资源需按需获取。

• Windows 10 1809 或更高版本，64 位系统。videoenhancer.exe 是自包含单文件，不要求另外安装 .NET。
• 安装 Microsoft Visual C++ 2015–2022 x64 运行库。便携 Python 及部分推理扩展仍依赖该运行库。
• CUDA/PyTorch、TensorRT、FlashVSR 和 BasicVSR++ 需要 NVIDIA GPU。当前后端包含 CUDA 13.0，建议使用 580 或更高版本的 NVIDIA 驱动。
• RTX VSR / RTX Video HDR 需要 NVIDIA RTX 20 系及以上显卡、555 或更高版本的驱动和 RTX Video sidecar 运行组件。运行组件包发布在模型仓库 Bin/rtx-video/RTXVideoRuntime_20260914.7z，解压到 Plugin\videoenhancer\bin\ 并重启 3FUI 即可。sidecar 基于 Zennmn/RTXHDR-RTXVSR（MIT）定制；本项目修改源码发布在 maxzrb/RTXHDR-RTXVSR，包内 NVIDIA SDK 运行库为 NVIDIA 专有组件，按其许可随显卡环境使用。
• NCNN 使用显卡驱动提供的 Vulkan 运行时，不要求安装 Vulkan SDK；显卡和驱动至少需要支持 Vulkan 1.0。

插件的环境检查会针对当前选择的后端实际导入关键模块并检查 GPU/执行提供程序，不会加载模型或 TensorRT Engine。若新机器不能运行，请先按检查结果处理 VC++ 运行库或显卡驱动问题。

1. 安装或准备可运行的 3FUI。
2. 从 GitHub Release 下载 VideoEnhancerInstaller-<version>-win-x64.exe。
3. 双击安装程序，点击“选择目录”，选中包含 FFmpegFreeUI.exe 的 3FUI 根目录，然后点击“安装”。
4. 启动 3FUI，打开「视频超分」插件页面。
5. 在模型下载页刷新远端清单，按当前后端下载需要的模型和运行环境。

插件配置固定保存在：

Plugin\videoenhancer\videoenhancer.plugin.json

插件首次启动时会尝试迁移旧版配置；已有模型和用户文件会保留。

如需移除插件，先关闭 3FUI，再删除 Plugin\videoenhancer.3fui.dll 和 Plugin\videoenhancer 目录；删除前请备份其中的模型与配置。

安装后的目录结构为：

Plugin\
├─ videoenhancer.3fui.dll
└─ videoenhancer\
   ├─ videoenhancer.exe
   ├─ videoenhancer.plugin.json
   ├─ cache\...（运行缓存）
   ├─ .work\...（临时工作文件）
   ├─ .update\...（已下载的更新包）
   ├─ THIRD-PARTY-NOTICES.txt
   ├─ licenses\...（第三方许可证与来源说明）
   ├─ bin\aria2-next\aria2-next.exe（独立 GPL 下载组件）
   ├─ bin\embedded-tools\...（随版本同步的 Python 辅助脚本）
   ├─ bin\ffmpeg\ffmpeg.exe
   ├─ bin\rtx-video\runtime\vsr_backend.exe（RTX 运行组件，可选）
   ├─ python\python\python.exe
   ├─ python\backend\rve-backend.py
   └─ models\...

首次运行时，安装程序可以创建 models、python 和 bin 目录；模型下载页也可以按资源类别自动放置文件。

插件文件、配置、更新文件和运行缓存保存在 Plugin\videoenhancer。临时文件和子进程缓存分别使用其中的 .work 与 cache 目录。

TensorRT 不依赖远端预置 Engine。任务启动时会根据当前视频和设备配置生成或复用本地 Engine。没有 NVIDIA/TensorRT 环境时，应选择 NCNN 或其他可用后端。

BasicVSR++ 与运动补帧不能同时启用；切换到 BasicVSR++ 时，插件会关闭并禁用补帧开关，切回可组合后端后保持关闭但恢复可操作。

“分段超分”默认使用按秒模式：页面先读取视频时长和关键帧，新增或修改断点时会自动吸附到附近��键帧，并始终自动覆盖完整时长；需要逐帧边界时可切换到精确帧模式。默认情况下，NCNN、CUDA/PyTorch、TensorRT、ONNX 单帧模型之间不得跨模型后端混用；这是为了降低环境依赖和后端切换失败概率。页面提供默认关闭的“测试功能：跨模型后端混用”布尔开关，只有手动开启后才允许跨这些模型后端。FFmpeg 的 Lanczos/Bicubic/Bilinear/Nearest/Area/Spline 等缩放方式和 Anime4K libplacebo 着色器不受该实验门禁影响，可与单一模型后端正常组合。FFmpeg 硬拉与 Anime4K 由 CLI 直接启动 FFmpeg 处理，不再经 Python 逐帧 rawvideo pipe：纯自定义任务直接从源视频滤镜到最终编码；混合任务中只有模型段生成无损中间块，自定义段直接从原视频进入最终 filter_complex，再与模型块一次 concat/编码。运行日志中的 SEGMENTED_DIRECT_DONE / SEGMENTED_DIRECT_GRAPH 可用于观察直连 FFmpeg 阶段。若存在 2x/4x 等固定倍率模型，所有固定倍率模型必须倍率一致，且该倍率优先决定整片输出分辨率，FFmpeg/Anime4K 段自动跟随；若全片只使用 FFmpeg/Anime4K，则所有段使用统一的自定义目标宽高。当前分段模式仍不与运动补帧、RTX HDR 或 PQ/HLG HDR 输入组合。

补帧模型建议放在：

models\Frame-Interpolation\

常见目录示例：

models\Frame-Interpolation\RIFE\rife4.25.pkl
models\Frame-Interpolation\RIFE\rife4.26.pkl
models\Frame-Interpolation\RIFE\rife4.26.heavy.pkl

旧版 models\RIFE 路径仍提供兼容读取，但新下载使用 Frame-Interpolation 目录。TensorRT 补帧目前使用 RIFE 权重；GIMM-VFI 和 GMFSS 通过 CUDA/PyTorch 路径使用。

查看帮助：

.\videoenhancer.exe -h

• HDR（PQ/HLG）处理使用 16-bit 中间格式。
• HDR 目前要求 CUDA/PyTorch、TensorRT、BasicVSR++ 或 RTX VSR/HDR；NCNN、ONNX、FlashVSR 会明确拒绝不兼容配置。
• 同一后端的组合处理在单进程内完成，跨后端时使用临时 FFV1 无损中间视频。
• RTX VSR 与补帧组合时固定先补帧、再 RTX；RTX HDR 始终最后执行。
• RTX 输出直接写入最终容器（按输出扩展名选择 FFmpeg 封装器）。容器装不下的流（如 TrueHD 进 MP4）会报 FFmpeg 原生错误；TrueHD/全景声源建议输出 mkv。
• 源视频已是 PQ/HLG 时，RTX HDR 会拒绝重复映射。
• 临时中间文件在任务结束后清理；任务停止时会尽量保留已经生成的有效输出。

模型下载默认使用：

AerithDream/VideoEnhancer-Models

可通过 VIDEOENHANCER_MODELSCOPE_DATASET=owner/name 切换仓库。私有仓库使用 VIDEOENHANCER_MODELSCOPE_TOKEN 或 MODELSCOPE_API_TOKEN。令牌不会写入项目配置。

模型页面会显示资源分类、安装状态、文件大小和下载进度。下载压缩包后会自动解压到对应目录，并使用安装标记避免重复处理。

插件更新顺序如下：

1. 优先从 GitHub maxzrb/VideoEnhancer 的最新 Release 读取 stable.json。
2. GitHub 检查失败时，从 ModelScope AerithDream/VideoEnhancer-Releases 读取 stable.json。
3. 下载更新包时优先使用 ModelScope 镜像，失败后使用 GitHub Release 资产。
4. 下载完成后校验 EXE 大小和 SHA-256。
5. 用户确认后，插件复制已校验的运行 EXE 为临时更新器，关闭 3FUI。
6. 更新器等待 3FUI 退出，替换运行 EXE 和插件 DLL；失败时按事务日志恢复旧文件。独立的 aria2-next 和模型不参与本体更新。
7. 更新器重新启动 3FUI，插件显示更新结果。

可配置环境变量：

• VIDEOENHANCER_UPDATE_GITHUB_REPO=owner/name
• VIDEOENHANCER_UPDATE_GITHUB_TOKEN
• VIDEOENHANCER_UPDATE_DATASET=owner/name

发现新版本后，可在插件界面确认更新。

先确认以下文件存在：

bin\ffmpeg\ffmpeg.exe
python\python\python.exe
python\backend\rve-backend.py
models\

模型库、补帧模型库和当前设备不兼容的 TensorRT Engine 属于可选资源，不应阻止插件页面启动。选择 TensorRT 或 CUDA 时，仍需准备对应的 NVIDIA 驱动、运行时和模型权重。

BasicVSR++ 不支持与补帧组合。切换到 TensorRT、CUDA、NCNN 或其他可组合超分后端后，补帧开关会恢复可点击，但默认保持关闭。

确认使用的是 PTH 源模型、当前输入尺寸和分块参数有效，并检查 Python/TensorRT/Torch-TensorRT 环境。Engine 会在首次任务启动时构建，本机没有 NVIDIA 时无法完成该流程。

确认 3FUI 已退出、当前用户可写 Plugin 目录，且 videoenhancer.3fui.dll 位于 Plugin、videoenhancer.exe 位于 Plugin\videoenhancer。如安装在受保护目录，需由用户使用有权限的账户运行 3FUI。更新失败结果保存在 Plugin\videoenhancer\.update\update-result.txt。

要求安装 .NET 10 SDK。插件还需要 3FUI 构建目录中的 FFmpegFreeUI.dll 和 LakeUI 5.1+（仅支持 5.x）。

仓库根目录的 VideoEnhancer.slnx 包含插件与 CLI；CLI 对插件声明了构建依赖， 因此不会再依赖预先存在的 videoenhancer.3fui.dll：

dotnet build .\VideoEnhancer.slnx -c Release `
  "-p:HostBin=C:\path\to\FFmpegFreeUI\bin\Release\net10.0-windows10.0.26100.0"

生成安装程序和手动安装包：

dotnet publish .\VideoEnhancer.slnx -c Release `
  "-p:HostBin=C:\path\to\FFmpegFreeUI\bin\Release\net10.0-windows10.0.26100.0"

HostBin 也可以通过环境变量 VIDEOENHANCER_HOST_BIN 设置。若仓库与 FFmpegFreeUI 并列放置，项目会优先自动发现相邻的 Release、其次 Debug 输出。 解决方案发布会生成图形安装程序、运行 EXE 和手动安装 ZIP，并放在仓库根目录的 Artifacts：

Artifacts\
  VideoEnhancerInstaller.exe
  videoenhancer.exe
  VideoEnhancer.zip

VideoEnhancer.zip 已包含手动安装所需的插件 DLL、纯运行版 CLI EXE、独立 aria2-next、许可证、来源说明和安装说明。解决方案发布会从上游 v2.5.6 Release 获取 aria2-next，SHA-256 不等于项目文件中锁定的值时立即失败；二进制 不再提交到 Git，也不再作为 .NET 嵌入资源。 如果只需要未改名的 CLI 单文件，可执行 dotnet publish .\cli\VideoEnhancer.csproj -c Release，产物位于 CLI 的标准 bin\Release\net10.0-windows\win-x64\publish 目录，不会生成 Artifacts，也不包含 aria2-next 或安装器载荷；需要下载功能时必须按上述便携布局配套放置独立组件。 只构建插件时可直接运行：

dotnet build .\VideoEnhancerPlugin\VideoEnhancerPlugin.vbproj -c Release `
  "-p:HostBin=C:\path\to\3FUI\bin"

如需同时安装插件 DLL，可附加 "-p:PluginInstallDir=C:\path\to\3FUI\Plugin"。

完整发布和门禁流程见 release/发布流程.md。

• 当前版本和发布记录：version/版本迭代记录.md
• 开发进度：version/工作进度.md
• AI/协作状态：docs/codex/STATUS.md

下表列出模型及其来源。模型文件可能由原作者发布，也可能由社区转换；具体许可与引用要求以对应项目说明为准。

本项目在下列程序与组件之上构建，感谢各自作者与社区：

• 3FUI（FFmpegFreeUI）：视频处理宿主与插件框架。
• LakeUI：3FUI 插件使用的原生界面控件库。
• FFmpeg：解码、编码、滤镜与封装核心。
• Zennmn/RTXHDR-RTXVSR（MIT）：RTX Video sidecar 的基础实现；本项目在其上定制了编码参数透传、容器直连与任务暂停/恢复。
• NVIDIA RTX Video SDK：RTX VSR 与 RTX Video HDR 的专有运行组件。
• NCNN、PyTorch、TensorRT、ONNX Runtime：推理运行时。
• REAL-Video-Enhancer 与 RVE 模型仓库：后端架构参考与模型镜像来源。
• mkvtoolnix：随包提供的字幕提取与封装工具。
• ModelScope：模型与发布镜像托管。
• aria2-next（GPL-2.0-or-later）：以独立进程提供分段和断点续传下载，安装在 bin\aria2-next；正式 Release 同时提供固定版本的对应源码归档。
• SharpCompress（MIT）：提供托管的 ZIP、7z、RAR、TAR、GZip、XZ 和 Zstandard 等格式读取，并负责生成发布流程使用的 7z 归档，取代原先分发和外部调用的 7za.exe。

下表覆盖当前模型镜像中可被程序选择的全部模型家族。带“待核实”的条目表示目前只能追溯到 RVE 的公开模型仓库或社区发布记录，尚未找到可确认的原作者正式发布页；这不是对模型所有权或再分发授权的主张。若作者、链接或授权信息有误，欢迎提交 Issue，本项目会及时更正或下架。

研究或公开发布结果时，请按原项目要求引用相关论文。

VideoEnhancer 项目源码采用 MIT 许可证，保留原作者及各贡献者的版权。可用 videoenhancer.exe --license 查看运行 EXE 内嵌的许可证全文；首次安装器和手动安装 ZIP 也会安装 Plugin\videoenhancer\LICENSE.txt。

3FUI 宿主、aria2-next、SharpCompress、RVE 后端、预训练权重、FFmpeg 和 Python 依赖分别使用各自的许可证。模型权重的许可条件请查看对应项目说明。

安装后的 THIRD-PARTY-NOTICES.txt 汇总本体直接分发的第三方组件。aria2-next 的 GPLv2 全文、作者与贡献者声明、二进制 SHA-256、上游标签/提交和对应源码地址位于 licenses\aria2-next；SharpCompress 的 MIT 许可证位于 licenses\SharpCompress。也可运行 videoenhancer.exe --third-party-notices 查看内嵌托管组件的声明。正式发布脚本会校验并同时上传 aria2-next-2.5.6-source.tar.gz。

RTX 运行组件包（模型仓库 Bin/rtx-video）包含基于 MIT 许可 sidecar 的定制构建、LGPL 动态链接的 FFmpeg 共享库，以及 NVIDIA 专有的 nvngx_*.dll 运行库；后者按 NVIDIA RTX Video SDK 许可随显卡环境使用，公开再分发前请自行完成许可复核。

本仓库不分发 PotPlayer.7z。模型资源的来源和授权状态应以发布记录及远端资源说明为准。

提交问题时，请附上：

• VideoEnhancer 版本和 3FUI 版本；
• Windows 版本、GPU 型号和驱动版本；
• 使用的后端、模型、处理顺序和关键参数；
• videoenhancer.exe --check 输出；
• 完整错误日志和可复现步骤。