HarmonyOS 7 新特性14：音频编创深潜——12节点格式契约、7链时延表与EQ不设参引发的系统库崩溃

1、引言

篇 2（《HarmonyOS 7 新特性2：音频编创》）我在轻音台里把降噪、环绕、格式转换三个单点效果各跑通了一遍。那时每个效果都是一条写死的三节点链：输入→效果→输出。这篇要回答的是下一步的问题——节点串起来之后，数据在节点之间怎么流、格式怎么变、什么样的接法是合法的。

动笔前我以为这篇的主角会是那张 12 种效果节点固定输出格式表。降噪节点（EFFECT_NODE_TYPE_NOISE_REDUCTION）出来固定是 16000Hz / S16LE / 单声道，声场、美化、环境效果全是 48000Hz / S16LE / 2ch，音源分离是 48000Hz / F32LE / 4ch——这张表藏在头文件的枚举注释里，配错下游就是「参数都对但声音不对」。结果真机实测第一天，主角换了：

我在加工台上连点两条预设链，第一条单节点降噪正常出结果，第二条 EQ+降噪点下去 19 秒后整个进程没了。hilog 里没有任何应用层错误，崩溃栈指向系统库 libaudio_suite.z.so 的音频处理线程：AudioSuiteProcessNode::ObtainProcessedData 读了一个 NULL+0x40 的地址，SIGSEGV，应用层不可捕获——它不走错误码，不走异常，直接带走进程。

排查全程写在第 6 节。结论先放这里：崩溃与「级联」「链长」都没有关系，真正的变量只有一个——创建均衡器节点后没有调用 SetEqualizerFrequencyBandGains。修复前 5 次崩溃全部含均衡器节点、4 次成功全部不含它；给均衡器补上默认增益参数后，7 条链 9 遍全部跑通。官方离线编辑示例里创建 EQ 后紧跟一句设置增益，我当时把这当成了「调音演示所以才有」，实际它是节点内部缓冲的初始化义务。

这篇在 Mate 60 Pro 上做了四件事，先给数据：

• 7 条链同数据集端到端时延表：含降噪的链 4601/4714/5091ms，不含降噪的链 672/1676/1749/2007ms——降噪节点独占约 3 秒成本，链长 2→4 级只增加约 330ms；
• 格式契约反证法验证：SDK 没有逐节点读格式的接口，用「按官方格式配输出节点、渲染成功且输出字节数自洽」证明契约表；意外收获是一个负结果——把降噪链的输出节点强行配成 48k/2ch，系统静默容忍，不报任何错；
• 音源分离首测成功：麒麟 9000S 上 204 节点探测支持且真跑通，双路输出人声轨 -20.1dBFS / 伴奏轨 -26.7dBFS，耗时 14659ms（全篇最重节点）；
• 空间渲染三模式取值域 6/6 如期：position/rotation/extension 的越界参数全部被 INVALID_PARAM 硬拒——参数域是硬要求，格式域是软约束，两类契约强度完全不同。

版本说法先确认（篇 2 立过的规矩）：OHAudioSuite 底座是 API 22 的能力，201–207 七个节点自 API 22，空间渲染 208 与变声族 209–211 自 API 23，HOA 空间渲染 212 才是 26.0.0 新增。这篇是深潜，不是新特性发布。

2、效果展示与项目结构

2.1 真机效果

加工台顶部的节点能力探测，14 类节点（输入/输出/12 效果）在麒麟 9000S 上全部支持，绿色 chip 是 IsNodeTypeSupported=true 且 queryError=0：

七条预设链跑完后的结果区（截图里能看到 6 条）：每条链输出格式、耗时、前后 RMS、输出字节数。注意 [2级·EQ→降噪⚠X1] 输出的 951KB（16k/1ch 契约）和其余 48k/2ch 链的 5708KB——字节数就是反证法的证据本体：

音源分离双路结果（人声轨与伴奏轨各自 RMS）：

多路混音（两路输入→混音节点→单输出）：

空间渲染三模式契约验证——合法值 ✓接受、越界值 ✗INVALID_PARAM，六条全如期：

2.2 工程结构：单链与编排器分层

篇 2 的 suite_pipeline.cpp 是硬编码单链（runDenoise 里 INPUT→降噪→OUTPUT 写死），本篇新增通用编排器 suite_chain.cpp，两者并存不合并——「单链 vs 编排器」的架构演进在工程目录上自证：

entry/src/main/cpp/
├── suite_pipeline.cpp      # 篇2：硬编码单链 + 格式转换器（已过审，不动）
├── realtime_pipeline.cpp   # 篇2：实时预览 + EQ + 空间旋转（不动）
├── suite_chain.cpp         # 本篇：通用编排器（四拓扑 + 契约冲突实验）
├── space_render.cpp        # 本篇：空间渲染三模式取值域契约（同步最小链）
├── node_probe.cpp          # 篇2：14 类节点能力探测（本篇预检复用）
└── pcm_source.cpp          # 篇2：双轨音源载入/RMS（复用）

编排器对外四个 NAPI：runChain（串行链）、runContractTest（强制错误格式配输出节点）、runSeparation（音源分离双路）、runMixer（两路混音）。ArkTS 侧 EffectChainPanel.ets 一个面板承载五组实验（⑥串行链 ⑦分离 ⑧混音 ⑨契约冲突 ⑩空间契约）。

3、Kit能力与核心API深度解析

3.1 十二种效果节点的固定输出格式表

这张表来自 native_audio_suite_base.h 枚举注释逐条抄录（头文件实证，212 为后续复核补录），是全篇的地基：

节点	类型值	@since	固定输出格式	备注
均衡器 EQUALIZER	201	22	48000Hz / S16LE / 2ch	建节点后必须设增益（第 6 节）
降噪 NOISE_REDUCTION	202	22	16000Hz / S16LE / 1ch	降格输出（同为 16k/1ch 的还有 209）
声场 SOUND_FIELD	203	22	48000Hz / S16LE / 2ch	需设 SetSoundFieldType
音源分离 AUDIO_SEPARATION	204	22	48000Hz / F32LE / 4ch	前 2 声道人声、后 2 伴奏；后面只能接输出节点；依赖 NPU
声音美化 VOICE_BEAUTIFIER	205	22	48000Hz / S16LE / 2ch	需设 SetVoiceBeautifierType
环境效果 ENVIRONMENT_EFFECT	206	22	48000Hz / S16LE / 2ch	需设 SetEnvironmentType
混音 AUDIO_MIXER	207	22	采样率随输入 / F32LE / 2ch	唯一支持多路输入
空间渲染 SPACE_RENDER	208	23	48000Hz / S16LE / 2ch	三模式参数见 3.4
传统变声 PURE_VOICE_CHANGE	209	23	16000Hz / S16LE / 1ch	亦降格输出（16k/1ch，与 202 同格式）
通用变声 GENERAL_VOICE_CHANGE	210	23	48000Hz / S16LE / 2ch
变速变调 TEMPO_PITCH	211	23	48000Hz / S16LE / 1ch	亦降格输出（2ch→1ch）；输出时长随倍率变
HOA 空间渲染 HOA_SPACE_RENDER	212	26.0.0	48000Hz / S32LE / 2ch	输入必须 HOA 布局（1–3 阶 ACN/FuMa）

三个工程含义：

1. 降格输出不止降噪一个——降噪（202）48k 立体声进、16k 单声道出；传统变声（209）同为 16k/1ch；变速变调（211）也掉到 1ch。所以不能拿「链尾是不是降噪」当开关去配输出节点，唯一可靠做法是按链尾节点查 3.1 表逐格配置（代码里的 FindNodeSpec 就是这个查表动作）。本篇输出节点格式一律按链尾契约动态配置，不写死。
2. F32LE 的三族（204/207/212 里的 212 是 S32LE）字节宽度是 S16LE 的两倍，算帧大小和反推时长时 bytesPerSample 不能按 2 一刀切。
3. 212 是 26.0.0 增量：探测支持，但输入必须是 HOA 布局素材，本篇的立体声素材驱动不了它，能力边界列在第 7 节。

3.2 连接规则与数量限制

头文件与开发概述（audio-suite）双重对证的硬规则：

• 连接顺序输入节点 → 效果节点 → 输出节点，单向，不可反向连接；
• 音源分离（204）后面只能接输出节点，其余效果节点无此限制；
• 只有混音节点（207）支持多路输入，其余节点多路连接直接报错；
• 每条管线至少 1 个输入节点、有且只有 1 个输出节点；输入节点数量 API 24 前 ≤5、24+ ≤15；混音节点 ≤3、音源分离 ≤1；
• StartPipeline 做完整性检查（无输出节点、起始非输入节点都会在这里被拒）；
• ConnectNodes/DisconnectNodes 建议在停止态操作，运行态只允许连到混音节点；
• IsNodeTypeSupported(type, bool*) 不依赖引擎和管线，可以先裸查——NPU 类节点（204）创建前必查。

3.3 渲染接口：requestFrameSize 的单位是字节

离线渲染两个接口，本篇全部数据从它们出来：

// 单输出渲染：反向驱动，管线从输出节点逐级向上游拉数据
OH_AudioSuite_Result OH_AudioSuiteEngine_RenderFrame(
    OH_AudioSuitePipeline* pipeline,
    void* audioData,          // 输出缓冲，单位字节
    int32_t requestFrameSize, // 请求的字节数（头文件 L191 明写 unit is byte）
    int32_t* responseSize,    // 实际写入的字节数
    bool* finishedFlag);

// 多输出渲染（音源分离专用）：OH_AudioDataArray 里各路缓冲内存大小必须一致
OH_AudioSuite_Result OH_AudioSuiteEngine_MultiRenderFrame(
    OH_AudioSuitePipeline* pipeline,
    OH_AudioDataArray* audioDataArray,
    int32_t* responseSize, bool* finishedFlag);

requestFrameSize 这个参数名里的 “Frame” 有迷惑性，我一度按「帧数」理解，拿头文件对质才确认单位是字节（native_audio_suite_engine.h L191、native_audio_suite_base.h L511 两处都写明 in byte）。帧大小按官方惯例 20ms 算：20 × sampleRate × channels × bytesPerSample / 1000。降噪链 16k/1ch/S16 就是 640 字节一帧，48k/2ch/S16 是 3840 字节。

另外注意与实时预览管线的区分：本篇 suite_chain 走的离线 RenderFrame 按字节请求；篇 2 实时管线的 SetFrameSizeInFrames 按采样点数（20ms×48k=960）。两条线两个接口两种单位，别拿一条的直觉去套另一条。

3.4 空间渲染三模式与取值域

208 节点三种模式，取值域直接写在头文件注释里，本篇是照单全验：

模式	接口	参数与取值域
固定摆位	SetSpaceRenderPositionParams	x/y/z ∈ [-5.0, 5.0] 米
旋转环绕	SetSpaceRenderRotationParams	x/y/z ∈ [-5.0, 5.0] 米；surroundTime ∈ [2, 40] 秒；direction CCW=0/CW=1
扩展声场	SetSpaceRenderExtensionParams	extRadius ∈ [1.0, 5.0] 米；extAngle ∈ (0, 360) 度

坐标系是左手系：拇指朝右 X+、食指朝上 Y+、其余手指朝前 Z+。

4、逻辑流梳理

4.1 反向驱动与跨格式级联

管线数据流是输出节点向上游拉（开发概述原文「由 RenderFrame 发起，输出节点逐级向连接的上游节点请求数据」）。一条 EQ→降噪 的链，一次 RenderFrame 内部的真实旅程：

崩溃栈（AudioOutputNode::DoProcess → ReadPreNodeData → AudioSuiteProcessNode::DoProcess → ObtainProcessedData）就是这张图里「逐级向上游拉」那条调用链——数据被拉经均衡器节点时，它内部未初始化的增益缓冲被解引用了。崩溃与这条链有几层无关，单节点 EQ 链同样触发（6.1 的决定性对照）。

4.2 编排器的四种拓扑

四种拓扑共用一个 SuiteTask 结构和一套固定顺序的销毁（NodeBuilder 用完即销毁；节点→管线→引擎，DestroyNode 要求管线已 STOPPED）。VIOLATION 与 SEPARATION 的「预期失败」都走 resolve 带标志位（violated / separationSupported），不 reject——这两类结果本身就是要采的数据。

5、项目实战

环境声明：以下全部代码与数据基于 HarmonyOS 7.0（API 26）正式版，真机 Mate 60 Pro（ALN-AL80，麒麟 9000S，1260×2720，7.0.0.107 SP8C00E105R4P3），DevEco Studio 26.0.0（SDK 26.0.0.105 Release）。OHAudioSuite 底座 API 22/23，212 节点为 26.0.0。素材：带噪人声 30.4s @48000Hz/2ch/S16LE + 棕噪声 8.0s，与篇 2 同源保证可复现。

5.1 通用编排器：输出节点格式按链尾契约动态配

runDenoise 到 runChain 的核心差异就一处——输出节点格式从写死变成查表：

// 链尾效果节点的固定输出格式决定输出节点配置（格式契约的代码体现）
const NodeFormatSpec *tailSpec = task->chainTypes.empty()
    ? nullptr : FindNodeSpec(static_cast<OH_AudioNode_Type>(task->chainTypes.back()));
// 链非空但链尾类型不在契约表：直接拒绝建链。若放任静默回退成输入格式，
// 反证法的字节自洽依据会被污染成假证（代码审查抓出来后修的）
if (!task->chainTypes.empty() && tailSpec == nullptr) {
    fail("UnknownNodeFormat", LOCAL_ERR_UNSUPPORTED);
    break;
}
OH_AudioFormat fmtOut;
if (task->mode == MODE_VIOLATION && task->forceOutRate > 0) {
    fmtOut = 强制格式;          // VIOLATION：故意配错，实录系统反应
} else if (tailSpec != nullptr) {
    fmtOut = MakeFormat(tailSpec, task->inputSampleRate);  // CHAIN：按链尾契约
} else {
    fmtOut = fmtIn;             // 空链直通
}

kNodeFormatSpec 表内 12 行就是 3.1 那张表的代码化。混音节点 rate=0 表示「采样率随输入」，MakeFormat 用 fallbackRate 落实。

5.2 反证法：SDK 没有 GetNodeFormat，就用字节数自洽来证

编码前 grep 了整个 ohaudiosuite 头文件目录，没有任何逐节点查询实际输出格式的接口——离线渲染是整链一次 RenderFrame 循环，也做不到逐节点插桩。格式契约的验证只能反证：按官方格式配输出节点，渲染成功且输出字节数与「时长×采样率×声道×字节宽」自洽，即证明链尾节点真的按契约格式出数。

7 条链的完整实测（同一素材、同一会话，hilog 逐条留档）：

链（效果序列）	端到端耗时	输出字节	输出格式	字节自洽	RMS 前→后 dBFS
[202] 降噪	4601ms	974080	16k/1ch/S16	30.44s×16000×1×2 ✓	-16.9→-18.2
[201] EQ	672ms	5844480	48k/2ch/S16	×48000×2×2 ✓	-16.9→-16.9
[201,203] EQ+声场	1676ms	5844480	48k/2ch/S16	✓	-16.9→-16.9
[201,203,205] +美化	1749ms	5844480	48k/2ch/S16	✓	-16.9→-17.3
[201,203,205,206] +环境	2007ms	5844480	48k/2ch/S16	✓	-16.9→-21.7
[201,202] EQ→降噪	4714ms	974080	16k/1ch/S16	✓	-16.9→-18.2
[202,201] 降噪→EQ	5091ms	5844480	48k/2ch/S16	✓	-16.9→-18.2

三个读表要点：

1. 降噪节点是绝对成本：凡含 202 的三条链全部落在 4.6–5.1s，不含的都在 0.7–2.0s。30 秒素材，降噪一项 ≈ +3s，其余所有效果加起来不到 1.4s。
2. 链长成本近线性且便宜：同格式链从 2 级到 4 级，1676→1749→2007ms，每加一级约 +170ms。编排时真正要省的是「要不要过降噪」，不是「链有几级」。
3. 降噪的 16k/1ch 输出双向成立：[201,202] 链尾是降噪，输出 974080B（16k/1ch 尺寸）；[202,201] 降噪在前、链尾是 EQ，输出 5844480B（48k/2ch 尺寸）。同一素材同一节点，输出尺寸跟着链尾契约走——反证法要证的「格式契约存在且由链尾决定」，两条链互为对照组。

顺带一提 RMS 列：默认增益的 EQ 前后 -16.9→-16.9 完全透传（增益全 0 本来就是平直曲线）；环境效果（BROADCAST 默认）把响度拉到 -21.7dBFS。降噪 -1.3dB 的轻微衰减在预期内。

5.3 契约冲突实验：系统静默容忍，不报错

把降噪链的输出节点强行配成 48000Hz/2ch（与链尾契约 16k/1ch 冲突），预期里这该被 StartPipeline 完整性检查拒绝。实测结果：渲染成功，耗时 4956ms（复跑 4992ms），errorCode=0，输出 5844480 字节——完全按强制的 48k/2ch 尺寸自洽。

也就是说：输出节点格式是「我要什么」，系统内部做了自适应转换，配错契约表不会有任何警告。这个负结果把 3.1 那张表的工程定位讲清楚了——它不是「配错就报错」的硬校验表，而是「输出尺寸/时长计算必须按它来」的数据一致性表。你按 16k/1ch 去数降噪输出，实际拿到 48k/2ch 缓冲时长的数据，「参数都对但声音不对」就是这么来的。

与第 5.4 节对照着看更有意思：格式域软（静默容忍），参数域硬（越界必拒）。

5.4 空间渲染三模式：取值域 6/6 硬拒

space_render.cpp 做了个最小同步链：建引擎→管线→208 节点，不接输入输出、不 StartPipeline、不渲染，直接在节点上设三模式参数捕获返回码——把「参数取值域契约」从「渲染是否出声」里干净隔离出来。六个用例真机全中：

position 合法 (1.5,0,0)米        → ✓接受
position 越界 (6.0,0,0)米        → ✗越界拒绝(INVALID_PARAM)
rotation 合法 (8s/周)            → ✓接受
rotation 越界 (50s>40)           → ✗越界拒绝(INVALID_PARAM)
extension 合法 (r2.0米,90°)      → ✓接受
extension 越界 (r0.5<1.0)        → ✗越界拒绝(INVALID_PARAM)

效果节点的参数接口在 StartPipeline 之前就能校验取值域（篇 2 已实测参数设置不依赖管线启动），这套「不启动只设参数」的验证手法成本极低，毫秒级出结果。

5.5 音源分离：麒麟 9000S 真跑通了（预案作废）

动笔前我给这一项写的预案是「麒麟 9000S 大概率 NPU 不支持，数据降级为预检拦截实录」。真机打脸了——而且是好的方向：探测 chip 是绿的，点「运行音源分离」，14.7 秒后双路结果出来：

分离成功：人声轨 -20.1dBFS · 伴奏轨 -26.7dBFS · 48000Hz/4ch/F32 · 耗时 14659ms

MultiRenderFrame 双路按官方语义取数：OH_AudioDataArray 两路缓冲（各路内存大小必须一致），audioDataArray[0] 人声、[1] 伴奏——头文件对 204 的注释「前 2 声道人声、后 2 声道伴奏」与双路拆分一一对应。伴奏轨比人声轨低 6.6dB 符合带噪人声素材的直觉（素材里本来就没有完整伴奏，分离出的「伴奏轨」主要承接噪声成分）。

14659ms 是全篇最重的单节点：30 秒素材做分离，比过一遍降噪（4.6s）还贵 3 倍。NPU 占用没有任何公开查询接口（hidumper 无 NPU 计数器），所以「分离跑在 NPU 还是 CPU」我只能存疑记录，不编造归因——能确认的只有「探测支持、跑通、耗时 14.7s」这三个观察。

5.6 多路混音：两路进一路出

混音成功：两路输入→混音207→输出 48000Hz/2ch/F32 · RMS -16.9→-16.2dBFS · 耗时 979ms

人声（30.4s）+ 棕噪声（8.0s）两路 INPUT 各挂独立回调，都 ConnectNodes 到同一个 207 节点——「仅混音支持多路输入」的连接规则正向成立。输出 F32LE/2ch 与契约表一致；两路长度不等时输出按较长路走（混音节点对耗尽的输入路补静音），979ms 的成本几乎可以忽略。代码侧加了道前置闸：两路采样率/声道数不一致直接拒绝建链——混音节点「采样率随输入」在两路异率时跟随谁没有官方保证，与其静默失真不如显式拦截。

6、避坑指南

6.1 均衡器不设增益直接渲染 = 系统库崩溃，应用层无法捕获

现象：预设链 [201,202] 渲染中途进程消失，无错误码、无 JS 异常、hilog 无应用层前兆。崩溃日志（cppcrash）：

Reason:Signal:SIGSEGV(SEGV_MAPERR)@0x0000000000000040
Fault thread: Tid:20870, Name:SuitePipeline   ← 系统库自己的处理线程
#00 ObtainProcessedData()+1168  libaudio_suite.z.so
#01 DoProcess()+2604            libaudio_suite.z.so
#02 ReadPreNodeData()           libaudio_suite.z.so
#03 AudioOutputNode::DoProcess()...

根因：创建 EQ(201) 后未调用 SetEqualizerFrequencyBandGains，节点内部增益缓冲未初始化；渲染期系统库嵌套读上游数据时解引用 NULL+0x40。崩溃发生在系统库线程，不走 RenderFrame 返回值、不抛异常——应用层没有任何捕获点。

排查过程（包括我走错的弯路）：最初归因我写的是「跨格式级联（48k→16k）触发系统库缺陷」，依据是 [201,202] 崩、[202] 不崩。这个归因错得离谱，错在一批假读数：做对照实验时第一条链崩了没重启，后续点击全部落在已死的进程上，pidof 超时被我的脚本读成了「也崩了」——于是「同格式级联也崩」这种伪证据混了进来。改成「每条测试 force-stop + 重启 + pidof 确认存活后再点击」的严格隔离后，数据立刻干净：

时序	链	是否设 EQ 增益	结果
15:20–16:05	[202] ×4	不适用	✅ 4/4
15:21 / 16:04	[201,202] ×2	否	💥 2/2
16:06	[201,202,203]	否	💥
16:24 / 16:28	[201] 单节点	否	💥 2/2 ← 决定性：级联根本不需要
17:20 起（修复后）	全部 7 条 ×9 轮	是	✅ 9/9

方案对比：

方案	效果	代价
应用侧约定「用 EQ 必须设参」	靠人记忆	编排器接受任意节点序列，迟早漏
建节点后按类型设官方默认参数（采纳）	崩溃路径从源头消除	每个效果节点多一次 Set 调用
渲染前探测节点参数状态	无此接口	SDK 没有 GetXxx 前置校验可依赖

最佳实践：编排器里加 ApplyEffectDefaults，建完效果节点立刻按类型设官方默认值，再连接再渲染：

OH_AudioSuite_Result ApplyEffectDefaults(OH_AudioNode *node, OH_AudioNode_Type type)
{
    switch (type) {
        case EFFECT_NODE_TYPE_EQUALIZER:
            // 官方 extern const 预置：10 频带全 0dB（base.h L641）
            return OH_AudioSuiteEngine_SetEqualizerFrequencyBandGains(node, OH_EQUALIZER_PARAM_DEFAULT);
        case EFFECT_NODE_TYPE_SOUND_FIELD:
            return OH_AudioSuiteEngine_SetSoundFieldType(node, SOUND_FIELD_FRONT_FACING);
        case EFFECT_NODE_TYPE_VOICE_BEAUTIFIER:
            return OH_AudioSuiteEngine_SetVoiceBeautifierType(node, VOICE_BEAUTIFIER_TYPE_CLEAR);
        case EFFECT_NODE_TYPE_ENVIRONMENT_EFFECT:
            return OH_AudioSuiteEngine_SetEnvironmentType(node, ENVIRONMENT_TYPE_BROADCAST);
        default:
            return AUDIOSUITE_SUCCESS;  // 202/204/207 实测不设参渲染安全
    }
}

203/205/206 与 EQ 同构（参数接口是节点内部状态的初始化路径），一并预防性设置；降噪/混音/分离三类实测不设参也安全，保持不设置。顺序与官方示例一致：CreateNode → Set 参数 → ConnectNodes。

验证：修复后 7 条链 9 轮全过，含原崩溃组合 [201,202]（4714ms 正常出数）；崩溃日志目录再无新增。

为什么文档没写：头文件对 SetEqualizerFrequencyBandGains 只描述功能，无「必须调用」措辞；官方示例建 EQ 后紧跟设参，但没人告诉你不跟会怎样。这条只能靠真机撞出来——这也是深潜篇存在的意义。

6.2 格式契约冲突不报错：静默容忍比报错更危险

5.3 的负结果单独列一条坑：把降噪链输出节点配成 48k/2ch，StartPipeline 和 RenderFrame 全程零错误。不要指望用「配错看它报不报错」来验证格式契约——报错预期落空时，很容易误判成「契约不存在」。正确的验证手段是 5.2 的字节数自洽反证：按两种格式分别配输出节点，比较输出字节数与时长反推值，契约在数据里，不在错误码里。

6.3 崩溃类隔离测试：每条用例必须重启后测

6.1 的假读数教训推广成规矩：验证「哪条链会崩」时，崩溃会杀死宿主进程，之后的所有点击都落在死应用上，读出来的「成功/失败」全是噪声。脚本模板固化为：force-stop → start → pidof 确认 → 导航 → 点击 → 轮询 pidof，任何一步 pidof 为空即判定「测试无效需重跑」，而不是「又崩了」。同理，真机自动化里结果行插入会把下方按钮坐标推歪——每次点击前重新 dumpLayout 取坐标，复用上一屏坐标会点到标题甚至空处。

6.4 MultiRenderFrame 双路缓冲：大小必须一致，responseSize 一路共享

音源分离的 OH_AudioDataArray 要求 requestFrameSize 是每一路缓冲的字节数，各路内存大小必须一致（base.h L511-512 明写）；返回的 responseSize 对两路同时生效（系统保证每路填充尺寸一致）。取数时两路各 insert(..., responseSize) 即可，但插入前一律 min(responseSize, frameSize) 截断兜底——官方契约保证有界，防御的是实现异常时的越界读（代码审查时达成的一致意见）。

6.5 空间渲染坐标越界：硬拒，但只在设参那一刻

与 6.2 相反，3.4 的取值域是硬要求：越界直接 INVALID_PARAM（6/6 实测）。工程上这意味着摆位/环绕参数来自用户输入（滑块、拖拽）时，设参返回值必须逐个检查——它不会崩、不会静默，但会拒；拒了不处理的话，用户会觉得「声场没变化」。

6.6 官方离线示例的 CreateNode 首参笔误

官方文档「离线编辑」基础示例第 2 步写的是 OH_AudioSuiteEngine_CreateNode(audioSuiteEngine, nodeBuilder, &node)——首参传了引擎。同文档音源分离示例和头文件签名都是 pipeline。照抄示例第一段会编译报错（类型不匹配），算笔误里运气好的；本篇所有 CreateNode 调用以头文件签名为准：CreateNode(pipeline, builder, &node)。

7、总结

把节点串起来这件事，OHAudioSuite 给的自由度比预期大（任意效果序列、多路混音、双路分离），约束则藏在三个深浅不一的地方：格式契约在数据里不在错误码里（配错静默容忍，靠字节自洽验证）；参数域契约在返回值里（越界硬拒 INVALID_PARAM，设参必查返回值）；初始化义务在崩溃栈里（EQ 不设增益直接渲染，系统库线程 SIGSEGV，应用层无从捕获——这是本篇付出一次进程代价换来的增量认知，头文件与文档均无明示）。

编排器（suite_chain.cpp 1179 行，含代码审查后的 9 项修复）验证过的拓扑与数据：7 链时延表、双路分离、两路混音、契约冲突负结果、三模式取值域 6/6。降噪节点 +3s 的成本结论和「链长每级约 +170ms」可以直接用于编排决策。

未实测部分（全部单机 Mate 60 Pro / 7.0.0.107 单固件实测，外推需再验证）：

• 212 HOA 空间渲染探测支持，但需 HOA 布局输入素材，本篇未驱动，能力边界止于「支持」二字；
• 音源分离的 NPU/CPU 执行归属无法查证（无公开占用接口），只记录「支持+跑通+14659ms」三个观察；14.7s 是否含首次加载预热未做剔除实验；
• EQ 不设参崩溃的复现率是修复前 5/5、修复后 0/9，样本限于 20ms 帧、30.4s 素材、离线 EDIT 模式；更短素材或实时管线（篇 2 的 REALTIME 模式建 EQ 即设参）是否同症状，未测；
• 格式契约「静默容忍」实测覆盖降噪→48k/2ch 一种组合；其余节点间配错组合未穷举，不排除个别组合有拒绝路径；
• 混音两路异采样率的行为（跟随哪一路）无官方说明，本篇以应用侧前置拦截回避，未实测系统原生表现；
• 时延数据为单次端到端观察值（hilog 毫秒级），未做多轮中位数统计，量级结论（降噪主导成本）稳、精确值供参考。