# 〖共创稿事节〗HarmonyOS 7 新特性实战（43）：声音放到左边，左耳就真的更响——OHAudioSuite 空间渲染最小管线

山海的异兽讲解是朗读出来的，出口永远是手机扬声器：单声道，没方向。可地图明明是三维的，昆仑的兽在左上角，东海的兽在右下角，讲解声却从同一个点出来。OHAudioSuite 是这轮新特性里专门干这个的——引擎、管线、节点三层结构，空间渲染节点吃一组 x/y/z 坐标，把普通音频渲染出方位感。

这篇只做一件事：把最小管线立起来，并且让"位置参数生效"变成一张可以复现的对照表。不接 TTS，不碰扬声器，不靠耳朵判断——程序生成的正弦波喂进去，渲染结果落成数据，喂进去的左右一样、出来不一样，差异的唯一来源就是空间渲染节点。

官方 API 参考：OHAudioSuite（C API）（核对日期 2026-10-28）

一、管线是反向驱动的

先把结构摆出来。AudioKit 的音频编创框架分三层：引擎（OH_AudioSuiteEngine）管生命周期，管线（Pipeline）是一次处理任务，节点（Node）串在管线上干活。最小管线三个节点：输入节点要料，效果节点加工，输出节点交货。

输入节点(校准正弦) → 空间渲染节点(x/y/z) → 输出节点
      ↑ 要料回调                |
      └────── RenderFrame 反向驱动 ──┘

跟预想不一样的地方在数据流向：不是"推"是"拉"。应用调 OH_AudioSuiteEngine_RenderFrame 从输出端拉处理完的数据，管线自己回头向输入节点登记的 RequestDataCallback 要料，要完加工，再填回应用的缓冲区。料给完的那次回调里置 finished，管线处理完最后一批后通过 RenderFrame 的出参 finishedFlag 告知。整个循环是应用驱动的，没有藏在系统里的播放线程——这一点决定了它既能接扬声器，也能像我这样接一个 WAV 文件。

二、项目里第一次有 C++

这个工程从头到尾是 ArkTS，cpp 目录都不存在。OHAudioSuite 是纯 C API，得先补一个 native 模块。骨架三件事：native 侧的 CMakeLists 链上 libohaudiosuite.so；模块构建配置加 externalNativeOptions 指向 CMakeLists；包配置里把 so 映射到一份 .d.ts 声明上，ArkTS 才能 import。

// 模块构建配置（节选）
"buildOption": {
  "externalNativeOptions": {
    "path": "src/main/cpp/CMakeLists.txt",
    "abiFilters": ["arm64-v8a"]
  }
}

# CMakeLists.txt（节选）：漏链 napi 库会在链接期报一堆 undefined symbol
target_link_libraries(shanhaiaudio PUBLIC libohaudiosuite.so libace_napi.z.so ${hilog-lib})

第一批编译错误全是签名对不上类型的细节：OH_Audio_SampleRate 不是 uint32_t 而是一个枚举，得用 SAMPLE_RATE_48000 这个枚举值；位置结构体的字段是 float，double 直接塞进初始化列表会被 narrowing 检查拦下。这类错误报错信息都很直白，改就行，列出来是给同样第一次建 native 模块的人省几分钟。

三、校准音的设计：喂进去的左右必须一样

要证明"位置参数生效"，先得排除其它可能。办法是把输入做成左右声道完全相同的 440Hz 正弦：如果渲染输出左右不一样，来源只剩空间渲染节点一个。

// 输入节点的要料回调：左右声道喂同一个样本，差异只能来自管线
int32_t OnRequestData(OH_AudioNode*, void* userData, void* audioData,
                      int32_t audioDataSize, bool* finished) {
    auto* state = static_cast<FeedState*>(userData);
    auto* out = static_cast<int16_t*>(audioData);
    const int32_t maxFrames = audioDataSize / (kChannels * sizeof(int16_t));
    int32_t written = 0;
    for (int32_t f = 0; f < maxFrames && state->framesFed < kTotalFrames; f++) {
        const double s = kAmp * sin(2.0 * kPi * kToneHz *
                                    state->framesFed / kSampleRate);
        const auto v = static_cast<int16_t>(s * 32767.0);
        out[written * kChannels] = v;
        out[written * kChannels + 1] = v;
        written++; state->framesFed++;
    }
    if (state->framesFed >= kTotalFrames) { *finished = true; }
    return written * kChannels * sizeof(int16_t);
}

空间渲染节点吃 OH_AudioSuite_SpaceRenderPositionParams，三个轴各 [-5.0, 5.0] 米。三组位置：x=-3（左）、x=0（中）、x=+3（右），y/z 都是 0，其余条件全同。

四、三次渲染，一张表

真机（HBN-AL80，API 26）上跑：先 IsNodeTypeSupported(EFFECT_NODE_TYPE_SPACE_RENDER) 探测——返回支持；然后三组位置各走一遍完整管线。渲染出来的 PCM 在设备端当场算左右声道 RMS（真机沙箱的文件拉不出来，第八节说这事）：

声源位置	左声道 RMS	右声道 RMS	关系
x=-3.00（左）	10864	6644	左比右响约 63%
x=0.00（中）	17753	18454	差 4%，基本居中
x=+3.00（右）	6586	10061	右比左响约 53%

同一份正弦，三组位置，能量分布跟着声源翻转——这就是空间渲染节点在干活。引擎日志也能对上：建节点时打 Create node type = 208（208 就是空间渲染的枚举值），设位置时打 SpaceRender set Position x:-3.000000。

RMS 的算法一行核心都没有，纯粹是算术：交错存储的 S16LE 里按奇偶拆开，各自平方求均再开方。真正费劲的是决定"在哪算"——见第八节。

五、PrintInfo：API 26 的运行时快照

管线跑起来之后，新接口 OH_AudioSuite_PrintInfo（API 26 起）能把当前管线拓扑打进日志：

I C02B8C/.../AudioSuiteEngine: Pipeline [ID: 1]
I C02B8C/.../AudioSuitePipeline: [CreateNodeForType]Create AudioInputNode
I C02B8C/.../AudioSuitePipeline: [CreateNodeForType]Create node type = 208
I C02B8C/.../AudioSuiteSpaceRenderAlgoInterf: [SetPositionParameter]SpaceRender set Position x :-3.000000

实测发现一个小脾气：空间渲染节点停在"位置模式"时，PrintInfo 内部去取旋转参数会打一条 E 级日志 [GetParameter]Space render mode is not support，接口本身返回 SUCCESS，快照内容也正常。排查的时候别被这条吓到——它不是你的调用错了，是快照函数对非旋转模式的节点取参失败被原样记了下来。

六、失败路径也要拆干净

管线的销毁有讲究：运行状态下节点不让删（返回 INVALID_STATE），必须先 StopPipeline。所以清理顺序固定：停管线 → 删节点 → 删 builder → 删管线 → 删引擎。我把它写成一个独立段放在主流程之外，任何一步失败都会落到这里：

// 放在主流程之外：任何一步失败 break 到这里，同样先停再拆
OH_AudioSuite_Result s1 = OH_AudioSuiteEngine_StopPipeline(pipeline);
OH_AudioSuite_Result d1 = OH_AudioSuiteEngine_DestroyNode(inputNode);
// ...builder → pipeline → engine，每步返回码落日志

这里踩过一个自己挖的坑：最初失败分支直接 return，在建完引擎之后才失败的调用会把引擎扔在进程里。写"资源回收"主题的代码，失败路径不回收，等于自己打自己的脸。改法是失败只记下第一个出错环节（step=错误码），统一走到清理段。真机上跑三组位置，每组销毁链六步全部 SUCCESS。

七、真机沙箱的文件拿不出来

最初的设计是渲染完写成 WAV，hdc file recv 拉回本地用 Python 分析。真机上卡住了：应用沙箱目录对 file recv 返回 permission denied，模拟器上没这问题（模拟器有更高权限）。

绕开的办法是把分析搬到设备端：RMS 本来就是十行算术，渲染完在 C++ 里直接算完打进日志，根本不用传文件。hilog 里一行 channel rms: x=-3.00 rmsL=10864.0 rmsR=6643.9 就是一组完整证据。事后看这是更好的设计——对照表和产生它的管线在同一个进程里，中间没有传输环节。

顺带记一个 ArkTS 侧的小坑：hilog 的格式串里 %{public}f 传 number 打出来是 x=}f，不展开。换成 %d/%s 或者干脆字符串拼接，绕过即可。

八、这条管线接下来接什么

目前只是立骨架，按证据清单还差几步，都不复杂：

待接项	说明
TTS 接入	讲解音频不再是程序生成的正弦，改喂 TTS 输出的 PCM
旋转/扩展模式	空间渲染另有旋转（SpaceRenderRotationParams）与扩展参数，地理漫游时可用
实时模式播放	REALTIME_MODE 管线直接出声，接到 OHAudio 播放器上就是完整的听感链路
地图联动	把 3D 地块的世界坐标映射进 [-5, 5] 米声场，点谁谁出声

骨架立住之后这些都只是往 input 和 space 两个点上接东西，管线结构不用动。

九、验了什么，怎么复现

复现三步：开 SHANHAI_AUDIO_SUITE_SELFTEST 开关构建，真机冷启，等 8 秒。应用自己跑完三组渲染，hilog 按 ShanhaiAudioSuite 过滤，channel rms 三行就是对照表；destroy chain 六步 SUCCESS 是释放证据；support: space_render=1 是能力探测。配套的门禁脚本钉住管线契约（引擎→管线→节点→渲染→先停后拆的顺序），删掉任何一步门禁就红。

这套东西最终要服务的是地图上的方位感：异兽在哪个方向，讲解就从哪个方向来。现在管线能证明"坐标进、方位出"，剩下的只是把坐标喂对。