文档概览/
Feedback

背景音乐 / 音频混流

功能描述

本文将介绍如何使用 AudioPlayer 插件在通话过程中实现背景音乐功能。AudioPlayer 插件支持播放 mp3、ogg、wav、flac 格式的音频文件，并可将音频混入发布流推送给远端用户。
相比 AudioMixer 插件，AudioPlayer 插件提供了播放器实例化的控制方式，支持更灵活的播放控制（start/pause/resume/stop/seek）和属性动态修改。

体验在线 Demo



前提条件

TRTC 版本 > 5.18.0
支持在通话中添加背景音乐的平台如下
操作系统
浏览器类型
浏览器最低版本要求
Mac OS
桌面版 Chrome 浏览器
56+
Mac OS
桌面版 Safari 浏览器
11+
Mac OS
桌面版 Firefox 浏览器
56+
Mac OS
桌面版 Edge
80+
Windows
桌面版 Chrome 浏览器
56+
Windows
桌面版 QQ 浏览器（极速模式）
10.4+
Windows
桌面版 Firefox 浏览器
56+
Windows
桌面版 Edge
80+
iOS
移动版 Safari 浏览器
14+
iOS
微信内嵌网页
✖
Android
移动版 Chrome 浏览器
81+
Android
微信内嵌网页(TBS 内核)
✔
Android
移动版 QQ 浏览器
✖

实现流程

1. 安装与注册插件

import TRTC from 'trtc-sdk-v5';
import AudioPlayer from 'trtc-sdk-v5/plugins/audio-player';

const trtc = TRTC.create({ plugins: [AudioPlayer] });

2. 进房并打开麦克风

await trtc.enterRoom({ roomId: 8888, sdkAppId, userId, userSig });
await trtc.startLocalAudio();

3. 创建播放器并播放背景音乐

使用 trtc.startPlugin 创建一个 URL 播放器实例，设置 publish: true 将音频混入发布流推送给远端用户。
const player = await trtc.startPlugin('AudioPlayer', {
  id: 'bgm',
  sourceType: 'url',
  url: 'https://example.com/music.mp3',
  loop: true,
  volume: 0.5,
  publish: true,
  onTimeUpdate: (currentTime, duration) => {
    console.log(`播放进度: ${currentTime.toFixed(2)}s / ${duration.toFixed(2)}s`);
  },
  onDurationChange: (duration) => {
    console.log(`音频时长: ${duration.toFixed(2)}s`);
  },
  onEnded: () => {
    console.log('播放结束');
  },
});

// 开始播放
await player.start();

4. 控制播放器

通过播放器实例方法进行播放控制：
// 暂停播放
player.pause();

// 恢复播放
player.resume();

// 跳转到指定时间（秒）
player.seek(30);

// 停止播放（重置到起始位置）
player.stop();

// 重新播放
await player.start();
通过实例属性动态修改参数：
// 调整音量（0~1）
player.volume = 0.8;

// 切换循环播放
player.loop = false;

// 调整播放速率
player.playbackRate = 1.5;

// 动态切换是否推送给远端
player.publish = false;

5. 销毁播放器

不再需要播放器时，调用 stopPlugin 销毁：
// 销毁指定播放器
await trtc.stopPlugin('AudioPlayer', { id: 'bgm' });
player = null; // 主动解除引用，避免内存泄漏

// 销毁所有播放器
await trtc.stopPlugin('AudioPlayer', { id: '*' });
注意：
调用 stopPlugin 销毁播放器后，务必将播放器实例引用设为 null，否则实例对象无法被垃圾回收，会造成内存泄漏。

API 说明

trtc.startPlugin('AudioPlayer', options)

创建一个音频播放器实例。

参数说明

参数
类型
必填
默认值
说明
id
string
是
-
播放器实例唯一标识。
sourceType
string
是
-
音频源类型，设置为 url。
url
string
是
-
音频文件 URL，支持 mp3/ogg/wav/flac 格式及 blob/data URL。
publish
boolean
否
false
是否混入发布流推送给远端用户。
loop
boolean
否
false
是否循环播放。
volume
number
否
1
播放音量（0~1）。
playbackRate
number
否
1
播放速率。
onTimeUpdate
function
否
-
播放进度回调，参数为 (currentTime: number, duration: number)，单位为秒。
onDurationChange
function
否
-
音频时长变化回调，参数为 (duration: number)，单位为秒。
onEnded
function
否
-
播放结束回调（loop 模式下每次播放到末尾不会触发）。
返回值： Promise<AudioPlayerContext> — 播放器实例
示例：
const player = await trtc.startPlugin('AudioPlayer', {
  id: 'bgm',
  sourceType: 'url',
  url: 'https://example.com/music.mp3',
  loop: true,
  volume: 0.5,
  playbackRate: 1.0,
  publish: true,
  onTimeUpdate: (currentTime, duration) => {
    console.log(`${currentTime}s / ${duration}s`);
  },
  onDurationChange: (duration) => {
    console.log(`音频时长: ${duration}s`);
  },
  onEnded: () => {
    console.log('播放结束');
  },
});

播放器实例方法

方法
说明
start()
开始播放，返回 Promise。
pause()
暂停播放。
resume()
从暂停位置恢复播放。
stop()
停止播放，重置到起始位置。
seek(time)
跳转到指定时间（秒）。

播放器实例只读属性

属性
类型
说明
id
string
播放器实例 ID。
sourceType
string
音频源类型。
currentTime
number
当前播放时间（秒）。
duration
number
音频总时长（秒）。
isStop
boolean
是否已停止。
isPause
boolean
是否已暂停。
isPlayEnd
boolean
是否播放结束。

播放器实例可读写属性

属性
类型
说明
volume
number
播放音量（0~1）。
loop
boolean
是否循环播放。
playbackRate
number
播放速率。
publish
boolean
是否混入发布流。

trtc.stopPlugin('AudioPlayer', options)

销毁播放器实例。

参数说明

参数
类型
说明
id
string
目标播放器实例 ID，传 * 销毁所有实例。
示例：
// 销毁指定播放器
await trtc.stopPlugin('AudioPlayer', { id: 'bgm' });

// 销毁所有播放器
await trtc.stopPlugin('AudioPlayer', { id: '*' });

// 释放播放器引用
player = null;
注意：
调用 stopPlugin 销毁播放器后，务必将播放器实例引用设为 null，否则实例对象无法被垃圾回收，会造成内存泄漏。

常见问题

出现跨域错误

例如：Access to audio at XXX from origin XXX has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.
解决：您需要配置线上音乐文件的 CORS 协议，确保音频资源服务器允许跨域访问。

音频格式不支持

例如：NotSupportedError: The operation is not supported.
解决：请使用浏览器支持的音频格式（推荐 mp3、ogg、wav、flac）。

publish 设置为 true 但远端听不到

解决：使用 publish: true 时，需要先进入房间并发布音频流（调用 trtc.startLocalAudio()），确保本地音频已发布后再创建播放器。

iOS 设备无法播放

解决：iOS 浏览器要求音频播放必须由用户手势触发，请确保 player.start() 在用户点击事件的回调中调用。

如何同时播放多个背景音乐

AudioPlayer 支持多实例管理，通过不同的 id 创建多个播放器即可：
const bgm1 = await trtc.startPlugin('AudioPlayer', {
  id: 'bgm1',
  sourceType: 'url',
  url: 'https://example.com/music1.mp3',
  publish: true,
});

const bgm2 = await trtc.startPlugin('AudioPlayer', {
  id: 'bgm2',
  sourceType: 'url',
  url: 'https://example.com/music2.mp3',
  publish: true,
});

await bgm1.start();
await bgm2.start();