Tutorial: Background Music Implementation

Feature Description

This article describes how to use the AudioPlayer plugin to implement background music functionality during calls. The AudioPlayer plugin supports playing audio files in mp3, ogg, wav, and flac formats, and can mix the audio into the published stream to send to remote users.

Compared to the AudioMixer plugin, the AudioPlayer plugin provides a more flexible player instantiation control method, supporting more flexible playback control (start/pause/resume/stop/seek) and dynamic parameter modification.

Experience Online Demo

Prerequisites

• TRTC version > 5.18.0

• Platforms supporting background music during calls:

  Operating System	Browser Type	Minimum Browser Version
  Mac OS	Desktop Chrome	56+
  Mac OS	Desktop Safari	11+
  Mac OS	Desktop Firefox	56+
  Mac OS	Desktop Edge	80+
  Windows	Desktop Chrome	56+
  Windows	Desktop QQ Browser (Speed Mode)	10.4+
  Windows	Desktop Firefox	56+
  Windows	Desktop Edge	80+
  iOS	Mobile Safari	14+
  iOS	WeChat Embedded Webpage	✖
  Android	Mobile Chrome	81+
  Android	WeChat Embedded Webpage (TBS Kernel)	✔
  Android	Mobile QQ Browser	✖

Implementation Process

1. Install and Register Plugin

import TRTC from 'trtc-sdk-v5';
import AudioPlayer from 'trtc-sdk-v5/plugins/audio-player';
const trtc = TRTC.create({ plugins: [AudioPlayer] });

2. Enter Room and Enable Microphone

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

3. Create Player and Play Background Music

Use trtc.startPlugin to create a URL player instance, set publish: true to mix the audio into the published stream and send to remote users.

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(`Playback progress: ${currentTime.toFixed(2)}s / ${duration.toFixed(2)}s`);
  },
  onDurationChange: (duration) => {
    console.log(`Audio duration: ${duration.toFixed(2)}s`);
  },
  onEnded: () => {
    console.log('Playback ended');
  },
});
// Start playback
await player.start();

4. Control Player

Control playback through player instance methods:

// Pause playback
player.pause();
// Resume playback
player.resume();
// Seek to specified time (seconds)
player.seek(30);
// Stop playback (reset to beginning)
player.stop();
// Restart playback
await player.start();

Dynamically modify parameters through instance properties:

// Adjust volume (0~1)
player.volume = 0.8;
// Toggle loop playback
player.loop = false;
// Adjust playback rate
player.playbackRate = 1.5;
// Dynamically toggle whether to send to remote users
player.publish = false;

5. Destroy Player

When the player is no longer needed, call stopPlugin to destroy it:

// Destroy specific player
await trtc.stopPlugin('AudioPlayer', { id: 'bgm' });
player = null; // Actively release reference to avoid memory leaks
// Destroy all players
await trtc.stopPlugin('AudioPlayer', { id: '*' });

⚠️ Important: After calling stopPlugin to destroy the player, be sure to set the player instance reference to null, otherwise the instance object cannot be garbage collected, causing memory leaks.

API Reference

trtc.startPlugin('AudioPlayer', options)

Create an audio player instance.

options

Return value: Promise<AudioPlayerContext> — Player instance

Example:

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(`Audio duration: ${duration}s`);
  },
  onEnded: () => {
    console.log('Playback ended');
  },
});

Player Instance Methods

Player Instance Read-only Properties

Player Instance Read-write Properties

trtc.stopPlugin('AudioPlayer', options)

Destroy player instance.

options

Example:

// Destroy specific player
await trtc.stopPlugin('AudioPlayer', { id: 'bgm' });
// Destroy all players
await trtc.stopPlugin('AudioPlayer', { id: '*' });
// Release player reference
player = null;

⚠️ Important: After calling stopPlugin to destroy the player, be sure to set the player instance reference to null, otherwise the instance object cannot be garbage collected, causing memory leaks.

Common Issues

1. Cross-origin error occurs

Example: 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.

Solution: You need to configure CORS protocol for online music files, ensuring the audio resource server allows cross-origin access.

2. Audio format not supported

Example: NotSupportedError: The operation is not supported.

Solution: Please use browser-supported audio formats (recommended mp3, ogg, wav, flac).

3. publish set to true but remote users cannot hear

Solution: When using publish: true, you need to enter the room and publish audio stream first (call trtc.startLocalAudio()), ensure local audio is published before creating the player.

4. Cannot play on iOS devices

Solution: iOS browsers require audio playback to be triggered by user gestures, ensure player.start() is called within user click event callbacks.

5. How to play multiple background music simultaneously

AudioPlayer supports multi-instance management, create multiple players with different ids:

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