P+ 图片·视频·本地·修复器
一个纯本地、离线运行的绿色多媒体处理工具箱，单文件 EXE 形态交付（也可直接跑 Python 源码）。
由四个页签组成，所有外部资源（ffmpeg、Video2X、ncnn 引擎、llama.cpp、whisper、权重）都按相对路径定位，
整套目录可整体拷贝到任意盘符、任意用户名电脑直接使用，不写死任何本机专属路径。
> 关于本 SKILL 的打包口径：采用"精简包"——只含源码、文档与部署说明，不含 runtime / 引擎 / 模型 / 权重等大型依赖，
> 这些由使用者按下方「部署」清单自行下载放置。若你想要"开箱即用"的一体包，请自行把各项依赖按目录结构补齐后再打包。
一、能力总览（四页签）
| 页签 | 功能 | 外部依赖 |
|---|---|---|
| 视频画质提升 | Video2X 放大/补帧/修复（ESRGAN / Real-CUGAN / RIFE / libplacebo） | Video2X\video2x.exe + 其模型 |
| 图片增强 | ncnn 三件套：waifu2x / realsr / srmd（Vulkan） | engines\waifu2x、engines\realsr、engines\srmd |
| 一键配字幕 | ffmpeg 抽音 → faster-whisper 识别 → 本地大模型逐条翻译 → 中/双语字幕 | ffmpeg_bin、whisper_models、runtime\asr(faster-whisper)、已启动的 llama-server |
| 本地大模型 | llama.cpp + Vulkan 启动本地推理服务（OpenAI 兼容接口） | llama.cpp\bin\llama-server.exe + models\*.gguf |
二、目录结构（绿色版交付形态）
P+：图片·视频·本地·修复器\
├─ P+：图片·视频·本地·修复器.exe # 单文件 EXE（由 P+.py 打包）
├─ aitoolbox_theme.json # 界面主题（须与 exe/py 同目录）
├─ P+.ico # 图标
├─ 启动P+.bat # 双击启动 EXE（%~dp0 自定位）
├─ P+.py / subtitle_run.py / face_restore.py # 源码
├─ Video2X\ # 视频画质提升引擎 + 模型
├─ ffmpeg_bin\ # ffmpeg.exe / ffprobe.exe
├─ engines\ # ncnn 图片增强三件套（waifu2x/realsr/srmd）
├─ llama.cpp\bin\llama-server.exe # 本地大模型服务
├─ models\ # *.gguf 权重（可用环境变量 PPLUS_MODELS_DIR 指向别处）
├─ whisper_models\ # faster-whisper 模型（base/small/medium）
├─ weights\ # GFPGAN / facexlib 权重
├─ runtime\asr\python.exe # 配字幕用的 faster-whisper 环境
└─ face_env\Scripts\python.exe # 人脸修复用的 GFPGAN 环境（或 runtime\python310）
资源定位全部基于 BASE = os.path.dirname(sys.executable)（EXE 形态）或 dirname(__file__)（源码形态），
因此整目录搬迁即生效，无任何硬编码用户名 / 盘符。
三、运行方式
A. 直接跑源码（适合开发/二次改动）
- 需要 Python 3.10+ 且含
tkinter（标准库自带）。 - 把
scripts/下三个.py与aitoolbox_theme.json、P+.ico放在同一目录，双击P+.py即可。 - 注意：配字幕 / 人脸修复页签会调用独立的 Python 环境（
runtime\asr、face_env），详见部署表。
B. 重打包为单文件 EXE（推荐分发给他人）
在你自己的构建环境（含 PyInstaller）里执行：
pyinstaller --onefile --noconsole \
--name PPlusApp \
--icon <复制成 ASCII 名的图标.ico> \
--add-data "aitoolbox_theme.json;." \
--add-data "P+.ico;." \
--distpath _dist --workpath _build P+.py
要点：
1. ico 必须先用 ASCII 文件名（如 app.ico）再传给 --icon，含中文/全角字符的 ico 名会被 PyInstaller 截断。
2. 发布时把 _dist\PPlusApp.exe 改名为 P+：图片·视频·本地·修复器.exe。
3. console=False 的 EXE 里 sys.stdout/stderr 为 None，必须在代码里接管 sys.excepthook /
threading.excepthook 并把异常写日志文件，否则"报错即消失"。
4. tkinter 非线程安全：子线程禁止直接碰 Tcl，统一用 queue.Queue + 主线程 after() 泵。
四、部署（依赖由对方自行下载）
下面每一项都是可选的——只用对应页签才需要对应的依赖。下载后按"放置位置"丢进工具目录即可，无需安装、无注册表。
| 依赖 | 官方下载源 | 放置位置 | 备注 / 许可证 |
|---|---|---|---|
| ffmpeg / ffprobe | gyan.dev 或 ffmpeg.org 的 Windows 构建 | ffmpeg_bin\ |
GPL/ LGPL；只取 ffmpeg.exe+ffprobe.exe |
| Video2X | github k4yt3x/video2x Releases（含 video2x.exe 与模型） |
Video2X\ |
GPL-3.0；放大依赖其自带 models |
| ncnn waifu2x | github nihui/waifu2x-ncnn-vulkan Releases |
engines\waifu2x\（exe+models-cunet 等） |
MIT |
| ncnn realsr | github nihui/realsr-ncnn-vulkan Releases |
engines\realsr\ |
MIT |
| ncnn srmd | github nihui/srmd-ncnn-vulkan Releases |
engines\srmd\ |
MIT |
| llama.cpp | github ggerganov/llama.cpp Releases（选 vulkan 构建） |
llama.cpp\bin\llama-server.exe |
MIT |
| GGUF 模型 | HuggingFace Qwen/Qwen2.5-1.5B/3B-Instruct 的 q4_k_m 量化 |
models\（或设 PPLUS_MODELS_DIR） |
Apache-2.0（Qwen） |
| Whisper 模型 | HuggingFace Systran/faster-whisper-base|small|medium |
whisper_models\ |
放模型目录本身（传目录路径，勿传模型名） |
| GFPGAN 权重 | github TencentARC/GFPGAN 的 weights/（GFPGANv1.4 / detection 等） |
weights\ |
须与 facexlib 权重同放 |
| faster-whisper 环境 | pip install faster-whisper 建 venv |
runtime\asr\（含 python.exe） |
MIT；CPU int8 |
| GFPGAN 环境 | pip install gfpgan facexlib opencv-python torch(CPU) 建 venv |
face_env\Scripts\python.exe |
用于"人脸修复"页签 |
三步部署示例（以"本地大模型"页签为例）：
1. 下载 llama.cpp vulkan 版 → 解压出 llama-server.exe 放到 llama.cpp\bin\。
2. 下载 qwen2.5-3b-instruct-q4_k_m.gguf → 放到 models\。
3. 双击 启动P+.bat 打开工具，切到"本地大模型"页 → 点启动（或用 scripts\start-llama.cmd 3b 8080）。
五、隐私与绿色化约定
- 所有资源路径都基于
BASE（可执行文件所在目录），不出现 用户名目录、系统保留目录、其它项目绝对路径。 - 启动脚本（
启动P+.bat/start-llama.cmd）一律用%~dp0自定位，拷贝到哪里都能跑。 - 本仓库已剔除旧目录名、外部项目路径等历史痕迹；如二次开发，请勿把本机绝对路径写死进代码。
六、中文 .cmd / .bat 铁律
> 含中文的批处理必须存成 GBK(cp936) + CRLF。存成 UTF-8 会被 cmd 用系统 OEM 码页(936) 解析，
> 中文被切碎 → 报 'LE'/'cho' 不是内部或外部命令、%~nF 路径运算符无效 等诡异错误，chcp 65001 救不了。
> 用 Python 写这类文件时：open(p,'w',encoding='gbk',newline='\r\n')。
七、已知坑位（踩过的，记死）
- ncnn 引擎
-m models-xxx是相对路径 → 启动该引擎时cwd必须是引擎目录本身，否则报找不到模型。 - Video2X 的 libplacebo 处理器必须给
-w/-h，不支持-s倍数；ESRGAN / RIFE 才用-s。 - faster-whisper 传目录路径，不是模型名——直接传
whisper_models\small这种目录，传模型名会去 HuggingFace 下载被代理拦截。 - llama.cpp 本地服务用
-ngl 99全层 offload 到 Vulkan（RX580 8G）；上下文-c取值需按显存调，过大直接崩。 - GUI 多线程：子线程禁止直接
widget.config()/StringVar/messagebox，统一queue+ 主线程after泵。 - PyInstaller onefile + noconsole：
sys.stdout/stderr为 None，print/traceback 必须 try 包裹或接管 excepthook，否则崩溃无迹可寻。
八、二次开发入口
P+.py：__main__与各页签类（VideoTab/ImageTab/SubtitleTab/LLMTab）；资源常量集中在文件头（V2X/FFMPEG/LLAMA/ENG/MODELS_DIR/...）。subtitle_run.py：独立 CLI（--video/--audio/--srt --port --model --asr-only），可被其它流程直接调用。face_restore.py：GFPGAN 批量人脸修复，权重自动摆到gfpgan/facexlib期望位置。- 界面配色/主题见
aitoolbox_theme.json与P+.py顶部ACC/ACC2/BORD常量。
许可证：本工具源码以仓库内 LICENSE_许可协议.txt 为准；第三方依赖（ffmpeg / Video2X / ncnn / llama.cpp / Qwen / faster-whisper / GFPGAN）请遵循各自许可证。
