戴上耳机播放一段环境音乐，用户期待的不再只是左声道和右声道音量不同，而是声音仿佛具有相对位置：远处的钟声与近处的脚步不互相遮挡，人物转身时方位线索仍然清楚。HarmonyOS 的空间音频方向为影音、游戏和沉浸式交互提供了更丰富的音频体验，但应用工程面对的第一道题不是“如何画一个三维声场按钮”，而是如何选择合适的音频路径并维持播放连续性。

这里选择“沉浸式声音游览”作为具体业务：页面提供城市场景、森林场景和室内展厅三种内容，每种内容有不同的声音布局。应用负责展示场景、管理播放状态、保存用户偏好和处理设备变化；底层播放、声场渲染和设备支持则由相应音频组件与能力条件决定。把这两部分分清楚，能有效避免把业务中的“空间化开关”误当成系统层的控制权限。

空间音频首先是一条媒体链路

音乐文件、音频流、音效素材进入播放链路后，需要经历内容解码、声道组织、输出设备选择、声场渲染以及最终声音输出等阶段。音源只有双声道并不自动意味着能呈现完整的三维方位；相反，内容格式、设备支持与实际渲染链路之间需要有明确约定。应用至少应区分“当前内容支持空间化处理”“输出设备满足条件”“用户希望启用该效果”这三个判断。

一个常见的问题是应用把“空间模式”放在 @State 中，用户每次点击都会把这个值置为 true，随后就展示“空间音频已启用”。如果底层没有相应能力或者输出设备发生切换，界面仍然显示开启，就会形成认知偏差。这里更推荐用“请求的模式”和“当前可采用的模式”两个字段，后者随输出能力变化重新计算。

确认系统音频模块和业务配置的分工

HarmonyOS Audio Kit 提供 AudioManager，并在相应 API 版本中提供 getSpatializationManager() 用于取得空间音频管理器。它与应用自行计算的声音坐标不是同一层概念。部分涉及改变系统空间音频设置、头部追踪策略的接口具有系统应用或特殊权限要求，普通应用不能把这些操作当成通用 UI 开关。实际项目应先查阅对应 API 版本与设备适用范围，再选择允许调用的接口。

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

export class AudioManagers {
  private readonly manager: audio.AudioManager = audio.getAudioManager();

  getRoutingManager(): audio.AudioRoutingManager {
    return this.manager.getRoutingManager();
  }

  getSpatialManager(): audio.AudioSpatializationManager | undefined {
    if (!canIUse('SystemCapability.Multimedia.Audio.Spatialization')) {
      return undefined;
    }
    return this.manager.getSpatializationManager();
  }
}

这个入口只取得管理对象，并没有擅自改变系统空间化状态。业务层还需要结合目标系统版本、输出设备类型和相应接口的访问要求判断后续路径。getSpatializationManager() 的存在说明应用可以在具备对应系统能力的条件下取得管理对象，但各项空间音频控制接口的访问条件仍需单独核对。实际输出仍应以可用媒体能力与音源条件为准。

把模式决策写成可复用的纯函数

音频体验容易被界面交互打断。用户从森林场景切换到展厅时，如果播放组件正在重新建立音频流，空间模式选择不应该在多个页面之间各算一遍。将决策放到业务层，有利于用同一份规则驱动页面提示、播放队列和设备变化后的恢复。

export type SoundMode = 'spatial' | 'stereo';

export interface SoundDecisionInput {
  userRequestedSpatial: boolean;
  contentSupportsSpatial: boolean;
  outputSupportsSpatial: boolean;
  routeAvailable: boolean;
}

export interface SoundDecision {
  mode: SoundMode;
  reason: string;
}

export function decideSoundMode(input: SoundDecisionInput): SoundDecision {
  if (!input.routeAvailable) {
    return { mode: 'stereo', reason: '等待可用输出设备' };
  }
  if (!input.userRequestedSpatial) {
    return { mode: 'stereo', reason: '使用标准声道播放' };
  }
  if (!input.contentSupportsSpatial) {
    return { mode: 'stereo', reason: '当前内容采用立体声路径' };
  }
  if (!input.outputSupportsSpatial) {
    return { mode: 'stereo', reason: '当前输出设备采用立体声路径' };
  }
  return { mode: 'spatial', reason: '内容与输出路径满足空间模式条件' };
}

这里的 outputSupportsSpatial 来自应用的输出适配层，而不是凭“设备名称含有耳机”直接推断。纯函数只负责模式选择，并不负责实际音频编码或 DSP 渲染。项目若接入不同版本的播放引擎，也可以把上述结构保留下来，替换真正执行渲染的适配器。

用独立的场景模型统一入口

对于声音游览，场景切换至少要约定三件事：切到哪个内容、是否沿用当前播放位置、效果是否需要重新评估。以下模型将内容资料与用户界面拆开，让播放器只接收结构化的播放请求。这样的结构也方便以后增加视频、朗读、环境提示音而不复制一套页面状态。

export interface SoundScene {
  id: string;
  title: string;
  sourceUri: string;
  spatialAsset: boolean;
  coverColor: string;
}

export const soundScenes: SoundScene[] = [
  { id: 'forest', title: '林间清晨', sourceUri: 'rawfile://forest.wav',
    spatialAsset: true, coverColor: '#277F91' },
  { id: 'gallery', title: '展厅漫步', sourceUri: 'rawfile://gallery.wav',
    spatialAsset: true, coverColor: '#675DBB' },
  { id: 'city', title: '城市夜色', sourceUri: 'rawfile://city.wav',
    spatialAsset: false, coverColor: '#3C5D9B' }
];

export class SceneSession {
  private currentScene: string = 'forest';
  private playbackPositionMs: number = 0;

  select(sceneId: string): void {
    this.currentScene = sceneId;
    this.playbackPositionMs = 0;
  }

  savePosition(positionMs: number): void {
    this.playbackPositionMs = Math.max(0, positionMs);
  }

  snapshot(): string {
    return `${this.currentScene}:${this.playbackPositionMs}`;
  }
}

rawfile:// 是示例项目内部约定的业务 URI，播放器适配层需要将它转换成具体资源访问方式；这个模型不承担文件打开工作。页面只显示场景与当前模式，真正的媒体流管理和设备变化处理放到独立服务，避免同一次按钮点击重复启动多个音频实例。

播放链路需要哪些恢复点

音频播放不是一次性动作。进入后台以后，音频会话可能受到其他应用打断；蓝牙耳机断开以后，输出路径也会改变。业务上至少要区分“用户主动暂停”“系统音频打断”“输出路径改变”“当前音源读取失败”四类事件。主动暂停应保持用户选择的状态；临时打断是否自动恢复应遵循系统音频焦点处理规则；输出设备变化则需要重新评估音频模式，必要时回退到常规立体声。

建议在播放控制层保存当前场景 ID、播放位置、用户期望的播放状态和实际播放状态。恢复时先检查当前资源是否仍可访问，再检查输出路径，然后依照最新条件重新选择声场模式。若恢复失败，页面应提示具体原因和可执行的操作，例如“输出设备已变化，请重新选择”。不应笼统地显示“空间音频发生错误”。

让“空间效果”不只是一句形容词

产品验收时可围绕感知方向建立有操作性的检查点。比如切换场景时左右声道是否出现明显跳变，用户按下暂停后界面是否还保留播放动画，耳机断开以后是否出现仍显示空间模式但实际无可用输出的冲突，以及用户把空间偏好关闭后是否仍能正常播放标准音轨。这些检查不需要预设一组漂亮的性能数字，而是关注业务状态和听觉体验之间是否一致。

空间音频的价值并不只在声场渲染算法。对应用开发者来说，容易忽略的部分是内容、设备、系统设置和页面状态之间的关系。把这四个维度分别建模，就能让沉浸式声音游览既有清晰的交互，也有可维护的播放链路。后续增加游戏中的方位提示、音视频混合场景或多端流转时，这套场景和模式决策模型仍然可以沿用。

相关文档

• HarmonyOS 空间计算能力：空间音频
• AudioManager API 与空间音频管理器
• HarmonyOS Audio Kit 文档入口