实时音视频
实时音视频
文档指南
请输入
实时音视频
快速入门
场景方案
开发指南
Token 鉴权
音频管理
视频管理
屏幕共享
SDK 升级指南
客户端 API 参考
服务端 API 参考
房间管理
转推直播
输入在线媒体流
WTN 流（原公共流）
实时数据监控
历史数据查询
业务标识管理
实时消息通信
历史版本（文档停止维护）
2023-08-01
2023-06-01
转推直播
2022-06-01
2020-12-01
转推直播
输入在线媒体流
获取数据指标
常见问题
集成相关
质量相关
AI 音视频互动方案
开发指南
配置 ASR/LLM/TTS 服务
API 参考
硬件对话智能体
用户指南
服务端 API
智能体
实时信令
互动白板
客户端 API 参考
服务端 API 参考
- 文档首页
实时音视频实时音视频开发指南音频管理播放音效文件
复制全文
下载 pdf播放音效文件
文档反馈
问问助手在游戏等互动娱乐场景中，播放音效（如掌声、欢呼、口哨等）可以烘托气氛、增添娱乐效果。RTC SDK 提供了音效接口，支持同时播放多个音效并实现叠加效果。
说明
实现方式
步骤 1：创建引擎
创建音视频引擎类后，你可以创建一个音效播放器类。
Java
Swift
CPP
EngineConfig engineConfig = new EngineConfig();
engineConfig.context = this;
engineConfig.appID = APP_ID;
rtcVideo = RTCEngine.createRTCEngine(engineConfig, videoEventHandler);
rtcVideo.startAudioCapture();
// 创建播放器
effectPlayer = rtcVideo.getAudioEffectPlayer();
let engineCfg = ByteRTCEngineConfig.init()
engineCfg.appID = kAppID
engineCfg.parameters = [:]
self.rtcVideo = ByteRTCEngine.createRTCEngine(engineCfg, delegate: self)
self.rtcVideo?.startAudioCapture()
// 创建播放器
self.effectPlayer = self.rtcVideo?.getAudioEffectPlayer()
m_handler.reset(new ByteRTCEventHandler());
bytertc::EngineConfig conf;
conf.app_id = g_appid.c_str();
m_video = bytertc::IRTCEngine::createRTCEngine(conf, m_handler.get());
m_video->startAudioCapture();
// 创建播放器
m_player = m_video->getAudioEffectPlayer();
m_player->setEventHandler(m_handler.get());
步骤 2：设置回调
调用 setEventHandler 后会收到播放音效的状态回调。
Java
Swift
CPP
effectPlayer.setEventHandler(effectPlayerEventHandler);
weak var weakSelf = self
self.effectPlayer?.setEventHandler(weakSelf)
m_player->setEventHandler(m_handler.get());
void Handler::onAudioEffectPlayerStateChanged(int effect_id, bytertc::PlayerState state, bytertc::PlayerError error){
//effect_id 为音效的 ID
//state 为音效的播放状态
//error 为错误码
}
步骤 3：预加载本地音效文件
推荐使用 preload 进行预加载，在需要多次播放同一个本地音效时，避免内存多次申请、释放。
如果不再需要播放后，可以调用 unload 清理内存空间。
不支持加载在线 URL 音频文件。
Java
Swift
CPP
effectPlayer.preload(EFFECT_ID, effectFilePath)
self.effectPlayer?.preload(effectId, filePath: filePath)
int ret = m_player->preload(id, "path");
步骤 4：开始播放音效
多次调用 start，分别传入不同的混音 ID 和 filepath 可以实现同时播放多个音效文件，达到音效叠加效果。如果已预加载文件，确保播放时传入的混音 ID 与预加载时的一致。
Java
Swift
CPP
private void startEffect(int effectId, String path) {
AudioEffectPlayerConfig playerConfig = new AudioEffectPlayerConfig();
playerConfig.type = AudioMixingType.AUDIO_MIXING_TYPE_PLAYOUT_AND_PUBLISH;
playerConfig.startPos = 0;
playerConfig.playCount = 1; // 重复播放次数
playerConfig.pitch = 0;
effectPlayer.start(effectId, path, playerConfig);
}
let filePath = Bundle.main.path(forResource: "rtc_test", ofType: "aac")
let config = ByteRTCAudioEffectPlayerConfig.init()
config.type = .playoutAndPublish
config.playCount = 1 // 重复播放次数
let code = self.effectPlayer?.start(effectId, filePath: filePath, config: config)
print("start play effect code = \\(code!)")
bytertc::AudioEffectPlayerConfig config;
config.pitch = 0;
config.play_count = 1; // 重复播放次数
config.start_pos = 0;
config.type = static_cast<bytertc::AudioMixingType>(type);
int ret = m_player->start(id, "path1", config);
步骤 5（可选）：调节音量或播放位置
所有的混音相关设置（如音量、播放位置等）必须在开始播放以后，停止播放之前进行，否则不生效。
说明
- 只有移动端有 setVolumeAll 接口，可以调节全部混音音量，PC 端只能通过 setVolume 接口调节指定混音音量。
- 对同一个音频文件进行操作时，请确保混音 ID 保持一致。
Java
Swift
CPP
effectPlayer.setPosition(EFFECT_ID, position);
//获取播放位置
int pos = effectPlayer.getPosition(EFFECT_ID);
//获取音效时长
effectPlayer.getDuration(EFFECT_ID);
//设置单个音效音量，音量取值范围 [0,400]
effectPlayer.setVolume(EFFECT_ID, volume);
//设置所有音效音量，音量取值范围 [0,400]
effectPlayer.setVolumeAll(volume);
//获取单个音效音量
int volume = effectPlayer.getVolume(EFFECT_ID);
//设置播放位置
self.effectPlayer?.setPosition(effectId, position: position);
//获取播放位置
let position = self.effectPlayer?.getPosition(effectId);
//获取音效时长
let totalTime = self.effectPlayer?.getDuration(effectId);
//设置单个音效音量，音量取值范围 [0,400]
self.effectPlayer?.setVolume(effectId, volume: volume);
//设置所有音效音量，音量取值范围 [0,400]
let volume = self.effectPlayer?.setVolumeAll(volume);
//获取单个音效音量
let volume = self.effectPlayer?.getVolume(effectId);
//设置播放位置
int ret = m_player->setPosition(id, position);
//获取播放位置
int ret = m_player->getPosition(id);
//获取音效时长
int ret = m_player->getDuration(id);
//设置单个音效音量，音量取值范围 [0,400]
int ret= m_player->setVolume(id, volume);
//设置所有音效音量，音量取值范围 [0,400]
int ret = m_player->setVolumeAll(volume);
//获取单个音效音量
int ret = m_player->getVolume(id);
步骤 6：管理播放状态
你可以根据业务需求，随时调用以下方法对音效进行停止、暂停或恢复操作：
停止播放音效
Java
Swift
CPP
//停止播放单个音效
effectPlayer.stop(EFFECT_ID);
//停止播放所有音效
effectPlayer.stopAll();
//停止播放单个音效
self.effectPlayer?.stop(effectId);
//停止播放所有音效
self.effectPlayer?.stopAll();
//停止播放单个音效
int ret = m_player->stop(id);
//停止播放所有音效
ret = m_player->stopAll();
暂停/恢复播放音效
Java
Swift
CPP
//暂停播放单个音效
effectPlayer.pause(EFFECT_ID);
//暂停播放所有音效
effectPlayer.pauseAll();
//恢复单个音效
effectPlayer.resume(EFFECT_ID);
//恢复所有音效
effectPlayer.resumeAll();
//暂停播放单个音效
self.effectPlayer?.pause(effectId);
//暂停播放所有音效
self.effectPlayer?.pauseAll() ;
//恢复单个音效
self.effectPlayer?.resume(effectId) ;
//恢复所有音效
self.effectPlayer?.resumeAll() ;
//暂停播放单个音效
int ret = m_player->pause(id);
//暂停播放所有音效
int ret = m_player->pauseAll();
//恢复单个音效
int ret = m_player->resume(id);
//恢复所有音效
int ret = m_player->resumeAll();
示例项目
- iOS
- PC
相关 API
表格中的 macOS API 接口为 Objective-C，而示例项目中的 macOS 项目使用的是 Windows SDK 中的 API 接口。
平台 | Android | iOS | macOS | Windows | Linux | Electron | Flutter | Web |
平台 | Android | iOS | macOS | Windows | Linux | Electron | Flutter | Web |
初始化音效管理类 | getAudioEffectPlayer | |||||||
音效混音管理类 | RTCAudioEffectPlayer | |||||||
音效播放器回调 | onAudioEffectPlayerStateChanged | |
功能变更日志
- SDK 3.54：支持混音播放 24kHz 的 mp3 文件。3.52 之前版本仅支持以下采样率的音频文件：8kHz、16kHz、22.05kHz、32kHz、44.1kHz、48kHz、64kHz、96kHz、192kHz。
- SDK 3.45.4：支持获取混音音频文件的实际播放时长，即歌曲不受停止、跳转、倍速、卡顿影响的播放时长。
- SDK 3.38：支持调整音视频通话中使用的音频文件的播放速度。
- SDK 3.36：全平台支持在线音频文件混音。
- SDK 3.32：支持设置音频文件的声道。
最近更新时间：2026.10.15 14:32:25
这个页面对您有帮助吗？
有用
有用
无用
无用