Skip to content

Latest commit

 

History

History
171 lines (134 loc) · 23.3 KB

project.md

File metadata and controls

171 lines (134 loc) · 23.3 KB

VS Renderer / VS Player:项目开发地图

1. 发心与边界

为需要可视化滤镜、画面对比和高精度媒体播放的 Windows 用户提供桌面工具。Renderer 编排处理链和导出,Player 负责播放,VSCap 负责捕获与标注,PhotoCraft 提供独立编辑工作区。

成功标准是处理路径可检查、时间轴一致、便携依赖可复现、问题可定位到模块。非目标包括通用 Python IDE、任意 FFmpeg 命令设计器、私有 NGU 算法仿制和全部设备/格式兼容保证。

2. 快速开始

开发需要 C++20、CMake 3.25+、Ninja、Qt 6.8+ 的 MinGW 套件;Native 使用独立 MSVC 工具链,通过 C ABI 与 GUI 通信。完整命令见 依赖与构建 和 API20 构建。

已有依赖时:配置 QT_ROOT 和工具链 PATH → cmake --preset windows-mingw-release → cmake --build --preset windows-mingw-release → 按改动模块运行 CTest/QtTest。

三个常见坑:① GUI EXE、Native 与 FFmpeg shared ABI 必须匹配;② 只复制 EXE 不构成完整部署;③ 首次索引/着色器编译与稳定播放性能分开测。

3. 架构决策

决策 原因与适用范围 不采用的方案 / 重估条件
Qt Widgets + C++20 适配 Windows 控件、HWND 和 D3D11 不引入 QML;跨平台或场景图需求改变再评估
Agent Qt 核心 + 独立 MCP Node 桥 Chat Completions/SSE、按需Skills、摘要投影、子会话;Qt异步本地文件/命令/图像;MCP用官方client v2 不引入.NET/LakeUI或网页壳;环境工具由模式及父权限统一拦截,原生非兼容模型协议需单独适配
MinGW GUI → Native 动态 C ABI 隔离 MinGW/MSVC C++ ABI 不跨工具链传 C++ 对象;升级必须核对结构版本和 DLL
FilterGraph → VPY → VSScript → 3FP 脚本可审查,预览与导出共用处理描述 不以离线 vspipe/Y4M 管道充当实时帧桥
直通与 VS 路径分开 普通播放不等待 VS 索引 不无条件初始化全部增强依赖
3FP原生色彩默认 SDR/HDR使用现有3FP处理;旧自动色彩档迁回原生,libplacebo仅由Full手动启用以对照mpv 不根据HDR标记自动进入libplacebo;手动档与ICC/LUT参数保留
时间组独立 FilterGraph 同片不同段落可使用不同链 拼接要求各组输出规格一致,不静默改变格式
Player 区间交接 PlayerLoop.cpp 用源时间传给新 Renderer,MainWindowTimeGroups.cpp 按源 FPS 建组并选中 A–B 不覆盖已有 Renderer 工作区;区间按恒定帧率源帧对齐
Explorer 适配器与解码进程分离 src/shell/ 的轻量 COM 适配器启动有时限的 worker,媒体解码在独立进程 不在 Explorer 中载入媒体解码器;当前用户注册由 PlayerThumbnails.cpp 备份和恢复
专用时间轴与请求代次 管理 seek、补帧和源/输出 FPS 不使用 seek 后局部帧号直接推算全局源帧
直通相对逐帧 PlayerWindow::stepFrame 调用内核当前PTS逐帧;Native重新解码局部GOP确认相邻帧 不用绝对帧号逐帧,也不把稀疏缓存中的近邻当成真实相邻帧;VS仍按输出帧号定位
查看与编辑解耦 PhotoCraft 独立进程保留未保存工作 旧 Qt 编辑器仍有源码/测试,不作为生产编辑入口
固定上游 + 完整 Native 补丁 保留本地扩展并可重新构建 不拼装 API14/18/20 不同版本 DLL 或补丁
比对源像素与显示值分开 AnalysisPage::updatePixelReadouts 按源坐标联动;SourcePixelProbe.h 和 Native 比对扩展提供转换前码值 YUV 不由渲染 RGB 反算;交互重绘不继承静态图片媒体帧率;缩放移除固定倍率上限,Native 裁剪视口并映射 UV
启动期库预读 src/player/main.cpp 用128KiB缓冲在低优先级线程读取FFmpeg;单文件解包后的Qt子进程共用 不照搬.NET图标和LakeUI设备预热,不额外提高进程优先级;首次解包单独计时
软件播放同步与内存预算 上游线程/帧池/CPU 域按负载逐级调整;音频从60ms起按告警升至240ms,呈现允许最多250ms的平滑节奏容差;保留VSP的8K关键包参考帧追赶 不把显示器限帧记为解码丢帧;CPU预缩放仍默认关闭,8K逐帧实时按素材验收
AI 字幕外置推理 固定 main + #36/#37 Native 音频 tap;Qt 有界传 PCM 到外置 worker,跳转按 generation 隔离 模型独立打包并由组件下载器安装;保留旧 GGUF 配置兼容,不移植上游 VB 页面
Shader 平面输出 third_party/vsr-placebo 直接回读 YUV 平面、合并增强 hooks,独立命名空间与 color 依赖 保留标准 placebo 插件作为缺少组件时的兼容路径;不把 VS 吞吐当作 Native 播放帧率
Full/Lite 原生 Anime4K PlayerBuiltinProfiles.h 定义六档;AFast CNN 使用 Anime4KFast.h,A CNN/AFast 1X 使用内置 HLSL 包;1X 按源尺寸处理后交给第二上采样,旧 no CNN 配置一次迁移 内置字节码更新仍须重建并验证像素;Full/Lite 内置档位不回退 GLSL;不兼容色彩或模型失败时明确提示并退回 D3D11,保留播放控制
通用 GLSL/HLSL 导入 ShaderPackage 编译并缓存,CustomShader.h 执行多 pass;兼容文件无需重建 DLL,播放不引入 VS/Python 依赖 当前支持 LUMA/MAIN/PREKERNEL 像素 pass、参数默认值与 gather;NATIVE 只提供尺寸,计算/外部纹理等明确拒绝,详见 Player 指南
Full/Renderer 提取末尾 shader 核对本项目图元数据与实际 Python 正文,再将兼容的末尾节点交给原生执行器 前序滤镜仍由 VS 执行;不兼容时回退原 GLSL,编码导出保留完整 VPY,不实现任意 VPY→HLSL

4. 目录地图与改动入口

目录 职责与关键入口
src/app/ Renderer:MainWindow.cpp、MainWindowTimeGroups.cpp、MainWindowPresets.cpp
src/agent/ AgentSession 管工具循环、权限与待接收输入,AgentContext 管用量与摘要;AgentLocalFiles/AgentLocalProcess/AgentLocalImages 管本机能力,AgentImageMessages 管图像校验/投影;AgentProvider/AgentModelCapabilities 管来源/模型;AgentInput 路由命令/引用;AgentInstructions 管指令/Skills;AgentMcp/AgentNodeRuntime 管MCP进程;AgentTaskQueue 管子会话,AgentToolLibrary 管组合
src/app/AgentVideoFrames.cpp 原片/处理后 VS 帧按完整原分辨率发送,仅显式裁剪取局部;图像工具由 AgentModelCapabilities 的端点模型元数据启用,含 Harness 的 input 声明
src/ui/AgentPage.cpp 会话列表绑定独立 AgentSession,切换不取消后台请求;MainWindowAgentFeatures.cpp 为各会话注册工具与独立任务队列,模型列表逐项显示视觉能力
tools/agent-runtime/ 官方 MCP client 锁文件与 Node JSONL 桥;测试服务器只供开发,tools/stage-agent-runtime.ps1 安装便携生产运行时与许可
src/graph/ 滤镜定义/图/预设:FilterCatalog.cpp、VpyScriptBuilder.cpp、PresetStore.cpp
src/backend/ VapourSynthFrameServer、ThreeFpPlayer、ThreeFpApi、FrameTimeline.h、导出与进程
src/ui/ PreviewPane、CompareView、AnalysisPage、参数、预设社区及导出窗口
src/player/ PlayerWindow、PlayerControls、PlayerProfiles、字幕/音频/设置/图片;PhotoCraftEditor.* 连接编辑器
src/shell/ ThumbnailProvider.cpp 对接现代缩略图及旧式 IExtractImage;文件/流入口共用 ThumbnailWorker.cpp / ThumbnailDecode.h 隔离解码
src/cap/ main.cpp 负责截图/标注/贴图,DesktopCapture 捕获,UiAccess 启动
src/bluray/ BlurayCatalog 解析节目,BlurayWidget 提供共用界面
src/color/、src/image/ 色彩桥、高精度图片、PSD/HDR/JXL 与保留的 Qt 编辑实现
src/render/ Anime4KFast.h 运行内置增强;ShaderPackage.* 负责自定义源解析、转换与缓存,CustomShader.h 负责原生多 pass;补丁及构建见 API20 指南
src/update/ PortableUpdater、ComponentDownloads
assets/、third_party/ 图标/语言/滤镜资源与第三方来源、运行时说明和许可
patches/、tools/ 固定上游补丁;构建、部署、打包和测量脚本
tools/sr-pareto/ 独立超分算法 Pareto HTML 模板;JSON 的 preview: true 点不计入前沿、可隐藏,使用见目录内 README
tests/ 可执行回归测试源码与小型 fixtures,保留按模块划分
docs/ 按任务组织的现行操作指南,不放逐版本测试/发布流水
development/ 源码工作区测试台账、合并历史原文与证据;不随运行包复制
.deps/、build/、dist/ 忽略的依赖、构建/原始日志、本地运行产物;不等于已发布附件

工作区清理:优先删除历史打包暂存、部署副本和编译中间文件,保留当前 build/mingw-release、dist、待打包的最新运行时及依赖源码。build/native-deps-20261115 被 Native 依赖目录链接引用,不能整体删除。build/retained-user-files/ 保存清理前提取的配置、VPY、色彩文件、媒体及记录,含 SHA256 清单;它属于保留资料,不是可再生成缓存。

1.1.0 改动入口:src/app/MainWindowRoutes.cpp / RenderRoute.h 管理处理路;PlayerDecodeBuffer.cpp 管理按需软解缓冲(常规8帧、尖峰最多48帧/4GiB,包含解码流水线,预算仅是上限);PlayerShortcuts.h 定义快捷键;ui/PageTheme.h 复用页面背景;assets/ncnn-filter.py 仅处理 Renderer 单帧,实时 Player 注入跳过标志。AI 音频桥仍为 PlayerAiSubtitles.cpp,包说明见 组件指南。

5. UI 地图

Renderer手动预览入口为MainWindow::validateScript;加路、换源和载入预设不触发预览,RenderRoute::reset清理旧输出。CompareView按处理路数维护标题。Player的setMinimalMode使用待恢复时间戳重新打开解码器,保留播放/暂停意图;底栏提示区仅占一行。

入口与导航 文件
Renderer:导入 → 时间组/处理链 → 参数/脚本 → 源与输出预览 → 预设/导出 src/app/MainWindow*.cpp、src/ui/ParameterEditor.cpp、CompareView.cpp
Agent:发送键旁来源/模型/思考 → 对话;功能 → Skills/AGENTS、MCP/npm;自动队列 → 子会话;Token → 上下文整理 AgentPage.*/AgentPageDialogs.cpp组装页面;AgentComposer管输入预览/补全,AgentChoicePopup管三类圆角选择浮层,AgentMarkdownView管消息排版与轮次过程折叠;MainWindowAgent.cpp注册工具,MainWindowAgentFeatures.cpp连接服务,MainWindowAgentInteractions.cpp路由命令/引用/能力;索引4,背景键VSR-Agent
图像分析比对:多源 → 偏移/布局 → 同坐标 RGB/原始 YUV → 对比画布导出 src/ui/AnalysisPage.cpp、MultiCompareView.cpp、AnalysisExport.cpp;OpenNGU 经 ShaderPackage 加载,缩小默认 D3D11;该核暂不支持一致的 VS 画布导出;Native 扩展见 patches/3fp-api20-analysis-probe.patch
BD Remux:节目识别 → 轨道/输出 → 队列 src/bluray/BlurayWidget.cpp
Player:打开媒体 → 底栏/列表 → 右键音频/字幕/设置 → 图片工具 src/player/PlayerWindow.cpp、PlayerMenus.cpp、PlayerSettings.cpp
Player色彩:解码设置 → 3FP默认 / 手动libplacebo对照;旧自动档迁回原生 src/player/PlayerColor.cpp、PlayerWindow.cpp
PhotoCraft:图片工具栏 → 独立编辑工作区 src/player/PhotoCraftEditor.*、tools/build-photocraft.ps1
VSCap:热键 → 选区调整 → 标注 → 最终裁切/复制/保存/贴图 src/cap/main.cpp

6. 外部依赖

依赖 固定版本 / 准备与调用 缺失行为
Qt 6.8+;本地记录 6.10.2,MinGW;CMake 查找 编译或 GUI 启动失败
Agent Node/npm/MCP Node 24.19.0、npm 11.17.0、MCP client/core 2.4.0;stage-agent-runtime.ps1固定生产包到runtime/agent,JSONL桥提供stdio/Streamable HTTP 缺少组件时MCP设置可安装/修复;模型对话与内置软件工具独立,许可与完整性见运行时components.json
VapourSynth / Python VS API4 / R81;构建和 stage 脚本,update-vapoursynth-runtime.py 锁定哈希 VS 链不可用;直通路径独立
VS 插件 BM3D 11.0、BM3Dvk2 1.0、BestSource 22;其余随运行时保留 对应滤镜不可用;不能用 API3 DLL 替代
FFF.Native API20 / 固定 85f514b;标准脚本应用 3fp-vsp-upstream-20261115.patch 并复制本库头文件;snapshot v23 / 608 字节、外部帧v2 / 240字节,动态 C ABI 原生播放/呈现不可用;旧内核无法保留新增帧信息时明确返回不支持
FFmpeg full09+SVT420修正发行版(2026-11-15),AVX2;shared ABI:63/63/61/7/10/12,来源哈希见 tools/ffmpeg-source.json;编译原生VS源需设置 VSR_FFMPEG_ROOT 相应解码/导出失败,单文件启动器先检查组件;SDK缺失时CMake明确失败
GLSL / RIFE 随包 shader 与 NCNN 模型,stage-shaders.ps1 / install-analysis-plugins.ps1 相应增强不可用;RIFE 需要 Vulkan
GLSL 转换组件 runtime/shader-tools/ 中的 glslc、SPIRV-Cross 及配套依赖,由 tools/stage-shader-tools.py 整理;HLSL 用 D3DCompiler 编译 缺失时不能导入 GLSL;原生 HLSL 不调用 GLSL 转换工具,逐帧播放仅执行已编译字节码
libVLC / LAV / madVR Full 可选后端,stage 脚本及各自许可 对应后端不可用,PlayerLite 不包含
PhotoCraft 固定源与补丁见 tools/photocraft-source.json、build-photocraft.ps1 详细编辑不可用,基础查看独立
JXL / AWJ / 图片库 tools/jxl-runtime.cmake、awj-runtime.cmake、image-runtime.cmake 对应格式/转换不可用;AWJ 需 AVX2
aria2 / 7-Zip / MKVToolNix stage-update-tools.ps1、stage-mkvtoolnix.ps1 更新下载/解压或 Remux 不可用

来源、安装和验证入口见 构建指南;分发许可见 第三方声明。

7. 核心数据

数据 位置 / 所属模块 兼容原则
处理链/时间组 FilterGraph、FilterTimeGroup 整秒起点分段;每组独立链,输出规格一致
Renderer 项目 *.vsr.json / MainWindow schemaVersion=2,保存各处理路、可见性与当前编辑路,兼容旧单路;未知节点不保证无损往返
VPY 预设 程序旁 vpy/ / PresetStore # VSR_PRESET Base64 JSON;时间组 metadata schema=2,兼容旧单链;不能与项目 schema 混淆
Player 配置 player.ini / PlayerSettings 保留用户显式选择;单文件放启动器旁
自定义 shader 配置旁 shaders/custom 或 render/shaderDirectory,所选源为 render/customShader;子目录 cache 存 .vsrhlsl 格式 1、语义版本 v8(参数默认值与 gather;兼容已验证的 v7 字节码);源内容、扩展名、转换器及 D3DCompiler 标识参与缓存键,结构损坏重建;导入失败保持旧选择
Renderer / 社区设置 QSettings;community/sourceUrl、appearance/dark、appearance/language 源/主题/语言在同一滚动页;主题即时生效
Agent 来源/会话/工具组合 QStandardPaths::AppDataLocation/agent/ 中的providers.json、conversations/、tools.json;选择与禁用工具用QSettings JSON schemaVersion=1;会话本地记录保存自定义名称与用户指定的分组,折叠状态存于 QSettings;工作目录不决定分组,旧记录归入未分组;显式新建只保留一条可复用的空白会话;启动或删除后自动准备的空白草稿不进入左侧历史;来源密钥DPAPI加密,导出来源省略密钥;会话导入检查工具配对
Agent 指令/插件/队列 同目录AGENTS.md、skills/、skills.json、mcp.json、conversation-tasks/<会话ID>.json 技能先索引后读取;MCP凭证DPAPI、导入默认断开;旧tasks.json首次复制迁入当前会话,原文件保留;队列重启后手动恢复;摘要不删除原始消息
Agent 待接收输入/模型能力 会话JSON中的pendingMessages保留原文/资料与来源,导入暂停;能力仅内存缓存 API投影过滤本地显示字段;工具配对完成后接收输入/图像;能力绑定端点+模型,仅决定思考字段与视觉许可,不能覆盖模型或消息
Agent 环境权限/图像 QSettings agent/accessMode、agent/workingDirectory;图像保留在会话content规范块中 默认software,full由用户选择;导入会话/队列不提升权限或恢复进程;图像来源需能力声明,摘要剥离编码数据、请求保留近期图像
说明 / 命令 / AI vpy/preset-descriptions.json;QSettings export/commandHistory;player.ini 的 ai/package 说明只补空键;命令历史最多 50 条;模型路径指向外置清单
临时脚本/索引 QStandardPaths、媒体索引缓存 可再生;导出冻结脚本、源和参数,不删除用户 VPY
分发元数据 release.json、资源/组件清单 版本、根目录和文件哈希须对应实际产物

8. 分层与高风险区

依赖方向:graph 不依赖 UI;backend 管帧、原生和进程;app/ui/player/cap 管交互。不要把算法直接塞入按钮回调。

2026-10-17 抽样:MainWindow.cpp 1193 行 / 60 KB,src/cap/main.cpp 888 行 / 59 KB,PlayerWindow.cpp 645 行 / 62 KB,旧 ImageEditorWindow.cpp 377 行 / 97 KB。行数与字节数只是职责审查信号;确需拆分时按交互状态、媒体操作、持久化和独立算法划分,不按行数机械拆分。

2026-11-08 Agent:Session约610行,LocalFiles约310行、LocalProcess约390行;权限派发仍属于Session,本地I/O与图片协议已独立。继续扩展时优先保持API/工具/I/O方向,不向主窗按钮填入文件或进程实现。

高风险包括 DLL/FFmpeg ABI、HDR 白位/色域/位深、seek 时钟和交接线程生命周期、超大图内存/ICC/Alpha、更新目录交换。涉及这些内容时需要实际媒体/GPU 像素或交互验证,编译成功与离屏布局不能代替实机结果。

Native 高风险集中于 .deps/fff-vsp-20261115/FFF.Native/3FP/Core/PlayerSession.cpp 与 Render/VideoRenderer.cpp(均超过一万行);本轮仅局部修复。后续按解码生命周期、预算准入和图集职责分别提取,避免把 GUI 预测器搬入 Native。安全回归随标准补丁归档于 FFF.Native.Tests/SecurityRegression.cpp。

9. 更新、测试与发布

  1. 明确变更范围,复现问题;修改相关模块,构建并运行对应测试。测试选择与结果写入 版本测试台账,步骤见 构建 / 测量。
  2. Native 用 API20 固定脚本和补丁;历史 API14/18 脚本只用于对应基线。GUI 使用 CMake preset。
  3. 本轮更新现有 dist/VS-GUI-Full,保留用户预设与色彩文件;单文件仅更新运行时暂存,dist/VS-Player.exe 保留上一轮1.1.3成品,待明确打包指令再生成。精简播放器暂存在build/playerlite-runtime-1.1.4,不再生成PlayerLite发行目录。tools/deploy-local-runtime.py增量部署并核对INI/VPY/ICC/LUT哈希;它会修改运行目录,文档整理时不运行。
  4. 打包前明确Full、历史Lite或当前PlayerLite;package-portable.ps1 -Edition Lite是历史Full删减版,不能充当当前PlayerLite。单文件从当前版本暂存(本轮build/playerlite-runtime-1.1.4)用package-playerlite-single.ps1生成tar.gz level 1负载,启动后临时解包、退出清理;Full/Single均排除themes目录及用户主题INI。收到打包指令后,Full压缩包按当前CMake版本生成;本轮不生成1.1.4压缩包或单文件,不修改远端Release草稿。完整流程见 便携更新。
  5. 解压、依赖、启动、配置和清单验证后才可报告包完成;源码推送、草稿、附件上传、正式发布分别记录,需要相应任务授权。

文档纪律:结构/决策变化当天更新本地图;操作变化只改对应 docs 指南;用户可见变化写 changelog;测试按版本与轮次更新同一台账,不新建 docs/update-版本.md、validation-版本.md。原始日志留 build/,必要证据放 development/evidence/;不携带用户媒体。README、本地测试数据和开发记录不得混入上游 PR。

10. 当前状态

本地内核基线更新至上游85f514b(#58–#62),RAW 图片经 LibRaw 原生开发成16位RGB;蓝牙补偿策略与设置见 PlayerBluetooth.h / PlayerAudio.cpp。1.1.4 发行目标为 Full 7z 与单文件 Player,构建、暂存和验收使用独立目录,不覆盖现有安装。

VSP Native 的安全/生命周期修复、可恢复丢帧和预算策略在 patches/3fp-vsp-upstream-20261115.patch;GUI 预测与失败重试入口为 src/player/PlayerDecodeBuffer.cpp。预算零值、缩容驻留、旧 DLL 降级、可信外部帧契约及隔离回归命令见 Native 构建指南。构建候选不自动更新安装目录。

当前源码版本 1.1.4;Anime4K 收敛为六档并迁移旧配置。生产 Native 必须关闭 SecurityRegressionTests 并检查不存在测试注入导出;公开发行不包含私有 OpenNGU 素材。实际发布状态以两端远端附件及哈希核验为准,流程见 便携更新。

11. 故障排查

症状 先检查
Qt 配置或构建失败 QT_ROOT、MinGW PATH、CMake preset;构建指南
Native 黑屏/ABI 错误 API20 补丁、FFmpeg shared DLL、VSR_3FP_DLL;原生构建
VS 缺插件/预览失败 API4 运行时、模型和 VSR_VSSCRIPT_DLL;Renderer
GLSL/HLSL 导入或执行失败 runtime/shader-tools、Native 自定义扩展、完整编译错误及 hook/色彩/尺寸边界;Player
seek/音画时间不同步 FrameTimeline.h、PlayerSession、请求代次;性能排查
HDR 色偏/截图异常 src/color/、HdrPreview.h、源屏幕 SDR 白位;色彩
VSCap 模态/文字/贴图异常 src/cap/main.cpp;截图
BD 菜单或跨段失败 BlurayCatalog、concat 定位、片段索引;蓝光
缩略图接口测试通过但 Explorer 不生成 核对独立系统进程实际读取的注册项;开发代理的注册表视图可能不同。安装后仍需文件列表自动生成验收,不能用强制提取代替;本地诊断记录
包缺 DLL/升级失败 分发形式、必需清单、包根目录与备份;更新

安全修复入口:BlurayCatalog.cpp 校验 MPLS 头部;ImageDocument.cpp 两处合成器限制深度64、结构访问65536,PlayerImage 将取消传到 PSD 解码/合成。Native 额外应用 patches/3fp-avif-budget.patch,由标准 API20 构建脚本接入;只修源码不代表发行 DLL 已更新。