前言

空间音频这条能力，放到应用里最直接的价值有三点。视频播放更有包围感，会议里更容易分辨发言方向，游戏中的声源定位也会更清楚。

鸿蒙 6 已经把这条链路接进系统音频栈，关键能力落在两个层面，一层是空间音频状态管理，另一层是 Audio Vivid 的编解码与渲染播放。把这两层接顺，空间音频就能从一个卖点，变成真正能交付的产品能力。

一、先把空间音频能力和状态收口

项目接空间音频，第一步先做能力判断和状态管理。应用侧真正需要的状态并不多，当前设备空间音频开关有没有打开，输出设备是否支持空间音频渲染，系统状态变化后页面和播放器要不要同步刷新。鸿蒙把这部分能力放进了 AudioSpatializationManager，入口从 AudioManager.getSpatializationManager() 取。设备侧能力则挂在 AudioDeviceDescriptor 上，通过 spatializationSupported 可以判断当前设备是否支持空间音频渲染。

空间音频的开关状态可以直接查，也可以订阅变化事件。这样做的意义很明确，设置页、详情页、播放器页都从同一份状态取值，后面就不会各自维护一套。工程里更稳的做法，是把这层能力单独封成 store 或 service，让页面只关心显示，播放器只关心播放链路。

import { audio } from '@kit.AudioKit'

type SpatialAudioState = {
  enabled: boolean
  updatedAt: number
}

class SpatialAudioStore {
  private manager = audio.getAudioManager().getSpatializationManager()
  private state: SpatialAudioState = {
    enabled: false,
    updatedAt: 0
  }

  init() {
    this.state = this.readNow()

    this.manager.on(
      'spatializationEnabledChangeForCurrentDevice',
      (enabled: boolean) => {
        this.state = {
          enabled,
          updatedAt: Date.now()
        }
      }
    )
  }

  readNow(): SpatialAudioState {
    return {
      enabled: this.manager.isSpatializationEnabledForCurrentDevice(),
      updatedAt: Date.now()
    }
  }

  getState(): SpatialAudioState {
    return this.state
  }
}

这段代码的重点很简单，空间音频状态单独收口，页面和播放器共享同一份结果。后面如果再补设备切换、蓝牙输出变化、耳机能力判断，入口也已经固定了。

二、Audio Vivid 的播放链路

空间音频播放链路里最容易写偏的地方，是只把 PCM 数据丢进播放器，元数据没有一起跟进去。声音能正常出来，空间信息却丢了，最后听起来还是普通播放。Audio Vivid 这条链路需要先完成解封装和解码，再把 PCM 数据和元数据一起交给 OHAudio 做渲染。音频流构造器阶段要设置 OH_AudioStreamBuilder_SetWriteDataWithMetadataCallback()，这一步就是整条链路的关键。

播放器这边不需要自己造一套额外的渲染框架，重点是把音源规格和解码输出对齐。采样率、声道数、声道布局都要跟解码后的结果一致，别为了图省事写死。Audio Vivid 已经作为编码类型进入音频流枚举，播放链路只要把数据喂对，后面的渲染才有基础。

#include <multimedia/player_framework/native_audiostreambuilder.h>
#include <multimedia/player_framework/native_audiorenderer.h>

static int32_t OnWriteDataWithMetadata(
    OH_AudioRenderer *renderer,
    void *userData,
    void *audioData,
    int32_t audioDataSize,
    void *metadata,
    int32_t metadataSize)
{
    // 这里写入解码后的 PCM 数据
    // 这里写入与 PCM 对应的 Audio Vivid 元数据
    return 0;
}

void StartAudioVividPlayback()
{
    OH_AudioStreamBuilder *builder = NULL;
    OH_AudioRenderer *renderer = NULL;

    OH_AudioStreamBuilder_Create(&builder, AUDIOSTREAM_TYPE_RENDERER);

    // 采样率、声道数、声道布局等参数
    // 需要和解码输出保持一致

    OH_AudioStreamBuilder_SetWriteDataWithMetadataCallback(
        builder,
        OnWriteDataWithMetadata,
        NULL
    );

    OH_AudioStreamBuilder_GenerateRenderer(builder, &renderer);
    OH_AudioRenderer_Start(renderer);

    // 播放结束后释放资源
    OH_AudioRenderer_Stop(renderer);
    OH_AudioRenderer_Release(renderer);
    OH_AudioStreamBuilder_Destroy(builder);
}

这段代码保留了最小可用的骨架。构造器阶段接入元数据回调，渲染器阶段启动播放，结束后及时释放实例和 builder。这样接下来，空间音频渲染链才能跑完整。

三、设备能力、系统状态和播放器状态要放进同一套流程

空间音频一旦进到真实项目，很快就会出现三个状态同时存在。设备支持不支持，系统开关开没开，播放器链路有没有真的走 Audio Vivid。三层状态只要有一层没接上，功能就会显得断裂。设备支持，开关没开，用户听不到空间效果。开关开着，输出设备不支持，页面却还在显示空间音频入口。播放器链路接好了，页面没同步状态，用户又会觉得功能不生效。

工程里更正规的做法，是把流程固定下来。进入播放器前先查输出设备能力，再读当前设备空间音频状态，最后再决定播放器走普通播放还是 Audio Vivid 链路。设备一旦切换，重新读能力和状态，再同步刷新页面。这样处理之后，设置页、播放页和设备切换逻辑就能串起来。项目越大，这种统一流程越重要。

一个很实际的建议，是把空间音频入口和播放链路彻底解耦。页面层只负责展示当前能力和状态，播放器层只负责根据状态选择播放链路。这样做后面最好维护，调试也更轻。状态不对，就查 store。播放不对，就查 Audio Vivid 数据链。问题会快很多收敛。

四、调试和优化先盯住资源格式、设备矩阵和链路完整性

空间音频接到最后，最常见的问题通常不在接口名字，而在资源和链路。音源格式、解封装结果、解码输出、PCM 数据、元数据回调，只要其中一环不对，播放效果就会打折。很多时候播放器能播，声音也正常，问题就藏在元数据没有真正跟进渲染链，或者当前输出设备根本不支持空间音频。

开发阶段更适合先固定两件事。第一，播放器资源规格尽量统一，同一类内容不要混着走普通立体声和 Audio Vivid，又要求用户听到同样的空间效果。第二，测试设备要覆盖不同输出链路。空间音频这类能力高度依赖输出设备和系统状态，只在一台开发机上测通，后面一定会出兼容性问题。

排查顺序也要固定。先确认输出设备是否支持空间音频，再确认当前设备开关是否开启，然后确认音源有没有完整走进 Audio Vivid 的解封装、解码和元数据回调链路，最后再看播放器页面状态是否跟着更新。这样排下来，问题定位会比从 UI 或播放器单点往回猜轻很多。

总结

鸿蒙 6 这条空间音频能力线，工程路径已经比较清楚了。状态管理走 AudioSpatializationManager，输出设备能力看 AudioDeviceDescriptor.spatializationSupported，播放链路走 Audio Vivid 解码加 OHAudio 元数据回调。把这三部分接顺，空间音频功能就有了稳定落地的基础。

项目里更值得先做的事情也很明确。先把能力查询和状态订阅收成统一状态源，再把 Audio Vivid 播放链路按正确方式接起来，最后把设备能力、播放状态和页面状态统一管理。这样写出来的空间音频功能，后面才更容易维护、调试和扩展。