实时音视频
实时音视频
文档指南
请输入
实时音视频
快速入门
场景方案
开发指南
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播放音乐文件（混音）
文档反馈
问问助手如果你需要在通话过程中播放时长较长的音乐文件或PCM 数据（如背景音乐、伴奏）并将其推送给房间内的其他成员，可使用音乐播放类接口。同一时间，只能播放 4 个音乐文件。
说明
实现方式
参考以下顺序，调用 API 实现此功能：
调用目标 | 非 PCM 音频文件 | PCM 音频文件 |
调用目标 | 非 PCM 音频文件 | PCM 音频文件 |
初始化 | getMediaPlayer | getMediaPlayer |
设置回调句柄 | setEventHandler | setEventHandler |
启动 | open | openWithCustomSource |
开始播放 | start | pushExternalAudioFrame |
结束 | stop | stop |
创建引擎
创建音视频引擎类后，你可以通过调用 getMediaPlayer，传入播放器 ID 创建一个音乐播放器类。
Java
Swift
CPP
// 创建引擎
EngineConfig config = new EngineConfig();
config.appID = appId;
config.context = applicationContext;
rtcVideo = RTCEngine.createRTCEngine(config, rtcVideoEventHandler);
// 开启本地音频采集
rtcVideo.startAudioCapture();
//播放非 PCM 文件
mediaPlayer = rtcVideo.getMediaPlayer(PLAYER_ID);
// 创建引擎
let engineCfg = ByteRTCEngineConfig.init()
engineCfg.appID = appId
engineCfg.parameters = [:]
self.rtcVideo = ByteRTCEngine.createRTCEngine(engineCfg, delegate: self)
// 开启本地音频采集
self.rtcVideo?.startAudioCapture()
//播放非 PCM 文件
self.mediaPlayer = self.rtcVideo?.getMediaPlayer(audioPlayerId)
// 创建引擎
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();
//播放非 PCM 文件
player_audio = m_video->getMediaPlayer(id1);
设置回调
你可以通过回调感知音乐的播放状态和播放位置。
Java
Swift
CPP
// handler 建议使用强引用
mediaPlayer.setEventHandler(playerEventHandler);
// 注意使用弱引用
weak var weakSelf = self
self.mediaPlayer?.setEventHandler(weakSelf)
// 设置播放进度回调间隔，以每 1s 回调一次为例
self.mediaPlayer?.setProgressInterval(1000)
func onMediaPlayerStateChanged(_ playerId: Int32, state: ByteRTCPlayerState, error: ByteRTCPlayerError) {
//播放状态回调
}
func onMediaPlayerPlayingProgress(_ playerId: Int32, progress: Int64) {
//播放进度回调
}
m_player_audio->setEventHandler(m_handler.get());
class EventHandler : public bytertc::IMediaPlayerEventHandler {
virtual void onMediaPlayerStateChanged(int playerId, bytertc::PlayerState state, bytertc::PlayerError error){
//播放状态回调
}
virtual void onMediaPlayerPlayingProgress(int playerId, int64_t progress){
//播放进度回调
}
};
// setProgressInterval 设置播放间隔，该接口需在播放状态中调用
播放非 PCM 文件（mp3/aac 等）
对同一个音频文件进行操作时，混音 ID 应保持一致。
打开音乐文件
Java
Swift
CPP
private void openMedia(String filePath) {
MediaPlayerConfig playerConfig = new MediaPlayerConfig();
playerConfig.startPos = 0;
// autoPlay=true时自动播放，无需再调用 start 接口
// autoPlay=false时，不自动播放，需要调用 start 接口
playerConfig.autoPlay = false;
playerConfig.playCount = 1; // 播放次数
playerConfig.type = AudioMixingType.AUDIO_MIXING_TYPE_PLAYOUT_AND_PUBLISH;
playerConfig.callbackOnProgressInterval = 500;
mediaPlayer.open(filePath, playerConfig);
}
let config = ByteRTCMediaPlayerConfig.init()
config.type = .playoutAndPublish
config.playCount = 1 // 播放次数
// autoPlay=true时自动播放，无需再调用 start 接口
// autoPlay=false时，不自动播放，需要调用 start 接口
config.autoPlay = true
self.mediaPlayer?.open(filePath, config: config)
bytertc::MediaPlayerConfig config;
// auto_play=true 时自动播放，无需再调用 start 接口，
// auto_play=false 时，不自动播放，需要调用 start 接口
config.auto_play = true;
config.callback_on_progress_interval = 500;
config.play_count = 1;
config.start_pos = 0;
config.sync_progress_to_record_frame = true;
config.type = bytertc::kAudioMixingTypePlayoutAndPublish;
int ret = player_audio->open(url, config);
手动播放
已经调用 open，且 auto_play = false 时，需要调用 start 播放音乐。
Java
Swift
CPP
mediaPlayer.start();
self.mediaPlayer?.start();
int ret = player_audio->start();
停止播放
如果你需要在播放中主动终止播放，可以调用 stop 方法。
Java
Swift
CPP
mediaPlayer.stop();
self.mediaPlayer?.stop();
int ret = player_audio->stop();
暂停/恢复音乐
Java
Swift
CPP
mediaPlayer.pause();
mediaPlayer.resume();
self.mediaPlayer?.pause();
self.mediaPlayer?.resume();
int ret = player_audio->pause();
int ret = player_audio->resume();
获取和设置音乐属性
所有的混音相关设置都必须在开始播放以后，停止播放之前进行，否则不生效，包括但不限于设置播放起始位置等。
Java
Swift
CPP
// 获取音量
float volume = mediaPlayer.getVolume();
// 设置音量
mediaPlayer.setVolume(volume, AudioMixingType.AUDIO_MIXING_TYPE_PLAYOUT_AND_PUBLISH);
// 文件总时长，单位 ms
int totalTime = mediaPlayer.getTotalDuration();
// 播放时长，单位 ms
int playbackDuration = mediaPlayer.getPlaybackDuration();
// 播放位置，单位 ms
int currentPosition = mediaPlayer.getPosition();
// 设置起播位置，单位 ms
mediaPlayer.setPosition(position);
// 音轨
int trackCount = mediaPlayer.getAudioTrackCount();
// 选择播放指定的音轨音乐
mediaPlayer.selectAudioTrack(trackIndex);
// 播放速度，单位：%，取值范围为[50, 200]，默认值为100
mediaPlayer.setPlaybackSpeed(speed);
// 获取音量
self.mediaPlayer?.getVolume(.playoutAndPublish)
// 设置音量
self.mediaPlayer?.setVolume(volume, type: .playoutAndPublish)
//文件总时长,单位 ms
let totalTime = self.mediaPlayer?.getTotalDuration()
// 播放时长,单位 ms
self.mediaPlayer?.getPlaybackDuration()
// 播放位置，单位 ms
self.mediaPlayer?.getPosition()
// 设置起播位置，单位 ms
self.mediaPlayer?.setPosition(position)
// 变调,取值范围 [-12, 12]
self.mediaPlayer?.setAudioPitch(pitch)
// 声道模式
self.mediaPlayer?.setAudioDualMonoMode(mode)
// 音轨
let tracks = self.mediaPlayer?.getAudioTrackCount()
//选择播放指定的音轨音乐
self.mediaPlayer?.selectAudioTrack(trackIndex)
// 播放速度，单位：%，取值范围为[50, 200]，默认值为100
self.mediaPlayer?.setPlaybackSpeed(speed)
// 获取音量
int volume = player_audio->getVolume(type);
// 设置音量
int ret = player_audio->setVolume(vol);
//文件总时长，单位 ms
int length = player_audio->getTotalDuration();
// 播放时长，单位 ms
int playback_length = player_audio->getPlaybackDuration();
// 播放位置，单位 ms
int pos = player_audio->getPosition();
// 设置起播位置，单位ms
int ret = player_audio->setPosition(pos);
// 变调，取值范围 [-12, 12]
int ret = player_audio->setAudioPitch(pitch);
// 声道模式
int ret = player_audio->setAudioDualMonoMode(mode);
//获取音轨数
int count = player_audio->getAudioTrackCount();
//选择播放指定的音轨音乐
int ret = player_audio->selectAudioTrack(index);
// 播放速度，单位：%，取值范围为 [50,200]，默认值为 100
int ret = player_audio->setPlaybackSpeed(speed);
播放 PCM 文件
启动混音
在调用 openWithCustomSource 启动混音前，可以进行初始化设置，包括是否自动播放、播放次数等。
Java
Swift
CPP
private void startPlayPCM() {
openFile(pcmPath);
MediaPlayerCustomSource source = new MediaPlayerCustomSource();
source.mode = MediaPlayerCustomSourceMode.PUSH;
source.type = MediaPlayerCustomSourceStreamType.RAW;
source.provider = null;
MediaPlayerConfig playerConfig = new MediaPlayerConfig();
playerConfig.startPos = 0;
// autoPlay=true时自动播放，无需再调用 start 接口
// autoPlay=false时，不自动播放，需要调用 start 接口
playerConfig.autoPlay = true;
playerConfig.playCount = 1;
playerConfig.type = AudioMixingType.AUDIO_MIXING_TYPE_PLAYOUT_AND_PUBLISH;
playerConfig.callbackOnProgressInterval = 500;
pcmPlayer.openWithCustomSource(source, playerConfig);
startPushPCM();
}
@objc func startPcmMix() {
let source = ByteRTCMediaPlayerCustomSource.init()
source.mode = .push
source.type = .raw
let config = ByteRTCMediaPlayerConfig.init()
config.type = .playoutAndPublish
config.playCount = 1
// autoPlay=true时自动播放，无需再调用 start 接口
// autoPlay=false时，不自动播放，需要调用 start 接口
config.autoPlay = true
self.mediaPlayerPCM?.open(with: source, config: config)
};
bytertc::MediaPlayerCustomSource source;
source.mode = bytertc::kMediaPlayerCustomSourceModePush;
source.provider = nullptr;
source.type = bytertc::kMediaPlayerCustomSourceStreamTypeRaw;
bytertc::MediaPlayerConfig config;
// auto_play=true时自动播放，无需再调用 start 接口
// auto_play=false时，不自动播放，需要调用 start 接口
config.auto_play = true;
config.callback_on_progress_interval = 1000;
config.play_count = 1;
config.start_pos = 0;
config.sync_progress_to_record_frame = true;
config.type = bytertc::kAudioMixingTypePlayoutAndPublish;
int ret = player->openWithCustomSource(source, config);
推送音频数据
调用 pushExternalAudioFrame 向 RTC 推送音频数据前，你需要按照 RTC SDK 要求对数据进行处理。以下代码片段以示例项目中提供的 PCM 音频文件为例，说明数据的格式要求。
Java
Swift
CPP
Runnable pushAudioFrameTask = new Runnable() {
@Override
public void run() {
// 每10ms的数据大小
int size = 16 * 10;
if (isFirstPush) {
// 建议第一次时传入 200ms 的缓冲数据，避免噪音
size = size * 20;
isFirstPush = false;
}
ByteBuffer pushBuffer = ByteBuffer.allocate(size * 2);
AudioFrame audioFrame = new AudioFrame();
audioFrame.channel = AudioChannel.AUDIO_CHANNEL_MONO;
audioFrame.sampleRate = AudioSampleRate.AUDIO_SAMPLE_RATE_16000;
audioFrame.samples = size;
int nRead = 0;
if (fileData != null) {
nRead = Integer.min(size * 2, fileDataBufferSize - fileDataOffset);
pushBuffer.put(fileData, fileDataOffset, nRead);
fileDataOffset += nRead;
}
Log.i(TAG, "offset:" + fileDataOffset + " read:" + nRead);
if (nRead == 0) {
stopPlayPCM();
return;
}
audioFrame.buffer = pushBuffer.array();
pcmPlayer.pushExternalAudioFrame(audioFrame);
}
};
func pushPCMData() {
if let mediaPlayerPCM = self.mediaPlayerPCM {
var size = 160 * 1 * 2 // 每 10ms 的数据 = 采样数 * 声道数 * 采样占字节数,该pcm文件是16000采样率，单声道，每个样本占2个字节
if self.firstPush {
size = size * 20 // 第一次建议推送 200ms 数据，避免噪音
self.firstPush = false
}
// 本地文件
let filePath = Bundle.main.path(forResource: "pcmFileName", ofType: "pcm")!
let url = URL(fileURLWithPath: filePath)
guard let fileData = try? Data(contentsOf: url) else {
print("Failed to read PCM file data.")
return
}
var endOffset = self.startOffset + size
// 如果偏移量超过文件长度，重置为 0，表示继续播放
if endOffset >= fileData.count {
self.startOffset = 0
endOffset = self.startOffset + size
}
let audioData: Data = fileData.subdata(in: startOffset..<endOffset)
self.startOffset = endOffset
let audioFrame = ByteRTCAudioFrame()
audioFrame.channel = .mono
audioFrame.sampleRate = .rate16000
audioFrame.samples = Int32(size) / 2 // 每个采样占2字节
audioFrame.buffer = audioData
mediaPlayerPCM.pushExternalAudioFrame(audioFrame)
}
}
m_pcm_file = new QFile(name);
m_pcm_file->seek(0); // pcm 音频文件 seek 到初始位置
m_timer.start(10); //开启定时器
connect(m_timer, &QTimer::timeout, [](){
// 每 10ms 的数据大小 = 采样数*声道数*每个采样占字节数，该 pcm 文件是 16000 采样率，单声道，每个样本占 2个字节
int size = 160 * 1 * 2;
if (m_first_push) {
size = 20 * size; // 建议第一次时传入200ms的缓冲数据，避免噪音
m_first_push = false;
}
if (m_pcm_file) {
QByteArray data = m_pcm_file->read(size);
if (data.size() == 0) {
return;
}
bytertc::AudioFrameBuilder builder;
builder.channel = bytertc::kAudioChannelMono;//根据 PCM 文件的声道数指定
builder.sample_rate = bytertc::kAudioSampleRate16000; //根据 PCM 文件的采样率指定
builder.data = (uint8_t*)data.data();
builder.data_size = size;
auto frame = bytertc::buildAudioFrame(builder);
int ret = player_pcm->pushExternalAudioFrame(frame);
}});
结束混音
如果你需要在播放中主动终止播放，可以调用 stop 方法。
Java
Swift
CPP
pcmPlayer.stop();
@objc func stopPcmMix() {
self.mediaPlayerPCM?.stop()
self.timer?.cancel()
}
int ret = player_pcm->stop();
m_timer.stop();
调整混音音量
音量设置必须在开始播放以后，停止播放之前进行，否则不生效。
通过 setVolume 接口逐个指定混音音量。
Java
Swift
CPP
pcmPlayer.setVolume(volume, AudioMixingType.AUDIO_MIXING_TYPE_PLAYOUT_AND_PUBLISH);
self.mediaPlayer?.setVolume(volume, type: .playoutAndPublish)
int ret = player_pcm->setVolume(volume, type);
示例项目
- 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 |
初始化音乐管理类 | getMediaPlayer | |||||||
音乐混音管理类 | RTCMediaPlayer | |||||||
音乐播放器状态回调 | onMediaPlayerStateChanged | 无 | ||||||
音乐播放进度回调 | onMediaPlayerPlayingProgress | 无 |
变更日志
- SDK 3.54：Native 平台废弃原有的混音类，分为音效混音和音乐混音，支持分别控制。
- SDK 3.52：支持混音播放 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:24
这个页面对您有帮助吗？
有用
有用
无用
无用