用途
该技能为 AR/VR 应用实现 3D 音频定位与渲染，使用头相关传输函数（HRTF）等技术实时模拟空间声源。
适用场景
在构建需要真实音频的沉浸式 AR/VR 体验时使用，例如虚拟导览、游戏环境或通过声音方向与距离增强用户临场感的仿真。不适用于 2D 音频需求，因为对非空间应用会增加额外开销。
主要能力
- 基于 HRTF 的实时音频渲染，实现准确的 3D 定位。
- 支持动态声源更新，包括遮挡与混响效果。
- 与 AR/VR 框架集成，实现设备特定的音频输出（如耳机或空间扬声器）。
- 可配置参数，如声音衰减模型（反距离或对数）和频率范围（20Hz-20kHz）。
- 多声源处理，每会话支持最多 32 个并发音频源。
使用方式
始终先初始化音频上下文，然后设置带位置的声源。在实时应用中使用循环进行更新。CLI 方式下，将音频文件通过管道传给工具；API 方式下，按顺序调用端点。模式：导入库 > 创建音频上下文 > 添加声源 > 渲染并更新。退出时处理清理以释放资源。
常用命令/API
使用 OpenClaw CLI 进行快速原型开发，或使用 REST API 进行程序化控制。认证需要将 $SPATIAL_AUDIO_API_KEY 设置为环境变量。
CLI 命令：带定位渲染音频
spatial-audio render --input audio.wav --position 1.5 2.0 3.0 --hrtf default --output rendered.wav
该命令在指定的 3D 坐标处理音频文件。
API 端点：创建声源
向 https://api.openclaw.ai/spatial-audio/sources 发送 POST 请求，JSON 体为：
{ "sourceId": "src1", "position": [0, 0, 5], "audioUrl": "s3://bucket/audio.mp3" }
响应包含用于更新的声源句柄。
代码片段（Python）：初始化并定位音频
import openclaw.spatial_audio as sa
context = sa.init(hrtf='default')
source = sa.add_source(context, position=[1, 2, 3])
sa.update_position(source, [4, 5, 6])
配置格式：API 配置使用 JSON，例如：
{ "hrtfProfile": "custom", "attenuation": "inverse", "maxSources": 16 }
通过 CLI 加载：spatial-audio config load --file config.json。
集成说明
通过将 OpenClaw SDK 添加为依赖项进行集成（例如 pip install openclaw-sdk 或通过 npm 用于 JS）。运行时前设置 $SPATIAL_AUDIO_API_KEY。对于 AR/VR 框架，可包装在 Unity 的 AudioListener 或 WebXR 的 AudioContext 中——例如在 Unity 中，将 SpatialAudio 组件附加到主摄像机。确保音频设备兼容；检查浏览器是否支持 Web Audio API。对于多平台，使用 Three.js 等抽象层用于基于 Web 的 AR。
错误处理
始终检查返回码或异常以处理错误。常见问题：无效位置（如 NaN 值）返回错误码 400；音频设备不可用会引发 "DEVICE_NOT_FOUND"。使用 try-except 块处理：
try:
sa.render(context)
except sa.AudioError as e:
if e.code == 400:
print("Invalid position; correct coordinates.")
对于 CLI，解析 stderr 输出（例如 "Error: HRTF not loaded—use --hrtf flag"）。对网络故障等瞬时错误使用指数退避重试。
示例 1：AR 应用中的基础空间音频设置
为 AR 对象设置 3D 音频：
- 初始化上下文：sa.init(hrtf='builtin')
- 添加声源：source = sa.add_source(context, position=[0, 1, 2], audioUrl='object_sound.mp3')
- 在主循环中，根据用户位置更新：sa.update_position(source, user_coords)
- 渲染：sa.render(context)
这会创建一个在 AR 场景中相对于用户移动的声音。
示例 2：VR 仿真中的动态音频
对于具有移动声源的 VR 游戏：
使用 CLI 进行原型开发：spatial-audio render --input explosion.wav --position 10 0 0 --hrtf custom
在代码中（例如 JavaScript）：
const context = await sa.init();
const source = await sa.addSource(context, { position: [5, 0, 0] });
setInterval(() => sa.updateSource(source, [Math.random()*10, 0, 0]), 1000);
与 VR 框架集成，与头部追踪同步以实现沉浸效果。
图谱关系
- 相关集群：ar-vr（例如与 "ar-rendering" 技能共享依赖）。
- 入站链接：依赖 "audio-processing" 进行基础音频处理。
- 出站链接：通过提供空间反馈增强 "vr-interaction"。
- 跨技能：与 "3d-visualization" 集成，实现同步的音视频体验。