目录

音频效果(C/C++)

从API版本22开始，OHAudioSuite提供多种音频效果节点，开发者可根据业务需求选择合适的效果节点对音频进行处理。

效果节点类型

效果类型 节点类型 起始API版本 用途 说明
均衡器 EFFECT_NODE_TYPE_EQUALIZER API版本22 频段调节，改变音频频率特性。 -
降噪 EFFECT_NODE_TYPE_NOISE_REDUCTION API版本22 降低背景噪声，提升语音清晰度。 -
声场 EFFECT_NODE_TYPE_SOUND_FIELD API版本22 调整声音空间感和声场范围。 -
音源分离 EFFECT_MULTII_OUTPUT_NODE_TYPE_AUDIO_SEPARATION API版本22 分离人声与伴奏（多路输出）。 该功能依赖NPU，创建节点前需调用OH_AudioSuiteEngine_IsNodeTypeSupported()检查是否支持该节点类型。
声音美化 EFFECT_NODE_TYPE_VOICE_BEAUTIFIER API版本22 提升音质和听感。 -
环境效果 EFFECT_NODE_TYPE_ENVIRONMENT_EFFECT API版本22 模拟不同环境的声学效果。 -
混音 EFFECT_NODE_TYPE_AUDIO_MIXER API版本22 多路音频混合为一路。 -
空间渲染 EFFECT_NODE_TYPE_SPACE_RENDER API版本23 3D空间音频定位与渲染。 -
传统变声 EFFECT_NODE_TYPE_PURE_VOICE_CHANGE API版本23 基于性别与音调的传统变声。 -
通用变声 EFFECT_NODE_TYPE_GENERAL_VOICE_CHANGE API版本23 多种风格化变声效果。 -
变速变调 EFFECT_NODE_TYPE_TEMPO_PITCH API版本23 改变音频速度与音调。 -
HOA空间音频 EFFECT_NODE_TYPE_HOA_SPACE_RENDER API版本26.0.0 HOA高阶Ambisonics转双耳渲染。 -

均衡器

均衡器效果节点EFFECT_NODE_TYPE_EQUALIZER通过调整不同频段的增益来改变音频的频率特性，实现丰富的音乐风格效果。

[h2]均衡器频段

均衡器效果节点支持10个频段的增益调节，每个频段可以独立设置增益值。增益值范围为[-10, 10]，单位为分贝（dB）。开发者可以使用预设效果或自定义各频段增益。

10个频段对应的频率如下表所示：

频段序号

频率

单位为赫兹（Hz）

增益范围

单位为分贝（dB）

 音频特性
0 31 [-10, 10] 超低频，影响重低音效果。
1 62 [-10, 10] 低频，影响低音鼓、贝斯等。
2 125 [-10, 10] 低中频，影响男声、吉他等。
3 250 [-10, 10] 中频，影响人声、乐器主体。
4 500 [-10, 10] 中高频，影响人声清晰度。
5 1000 [-10, 10] 中高频，影响人声明亮度。
6 2000 [-10, 10] 高频，影响人声细节、乐器泛音。
7 4000 [-10, 10] 高频，影响乐器明亮度。
8 8000 [-10, 10] 高频，影响乐器高音、打击乐。
9 16000 [-10, 10] 超高频，影响空气感、细节。

[h2]预置效果类型

均衡器节点内置以下预置效果：

[h2]均衡器效果节点设置方法

// 设置为均衡器节点类型。
OH_AudioSuiteNodeBuilder_SetNodeType(builder, OH_AudioNode_Type::EFFECT_NODE_TYPE_EQUALIZER);
// 创建均衡器节点。
OH_AudioSuiteEngine_CreateNode(pipeline, builder, node);
// ...
// 设置均衡器节点效果。
OH_AudioSuiteEngine_SetEqualizerFrequencyBandGains(*node, gains);

降噪

降噪效果节点EFFECT_NODE_TYPE_NOISE_REDUCTION用于降低音频中的背景噪声，提升语音的清晰度与可懂度。

[h2]配置说明

降噪效果节点无需额外配置参数，创建节点并接入管线后即生效。开发者可通过OH_AudioSuiteEngine_BypassEffectNode控制是否旁路（透传）该效果。

[h2]降噪效果节点设置方法

// 设置为降噪节点类型。
OH_AudioSuiteNodeBuilder_SetNodeType(builder, OH_AudioNode_Type::EFFECT_NODE_TYPE_NOISE_REDUCTION);
// 创建降噪节点。
OH_AudioSuiteEngine_CreateNode(pipeline, builder, node);

声场

声场效果节点EFFECT_NODE_TYPE_SOUND_FIELD通过调整声音的空间感与声场范围，营造不同的听感氛围。

[h2]声场类型

声场效果节点支持以下四种声场效果，通过OH_SoundFieldType进行设置：

枚举值 名称 描述
SOUND_FIELD_FRONT_FACING = 1 前置声场 声音集中于前方，营造前向聚焦听感。
SOUND_FIELD_GRAND = 2 宏大声场 拓宽声场范围，营造宏大开阔的空间感。
SOUND_FIELD_NEAR = 3 聆听声场 缩短听感距离，营造贴近聆听的现场感。
SOUND_FIELD_WIDE = 4 宽广声场 扩展左右声场宽度，增强横向包围感。

[h2]声场效果节点设置方法

// 设置为声场节点类型。
OH_AudioSuiteNodeBuilder_SetNodeType(builder, OH_AudioNode_Type::EFFECT_NODE_TYPE_SOUND_FIELD);
// 创建声场节点。
OH_AudioSuiteEngine_CreateNode(pipeline, builder, node);
// 设置声场节点效果。
OH_AudioSuiteEngine_SetSoundFieldType(*node, static_cast<OH_SoundFieldType>(params.soundFieldType));

音源分离

音源分离效果节点EFFECT_MULTII_OUTPUT_NODE_TYPE_AUDIO_SEPARATION可将混合音频分离为人声与伴奏两路，属于多输出效果节点，每个管线中数量不超过1个。

[h2]配置说明

[h2]音源分离效果节点设置方法

参考音源分离场景进行设置。

声音美化

声音美化效果节点EFFECT_NODE_TYPE_VOICE_BEAUTIFIER可以提升音频的音质和听感，为用户带来更加优质的听觉体验。

[h2]美化类型

声音美化效果节点支持以下四种美化效果类型，通过OH_VoiceBeautifierType进行设置：

枚举值 名称 描述
VOICE_BEAUTIFIER_TYPE_CLEAR = 1 清澈效果 使声音更加清晰明亮，适合需要突出细节的场景。
VOICE_BEAUTIFIER_TYPE_THEATRE = 2 剧场效果 营造剧场般的空间感和回响效果，适合戏剧、演出等场景。
VOICE_BEAUTIFIER_TYPE_CD = 3 CD效果 提供专业CD音质的听感，适合高品质音乐播放场景。
VOICE_BEAUTIFIER_TYPE_RECORDING_STUDIO = 4 录音棚效果 录音棚效果，营造专业录音棚的声音质感，适合录音制作场景。

[h2]美化效果节点设置方法

// 设置为声音美化节点类型。
OH_AudioSuiteNodeBuilder_SetNodeType(builder, OH_AudioNode_Type::EFFECT_NODE_TYPE_VOICE_BEAUTIFIER);
// 创建声音美化节点。
OH_AudioSuiteEngine_CreateNode(pipeline, builder, node);
// 设置声音美化节点效果。
OH_AudioSuiteEngine_SetVoiceBeautifierType(*node,
                                           static_cast<OH_VoiceBeautifierType>(params.voiceBeautifierType));

环境效果

环境效果节点EFFECT_NODE_TYPE_ENVIRONMENT_EFFECT通过模拟不同声学环境的特性，使音频呈现对应场景的听感。

[h2]环境类型

环境效果节点支持以下四种环境效果，通过OH_EnvironmentType进行设置：

枚举值 名称 描述
ENVIRONMENT_TYPE_BROADCAST = 1 广播 模拟广播电台的声学特性。
ENVIRONMENT_TYPE_EARPIECE = 2 电话听筒 模拟电话听筒的窄带听感。
ENVIRONMENT_TYPE_UNDERWATER = 3 水下 模拟水下传播的闷响效果。
ENVIRONMENT_TYPE_GRAMOPHONE = 4 留声机 模拟老式留声机的复古音色。

[h2]环境效果节点设置方法

// 设置为环境效果节点类型。
OH_AudioSuiteNodeBuilder_SetNodeType(builder, OH_AudioNode_Type::EFFECT_NODE_TYPE_ENVIRONMENT_EFFECT);
// 创建环境效果节点。
OH_AudioSuiteEngine_CreateNode(pipeline, builder, node);
// 设置环境效果节点效果。
OH_AudioSuiteEngine_SetEnvironmentType(*node, static_cast<OH_EnvironmentType>(params.environmentType));

混音

混音效果节点EFFECT_NODE_TYPE_AUDIO_MIXER用于将多路输入音频混合为一路输出，每个管线中混音节点的数量不超过3个。

[h2]混音效果节点设置方法

参考混音与级联进行设置。

空间渲染

空间渲染效果节点EFFECT_NODE_TYPE_SPACE_RENDER用于实现3D空间音频的定位与渲染，采用左手坐标系（拇指指向x轴正方向、食指指向y轴正方向、其余手指指向z轴正方向），详细说明请参考空间音频渲染(C/C++)。

[h2]渲染模式

空间渲染效果节点支持三种渲染模式，分别对应三组配置参数：

固定摆位模式

通过OH_AudioSuiteEngine_SetSpaceRenderPositionParams进行设置，参数结构体OH_AudioSuite_SpaceRenderPositionParams的成员定义如下：

成员 类型 取值范围 单位 说明
x float [-5.0, 5.0] 米（m） 空间中的X坐标。
y float [-5.0, 5.0] 米（m） 空间中的Y坐标。
z float [-5.0, 5.0] 米（m） 空间中的Z坐标。

旋转模式

通过OH_AudioSuiteEngine_SetSpaceRenderRotationParams进行设置，参数结构体OH_AudioSuite_SpaceRenderRotationParams的成员定义如下：

成员 类型 取值范围 单位 说明
x float [-5.0, 5.0] 米（m） 空间中的X坐标。
y float [-5.0, 5.0] 米（m） 空间中的Y坐标。
z float [-5.0, 5.0] 米（m） 空间中的Z坐标。
surroundTime int32_t [2, 40] 秒（s） 单周环绕时间。
surroundDirection OH_AudioSuite_SurroundDirection [0, 1] - 环绕方向：0=逆时针（SPACE_RENDER_CCW），1=顺时针（SPACE_RENDER_CW）。

扩展模式

通过OH_AudioSuiteEngine_SetSpaceRenderExtensionParams进行设置，参数结构体OH_AudioSuite_SpaceRenderExtensionParams的成员定义如下：

成员 类型 取值范围 单位 说明
extRadius float [1.0, 5.0] 米（m） 扩展半径。
extAngle int32_t (0, 360) 度（°） 扩展角度。

[h2]空间渲染效果节点设置方法

// 设置为空间渲染节点类型。
OH_AudioSuiteNodeBuilder_SetNodeType(builder, OH_AudioNode_Type::EFFECT_NODE_TYPE_SPACE_RENDER);
// 创建空间渲染节点。
OH_AudioSuiteEngine_CreateNode(pipeline, builder, node);
// 按场景设置空间渲染参数。
switch (params.spaceRenderMode) {
    // 固定摆位模式。
    case SPACE_RENDER_MODE_POSITION: {
        OH_AudioSuite_SpaceRenderPositionParams position;
        position.x = params.spacePositionX;
        position.y = params.spacePositionY;
        position.z = params.spacePositionZ;
        OH_AudioSuiteEngine_SetSpaceRenderPositionParams(*node, position);
        break;
    }
    // 旋转模式。
    case SPACE_RENDER_MODE_ROTATION: {
        OH_AudioSuite_SpaceRenderRotationParams rotation;
        rotation.x = params.spaceRotationX;
        rotation.y = params.spaceRotationY;
        rotation.z = params.spaceRotationZ;
        rotation.surroundTime = params.spaceRotationSurroundTime;
        rotation.surroundDirection =
            static_cast<OH_AudioSuite_SurroundDirection>(params.spaceRotationSurroundDirection);
        OH_AudioSuiteEngine_SetSpaceRenderRotationParams(*node, rotation);
        break;
    }
    // 扩展模式。
    case SPACE_RENDER_MODE_EXTENSION: {
        OH_AudioSuite_SpaceRenderExtensionParams extension;
        extension.extRadius = params.spaceExtensionRadius;
        extension.extAngle = params.spaceExtensionAngle;
        OH_AudioSuiteEngine_SetSpaceRenderExtensionParams(*node, extension);
        break;
    }
    default:
        break;
}

传统变声

传统变声效果节点EFFECT_NODE_TYPE_PURE_VOICE_CHANGE通过指定性别、变声类型与音调实现传统变声效果。

[h2]配置说明

传统变声效果节点通过结构体OH_AudioSuite_PureVoiceChangeOption配置，包含以下成员：

成员 类型 说明
optionGender OH_AudioSuite_PureVoiceChangeGenderOption 变声性别：1=女声（PURE_VOICE_CHANGE_FEMALE），2=男声（PURE_VOICE_CHANGE_MALE）。
optionType OH_AudioSuite_PureVoiceChangeType 参考下方变声类型。
pitch float 音调。使用系统推荐音调设为宏定义中的OH_PURE_VOICE_DEFAULT_PITCH（0.0f）以获得最佳效果，自定义取值范围为[0.3f, 3.0f]。

变声类型

枚举值 名称 描述
PURE_VOICE_CHANGE_TYPE_CARTOON = 1 卡通 卡通风格变声。
PURE_VOICE_CHANGE_TYPE_CUTE = 2 萝莉 萝莉风格变声。
PURE_VOICE_CHANGE_TYPE_FEMALE = 3 女声 女声变声。
PURE_VOICE_CHANGE_TYPE_MALE = 4 男声 男声变声。
PURE_VOICE_CHANGE_TYPE_MONSTER = 5 怪兽 怪兽风格变声。
PURE_VOICE_CHANGE_TYPE_ROBOTS = 6 机器人 机器人风格变声。
PURE_VOICE_CHANGE_TYPE_SEASONED = 7 大叔 大叔风格变声。

[h2]传统变声效果节点设置方法

// 设置为传统变声节点类型。
OH_AudioSuiteNodeBuilder_SetNodeType(builder, OH_AudioNode_Type::EFFECT_NODE_TYPE_PURE_VOICE_CHANGE);
// 创建传统变声节点。
OH_AudioSuiteEngine_CreateNode(pipeline, builder, node);
// 设置传统变声节点效果。
OH_AudioSuite_PureVoiceChangeOption option;
option.optionGender = static_cast<OH_AudioSuite_PureVoiceChangeGenderOption>(params.pureVoiceChangeGender);
option.optionType = static_cast<OH_AudioSuite_PureVoiceChangeType>(params.pureVoiceChangeType);
option.pitch = params.pureVoiceChangePitch;
OH_AudioSuiteEngine_SetPureVoiceChangeOption(*node, option);

通用变声

通用变声效果节点EFFECT_NODE_TYPE_GENERAL_VOICE_CHANGE提供多种风格化的变声效果，适用场景更丰富。

[h2]变声类型

通用变声效果节点支持以下十种变声类型，通过OH_AudioSuite_GeneralVoiceChangeType进行设置：

枚举值 名称 描述
GENERAL_VOICE_CHANGE_TYPE_CUTE = 1 萝莉 萝莉风格变声。
GENERAL_VOICE_CHANGE_TYPE_CYBERPUNK = 2 赛博朋克 赛博朋克风格变声。
GENERAL_VOICE_CHANGE_TYPE_FEMALE = 3 女声 女声变声。
GENERAL_VOICE_CHANGE_TYPE_MALE = 4 男声 男声变声。
GENERAL_VOICE_CHANGE_TYPE_MIX = 5 混响 混响风格变声。
GENERAL_VOICE_CHANGE_TYPE_MONSTER = 6 怪兽 怪兽风格变声。
GENERAL_VOICE_CHANGE_TYPE_SEASONED = 7 大叔 大叔风格变声。
GENERAL_VOICE_CHANGE_TYPE_SYNTH = 8 合成器 合成器风格变声。
GENERAL_VOICE_CHANGE_TYPE_TRILL = 9 颤音 颤音风格变声。
GENERAL_VOICE_CHANGE_TYPE_WAR = 10 战争 战争风格变声。

[h2]通用变声效果节点设置方法

// 设置为通用变声节点类型。
OH_AudioSuiteNodeBuilder_SetNodeType(builder, OH_AudioNode_Type::EFFECT_NODE_TYPE_GENERAL_VOICE_CHANGE);
// 创建通用变声节点。
OH_AudioSuiteEngine_CreateNode(pipeline, builder, node);
// 设置通用变声节点效果。
OH_AudioSuiteEngine_SetGeneralVoiceChangeType(
    *node, static_cast<OH_AudioSuite_GeneralVoiceChangeType>(params.generalVoiceChangeType));

变速变调

变速变调效果节点EFFECT_NODE_TYPE_TEMPO_PITCH用于独立或同时改变音频的播放速度与音调。

[h2]配置说明

通过OH_AudioSuiteEngine_SetTempoAndPitch设置，参数说明如下：

参数 类型 取值范围 说明
speed float [0.5, 10.0] 变速参数。1.0为原始速度，小于1.0减速，大于1.0加速。
pitch float [0.1, 5.0] 变调参数。1.0为原始音调，小于1.0降调，大于1.0升调。

[h2]变速变调效果节点设置方法

// 设置为变速变调节点类型。
OH_AudioSuiteNodeBuilder_SetNodeType(builder, OH_AudioNode_Type::EFFECT_NODE_TYPE_TEMPO_PITCH);
// 创建变速变调节点。
OH_AudioSuiteEngine_CreateNode(pipeline, builder, node);
// 设置变速变调节点效果。
OH_AudioSuiteEngine_SetTempoAndPitch(*node, params.tempoSpeed, params.tempoPitch);

HOA空间音频

HOA（High-Order Ambisonics）转双耳空间音频节点EFFECT_NODE_TYPE_HOA_SPACE_RENDER用于将HOA格式的空间音频转换为双耳（Binaural）立体声输出。

[h2]输入音频格式

该节点的前置节点必须为HOA格式的输入节点，输入音频格式要求如下：

[h2]配置说明