文档概览/
Live/
SDK/
iOS/
API Usage Guide/
Advanced Features/
Background Music/

Background Music

本文档主要介绍如何使用 RTC Room Engine SDK 实现背景音乐相关功能。

前提条件

在使用RTC Room Engine SDK 提供的背景音乐设置相关功能之前，您需要先 登录 SDK。

使用指引

开始/停止播放背景音乐

iOS
Android
您可以分别通过调用startPlayMusic和stopPlayMusic两个接口，来开始或停止播放背景音乐。
在调用startPlayMusic开始播放背景音乐时，需要传入一个TXAudioMusicParam类型的参数来设置播放控制信息。TXAudioMusicParam包含以下信息，您可以分别对其进行设置：
枚举类型
描述
id
字段含义：音乐 ID。
特殊说明：SDK 允许播放多路音乐，因此需要使用 ID 进行标记，用于控制音乐的开始、停止、音量等。
endTimeMS
字段含义：音乐结束播放时间点，单位毫秒，0表示播放至文件结尾。
isShortFile
字段含义：播放的是否为短音乐文件。
推荐取值：
YES：需要重复播放的短音乐文件。
NO：正常的音乐文件。默认值：NO。
loopCount
字段含义：音乐循环播放的次数。
推荐取值：取值范围为0 - 任意正整数，默认值：0。0 表示播放音乐一次；1 表示播放音乐两次；以此类推。
path
字段含义：音效文件的完整路径或 URL 地址。支持的音频格式包括 MP3、AAC、M4A、WAV。
publish
字段含义：是否将音乐传到远端。
推荐取值：
YES：音乐在本地播放的同时，远端用户也能听到该音乐。
NO：主播只能在本地听到该音乐，远端观众听不到。默认值：NO。
startTimeMS
字段含义：音乐开始播放时间点，单位：毫秒
您可以分别通过调用startPlayMusic和stopPlayMusic两个接口，来开始或停止播放背景音乐。
在调用startPlayMusic开始播放背景音乐时，需要传入一个AudioMusicParam类型的参数来设置播放控制信息。AudioMusicParam包含以下信息，您可以分别对其进行设置：
枚举类型
描述
id
字段含义：音乐 ID。
特殊说明：SDK 允许播放多路音乐，因此需要使用 ID 进行标记，用于控制音乐的开始、停止、音量等。
endTimeMS
字段含义：音乐结束播放时间点，单位毫秒，0表示播放至文件结尾。
isShortFile
字段含义：播放的是否为短音乐文件。
推荐取值：
YES：需要重复播放的短音乐文件。
NO：正常的音乐文件。默认值：NO。
loopCount
字段含义：音乐循环播放的次数。
推荐取值：取值范围为0 - 任意正整数，默认值：0。0 表示播放音乐一次；1 表示播放音乐两次；以此类推。
path
字段含义：音效文件的完整路径或 URL 地址。支持的音频格式包括 MP3、AAC、M4A、WAV。
publish
字段含义：是否将音乐传到远端。
推荐取值：
YES：音乐在本地播放的同时，远端用户也能听到该音乐。
NO：主播只能在本地听到该音乐，远端观众听不到。默认值：NO。
startTimeMS
字段含义：音乐开始播放时间点，单位：毫秒
以下是一个简单开始/停止播放背景音乐的示例：
iOS
Android
import RTCRoomEngine
import TXLiteAVSDK_Professional

let audioEffectManager = TUIRoomEngine.sharedInstance().getTRTCCloud().getAudioEffectManager()

// 开始播放背景音乐
let musicParam = TXAudioMusicParam()
musicParam.id = 0                    // 替换为您自己的音乐ID
musicParam.path = "path"             // 替换为音乐文件的完整路径或 URL 地址
musicParam.publish = true            // 将音乐传到远端
musicParam.loopCount = 0             // 替换为您需要循环播放的次数
audioEffectManager.startPlayMusic(musicParam) { code in
    if code == 0 {
      // 开始播放成功
    } else {
      // 开始播放失败
    }
} onProgress: { progress, duration in
    // 播放进度回调
} onComplete: { _ in
    // 播放结束回调
}

// 停止播放背景音乐
audioEffectManager.stopPlayMusic(musicId)  // 替换为您需要停止播放的音乐ID

TXAudioEffectManager audioEffectManager = TUIRoomEngine.sharedInstance().getTRTCCloud().getAudioEffectManager();

int id = 0;  // 替换为您自己的音乐ID
String path = "path"; // 替换为音乐文件的完整路径或 URL 地址
// 开始播放背景音乐
TXAudioEffectManager.AudioMusicParam musicParam = new TXAudioEffectManager.AudioMusicParam(id, path);
musicParam.publish = true;            // 将音乐传到远端
musicParam.loopCount = 0;             // 替换为您需要循环播放的次数
audioEffectManager.startPlayMusic(musicParam);

// 停止播放背景音乐
audioEffectManager.stopPlayMusic(id);  // 替换为您需要停止播放的音乐ID

设置背景音乐音量

您可以通过调用setAllMusicVolume接口并传入一个Int值，来设置背景音乐的音量。
传入的Int值代表音量大小，取值范围为0 - 100。以下是一个调用setAllMusicVolume设置背景音乐音量的示例：
iOS
Android
import RTCRoomEngine
import TXLiteAVSDK_Professional

let audioEffectManager = TUIRoomEngine.sharedInstance().getTRTCCloud().getAudioEffectManager()

let volume = 60    // 替换为您需要设置的音量大小
audioEffectManager.setAllMusicVolume(volume)
TXAudioEffectManager audioEffectManager = TUIRoomEngine.sharedInstance().getTRTCCloud().getAudioEffectManager();

int volume = 60;    // 替换为您需要设置的音量大小
audioEffectManager.setAllMusicVolume(volume);