视频高清化处理软件（Video HD Enhancer）

一个基于 ffmpeg 的视频高清化工具，支持：

• 分辨率放大（Lanczos）
• 时域+空域降噪（hqdn3d）
• 锐化增强（unsharp）
• 预设质量档位（fast / balanced / quality）

Quick start (source-only):

cd video-hd-enhancer
cp /path/to/your/video.mp4 samples/input.mp4
./scripts/run_cli.sh samples/input.mp4 --preset quality --scale 2

1. 软件设计

1.1 核心目标

• 输入普通视频，输出更高分辨率与更清晰主观观感的视频。
• 提供可复用的 CLI 工具，便于后续接 GUI 或服务端 API。

1.2 模块划分

• video_hd_enhancer/config.py：画质预设管理。
• video_hd_enhancer/enhancer.py：高清化参数模型、滤镜图构建、ffmpeg 命令拼装。
• video_hd_enhancer/ffmpeg_runner.py：ffmpeg/ffprobe 可用性检查、视频信息探测、命令执行。
• video_hd_enhancer/cli.py：命令行入口与任务编排。

1.3 处理流程

1. 检查 ffmpeg / ffprobe 是否可用。
2. 读取输入视频元信息（分辨率、编码）。
3. 按预设构建滤镜链：scale -> hqdn3d -> unsharp -> format。
4. 用 libx264 + CRF 编码视频流，音频流直接拷贝。
5. 输出并验证结果分辨率。

2. 快速开始

2.1 环境要求

• macOS Apple Silicon（当前内置二进制针对该平台）
• 首次运行可联网下载内置运行时与内置 Godot

2.2 准备你自己的测试视频

本仓库不分发 MP4 示例视频。请先放置自己的测试视频，例如：

cd video-hd-enhancer
cp /path/to/your/video.mp4 samples/input.mp4

2.3 内置运行时（推荐）

项目已支持内置 Python 运行时，不依赖系统 Python 包环境：

cd video-hd-enhancer
./scripts/run_cli.sh samples/input.mp4 --preset quality --scale 2

首次运行会自动在项目目录创建 .runtime/ 并安装固定依赖。 其中 ffmpeg/ffprobe 由内置 runtime 提供。

2.4 直接运行（兼容）

在项目目录执行：

cd video-hd-enhancer
PYTHONPATH=src python3 -m video_hd_enhancer.cli samples/input.mp4 --preset quality --scale 2

默认输出命名：<原视频名>__<高清化方法>__<时间戳>.mp4

2.5 运行测试脚本

cd video-hd-enhancer
./scripts/test_with_a_mp4.sh

2.6 启动 Godot GUI

cd video-hd-enhancer
./scripts/run_godot_gui.sh

首次启动会自动下载并使用内置 Godot（不依赖系统安装）。

GUI 支持：

• 输入/输出路径配置
• 预设和放大倍数配置
• 保持分辨率（不放大，仅提质）
• AI 增强开关（Real-ESRGAN）
• AI 后端切换（Real-ESRGAN / CoreML / MLX）
• 一键高清化
• 程序内嵌预览原视频与高清视频（自动生成 JPG 帧序列到 user://previews）

如果你想手动启动：

godot4 --path ./godot-ui

3. CLI 参数

PYTHONPATH=src python3 -m video_hd_enhancer.cli INPUT \
  [--engine classic|ai] [--ai-backend realesrgan|coreml|mlx] \
  [--ai-model realesrgan-x4plus] [--ai-scale 2] [--ai-device auto|gpu|cpu|npu] \
  [--coreml-model MODEL_PATH] [--coreml-compute-units all|cpu_only|cpu_and_gpu] \
  [-o OUTPUT] [--preset fast|balanced|quality] [--scale 2.0] \
  [--keep-resolution] [--denoise 1.8] [--sharpen 1.0] [--crf 20] [--dry-run]

或使用内置运行时：

./scripts/run_cli.sh INPUT [参数...]

• --engine：classic（传统滤镜）或 ai（Real-ESRGAN）
• --ai-backend：realesrgan / coreml / mlx
• --ai-model：AI 模型名，默认 realesrgan-x4plus
• --ai-scale：AI 超分倍率，默认 2
• --ai-device：Real-ESRGAN 设备偏好
• --coreml-model：CoreML 模型路径（.mlmodel / .mlpackage）
• --coreml-compute-units：CoreML 计算设备策略
• --preset：预设档位
• --scale：放大倍数
• --denoise / --sharpen / --crf：覆盖预设参数
• --keep-resolution：保持输入分辨率，只做画质增强
• --dry-run：只打印命令，不执行

3.1 画质建议

• 先用 --preset quality --keep-resolution 观察同分辨率提质效果。
• 如果想明显放大，请取消保持分辨率并设置 --scale 2。

3.2 安装 AI 引擎（Real-ESRGAN NCNN）

cd video-hd-enhancer
./scripts/install_realesrgan_ncnn.sh

安装后可直接使用：

PYTHONPATH=src python3 -m video_hd_enhancer.cli samples/input.mp4 \
  --engine ai --ai-model realesrgan-x4plus --ai-scale 2 --keep-resolution \
  -o outputs/input_ai.mp4

3.3 启用 CoreML 后端（Apple NPU/ANE）

先安装依赖：

cd video-hd-enhancer
./scripts/install_coreml_deps.sh
./scripts/install_ai_models.sh

放置 CoreML 模型到 tools/coreml/（或用 --coreml-model 显式指定），然后运行：

PYTHONPATH=src /usr/bin/python3 -m video_hd_enhancer.cli samples/input.mp4 \
  --engine ai --ai-backend coreml --coreml-model tools/coreml/your_model.mlpackage \
  --coreml-compute-units all --keep-resolution -o outputs/input_coreml.mp4

3.4 启用 MLX 后端

cd video-hd-enhancer
./scripts/install_ai_models.sh
PYTHONPATH=src /usr/bin/python3 -m video_hd_enhancer.cli samples/input.mp4 \
  --engine ai --ai-backend mlx --coreml-model tools/coreml/RealESRGAN.mlpackage \
  --keep-resolution -o outputs/input_mlx.mp4

4. 作为 AI Skill 使用

提供了可直接给 AI 代理调用的 Skill 包与统一脚本：

• Skill 文档：skills/video-hd-enhancer/SKILL.md
• AI 入口脚本：scripts/skill_vhe.sh

示例：

cd video-hd-enhancer
./scripts/skill_vhe.sh coreml samples/input.mp4 outputs/input_skill_coreml.mp4

5. License & Compliance

• Source code license: Apache License 2.0 (LICENSE).
• Third-party engines/models/binaries use their own upstream licenses. See THIRD_PARTY_NOTICES.md.
• This repository is source-only for legal clarity: it does not commit third-party model weights, third-party executables, or sample MP4 files.
• If you redistribute packaged builds that bundle FFmpeg/Godot/models, you must include corresponding third-party notices and satisfy their license obligations.
• You are responsible for ensuring you have rights to process and redistribute any input media.

6. 后续可扩展方向

• 引入 AI 超分模型（如 Real-ESRGAN）作为可选后端。
• 增加批处理任务队列。
• 增加 Godot 内嵌视频预览（减少对 ffplay 的依赖）。