实时音视频
实时音视频
文档指南
请输入
- 文档首页
实时音视频实时音视频开发指南音频管理Web 端音频前处理（AEC-AGC）
复制全文
下载 pdfWeb 端音频前处理（AEC-AGC）
文档反馈
问问助手你可以在 Web 端音频采集链路中使用音频前处理插件，对本地采集音频进行回声消除和增益控制，提升通话或直播场景下的音频采集效果。其中，AEC（Acoustic Echo Cancellation）用于降低扬声器外放音频被本地麦克风再次采集后产生的回声，AGC（Automatic Gain Control）用于自动调节采集音量，提升不同设备和使用姿态下的音量稳定性。本文主要介绍 Web 端 AEC 和 AGC 插件的接入方式及相关使用说明。
前提条件
- 已集成 Web SDK 4.69.1 或更高版本。
- 已实现 Web 端音视频通话能力。具体可参见实现音视频通话。
- 已完成基础音频采集链路接入。
注意事项
- 建议在开始音频采集前完成插件注册，再调用 startAudioCapture() 开启音频采集。
- 如果同时使用 AEC、AINR、AGC 三个插件，建议按 AEC -> AINR -> AGC 的顺序接入；Web SDK 4.69.1 及以上版本会保证该顺序，更早版本无法保证。
- AEC 与 AGC 都属于采集前处理能力，应明确其作用对象，避免与业务已有的自定义音频处理逻辑冲突。
- AEC 在耳机播放场景下通常没有明显收益，更适合扬声器外放场景。
- 当插件回调 onOverload 时，建议关闭不必要的前处理能力，或引导用户切换到性能更好的设备。
回声消除插件
AEC 适用于扬声器外放场景。开启后可降低远端播放音频再次被本地麦克风采集而形成回声的问题。
使用示例
import RTCAECExtension, { AECProfile } from '@volcengine/rtc/extension-aec';
import VERTC from '@volcengine/rtc';
// 创建插件实例
const aecExtension = new RTCAECExtension();
// 检查当前浏览器是否支持 AEC 插件
const isSupported = await aecExtension.isSupported();
const engine = VERTC.createEngine('<YOUR_APP_ID>');
if (isSupported) {
try {
await engine.registerExtension(aecExtension);
} catch (error) {
// 注册失败，详见 error.message
}
}
// 设置插件档位
// AI: AI 场景
// BROADCASTER: 连麦主播场景
// AUTO: 自动档位
await aecExtension.setProfile(AECProfile.AI);
// 建议在注册插件后开启采集
await engine.startAudioCapture();
关键说明
- 调用 enable() 和 disable() 时，如果不传参数，默认作用于内部采集的主流音频。
- AEC 只有在存在远端参考音频流时才会真正生效。
- 插件会自动维护远端参考流，通常无需业务侧手动调用 addReferenceTrack()。
- 建议在开始音频采集前注册 AEC 插件。若在采集前注册，后续采集会移除浏览器采集参数中的 echoCancellation；若在采集开始后再注册，则当前采集链路无法移除该属性，SDK 会通过控制台告警和埋点提示业务方。
- 与旧版本 SDK 混用时，无法保证 AEC 对 echoCancellation 的移除行为。
- 如果需要兼容更早版本，业务侧需要在确认已订阅远端音频后，通过 getRemoteStreamTrack 获取 MediaStreamTrack 并手动传入插件，例如：
- import VERTC, { EngineEventsTypes, MediaType, StreamIndex } from '@volcengine/rtc';engine.on(EngineEventsTypes.onUserPublishStream, ({ userId, mediaType }) => {if (!(mediaType & MediaType.AUDIO)) {return;}const track = engine.getRemoteStreamTrack(userId, StreamIndex.STREAM_INDEX_MAIN, 'audio');aecExtension.addReferenceTrack(track);});
AECProfile
档位 | 取值 | 说明 |
AUTO | 'auto' | 自动场景。详细配置由 SDK 的 AEC_AUTO_CONFIG 参数控制。 |
AI | 'AI' | AI 场景。 |
BROADCASTER | 'broadcaster' | 主播场景。 |
常用接口
- enable(constraint?)：开启回声消除。
- disable(constraint?)：关闭回声消除。
- isSupported()：检查当前浏览器是否支持插件。
- setProfile(profile)：设置 AEC 档位。
- resume()：插件发生可恢复错误时尝试恢复。
- addReferenceTrack(track)：手动添加一路远端参考音频流。
- removeReferenceTrack(track)：移除一路远端参考音频流。
- clearReferenceTracks()：清空所有远端参考音频流。
自动增益插件
AGC 适用于不同用户麦克风输入音量差异较大，或用户发声距离麦克风远近不稳定的场景。开启后可自动调节采集音量，使音量更平稳。
使用示例
import RTCAGCExtension from '@volcengine/rtc/extension-agc';
import VERTC from '@volcengine/rtc';
// 创建插件实例
const agcExtension = new RTCAGCExtension();
// 检查当前浏览器是否支持 AGC 插件
const isSupported = await agcExtension.isSupported();
const engine = VERTC.createEngine('<YOUR_APP_ID>');
if (isSupported) {
try {
await engine.registerExtension(agcExtension);
} catch (error) {
// 注册失败，详见 error.message
}
}
// 建议在注册插件后开启采集
await engine.startAudioCapture();
关键说明
- 调用 enable() 和 disable() 时，如果不传参数，默认作用于内部采集的主流音频。
- 当前 AGC 插件仅公开支持 AUTO 档位。
- 建议在开始音频采集前注册 AGC 插件。若在采集前注册，后续采集会移除浏览器采集参数中的 autoGainControl；若在采集开始后再注册，则当前采集链路无法移除该属性，SDK 会通过控制台告警和埋点提示业务方。
- 与旧版本 SDK 混用时，无法保证 AGC 对 autoGainControl 的移除行为。
AGCProfile
档位 | 取值 | 说明 |
AUTO | 'auto' | 自动档位。详细配置由 SDK 的 AGC_AUTO_CONFIG 参数控制。 |
常用接口
- enable(constraint?)：开启自动增益控制。
- disable(constraint?)：关闭自动增益控制。
- isSupported()：检查当前浏览器是否支持插件。
- setProfile(profile)：设置 AGC 档位。
- resume()：插件发生可恢复错误时尝试恢复。
事件监听
AEC 和 AGC 都支持以下事件：
- onUnsupported：当前浏览器环境或音频处理链路不支持插件运行。
- onOverload：处理耗时过高，通常表示设备负载较高。
- onError：插件运行时发生错误，可视情况调用 resume() 尝试恢复。
import { EventTypes as AECEventTypes } from '@volcengine/rtc/extension-aec';
import { EventTypes as AGCEventTypes } from '@volcengine/rtc/extension-agc';
aecExtension.on(AECEventTypes.onUnsupported, ({ message }) => {});
aecExtension.on(AECEventTypes.onOverload, ({ elapsedTime }) => {});
aecExtension.on(AECEventTypes.onError, async ({ message }) => {
await aecExtension.resume();
});
agcExtension.on(AGCEventTypes.onUnsupported, ({ message }) => {});
agcExtension.on(AGCEventTypes.onOverload, ({ elapsedTime }) => {});
agcExtension.on(AGCEventTypes.onError, async ({ message }) => {
await agcExtension.resume();
});
最近更新时间：2026.09.04 10:07:24
这个页面对您有帮助吗？
有用
有用
无用
无用