# WAIC YOUNG 音创宇宙视觉交付说明

## 当前交付形态

本项目现在采用“静态 show app + 主项目控制台”的结构：

- `index.html`：项目总入口，提供预览、录屏、单场景巡检和资产链接。
- `hunan-journey/index.html`：湖南 10 场景音乐旅程主视觉资产。
- `hunan-journey/manifest.json`：场景清单、默认入口、录屏入口和大屏比例配置。
- `energy-field/index.html`：上一版抽象能量场资产，保留为参考。
- `site/index.html`：报价/提案展示页。
- `scripts/build-cloudflare-pages.mjs`：生成 Cloudflare Pages 白名单发布包，只包含可公开视觉资产与必要 Three.js 运行时。

运行：

```bash
python3 -m http.server 4613 --bind 127.0.0.1
```

打开：

```text
http://127.0.0.1:4613/
```

线上地址：

```text
https://waic-music-visuals.pages.dev/
```

## 为什么不直接塞进 r3f-viz

联网调研和当前代码结构都指向同一个结论：短期不应把 `hunan-journey` 硬重构成 `r3f-viz/app` 的 React Three Fiber visualizer。

原因：

- `hunan-journey` 是演出型 show app，需要独立渲染循环、固定 2.58:1 构图、录屏/capture 模式和稳定 URL。
- `r3f-viz/app` 是 React + R3F/WebGPU 可视化编辑器，适合交互探索和参数化 visualizer，不适合在视觉方向未定时承载 10 个高复杂场景。
- Vite 的 `public` 目录适合承载静态资产，但当前资产还依赖本地 Three.js 模块路径；直接复制进 Vite public 并不会自动打包这些模块。

所以本轮采用更稳妥的交付路径：

1. 先把 show app 作为独立资产接入项目总入口。
2. 用 manifest 统一场景和入口。
3. 建立截图、hooks、单场景巡检验证。
4. 视觉方向确认后，再决定是否重构为 R3F visualizer 或保持独立演出应用。

## 官方资料依据

- Three.js `UnrealBloomPass`：Bloom 应作为后期高光辅助，不应成为主视觉主体。  
  https://threejs.org/docs/#examples/en/postprocessing/UnrealBloomPass
- Three.js `InstancedMesh`：大量重复楼体、树、人流、峰柱应使用实例化降低 draw call。  
  https://threejs.org/docs/#api/en/objects/InstancedMesh
- React Three Fiber 性能建议：复杂场景需要按需渲染、资源复用和组件边界控制。  
  https://r3f.docs.pmnd.rs/advanced/scaling-performance
- Vite public 静态资源：不经打包处理，按根路径原样提供，适合静态 show app 入口。  
  https://vite.dev/guide/assets.html#the-public-directory
- MDN `AnalyserNode`：频域数据适合驱动实时音频响应。  
  https://developer.mozilla.org/en-US/docs/Web/API/AnalyserNode
- Resolume BPM：VJ 内容最好按 beat / bar / phrase 结构同步，视觉事件适合使用 4、8、16、32 拍这类倍数。  
  https://resolume.com/support/en/bpm
- MDN `HTMLCanvasElement.captureStream()`：后续如做浏览器内录制，可从 canvas 捕获视频流。  
  https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/captureStream

## 演出/录屏入口

Cloudflare 生产入口：

```text
https://waic-music-visuals.pages.dev/
```

生产入口默认是简洁演出预览台：首屏保留简洁预览、录屏输出、全屏、新窗口和多画幅选择。单场景巡检、纯均衡器、张家界样板、报价页和交付文档都收进“高级控制”，避免观演或客户预览时先看到复杂控制台。

画幅 / 输出预设：

```text
2.58:1  3840x1488  ar=2.58
16:9    1920x1080  ar=16:9
21:9    2560x1080  ar=2.333
9:16    1080x1920  ar=0.5625
```

顺播预览：

```text
https://waic-music-visuals.pages.dev/hunan-journey/index.html?auto=1&ar=2.58&mode=hybrid&ui=0
```

张家界高精样板：

```text
https://waic-music-visuals.pages.dev/hunan-journey/index.html?ar=2.58&mode=scenes&scene=5&ui=0
```

演出控制调试：

```text
http://127.0.0.1:4613/hunan-journey/index.html?auto=1&ar=2.58&mode=hybrid
```

纯净预览：

```text
http://127.0.0.1:4613/hunan-journey/index.html?auto=1&ar=2.58&mode=hybrid&ui=0
```

录屏输出：

```text
http://127.0.0.1:4613/hunan-journey/index.html?auto=1&ar=2.58&mode=hybrid&capture=1
```

独立 3D 视觉均衡器：

```text
http://127.0.0.1:4613/hunan-journey/index.html?auto=1&ar=2.58&mode=equalizer
```

单场景巡检：

```text
http://127.0.0.1:4613/hunan-journey/index.html?ar=2.58&mode=scenes&scene=1
...
http://127.0.0.1:4613/hunan-journey/index.html?ar=2.58&mode=scenes&scene=10
```

## 导演逻辑

当前演出逻辑采用三层结构：

- 微节奏层：低频、 中频、 高频持续驱动均衡器柱体、粒子、Bloom、平滑镜头推进速度和轻微 FOV 呼吸。
- 乐句层：`hybrid` 模式按 32 拍组织：前 8 拍是独立 3D 视觉均衡器段落，中段进入融合过渡，第 17-24 拍切入湖南场景插入段落。
- 段落层：白天 / 黄昏 / 夜晚光照预设随乐句推进，不再把所有地标都放在夜景灯光里。
- 运镜层：相机轨道、注视点和 FOV 使用 delta-time 阻尼更新，避免节拍或切场造成“一抽一抽”的硬跳。
- 场景均衡器层：每个湖南场景拥有独立 equalizer anchor/layout。水面场景贴水线，天门山音波上移到星空，武陵源进入云海谷地，IFS 放到塔冠高度，文和友贴近霓虹街道，避免 10 个场景共用同一条音波。

这意味着“原有图像均衡器逻辑”不只是场景里的小融合层，而是拥有独立 3D 段落；湖南 10 场景是导演镜头插入和环境叙事层，二者在节目中交替出现。

## 验收状态

已完成：

- 10 场景入口可切换。
- fallback BPM 可在无音频授权时继续驱动画面。
- `window.__hooks.ready` / `error` / `stats` / `setScene()` 可用于自动化验收。
- Headless Chrome + SwiftShader 截图验证可用。
- 根目录控制台可直接进入顺播、录屏、单场景巡检。
- 根入口全屏按钮已通过真实点击验证：预览 iframe 显式允许 fullscreen，点击后 `document.fullscreenElement` 为 `IFRAME`。
- 10 个湖南场景的 equalizer anchor/layout 已纳入自动化验证，防止后续退回统一位置。
- Cloudflare Pages 已发布到 `waic-music-visuals.pages.dev`，线上 hooks 与 10 场景巡检验证通过。
- Cloudflare 发布包已将 Three.js 从 `node_modules` 路径 vendor 到 `vendor/three`，避免 Pages 对 `node_modules` 路径回退为 HTML。
- 第 5 场“张家界 · 武陵源”已完成第一版高精样板：程序化岩纹、密集峰林、云海、玻璃栈道、瀑布、植被冠层和能量地形母体。
- 导演镜头连续性已修复：验证脚本会采样 `cameraDelta`、`cameraSpeed` 和 `cameraFov`，用于检查镜头是否存在瞬时跳变。
- 根入口已支持 2.58:1、16:9、21:9、9:16 多画幅切换和全屏预览。
- `hybrid` 已支持独立 3D 均衡器段落与湖南场景段落穿插；验证脚本会检查 `visual3dMix` 与 `sceneMix`。

未完成：

- 除第 5 场外，其余地标仍为低模意向，不是最终比例化重建。
- 尚未接入真实节目 cue sheet。
- 尚未做每个场景的高精 Sky / Water / PMREM / 昼夜三态 / 标志性运镜。
- 源码开发态仍使用 `r3f-viz/app/node_modules/three` 的本地模块路径；Cloudflare 发布态已由脚本重写为 `vendor/three`。

## 下一阶段建议

优先级从高到低：

1. 建立 `cue.json`，用真实音乐时间轴替代当前 32 拍 fallback 编排。
2. 按第 5 场资产语法继续高精化 1、10 两个对比强的样板。
3. 为每个场景补 `?shot=hero|wide|detail` 运镜入口。
4. 把源码开发态也迁移到统一 `vendor/three` 或正式构建系统，减少本地路径差异。
5. 通过 `scripts/verify-waic-visuals.mjs` 扩展截图矩阵，视觉评分达到 90 后再进入交付候选。