用途
threejs-audio 是一个面向 three.js 音频空间化的技能，用于在三维场景中处理声音的播放、定位与可视化。当用户提到 AudioListener 挂载到相机、Audio 与 PositionalAudio 的选择、距离模型、refDistance/maxDistance/rolloff、AudioAnalyser 频谱可视化，或浏览器自动播放策略阻止音频启动时，应使用该技能。触发词包括 PositionalAudio、AudioListener、AudioAnalyser、panner，以及中文的“空间音频”“音量衰减”“频谱”。
主要能力
- 将 AudioListener 附加到相机对象，使头部相关音频跟随视角变化。
- 创建与浏览器用户手势解锁模式兼容的 AudioContext。
- 使用 PositionalAudio，并按文档设置 refDistance、maxDistance、rolloffFactor、distanceModel 等空间化参数。
- 通过 AudioAnalyser 获取 FFT 与时域数据，用于可视化条形图或频谱。
- 连接音频图：按示例使用 listener.context.createAnalyser() 等路径。
使用方式
- 将监听器挂载到相机对象，使音频随视角移动。
- 创建与用户手势解锁模式兼容的上下文。
- 为 PositionalAudio 设置 refDistance、maxDistance、rolloffFactor、distanceModel。
- 通过 AudioLoader（属于 threejs-loaders 技能）加载缓冲，再调用 positionalAudio.setBuffer。
- 分析器按示例连接音频图，并关注性能。
- 音频节点通常无需逐帧更新，除非需要手动跟随移动声源。
工作流示例见 examples/workflow-positional-audio.md。
职责边界
- 解码 mp3/ogg 缓冲由 threejs-loaders（AudioLoader）负责。
- 空间播放 API 由本技能负责。
- 范围内：核心 Audio 类、空间化参数、分析器用法概览。
- 范围外：FMOD/Wwise 风格的音频创作工具。
适用场景
- 需要声音随相机视角变化的三维场景。
- 需要位置音效与距离衰减的交互体验。
- 需要基于音频数据驱动可视化（频谱条、波形）的场景。
限制与注意事项
- 自动播放限制要求用户交互才能恢复 AudioContext。
- 过多位置声源会增加 CPU 负担，建议使用池化或 LOD 音频。
- 需确保世界单位与距离模型的预期一致。
- 不应承诺 DAW 级别的混音能力，应保持在 three.js 音频范围内。
官方文档映射
- AudioListener：https://threejs.org/docs/AudioListener.html
- Audio：https://threejs.org/docs/Audio.html
- PositionalAudio：https://threejs.org/docs/PositionalAudio.html
- AudioAnalyser：https://threejs.org/docs/AudioAnalyser.html
- 扩展列表：references/official-sections.md
- 总览：https://threejs.org/docs/#Audio
版本说明
Audio 类位于 three.js 文档的 Audio 部分。缓冲解码使用 AudioLoader，参见 threejs-loaders。浏览器 Web Audio 策略属于外部因素，但当 AudioContext 处于 suspended 状态时必须提及。