HarmonyOS开发中的空间音频：空间音频原理、头部追踪、3D 音效渲染与兼容性实战

核心要点：空间音频是音频技术的"下一件大事"。本文从空间音频的声学原理入手，深入讲解头部追踪（Head Tracking）的实现机制、3D 音效渲染管线、空间音频的配置与调优、不同设备的兼容性处理，以及在鸿蒙生态中落地空间音频的完整方案。

一、背景与动机

你有没有在电影院体验过这样的感觉——直升机从头顶飞过，声音从左后方移到右前方，你甚至下意识地扭头去看？

这就是空间音频的魔力。它不仅仅是"环绕声"——环绕声只是把声音放在你周围的固定位置，而空间音频还能让声音跟随你的头部移动，创造出真正的"身临其境"感。

在移动设备上，空间音频的应用场景越来越广：

• 沉浸式视频：用耳机看电影，也能感受到影院级的空间感
• AR/VR 体验：虚拟世界中的声音必须随头部转动而变化
• 游戏：听声辨位，从脚步声判断敌人方向
• 导航：语音提示从转弯方向传来，不用看屏幕
• 音乐：Apple Music 的空间音频已经让很多人"回不去"了

鸿蒙系统从 API 12 开始提供空间音频支持，API 14 进一步增强了头部追踪和 3D 渲染能力。如果你在做沉浸式媒体应用，空间音频不再是"加分项"，而是"必修课"。

二、核心原理

2.1 空间音频的声学基础

人耳之所以能判断声音的方向，主要依赖三个线索：

1. ILD（耳间声级差）：声音到达左右耳的响度不同。右边的声音在右耳更响
2. ITD（耳间时间差）：声音到达左右耳的时间不同。右边的声音先到达右耳
3. HRTF（头部相关传输函数）：声音经过头部、耳廓的衍射和反射后，频谱特征发生变化。这个"滤波效应"是定位的关键

flowchart TD
    A[声源] --> B[空间音频引擎]
    B --> C{渲染方式}

    C --> D[双耳渲染 Binaural]
    D --> D1[应用 HRTF 滤波]
    D1 --> D2[计算 ILD + ITD]
    D2 --> D3[输出双声道耳机信号]

    C --> E[扬声器渲染]
    E --> E1[应用 VBAP/DBAP]
    E1 --> E2[计算各扬声器增益]
    E2 --> E3[输出多声道信号]

    C --> F[头部追踪]
    F --> F1[读取陀螺仪数据]
    F1 --> F2[更新 HRTF 参数]
    F2 --> F3[实时调整声像位置]

    classDef primary fill:#4FC3F7,stroke:#0288D1,color:#000
    classDef warning fill:#FFB74D,stroke:#F57C00,color:#000
    classDef error fill:#EF5350,stroke:#C62828,color:#fff
    classDef info fill:#81C784,stroke:#388E3C,color:#000
    classDef purple fill:#CE93D8,stroke:#7B1FA2,color:#000

    class A info
    class B primary
    class D,D1,D2,D3 warning
    class E,E1,E2,E3 purple
    class F,F1,F2,F3 info

2.2 HRTF：空间音频的核心

HRTF（Head-Related Transfer Function）描述了声音从空间中某个方向到达鼓膜时的频谱变化。每个人的 HRTF 都是独特的（因为每个人的头型和耳廓不同），但通用 HRTF 已经能提供不错的空间感。

HRTF 滤波过程：
原始音频 × HRTF(θ, φ) → 左耳信号
原始音频 × HRTF(θ+π, φ) → 右耳信号

其中：
θ = 水平角（方位角），0°=正前方，90°=正右方
φ = 仰角，0°=水平面，90°=正上方

2.3 头部追踪原理

头部追踪让空间音频"活"了起来。当你转头时，声源的位置应该相对于房间保持不变——也就是说，如果你面朝正前方时声音在右边，你向右转头 90° 后，声音应该变成在正前方。

flowchart LR
    A[设备陀螺仪/加速度计] --> B[传感器融合算法]
    B --> C[头部朝向四元数<br/>qx, qy, qz, qw]
    C --> D[空间音频引擎]
    D --> E[更新 HRTF 参数]
    E --> F[重新渲染音频]

    F --> G[耳机输出]

    classDef primary fill:#4FC3F7,stroke:#0288D1,color:#000
    classDef warning fill:#FFB74D,stroke:#F57C00,color:#000
    classDef error fill:#EF5350,stroke:#C62828,color:#fff
    classDef info fill:#81C784,stroke:#388E3C,color:#000
    classDef purple fill:#CE93D8,stroke:#7B1FA2,color:#000

    class A info
    class B,C primary
    class D,E purple
    class F,G warning

2.4 3D 音效渲染管线

完整的 3D 音效渲染管线包含以下步骤：

1. 声源定位：确定每个声源在 3D 空间中的位置（x, y, z）
2. 距离衰减：根据声源距离计算音量衰减
3. 多普勒效应：运动声源的频率偏移
4. 房间声学：早期反射和混响
5. HRTF 滤波：将 3D 声源映射到双耳信号
6. 双耳输出：最终的左右声道信号

三、代码实战

3.1 基础：启用系统空间音频

鸿蒙系统提供了系统级的空间音频开关，应用可以通过 API 查询和配置。

// 文件名：BasicSpatialAudio.ets
// 功能：查询和配置系统空间音频

import { audio } from '@kit.AudioKit';

@Entry
@Component
struct BasicSpatialAudioPage {
  @State isSpatialAudioSupported: boolean = false;
  @State isSpatialAudioEnabled: boolean = false;
  @State isHeadTrackingSupported: boolean = false;
  @State isHeadTrackingEnabled: boolean = false;
  @State deviceInfo: string = '检测中...';

  aboutToAppear() {
    this.checkSpatialAudioSupport();
  }

  // 检查空间音频支持情况
  async checkSpatialAudioSupport() {
    try {
      const audioManager = audio.getAudioManager();
      const spatializationManager = audioManager.getSpatializationManager();

      // 检查设备是否支持空间音频
      this.isSpatialAudioSupported = spatializationManager.isSpatializationSupported();
      console.info(`[Spatial] 空间音频支持: ${this.isSpatialAudioSupported}`);

      // 检查当前是否启用了空间音频
      this.isSpatialAudioEnabled = spatializationManager.isSpatializationEnabled();
      console.info(`[Spatial] 空间音频启用: ${this.isSpatialAudioEnabled}`);

      // 检查头部追踪支持
      this.isHeadTrackingSupported = spatializationManager.isHeadTrackingSupported();
      console.info(`[Spatial] 头部追踪支持: ${this.isHeadTrackingSupported}`);

      // 检查头部追踪是否启用
      this.isHeadTrackingEnabled = spatializationManager.isHeadTrackingEnabled();
      console.info(`[Spatial] 头部追踪启用: ${this.isHeadTrackingEnabled}`);

      // 更新设备信息
      this.deviceInfo = this.buildDeviceInfo();

    } catch (error) {
      console.error(`[Spatial] 检测失败: ${JSON.stringify(error)}`);
      this.deviceInfo = '检测失败';
    }
  }

  // 构建设备信息字符串
  private buildDeviceInfo(): string {
    const items: string[] = [];
    items.push(`空间音频: ${this.isSpatialAudioSupported ? '✓ 支持' : '✗ 不支持'}`);
    items.push(`头部追踪: ${this.isHeadTrackingSupported ? '✓ 支持' : '✗ 不支持'}`);
    items.push(`当前状态: ${this.isSpatialAudioEnabled ? '已启用' : '未启用'}`);
    return items.join('\n');
  }

  // 切换空间音频
  async toggleSpatialAudio(enable: boolean) {
    try {
      const audioManager = audio.getAudioManager();
      const spatializationManager = audioManager.getSpatializationManager();

      await spatializationManager.setSpatializationEnabled(enable);
      this.isSpatialAudioEnabled = enable;
      console.info(`[Spatial] 空间音频${enable ? '启用' : '禁用'}成功`);

    } catch (error) {
      console.error(`[Spatial] 切换失败: ${JSON.stringify(error)}`);
    }
  }

  // 切换头部追踪
  async toggleHeadTracking(enable: boolean) {
    try {
      const audioManager = audio.getAudioManager();
      const spatializationManager = audioManager.getSpatializationManager();

      await spatializationManager.setHeadTrackingEnabled(enable);
      this.isHeadTrackingEnabled = enable;
      console.info(`[Spatial] 头部追踪${enable ? '启用' : '禁用'}成功`);

    } catch (error) {
      console.error(`[Spatial] 头部追踪切换失败: ${JSON.stringify(error)}`);
    }
  }

  build() {
    Scroll() {
      Column() {
        Text('空间音频配置')
          .fontSize(24)
          .fontWeight(FontWeight.Bold)
          .fontColor('#E0E0E0')
          .margin({ bottom: 20 })

        // 设备支持情况
        Column() {
          Text('设备能力检测').fontSize(16).fontWeight(FontWeight.Bold).fontColor('#4FC3F7')
          
          Row() {
            this.CapabilityCard('空间音频', this.isSpatialAudioSupported)
            this.CapabilityCard('头部追踪', this.isHeadTrackingSupported)
          }
          .width('100%')
          .justifyContent(FlexAlign.SpaceAround)
          .margin({ top: 12 })
        }
        .width('100%')
        .padding(15)
        .borderRadius(12)
        .backgroundColor('#16213e')
        .margin({ bottom: 15 })

        // 空间音频开关
        Row() {
          Column() {
            Text('空间音频')
              .fontSize(16)
              .fontColor('#E0E0E0')
            Text('为耳机提供 3D 环绕声效果')
              .fontSize(12)
              .fontColor('#888888')
              .margin({ top: 4 })
          }
          .alignItems(HorizontalAlign.Start)
          .layoutWeight(1)

          Toggle({ type: ToggleType.Switch, isOn: this.isSpatialAudioEnabled })
            .onChange((isOn: boolean) => this.toggleSpatialAudio(isOn))
            .selectedColor('#6C63FF')
            .enabled(this.isSpatialAudioSupported)
        }
        .width('100%')
        .padding(15)
        .borderRadius(12)
        .backgroundColor('#16213e')
        .margin({ bottom: 10 })

        // 头部追踪开关
        Row() {
          Column() {
            Text('头部追踪')
              .fontSize(16)
              .fontColor('#E0E0E0')
            Text('声音随头部转动而变化')
              .fontSize(12)
              .fontColor('#888888')
              .margin({ top: 4 })
          }
          .alignItems(HorizontalAlign.Start)
          .layoutWeight(1)

          Toggle({ type: ToggleType.Switch, isOn: this.isHeadTrackingEnabled })
            .onChange((isOn: boolean) => this.toggleHeadTracking(isOn))
            .selectedColor('#6C63FF')
            .enabled(this.isHeadTrackingSupported && this.isSpatialAudioEnabled)
        }
        .width('100%')
        .padding(15)
        .borderRadius(12)
        .backgroundColor('#16213e')
        .margin({ bottom: 15 })

        // 提示信息
        Column() {
          Text('💡 使用提示')
            .fontSize(14)
            .fontWeight(FontWeight.Bold)
            .fontColor('#FFB74D')
          Text('• 空间音频需要佩戴耳机体验')
            .fontSize(12).fontColor('#AAAAAA').margin({ top: 8 })
          Text('• 头部追踪需要设备具备陀螺仪')
            .fontSize(12).fontColor('#AAAAAA').margin({ top: 4 })
          Text('• 部分蓝牙耳机内置头部追踪传感器')
            .fontSize(12).fontColor('#AAAAAA').margin({ top: 4 })
        }
        .width('100%')
        .padding(15)
        .borderRadius(12)
        .backgroundColor('#1a1a2e')
        .alignItems(HorizontalAlign.Start)
      }
      .width('100%')
      .padding(20)
    }
    .width('100%')
    .height('100%')
    .backgroundColor('#0d0d1a')
  }

  @Builder
  CapabilityCard(label: string, supported: boolean) {
    Column() {
      Text(supported ? '✓' : '✗')
        .fontSize(28)
        .fontColor(supported ? '#81C784' : '#EF5350')
      Text(label)
        .fontSize(13)
        .fontColor(supported ? '#E0E0E0' : '#888888')
        .margin({ top: 6 })
      Text(supported ? '支持' : '不支持')
        .fontSize(11)
        .fontColor(supported ? '#81C784' : '#EF5350')
        .margin({ top: 2 })
    }
    .width(140)
    .height(100)
    .justifyContent(FlexAlign.Center)
    .borderRadius(12)
    .backgroundColor('#1a1a2e')
  }
}

3.2 进阶：3D 音效渲染器——声源位置控制

在游戏和 AR 应用中，你需要精确控制每个声源在 3D 空间中的位置。下面的示例展示了如何实现一个 3D 音效渲染器。

// 文件名：SpatialAudioRenderer.ets
// 功能：3D 音效渲染器——控制声源在 3D 空间中的位置

import { audio } from '@kit.AudioKit';

// 3D 空间中的声源
interface SpatialSource {
  id: string;
  name: string;
  // 3D 坐标（米），以听者头部为原点
  x: number;  // 左右：负=左，正=右
  y: number;  // 上下：负=下，正=上
  z: number;  // 前后：负=前，正=后
  // 声源属性
  volume: number;     // 音量 0.0~1.0
  minDistance: number; // 最小衰减距离（米）
  maxDistance: number; // 最大衰减距离（米）
  isPlaying: boolean;
}

// 听者状态
interface ListenerState {
  x: number;
  y: number;
  z: number;
  // 朝向（欧拉角，度数）
  yaw: number;    // 水平旋转
  pitch: number;  // 俯仰
  roll: number;   // 翻滚
}

@Entry
@Component
struct SpatialAudioRendererPage {
  // 听者位置
  @State listener: ListenerState = { x: 0, y: 0, z: 0, yaw: 0, pitch: 0, roll: 0 };

  // 声源列表
  @State sources: SpatialSource[] = [
    { id: 'src_1', name: '鸟鸣', x: -3, y: 2, z: -5, volume: 0.7, minDistance: 1, maxDistance: 20, isPlaying: true },
    { id: 'src_2', name: '流水', x: 4, y: 0, z: -3, volume: 0.6, minDistance: 1, maxDistance: 15, isPlaying: true },
    { id: 'src_3', name: '风声', x: 0, y: 5, z: -8, volume: 0.4, minDistance: 2, maxDistance: 30, isPlaying: true },
  ];

  @State selectedSourceIndex: number = 0;
  @State spatialAudioActive: boolean = false;

  aboutToAppear() {
    this.enableSpatialAudio();
  }

  // 启用空间音频
  async enableSpatialAudio() {
    try {
      const audioManager = audio.getAudioManager();
      const spatializationManager = audioManager.getSpatializationManager();

      if (spatializationManager.isSpatializationSupported()) {
        await spatializationManager.setSpatializationEnabled(true);
        this.spatialAudioActive = true;
        console.info('[Spatial3D] 空间音频已启用');
      } else {
        console.warn('[Spatial3D] 设备不支持空间音频');
      }
    } catch (error) {
      console.error(`[Spatial3D] 启用失败: ${JSON.stringify(error)}`);
    }
  }

  // 计算声源到听者的距离
  private calculateDistance(source: SpatialSource): number {
    const dx = source.x - this.listener.x;
    const dy = source.y - this.listener.y;
    const dz = source.z - this.listener.z;
    return Math.sqrt(dx * dx + dy * dy + dz * dz);
  }

  // 计算距离衰减后的音量
  private calculateAttenuatedVolume(source: SpatialSource): number {
    const distance = this.calculateDistance(source);

    if (distance <= source.minDistance) {
      // 在最小距离内，不衰减
      return source.volume;
    } else if (distance >= source.maxDistance) {
      // 超出最大距离，静音
      return 0;
    } else {
      // 线性衰减（实际应用中常用对数衰减）
      const attenuation = 1 - (distance - source.minDistance) / (source.maxDistance - source.minDistance);
      return source.volume * attenuation;
    }
  }

  // 计算声源相对于听者的方位角
  private calculateAzimuth(source: SpatialSource): number {
    // 考虑听者的朝向
    const dx = source.x - this.listener.x;
    const dz = source.z - this.listener.z;
    // 转换为角度，0°=正前方
    let azimuth = Math.atan2(dx, -dz) * (180 / Math.PI);
    // 减去听者朝向
    azimuth -= this.listener.yaw;
    // 归一化到 -180° ~ 180°
    while (azimuth > 180) azimuth -= 360;
    while (azimuth < -180) azimuth += 360;
    return azimuth;
  }

  // 计算仰角
  private calculateElevation(source: SpatialSource): number {
    const dx = source.x - this.listener.x;
    const dy = source.y - this.listener.y;
    const dz = source.z - this.listener.z;
    const horizontalDist = Math.sqrt(dx * dx + dz * dz);
    return Math.atan2(dy, horizontalDist) * (180 / Math.PI);
  }

  // 更新声源位置（拖动控制）
  updateSourcePosition(index: number, axis: 'x' | 'y' | 'z', value: number) {
    this.sources[index][axis] = value;
  }

  // 更新听者朝向（模拟头部转动）
  updateListenerYaw(yaw: number) {
    this.listener.yaw = yaw;
  }

  build() {
    Scroll() {
      Column() {
        Text('3D 音效渲染器')
          .fontSize(24)
          .fontWeight(FontWeight.Bold)
          .fontColor('#E0E0E0')
          .margin({ bottom: 8 })

        Text(this.spatialAudioActive ? '🎧 空间音频已启用' : '⚠️ 空间音频未启用')
          .fontSize(13)
          .fontColor(this.spatialAudioActive ? '#81C784' : '#FFB74D')
          .margin({ bottom: 20 })

        // 听者朝向控制
        Column() {
          Text('听者朝向（模拟头部转动）').fontSize(14).fontWeight(FontWeight.Bold).fontColor('#CE93D8')
          
          Row() {
            Text('← 左').fontSize(12).fontColor('#888888')
            Slider({
              value: this.listener.yaw,
              min: -180,
              max: 180,
              step: 1,
            })
              .onChange((value: number) => this.updateListenerYaw(value))
              .layoutWeight(1)
              .margin({ left: 8, right: 8 })
            Text('右 →').fontSize(12).fontColor('#888888')
          }
          .margin({ top: 10 })

          Text(`当前朝向: ${this.listener.yaw.toFixed(0)}°`)
            .fontSize(12)
            .fontColor('#4FC3F7')
            .margin({ top: 6 })
        }
        .width('100%')
        .padding(15)
        .borderRadius(12)
        .backgroundColor('#16213e')
        .margin({ bottom: 15 })

        // 声源列表
        Text('声源控制').fontSize(16).fontWeight(FontWeight.Bold).fontColor('#4FC3F7')
          .margin({ bottom: 10 })

        ForEach(this.sources, (source: SpatialSource, index: number) => {
          Column() {
            // 声源名称和状态
            Row() {
              Text(source.name)
                .fontSize(15)
                .fontWeight(FontWeight.Bold)
                .fontColor('#E0E0E0')
              Text(source.isPlaying ? '🔊' : '🔇')
                .fontSize(16)
                .margin({ left: 8 })
              Blank()
              // 方位信息
              Text(`方位: ${this.calculateAzimuth(source).toFixed(0)}° / 仰角: ${this.calculateElevation(source).toFixed(0)}°`)
                .fontSize(11)
                .fontColor('#4FC3F7')
            }
            .width('100%')

            // 位置控制滑块
            Row() {
              Text('X').fontSize(12).fontColor('#888888').width(16)
              Slider({ value: source.x, min: -10, max: 10, step: 0.5 })
                .onChange((v: number) => this.updateSourcePosition(index, 'x', v))
                .layoutWeight(1)
              Text(source.x.toFixed(1)).fontSize(11).fontColor('#AAAAAA').width(35)
            }
            .margin({ top: 8 })

            Row() {
              Text('Y').fontSize(12).fontColor('#888888').width(16)
              Slider({ value: source.y, min: -5, max: 10, step: 0.5 })
                .onChange((v: number) => this.updateSourcePosition(index, 'y', v))
                .layoutWeight(1)
              Text(source.y.toFixed(1)).fontSize(11).fontColor('#AAAAAA').width(35)
            }

            Row() {
              Text('Z').fontSize(12).fontColor('#888888').width(16)
              Slider({ value: source.z, min: -15, max: 5, step: 0.5 })
                .onChange((v: number) => this.updateSourcePosition(index, 'z', v))
                .layoutWeight(1)
              Text(source.z.toFixed(1)).fontSize(11).fontColor('#AAAAAA').width(35)
            }

            // 距离和衰减信息
            Row() {
              Text(`距离: ${this.calculateDistance(source).toFixed(1)}m`)
                .fontSize(11).fontColor('#888888')
              Text(' | ').fontColor('#555')
              Text(`衰减音量: ${(this.calculateAttenuatedVolume(source) * 100).toFixed(0)}%`)
                .fontSize(11)
                .fontColor(this.calculateAttenuatedVolume(source) > 0.3 ? '#81C784' : '#EF5350')
            }
            .margin({ top: 6 })
          }
          .width('100%')
          .padding(12)
          .borderRadius(10)
          .backgroundColor('#1a1a2e')
          .margin({ bottom: 8 })
        })

        // 3D 空间示意图（简化版）
        Column() {
          Text('空间示意图（俯视图）').fontSize(12).fontColor('#888888').margin({ bottom: 8 })

          Stack() {
            // 听者（中心）
            Circle({ width: 20, height: 20 })
              .fill('#6C63FF')
            Text('👂').fontSize(14)

            // 声源位置指示（简化展示）
            ForEach(this.sources, (source: SpatialSource) => {
              Circle({ width: 10, height: 10 })
                .fill(source.isPlaying ? '#4FC3F7' : '#555555')
                .position({
                  x: 80 + source.x * 8,  // 缩放到画布范围
                  y: 80 + source.z * 5,
                })
            })
          }
          .width(160)
          .height(160)
          .borderRadius(80)
          .backgroundColor('#0d0d1a')
          .border({ width: 1, color: '#333333' })
        }
        .width('100%')
        .padding(15)
        .borderRadius(12)
        .backgroundColor('#16213e')
        .alignItems(HorizontalAlign.Center)
        .margin({ top: 15 })
      }
      .width('100%')
      .padding(20)
    }
    .width('100%')
    .height('100%')
    .backgroundColor('#0d0d1a')
  }

  aboutToDisappear() {
    // 禁用空间音频
    const audioManager = audio.getAudioManager();
    const spatializationManager = audioManager.getSpatializationManager();
    spatializationManager.setSpatializationEnabled(false).catch(() => {});
  }
}

3.3 高级：空间音频兼容性处理器

不同设备对空间音频的支持程度不同。下面的示例展示了如何构建一个兼容性处理器，自动适配不同设备的能力。

// 文件名：SpatialAudioCompat.ets
// 功能：空间音频兼容性处理器——自动适配不同设备能力

import { audio } from '@kit.AudioKit';

// 设备空间音频能力等级
type SpatialCapabilityLevel = 'full' | 'basic' | 'none';

// 空间音频配置
interface SpatialAudioConfig {
  capabilityLevel: SpatialCapabilityLevel;
  enableSpatialization: boolean;
  enableHeadTracking: boolean;
  hrtfMode: 'individual' | 'generic';  // 个性化 HRTF 或通用 HRTF
  renderingMode: 'binaural' | 'stereo_widening' | 'standard';  // 渲染模式
  maxSources: number;                   // 最大声源数
  updateRate: number;                   // 头部追踪更新率（Hz）
}

class SpatialAudioCompatHandler {
  private config: SpatialAudioConfig;
  private spatializationManager: audio.SpatializationManager | null = null;

  constructor() {
    // 默认配置（最保守）
    this.config = {
      capabilityLevel: 'none',
      enableSpatialization: false,
      enableHeadTracking: false,
      hrtfMode: 'generic',
      renderingMode: 'standard',
      maxSources: 0,
      updateRate: 0,
    };
  }

  // 初始化并检测设备能力
  async init(): Promise<SpatialAudioConfig> {
    try {
      const audioManager = audio.getAudioManager();
      this.spatializationManager = audioManager.getSpatializationManager();

      // 检测各项能力
      const supportsSpatialization = this.spatializationManager.isSpatializationSupported();
      const supportsHeadTracking = this.spatializationManager.isHeadTrackingSupported();

      // 根据能力确定等级
      if (supportsSpatialization && supportsHeadTracking) {
        this.config.capabilityLevel = 'full';
        this.config.enableSpatialization = true;
        this.config.enableHeadTracking = true;
        this.config.hrtfMode = 'generic';
        this.config.renderingMode = 'binaural';
        this.config.maxSources = 16;
        this.config.updateRate = 60;
      } else if (supportsSpatialization) {
        this.config.capabilityLevel = 'basic';
        this.config.enableSpatialization = true;
        this.config.enableHeadTracking = false;
        this.config.hrtfMode = 'generic';
        this.config.renderingMode = 'binaural';
        this.config.maxSources = 8;
        this.config.updateRate = 0;
      } else {
        this.config.capabilityLevel = 'none';
        this.config.enableSpatialization = false;
        this.config.enableHeadTracking = false;
        this.config.renderingMode = 'standard';
        this.config.maxSources = 0;
        this.config.updateRate = 0;
      }

      // 应用配置
      await this.applyConfig();

      console.info(`[SpatialCompat] 设备能力: ${this.config.capabilityLevel}`);
      return this.config;

    } catch (error) {
      console.error(`[SpatialCompat] 初始化失败: ${JSON.stringify(error)}`);
      return this.config;
    }
  }

  // 应用配置到系统
  private async applyConfig() {
    if (!this.spatializationManager) return;

    try {
      // 设置空间音频开关
      await this.spatializationManager.setSpatializationEnabled(this.config.enableSpatialization);

      // 设置头部追踪开关
      if (this.config.enableHeadTracking) {
        await this.spatializationManager.setHeadTrackingEnabled(true);
      }

      console.info('[SpatialCompat] 配置已应用');

    } catch (error) {
      console.error(`[SpatialCompat] 应用配置失败: ${JSON.stringify(error)}`);
    }
  }

  // 获取当前配置
  getConfig(): SpatialAudioConfig {
    return { ...this.config };
  }

  // 获取降级方案描述
  getFallbackDescription(): string {
    switch (this.config.capabilityLevel) {
      case 'full':
        return '完整空间音频：支持双耳渲染 + 头部追踪，最佳沉浸体验';
      case 'basic':
        return '基础空间音频：支持双耳渲染，不支持头部追踪，声像位置固定';
      case 'none':
        return '不支持空间音频：使用标准立体声输出，可考虑声道展宽处理';
    }
  }

  // 为不支持空间音频的设备提供声道展宽方案
  applyStereoWidening(pcmData: Int16Array, channelCount: number, widthFactor: number): Int16Array {
    if (channelCount !== 2) return pcmData;

    // 简单的声道展宽算法：通过交叉馈送（Cross-feed）实现
    // left_out = left * (1 - factor) + right * factor
    // right_out = right * (1 - factor) + left * factor
    const factor = Math.max(0, Math.min(0.5, widthFactor));

    for (let i = 0; i < pcmData.length; i += 2) {
      const left = pcmData[i];
      const right = pcmData[i + 1];
      pcmData[i] = Math.floor(left * (1 - factor) + right * factor);
      pcmData[i + 1] = Math.floor(right * (1 - factor) + left * factor);
    }

    return pcmData;
  }

  // 清理资源
  async cleanup() {
    if (this.spatializationManager) {
      try {
        await this.spatializationManager.setSpatializationEnabled(false);
        await this.spatializationManager.setHeadTrackingEnabled(false);
      } catch (error) {
        // 忽略清理错误
      }
    }
  }
}

// ==================== UI 组件 ====================

@Entry
@Component
struct SpatialAudioCompatPage {
  private compatHandler: SpatialAudioCompatHandler = new SpatialAudioCompatHandler();

  @State config: SpatialAudioConfig = {
    capabilityLevel: 'none',
    enableSpatialization: false,
    enableHeadTracking: false,
    hrtfMode: 'generic',
    renderingMode: 'standard',
    maxSources: 0,
    updateRate: 0,
  };
  @State fallbackDesc: string = '检测中...';
  @State isInitialized: boolean = false;

  aboutToAppear() {
    this.initSpatialAudio();
  }

  async initSpatialAudio() {
    this.config = await this.compatHandler.init();
    this.fallbackDesc = this.compatHandler.getFallbackDescription();
    this.isInitialized = true;
  }

  build() {
    Scroll() {
      Column() {
        Text('空间音频兼容性')
          .fontSize(24)
          .fontWeight(FontWeight.Bold)
          .fontColor('#E0E0E0')
          .margin({ bottom: 20 })

        // 能力等级展示
        Row() {
          ForEach(['full', 'basic', 'none'] as SpatialCapabilityLevel[], (level: SpatialCapabilityLevel) => {
            Column() {
              Text(level === 'full' ? '🚀' : level === 'basic' ? '🎧' : '🔈')
                .fontSize(28)
              Text(level === 'full' ? '完整' : level === 'basic' ? '基础' : '不支持')
                .fontSize(13)
                .fontColor(this.config.capabilityLevel === level ? '#E0E0E0' : '#666666')
                .margin({ top: 6 })
            }
            .layoutWeight(1)
            .padding(12)
            .borderRadius(12)
            .backgroundColor(this.config.capabilityLevel === level ? '#6C63FF' : '#16213e')
            .border({
              width: this.config.capabilityLevel === level ? 2 : 0,
              color: '#6C63FF',
            })
          })
        }
        .margin({ bottom: 15 })

        // 降级方案说明
        Column() {
          Text('当前方案').fontSize(14).fontWeight(FontWeight.Bold).fontColor('#4FC3F7')
          Text(this.fallbackDesc)
            .fontSize(13)
            .fontColor('#AAAAAA')
            .margin({ top: 8 })
            .lineHeight(22)
        }
        .width('100%')
        .padding(15)
        .borderRadius(12)
        .backgroundColor('#16213e')
        .alignItems(HorizontalAlign.Start)
        .margin({ bottom: 15 })

        // 详细配置信息
        Column() {
          Text('配置详情').fontSize(14).fontWeight(FontWeight.Bold).fontColor('#CE93D8')

          Grid() {
            GridItem() {
              this.ConfigItem('空间音频', this.config.enableSpatialization ? '✓ 启用' : '✗ 禁用')
            }
            GridItem() {
              this.ConfigItem('头部追踪', this.config.enableHeadTracking ? '✓ 启用' : '✗ 禁用')
            }
            GridItem() {
              this.ConfigItem('HRTF 模式', this.config.hrtfMode === 'individual' ? '个性化' : '通用')
            }
            GridItem() {
              this.ConfigItem('渲染模式', this.config.renderingMode === 'binaural' ? '双耳' :
                              this.config.renderingMode === 'stereo_widening' ? '声道展宽' : '标准')
            }
            GridItem() {
              this.ConfigItem('最大声源', `${this.config.maxSources}`)
            }
            GridItem() {
              this.ConfigItem('追踪更新率', this.config.updateRate > 0 ? `${this.config.updateRate}Hz` : 'N/A')
            }
          }
          .columnsTemplate('1fr 1fr')
          .rowsTemplate('1fr 1fr 1fr')
          .width('100%')
          .height(200)
        }
        .width('100%')
        .padding(15)
        .borderRadius(12)
        .backgroundColor('#16213e')
        .margin({ bottom: 15 })

        // 兼容性建议
        Column() {
          Text('兼容性建议').fontSize(14).fontWeight(FontWeight.Bold).fontColor('#FFB74D')

          Text('1. 始终先检测设备能力再启用功能')
            .fontSize(12).fontColor('#AAAAAA').margin({ top: 8 })
          Text('2. 为不支持空间音频的设备提供声道展宽降级方案')
            .fontSize(12).fontColor('#AAAAAA').margin({ top: 4 })
          Text('3. 头部追踪是可选增强，不影响基本空间音频')
            .fontSize(12).fontColor('#AAAAAA').margin({ top: 4 })
          Text('4. 蓝牙耳机可能内置头部追踪，优先使用耳机传感器')
            .fontSize(12).fontColor('#AAAAAA').margin({ top: 4 })
          Text('5. 空间音频会增加约 10-15% 的 CPU 开销')
            .fontSize(12).fontColor('#AAAAAA').margin({ top: 4 })
        }
        .width('100%')
        .padding(15)
        .borderRadius(12)
        .backgroundColor('#1a1a2e')
        .alignItems(HorizontalAlign.Start)
      }
      .width('100%')
      .padding(20)
    }
    .width('100%')
    .height('100%')
    .backgroundColor('#0d0d1a')
  }

  @Builder
  ConfigItem(label: string, value: string) {
    Column() {
      Text(value).fontSize(14).fontWeight(FontWeight.Bold).fontColor('#E0E0E0')
      Text(label).fontSize(11).fontColor('#888888').margin({ top: 4 })
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
    .borderRadius(8)
    .backgroundColor('#1a1a2e')
  }

  aboutToDisappear() {
    this.compatHandler.cleanup();
  }
}

四、踩坑与注意事项

4.1 常见陷阱

4.2 距离衰减模型选择

// 三种常见的距离衰减模型

// 1. 线性衰减——简单但不够自然
function linearAttenuation(distance: number, minDist: number, maxDist: number): number {
  if (distance <= minDist) return 1.0;
  if (distance >= maxDist) return 0.0;
  return 1.0 - (distance - minDist) / (maxDist - minDist);
}

// 2. 对数衰减——更接近真实声学
function logarithmicAttenuation(distance: number, minDist: number): number {
  if (distance <= minDist) return 1.0;
  return minDist / distance;  // 反平方定律的简化版
}

// 3. 反平方衰减——物理精确但变化剧烈
function inverseSquareAttenuation(distance: number, minDist: number): number {
  if (distance <= minDist) return 1.0;
  const ratio = minDist / distance;
  return ratio * ratio;  // 1/r² 衰减
}

4.3 空间音频性能优化

1. 声源优先级排序：只渲染听者附近的 N 个声源，远处的静音或简化
2. HRTF 插值优化：相邻帧的 HRTF 变化很小时，可以跳过重新计算
3. 异步渲染：空间音频渲染放在独立线程，不阻塞主线程
4. 低精度模式：低端设备使用简化的 HRTF 数据集（减少滤波器阶数）

五、HarmonyOS 6 适配

5.1 版本差异

5.2 迁移指南

// HarmonyOS 5 写法——仅能控制系统级开关
const audioManager = audio.getAudioManager();
const spatializationManager = audioManager.getSpatializationManager();
await spatializationManager.setSpatializationEnabled(true);
// 无法控制声源位置、HRTF 参数等

// HarmonyOS 6 写法——使用应用级空间音频渲染器
// const renderer = audio.createSpatializationRenderer();
//
// // 创建声源
// const source1 = renderer.createSource({
//   position: { x: -3, y: 0, z: -5 },  // 左前方 5 米
//   volume: 0.7,
//   minDistance: 1,
//   maxDistance: 20,
//   attenuationModel: audio.AttenuationModel.LOGARITHMIC,
// });
//
// // 设置听者位置和朝向
// renderer.setListenerPosition({ x: 0, y: 0, z: 0 });
// renderer.setListenerOrientation({ yaw: 0, pitch: 0, roll: 0 });
//
// // 启用头部追踪
// renderer.enableHeadTracking(true);
//
// // 设置房间声学参数
// renderer.setRoomAcoustics({
//   roomSize: audio.RoomSize.MEDIUM,
//   reverberationTime: 0.8,  // 混响时间（秒）
//   earlyReflectionsGain: 0.3,
//   lateReverberationGain: 0.2,
// });
//
// // 向声源写入 PCM 数据
// source1.write(pcmBuffer);

5.3 注意事项

• HarmonyOS 6 的 AudioSpatializationRenderer 需要在创建 AudioRenderer 时指定空间音频标志
• 个性化 HRTF 校准需要用户配合测量（通常需要 5-10 分钟），建议提供"跳过"选项
• 房间声学参数对 CPU 开销影响较大，低端设备建议使用 RoomSize.SMALL 或关闭
• 蓝牙耳机的头部追踪传感器数据通过 GATT 协议传输，延迟约 20-30ms

六、总结

mindmap
  root((空间音频))
    声学原理
      ILD 耳间声级差
      ITD 耳间时间差
      HRTF 头部相关传输函数
      距离衰减模型
    头部追踪
      陀螺仪数据
      传感器融合
      四元数表示
      蓝牙耳机传感器
    3D 渲染管线
      声源定位
      距离衰减
      多普勒效应
      房间声学
      HRTF 滤波
    空间音频配置
      系统级开关
      应用级渲染器
      HRTF 模式选择
      声源数量限制
    兼容性处理
      能力等级检测
      降级方案
      声道展宽
      性能优化
    HarmonyOS 6
      AudioSpatializationRenderer
      个性化 HRTF
      多声源渲染
      房间声学模拟

    classDef primary fill:#4FC3F7,stroke:#0288D1,color:#000
    classDef warning fill:#FFB74D,stroke:#F57C00,color:#000
    classDef error fill:#EF5350,stroke:#C62828,color:#fff
    classDef info fill:#81C784,stroke:#388E3C,color:#000
    classDef purple fill:#CE93D8,stroke:#7B1FA2,color:#000

关键知识点回顾：

1. 空间音频的核心是 HRTF——它模拟了声音经过头部和耳廓后的频谱变化，是实现 3D 定位的关键
2. 头部追踪让空间音频"活"起来——转头时声源位置相对房间不变，这才是真正的沉浸感
3. 必须先检测设备能力再启用——不是所有设备都支持空间音频，降级方案不可少
4. 空间音频仅适用于耳机——扬声器播放空间音频效果差甚至异常
5. HarmonyOS 6 提供了应用级空间音频渲染器——可以精确控制声源位置、HRTF 参数和房间声学

空间音频是音频技术的未来方向。从"听得到"到"听得出方向"，再到"听出身临其境"，每一步都是体验的飞跃。掌握空间音频，就是掌握了下一代音频交互的钥匙。