Skip to content

IMPLEMENTATION_STATUS.md

Latest commit

 

History

History
140 lines (110 loc) · 20.4 KB

IMPLEMENTATION_STATUS.md

File metadata and controls

140 lines (110 loc) · 20.4 KB
Raw

实现状态

更新日期：2026-08-06

当前结论

插件已经形成 UERayTracingAudioSDK、UERayTracingAudio、UERayTracingAudioEditor 三模块闭环，并已接通 UE 5.7 的硬件 Ray Tracing RHI、Direct/Occlusion、方向性多 bounce 间接声、Realtime/Baked/Hybrid IR、离线卷积和 Editor A/B 验收界面。

蓝/橙密闭空间已拆分为固定相机自动门禁和可交互 PIE 验收：交互模式把 Listener 跟随 First Person 相机，提供 F1/F2/F5 数据源切换、F3 同步 Rendered/Original A/B、F4 烘焙原点复位、F8 视角切换，并在主屏显示实际当前模式、A/B 播放状态和 Baked 资产状态。自动交互 smoke 已证明 Pawn、Listener、快捷键和两条播放链路工作；实际听感仍需人工确认。 F3 的 A/B 辅助逻辑只改变 Original/Rendered 播放链路，不改变 Source 的 IndirectDataSource；从 F2 Baked 或 F5 Hybrid 进入 F3 后仍保持原数据源。交互 smoke 现在额外要求 f3_source_preserved=1，防止把静默回退到 Realtime 误报为通过。

自动化证据证明的是实现链路、数值语义、音频完整性和硬件路径；最终“听起来正确”仍必须由目标耳机或扬声器上的 Human Pass 证明。未取得该记录前，不宣称最终声质验收完成。

2026-08-06 HumanAcceptance schema-v3 验收记录闭环

  • Editor Listening Acceptance 新增必填目标耳机/扬声器、可选试听备注和五项结构化人工确认：Direct 保真、Wet/Full 可听差异、移动遮挡连续性、运行时模式切换连续性、环境差异。每个新 comparison artifact 都会把 Previewed 和 Confirmed 重置；只有成功启动的 Reference / Direct / Wet / Full 才计入试听进度。Human Pass 必须设备非空、四模式齐全且 Confirmed=5/5，Human Fail 在设备非空并成功试听任一模式后即可提前记录。
  • 人工记录升级为 schema v3，并从 comparison manifest 固化输入资产、Source、Listener、场景 signature、Direct 预设、反射环境、自动检查、模式差异和三项音频指标；五项确认保存为独立布尔字段。保存采用临时文件后原子发布；独立 validate_human_acceptance.py 会重新读取 manifest，拒绝旧 schema、空设备、缺失试听模式、缺失/非布尔/未通过确认、重复/未知模式和来源篡改。--require-pass 额外要求人工 PASS、自动检查通过和模式确有差异。
  • 最终可见硬件工件 TestProject/UeVersion1/Saved/UERayTracingAudio/ListeningAcceptance/HardwareValidation/20260806-121645/MarchingBand_clear_HardwareIR_clear_20260806-121645_Manifest.json 通过自动门禁。截图 Saved/Validation/human-acceptance-schema-v3.png 已目视确认设备/备注输入、五项确认文字、Previewed=none、Confirmed=0/5、四条真实波形及禁用的 Human Pass/Fail；Editor 日志 TestProject/UeVersion1/Saved/Logs/UERayTracingAudioValidation-Editor-1786018587178540700.log 记录 human_record_schema=3 device_required=1 pass_requires_all_modes=1 pass_requires_confirmations=5，PID 12672 已保留供人工试听。
  • 新鲜验证：Python 175/175；HumanAcceptance UE Automation 5/5；插件全量 Automation 81/81；音频回调审计 39 functions / 40 bodies / 0 forbidden operations；规定的 UE 5.7 Development 构建成功。最终固定硬件运行 Direct sweep 223 generations、dropout 0，Baked/Realtime/Hybrid Wet 均 24/24，hard realtime 1578/0/0，交互 smoke passed=1。Game 日志为 UERayTracingAudioValidation-Game-1786018541593742800.log。
  • 历史 HumanAcceptance PASS 和较弱的 schema-v2 合约都不符合最终 schema v3，不能作为最终证据；本轮没有代替用户勾选确认或生成 PASS。目标设备上的 Direct/Wet/Full 听感、移动遮挡、环境差异和 click/pop 结论仍未完成。

2026-08-06 可见 A/B 波形闭环

  • 目视检查 Saved/Validation/direct-clear.png 发现固定 artifact runner 虽已生成并导入四个比较资产，面板仍显示 Waveforms=waiting for comparison render，四条轨道只有空基线。根因是 AdoptValidationArtifactResult() 没有像面板内的 FinishOfflineRender() 一样调用 LoadComparisonWaveforms()。
  • 固定 artifact adoption 现在会从本次 Reference / Direct / Wet / Full PCM16 WAV 加载 512-bin peak envelope，并在四轨装入可见 Slate 控件失败时拒绝就绪。Editor 日志与 Python 门禁同时要求同一 manifest 的 waveforms=ready，防止“资产存在但波形未显示”再次误报通过。
  • 修复后截图 Saved/Validation/direct-clear-waveforms-ready.png 已目视确认四条同时间轴、同 full-scale 波形实际绘制：Reference 灰色、Direct 蓝色、Wet 紫色、Full 绿色。对应硬件 Clear artifact 的 Direct/Wet difference 为 1.615526、Wet stereo difference 为 0.506958、公共缩放为 1.0。
  • 同日 Clear/Soft/Hard 等距配对通过：同一 MarchingBand Reference SHA-256 为 23c6b47ad734298fd451f818d0a5eef7fd615b565a333b5b0a2ef93a716fa3aa，距离与距离衰减差均为 0，Direct gain 为 0.499334 / 0.174767 / 0，Soft/Clear 比例为 0.35。证据 manifest：TestProject/UeVersion1/Saved/UERayTracingAudio/ListeningAcceptance/DirectOcclusionPair/20260806-174518/DirectOcclusionPair_Manifest.json。
  • 新鲜验证：Python 162/162、插件全量 Automation 76/76、UE 5.7 项目/插件 Development 构建通过；源码审计 39 functions / 40 bodies / 0 forbidden operations。固定硬件运行通过，Direct sweep 214 generations、dropout 0，Baked/Realtime/Hybrid Wet 均为 24/24，hard realtime 为 1589 / 0 / 0。Game 日志：TestProject/UeVersion1/Saved/Logs/UERayTracingAudioValidation-Game-1786010143822170400.log；Editor 日志：UERayTracingAudioValidation-Editor-1786010324450223400.log。
  • 上述证据关闭“固定流程未显示波形”的实现缺口，但不替代目标耳机/扬声器上的 Direct/Wet/Full Human Pass，也不证明移动穿墙或模式切换无 click/pop。

2026-08-06 交互 F4 测量闭环

  • 交互 smoke 曾间歇报告 F4 原点误差 170.581 cm 或 380.551 cm。系统化复现证明 F4 放置本身立即到达 0 cm；旧门禁却在之后继续开放 WASD 的 17 秒 A/B 观察窗口末尾才测位置，因此合法的用户输入会被误归因成 F4 失败。
  • RED 用新 marker 合约证明旧 parser 无法表达“F4 即时成功、随后继续移动”。运行时现在在 phase 4 放置完成后立即保存 origin_return_error_cm 作为 F4 门禁，并把后续位移单独记录为不参与成败的 post_return_moved_cm；17 秒同步 A/B 连续播放观察保持不变。
  • 受控硬件复验在 phase 4 后注入 800 ms 前进输入，得到 origin_return_error_cm=0.000、post_return_moved_cm=50.900、smoke passed=1，证明可交互移动不再制造 F4 假失败。Game 日志：TestProject/UeVersion1/Saved/Logs/UERayTracingAudioValidation-Game-1786014660179327100.log。
  • 新鲜回归为 Python 163/163、插件全量 Automation 76/76、项目/插件 Development 构建成功、音频回调审计 39 functions / 40 bodies / 0 forbidden operations。无参数固定硬件运行 Direct sweep 209 generations、三种 IR Wet 均 24/24、hard realtime 1581/0/0；Game 日志：TestProject/UeVersion1/Saved/Logs/UERayTracingAudioValidation-Game-1786014440733607600.log。
  • 该修复只关闭自动交互门禁的测量时点缺陷；目标设备上的移动遮挡、模式切换 click/pop 和 Direct/Wet/Full 听感仍须人工验收。

2026-07-30 Hard-real-time 与实时卷积预算闭环

  • 模拟快照注册表改为 lock-free 生命周期管理；Spatialization/Occlusion 音频回调不再获取注册表 FRWLock，也不读取 UObject。
  • Realtime/Baked/Hybrid 的卷积 kernel、切换 crossfade 状态和工作区由非音频线程准备；音频线程只采用已准备对象。Bridge 的服务按 source 槽位轮转且受单次 PrepareBudget 和一次表扫描限制，避免高频 source 长期饿死。
  • 实时卷积每声道限定为 4 × 1024 = 4096 个 IR 样本，48 kHz 时直接卷积头部约为 85.33 ms。完整 Baked/离线 IR 不裁剪；实时头部之外的能量估计会交给 parametric late reverb，避免用无限分区换取不可控音频线程成本。
  • Prepared state pool 为活动声道提供至少一次并发切换的 headroom，并在准备完成后按真实 workspace 检查 512 MiB 上限；超额状态在非音频线程拒绝和回收。
  • 新的 hard-real-time 源码审计覆盖 31 个关键函数、32 个函数体、1437 行，拒绝回调期锁、heap 操作、共享所有权、阻塞和 UObject 访问；build_and_validate.py 在同步/构建前强制执行该审计。
  • 运行时门禁公开 callbacks / callback_capacity_misses / convolution_prepare_drops。最新固定验证为 197 / 0 / 0，因此本次运行没有发现回调容量不足或卷积准备容量丢弃。
  • 生产 Publish → Prepare → Bridge Service → audio-thread adopt 路径已经替换 Automation 中的测试专用 owning convolver 旁路；新增实时预算、512-lane 切换 headroom、公平服务和诊断解析回归。
  • 当前证据：Python 50/50、UE 音频 Automation 23/23、插件全量 Automation 38/38、规定的项目/插件完整构建与固定运行时验证全部通过。Game 日志为 TestProject/UeVersion1/Saved/Logs/UERayTracingAudioValidation-Game-1785417909352203200.log，Editor 日志为 UERayTracingAudioValidation-Editor-1785418090145276700.log。

2026-07-30 Original / Direct / Wet 连续性与 Full 峰值闭环

  • Original 与 Rendered 现在从同一 MarchingBand 采样零点同时启动并持续循环。硬件快照尚未就绪时只听 Original；只有目标 AudioComponent 的 Realtime Direct、Indirect 及左右 IR kernel 都有效后，Rendered 才允许自动淡入或由 F3 选择。17 秒多循环 smoke 中 ab_restart_count=0，避免把“重启后第一声”误当持续 Direct。
  • 首个有效 Direct 快照会从物理增益开始；若快照晚于首个音频缓冲，则在一个缓冲内从 unity 平滑到目标。快照移除时平滑回 unity，零帧回调不会消耗渐变。运行时 Soft Occlusion 的 Direct 不再归零，Hard Occlusion 才允许接近静音。
  • IndirectMix 的正式语义是 Wet Send，不是互斥 dry/wet 比例：Full = Direct + WetSend × Wet。新 Source、Editor 验收场景和离线请求默认 1.0，范围 0..4；运行时主验收夹具显式使用 1.75 作为可听补偿。Bake 启动时冻结 Source、Listener、输入 SoundWave、Actor 路径和 Wet Send，避免异步完成前切换选择污染结果。
  • Full 峰值诊断覆盖 UE 的两条真实输出路径：双声道 MarchingBand 绕过自定义 Spatialization 时使用 Occlusion 的最终输出；单声道进入 Spatialization 时使用最终 L/R 重组后的输出。两条路径都有确定性 RED/GREEN Automation，且非有限最终样本会被计数并清零。
  • 最新 180 秒硬件运行门禁中，Baked / Realtime / Hybrid 的 full_peak 分别为 0.032985 / 0.033651 / 0.114308，over_unit=0/0/0，non_finite=0；Wet 持续覆盖分别为 24/24、57/57、24/24，积分 Wet/Input RMS 分别为 0.501271 / 0.050046 / 0.773309。
  • 自动移动 smoke 曾暴露 F4 传送后残余速度令原点漂移 170.581 cm；复位现在同时清空 Pawn 移动输入并调用 StopMovementImmediately()。重跑结果为移动 50.900 cm、Listener/相机误差 0 cm、F4 原点误差 0 cm，三种 IR、F3 双链路与 F8 双视角全部通过。
  • 该阶段验证证据：Python 44/44、UE 音频 Automation 13/13、规定的项目/插件完整构建成功；对应运行日志为 TestProject/UeVersion1/Saved/Logs/UERayTracingAudioValidation-Game-1785409168313219000.log，Editor readiness 日志为 UERayTracingAudioValidation-Editor-1785409349036387700.log。最新完整证据见上一节。

2026-07-29 持续 Direct / Indirect 修复

  • 运行时“一开始有声、随后消失”不是正常距离衰减：音频组件和 MarchingBand 实际仍在循环，旧场景在首个光追快照到达后把 Direct 压到了近静音。Direct 距离项现按线性声压幅度使用 1/r，不再把声强的 1/r² 直接乘到样本上；Soft Occlusion 保留明确的透声下限，Hard Occlusion 才允许完全遮挡接近静音。
  • 固定门禁中的 Clear / Soft / Hard Direct 预设统一为 2 m：Clear 位于墙体同侧，Soft / Hard 位于墙体两侧，避免用距离差冒充遮挡效果。自动化覆盖 1 m / 2 m / 4 m 幅度 1 / 0.5 / 0.25 且持续非零。
  • Editor 的 Reference / Direct / Wet / Full 比较资产改为循环预听，并跟踪实际 Preview AudioComponent；Stop、外部替换、面板销毁或播放结束都会同步清理状态。
  • Realtime IR 高频更新改为有界的单槽 last-wins pending：当前卷积核继续保留历史和尾音，预热/交叉淡化完成后才切到最新 IR，避免每次 GPU generation 都重新进入静音预热。
  • Baked 数据源检查结束后恢复 HybridReverb，Realtime / Hybrid 必须实际启用 parametric late tail。Wet 门禁不再接受一次峰值：每种数据源的总缓冲和输入 RMS 有效缓冲均至少 24；有效缓冲中 Wet RMS presence（> 1e-8）至少覆盖 80%，最长 Wet 完全静音连续段不超过有效观察窗的 20%；按帧积分的窗口 Wet/Input RMS 与最大 Wet/Input RMS 均须 >= 5%。逐缓冲 audible_wet / max_inaudible_run 仅作诊断，不作为通过条件。
  • Python 脚本回归当前为 41/41；本轮 UE 构建、硬件运行时与人工试听结果在完成后补记。

功能矩阵

范围 实现状态 当前证据 剩余验收
Direct 已实现 距离衰减、空气吸收、方向、硬件可见性；Direct dry correlation 门禁 距离扫描、移动穿墙和目标设备试听
Occlusion 已实现 Clear/Soft/Hard 等距预设；visibility 1/0/0，Direct gain 随遮挡收敛 连续移动遮挡无 click/pop 试听
Reflections 已实现 GPU EnergyField，多 bounce 路径和方向 delay bins 开放空间、靠墙场景补充验收
Reverb 已实现 early/late 分离、Stereo Wet、Full = Direct + Wet Send × Wet 目标设备确认 Wet 尾声合理且不淹没 Direct
Realtime IR 已实现 硬件 RHI 路径可观察，Realtime Stereo kernel 非静音 实际关卡长期运行验收
Baked IR 已实现 Editor 异步 Bake、Stereo IR 资产保存/加载/stale 校验 用户场景资产验收
Hybrid IR 已实现 Baked early + Realtime tail 互补交叉渐变 移动和切换时的人耳 click/pop 验收
离线对比 已实现 同输入、同起点、同长度 Reference/Direct/Wet/Full，共用安全缩放 10–20 秒语音/音乐素材试听
波形对比 已实现、构建并目视通过 direct-clear-waveforms-ready.png 中四条同时间轴、同 full-scale 波形实际绘制；启动器要求 waveforms=ready 目标设备完成人耳 A/B
Human A/B 界面已实现 四模式播放、Reference↔Direct/Full、Replay、Human Pass/Fail JSON 目标耳机/扬声器记录 PASS
交互实时验收 已实现并通过自动交互 smoke Pawn 移动 50.900 cm；Listener/相机和 F4 原点误差均 0 cm；F1/F2/F5、F3 双链路和 F8 均通过 实际 PIE 移动穿墙和人耳 click/pop 验收
Hard realtime 已实现并通过门禁 lock-free 快照、非音频线程 Prepared state、源码审计；运行时 197 / 0 / 0 后续每次发布持续保持零违规

硬件光追路径

  • 静态网格声学几何优先提交 UE Ray Tracing RHI。
  • Direct 可见性和 Indirect EnergyField 都通过跨帧渲染线程查询；音频线程只消费快照，不读取 UObject。
  • 日志公开硬件/CPU fallback 路径、fallback 原因、batch source 数、有效路径、IR energy 和方向统计。
  • 固定验证把硬件结果与 CPU acoustic-scene reference 对照；当前门禁要求路径、增益、IR 能量和方向指标处于容差内。

音频渲染链路

  1. Source/Listener/Geometry 在 Game Thread 注册并发布场景快照。
  2. Manager 批量提交 Direct 与 Indirect RHI 查询。
  3. 模拟结果通过双缓冲快照交给音频线程。
  4. Spatialization/Occlusion 分离 Direct 与 Wet，避免同一衰减重复应用。
  5. Indirect Renderer 根据 Realtime、Baked 或 Hybrid 数据源更新左右卷积核，并平滑切换。
  6. Editor Offline Renderer 使用同一原始 SoundWave 生成对齐的 Reference、Direct、Wet、Full WAV/SoundWave 和 manifest。

最近已知验证

  • 2026-08-06：当前工作树 32-bounce OpenSpace/NearWall/Enclosed 硬件矩阵通过；有效路径 0/618/20351，12/12 WAV 哈希和 PCM16 头一致，三环境真实波形已目视核对。
  • 2026-08-06：矩阵后固定交互 smoke 通过，Direct 212 generations、三种 IR Wet 24/24、hard realtime 1589/0/0、F4 即时误差 0 cm；Editor PID 44260 已留给人工验收。
  • 2026-08-06：Python 162/162、插件全量 Automation 76/76、UE 5.7 项目/插件 Development 构建与固定硬件运行通过；音频回调审计 39/40/0，hard realtime 1589/0/0。
  • 2026-08-06：Clear/Soft/Hard 等距硬件配对通过，Direct gain 0.499334/0.174767/0；固定 artifact adoption 已显示 Reference/Direct/Wet/Full 四轨真实波形，严格门禁要求 waveforms=ready。
  • 2026-07-30：Python 50/50、UE 音频 Automation 23/23、插件全量 Automation 38/38、UE 5.7 项目/插件完整构建通过。
  • 2026-07-30：固定硬件门禁通过；4 Source Direct/Indirect batch 均为 4，GPU/CPU 有效路径均为 171，增益均为 0.001625；Baked/Realtime/Hybrid 的 Wet 有效缓冲为 24/24、54/54、24/24，Full 峰值为 0.032427 / 0.033646 / 0.114014，越界与非有限样本均为 0。
  • 2026-07-30：hard-real-time 门禁通过：源码审计 31 functions / 32 bodies / 1437 lines，运行时 callbacks=197、callback_capacity_misses=0、convolution_prepare_drops=0。
  • 2026-07-30：自动交互 smoke 通过：移动 50.900 cm、Listener/相机误差 0 cm、F4 原点误差 0 cm、A/B 重启 0、外部播放声源 0；Editor 已由固定脚本打开等待人工 PIE 试听。
  • 2026-07-29：Python 36/36 通过，包含工作区内项目发现、交互启动命令、F3 双链路解析和 Editor/Bake 夹具隔离。
  • 2026-07-29：工作区内 TestProject/UeVersion1 的 UE 5.7 Development Editor 项目与插件完整构建通过；默认验证不再选择工作区外的同名工程。
  • 2026-07-29：固定 -game 验证通过：4 个 Source 的 Direct/Indirect 硬件批次、GPU/CPU 路径与增益、Realtime/Baked/Hybrid、真实 MarchingBand 输入及实际非静音音量均满足门禁。
  • 2026-07-29：自动交互 smoke 通过：移动 250.901 cm、Listener/相机误差 0 cm、F4 原点误差 0 cm，Realtime/Baked/Hybrid、Rendered/Original、固定/交互视角及双音频播放均通过。
  • 2026-07-29：--interactive-runtime Editor readiness 通过，确认 static_bake_fixture=0，Editor 已留给用户进入 PIE。
  • 2026-07-29：测试项目已移除 Ravel 资产、引用它的旧 World Partition AudioActor 及 Asset Registry 缓存记录；Content/FirstPerson/Audio 仅保留 MarchingBand.uasset。
  • 2026-07-26：Python 32/32 通过。
  • 2026-07-26：UE Automation 21/21 通过。
  • 2026-07-26：UE 5.7 Development Editor 项目与插件构建通过。
  • 已有 Clear/Soft/Hard、1/8 bounce、Realtime/Baked/Hybrid、Bake repeatability、8/16/32 source 性能证据。
  • 波形 UI 已在 Editor 截图中目视确认实际绘制；仍需完成目标设备移动、模式切换和听感验收。

已知未完成项

  • 目标耳机/扬声器 Human Pass 尚未记录。
  • 10–20 秒且同时含清晰语音和瞬态/音乐的最终验收输入尚未由用户确认。
  • 移动穿墙、距离扫描、开放空间、靠墙位置的完整试听矩阵尚未完成。
  • HRTF 暂不作为 v1 硬门槛；当前方向输出为 Stereo panning/方向性 IR。

完成标准

只有以下条件同时成立才可关闭总目标：

  • 当前工作树重新构建、自动化和固定运行时验证全部通过；
  • Editor 中硬件路径、四模式资产、同轴波形和 A/B 控件可见；
  • Direct/Full 保留可辨识原始主体，Wet-only 是合理空间尾声；
  • 目标设备上无削波、异常噪声、掉音、click/pop 或时间跳变；
  • Human Pass JSON 记录输入、场景、设备和结论；
  • TODO.md、USAGE.md、IMPLEMENTATION_STATUS.md、progress_log.md 与证据一致。