@detail api
@author luomingkang
@brief Whether to receive the audio stream of a specific user. Call this insterface will not affect the state of the speaker or other audio output devices.
@param userId User ID, a non-empty string with a maximum length of 128 bytes. The supported character set range is:
1. 26 capital letters A ~ Z
2. 26 lowercase letters a ~ z
3. 10 numbers 0 ~ 9
4. Underscore "_", at sign "@", minus sign "-"
@param enable
- true：Receive the user's audio stream.
- false：Default setting. Do not receive the user's audio stream. The speaker will not be muted and can still be used for other audio outputs.
@return
- 0: Success.
- -2: Failure. The provided userId is an empty string.
@detail api
@author luomingkang
@brief Starts or stops sending audio streams. Calling this interface does not affect audio capture. Other users in the same room will receive the corresponding callback.
@param enable Whether to send the saudio data:
- true: Starts sending audio data.
- false: Default setting. Stops sending audio data.
@return
- 0: It means that the parameter check has passed, but it does not mean that opening the microphone will succeed. For example, the room does not exist.
- -3: Failure. Not joined a room.
@note Cannot be called at the same time as EnableMicrophone{@link #IGameRoom#EnableMicrophone}.
@detail api
@author luomingkang
@brief Turns on/off the microphone after joining a game room. Other users in the same room will receive callback OnAudioDeviceStateChanged{@link #IRTCEngineEventHandler#OnAudioDeviceStateChanged}.
@param enable Whether to turn on the microphone:
- true: Turns on the microphone, captures and publishes audio stream.
- false: Default setting. Turns off the microphone and stops capturing and publishing audio streams.
@return
- 0: Success.
- -3: Failure. Not joined the room.
@note Cannot be called simultaneously with enableAudioSend{@link #IGameRoom#enableAudioSend}.
@detail api
@author luomingkang
@brief Turns on/off the speaker after joining a game room.
@param enable Whether to turn on the speaker:
- true: Turns on the speaker and subscribes to audio streams of all remote users.
- false: Default setting. Turns off the speaker and unsubscribes audio streams from all remote users.
@return
- 0: Success.
- -3: Failure. Not joined a room.
@hidden for internal use only.
@detail api
@author shenpengliang
@brief Set whether to subscribe to your own stream
@param enable Subscribe to yourself/not subscribe to yourself
@return
- 0: Success.
- < 0 : Fail. See ReturnStatus{@link #ReturnStatus} for more details.
@detail api
@valid since 3.60.
@author xuyiling
@brief Gets call ID.
Call this method after joining an RTC room. After creating a room, a call ID is generated to identify the call for this room.
@return Call ID.
@detail api
@author luomingkang
@brief Gets range audio instance.
@return API call result:
- IRangeAudio: Success. You will get an IRangeAudio{@link #IRangeAudio} returned from the SDK.
- null: Failure. The current SDK does not offer range audio function.
@note The first time this API is called must be between you create a room and you actually enter the room. Refer to Range Voice for more information.
@detail api
@author wangjunzheng
@brief Get location audio interface instances.
@return Spatial audio management interface instance. If NULL is returned, spatial audio is not supported. See ISpatialAudio{@link #ISpatialAudio}.
@note
- The first time this API is called must be between you create a room and you actually enter the room. Refer to Spatial Audio for more information.
- The spatial audio effect can only be turned on when using a device that supports true two-channel playback;
- In the case of poor network conditions, even if this function is turned on, the spatial audio effect will not be generated;
- Insufficient performance of the model may cause the audio card. When using a low-end machine, it is not recommended to turn on the spatial audio effect;
- Spatial audio effects do not take effect when server level routing is enabled.
@detail api
@author shenpengliang
@brief Join the RTC room.
After creating a room by calling createRTCRoom{@link #RTCEngine#createRTCRoom}, call this API to join the room and make audio & video calls with other users in the room.
@param token Dynamic key. It is used for authentication and verification of users entering the room.
You need to bring Token to enter the room. When testing, you can use the console to generate temporary tokens. The official launch requires the use of the key SDK to generate and issue tokens at your server level. See Use Token to complete authentication for token validity and generation method.
Apps with different AppIDs are not interoperable.
Make sure that the AppID used to generate the Token is the same as the AppID used to create the engine, otherwise it will cause the join room to fail.
@param userInfo User information. See UserInfo{@link #UserInfo}.
@param userVisibility User visibility. We recommend setting the user visibility to false when entering the room, and then setting it to true via setUserVisibility{@link #RTCRoom#setUserVisibility} when the user needs to send audio & video streams. Joining fails when the number of users in an RTC room reaches the upper limit. An RTC room can accommodate a maximum of 50 visible users, and 30 media streams can be published simultaneously. For more information, see Capability of Users and Streams.
@param roomConfig Room parameter configuration, set the room mode and whether to automatically publish or subscribe to the flow. See RTCRoomConfig{@link #RTCRoomConfig} for the specific configuration mode.
@return
- 0: Success.
- Local users receive notifications of the room state via onRoomStateChanged{@link #IRTCRoomEventHandler#onRoomStateChanged}.
- Local users receive notifications of the local-stream state via onVideoPublishStateChanged{@link #IRTCRoomEventHandler#onVideoPublishStateChanged}, onAudioPublishStateChanged{@link #IRTCRoomEventHandler#onAudioPublishStateChanged}.
- Local users receive notifications of the subscribed-stream state via onUserPublishStreamVideo{@link #IRTCRoomEventHandler#onUserPublishStreamVideo}, onUserPublishStreamAudio{@link #IRTCRoomEventHandler#onUserPublishStreamAudio}.
- Local users receive notifications of the published-stream state via onUserPublishStreamVideo{@link #IRTCRoomEventHandler#onUserPublishStreamVideo}, onUserPublishStreamAudio{@link #IRTCRoomEventHandler#onUserPublishStreamAudio}.
- Local users receive notifications of the subscribed-stream state via onVideoSubscribeStateChanged{@link #IRTCRoomEventHandler#onVideoSubscribeStateChanged}, onAudioSubscribeStateChanged{@link #IRTCRoomEventHandler#onAudioSubscribeStateChanged}.
- If the local user is also a visible user, the other participants receive onUserJoined{@link #IRTCRoomEventHandler#onUserJoined} callback.
- -1: RoomID/userI nfo.uid contains invalid parameters.
- -2: Already in the room. After the interface call is successful, as long as the return value of 0 is received and leaveRoom{@link #RTSRoom#leaveRoom} is not called successfully, this return value is triggered when the room entry interface is called again, regardless of whether the filled room ID and user ID are duplicated.
The reason for the failure will be communicated via the onRoomStateChanged{@link #IRTCRoomEventHandler#onRoomStateChanged} callback.
@note
- In the same room with the same App ID, the user ID of each user must be unique. If two users have the same user ID, the user who entered the room later will kick the user who entered the room out of the room, and the user who entered the room will receive the onRoomStateChanged{@link #IRTCRoomEventHandler#onRoomStateChanged} callback notification. For the error type. See kErrorCodeDuplicateLogin in ERROR_CODE_DUPLICATE_LOGIN{@link #ErrorCode#ERROR_CODE_DUPLICATE_LOGIN}.
- By default, the user is visible in an RTC room. Joining fails when the number of users in an RTC room reaches the upper limit. To avoid this, call setUserVisibility{@link #RTCRoom#setUserVisibility} to change the visibility of the audience users to false by considering the capacity for the invisible users is much larger than that for visible users. An RTC room can accommodate a maximum of 50 visible users, and 30 media streams can be published simultaneously. For more information, see Capability of Users and Streams.
- After the user successfully joins the room, the SDK may lose connection to the server in case of poor local network conditions. At this point, onConnectionStateChanged{@link #IRTCEngineEventHandler#onConnectionStateChanged} callback will be triggered and the SDK will automatically retry until it successfully reconnects to the server. After successful reconnection, onRoomStateChanged{@link #IRTCRoomEventHandler#onRoomStateChanged} callback notification will be received locally.
@detail api
@brief Joins the RTS room.
After creating a room by calling createRTSRoom{@link #RTCEngine#createRTSRoom}, call this API to join the room and make audio & video calls with other users in the room.
@param token Dynamic key. It is used for authentication and verification of users entering the room.
You need to bring Token to enter the room. When testing, you can use the console to generate temporary tokens. The official launch requires the use of the key SDK to generate and issue tokens at your server level. See Use Token to complete authentication for token validity and generation method.
Apps with different AppIDs are not interoperable.
Make sure that the AppID used to generate the Token is the same as the AppID used to create the engine, otherwise it will cause the join room to fail.
@param userInfo User information. See UserInfo{@link #UserInfo}.
@return
- 0: Success.
- Local users receive notifications of the room state via onRoomStateChanged{@link #IRTSRoomEventHandler#onRoomStateChanged}.
- -1: RoomID/userI nfo.uid contains invalid parameters.
- -2: Already in the room. After the interface call is successful, as long as the return value of 0 is received and leaveRoom{@link #RTSRoom#leaveRoom} is not called successfully, this return value is triggered when the room entry interface is called again, regardless of whether the filled room ID and user ID are duplicated.
The reason for the failure will be communicated via the onRoomStateChanged{@link #IRTSRoomEventHandler#onRoomStateChanged} callback.
@note
- In the same room with the same App ID, the user ID of each user must be unique. If two users have the same user ID, the user who entered the room later will kick the user who entered the room out of the room, and the user who entered the room will receive the onRoomStateChanged{@link #IRTSRoomEventHandler#onRoomStateChanged} callback notification. For the error type. See kErrorCodeDuplicateLogin in ERROR_CODE_DUPLICATE_LOGIN{@link #ErrorCode#ERROR_CODE_DUPLICATE_LOGIN}.
- After the user successfully joins the room, the SDK may lose connection to the server in case of poor local network conditions. At this point, onConnectionStateChanged{@link #IRTCEngineEventHandler#onConnectionStateChanged} callback will be triggered and the SDK will automatically retry until it successfully reconnects to the server. After successful reconnection, onRoomStateChanged{@link #IRTSRoomEventHandler#onRoomStateChanged} callback notification will be received locally.
@detail api
@author luomingkang
@brief Leaves the game room.
The user calls this method to leave the room, end the call process, and release all call-related resources.
@return
- 0: Success. If the user is a host:
- The other participants receive onUserLeave{@link #IRTCRoomEventHandler#onUserLeave} callback.
- The publishing streams stop and the other participants receive notifications of the stream states via onAudioPublishStateChanged{@link #IRTCRoomEventHandler#onAudioPublishStateChanged} callback.
- < 0 : Fail. See ReturnStatus{@link #ReturnStatus} for more details
@note This method is an asynchronous operation, and the call returns without actually exiting the room. After you actually exit the room, you will receive a callback notification from onRoomStateChanged{@link #IRTCRoomEventHandler#onRoomStateChanged} locally. If the engine is destroyed immediately after this method is called, the SDK will not be able to trigger the onRoomStateChanged{@link #IRTCRoomEventHandler#onRoomStateChanged} callback.
@detail api
@valid since 3.60. Since version 3.60, this interface replaces the pauseAllSubscribedStream method for the below functions. If you have upgraded to version 3.60 or later and are still using this method, please migrate to this interface.
@author shenpengliang
@brief Pauses receiving all remote audio streams.
@return
- 0: Success.
- < 0 : Fail. See ReturnStatus{@link #ReturnStatus} for more details
@note
- Calling this API does not change the capture state and the transmission state of the remote clients.
- Calling this API does not cancel the subscription or change any subscription configuration.
- To resume, call resumeAllSubscribedStreamVideo{@link #RTCRoom#resumeAllSubscribedStreamVideo}.
- In a multi-room scenario, this API only pauses the reception of streams published in the current room.
@detail api
@valid since 3.60. Since version 3.60, this interface replaces the pauseAllSubscribedStream method for the below functions. If you have upgraded to version 3.60 or later and are still using this method, please migrate to this interface.
@author shenpengliang
@brief Pauses receiving all remote video streams.
@return
- 0: Success.
- < 0 : Fail. See ReturnStatus{@link #ReturnStatus} for more details.
@note
- Calling this API does not change the capture state and the transmission state of the remote clients.
- Calling this API does not cancel the subscription or change any subscription configuration.
- To resume, call resumeAllSubscribedStreamVideo{@link #RTCRoom#resumeAllSubscribedStreamVideo}.
- In a multi-room scenario, this API only pauses the reception of streams published in the current room.
@detail api
@region Multi-room
@author shenpengliang
@brief Call this method to pause relaying media stream to all rooms after calling startForwardStreamToRooms{@link #RTCRoom#startForwardStreamToRooms}.
After that, call resumeForwardStreamToAllRooms{@link #RTCRoom#resumeForwardStreamToAllRooms} to resume.
@return
- 0: Success.
- < 0 : Fail. See ReturnStatus{@link #ReturnStatus} for more details.
@note The other users in the room will receive callback of onUserJoined{@link #IRTCRoomEventHandler#onUserJoined}, onUserPublishStreamVideo{@link #IRTCRoomEventHandler#onUserPublishStreamVideo}, onUserPublishStreamAudio{@link #IRTCRoomEventHandler#onUserPublishStreamAudio} when you stop relaying.
@detail api
@valid since 3.60. Since version 3.60, this interface replaces the publishStream, unpublishStream, publishScreen and unpublishScreen methods for the following functions. If you have upgraded to version 3.60 or above and are still using these two methods, please migrate to this interface.
@brief Publishes or stops publishing audio streams in the current room.
@param publish Whether to publish the audio stream.
- true: Publish.
- false: Stop publishing.
@return
- 0: Success.
- < 0 : Fail. See ReturnStatus{@link #ReturnStatus} for more details
@note
- You don't need to call this API if you set it to Auto-publish when calling joinRoom{@link #RTCRoom#joinRoom}.
- An invisible user cannot publish media streams. Call setUserVisibility{@link #RTCRoom#setUserVisibility} to change your visibility in the room.
- Call publishStreamVideo{@link #RTCRoom#publishStreamVideo} to start or stop publishing the video stream captured by the camera.
- Call startForwardStreamToRooms{@link #RTCRoom#startForwardStreamToRooms} to forward the published streams to the other rooms.
- After you call this API, the other users in the room will receive onUserPublishStreamAudio{@link #IRTCRoomEventHandler#onUserPublishStreamAudio}. Those who successfully received your streams will receive onFirstRemoteAudioFrame{@link #IRTCEngineEventHandler#onFirstRemoteAudioFrame} at the same time.
@detail api
@valid since 3.60. Since version 3.60, this interface replaces the publishStream, unpublishStream, publishScreen and unpublishScreen methods for the following functions. If you have upgraded to version 3.60 or above and are still using these two methods, please migrate to this interface.
@brief Publishes or stops publishing video streams.
@param publish Whether to publish the video stream.
- true: Publish.
- false: Stop publishing.
@return
- 0: Success.
- < 0 : Fail. See ReturnStatus{@link #ReturnStatus} for more details
@note
- You don't need to call this API if you set it to Auto-publish when calling joinRoom{@link #RTCRoom#joinRoom}.
- An invisible user cannot publish media streams. Call setUserVisibility{@link #RTCRoom#setUserVisibility} to change your visibility in the room.
- Call publishStreamAudio{@link #RTCRoom#publishStreamAudio} to start or stop publishing the audio stream captured by the microphone.
- Call startForwardStreamToRooms{@link #RTCRoom#startForwardStreamToRooms} to forward the published streams to the other rooms.
- After you call this API, the other users in the room will receive onUserPublishStreamVideo{@link #IRTCRoomEventHandler#onUserPublishStreamVideo}. Those who successfully received your streams will receive onFirstRemoteVideoFrameDecoded{@link #IRTCEngineEventHandler#onFirstRemoteVideoFrameDecoded} at the same time.
@detail api
@valid since 3.60. Since version 3.60, this interface replaces the resumeAllSubscribedStream method for the below functions. If you have upgraded to version 3.60 or later and are still using this method, please migrate to this interface.
@author shenpengliang
@brief Resumes receiving all remote audio streams.
@return
- 0: Success.
- < 0 : Fail. See ReturnStatus{@link #ReturnStatus} for more details
@note
- Calling this API does not change the capture state and the transmission state of the remote clients.
- Calling this API does not change any subscription configuration.
@detail api
@valid since 3.60. Since version 3.60, this interface replaces the resumeAllSubscribedStream method for the below functions. If you have upgraded to version 3.60 or later and are still using this method, please migrate to this interface.
@author shenpengliang
@brief Resumes receiving all remote video streams.
@return
- 0: Success.
- < 0 : Fail. See ReturnStatus{@link #ReturnStatus} for more details.
@note
- Calling this API does not change the capture state and the transmission state of the remote clients.
- Calling this API does not change any subscription configuration.
@detail api
@author shenpengliang
@brief Call this method to resume relaying to all rooms from the pause by calling pauseForwardStreamToAllRooms{@link #RTCRoom#pauseForwardStreamToAllRooms}.
@return
- 0: Success.
- < 0 : Fail. See ReturnStatus{@link #ReturnStatus} for more details.
@note The other users in the room will receive callback of onUserJoined{@link #IRTCRoomEventHandler#onUserJoined} and onUserPublishStreamVideo{@link #IRTCRoomEventHandler#onUserPublishStreamVideo}, onUserPublishStreamAudio{@link #IRTCRoomEventHandler#onUserPublishStreamAudio} when you resume relaying.
@detail api
@brief Group binary messages to all other users in the room.
@param buffer The content of the binary message sent. The message does not exceed 46KB.
@note
- Before broadcasting binary messages in the room, you must call joinRTSRoom{@link #RTSRoom#joinRTSRoom} to join the room.
- After the call, you will receive the onRoomMessageSendResult{@link #IRTSRoomEventHandler#onRoomMessageSendResult} callback;
- Other users in the same room will receive the onRoomBinaryMessageReceived{@link #IRTSRoomEventHandler#onRoomBinaryMessageReceived} callback.
@detail api
@brief Mass text messages to all other users in the room.
@param messageStr The content of the text message sent. The message does not exceed 64 KB.
@note
- Before broadcasting a text message in the room, you must call joinRTSRoom{@link #RTSRoom#joinRTSRoom} to join the room.
- After the call, you will receive the onRoomMessageSendResult{@link #IRTSRoomEventHandler#onRoomMessageSendResult} callback;
- Other users in the same room will receive the onRoomMessageReceived{@link #IRTSRoomEventHandler#onRoomMessageReceived} callback.
@detail api
@brief Sends a point-to-point binary message to the specified user in the room.
@param userId Message Receives user ID
@param buffer Binary message content sent. Message does not exceed 46KB.
@param config See MessageConfig{@link #MessageConfig}
@note
- Before sending in-room binary messages, you must call joinRTSRoom{@link #RTSRoom#joinRTSRoom} to join the room.
- After the call, you will receive an onUserMessageSendResult{@link #IRTSRoomEventHandler#onUserMessageSendResult} callback to notify that the message was sent successfully or failed;
- If the message was sent successfully, the user specified by the userId will receive an onUserBinaryMessageReceived{@link #IRTSRoomEventHandler#onUserBinaryMessageReceived} callback.
@detail api
@brief Send a point-to-point text message to the specified user in the room
@param userId User ID of the message receiver
@param messageStr Text message content sent. Message does not exceed 64 KB.
@param config See MessageConfig{@link #MessageConfig}.
@return
- > 0: Sent successfully, return the number of the sent message, increment from 1
- -1: Sent failed, RTCRoom instance not created
- -2: Sent failed, uid is empty
@note
- Before sending an in-room text message, you must call joinRTSRoom{@link #RTSRoom#joinRTSRoom} to join the room.
- After the call, you will receive an onUserMessageSendResult{@link #IRTSRoomEventHandler#onUserMessageSendResult} callback to notify that the message was sent successfully or failed;
- If the message was sent successfully, the user specified by the userId will receive an onUserMessageReceived{@link #IRTSRoomEventHandler#onUserMessageReceived} callback.
@valid since 3.52
@detail api
@author yejing.luna
@brief Set the priority of the local audio stream to be published.
@param audioSelectionPriority The priority of the local audio stream which defaults to be subscribable only up to the result of the Audio Selection. Refer to AudioSelectionPriority{@link #AudioSelectionPriority}.
@note
You must enable Audio Selection in the RTC console before using this API. You can call this API whether the user has joined a room. Refer to Audio Selection.
The setting is independent in each room that the user joins.
@detail api
@author wangzhanqiang
@brief Synchronizes published audio and video.
When the same user simultaneously uses separate devices to capture and publish audio and video, there is a possibility that the streams are out of sync due to the network disparity. In this case, you can call this API on the video publisher side and the SDK will automatically line the video stream up according to the timestamp of the audio stream, ensuring that the audio the receiver hears corresponds to the video the receiver watches.
@param audioUserId The ID of audio publisher. You can stop the current A/V synchronization by setting this parameter to null.
@return
- 0: Success. When the A/V synchronization state changes, you will receive onAVSyncStateChange{@link #IRTCRoomEventHandler#onAVSyncStateChange}.
- < 0 : Fail. You can also learn the error details via onAVSyncEvent{@link #IRTCRoomEventHandler#onAVSyncEvent}. More than one pair of audio and video can be synchronized simultaneously in the same RTC room, but you should note that one single audio source cannot be synchronized with multiple video sources at the same time.
@note
- You can call this API anytime before or after entering the room.
- The source user IDs of the audio and video stream to be synchronized must be in the same RTC room.
- If you want to change the audio source, call this API again with a new audioUserId. If you want to change the video source, you need to stop the current synchronization first, then call this API on the new video publisher side.
@detail api
@author zhangcaining
@brief Adjusts the audio playback volume from all the remote users in a room.
@param volume Ratio(%) of playback volume to original volume, in the range 0, 400, with overflow protection.
To ensure the audio quality, we recommend setting the volume to 100.
- 0: mute
- 100: original volume. Default value.
- 400: Up to 4 times the original volume (with overflow protection)
@return
- 0: Success.
- < 0 : Fail. See ReturnStatus{@link #ReturnStatus} for more details
@note Suppose a remote user A is always within the range of the target user whose playback volume will be adjusted,
- If you use both this method and setRemoteAudioPlaybackVolume{@link #RTCEngine#setRemoteAudioPlaybackVolume}, the volume that the local user hears from user A is the volume set by the method called later.
- If you use both this method and setPlaybackVolume{@link #RTCEngine#setPlaybackVolume}, the volume that the local user hears from user A is the overlay of both settings.
@detail api
@valid since 3.60.
@brief Sets the type of the remote video stream to subscribe to.
@param streamId ID of the remote video stream you expect to subscribe to.
@param streamType Video stream type, see SimulcastStreamType{@link #SimulcastStreamType}.
@return API call result:
- 0: Success.
- <0: Failure. See ReturnStatus{@link #ReturnStatus} for specific reasons.
@note
- This API only works after the publisher calls setLocalSimulcastMode{@link #RTCEngine#setLocalSimulcastMode} to enable publishing multiple-quality video streams, in which case the subscriber will receive the stream from the publisher that is closest to the set configuration; otherwise the subscriber will only receive one video stream with a resolution of 640px × 360px and a frame rate of 15fps.
- If you don't call this API after the publisher enables the function of publishing multiple streams, you will receive by default the video stream with the largest resolution set by the publisher.
- This API only affects camera video streams published by remote users.
@detail api
@brief Sets your expected configuration of the remote video stream that you want to subscribe to or have subscribed to.
@param streamId ID of the remote video stream publisher you expect to configure subscription parameters for.
@param remoteVideoConfig The parameters you expect to configure for the remote video stream, see RemoteVideoConfig{@link #RemoteVideoConfig}.
@return API call result:
- 0: Success.
- !0: Failure.
@note
- This API only works after the publisher calls setLocalSimulcastMode{@link #RTCEngine#setLocalSimulcastMode} to enable sending multiple video streams, in which case the subscriber will receive the stream from the publisher that is closest to the set configuration; otherwise the subscriber will only receive one video stream with a resolution of 640px × 360px and a frame rate of 15fps.
- If you don't call this API after the publisher enables the function of publishing multiple streams, you will receive by default the video stream with the largest resolution set by the publisher.
- You should call this API in the room.
- SDK will automatically select the stream to be published or subcribed based on the settings of both sides see for details.
@valid since 3.52
@detail api
@author lichangfeng.rtc
@brief Sets extra information about the RTC room the local user joins.
@param key Key of the extra information, less than 10 bytes in length.
A maximum of 5 keys can exist in the same room, beyond which the first key will be replaced.
@param value Content of the extra information, less than 128 bytes in length.
@return API call result:
- 0: Success with a taskId returned.
- <0: Failure. See SetRoomExtraInfoResult{@link #SetRoomExtraInfoResult} for the reasons.
@note
- Call joinRoom{@link #RTCRoom#joinRoom} first before you call this API to set extra information.
- After calling this API, you will receive onSetRoomExtraInfoResult{@link #IRTCRoomEventHandler#onSetRoomExtraInfoResult} callback informing you the result of the setting.
- After the extra information is successfully set, other users in the same room will receive the information through onRoomExtraInfoUpdate{@link #IRTCRoomEventHandler#onRoomExtraInfoUpdate} callback.
- Users who join the room later will be notified of all extra information in the room set prior to entering.
@detail api
@author shenpengliang
@brief Listens for event callbacks related to the RTCRoom{@link #RTCRoom} instance by setting the event handler of this instance.
@param rtcRoomEventHandler Refer to IRTCRoomEventHandler{@link #IRTCRoomEventHandler}.
@return
- 0: Success.
- < 0 : Fail. See ReturnStatus{@link #ReturnStatus} for more details
@detail api
@brief Listens for event callbacks related to the RTCRoom{@link #RTCRoom} instance by setting the event handler of this instance.
@param rtcRoomEventHandler Refer to IRTSRoomEventHandler{@link #IRTSRoomEventHandler}.
@return
- 0: Success.
- < 0 : Fail. See ReturnStatus{@link #ReturnStatus} for more details
@detail api
@region Stream Management
@brief Sets extra information about the stream the local user publishes.
@param extra_info Extra information of the stream. The length does not exceed 1024 bytes.
@return
- 0: Success.
- < 0: Failure.
@note
- You can use this function to set extra information about the stream the local user publishes. Stream extra information is an additional information attached to the stream ID. Unlike the stream ID, the stream extra information can be modified during the publishing of the corresponding stream ID. Developers can use the stream extra information to synchronize the content of the stream ID with the corresponding stream ID.
- You can call this API before or after you call joinRoom{@link #RTCRoom#joinRoom}.
- Other users in the same room will receive the notification through onRoomStreamExtraInfoUpdate{@link #IRTCRoomEventHandler#onRoomStreamExtraInfoUpdate}.
@detail api
@author shenpengliang
@brief Set the visibility of the user in the room. The local user is visible to others by default before calling this API.
An RTC room can accommodate a maximum of 50 visible users, and 30 media streams can be published simultaneously. For more information, see Room Capacity.
@param enable Visibility of the user in the room.
- true: The user can publish media streams. The other users in the room get informed of the behaviors of the user, such as joining room, starting video capture, and leaving room.
- false: The user cannot publish media streams. The other users in the room do not get informed of the behaviors of the user, such as joining room, starting video capture, or leaving room.
@return
- 0: Success.
- < 0 : Failure. See ReturnStatus{@link #ReturnStatus}.
You will receive onUserVisibilityChanged{@link #IRTCRoomEventHandler#onUserVisibilityChanged} after calling this API. (Available since v3.54)
- If you call this API before joining room, and the set value is different from the default value, you will receive the callback when you join the room.
- If you call this API after joining room, and the current visibility is different from the previous value, you will receive the callback.
- When reconnecting after losing internet connection, if the visibility changes, you will receive the callback.
@note
- You can call this API whether the user is in a room or not.
- When you call this API while you are in the room, the other users in the room will be informed via the following callback.
• When you switch from false to true, they will receive onUserJoined{@link #IRTCRoomEventHandler#onUserJoined}.
• When you switch from true to false, they will receive onUserLeave{@link #IRTCRoomEventHandler#onUserLeave}.
• The invisible user will receive the warning code, WARNING_CODE_PUBLISH_STREAM_FORBIDEN, when trying to publish media streams.
@detail api
@author shenpengliang
@brief Start relaying media stream across rooms.
After calling joinRoom{@link #RTCRoom#joinRoom}, you can call this method to publish the media stream to multiple rooms that applies to scenarios such as an online talent contest and so on.
@param forwardStreamInfos Information of the rooms where you want to relay the media stream to. Refer to ForwardStreamInfo{@link #ForwardStreamInfo} for more information.
@return
- 0: Success.
- < 0: Failure. See ReturnStatus{@link #ReturnStatus} for more details.
@note
- Call this method will trigger onForwardStreamStateChanged{@link #IRTCRoomEventHandler#onForwardStreamStateChanged}.
- After calling this method, listen the events from each room during the relaying by registering onForwardStreamEvent{@link #IRTCRoomEventHandler#onForwardStreamEvent}.
- Once the relaying begins, the other users in the room will receive callback of onUserJoined{@link #IRTCRoomEventHandler#onUserJoined}, onUserPublishStreamVideo{@link #IRTCRoomEventHandler#onUserPublishStreamVideo}, onUserPublishStreamAudio{@link #IRTCRoomEventHandler#onUserPublishStreamAudio}.
- Call updateForwardStreamToRooms{@link #RTCRoom#updateForwardStreamToRooms} to add or remove the designated room(s) after calling this method.
- Call stopForwardStreamToRooms{@link #RTCRoom#stopForwardStreamToRooms} to stop relaying to all rooms after calling this method.
- Call pauseForwardStreamToAllRooms{@link #RTCRoom#pauseForwardStreamToAllRooms} to pause relaying to all rooms after calling this method.
@hidden currently not available
@detail api
@author qiaoxingwang
@brief Recognizes or translates the speech of all speakers in the room and converts the results into captions.
When calling this method, you can choose the subtitle mode in SubtitleMode{@link #SubtitleMode}. If you choose the recognition mode, you will receive the onSubtitleMessageReceived{@link #IRTCRoomEventHandler#onSubtitleMessageReceived} callback which contains the transcribed text.
If you choose the translation mode, you will receive two onSubtitleMessageReceived{@link #IRTCRoomEventHandler#onSubtitleMessageReceived} callbacks simultaneously, one contains the transcribed text and the other contains the translated text.
After calling this method, you will receive the onSubtitleStateChanged{@link #IRTCRoomEventHandler#onSubtitleStateChanged} to inform you of whether subtitles are on.
@param subtitleConfig Subtitle configurations. Refer to SubtitleConfig{@link #SubtitleConfig} for details.
@return
- 0: Success.
- < 0: Failure. See ReturnStatus{@link #ReturnStatus} for more details.
@note
- Call this method after joining the room.
- You can set your source language to Chinese by calling joinRoom and importing a json formatted string "source_language": "zh" through the parameter of extraInfo, to English by importing "source_language": "en" , and to Japanese by importing "source_language": "ja" . If you don't set the source language, SDK will set the language of your system as the source language. If the language of your system is not Chinese, English or Japanese, SDK will set Chinese as the source language.
@detail api
@author shenpengliang
@brief Call to this method to stop relaying media stream to all rooms after calling startForwardStreamToRooms{@link #RTCRoom#startForwardStreamToRooms}.
@return
- 0: Success.
- < 0 : Fail. See ReturnStatus{@link #ReturnStatus} for more details.
@note
- Call this method will trigger onForwardStreamStateChanged{@link #IRTCRoomEventHandler#onForwardStreamStateChanged}.
- The other users in the room will receive callback of onUserJoined{@link #IRTCRoomEventHandler#onUserJoined}, onUserPublishStreamVideo{@link #IRTCRoomEventHandler#onUserPublishStreamVideo}, onUserPublishStreamAudio{@link #IRTCRoomEventHandler#onUserPublishStreamAudio} when you stop relaying.
- To stop relaying media stream to specific rooms, call updateForwardStreamToRooms{@link #RTCRoom#updateForwardStreamToRooms} instead.
- To resume the relaying in a short time, call pauseForwardStreamToAllRooms{@link #RTCRoom#pauseForwardStreamToAllRooms} instead and then call resumeForwardStreamToAllRooms{@link #RTCRoom#resumeForwardStreamToAllRooms} to resume after that.
@hidden currently not available
@detail api
@author qiaoxingwang
@brief Turns off subtitles.
After calling this method, you will receive the onSubtitleStateChanged{@link #IRTCRoomEventHandler#onSubtitleStateChanged} to inform you of whether subtitles are off.
@return
- 0: Success.
- < 0: Failure. See ReturnStatus{@link #ReturnStatus} for more details.
@detail api
@valid since 3.60. Since version 3.60, this interface replaces the subscribeAllStreams and unsubscribeAllStreams methods for the below functions. If you have upgraded to version 3.60 or later and are still using these methods, please migrate to this interface.
@author yejing.luna
@brief Subscribes to or unsubscribes from all remote audio streams.
@param subscribe Whether to subscribe to all remote audio streams:
- true: Subscribe.
- false: Unsubscribe.
@return API call result:
- 0: Success.
- < 0: Failure. See ReturnStatus{@link #ReturnStatus} for more details.
@note
- If the subscription options conflict with the previous ones, they are subject to the configurations in the last call.
- With the Audio selection enabled, if the number of media streams exceeds the limit, we recommend you subscribe each target media stream with the API follows: subscribeStreamVideo{@link #RTCRoom#subscribeStreamVideo}, subscribeStreamAudio{@link #RTCRoom#subscribeStreamAudio}.
- After calling this API, you will be informed of the calling result with onVideoSubscribeStateChanged{@link #IRTCRoomEventHandler#onVideoSubscribeStateChanged}, onAudioSubscribeStateChanged{@link #IRTCRoomEventHandler#onAudioSubscribeStateChanged}. You can also find exceptions cause from the callbacks above.
- Once the local user subscribes to the stream of a remote user, the subscription to the remote user will sustain until the local user leaves the room or unsubscribe from it by calling subscribeStreamVideo{@link #RTCRoom#subscribeStreamVideo}, subscribeStreamAudio{@link #RTCRoom#subscribeStreamAudio}.
@detail api
@valid since 3.60. Since version 3.60, this interface replaces the subscribeAllStreams and unsubscribeAllStreams methods for the below functions. If you have upgraded to version 3.60 or later and are still using these methods, please migrate to this interface.
@author yejing.luna
@brief Subscribes to or unsubscribes from all remote video streams (by the camera).
@param subscribe Whether to subscribe to all remote video streams.
- true: Subscribe.
- false: Unsubscribe.
@return API call result:
- 0: Success.
- < 0: Failure. See ReturnStatus{@link #ReturnStatus} for more details.
@note
- If the subscription options conflict with the previous ones, they are subject to the configurations in the last call.
- With the Audio selection enabled, if the number of media streams exceeds the limit, we recommend you subscribe each target media stream with the API follows: subscribeStreamVideo{@link #RTCRoom#subscribeStreamVideo}, subscribeStreamAudio{@link #RTCRoom#subscribeStreamAudio}.
- After calling this API, you will be informed of the calling result with onVideoSubscribeStateChanged{@link #IRTCRoomEventHandler#onVideoSubscribeStateChanged}, onAudioSubscribeStateChanged{@link #IRTCRoomEventHandler#onAudioSubscribeStateChanged}. You can also find exceptions cause from the callbacks above.
- Once the local user subscribes to the stream of a remote user, the subscription to the remote user will sustain until the local user leaves the room or unsubscribe from it by calling subscribeStreamVideo{@link #RTCRoom#subscribeStreamVideo}, subscribeStreamAudio{@link #RTCRoom#subscribeStreamAudio}.
@detail api
@valid since 3.60. Since version 3.60, this interface replaces the subscribeStream, unsubscribeStream, subscribeScreen and unsubscribeScreen methods for the below functions. If you have upgraded to version 3.60 or later and are still using these methods, please migrate to this interface.
@region Room Management
@author xuyiling.x10
@brief Subscribes to or unsubscribes from the specific remote audio streams captured by the microphone.
@param streamId The ID of the target remote audio stream.
@param subscribe Whether to subscribe to the audio stream.
- true: Subscribe.
- false: Unsubscribe.
@return
- 0: Success.
- < 0 : Fail. See ReturnStatus{@link #ReturnStatus} for more details.
@note
- If you have already subscribed to the remote audio stream (manually or automatically) when you call this method, the subscription configuration will be updated based on the parameters passed in this call.
- You must call onUserPublishStreamAudio{@link #IRTCRoomEventHandler#onUserPublishStreamAudio} callback to get the current remote microphone stream information in the room, and then call this method to subscribe to the remote media streams.
- After you call this method, you will receive onAudioSubscribeStateChanged{@link #IRTCRoomEventHandler#onAudioSubscribeStateChanged} notification method call results.
- After you successfully subscribe to the remote audio stream, the subscription relationship will continue until you call subscribeStreamAudio{@link #RTCRoom#subscribeStreamAudio} to unsubscribe from it or the local user leaves the room.
- Any other exceptions will be included in onAudioSubscribeStateChanged{@link #IRTCRoomEventHandler#onAudioSubscribeStateChanged} callback notification.
@detail api
@valid since 3.60. Since version 3.60, this interface replaces the subscribeStream, unsubscribeStream, subscribeScreen and unsubscribeScreen methods for the below functions. If you have upgraded to version 3.60 or later and are still using these methods, please migrate to this interface.
@brief Subscribes to or unsubscribes from the specific remote video streams captured by the camera.
@param streamId The ID of the target remote video stream.
@param subscribe Whether to subscribe to the video stream.
- true: Subscribe.
- false: Unsubscribe.
@return
- 0: Success.
- < 0 : Fail. See ReturnStatus{@link #ReturnStatus} for more details.
@note
- If you have already subscribed to the remote stream (manually or automatically) when you call this method, the subscription configuration will be updated based on the parameters passed in this call.
- You must call onUserPublishStreamVideo{@link #IRTCRoomEventHandler#onUserPublishStreamVideo} callback to get the current remote camera stream information in the room, and then call this method to subscribe to the remote media streams.
- After you call this method, you will receive onVideoSubscribeStateChanged{@link #IRTCRoomEventHandler#onVideoSubscribeStateChanged} notification method call results.
- After you successfully subscribe to the remote video stream, the subscription relationship will continue until you call subscribeStreamVideo{@link #RTCRoom#subscribeStreamVideo} to unsubscribe from it or the local user leaves the room.
- Any other exceptions will be included in onVideoSubscribeStateChanged{@link #IRTCRoomEventHandler#onVideoSubscribeStateChanged} callback notification.
@detail api
@author shenpengliang
@brief Update information of the rooms where you want to relay the media stream to after calling startForwardStreamToRooms{@link #RTCRoom#startForwardStreamToRooms}.
Adding and removing rooms by calling this method will trigger onForwardStreamStateChanged{@link #IRTCRoomEventHandler#onForwardStreamStateChanged} on the local.
@param forwardStreamInfos Information of the rooms where you want to relay the media stream to. Refer to ForwardStreamInfo{@link #ForwardStreamInfo} for more information.
@return
- 0: Success.
- < 0: Failure. See ReturnStatus{@link #ReturnStatus} for more details.
@note
Users in the room which is added or removed from the target list by calling this method will receive onUserJoined{@link #IRTCRoomEventHandler#onUserJoined}, onUserPublishStreamVideo{@link #IRTCRoomEventHandler#onUserPublishStreamVideo}, onUserPublishStreamAudio{@link #IRTCRoomEventHandler#onUserPublishStreamAudio}.
@detail api
@author luomingkang
@brief Updates the Token of the game room.
You must call this API to update token to ensure the RTC call to continue when you receive onTokenWillExpire{@link #IRTCRoomEventHandler#onTokenWillExpire}, onPublishPrivilegeTokenWillExpire{@link #IRTCRoomEventHandler#onPublishPrivilegeTokenWillExpire}, or onSubscribePrivilegeTokenWillExpire{@link #IRTCRoomEventHandler#onSubscribePrivilegeTokenWillExpire}.
@param token Valid token.
If the Token is invalid, you will receive onRoomStateChanged{@link #IRTCRoomEventHandler#onRoomStateChanged} with the error code of -1010.
@return API call result:
- 0: Success.
- <0: Failure. See ReturnStatus{@link #ReturnStatus} for specific reasons.
@note Do not call both updateToken{@link #IGameRoom#updateToken} and joinRoom{@link #IGameRoom#joinRoom} to update the Token. If you fail to join the room or have been removed from the room due to an expired or invalid Token, call joinRoom{@link #IGameRoom#joinRoom} with a valid token to rejoin the room.
