实时音视频 TXAudioEffectManager

Copyright (c) 2026 Tencent. All rights reserved.
﻿
Module:   TXAudioEffectManager @ TXLiteAVSDK
Function: 背景音乐、短音效和人声特效的相关接口
Version: 13.5
﻿
背景音乐、耳返、人声音效管理接口，Flutter SDK：tencent_rtc_sdk。通过 TRTCCloud 的 getAudioEffectManager() 获取实例后即可调用。
函数列表
人声相关接口
API
描述
﻿enableVoiceEarMonitor﻿
开启耳返。
﻿setVoiceEarMonitorVolume﻿
设置耳返音量。
﻿setVoiceReverbType﻿
设置人声的混响效果。
﻿setVoiceChangerType﻿
设置人声的变声特效。
﻿setVoiceCaptureVolume﻿
设置语音音量。
﻿setVoicePitch﻿
设置语音音调。
背景音乐播放
API
描述
﻿setMusicObserver﻿
设置背景音乐的事件回调。
﻿startPlayMusic﻿
开始播放背景音乐。
﻿stopPlayMusic﻿
停止播放背景音乐。
﻿pausePlayMusic﻿
暂停播放背景音乐。
﻿resumePlayMusic﻿
恢复播放背景音乐。
背景音乐音量、音调与速度
API
描述
﻿setAllMusicVolume﻿
设置所有背景音乐的本地音量和远端音量。
﻿setMusicPublishVolume﻿
设置某一首背景音乐的远端音量。
﻿setMusicPlayoutVolume﻿
设置某一首背景音乐的本地音量。
﻿setMusicPitch﻿
调整背景音乐的音调高低。
﻿setMusicSpeedRate﻿
调整背景音乐的变速效果。
﻿setMusicScratchSpeedRate﻿
调整搓碟的变速效果。
背景音乐进度与音轨
API
描述
﻿getMusicCurrentPosInMS﻿
获取背景音乐的播放进度（单位：毫秒）。
﻿getMusicDurationInMS﻿
获取背景音乐的总时长（单位：毫秒）。
﻿seekMusicToPosInTime﻿
设置背景音乐的播放进度（单位：毫秒）。
﻿getMusicTrackCount﻿
获取背景音乐的音轨数量。
﻿setMusicTrack﻿
指定背景音乐的播放音轨。
背景音乐预加载
API
描述
﻿setPreloadObserver﻿
设置预加载的事件回调。
﻿preloadMusic﻿
预加载背景音乐。
接口详情
以下按函数列表顺序逐一说明各接口的签名、功能、参数、返回值及注意事项。
enableVoiceEarMonitor
void enableVoiceEarMonitor(bool enable)
开启耳返。
主播开启耳返后，可以在耳机里听到麦克风采集到的自己发出的声音，该功能适用于主播唱歌的应用场景中。
由于蓝牙耳机的延迟较高，因此无法为蓝牙耳机开启耳返，请在 UI 上提醒主播使用有线耳机。
由于并非所有手机都能获得良好的耳返效果，因此部分手机上已屏蔽该功能。
参数
类型
描述
enable
bool
true：开启；
false：关闭。
说明：
仅在主播佩戴耳机时才能开启耳返，请在 UI 上提醒主播使用有线耳机。
setVoiceEarMonitorVolume
void setVoiceEarMonitorVolume(int volume)
设置耳返音量。
通过该接口可以设置耳返的音量大小。
参数
类型
描述
volume
int
音量大小，取值范围：0 - 100，默认值：100。
说明：
如果将 volume 设置成 100 之后感觉音量还是太小，可以将 volume 最大设置成 150，但可能会有副作用。
setVoiceReverbType
void setVoiceReverbType(TXVoiceReverbType type)
设置人声的混响效果。
通过该接口可以设置人声的混响效果，具体特效请参见 ​TXVoiceReverbType。
参数
类型
描述
type
﻿TXVoiceReverbType﻿
混响效果类型，详见 ​TXVoiceReverbType。
说明：
设置的效果在退出房间后会自动失效，如果下次进房还需要对应特效，需要调用此接口再次进行设置。
setVoiceChangerType
void setVoiceChangerType(TXVoiceChangerType type)
设置人声的变声特效。
通过该接口可以设置人声的变声特效，具体特效请参见 ​TXVoiceChangerType。
参数
类型
描述
type
﻿TXVoiceChangerType﻿
变声特效类型，详见 ​TXVoiceChangerType。
说明：
设置的效果在退出房间后会自动失效，如果下次进房还需要对应特效，需要调用此接口再次进行设置。
setVoiceCaptureVolume
void setVoiceCaptureVolume(int volume)
设置语音音量。
该接口可以设置语音音量的大小，一般配合音乐音量的设置接口 ​setAllMusicVolume 协同使用，用于平衡语音和音乐的音量。
参数
类型
描述
volume
int
音量大小，取值范围：0 - 100，默认值：100。
说明：
如果将 volume 设置成 100 之后感觉音量还是太小，可以将 volume 最大设置成 150，但可能会有副作用。
setVoicePitch
void setVoicePitch(double pitch)
设置语音音调。
该接口可以设置语音音调。
参数
类型
描述
pitch
double
音调，取值范围：-1.0 - 1.0，默认值：0.0。
setMusicObserver
void setMusicObserver(int musicId, TXMusicPlayObserver? observer)
设置背景音乐的事件回调。
请在播放背景音乐之前使用该接口设置播放事件回调，以便感知背景音乐的播放进度。
参数
类型
描述
musicId
int
音乐 ID。
observer
TXMusicPlayObserver?
背景音乐播放的事件回调，详见 ​TXMusicPlayObserver。
说明：
如果该 ID 不再需要使用，可以将 observer 设置为 null 以彻底释放该回调。
startPlayMusic
void startPlayMusic(AudioMusicParam musicParam)
开始播放背景音乐。
每个音乐都需要您指定具体的 ID，您可以通过该 ID 对音乐的开始、停止、音量等进行设置。
参数
类型
描述
musicParam
﻿AudioMusicParam﻿
音乐参数，详见 ​AudioMusicParam。
说明：
1. 如果要多次播放同一首背景音乐，请不要每次播放都分配一个新的 ID，推荐使用相同的 ID。
2. 若您希望同时播放多首不同的音乐，请为不同的音乐分配不同的 ID 进行播放。
3. 如果使用同一个 ID 播放不同音乐，SDK 会先停止播放旧的音乐，再播放新的音乐。
示例代码
const int musicId = 1;
﻿
audioEffectManager.setMusicObserver(musicId, TXMusicPlayObserver(
  onStart: (int id, int errorCode) {
    debugPrint('music $id start, errorCode: $errorCode');
  },
  onPlayProgress: (int id, int curPtsMS, int durationMS) {
    debugPrint('music $id progress: $curPtsMS / $durationMS');
  },
  onComplete: (int id, int errorCode) {
    debugPrint('music $id complete, errorCode: $errorCode');
  },
));
﻿
audioEffectManager.startPlayMusic(AudioMusicParam(
  id: musicId,
  path: '/path/to/music.mp3',
  publish: true,
));
stopPlayMusic
void stopPlayMusic(int id)
停止播放背景音乐。
参数
类型
描述
id
int
音乐 ID。
pausePlayMusic
void pausePlayMusic(int id)
暂停播放背景音乐。
参数
类型
描述
id
int
音乐 ID。
resumePlayMusic
void resumePlayMusic(int id)
恢复播放背景音乐。
参数
类型
描述
id
int
音乐 ID。
setAllMusicVolume
void setAllMusicVolume(int volume)
设置所有背景音乐的本地音量和远端音量。
该接口可以设置所有背景音乐的本地音量和远端音量。
本地音量：即主播本地可以听到的背景音乐的音量大小。
远端音量：即观众端可以听到的背景音乐的音量大小。
参数
类型
描述
volume
int
音量大小，取值范围：0 - 100，默认值：60。
说明：
如果将 volume 设置成 100 之后感觉音量还是太小，可以将 volume 最大设置成 150，但可能会有副作用。
setMusicPublishVolume
void setMusicPublishVolume(int id, int volume)
设置某一首背景音乐的远端音量。
该接口可以细粒度地控制每一首背景音乐的远端音量，也就是观众端可听到的背景音乐的音量大小。
参数
类型
描述
id
int
音乐 ID。
volume
int
音量大小，取值范围：0 - 100，默认值：60。
说明：
如果将 volume 设置成 100 之后感觉音量还是太小，可以将 volume 最大设置成 150，但可能会有副作用。
setMusicPlayoutVolume
void setMusicPlayoutVolume(int id, int volume)
设置某一首背景音乐的本地音量。
该接口可以细粒度地控制每一首背景音乐的本地音量，也就是主播本地可以听到的背景音乐的音量大小。
参数
类型
描述
id
int
音乐 ID。
volume
int
音量大小，取值范围：0 - 100，默认值：60。
说明：
如果将 volume 设置成 100 之后感觉音量还是太小，可以将 volume 最大设置成 150，但可能会有副作用。
setMusicPitch
void setMusicPitch(int id, double pitch)
调整背景音乐的音调高低。
参数
类型
描述
id
int
音乐 ID。
pitch
double
音调，取值范围：[-1, 1] 之间的浮点数，默认值：0.0。
setMusicSpeedRate
void setMusicSpeedRate(int id, double rate)
调整背景音乐的变速效果。
参数
类型
描述
id
int
音乐 ID。
rate
double
速度，取值范围：[0.5, 2] 之间的浮点数，默认值：1.0。
setMusicScratchSpeedRate
void setMusicScratchSpeedRate(int id, double scratchSpeedRate)
调整搓碟的变速效果。
参数
类型
描述
id
int
音乐 ID。
scratchSpeedRate
double
搓碟速度，取值范围：[-12.0, 12.0] 之间的浮点数，默认值：1.0。
正负值表示方向（正向 / 反向），绝对值表示速度大小。
说明：
前置条件：必须先成功调用 ​preloadMusic 预加载。
getMusicCurrentPosInMS
int getMusicCurrentPosInMS(int id)
获取背景音乐的播放进度（单位：毫秒）。
参数
类型
描述
id
int
音乐 ID。
返回值
成功返回当前播放时间，单位：毫秒；失败返回 -1。
getMusicDurationInMS
int getMusicDurationInMS(String path)
获取背景音乐的总时长（单位：毫秒）。
参数
类型
描述
path
String
音乐文件路径。
返回值
成功返回指定音乐文件的时长，单位：毫秒；失败返回 -1。
seekMusicToPosInTime
void seekMusicToPosInTime(int id, int pts)
设置背景音乐的播放进度（单位：毫秒）。
参数
类型
描述
id
int
音乐 ID。
pts
int
播放进度，单位：毫秒。
说明：
请尽量避免过度频繁地调用该接口，因为该接口可能会再次读写音乐文件，耗时稍高。
因此，当用户拖拽音乐的播放进度条时，请在用户完成拖拽操作后再调用本接口。
因为 UI 上的进度条控件往往会以很高的频率反馈用户的拖拽进度，如不做频率限制，会导致较差的用户体验。
getMusicTrackCount
int getMusicTrackCount(int id)
获取背景音乐的音轨数量。
参数
类型
描述
id
int
音乐 ID。
返回值
指定背景音乐的音轨数量。
setMusicTrack
void setMusicTrack(int id, int trackIndex)
指定背景音乐的播放音轨。
参数
类型
描述
id
int
音乐 ID。
trackIndex
int
指定播放第几个音轨（默认播放第一个音轨），取值范围：[0, 音轨总数)。
说明：
音轨总数可以通过 ​getMusicTrackCount 接口获取。
setPreloadObserver
void setPreloadObserver(TXMusicPreloadObserver? observer)
设置预加载的事件回调。
请在预加载背景音乐之前使用该接口设置回调，以便感知背景音乐的预加载进度。
参数
类型
描述
observer
TXMusicPreloadObserver?
预加载的事件回调，详见 ​TXMusicPreloadObserver；传 null 表示移除回调。
preloadMusic
void preloadMusic(AudioMusicParam musicParam)
预加载背景音乐。
每个音乐都需要您指定具体的 ID，您可以通过该 ID 对音乐的开始、停止、音量等进行设置。
参数
类型
描述
musicParam
﻿AudioMusicParam﻿
音乐参数，详见 ​AudioMusicParam。
说明：
1. 预加载最多同时支持 2 个不同 ID 的预加载，且预加载时长不超过 10 分钟。使用完之后需要调用 stopPlayMusic，否则内存不会被释放。
2. 若该 ID 对应的音乐正在播放中，预加载会失败，需要先调用 stopPlayMusic。
3. 当传入 startPlayMusic 的 musicParam 与预加载时完全相同时，预加载才会生效。
类型定义
TXVoiceReverbType
混响特效。
混响特效可以作用于人声之上，基于声学算法模拟出各种不同环境下的声音效果。
枚举值
数值
描述
type0
0
关闭特效。
type1
1
KTV。
type2
2
小房间。
type3
3
大会堂。
type4
4
低沉。
type5
5
洪亮。
type6
6
金属声。
type7
7
磁性。
type8
8
空灵。
type9
9
录音棚。
type10
10
悠扬。
type11
11
录音棚 2。
TXVoiceChangerType
变声特效。
变声特效可以作用于人声之上，基于声学算法改变人声的音色。
枚举值
数值
描述
type0
0
关闭特效。
type1
1
熊孩子。
type2
2
萝莉。
type3
3
大叔。
type4
4
重金属。
type5
5
感冒。
type6
6
外国人。
type7
7
困兽。
type8
8
肥宅。
type9
9
强电流。
type10
10
重机械。
type11
11
空灵。
AudioMusicParam
背景音乐的播放控制信息。
该信息用于在接口 ​startPlayMusic 中指定背景音乐的相关信息，包括播放 ID、文件路径和循环次数等。
1. 如果要多次播放同一首背景音乐，请不要每次播放都分配一个新的 ID，推荐使用相同的 ID。
2. 若您希望同时播放多首不同的音乐，请为不同的音乐分配不同的 ID 进行播放。
3. 如果使用同一个 ID 播放不同音乐，SDK 会先停止播放旧的音乐，再播放新的音乐。
字段
类型
默认值
描述
id
int
必填
音乐 ID。SDK 允许播放多路音乐，因此需要使用 ID 进行标记，用于控制音乐的开始、停止、音量等。
path
String
必填
音乐文件的绝对路径或 URL 地址，支持 mp3、aac、m4a、wav 格式。
loopCount
int
0
音乐循环播放的次数，取值范围为 0 或任意正整数。
0 表示播放音乐一次；
1 表示播放音乐两次，以此类推。
publish
bool
false
是否将音乐传到远端。
true：音乐在本地播放的同时，远端用户也能听到该音乐；
false：主播只能在本地听到该音乐，远端观众听不到。
isShortFile
bool
false
播放的是否为短音乐文件。
true：需要重复播放的短音乐文件；
false：正常的音乐文件。
startTimeMS
int
0
音乐开始播放时间点，单位：毫秒。
endTimeMS
int
0
音乐结束播放时间点，单位：毫秒。0 表示播放至文件结尾。
TXMusicPlayObserver
背景音乐的播放事件回调。
onStart
final void Function(int id, int errorCode) onStart
背景音乐开始播放。
参数
类型
描述
id
int
音乐 ID。
errorCode
int
0：开始播放成功；
-4001：打开文件失败，如处理输入时发现无效数据、找不到 ffmpeg 协议等；
-4005：非法路径，请检查传入的路径是否指向合法的音乐文件；
-4006：非法 URL，请使用浏览器检查传入的 URL 地址是否可以下载到期望的音乐文件；
-4007：无音频流，请确认传入的文件是否是合法的音频文件，文件是否被损坏；
-4008：不支持的格式，请确认传入的文件格式是否为支持的文件格式。移动端支持 mp3、aac、m4a、wav、ogg、mp4、mkv，桌面端支持 mp3、aac、m4a、wav、mp4、mkv。
onPlayProgress
final void Function(int id, int curPtsMSm, int durationMS) onPlayProgress
背景音乐的播放进度。
参数
类型
描述
id
int
音乐 ID。
curPtsMSm
int
当前播放时间点，单位：毫秒。
durationMS
int
音乐总时长，单位：毫秒。
onComplete
final void Function(int id, int errorCode) onComplete
背景音乐已经播放完毕。
在背景音乐播放完毕或播放出错时回调。
参数
类型
描述
id
int
音乐 ID。
errorCode
int
0：播放结束；
-4002：解码失败，如音频文件损坏、网络音频文件服务器无法访问等。
TXMusicPreloadObserver
背景音乐的预加载事件回调。
onLoadProgress
final void Function(int id, int progress) onLoadProgress
背景音乐预加载进度。
参数
类型
描述
id
int
音乐 ID。
progress
int
预加载进度。
onLoadError
final void Function(int id, int errorCode) onLoadError
背景音乐预加载出错。
参数
类型
描述
id
int
音乐 ID。
errorCode
int
-4001：打开文件失败，如处理输入时发现无效数据、找不到 ffmpeg 协议等；
-4002：解码失败，如音频文件损坏、网络音频文件服务器无法访问等；
-4003：预加载数量超过上限，请先调用 stopPlayMusic 释放无用的预加载；
-4005：非法路径，请检查传入的路径是否指向合法的音乐文件；
-4006：非法 URL，请使用浏览器检查传入的 URL 地址是否可以下载到期望的音乐文件；
-4007：无音频流，请确认传入的文件是否是合法的音频文件，文件是否被损坏；
-4008：不支持的格式，请确认传入的文件格式是否为支持的文件格式。移动端支持 mp3、aac、m4a、wav、ogg、mp4、mkv，桌面端支持 mp3、aac、m4a、wav、mp4、mkv。
﻿

参数	类型	描述
`musicId`	`int`	音乐 ID。
`observer`	`TXMusicPlayObserver?`	背景音乐播放的事件回调，详见 TXMusicPlayObserver。

字段	类型	默认值	描述
`id`	`int`	必填	音乐 ID。SDK 允许播放多路音乐，因此需要使用 ID 进行标记，用于控制音乐的开始、停止、音量等。
`path`	`String`	必填	音乐文件的绝对路径或 URL 地址，支持 mp3、aac、m4a、wav 格式。
`loopCount`	`int`	`0`	音乐循环播放的次数，取值范围为 0 或任意正整数。 `0` 表示播放音乐一次； `1` 表示播放音乐两次，以此类推。
`publish`	`bool`	`false`	是否将音乐传到远端。 `true`：音乐在本地播放的同时，远端用户也能听到该音乐； `false`：主播只能在本地听到该音乐，远端观众听不到。
`isShortFile`	`bool`	`false`	播放的是否为短音乐文件。 `true`：需要重复播放的短音乐文件； `false`：正常的音乐文件。
`startTimeMS`	`int`	`0`	音乐开始播放时间点，单位：毫秒。
`endTimeMS`	`int`	`0`	音乐结束播放时间点，单位：毫秒。`0` 表示播放至文件结尾。

参数	类型	描述
`id`	`int`	音乐 ID。
`errorCode`	`int`	`0`：开始播放成功； `-4001`：打开文件失败，如处理输入时发现无效数据、找不到 ffmpeg 协议等； `-4005`：非法路径，请检查传入的路径是否指向合法的音乐文件； `-4006`：非法 URL，请使用浏览器检查传入的 URL 地址是否可以下载到期望的音乐文件； `-4007`：无音频流，请确认传入的文件是否是合法的音频文件，文件是否被损坏； `-4008`：不支持的格式，请确认传入的文件格式是否为支持的文件格式。移动端支持 mp3、aac、m4a、wav、ogg、mp4、mkv，桌面端支持 mp3、aac、m4a、wav、mp4、mkv。

参数	类型	描述
`id`	`int`	音乐 ID。
`errorCode`	`int`	`0`：播放结束； `-4002`：解码失败，如音频文件损坏、网络音频文件服务器无法访问等。

参数	类型	描述
`id`	`int`	音乐 ID。
`errorCode`	`int`	`-4001`：打开文件失败，如处理输入时发现无效数据、找不到 ffmpeg 协议等； `-4002`：解码失败，如音频文件损坏、网络音频文件服务器无法访问等； `-4003`：预加载数量超过上限，请先调用 `stopPlayMusic` 释放无用的预加载； `-4005`：非法路径，请检查传入的路径是否指向合法的音乐文件； `-4006`：非法 URL，请使用浏览器检查传入的 URL 地址是否可以下载到期望的音乐文件； `-4007`：无音频流，请确认传入的文件是否是合法的音频文件，文件是否被损坏； `-4008`：不支持的格式，请确认传入的文件格式是否为支持的文件格式。移动端支持 mp3、aac、m4a、wav、ogg、mp4、mkv，桌面端支持 mp3、aac、m4a、wav、mp4、mkv。

API	描述
enableVoiceEarMonitor	开启耳返。
setVoiceEarMonitorVolume	设置耳返音量。
setVoiceReverbType	设置人声的混响效果。
setVoiceChangerType	设置人声的变声特效。
setVoiceCaptureVolume	设置语音音量。
setVoicePitch	设置语音音调。

API	描述
setMusicObserver	设置背景音乐的事件回调。
startPlayMusic	开始播放背景音乐。
stopPlayMusic	停止播放背景音乐。
pausePlayMusic	暂停播放背景音乐。
resumePlayMusic	恢复播放背景音乐。

API	描述
setAllMusicVolume	设置所有背景音乐的本地音量和远端音量。
setMusicPublishVolume	设置某一首背景音乐的远端音量。
setMusicPlayoutVolume	设置某一首背景音乐的本地音量。
setMusicPitch	调整背景音乐的音调高低。
setMusicSpeedRate	调整背景音乐的变速效果。
setMusicScratchSpeedRate	调整搓碟的变速效果。

API	描述
getMusicCurrentPosInMS	获取背景音乐的播放进度（单位：毫秒）。
getMusicDurationInMS	获取背景音乐的总时长（单位：毫秒）。
seekMusicToPosInTime	设置背景音乐的播放进度（单位：毫秒）。
getMusicTrackCount	获取背景音乐的音轨数量。
setMusicTrack	指定背景音乐的播放音轨。

API	描述
setPreloadObserver	设置预加载的事件回调。
preloadMusic	预加载背景音乐。

枚举值	数值	描述
`type0`	0	关闭特效。
`type1`	1	KTV。
`type2`	2	小房间。
`type3`	3	大会堂。
`type4`	4	低沉。
`type5`	5	洪亮。
`type6`	6	金属声。
`type7`	7	磁性。
`type8`	8	空灵。
`type9`	9	录音棚。
`type10`	10	悠扬。
`type11`	11	录音棚 2。

TXAudioEffectManager

本页目录：

函数列表

人声相关接口

背景音乐播放

背景音乐音量、音调与速度

背景音乐进度与音轨

背景音乐预加载

接口详情

enableVoiceEarMonitor

setVoiceEarMonitorVolume

setVoiceReverbType

setVoiceChangerType

setVoiceCaptureVolume

setVoicePitch

setMusicObserver

startPlayMusic

示例代码

stopPlayMusic

pausePlayMusic

resumePlayMusic

setAllMusicVolume

setMusicPublishVolume

setMusicPlayoutVolume

setMusicPitch

setMusicSpeedRate

setMusicScratchSpeedRate

getMusicCurrentPosInMS

返回值

getMusicDurationInMS

返回值

seekMusicToPosInTime

getMusicTrackCount

返回值

setMusicTrack

setPreloadObserver

preloadMusic

类型定义

TXVoiceReverbType

TXVoiceChangerType

AudioMusicParam

TXMusicPlayObserver

onStart

onPlayProgress

onComplete

TXMusicPreloadObserver

onLoadProgress

onLoadError