HarmonyOS 7 空间音频展陈声源方位与场景切换治理【共创稿事节】

在文博展陈应用中，音频不仅承担讲解功能，还直接影响观众对展品位置的感知。传统的顺序播报将声音与展柜解耦，观众从青铜器展区走向瓷器展区时，界面已经切换展品，听到的却仍是上一段讲解。另一类问题是方位参数更新得太频繁，触摸地图、调整视角和切换展区同时改变音频状态，结果出现内容跳跃、重复启动与位置提示不同步。

这类场景需要把“声源在哪里”“现在讲什么”“通过什么音频链路播放”分成三个职责。HarmonyOS 的 Audio Kit 提供音频管理与空间音频相关能力，应用则负责展品元数据、声源相对位置、会话顺序、失效请求过滤和界面反馈。只有先划清这条数据链，后续接入具体音频引擎时才能保持业务状态稳定。

图1 展陈区域与声源方位管理关系

从展品位置建立可维护的数据契约

假设展厅有青铜鼎、青花瓷瓶和古地图三个声源，应用需要记录相对展厅参照轴的方位角、仰角和距离，以及对应的讲解资源。方位角统一采用角度制，正前方为零，向右为正、向左为负；距离统一为米。这些约束应放在模型层，不应分散在 UI 中。保存到本地的角度和空间渲染引擎使用的坐标可能不是同一种约定，因而必须通过适配层转换。

export interface ExhibitSource {
  id: string
  title: string
  audioUri: string
  azimuthDeg: number
  elevationDeg: number
  distanceMeters: number
  revision: number
}

export interface ListenerPose {
  headingDeg: number
  zoneId: string
  updatedAt: number
}

export interface SourceSnapshot {
  id: string
  relativeAzimuthDeg: number
  elevationDeg: number
  distanceMeters: number
  revision: number
}

export const EXHIBITS: ExhibitSource[] = [
  { id: 'bronze', title: '青铜鼎', audioUri: 'resources/rawfile/bronze.wav',
    azimuthDeg: -60, elevationDeg: 0, distanceMeters: 2.5, revision: 1 },
  { id: 'porcelain', title: '青花瓷瓶', audioUri: 'resources/rawfile/porcelain.wav',
    azimuthDeg: 0, elevationDeg: 0, distanceMeters: 3.0, revision: 1 },
  { id: 'map', title: '古地图', audioUri: 'resources/rawfile/map.wav',
    azimuthDeg: 60, elevationDeg: 0, distanceMeters: 2.0, revision: 1 }
]

这里的 audioUri 是内容资源的业务引用，实际交给播放器前需解析为可访问的资源句柄。声源 ID 用来关联选中态，revision 用来判断场景切换后是否仍是同一版讲解。不要把动态取得的头部朝向直接写回展品元数据：展品的固有位置不会因为观众转身而改变。倾斜角、展品距离及朝向必须遵循一套坐标基准，后续维护者才能理解每个字段代表的物理含义。

把“绝对方位”转换为“听众相对方位”

展品元数据记录的是展厅中的位置，用户耳边听到的则应随朝向改变。计算时，将展品方位减去听众朝向，再把结果规范化到 -180° 至 180°。该方法可避免转过 360° 时出现视觉指示突然跳变；它只是应用层的参数计算，不等同于直接控制系统音频空间化效果。

export class SourceProjector {
  static wrapAngle(degrees: number): number {
    let result: number = degrees % 360
    if (result > 180) {
      result -= 360
    }
    if (result < -180) {
      result += 360
    }
    return result
  }

  static project(source: ExhibitSource, pose: ListenerPose): SourceSnapshot {
    let safeDistance: number = Math.max(0.2, Math.min(20, source.distanceMeters))
    return {
      id: source.id,
      relativeAzimuthDeg: SourceProjector.wrapAngle(
        source.azimuthDeg - pose.headingDeg),
      elevationDeg: Math.max(-90, Math.min(90, source.elevationDeg)),
      distanceMeters: safeDistance,
      revision: source.revision
    }
  }
}

为避免在触摸拖动时每一帧都重新分配音频对象，可将高频姿态输入交由轻量计算模块更新，页面仅在角度跨过设定阈值、声源发生变化或者固定采样周期到达时刷新文本。这里的阈值属于产品策略：例如方位变化不足两度时维持当前文案，能减少提示闪烁；它并不是系统规定的空间音频精度。距离设置也应该进行边界控制，防止错误配置产生极端值。

保持场景切换的单向数据流

“全域讲解”“单展品聚焦”“静音区域”可以作为业务模式，但不应在各按钮中分别开启和停止播放器。更好的结构是由场景控制器生成唯一的当前会话标识，所有异步资源准备都检查标识是否过期。一次模式切换会影响声源选择、音频资源、字幕和当前展区标签，但只有控制器能够发布最终的有效场景。

export type ExhibitMode = 'all' | 'focus' | 'quiet'

export interface ExhibitScene {
  mode: ExhibitMode
  activeSourceId: string
  requestSeq: number
}

export class SceneCoordinator {
  private current: ExhibitScene = {
    mode: 'all', activeSourceId: 'porcelain', requestSeq: 0
  }

  switchTo(mode: ExhibitMode, sourceId: string): ExhibitScene {
    const nextSeq: number = this.current.requestSeq + 1
    this.current = { mode: mode, activeSourceId: sourceId, requestSeq: nextSeq }
    return this.current
  }

  isCurrent(sequence: number): boolean {
    return sequence === this.current.requestSeq
  }

  snapshot(): ExhibitScene {
    return {
      mode: this.current.mode,
      activeSourceId: this.current.activeSourceId,
      requestSeq: this.current.requestSeq
    }
  }
}

如果资源加载较慢，用户先选青铜鼎又立即切到瓷瓶，青铜鼎请求可能后完成。处理方式是在资源准备结束时比较 requestSeq；不一致时只释放旧资源，不修改正在展示的页面。这样能避免旧音频覆盖新选中的展品。对于暂停状态、耳机切换和音频焦点变化，界面应显示“准备中”“播放中”“已暂停”等明确状态，而不是单纯依据按钮按下与否推测播放成功。

图2 声源模型、场景控制与播放状态的开发视图

与 Audio Kit 的连接点

在系统层，Audio Kit 提供音频管理与空间音频管理器。audio.getAudioManager() 和 AudioManager.getSpatializationManager() 的使用入口可以在官方 API 参考中核对，后者要求相应系统能力与设备版本支持。取得管理器只是系统能力接入的起点，是否具有空间化输出以及如何选择渲染路径，还与设备路由、音频内容和产品能力有关。业务控制器不要把上述两种状态混为一谈。

import { audio } from '@kit.AudioKit'

export class SpatialCapabilityAccess {
  private audioManager: audio.AudioManager = audio.getAudioManager()

  getManager(): audio.AudioSpatializationManager {
    return this.audioManager.getSpatializationManager()
  }
}

对展陈产品而言，声源元数据服务不必依赖具体渲染器。它只输出相对方位、距离和资源身份。音频处理模块可以根据已确认的设备能力选择对应音频路径，字幕与展品卡片仍然使用相同的 ExhibitScene。这种隔离还便于定位问题：方位显示错误优先检查坐标约定，音频内容错位优先检查资源与会话 ID，播放中断优先检查音频路由和生命周期。

让界面成为状态的观察者

展品控制页采用简洁的 @State 字段表达当前展品与模式。切换完成后，先修改业务会话再刷新页面；真正的播放结果由音频模块回传。这样可避免点击按钮立即显示“已播放”，而音频资源仍在准备阶段。宽屏可将地图与列表分栏，手机端优先展示当前展品、方向与播放入口。对于听力不便的观众，字幕和方向文本要保持同步可读。

@Entry
@Component
struct ExhibitionPage {
  @State selectedId: string = 'porcelain'
  @State mode: string = 'all'
  private coordinator: SceneCoordinator = new SceneCoordinator()

  build() {
    Column({ space: 16 }) {
      Text('展陈空间音频').fontSize(28).fontWeight(FontWeight.Bold)
      Text(`当前展品：${this.selectedId}`)
      Row({ space: 12 }) {
        Button('全域讲解').onClick(() => { this.changeMode('all') })
        Button('单展品聚焦').onClick(() => { this.changeMode('focus') })
        Button('静音区域').onClick(() => { this.changeMode('quiet') })
      }
      ForEach(EXHIBITS, (item: ExhibitSource) => {
        Row() {
          Text(item.title).layoutWeight(1)
          Button('选择').onClick(() => { this.selectSource(item.id) })
        }.width('100%')
      }, (item: ExhibitSource) => item.id)
      Text(`当前模式：${this.mode}`)
    }.padding(20).width('100%')
  }

  private changeMode(nextMode: ExhibitMode): void {
    this.coordinator.switchTo(nextMode, this.selectedId)
    this.mode = nextMode
  }

  private selectSource(id: string): void {
    this.coordinator.switchTo(this.mode as ExhibitMode, id)
    this.selectedId = id
  }
}

图3 展品定位与讲解模式的移动端运行效果

排查应先看哪一层

建议按“数据—会话—播放—呈现”的顺序排查。数据层检查方位角是否同基准、距离是否越界、资源身份是否一致；会话层检查切换请求序列号以及新旧资源是否串线；播放层确认音频路由、资源准备、暂停恢复和空间化支持状态；呈现层再核对字幕、雷达图和展品选择标识。每层日志记录必要的事件和序列号即可，不要记录可识别访客的原始轨迹。

性能方面，应区分高频朝向变化与低频业务场景切换。朝向改变通常不需要重建整个页面；切换展品才需要替换资源并更新讲解信息。快速来回切换、耳机断开、应用返回前台和资源读取失败是重要的边界用例，分别检查旧请求丢弃、播放状态回执、选中态恢复与错误提示。对于需要严格声像定位的项目，还应在目标音频输出设备上校准音量、距离衰减与听感，而不能仅依据坐标图作判断。

HarmonyOS 的空间音频能力为展陈产品提供了新的声音组织方式，但应用质量取决于声源数据能否独立、场景切换能否有序、状态反馈能否准确。把相对方位计算放在可维护的业务模型中，再以已核对的 Audio Kit 接口连接设备音频链路，后续无论增加展区、替换讲解内容还是扩展多终端展示，都能沿用同一套治理原则。

相关开发文档：HarmonyOS 空间计算与空间音频、AudioManager API 参考、HarmonyOS 开发文档中心。