Tutorial: 背景音乐实现方案

功能描述

本文将介绍如何使用 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)

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

options

返回值： 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('播放结束');
  },
});

播放器实例方法

播放器实例只读属性

播放器实例可读写属性

trtc.stopPlugin('AudioPlayer', options)

销毁播放器实例。

options

示例：

// 销毁指定播放器
await trtc.stopPlugin('AudioPlayer', { id: 'bgm' });
// 销毁所有播放器
await trtc.stopPlugin('AudioPlayer', { id: '*' });
// 释放播放器引用
player = null;

⚠️ 重要：调用 stopPlugin 销毁播放器后，务必将播放器实例引用设为 null，否则实例对象无法被垃圾回收，会造成内存泄漏。

常见问题

1. 出现跨域错误

例如：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 协议，确保音频资源服务器允许跨域访问。

2. 音频格式不支持

例如：NotSupportedError: The operation is not supported.

解决：请使用浏览器支持的音频格式（推荐 mp3、ogg、wav、flac）。

3. publish 设置为 true 但远端听不到

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

4. iOS 设备无法播放

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

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

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();