<INERtcChannel> Protocol Reference

The INERtcChannel class provides methods that enable real-time communications in a specified channel. More...

#import <INERtcChannel.h>

Inheritance diagram for <INERtcChannel>:

Instance Methods
(int)	- destroy
	Destroys an IRtcChannel instance to release resources. More...
(int)	- setChannelDelegate:
	Sets the channel delegate. More...
(NSString *)	- getChannelName
	Gets the current channel name. More...
(NERtcConnectionStateType)	- connectionState
	Gets the connection status. More...
(int)	- joinChannelWithToken:completion:
	Joins an RTC room. More...
(int)	- leaveChannel
	Leaves a room, such as hanging up or ending a call. More...
(int)	- enableLocalAudio:
	Enables or disables local audio capture. More...
(int)	- enableLocalVideo:
	Specifies whether to enable local video capture. More...
(int)	- enableMediaPub:withMediaType:
	Publishes or unpublishes the local audio stream. More...
(int)	- enableDualStreamMode:
	Enables or disables the dual-stream mode. More...
(int)	- setCameraCaptureConfig:
	Sets the camera capturer configuration. More...
(int)	- setLocalVideoConfig:
	Sets the video encoding profile. More...
(int)	- subscribeRemoteAudio:forUserID:
	Subscribes to or unsubscribes from audio streams from specified remote users. More...
(int)	- subscribeAllRemoteAudio:
	Subscribes to or unsubscribes from audio streams from all remote users. More...
(int)	- setAudioSubscribeOnlyBy:
	Sets the local audio stream can be subscribed by specified participants in a room. More...
(int)	- muteLocalAudio:
	Stops or resumes publishing the local audio stream. More...
(int)	- setupLocalVideoCanvas:
	Sets the local view. More...
(int)	- setLocalRenderScaleMode:
	Sets the local video display mode. More...
(int)	- setupRemoteVideoCanvas:forUserID:
	Sets views for remote users. More...
(int)	- setRemoteRenderScaleMode:forUserID:
	Sets the remote video display mode. More...
(int)	- subscribeRemoteVideo:forUserID:streamType:
	Subscribes to or unsubscribes from video streams from specified remote users. More...
(int)	- muteLocalVideo:
	Stops or resumes publishing the local video stream. More...
(int)	- setClientRole:
	Sets the role of a user in live streaming. More...
(int)	- adjustUserPlaybackSignalVolume:forUserID:
	Adjust the volume of local signal playback from a specified remote user. More...
(int)	- enableLocalSubStreamAudio:
	Enables or disables the audio substream. More...
(int)	- subscribeRemoteSubStreamAudio:forUserID:
	Subscribes or unsubscribes audio streams from specified remote users. More...
(int)	- muteLocalSubStreamAudio:
	Mutes or unmutes the local upstream audio stream. More...
(int)	- setupLocalSubStreamVideoCanvas:
	Sets the local substream canvas. More...
(int)	- startScreenCapture:
	Enables screen sharing. More...
(int)	- stopScreenCapture
	Disables screen sharing with the substream transmission. More...
(int)	- setLocalRenderSubStreamScaleMode:
	Sets the display mode of the local substream video for screen sharing. More...
(int)	- setupRemoteSubStreamVideoCanvas:forUserID:
	Sets a remote substream canvas. More...
(int)	- subscribeRemoteSubStreamVideo:forUserID:
	Subscribes to or unsubscribes from remote video substream for screen sharing. More...
(int)	- setRemoteRenderSubStreamVideoScaleMode:forUserID:
	Sets the display mode of to remote substream video for screen sharing. More...
(int)	- setRemoteHighPriorityAudioStream:forUserID:streamType:
	Sets a remote audio stream to high priority. More...
(int)	- setLocalCanvasWatermarkConfigs:withStreamType:
	Adds a watermark image to the local video. More...
(int)	- setRemoteCanvasWatermarkConfigs:forUserID:withStreamType:
	Adds a watermark to the remote video canvas. More...
(int)	- takeLocalSnapshot:callback:
	Takes a local video snapshot. More...
(int)	- takeRemoteSnapshot:forUserID:callback:
	Takes a snapshot of a remote video. More...
(int)	- sendSEIMsg:streamChannelType:
	Sends supplemental enhancement information (SEI) data through a specified mainstream or substream. More...
(int)	- sendSEIMsg:
	Sends SEI data through the mainstream. More...
(int)	- addLiveStreamTask:compeltion:
	Adds a streaming task in a room. More...
(int)	- updateLiveStreamTask:compeltion:
	Updates a streaming task. More...
(int)	- removeLiveStreamTask:compeltion:
	Deletes a streaming task. More...
(int)	- addChannelMediaStatsObserver:
	Registers a channel media stats observer. More...
(int)	- removeChannelMediaStatsObserver:
	Remove a channel media stats observer. More...
(int)	- cleanupChannelMediaStatsObserver
	Remove all channel media stats observers. More...
(int)	- startChannelMediaRelay:
	Starts to relay media streams across rooms. More...
(int)	- updateChannelMediaRelay:
	Updates the information of the destination room for media stream relay. More...
(int)	- stopChannelMediaRelay
	Stops media stream relay across rooms. More...
(int)	- setLocalMediaPriority:preemptive:
	Sets the priority of media streams from a local user. More...
(int)	- setLocalPublishFallbackOption:
	Sets the fallback option for the published local video stream based on the network conditions. More...
(int)	- setRemoteSubscribeFallbackOption:
	Sets the fallback option for the subscribed remote audio and video stream with poor network connections. More...

Detailed Description

The INERtcChannel class provides methods that enable real-time communications in a specified channel.

By creating multiple NERtcChannel instances, users can join multiple channels.

Since

V4.5.0

Method Documentation

addChannelMediaStatsObserver:

- (int) addChannelMediaStatsObserver:

(id< NERtcChannelMediaStatsObserver >)

observer

Registers a channel media stats observer.

Since

V4.5.0

Parameters

observer

The stats observer. For more information, see NERtcChannelMediaStatsObserver。

Returns

The value returned. A value of 0 indicates that the operation is successful.

addLiveStreamTask:compeltion:

- (int) addLiveStreamTask:		(NERtcLiveStreamTaskInfo *)	taskInfo
compeltion:		(NERtcLiveStreamCompletion)	completion

Adds a streaming task in a room.

After you call the method, the current user can receive a notification about the status of live streaming.

Note

• The method is applicable to only live streaming.
• You can call the method when you are in a room. The method is valid for calls.
• Only one URL for the relayed stream is added in each call. You need to call the method multiple times if you want to push many streams. An RTC room with the same channelid can create three different streaming tasks.

Since

V4.5.0

Parameters

taskInfo	The information about the streaming task. For more information, NERtcLiveStreamTaskInfo.
completion	The result. The callback is triggered after the method is called. For more information, see NERtcLiveStreamCompletion.

Returns

The value returned. A value of 0 indicates that the operation is successful.

adjustUserPlaybackSignalVolume:forUserID:

- (int) adjustUserPlaybackSignalVolume:		(uint32_t)	volume
forUserID:		(uint64_t)	userID

Adjust the volume of local signal playback from a specified remote user.

After you join the room, you can call the method to set the volume of local audio playback from different remote users or repeatedly adjust the volume of audio playback from a specified remote user.

Note

• You can call this method after you join a room.
• The method is valid in the current call. If a remote user exits the room and rejoins the room again, the setting is still valid until the call ends.
• The method adjusts the volume of the mixing audio published by a specified remote user. Only one remote user can be adjusted. If you want to adjust multiple remote users, you need to call the method for the required times.

Since

V4.5.0

Parameters

userID	The ID of a remote user.
volume	The playback volume. Valid values: 0 to 100. 0: muted 100: the original volume

Returns

The value returned. A value of 0 indicates that the operation is successful.

cleanupChannelMediaStatsObserver

- (int) cleanupChannelMediaStatsObserver

Remove all channel media stats observers.

Since

V4.5.0

Returns

The value returned. A value of 0 indicates that the operation is successful.

connectionState

- (NERtcConnectionStateType) connectionState

Gets the connection status.

Since

V4.5.0

Returns

The current channel status is returned.

destroy

- (int) destroy

Destroys an IRtcChannel instance to release resources.

Since

V4.5.0

enableDualStreamMode:

- (int) enableDualStreamMode:

(BOOL)

enable

Enables or disables the dual-stream mode.

The method sets the individual-stream mode or dual-stream mode. If the dual-stream mode is enabled on the publishing client, the receiver can choose to receive the high-quality stream or low-quality stream video. The high-quality stream has a high resolution and high bitrate. The low-quality stream has a low resolution and low bitrate.

Note

• The audio-only SDK disables this API. If you need to use the API, you can download the standard SDK from the official website of CommsEase and replace the audio-only SDK.
• The method applies to only camera data. Video streams from external input and screen sharing are not affected.
• You can call this method before or after you join a room.

Since

V4.5.0

Parameters

enable

A value of YES indicates that the dual-stream mode is enabled. A value of NO indicates that the dual stream mode is disabled.

Returns

The value returned. A value of 0 indicates that the operation is successful.

enableLocalAudio:

- (int) enableLocalAudio:

(BOOL)

enabled

Enables or disables local audio capture.

<brWhen an app joins a room, the voice module is enabled by default. <brThe method does not affect receiving or playing back the remote audio stream. The enableLocalAudio(NO) method is suitable for scenarios where a user wants to receive the remote audio stream without sending audio streams to other users in the room.

Note

• The enableLocalAudio method is different from muteLocalAudioStream. The enableLocalAudio method is used to enable local audio capture and processing whereas the muteLocalAudioStream method is used to stop or restart pushing the local audio stream.
• The method enables the internal engine. The setting remains unchanged after the leaveChannel method is called.
• Starting from V4.4.0, turning on or off local audio capture does not affect the playback of music files. You can still play music files by calling startAudioMixingWithOption after you set enableLocalAudio(NO).

Since

V4.5.0

Parameters

enabled

The option whether to enable local Audio capture.

Returns

The value returned. A value of 0 indicates that the operation is successful.

enableLocalSubStreamAudio:

- (int) enableLocalSubStreamAudio:

(BOOL)

enabled

Enables or disables the audio substream.

If the audio substream is enabled, remote clients will get notified by NERtcChannelDelegate#onNERtcChannelUserSubStreamAudioDidStart:, and NERtcChannelDelegate#onNERtcChannelUserSubStreamAudioDidStop: when the audio stream is disabled.

Since

V4.6.10

Parameters

enabled

specifies whether to enable the audio substream. true: enables the audio substream. false: disable the audio substream.

Returns

• 0: success
• Others: failure

enableLocalVideo:

- (int) enableLocalVideo:

(BOOL)

enabled

Specifies whether to enable local video capture.

Note

• You can call this method before or after you join a room.
• After you enable or disable local video capture, the onNERtcEngineUserVideoDidStartWithUserID or onNERtcEngineUserVideoDidStop callback is triggered on a remote client.

Parameters

enabled

The option whether to enable local video capture.

Since

V4.5.0

Returns

The value returned. A value of 0 indicates that the operation is successful.

enableMediaPub:withMediaType:

- (int) enableMediaPub:		(BOOL)	enabled
withMediaType:		(NERtcMediaPubType)	mediaType

Publishes or unpublishes the local audio stream.

When a user joins a room, the feature is enabled by default.
The method does not affect receiving or playback remote audio streams. The enableLocalAudio(false) method is suitable for scenarios where only downstream data is received without upstream data.

Note

• The method controls only the main stream.
• The method can be called before or after a user joins a room.

Since

V4.6.10

Parameters

enabled	specifies whether to publish the local audio stream. YES(default): publishes the local audio stream. NO: unpublishes the local audio stream.
mediaType	media type. Only the audio is supported.

Returns

• 0: success.
• Others: failure

getChannelName

- (NSString *) getChannelName

Gets the current channel name.

Since

V4.5.0

Returns

• Success: Return IRtcChannel channel name.
• Fail: Return nothing.

joinChannelWithToken:completion:

- (int) joinChannelWithToken:		(NSString *)	token
completion:		(NERtcJoinChannelCompletion)	completion

Joins an RTC room.

If the specified room does not exist when you join the room, a room with the specified name is automatically created in the server provided by CommsEase.

• After you join a room by calling the relevant method supported by the SDK, users in the same room can make audio or video calls. Users that join the same room can start a group chat. Apps that use different AppKeys cannot communicate with each other.
• If you join a room by calling this method, onNERtcEngineUserDidJoinWithUserID is triggered on a remote client.
• If you join a room, you subscribe to the audio streams from other users in the same room by default. In this case, the data usage is billed. To unsubscribe, you can call the mute method.

Since

V4.5.0

Parameters

token

The certification signature used in authentication (NERTC Token). Valid values: null。 You can set the value to null in the debugging mode. This poses a security risk. We recommend that you contact your business manager to change to the default safe mode before your product is officially launched. NERTC Token acquired. In safe mode, the acquired token must be specified. If the specified token is invalid, users are unable to join a room. We recommend that you use the safe mode.

completion

The callback when the operation is complete.

Returns

The value returned. A value of 0 indicates that the operation is performed.

leaveChannel

- (int) leaveChannel

Leaves a room, such as hanging up or ending a call.

A user must call the leaveChannel method to end the call before the user makes another call. After you leave the room by calling the method, the onNERtcEngineDidLeaveChannelWithResult callback is triggered on the local client, and the onNERtcEngineUserDidLeaveWithUserID callback is triggered on a remote client.

Since

V4.5.0

Returns

The value returned. A value of 0 indicates that the operation is successful.

muteLocalAudio:

- (int) muteLocalAudio:

(BOOL)

muted

Stops or resumes publishing the local audio stream.

The method is used to stop or resume publishing the local audio stream.

Note

• This method does not change the audio capture state because the audio capture devices are not disabled.
• The mute state is reset to unmuted after the call ends.

Since

V4.5.0

Parameters

muted

The option whether to enable publishing the local audio stream.

Returns

The value returned. A value of 0 indicates that the operation is successful.

muteLocalSubStreamAudio:

- (int) muteLocalSubStreamAudio:

(BOOL)

muted

Mutes or unmutes the local upstream audio stream.

Note

The muted state will be reset to unmuted after a call ends.

Since

V4.6.10

Parameters

muted

specifies whether to mute a local audio stream. true (default): mutes a local audio stream. false: unmutes a local audio stream.

Returns

• 0: success
• Others: failure

muteLocalVideo:

- (int) muteLocalVideo:

(BOOL)

muted

Stops or resumes publishing the local video stream.

If you call the method successfully, the remote client triggers the onNERtcEngineUser:videoMuted: callback.

Note

• The audio-only SDK disables this API. If you need to use the API, you can download the standard SDK from the official website of CommsEase and replace the audio-only SDK.
• If you call this method to stop publishing the local video stream, the SDK no longer publishes the local video stream. You can call the method before or after you join a room.
• If you stop publishing the local video stream by calling this method, the setting is reset to the default state that allows the app to publish the local video stream.
• The method is different from enableLocalVideo. The enableLocalVideo method turns off local camera devices. The muteLocalVideovideo method does not affect local video capture, or disables cameras, and responds faster.

Since

V4.5.0

Parameters

muted

The option whether to stop publishing the local video stream.

Returns

The value returned. A value of 0 indicates that the operation is successful.

removeChannelMediaStatsObserver:

- (int) removeChannelMediaStatsObserver:

(id< NERtcChannelMediaStatsObserver >)

observer

Remove a channel media stats observer.

Since

V4.5.0

Parameters

observer

The stats observer. For more information, see NERtcChannelMediaStatsObserver。

Returns

The value returned. A value of 0 indicates that the operation is successful.

removeLiveStreamTask:compeltion:

- (int) removeLiveStreamTask:		(NSString *)	taskId
compeltion:		(NERtcLiveStreamCompletion)	completion

Deletes a streaming task.

Note

• The method is applicable to only live streaming.
• You can call the method when you are in a room. The method is valid for calls.

Since

V4.5.0

Parameters

taskId	The ID of a streaming task.
completion	The result. The callback is triggered after the method is called. For more information, see NERtcLiveStreamCompletion.

Returns

The value returned. A value of 0 indicates that the operation is successful.

sendSEIMsg:

- (int) sendSEIMsg:

(NSData *)

data

Sends SEI data through the mainstream.

When you publish the local audio and video stream, SEI data is also sent to sync some additional information. After SEI data is sent, the receiver can retrieve the content by listening for the onRecvSEIMsg callback.

• Condition: After you publish the video stream using the mainstream and substream, you can invoke the method.
• Data limit in length: The SEI data can contain a maximum of 4,096 bytes in size. Sending an SEI message fails if the data exceeds the size limit. If a large amount of data is sent, the video bitrate rises. This degrades the video quality or causes broken video frames.
• Frequency limit: We recommend that the maximum video frame rate does not exceed 10 fps.
• Time to take effect: After the method is called, the SEI data is sent from the next frame in the fastest fashion or after the next 5 frames at the slowest pace.

Note

• The SEI data is transmitted together with the video stream. If video frame loss occurs due to poor connection quality, the SEI data will also get dropped. We recommend that you increase the frequency within the transmission limits. This way, the receiver can get the data.
• By default, the SEI is transmitted by using the mainstream.
• The audio-only SDK disables this API. If you need to use the API, you can download the standard SDK from the official website of CommsEase and replace the audio-only SDK.

Since

V4.5.0

Parameters

data	The custom SEI data.

Returns

The value returned. A value of 0 indicates that the operation is successful. -Success: The SEI data joins the queue and is ready for delivery. The data will be sent after the most recent video frame. -Failure: If the data is restricted, the frequency may be too high, the queue is full, or the data size exceeds the maximum value of 4k

sendSEIMsg:streamChannelType:

- (int) sendSEIMsg:		(NSData *)	data
streamChannelType:		(NERtcStreamChannelType)	type

Sends supplemental enhancement information (SEI) data through a specified mainstream or substream.

When you publish the local audio and video stream, SEI data is also sent to sync some additional information. After SEI data is sent, the receiver can retrieve the content by listening for the onRecvSEIMsg callback.

• Condition: After you publish the video stream using the mainstream and substream, you can invoke the method.
• Data limit in length: The SEI data can contain a maximum of 4,096 bytes in size. Sending an SEI message fails if the data exceeds the size limit. If a large amount of data is sent, the video bitrate rises. This degrades the video quality or causes frozen frames.
• Frequency limit: We recommend that the maximum video frame rate does not exceed 10 fps.
• Time to take effect: After the method is called, the SEI data is sent from the next frame in the fastest fashion or after the next 5 frames at the slowest pace.

Note

• The SEI data is transmitted together with the video stream. If video frame loss occurs due to poor connection quality, the SEI data will also get dropped. We recommend that you increase the frequency within the transmission limits. This way, the receiver can get the data.
• Before you specify a channel to transmit the SEI data, you must first enable the data transmission channel.
• The audio-only SDK disables this API. If you need to use the API, you can download the standard SDK from the official website of CommsEase and replace the audio-only SDK.

Since

V4.5.0

Parameters

data	The custom SEI data.
type	The type of the channel with which the SEI data is transmitted. For more information, see NERtcStreamChannelType.

Returns

The value returned. A value of 0 indicates that the operation is successful. -Success: The SEI data joins the queue and is ready for delivery. The data will be sent after the most recent video frame. -Failure: If the data is restricted, the frequency may be too high, the queue is full, or the data exceeds the maximum value of 4k.

setAudioSubscribeOnlyBy:

- (int) setAudioSubscribeOnlyBy:

(NSArray< NSNumber * > *)

uidArray

Sets the local audio stream can be subscribed by specified participants in a room.

All participants in the room can subscribe to the local audio stream by default.

Note

• The API must be called after a user joins a room.
• The API cannot be called by user IDs out of the room.

Since

V4.6.10

Parameters

uidArray

The list of user IDs that can subscribe to the local audio stream.

Note

The list contains all participants in a room. If the value is empty or null, all participants can subscribe to the local audio stream.

Returns

• 0: success
• Others: failure.

setCameraCaptureConfig:

- (int) setCameraCaptureConfig:

(NERtcCameraCaptureConfiguration *)

config

Sets the camera capturer configuration.

For a video call or live streaming, generally the SDK controls the camera output parameters. By default, the SDK matches the most appropriate resolution based on the user's setLocalVideoConfig configuration. When the default camera capture settings do not meet special requirements, we recommend using this method to set the camera capturer configuration:

• If you want better quality for the local video preview, we recommend setting config as kNERtcCameraOutputQuality. The SDK sets the camera output parameters with higher picture quality.
• To customize the width and height of the video image captured by the local camera, set the camera capture configuration as kNERtcCameraOutputManual.

Note

• Call this method before or after joining the channel. The setting takes effect immediately without restarting the camera.
• Higher collection parameters means higher performance consumption, such as CPU and memory usage, especially when video pre-processing is enabled.

Since

V4.5.0

Parameters

config

The camera capturer configuration.

Returns

0 A value of 0 returned indicates that the method call is successful. Otherwise, the method call fails.

setChannelDelegate:

- (int) setChannelDelegate:

(id< NERtcChannelDelegate >)

channelDelegate

Sets the channel delegate.

Since

V4.5.0

Parameters

channelDelegate

The channel delegate.

Returns

The value returned. A value of 0 indicates that the operation is successful.

setClientRole:

- (int) setClientRole:

(NERtcClientRole)

role

Sets the role of a user in live streaming.

The method sets the role to host or audience. The permissions of a host and an audience are different.

• A host has the permissions to open or close a camera, publish streams, call methods related to publishing streams in interactive live streaming. The status of the host is visible to the users in the room when the host joins or leaves the room.
• The audience has no permissions to open or close a camera, call methods related to publishing streams in interactive live streaming, and is invisible to other users in the room when the user that has the audience role joins or leaves the room.

Note

• By default, a user joins a room as a host. Before a user joins a room, the user can call this method to change the client role to the audiences. After a user joins a room, the user can call this method to switch the client role.
• If the user switches the role to the audiences, the SDK automatically closes the audio and video devices.

Since

V4.5.0

Parameters

role	The role of a user. For more information, see NERtcClientRole.

Returns

The value returned. A value of 0 indicates that the operation is successful.

setLocalCanvasWatermarkConfigs:withStreamType:

- (int) setLocalCanvasWatermarkConfigs:		(nullable NERtcCanvasWatermarkConfig *)	config
withStreamType:		(NERtcStreamChannelType)	type

Adds a watermark image to the local video.

Note

• The setLocalCanvasWatermarkConfigs method applies to the local video canvas and does not affect the video stream. If the canvas is removed, the watermark will be automatically deleted.
• Before you set a watermark, you must first set the canvas by calling related methods.

Since

V4.5.0

Parameters

type	The type of video streams. You can set the value to mainstream or substream. For more information, see NERtcStreamChannelType.
config	The configuration of the watermark for the canvas. You can set text watermark, image watermark, and timestamp watermark. A value of null indicates removing the watermark. For more information, see NERtcCanvasWatermarkConfig.

Note

The API is disabled in the audio-only SDK. If you need to use the API, you can download the standard SDK from the official website of CommsEase and replace the audio-only SDK.

Returns

The value returned. A value of 0 indicates that the operation is successful.

setLocalMediaPriority:preemptive:

- (int) setLocalMediaPriority:		(NERtcMediaPriorityType)	priority
preemptive:		(BOOL)	preemptive

Sets the priority of media streams from a local user.

If a user has a high priority, the media stream from the user also has a high priority. In unreliable network connections, the SDK guarantees the quality of the media stream from users with a high priority.

Note

• You must call the method before you call joinChannel.
• After you switch the room by calling switchChannel, the media stream priority is restored to the default normal priority.

Since

V4.5.0

Parameters

priority

The priority of the local media stream. The default value is kNERtcMediaPriorityNormal, which indicates the normal priority. For more information, see NERtcMediaPriorityType.

preemptive

The option whether to enable the preempt mode. If the preempt mode is enabled, the local media stream preempts the high priority over other users. The priority of the media stream whose priority is taken becomes normal. After the user who preempts the priority leaves the room, other users still keep the normal priority. If the preempt mode is disabled, and a user in the room has a high priority, then, the high priority of the local client remains invalid and is still normal.

Returns

The value returned. A value of 0 indicates that the operation is successful.

setLocalPublishFallbackOption:

- (int) setLocalPublishFallbackOption:

(NERtcStreamFallbackOptions)

option

Sets the fallback option for the published local video stream based on the network conditions.

The quality of the published local audio and video streams is degraded with poor quality network connections. After you call this method and set the option to kNERtcStreamFallbackOptionAudioOnly:

• With unreliable uplink network connections and the quality of audio and video streams degraded, the SDK switches to receive a low-quality video stream or stops receiving video streams. This way, the audio quality is maintained or improved.
• The SDK monitors the network performance and recover audio and video streams if the network quality improves.
• If the published audio and video stream from the local client falls back to the audio stream, or recovers to the audio and video stream, the SDK triggers the onLocalPublishFallbackToAudioOnly callback.

Note

You must call the method before you call joinChannel.

Since

V4.5.0

Parameters

option

The fallback options for publishing audio and video streams. The default value is disabled. For more information, see NERtcStreamFallbackOptions.

Returns

The value returned. A value of 0 indicates that the operation is successful.

setLocalRenderScaleMode:

- (int) setLocalRenderScaleMode:

(NERtcVideoRenderScaleMode)

mode

Sets the local video display mode.

Note

The audio-only SDK disables this API. If you need to use the API, you can download the standard SDK from the official website of CommsEase and replace the audio-only SDK.

Since

V4.5.0

Parameters

mode	The video display mode. For more information, see NERtcVideoRenderScaleMode.

Returns

The value returned. A value of 0 indicates that the operation is successful.

setLocalRenderSubStreamScaleMode:

- (int) setLocalRenderSubStreamScaleMode:

(NERtcVideoRenderScaleMode)

mode

Sets the display mode of the local substream video for screen sharing.

Use this method if you want to enable screen sharing through the local substream. Apps can call this method multiple times to change the display mode.

Note

• The audio-only SDK disables this API. If you need to use the API, you can download the standard SDK from the official website of CommsEase and replace the audio-only SDK.
• Before you can call this method, you must set up the canvas for the local substream by calling setupLocalSubStreamVideoCanvas.

Since

V4.5.0

Parameters

mode	The video display mode. For more information, see NERtcVideoRenderScaleMode.

Returns

The value returned. A value of 0 indicates that the operation is successful.

setLocalVideoConfig:

- (int) setLocalVideoConfig:

(NERtcVideoEncodeConfiguration *)

config

Sets the video encoding profile.

Note

• The audio-only SDK disables this API. If you need to use the API, you can download the standard SDK from the official website of CommsEase and replace the audio-only SDK.
• You can call this method before or after you join the room.
• After the setting is configured. The setting takes effect the next time local video is enabled.
• Each profile has a set of video parameters, such as resolution, frame rate, and bitrate. All the specified values of the parameters are the maximum values in optimal conditions. If the video engine cannot use the maximum value of resolution, frame rate, or bitrate due to unreliable network conditions, the value closest to the maximum value is used.

Parameters

config

The video encoding profile. For more information, see NERtcVideoEncodeConfiguration.

Returns

The value returned. A value of 0 indicates that the operation is successful.

setRemoteCanvasWatermarkConfigs:forUserID:withStreamType:

- (int) setRemoteCanvasWatermarkConfigs:		(nullable NERtcCanvasWatermarkConfig *)	config
forUserID:		(uint64_t)	userID
withStreamType:		(NERtcStreamChannelType)	type

Adds a watermark to the remote video canvas.

Note

• The setRemoteCanvasWatermarkConfigs method Adds a watermark to the remote video canvas and does not affect the video stream. If the canvas is removed, the watermark will be automatically deleted.
• Before you set a watermark, you must first set the canvas by calling related methods.

Since

V4.5.0

Parameters

userID	The ID of a remote user.
type	The type of video streams. You can set the value to mainstream or substream. For more information, see NERtcStreamChannelType.
config	The configuration of the watermark for the canvas. You can set text watermark, image watermark, and timestamp watermark. A value of null indicates to remove the watermark. For more information, see NERtcCanvasWatermarkConfig.

Note

The API is disabled in the audio-only SDK. If you need to use the API, you can download the standard SDK from the official website of CommsEase and replace the audio-only SDK.

Returns

The value returned. A value of 0 indicates that the operation is successful.

setRemoteHighPriorityAudioStream:forUserID:streamType:

- (int) setRemoteHighPriorityAudioStream:		(BOOL)	enable
forUserID:		(uint64_t)	userID
streamType:		(NERtcAudioStreamType)	streamType

Sets a remote audio stream to high priority.

If a remote audio stream is set to high priority during automatic stream subscription, users can hear the audio stream with high priority.

Note

• You must set the API during calling with automatic subscription enabled (default)。
• The API can only set one audio stream to high priority. Subsequent settings will override the previous ones.
• If a call ends, the priority setting will be reset.

Since

V4.6.0

Parameters

enable	enables or disables the high priority of a remote audio stream true：sets the high priority of a remote audio stream. false：Does not set the high priority of a remote audio stream.
userID	User ID
streamType	The type of subscribed audio stream. The default type is kNERtcAudioStreamMain.

Returns

• 0:success
• Others: failure

setRemoteRenderScaleMode:forUserID:

- (int) setRemoteRenderScaleMode:		(NERtcVideoRenderScaleMode)	mode
forUserID:		(uint64_t)	userID

Sets the remote video display mode.

Note

The audio-only SDK disables this API. If you need to use the API, you can download the standard SDK from the official website of CommsEase and replace the audio-only SDK.

Since

V4.5.0

Parameters

mode	The video display mode. For more information, see NERtcVideoRenderScaleMode.
userID	The ID of a remote user.

Returns

The value returned. A value of 0 indicates that the operation is successful.

setRemoteRenderSubStreamVideoScaleMode:forUserID:

- (int) setRemoteRenderSubStreamVideoScaleMode:		(NERtcVideoRenderScaleMode)	mode
forUserID:		(uint64_t)	userID

Sets the display mode of to remote substream video for screen sharing.

Note

• The audio-only SDK disables this API. If you need to use the API, you can download the standard SDK from the official website of CommsEase and replace the audio-only SDK.
• Before you call this API, you must subscribe to the remote video substream for screen sharing by using subscribeRemoteSubStreamVideo.

Since

V4.5.0

Parameters

mode	The video display mode. For more information, see NERtcVideoRenderScaleMode.
userID	The ID of a remote user.

Returns

The value returned. A value of 0 indicates that the operation is successful.

setRemoteSubscribeFallbackOption:

- (int) setRemoteSubscribeFallbackOption:

(NERtcStreamFallbackOptions)

option

Sets the fallback option for the subscribed remote audio and video stream with poor network connections.

The quality of the subscribed audio and video streams is degraded with unreliable network connections. After you set the fallback options for the subscribed audio and video stream by using this method:

• With unreliable downstream network connections, the SDK switches to receive a low-quality video stream or stops receiving video streams. This way, the audio quality is maintained or improved.
• The SDK monitors the network quality and resumes the video stream when the network conditions improve.
• If the subscribed remote video stream falls back to an audio-only stream, or the audio-only stream switches back to the video stream, the SDK triggers the onNERtcEngineRemoteSubscribeFallbackToAudioOnly callback.

Note

You must call the method before you call joinChannel.

Since

V4.5.0

Parameters

option

The fallback option for subscribing to audio and video streams. The default setting is to fall back to the low-quality video stream in the poor network. For more information, see NERtcStreamFallbackOptions.

Returns

The value returned. A value of 0 indicates that the operation is successful.

setupLocalSubStreamVideoCanvas:

- (int) setupLocalSubStreamVideoCanvas:

(NERtcVideoCanvas *)

canvas

Sets the local substream canvas.

This method is used to set the display information about the local screen sharing with the substream video. The app associates with the video view of local substream by calling this method. During application development, in most cases, before joining a room, you must first call this method to set the local video view after the SDK is initialized.

Note

• If the app uses external rendering, we recommend that you set the video view before you join the room.
• Before you join a room, you must call the method after the SDK is initialized.
• A canvas is configured for only one user.
• The audio-only SDK disables this API. If you need to use the API, you can download the standard SDK from the official website of CommsEase and replace the audio-only SDK.

Since

V4.5.0

Parameters

canvas

The video canvas. For more information, see NERtcVideoCanvas. To delete the canvas setting, set the value to nil.

Returns

The value returned. A value of 0 indicates that the operation is successful.

setupLocalVideoCanvas:

- (int) setupLocalVideoCanvas:

(NERtcVideoCanvas *_Nullable)

canvas

Sets the local view.

This method is used to set the display information about the local video. The method is applicable only to local users. Remote users are not affected. Apps can call this API operation to associate with the view that plays local video streams. During application development, in most cases, before joining a room, you must first call this method to set the local video view after the SDK is initialized.

Note

The audio-only SDK disables this API. If you need to use the API, you can download the standard SDK from the official website of CommsEase and replace the audio-only SDK.

Since

V4.5.0

Parameters

canvas

The video canvas. For more information, see NERtcVideoCanvas. If you want to delete the canvas, you can set the value to nil.

Returns

The value returned. A value of 0 indicates that the operation is successful.

setupRemoteSubStreamVideoCanvas:forUserID:

- (int) setupRemoteSubStreamVideoCanvas:		(NERtcVideoCanvas *)	canvas
forUserID:		(uint64_t)	userID

Sets a remote substream canvas.

The method associates a remote user with a substream view. You can assign a specified userID to use a corresponding canvas.

Note

• The audio-only SDK disables this API. If you need to use the API, you can download the standard SDK from the official website of CommsEase and replace the audio-only SDK.
• If the app uses external rendering, we recommend that you set the canvas after you receive the return of onUserJoined.
• If the app does not retrieve the ID of a remote user, you can call the method after the remote user joins the room. You can retrieve the uid of the remote user from the return of onNERtcEngineUserDidJoinWithUserID. You can use this method to set the substream video canvas.
• If the remote user leaves the room, the SDK disassociates the remote user from the canvas. The setting automatically becomes invalid.

Since

V4.5.0

Parameters

userID	The ID of a remote user.
canvas	The video canvas. For more information, see NERtcVideoCanvas. To delete the canvas setting, set the value to nil.

Returns

The value returned. A value of 0 indicates that the operation is successful.

setupRemoteVideoCanvas:forUserID:

- (int) setupRemoteVideoCanvas:		(NERtcVideoCanvas *_Nullable)	canvas
forUserID:		(uint64_t)	userID

Sets views for remote users.

This method is used to associate remote users with display views and configure the rendering mode and mirror mode for remote views displayed locally. The method affects only the video screen viewed by local users.

Note

• The audio-only SDK disables this API. If you need to use the API, you can download the standard SDK from the official website of CommsEase and replace the audio-only SDK.
• If the user ID is not retrieved, you can set the user ID after the app receives a message delivered when the onNERtcEngineUserDidJoinWithUserID event is triggered.
• To disassociate a specified user from a view, you can leave the canvas parameter empty.
• After a user leaves the room, the association between a remote user and the view is cleared.

Since

V4.5.0

Parameters

userID	The ID of a remote user.
canvas	The video window. if you want to delete the canvas, you can set the value to nil.

Returns

The value returned. A value of 0 indicates that the operation is successful.

startChannelMediaRelay:

- (int) startChannelMediaRelay:

(NERtcChannelMediaRelayConfiguration *_Nonnull)

config

Starts to relay media streams across rooms.

• The method can invite co-hosts across rooms. Media streams from up to four rooms can be relayed. A room can receive multiple relayed media streams.
• After you call the method, the SDK triggers onNERtcEngineChannelMediaRelayStateDidChange and onNERtcEngineDidReceiveChannelMediaRelayEvent. The callback reports the status and events about the current relayed media streams across rooms.

Note

• You can call this method after you join a room. Before you call the method, you must set the destination room by calling setDestinationInfo in the config parameter.
• The method is applicable only to the host in live streaming.
• If you want to call the method again, you must first call the stopChannelMediaRelay method to exit the current relay status.
• If you succeed in relaying the media stream across rooms, and want to change the destination room, for example, add or remove the destination room, you can call updateChannelMediaRelay to update the information about the destination room.

Since

V4.5.0

Parameters

config

The configuration for media stream relay across rooms. For more information, see NERtcChannelMediaRelayConfiguration.

Returns

A value of 0 returned indicates that the operation is successful. Otherwise, the operation fails.

startScreenCapture:

- (int) startScreenCapture:

(NERtcVideoSubStreamEncodeConfiguration *)

config

Enables screen sharing.

The content of the screen sharing is published through the substream.
You can call the method only after you join a room.
If you join a room and call this method to enable the substream, the onUserSubStreamVideoStart callback is triggered on the remote client.

Note

The audio-only SDK disables this API. If you need to use the API, you can download the standard SDK from the official website of CommsEase and replace the audio-only SDK.

Since

V4.5.0

Parameters

config

The encoding configuration of the local substream. For more information, see NERtcVideoSubStreamEncodeConfiguration.

Returns

The value returned. A value of 0 indicates that the operation is successful.

stopChannelMediaRelay

- (int) stopChannelMediaRelay

Stops media stream relay across rooms.

If the host leave the room, media stream replay across rooms automatically stops. You can also call stopChannelMediaRelay. In this case, the host leaves all destination rooms.

• If you call this method, the SDK triggers the onNERtcEngineChannelMediaRelayStateDidChange callback. If NERtcChannelMediaRelayStateRunning is returned, the media stream relay stops.
• If the operation fails, the SDK triggers the onNERtcEngineChannelMediaRelayStateDidChange callback that returns the status code NERtcChannelMediaRelayStateFailure.

Since

V4.5.0

Returns

A value of 0 returned indicates that the operation is successful. Otherwise, the operation fails.

stopScreenCapture

- (int) stopScreenCapture

Disables screen sharing with the substream transmission.

If you use the method to disable the substream after you join a room, the onNERtcEngineUserSubStreamDidStop callback is triggered on the remote client.

Note

The audio-only SDK disables this API. If you need to use the API, you can download the standard SDK from the official website of CommsEase and replace the audio-only SDK.

Since

V4.5.0

Returns

The value returned. A value of 0 indicates that the operation is successful.

subscribeAllRemoteAudio:

- (int) subscribeAllRemoteAudio:

(BOOL)

subscribe

Subscribes to or unsubscribes from audio streams from all remote users.

Note

• After a user joins a room, audio streams from all remote users are subscribed by default. In this case, do not repeat subscribing to audio streams from all remote users by calling subscribeAllRemoteAudioStreams(YES).
• You must join a room before you can call the method.
• This setting applies to subsequent users that join the room.

Since

V4.5.0

Parameters

subscribe

The option whether to unsubscribe from audio streams from all remote users.

Returns

The value returned. A value of 0 indicates that the operation is successful.

subscribeRemoteAudio:forUserID:

- (int) subscribeRemoteAudio:		(BOOL)	subscribe
forUserID:		(uint64_t)	userID

Subscribes to or unsubscribes from audio streams from specified remote users.

After a user joins a room, audio streams from all remote users are subscribed by default. You can call this method to subscribe to or unsubscribe from audio streams from all remote users.

Note

You can call this method before or after you join a room.

Since

V4.5.0

Parameters

subscribe	The option whether to subscribe to specified audio streams.
userID	The ID of a specified remote user.

Returns

The value returned. A value of 0 indicates that the operation is successful.

subscribeRemoteSubStreamAudio:forUserID:

- (int) subscribeRemoteSubStreamAudio:		(BOOL)	subscribe
forUserID:		(uint64_t)	userID

Subscribes or unsubscribes audio streams from specified remote users.

After a user joins a room, audio streams from all remote users are subscribed by default. You can call this method to subscribe or unsubscribe audio streams from all remote users.

Note

This method can be called only if a user joins a room.

Since

V4.6.10

Parameters

userID	indicates the user ID.
subscribe	specifies whether to subscribe specified audio streams. true: subscribes audio steams. This is the default value. false: unsubscribes audio streams.

Returns

• 0: success
• Others: failure

subscribeRemoteSubStreamVideo:forUserID:

- (int) subscribeRemoteSubStreamVideo:		(BOOL)	subscribe
forUserID:		(uint64_t)	userID

Subscribes to or unsubscribes from remote video substream for screen sharing.

You can receive the video substream data only after you subscribe to the video substream.

Note

• The audio-only SDK disables this API. If you need to use the API, you can download the standard SDK from the official website of CommsEase and replace the audio-only SDK.
• You can call the method only after you join a room.

Since

V4.5.0

Parameters

subscribe	The option whether to subscribe to remote video substream for screen sharing.
userID	The ID of a remote user.

Returns

The value returned. A value of 0 indicates that the operation is successful.

subscribeRemoteVideo:forUserID:streamType:

- (int) subscribeRemoteVideo:		(BOOL)	subscribe
forUserID:		(uint64_t)	userID
streamType:		(NERtcRemoteVideoStreamType)	streamType

Subscribes to or unsubscribes from video streams from specified remote users.

After a user joins a room, the video streams from remote users are not subscribed by default. If you want to view video streams from specified remote users, you can call this method to subscribe to the video streams from the user when the user joins the room or publishes the video streams.

Note

• The audio-only SDK disables this API. If you need to use the API, you can download the standard SDK from the official website of CommsEase and replace the audio-only SDK.
• You must join a room before you can call the method.

Since

V4.5.0

Parameters

subscribe	The option whether to unsubscribe from local video streams.
userID	The ID of a specified user.
streamType	The type of the video streams. For more information, see NERtcRemoteVideoStreamType.

Returns

The value returned. A value of 0 indicates that the operation is successful.

takeLocalSnapshot:callback:

- (int) takeLocalSnapshot:		(NERtcStreamChannelType)	streamType
callback:		(NERtcTakeSnapshotCallback)	callback

Takes a local video snapshot.

The takeLocalSnapshot method takes a local video snapshot on the local mainstream or local substream. The callback that belongs to the NERtcTakeSnapshotCallback class returns the data of the snapshot image.

Note

• Before you call the method to capture the snapshot from the mainstream, you must first call startVideoPreview or enableLocalVideo, and joinChannel.
• Before you call the method to capture the snapshot from the substream, you must first call joinChannel and startScreenCapture.
• You can set text, timestamp, and image watermarks at the same time. If different types of watermarks overlap, the layers overlay previous layers in the image, text, and timestamp sequence.

Since

V4.5.0

Parameters

streamType	The video stream type of the snapshot. You can set the value to mainstream or substream.
callback	The snapshot callback.

Note

The API is disabled in the audio-only SDK. If you need to use the API, you can download the standard SDK from the official website of CommsEase and replace the audio-only SDK.

Returns

The value returned. A value of 0 indicates that the operation is successful.

takeRemoteSnapshot:forUserID:callback:

- (int) takeRemoteSnapshot:		(NERtcStreamChannelType)	streamType
forUserID:		(uint64_t)	userID
callback:		(NERtcTakeSnapshotCallback)	callback

Takes a snapshot of a remote video.

The takeRemoteSnapshot method takes a snapshot from the remote video published through the mainstream or substream with a specified uid. The callback that belongs to the NERtcTakeSnapshotCallback class returns the data of the snapshot image.

Note

• Before you call takeRemoteSnapshot, you must first call onUserVideoStart and onNERtcEngineUserSubStreamDidStartWithUserID.
• You can set text, timestamp, and image watermarks at the same time. If different types of watermarks overlap, the layers overlay previous layers in the image, text, and timestamp sequence.

Since

V4.5.0

Parameters

userID	The ID of a remote user.
streamType	The video stream type of the snapshot. You can set the value to mainstream or substream.
callback	The snapshot callback.

Note

The API is disabled in the audio-only SDK. If you need to use the API, you can download the standard SDK from the official website of CommsEase and replace the audio-only SDK.

Returns

The value returned. A value of 0 indicates that the operation is successful.

updateChannelMediaRelay:

- (int) updateChannelMediaRelay:

(NERtcChannelMediaRelayConfiguration *_Nonnull)

config

Updates the information of the destination room for media stream relay.

You can call this method to relay the media stream to multiple rooms or exit the current room.

• You can call this method to change the destination room, for example, add or remove the destination room.
• If you call this method, the SDK triggers the onNERtcEngineChannelMediaRelayStateDidChange callback. If NERtcChannelMediaRelayStateRunning is returned, the media stream relay is successful.

Note

• Before you call the method, you must join the room and call startChannelMediaRelay to relay the media stream across rooms. Before you call the method, you must set the destination room by calling setDestinationInfo in the config parameter.
• You can relay the media stream up to four destination rooms. You can first call removeDestinationInfoForChannelName that belongs to the NERtcChannelMediaRelayConfiguration class to remove the rooms that you have no interest in and add new destination rooms.

Since

V4.5.0

Parameters

config

The configuration for media stream relay across rooms. For more information, see NERtcChannelMediaRelayConfiguration.

Returns

A value of 0 returned indicates that the operation is successful. Otherwise, the operation fails.

updateLiveStreamTask:compeltion:

- (int) updateLiveStreamTask:		(NERtcLiveStreamTaskInfo *)	taskInfo
compeltion:		(NERtcLiveStreamCompletion)	completion

Updates a streaming task.

Note

• The method is applicable to only live streaming.
• You can call the method when you are in a room. The method is valid for calls.

Since

V4.5.0

Parameters

taskInfo	The information about the streaming task. For more information, see NERtcLiveStreamTaskInfo.
completion	The result. The callback is triggered after the method is called. For more information, see NERtcLiveStreamCompletion.

Returns

The value returned. A value of 0 indicates that the operation is successful.

---

The documentation for this protocol was generated from the following file:

• exportHeaders/INERtcChannel.h