TRTCChatSalonAPI.md

TRTCChatSalon 是基于腾讯云实时音视频（TRTC）和即时通信 IM 服务组合而成的组件，支持以下功能：

• 主播创建新的语音沙龙开播，观众进入语音沙龙收听/互动。
• 主播可以同意观众上麦、将麦上主播踢下麦。
• 观众可以申请上麦，变成麦上主播，可以和其他人语音互动，也可以随时下麦成为普通的观众。
• 支持发送各种文本消息。

TRTCChatSalon 是一个开源的 Class，依赖腾讯云的两个闭源 SDK，具体的实现过程请参见 语音沙龙（Flutter）。

• TRTC SDK：使用 TRTC SDK 作为低延时语音聊天组件。
• IM SDK：使用 IM SDK 的 AVChatroom 实现聊天室的功能，同时，通过 IM 的属性接口来存储麦位表等房间信息，邀请信令可以用于上麦申请/抱麦申请。

TRTCChatSalon API 概览

SDK 基础函数

API	描述
sharedInstance	获取单例对象。
destroySharedInstance	销毁单例对象。
registerListener	设置事件监听。
unRegisterListener	销毁事件监听。
login	登录。
logout	登出。
setSelfProfile	修改个人信息。

房间相关接口函数

API	描述
createRoom	创建房间（主播调用），若房间不存在，系统将自动创建一个新房间。
destroyRoom	销毁房间（主播调用）。
enterRoom	进入房间（观众调用）。
exitRoom	离开房间（观众调用）。
getRoomInfoList	获取房间列表的详细信息。
getRoomMemberList	获取房间内所有用户信息。
getArchorInfoList	获取房间主播列表。
getUserInfoList	获取指定 userId 的用户信息。

上下麦接口

API	描述
enterMic	观众上麦。
leaveMic	主播下麦。
muteMic	静音/解除静音某个麦位（主播调用）。
kickMic	踢人下麦（群主调用）。

本地音频操作接口

API	描述
startMicrophone	开启麦克风采集。
stopMicrophone	停止麦克风采集。
muteLocalAudio	开启/关闭本地静音。
setSpeaker	设置开启扬声器。
setAudioCaptureVolume	设置麦克风采集音量。
setAudioPlayoutVolume	设置播放音量。

远端用户音频操作接口

API	描述
muteRemoteAudio	静音/解除静音指定成员。
muteAllRemoteAudio	静音/解除静音所有成员。

背景音乐音效相关接口

API	描述
getAudioEffectManager	获取背景音乐音效管理对象 TXAudioEffectManager。

消息发送相关接口

API	描述
sendRoomTextMsg	在房间中广播文本消息，一般用于弹幕聊天。

申请上麦信令相关接口

API	描述
raiseHand	观众申请上麦。
agreeToSpeak	群主同意上麦。
refuseToSpeak	群主拒绝上麦。

TRTCChatSalonDelegate API 概览

通用事件回调

API	描述
onError	错误回调。
onWarning	警告回调。
onKickedOffline	登录同一账号，被踢下线。

房间事件回调

API	描述
onRoomDestroy	房间被销毁的回调。
onAnchorListChange	主播列表发生变化的回调。
onUserVolumeUpdate	用户通话音量回调。

麦位变更回调

API	描述
onAnchorEnterMic	有成员上麦（主动上麦/群主抱人上麦）。
onAnchorLeaveMic	有成员下麦（主动下麦/群主踢人下麦）。
onMicMute	主播禁麦。

观众进出事件回调

API	描述
onAudienceEnter	收到观众进房通知。
onAudienceExit	收到观众退房通知。

消息事件回调

API	描述
onRecvRoomTextMsg	收到文本消息。

申请上麦信令事件回调

API	描述
onRaiseHand	有观众举手，申请上麦。
onAgreeToSpeak	观众申请举手后，收到群主同意举手的回调。
onRefuseToSpeak	观众申请举手后，群主拒绝举手的回调。

SDK 基础函数

sharedInstance

获取 TRTCChatSalon 单例对象。

 static Future<TRTCChatSalon> sharedInstance()

destroySharedInstance

销毁 TRTCChatSalon 单例对象。

?销毁实例后，外部缓存的 TRTCChatSalon 实例无法再使用，需要重新调用 sharedInstance 获取新实例。

static void destroySharedInstance()

registerListener

设置事件监听

void registerListener(VoiceListenerFunc func)

?setDelegate 是 TRTCChatSalon 的代理回调。

unRegisterListener

移除组件事件监听接口

void unRegisterListener(VoiceListenerFunc func)

参数如下表所示：

参数	类型	含义
func	VoiceListenerFunc	TRTCChatSalon 中的各种状态通知，会派发到您指定的 func函数

login

登录。

Future<ActionCallback> login(int sdkAppId, String userId, String userSig)

参数如下表所示：

参数	类型	含义
sdkAppId	int	您可以在实时音视频控制台 >【应用管理】> 应用信息中查看 SDKAppID。
userId	String	当前用户的 ID，字符串类型，只允许包含英文字母（a-z 和 A-Z）、数字（0-9）、连词符（-）和下划线（_）。
userSig	String	腾讯云设计的一种安全保护签名，获取方式请参考 如何计算 UserSig。

logout

登出。

Future<ActionCallback> logout()

setSelfProfile

修改个人信息。

Future<ActionCallback> setSelfProfile(String userName, String avatarURL)

参数如下表所示：

参数	类型	含义
userName	String	昵称。
avatarURL	String	头像地址。

房间相关接口函数

createRoom

创建房间（新建房间时调用）。

Future<ActionCallback> createRoom(int roomId, RoomParam roomParam)

参数如下表所示：

参数	类型	含义
roomId	int	房间标识，需要由您分配并进行统一管理。多个 roomID 可以汇总成一个语音沙龙房间列表，腾讯云暂不提供语音沙龙房间列表的管理服务，请自行管理您的语音沙龙房间列表。
roomParam	RoomParam	房间信息，用于房间描述的信息。例如房间名称、封面信息等。

主播开播的正常调用流程如下：

1. 主播调用createRoom创建新的语音沙龙，此时传入房间 ID等房间属性信息。
2. 主播还会收到麦位表有成员进入的onAnchorEnterMic的事件通知，此时会自动打开麦克风采集。

destroyRoom

销毁房间（主播调用）。主播在创建房间后，可以调用这个函数来销毁房间。

Future<ActionCallback> destroyRoom()

enterRoom

进入房间（观众调用）。

Future<ActionCallback> enterRoom(int roomId)

参数如下表所示：

参数	类型	含义
roomId	int	房间标识。

观众进房收听的正常调用流程如下：

1. 观众向您的服务端获取最新的语音沙龙列表，可能包含多个语音沙龙房间的 roomId 和房间信息。
2. 观众选择一个语音沙龙，调用enterRoom并传入房间号即可进入该房间。
3. 进房后会可查询getArchorInfoList获取主播列表，并根据getRoomMemberList获取房间所有用户列表，减去主播列表可以得到观众列表。
4. 进房后还会收到麦位表有主播进入的onAnchorEnterMic的事件通知。

exitRoom

离开房间。

Future<ActionCallback> exitRoom()

getRoomInfoList

获取房间列表的详细信息，其中房间名称、房间封面是主播在创建 createRoom() 时通过 roomInfo 设置的。

?如果房间列表和房间信息都由您自行管理，可忽略该函数。

Future<RoomInfoCallback> getRoomInfoList(List<String> roomIdList)

参数如下表所示：

参数	类型	含义
roomIdList	List<Integer>	房间号列表。

getRoomMemberList

获取房间内所有成员列表

?IM直播聊天群默认只能拉取最近31个成员列表

Future<MemberListCallback> getRoomMemberList(double nextSeq)

参数如下表所示：

参数	类型	含义
nextSeq	double	分页拉取标志，第一次拉取填0，回调成功如果 nextSeq 不为零，需要分页，传入再次拉取，直至为0。

getArchorInfoList

获取房间内主播列表。

Future<UserListCallback> getArchorInfoList()

getUserInfoList

获取指定userId的用户信息。

Future<UserListCallback> getUserInfoList(List<String> userIdList)

参数如下表所示：

参数	类型	含义
userIdList	List<String>	需要获取的用户 ID 列表，如果为 null，则获取房间内所有人的信息。

上下麦接口

enterMic

上麦（观众端和主播均可调用）。

?上麦成功后，房间内所有成员会收到onAnchorEnterSeat的事件通知。

Future<ActionCallback> enterMic();

调用该接口会立即修改麦位表。观众需先调用 raiseHand 向主播申请，收到 onAgreeToSpeak后再调用该函数。

leaveMic

主动下麦

? 下麦成功后，房间内所有成员会收到onAnchorLeaveMic的事件通知。

Future<ActionCallback> leaveMic()

muteMic

静音/解除静音某个麦位（主播调用）

? 改变麦位的状态后，房间内所有成员会收到onAnchorListChange和onMicMute的事件通。

Future<ActionCallback> muteMic(bool mute)

kickMic

踢人下麦（主播调用）。

? 主播踢人下麦，房间内所有成员会收到onAnchorLeaveMic的事件通知。

Future<ActionCallback> kickMic(String userId)

参数如下表所示：

参数	类型	含义
userId	String	需要踢下麦的用户id。

调用该接口会立即修改麦位表。

本地音频操作接口

startMicrophone

开启麦克风采集。

void startMicrophone(int quality)

参数如下表所示：

参数	类型	含义
quality	int	音频质量，详情请参见 TRTC SDK。

stopMicrophone

停止麦克风采集。

void stopMicrophone()

muteLocalAudio

静音/取消静音本地的音频。

void muteLocalAudio(bool mute)

参数如下表所示：

参数	类型	含义
mute	boolean	静音/取消静音，详情请参见 TRTC SDK。

setSpeaker

设置开启扬声器。

void setSpeaker(bool useSpeaker)

参数如下表所示：

参数	类型	含义
useSpeaker	boolean	true：扬声器；false：听筒。

setAudioCaptureVolume

设置麦克风采集音量。

void setAudioCaptureVolume(int volume)

参数如下表所示：

参数	类型	含义
volume	int	采集音量，0 - 100， 默认100。

setAudioPlayoutVolume

设置播放音量。

void setAudioPlayoutVolume(int volume)

参数如下表所示：

参数	类型	含义
volume	int	播放音量，0 - 100， 默认100。

muteRemoteAudio

静音/解除静音指定成员。

void muteRemoteAudio(String userId, bool mute)

参数如下表所示：

参数	类型	含义
userId	String	指定的用户 ID。
mute	boolean	true：开启静音；false：关闭静音。

muteAllRemoteAudio

静音/解除静音所有成员。

void muteAllRemoteAudio(bool mute)

参数如下表所示：

参数	类型	含义
mute	boolean	true：开启静音；false：关闭静音。

背景音乐音效相关接口函数

getAudioEffectManager

获取背景音乐音效管理对象 TXAudioEffectManager。

TXAudioEffectManager getAudioEffectManager()

消息发送相关接口函数

sendRoomTextMsg

在房间中广播文本消息，一般用于弹幕聊天。

Future<ActionCallback> sendRoomTextMsg(String message)

参数如下表所示：

参数	类型	含义
message	String	文本消息。

申请上麦信令相关接口

raiseHand

观众申请上麦

void raiseHand()

agreeToSpeak

群主同意上麦

Future<ActionCallback> agreeToSpeak(String userId)

参数如下表所示：

参数	类型	含义
userId	String	用户ID。

refuseToSpeak

群主拒绝用户上麦。

Future<ActionCallback> refuseToSpeak(String userId)

参数如下表所示：

参数	类型	含义
userId	String	用户ID。

TRTCChatSalonDelegate事件回调

通用事件回调

onError

错误回调。

? SDK 不可恢复的错误，一定要监听，并分情况给用户适当的界面提示。

参数如下表所示：

参数	类型	含义
errCode	int	错误码。
errMsg	String	错误信息。
extraInfo	String	扩展信息字段，个别错误码可能会带额外的信息帮助定位问题。

onWarning

警告回调。

参数如下表所示：

参数	类型	含义
warningCode	int	错误码。
warningMsg	String	警告信息。
extraInfo	String	扩展信息字段，个别错误码可能会带额外的信息帮助定位问题。

onKickedOffline

其他用户登录了同一账号，被踢下线。

房间事件回调

onRoomDestroy

房间被销毁的回调。主播解散房间时，房间内的所有用户都会收到此通知。

onAnchorListChange

主播列表发生变化的通知

参数如下表所示：

参数	类型	含义
userId	String	用户 ID。
mute	bool	静音状态。

onUserVolumeUpdate

启用音量大小提示，会通知每个成员的音量大小。

参数如下表所示：

参数	类型	含义
userId	String	用户 ID。
volume	int	音量大小，取值：0 - 100。

麦位回调

onAnchorEnterMic

有成员上麦

参数如下表所示：

参数	类型	含义
userId	String	上麦的用户id。
userName	String	用户昵称。
userAvatar	String	头像地址。
mute	bool	麦位状态，默认开麦。

onAnchorLeaveMic

有成员下麦

参数如下表所示：

参数	类型	含义
userId	String	下麦的用户id。

onMicMute

主播是否禁麦

参数如下表所示：

参数	类型	含义
userId	String	下麦的用户id。
mute	bool	麦位状态。

观众进出事件回调

onAudienceEnter

收到观众进房通知。

参数如下表所示：

参数	类型	含义
userId	String	上麦的用户id。
userName	String	用户昵称。
userAvatar	String	头像地址。

onAudienceExit

收到观众退房通知。

参数如下表所示：

参数	类型	含义
userId	String	下麦的用户id。

消息事件回调

onRecvRoomTextMsg

收到文本消息。

参数如下表所示：

参数	类型	含义
message	String	文本消息。
sendId	String	发送者用户id。
userAvatar	String	发送者用户头像。
userName	String	发送者用户昵称。

申请举手信令事件回调

onRaiseHand

收到新的上麦请求。

参数如下表所示：

参数	类型	含义
userId	String	申请举手的用户id。

onAgreeToSpeak

群主同意上麦的回调。

参数如下表所示：

参数	类型	含义
userId	String	群主的用户id。

onRefuseToSpeak

群主拒绝上麦的回调。

参数如下表所示：

参数	类型	含义
userId	String	群主的用户id。