tencent cloud

TRTCChatSalon is based on Tencent Real-Time Communication (TRTC) and Instant Messaging (IM). Its features include:

• A user can create a chat salon and become a speaker, or enter a salon as a listener.
• The room owner can accept a listener’s request to speak as well as remove a speaker.
• A listener can request to speak and become a speaker. A speaker can also become a listener.
• All users can send text messages.

TRTCChatSalon is an open-source class depending on two closed-source Tencent Cloud SDKs. For the specific implementation process, please see Chat Salon (Flutter).

• TRTC SDK: the TRTC SDK is used as a low-latency audio chat component.
• IM SDK: the AVChatRoom feature of the IM SDK is used to implement chat rooms. The attribute APIs of IM are used to store room information such as the seat list, and invitation signaling is used to send requests to speak or invite others to speak.

TRTCChatSalon API Overview

Basic SDK APIs

API	Description
sharedInstance	Gets a singleton object.
destroySharedInstance	Terminates singleton object.
registerListener	Sets event listener.
unRegisterListener	Terminates event listener.
login	Logs in.
logout	Logs out.
setSelfProfile	Sets profile.

Room APIs

API	Description
createRoom	Creates a room (called by room owner). If the room does not exist, the system will automatically create a room.
destroyRoom	Terminates a room (called by room owner).
enterRoom	Enters a room (called by listener).
exitRoom	Exits a room (called by listener).
getRoomInfoList	Gets room list details.
getRoomMemberList	Gets the information of all users in the room.
getArchorInfoList	Gets the list of speakers in the room.
getUserInfoList	Gets the user information of the specified userId.

Mic APIs

API	Description
enterMic	Becomes a speaker.
leaveMic	Becomes a listener.
muteMic	Mutes/Unmutes a speaker (called by room owner).
kickMic	Removes a speaker (called by room owner).

Local audio APIs

API	Description
startMicrophone	Enables mic capturing.
stopMicrophone	Stops mic capturing.
muteLocalAudio	Mutes/Unmutes local audio.
setSpeaker	Turns the speaker on.
setAudioCaptureVolume	Sets mic capturing volume.
setAudioPlayoutVolume	Sets playback volume.

Remote audio APIs

API	Description
muteRemoteAudio	Mutes/Unmutes a specified member.
muteAllRemoteAudio	Mutes/Unmutes all members.

Background music and audio effect APIs

API	Description
getAudioEffectManager	Gets the background music and audio effect management object TXAudioEffectManager.

Message sending APIs

API	Description
sendRoomTextMsg	Broadcasts a text message in the room. This API is generally used for on-screen comments.

APIs for sending requests to speak

API	Description
raiseHand	Requests to speak.
agreeToSpeak	Accepts the request to speak (called by room owner).
refuseToSpeak	Rejects the request to speak (called by room owner).

TRTCChatSalonDelegate API Overview

Common event callback APIs

API	Description
onError	Error
onWarning	Warning
onKickedOffline	Kicked offline

Room event callback APIs

API	Description
onRoomDestroy	The room was closed.
onAnchorListChange	Speaker list change
onUserVolumeUpdate	User volume

Seat list change callback APIs

API	Description
onAnchorEnterMic	Someone became a speaker after requesting or being invited by the room owner.
onAnchorLeaveMic	Someone became a listener or was moved to listeners by the room owner.
onMicMute	The room owner muted a speaker.

Callback APIs for room entry/exit by listeners

API	Description
onAudienceEnter	A listener entered the room.
onAudienceExit	A listener exited the room.

Message event callback APIs

API	Description
onRecvRoomTextMsg	A text message was received.

Callback APIs for sending requests to speak

API	Description
onRaiseHand	A listener requested to speak.
onAgreeToSpeak	The room owner accepted the listener’s request to speak.
onRefuseToSpeak	The room owner rejected the listener’s request to speak.

Basic SDK APIs

sharedInstance

This API is used to get a TRTCChatSalon singleton object.

static Future<TRTCChatSalon> sharedInstance()

destroySharedInstance

This API is used to terminate a TRTCChatSalon singleton object.

Note：

After the instance is terminated, the externally cached TRTCChatSalon instance can no longer be used. You need to call sharedInstance again to get a new instance.

static void destroySharedInstance()

registerListener

This API is used to set an event listener.

void registerListener(VoiceListenerFunc func)

Note：

setDelegate is the delegate callback of TRTCChatSalon.

unRegisterListener

This API is used to remove the component event listener.

void unRegisterListener(VoiceListenerFunc func)

The parameters are as detailed below:

Parameter	Type	Description
func	VoiceListenerFunc	Status notifications in TRTCChatSalon are sent to the function you specify.

login

This API is used to log in.

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

The parameters are as detailed below:

Parameter	Type	Description
sdkAppId	int	You can view the SDKAppID via Application Management > Application Info in the TRTC console.
userId	String	ID of the current user, which is a string that can contain only letters (a-z and A-Z), digits (0-9), hyphens (-), and underscores (_).
userSig	String	Tencent Cloud's proprietary security signature. For more information on how to get it, please see UserSig.

logout

This API is used to log out.

Future<ActionCallback> logout()

setSelfProfile

This API is used to set profile.

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

The parameters are as detailed below:

Parameter	Type	Description
userName	String	Nickname
avatarURL	String	Profile photo address

Room APIs

createRoom

This API is used to create a room.

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

The parameters are as detailed below:

Parameter	Type	Description
roomId	int	Room ID. You need to assign and manage the IDs in a centralized manner. Multiple roomID values can be aggregated into a chat salon room list. Currently, Tencent Cloud does not provide management services for chat salon room lists. Please manage the list by yourself.
roomParam	RoomParam	Room information, such as room name and cover information

The process of creating an audio chat room and becoming a speaker is as follows:

1. A user calls createRoom to create a chat salon, passing in room attributes such as room ID.
2. The user receives an onAnchorEnterSeat notification that someone became a speaker, and mic capturing is enabled automatically.

destroyRoom

This API is used to terminate a room (called by room owner).

Future<ActionCallback> destroyRoom()

enterRoom

This API is used to enter a room (called by listener).

Future<ActionCallback> enterRoom(int roomId)

The parameters are as detailed below:

Parameter	Type	Description
roomId	int	Room ID

The process of entering a room as a listener is as follows:

1. A user gets the latest chat salon list from your server. The list may contain the roomId and room information of multiple chat salons.
2. Select a chat salon, and call enterRoom with the room ID passed in to enter.
3. After room entry, the user can call getArchorInfoList to get the speaker list and call getRoomMemberList to get the user list. The user list minus the speaker list is the listener list.
4. The user receives an onAnchorEnterMic notification that someone became a speaker.

exitRoom

This API is used to exit a room.

Future<ActionCallback> exitRoom()

getRoomInfoList

This API is used to get room list details. The room name and cover are set by the room owner via roomInfo when calling createRoom().

Note：

You don’t need this API if both the room list and room information are managed on your server.

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

The parameters are as detailed below:

Parameter	Type	Description
roomIdList	List<String>	Room ID list

getRoomMemberList

This API is used to get the user list of a room.

Note：

By default, the user list includes only the latest 31 users who entered an IM live chat group.

Future<MemberListCallback> getRoomMemberList(double nextSeq)

The parameters are as detailed below:

Parameter	Type	Description
nextSeq	double	Pulling-by-page flag. It is set to 0 when the information is pulled for the first time. If the callback succeeds and nextSeq is not 0, pagination is needed. The value of this field is passed in for the next pull until the value becomes 0.

getArchorInfoList

This API is used to get the list of speakers in the room.

Future<UserListCallback> getArchorInfoList()

getUserInfoList

This API is used to get the user information of a specified userId.

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

The parameters are as detailed below:

Parameter	Type	Description
userIdList	List	IDs of the users to query. If this parameter is null, the information of all users in the room is obtained.

Mic APIs

enterMic

This API is used to become a speaker (called by room owner or listener).

Note：

After a user becomes a speaker, all members in the room will receive an onAnchorEnterSeat notification.

Future<ActionCallback> enterMic();

Calling this API will immediately modify the speaker list. A listener needs to call raiseHand first to send a request to the room owner and call this API after receiving onAgreeToSpeak.

leaveMic

A speaker became a listener.

Note：

After a speaker becomes a listener, all members in the room will receive an onAnchorLeaveMic notification.

Future<ActionCallback> leaveMic()

muteMic

This API is used to mute/unmute a seat (called by room owner).

Note：

After the speaker list changes, all users in the room will receive onAnchorListChange and onMicMute notifications.

Future<ActionCallback> muteMic(bool mute)

kickMic

This API is used to remove a speaker (called by room owner).

Note：

After the room owner removes a speaker, all users in the room will receive an onAnchorLeaveMic notification.

Future<ActionCallback> kickMic(String userId)

The parameters are as detailed below:

Parameter	Type	Description
userId	String	User ID of the speaker to remove

Calling this API will immediately modify the speaker list.

Local Audio APIs

startMicrophone

This API is used to enable mic capturing.

void startMicrophone(int quality)

The parameters are as detailed below:

Parameter	Type	Description
quality	int	Audio quality. For more information, please see TRTC SDK.

stopMicrophone

This API is used to stop mic capturing.

void stopMicrophone()

muteLocalAudio

This API is used to mute/unmute the local audio.

void muteLocalAudio(bool mute)

The parameters are as detailed below:

Parameter	Type	Description
mute	bool	Mutes/Unmutes. For more information, please see TRTC SDK.

setSpeaker

This API is used to turn the speaker on.

void setSpeaker(bool useSpeaker)

The parameters are as detailed below:

Parameter	Type	Description
useSpeaker	bool	true: speaker; false: receiver

setAudioCaptureVolume

This API is used to set the mic capturing volume.

void setAudioCaptureVolume(int volume)

The parameters are as detailed below:

Parameter	Type	Description
volume	int	Capturing volume. Value range: 0-100 (default: 100)

setAudioPlayoutVolume

This API is used to set the playback volume.

void setAudioPlayoutVolume(int volume)

The parameters are as detailed below:

Parameter	Type	Description
volume	int	Playback volume. Value range: 0-100 (default: 100)

muteRemoteAudio

This API is used to mute/unmute a specified user.

void muteRemoteAudio(String userId, bool mute)

The parameters are as detailed below:

Parameter	Type	Description
userId	String	Specified user ID
mute	bool	true: mutes; false: unmutes.

muteAllRemoteAudio

This API is used to mute/unmute all users.

void muteAllRemoteAudio(bool mute)

The parameters are as detailed below:

Parameter	Type	Description
mute	bool	true: mutes; false: unmutes.

Background Music and Audio Effect APIs

getAudioEffectManager

This API is used to get the background music and audio effect management object TXAudioEffectManager.

TXAudioEffectManager getAudioEffectManager()

Message Sending APIs

sendRoomTextMsg

This API is used to broadcast a text message in a room, which is generally used for on-screen comments.

Future<ActionCallback> sendRoomTextMsg(String message)

The parameters are as detailed below:

Parameter	Type	Description
message	String	Text message.

APIs for sending requests to speak

raiseHand

This API is used to send a request to speak (called by listener).

void raiseHand()

agreeToSpeak

This API is used to accept a request to speak (called by room owner).

Future<ActionCallback> agreeToSpeak(String userId)

The parameters are as detailed below:

Parameter	Type	Description
userId	String	User ID.

refuseToSpeak

This API is used to reject a request to speak (called by room owner).

Future<ActionCallback> refuseToSpeak(String userId)

The parameters are as detailed below:

Parameter	Type	Description
userId	String	User ID.

TRTCChatSalonDelegate Event Callback APIs

Common Event Callback APIs

onError

Callback for error.

Note：

This callback indicates that the SDK encountered an unrecoverable error. Such errors must be listened for, and UI reminders should be sent to users if necessary.

The parameters are as detailed below:

Parameter	Type	Description
errCode	int	Error code
errMsg	String	Error message
extraInfo	String	Extended field. Certain error codes may carry extra information for troubleshooting.

onWarning

Callback for warning.

The parameters are as detailed below:

Parameter	Type	Description
warningCode	int	Warning code
warningMsg	String	Warning message
extraInfo	String	Extended field. Certain error codes may carry extra information for troubleshooting.

onKickedOffline

Callback for being kicked offline because another user logged in to the same account.

Room Event Callback APIs

onRoomDestroy

Callback for room termination. When the owner terminates the room, all users in the room will receive this callback.

onAnchorListChange

Callback for speaker list change.

The parameters are as detailed below:

Parameter	Type	Description
userId	String	User ID
mute	bool	Muted or not

onUserVolumeUpdate

Callback of the volume of each member in the room after the volume reminder is enabled.

The parameters are as detailed below:

Parameter	Type	Description
userId	String	User ID
volume	int	Volume. Value range: 0-100

Seat Callback APIs

onAnchorEnterMic

Someone became a speaker.

The parameters are as detailed below:

Parameter	Type	Description
userId	String	ID of the user who became a speaker
userName	String	Nickname
userAvatar	String	Profile photo address
mute	bool	Muted or not. Default: unmuted

onAnchorLeaveMic

A speaker became a listener.

The parameters are as detailed below:

Parameter	Type	Description
userId	String	ID of the user who became a listener

onMicMute

Whether a user is muted by the room owner.

The parameters are as detailed below:

Parameter	Type	Description
userId	String	User ID
mute	bool	Muted or not

Callback APIs for Room Entry/Exit by Listener

onAudienceEnter

A listener entered the room.

The parameters are as detailed below:

Parameter	Type	Description
userId	String	ID of the user who entered the room
userName	String	Nickname
userAvatar	String	Profile photo address

onAudienceExit

A listener exited the room.

The parameters are as detailed below:

Parameter	Type	Description
userId	String	User ID

Message Event Callback APIs

onRecvRoomTextMsg

A text message was received.

The parameters are as detailed below:

Parameter	Type	Description
message	String	Text message
sendId	String	Sender’s user ID
userAvatar	String	Sender’s profile photo
userName	String	Sender’s nickname

Callback APIs for sending requests to speak (hand raising)

onRaiseHand

A request to speak was received.

The parameters are as detailed below:

Parameter	Type	Description
userId	String	ID of the user who requested to speak

onAgreeToSpeak

The room owner accepted the request to speak.

The parameters are as detailed below:

Parameter	Type	Description
userId	String	User ID of the room owner

onRefuseToSpeak

The room owner rejected the request to speak.

The parameters are as detailed below:

Parameter	Type	Description
userId	String	User ID of the room owner