Only the Chinese version of this page is provided currently. The English version will be provided soon.
Help & Documentation>实时音视频>直播与语聊 SDK>Core SDK>功能模块>音效>音效（React Native）

音效（React Native）

Last updated: 2026-05-07 15:09:11

On this page:

本篇文档旨在指导您如何使用 AtomicXCore 框架中的 AudioEffectState 和 DeviceState 模块，为您的直播应用快速集成音效控制功能，包括麦克风音量、耳返监听，并添加多种趣味变声效果和混响效果。


核心功能

通过组合 AudioEffectState 和 DeviceState，您将能实现以下核心功能：
人声音量调节：控制本地音频上行的采集音量大小，即观众听到的您的声音大小。
耳返功能：允许主播或连麦用户通过耳机实时听到自己的声音，用于监听和矫正发音。
变声效果：提供多种趣味变声选项，例如萝莉、大叔、熊孩子等。
混响效果：模拟不同环境的声场效果，例如 KTV、金属声、低沉、洪亮等。

实现步骤

步骤1：组件集成

视频直播：请参考 开播与观看 集成 AtomicXCore，完成接入。
语聊房：请参考 开播与收听 集成 AtomicXCore，完成接入。

步骤2：获取 State 实例

AudioEffectState 和 DeviceState 是单例对象，您可以在项目的任何位置获取实例。
import { useAudioEffectState } from 'react-native-tuikit-atomic-x/lib/module/atomic-x/state/AudioEffectState';
import { useDeviceState } from 'react-native-tuikit-atomic-x/lib/module/atomic-x/state/DeviceState';

// 获取对应实例
const audioEffect = useAudioEffectState();
const deviceState = useDeviceState();

步骤3：实现耳返功能

耳返功能允许用户实时监听自己的麦克风声音，可以通过调用本节介绍的接口管理耳返功能。
注意：
耳返功能通常需要连接耳机才能正常工作。

实现方式:

1. 开关耳返：您可以在 UI 上自行实现开关耳返功能。
2. 设置耳返音量值：您可以自行实现左右拖动滑块来调节音量的功能，并将您 UI 上的值映射成音量值，调用 setVoiceEarMonitorVolume。请注意，该接口接收的参数范围是 [0, 100] 所以您需要将 UI 控件的值映射到 0 ~ 100 的范围。
3. 监听状态更新 UI：您可以订阅实时的耳返状态值更新 UI。

代码示例:

import { useEffect } from 'react';
import { useAudioEffectState } from 'react-native-tuikit-atomic-x/lib/module/atomic-x/state/AudioEffectState';

// 获取对应实例
const { setVoiceEarMonitorEnable, setVoiceEarMonitorVolume, earMonitorVolume } = useAudioEffectState();

// 1. 开启/关闭耳返
const handleSetVoiceEarMonitorEnable = (enable) => {
  setVoiceEarMonitorEnable({ enable });
};

// 2. 调节耳返音量
const handleSetVoiceEarMonitorVolume = (volume) => {
  setVoiceEarMonitorVolume({ volume });
};

// 3. 监听耳返音量变化
useEffect(() => {
  console.log('耳返音量:', earMonitorVolume);
}, [earMonitorVolume]);

setVoiceEarMonitorEnable 接口参数

参数名
类型
描述
enable
boolean
是否开启耳返。
true：开启
false：关闭

setVoiceEarMonitorVolume 接口参数

参数名
类型
描述
volume
number
耳返音量大小。
取值范围： [0, 100]
默认值：100

步骤4：实现人声音量调节

当主播希望调节自己的上行采集音量大小时，调用 DeviceState 的 setCaptureVolume 方法传入音量值即可。

实现方式:

1. 设置采集音量值：您可自行实现调节音量的功能，并将 UI 上的值映射成音量值后调用 setCaptureVolume。请注意，该接口接收的参数范围是 [0, 100] ，所以您需要将 UI 控件的值映射到 0 - 100 的范围。
2. 监听状态更新 UI：您可以订阅实时的音量状态值更新 UI。

示例代码：

import { useEffect } from 'react';
import { useDeviceState } from 'react-native-tuikit-atomic-x/lib/module/atomic-x/state/DeviceState';

// 获取对应实例
const { setCaptureVolume, captureVolume } = useDeviceState();

// 1. 调节音量
const handleSetCaptureVolume = (volume) => {
  setCaptureVolume({ volume });
};

// 2. 监听状态
useEffect(() => {
  console.log('采集音量:', captureVolume);
}, [captureVolume]);

setCaptureVolume 接口参数

参数名
类型
描述
volume
number
采集音量大小。
取值范围： [0, 100]
默认值：100

步骤5：实现变声效果

当主播希望改变自己的声音时，您可以调用 setAudioChangerType 方法，传入相应的枚举值即可切换效果。

示例代码：

import { useAudioEffectState } from 'react-native-tuikit-atomic-x/lib/module/atomic-x/state/AudioEffectState';

// 获取对应实例
const { setAudioChangerType } = useAudioEffectState();

// 设置变声效果
const handleSetAudioChangerType = (changerType) => {
  setAudioChangerType({ changerType });
};

setAudioChangerType 接口参数

参数名
类型
描述
changerType
string
变声效果，可选值：
'NONE' ：关闭变声，不使用任何变声效果。
'CHILD' ：熊孩子，音色稚嫩，活泼可爱。
'LITTLE_GIRL' ：小孩子，音色甜美，清脆悦耳。
'MAN' ：大叔，音色低沉，浑厚有力。
'HEAVY_METAL' ：重金属，音色带有金属质感，硬朗粗犷。
'COLD' ：感冒，音色带有鼻音，仿佛感冒状态。
'FOREIGNER' ：外国人，音色带有外国口音风格。
'TRAPPED_BEAST' ：困兽，音色低沉压抑，带有咆哮感。
'FATSO' ：浑厚，音色浑厚憨态，风格幽默。
'STRONG_CURRENT' ：强电流，音色带有电流干扰效果，科幻感强。
'HEAVY_MACHINERY' ：重机械，音色带有机械回响，工业风格。
'ETHEREAL' ：空灵，音色飘渺通透，富有仙气。

步骤6：实现混响效果

当主播希望给自己的声音添加混响效果时，您可以调用 setAudioReverbType 方法，传入相应的枚举值即可切换效果。
import { useAudioEffectState } from 'react-native-tuikit-atomic-x/lib/module/atomic-x/state/AudioEffectState';

// 获取对应实例
const { setAudioReverbType } = useAudioEffectState();

// 设置混响效果
const handleSetAudioReverbType = (reverbType) => {
  setAudioReverbType({ reverbType });
};

setAudioReverbType 接口参数

参数名
类型
描述
reverbType
string
混响效果，可选值：
'NONE' ：关闭混响，不使用任何混响效果。
'KTV' ：KTV，模拟 KTV 包房的混响效果，回声适中，适合唱歌场景。
'SMALL_ROOM' ：小房间，模拟小型房间的混响效果，空间感紧凑。
'AUDITORIUM' ：大会堂，模拟大型会堂的混响效果，回声宽广，空间感强。
'DEEP' ：低沉，混响效果偏低频，声音深沉浑厚。
'LOUD' ：洪亮，混响效果增强响度，声音更加饱满有力。
'METALLIC' ：金属声，混响带有金属质感，声音清脆尖锐。
'MAGNETIC' ：磁性，混响效果柔和温暖，声音富有磁性和感染力。

API 文档

关于 AudioEffectState 和 DeviceState 及其相关类的所有公开接口、属性的详细信息，请参阅随 AtomicXCore 框架的官方 API 文档。
State
功能描述
API 文档
AudioEffectState
音效管理：进行音效设置，并获取实时音效状态。
API 文档
DeviceState
设备管理：进行摄像头、麦克风操作，并获取实时设备状态。
API 文档

常见问题

音效和设备接口的调用时机有没有要求？

没有限制。AudioEffectState 和 DeviceState 的设置是全局生效的 您可以在进入直播间之前或之后随时调用相关接口（例如设置变声、混响或耳返），设置会立即生效并被保留。

“人声音量” 和“耳返音量” 有什么区别？

这是一个非常重要且易混淆的概念，区别如下：
人声音量 (CaptureVolume)：通过 setCaptureVolume 设置。它决定了观众能听到的您的声音大小。
耳返音量 (EarMonitorVolume)：通过 setVoiceEarMonitorVolume 设置。它只决定了您自己在耳机里听到的监听声音大小，不会影响观众。

新创建的直播间为什么直接就有音效、或者出现音量很大、很小等问题？

AudioEffectState 和 DeviceState 是单例，这意味着音效和设备设置是全局生效的，出现这种情况很可能是因为您之前设置过音效但是没有重置，需要在合适的地方将数据重置。

为什么我开启了“耳返”，但是听不到自己的声音？

请您按照以下步骤检查：
1. 是否插入耳机：耳返功能绝大多数情况下依赖耳机才能生效，请确保已连接有线或蓝牙耳机。
2. 音量是否为0：检查“耳返音量”是否被设置为了 0。
3. 麦克风是否开启：确认 DeviceState 中的麦克风是开启状态（即已调用 openLocalMicrophone）。

变声效果 和混响效果 可以同时生效吗？

可以。AudioChangerType 和 AudioReverbType 是可以叠加生效的。例如，您可以同时设置 'LITTLE_GIRL' 变声和 'KTV'混响。




中国站 - English