Agora RTC Objective-C API Reference  Refactor
Instance Methods
AgoraRtcEngineKit(Ex) Category Reference

Instance Methods

(int) - joinChannelExByToken:connection:delegate:mediaOptions:joinSuccess:
 
(int) - joinChannelExByToken:channelId:userAccount:delegate:mediaOptions:joinSuccess:
 
(int) - updateChannelExWithMediaOptions:connection:
 
(int) - setDelegateEx:connection:
 
(int) - muteLocalAudioStreamEx:connection:
 
(int) - muteLocalVideoStreamEx:connection:
 
(int) - muteRemoteAudioStreamEx:mute:connection:
 
(int) - muteAllRemoteAudioStreamsEx:connection:
 
(int) - setVideoEncoderConfigurationEx:connection:
 
(int) - setupRemoteVideoEx:connection:
 
(int) - setRemoteRenderModeEx:mode:mirror:connection:
 
(int) - muteRemoteVideoStreamEx:mute:connection:
 
(int) - muteAllRemoteVideoStreamsEx:connection:
 
(int) - enableDualStreamModeEx:streamConfig:connection:
 
(int) - setDualStreamModeEx:streamConfig:connection:
 
(int) - setSimulcastConfigEx:connection:
 
(int) - setRemoteVideoStreamEx:type:connection:
 
(int) - setRemoteVideoSubscriptionOptionsEx:options:connection:
 
(AgoraUserInfo *_Nullable) - getUserInfoByUserAccountEx:connection:withError:
 
(AgoraUserInfo *_Nullable) - getUserInfoByUidEx:connection:withError:
 
(AgoraConnectionState- getConnectionStateEx:
 
(int) - adjustRecordingSignalVolumeEx:connection:
 
(int) - muteRecordingSignalEx:connection:
 
(int) - adjustUserPlaybackSignalVolumeEx:volume:connection:
 
(int) - setRemoteVoicePositionEx:pan:gain:connection:
 
(int) - addVideoWatermarkEx:options:connection:
 
(int) - clearVideoWatermarkEx:
 

Stream Fallback


(int) - setHighPriorityUserListEx:option:connection:
 

Built-in Encryption


(int) - enableEncryptionEx:encryptionConfig:connection:
 

Data Steam


(int) - createDataStreamEx:reliable:ordered:connection:
 
(int) - createDataStreamEx:config:connection:
 
(int) - sendStreamMessageEx:data:connection:
 

Stream Publish


(int) - setSubscribeAudioAllowlistEx:connection:
 
(int) - setSubscribeVideoAllowlistEx:connection:
 
(NSInteger) - takeSnapshotEx:uid:filePath:
 
(NSInteger) - takeSnapshotExWithConfig:uid:config:
 
(int) - sendAudioMetadataEx:metadata:
 
(int) - enableContentInspectEx:config:connection:
 
(int) - startRtmpStreamWithoutTranscodingEx:connection:
 
(int) - startRtmpStreamWithTranscodingEx:transcoding:connection:
 
(int) - updateRtmpTranscodingEx:connection:
 
(int) - stopRtmpStreamEx:connection:
 
(int) - startOrUpdateChannelMediaRelayEx:connection:
 
(int) - stopChannelMediaRelayEx:
 
(int) - pauseAllChannelMediaRelayEx:
 
(int) - resumeAllChannelMediaRelayEx:
 
(int) - startMediaRenderingTracingEx:
 
(int) - setParametersEx:connection:
 
(NSString *_Nullable) - getCallIdEx:
 
(void) - addDelegateEx:connection:
 
(void) - removeDelegateEx:connection:
 

Method Documentation

◆ joinChannelExByToken:connection:delegate:mediaOptions:joinSuccess:

- (int) joinChannelExByToken: (NSString *_Nullable)  token
connection: (AgoraRtcConnection *_Nonnull)  connection
delegate: (id< AgoraRtcEngineDelegate > _Nullable)  delegate
mediaOptions: (AgoraRtcChannelMediaOptions *_Nonnull)  mediaOptions
joinSuccess: (void(^)(NSString *_Nonnull channel, NSUInteger uid, NSInteger elapsed))  joinSuccessBlock 

Joins a channel.

You can call this method multiple times to join multiple channels.

Parameters
tokenThe token for authentication.
  • In situations not requiring high security: You can use the temporary token generated at Console. For details, see Get a temporary token.
  • In situations requiring high security: Set it as the token generated at you server. For details, see Generate a token.
connectionAgoraRtcConnection by channelId and uid combine
delegateAgoraRtcEngineDelegate protocol.(Need a new object when called)
mediaOptionsAgoraRtcChannelMediaOptions Object.
joinSuccessBlockSame as AgoraRtcEngineDelegate.rtcEngine:didJoinChannel:withUid:elapsed: didJoinChannel. We recommend you set this parameter as nil to use didJoinChannel.
  • If joinSuccessBlock is nil, the SDK triggers the didJoinChannel callback.
  • If you implement both joinSuccessBlock and didJoinChannel, joinSuccessBlock takes higher priority than didJoinChannel.
Returns
  • 0: Success.
  • < 0: Failure.

Extends class AgoraRtcEngineKit.

◆ joinChannelExByToken:channelId:userAccount:delegate:mediaOptions:joinSuccess:

- (int) joinChannelExByToken: (NSString *_Nullable)  token
channelId: (NSString *_Nonnull)  channelId
userAccount: (NSString *_Nonnull)  userAccount
delegate: (id< AgoraRtcEngineDelegate > _Nullable)  delegate
mediaOptions: (AgoraRtcChannelMediaOptions *_Nonnull)  mediaOptions
joinSuccess: (void(^)(NSString *_Nonnull channel, NSUInteger uid, NSInteger elapsed))  joinSuccessBlock 

Joins the channel with a user account.

After the user successfully joins the channel, the SDK triggers the following callbacks:

Note
To ensure smooth communication, use the same parameter type to identify the user. For example, if a user joins the channel with a user ID, then ensure all the other users use the user ID too. The same applies to the user account. If a user joins the channel with the Agora Web SDK, ensure that the uid of the user is set to the same parameter type.
Parameters
tokenThe token generated at your server:
  • For low-security requirements: You can use the temporary token generated at Console. For details, see Get a temporary toke.
  • For high-security requirements: Set it as the token generated at your server. For details, see Get a token.
channelIdThe channel name. The maximum length of this parameter is 64 bytes. Supported character scopes are:
  • All lowercase English letters: a to z.
  • All uppercase English letters: A to Z.
  • All numeric characters: 0 to 9.
  • The space character.
  • Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
userAccountThe user account. The maximum length of this parameter is 255 bytes. Ensure that you set this parameter and do not set it as null. Supported character scopes are:
  • All lowercase English letters: a to z.
  • All uppercase English letters: A to Z.
  • All numeric characters: 0 to 9.
  • The space character.
  • Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
delegateAgoraRtcEngineDelegate protocol.
mediaOptionsThe channel media options: ChannelMediaOptions
Returns
  • 0: Success.
  • < 0: Failure.
    • #ERR_INVALID_ARGUMENT (-2)
    • #ERR_NOT_READY (-3)
    • #ERR_REFUSED (-5)

Extends class AgoraRtcEngineKit.

◆ updateChannelExWithMediaOptions:connection:

- (int) updateChannelExWithMediaOptions: (AgoraRtcChannelMediaOptions *_Nonnull)  mediaOptions
connection: (AgoraRtcConnection *_Nonnull)  connection 

Updates the channel media options after joining the channel.

Parameters
mediaOptionsThe channel media options: ChannelMediaOptions.
connectionAgoraRtcConnection by channelId and uid combine
Returns
  • 0: Success.
  • < 0: Failure.

Extends class AgoraRtcEngineKit.

◆ setDelegateEx:connection:

- (int) setDelegateEx: (id< AgoraRtcEngineDelegate > _Nullable)  delegate
connection: (AgoraRtcConnection *_Nonnull)  connection 

Resets the SDK delegate.

The SDK uses the delegate to inform the app on engine runtime events. All methods defined in the delegate are optional implementation methods.

Parameters
delegateThe AgoraRtcEngineDelegate protocol.
connectionThe AgoraRtcConnection object.

Extends class AgoraRtcEngineKit.

◆ muteLocalAudioStreamEx:connection:

- (int) muteLocalAudioStreamEx: (BOOL)  mute
connection: (AgoraRtcConnection *_Nonnull)  connection 

Stops or resumes sending the local audio stream with connection.

Parameters
muteDetermines whether to send or stop sending the local audio stream:
  • YES: Stop sending the local audio stream.
  • NO: Send the local audio stream.
connectionAgoraRtcConnection by channelId and uid combine
Returns
  • 0: Success.
  • < 0: Failure.

Extends class AgoraRtcEngineKit.

◆ muteLocalVideoStreamEx:connection:

- (int) muteLocalVideoStreamEx: (BOOL)  mute
connection: (AgoraRtcConnection *_Nonnull)  connection 

Stops or resumes sending the local video stream with connection.

Parameters
muteDetermines whether to send or stop sending the local video stream:
  • YES: Stop sending the local video stream.
  • NO: Send the local video stream.
connectionAgoraRtcConnection by channelId and uid combine
Returns
  • 0: Success.
  • < 0: Failure.

Extends class AgoraRtcEngineKit.

◆ muteRemoteAudioStreamEx:mute:connection:

- (int) muteRemoteAudioStreamEx: (NSUInteger)  uid
mute: (BOOL)  mute
connection: (AgoraRtcConnection *_Nonnull)  connection 

Mutes a specified remote user's audio stream.

Note
When setting to YES, this method stops playing audio streams without affecting the audio stream receiving process.
Parameters
uidUser ID whose audio streams the user intends to mute.
mute* YES: Stops playing a specified user’s audio streams. NO: Resumes playing a specified user’s audio streams.
connectionAgoraRtcConnection by channelId and uid combine
Returns
* 0: Success. <0: Failure.

Extends class AgoraRtcEngineKit.

◆ muteAllRemoteAudioStreamsEx:connection:

- (int) muteAllRemoteAudioStreamsEx: (BOOL)  mute
connection: (AgoraRtcConnection *_Nonnull)  connection 

Stops or resumes receiving all remote audio stream with connection.

Parameters
muteWhether to stop receiving remote audio streams:
  • YES: Stop receiving any remote audio stream.
  • NO: Resume receiving all remote audio streams.
connectionAgoraRtcConnection by channelId and uid combine
Returns
  • 0: Success.
  • < 0: Failure.

Extends class AgoraRtcEngineKit.

◆ setVideoEncoderConfigurationEx:connection:

- (int) setVideoEncoderConfigurationEx: (AgoraVideoEncoderConfiguration *_Nonnull)  config
connection: (AgoraRtcConnection *_Nonnull)  connection 

Sets the video encoder configuration.

Each configuration profile corresponds to a set of video parameters, including the resolution, frame rate, and bitrate.

The parameters specified in this method are the maximum values under ideal network conditions. If the video engine cannot render the video using the specified parameters due to poor network conditions, the parameters further down the list are considered until a successful configuration is found.

Parameters
configThe local video encoder configuration, see #AgoraVideoEncoderConfiguration.
connectionAgoraRtcConnection by channelId and uid combine
Returns
  • 0: Success.
  • < 0: Failure.

Extends class AgoraRtcEngineKit.

◆ setupRemoteVideoEx:connection:

- (int) setupRemoteVideoEx: (AgoraRtcVideoCanvas *_Nonnull)  remote
connection: (AgoraRtcConnection *_Nonnull)  connection 

Binds the remote user to the video display window, that is, sets the view for the user of the specified uid.

Usually, the application should specify the uid of the remote video in the method call before the user enters a channel. If the remote uid is unknown to the application, you can set the uid after receiving the AgoraRtcEngineDelegate.rtcEngine:didJoinedOfUid:elapsed: didJoinedOfUid event.

Parameters
remoteAgoraRtcVideoCanvas
connectionAgoraRtcConnection by channelId and uid combine
Returns
  • 0: Success.
  • <0: Failure.

Extends class AgoraRtcEngineKit.

◆ setRemoteRenderModeEx:mode:mirror:connection:

- (int) setRemoteRenderModeEx: (NSUInteger)  uid
mode: (AgoraVideoRenderMode mode
mirror: (AgoraVideoMirrorMode)  mirror
connection: (AgoraRtcConnection *_Nonnull)  connection 

Configures the remote video display mode. The application can call this method multiple times to change the display mode.

Parameters
uidUser id of the user whose video streams are received.
modeAgoraVideoRenderMode
mirrorAgoraVideoMirrorMode
connectionAgoraRtcConnection by channelId and uid combine
Returns
  • 0: Success.
  • <0: Failure.

Extends class AgoraRtcEngineKit.

◆ muteRemoteVideoStreamEx:mute:connection:

- (int) muteRemoteVideoStreamEx: (NSUInteger)  uid
mute: (BOOL)  mute
connection: (AgoraRtcConnection *_Nonnull)  connection 

Stops or resumes receiving the video stream of a specified user.

Note
Once you leave the channel, the settings in this method becomes invalid.
Parameters
uidID of the specified remote user.
muteDetermines whether to receive or stop receiving a specified video stream:
  • YES: Stop receiving the specified video stream.
  • NO: (Default) Receive the specified video stream.
connectionAgoraRtcConnection by channelId and uid combine
Returns
  • 0: Success.
  • < 0: Failure.

Extends class AgoraRtcEngineKit.

◆ muteAllRemoteVideoStreamsEx:connection:

- (int) muteAllRemoteVideoStreamsEx: (BOOL)  mute
connection: (AgoraRtcConnection *_Nonnull)  connection 

Stops or resumes receiving all remote video stream with connection.

Parameters
muteWhether to stop receiving remote video streams:
  • YES: Stop receiving any remote video stream.
  • NO: Resume receiving all remote video streams.
connectionAgoraRtcConnection by channelId and uid combine
Returns
  • 0: Success.
  • < 0: Failure.

Extends class AgoraRtcEngineKit.

◆ enableDualStreamModeEx:streamConfig:connection:

- (int) enableDualStreamModeEx: (BOOL)  enabled
streamConfig: (AgoraSimulcastStreamConfig *)  streamConfig
connection: (AgoraRtcConnection *_Nonnull)  connection 

Enables or disables the dual video stream mode.

Deprecated:
v4.2.0. This method is deprecated. Use setDualStreamModeEx instead.

If dual-stream mode is enabled, the subscriber can choose to receive the high-stream (high-resolution high-bitrate video stream) or low-stream (low-resolution low-bitrate video stream) video using setRemoteVideoStreamType setRemoteVideoStreamType.

Parameters
enabled
  • true: Enable the dual-stream mode.
  • false: (default) Disable the dual-stream mode.
streamConfigThe minor stream config
connectionAn output parameter which is used to control different connection instances.

Extends class AgoraRtcEngineKit.

◆ setDualStreamModeEx:streamConfig:connection:

- (int) setDualStreamModeEx: (AgoraSimulcastStreamMode mode
streamConfig: (AgoraSimulcastStreamConfig *)  streamConfig
connection: (AgoraRtcConnection *_Nonnull)  connection 

Enables or disables the dual video stream mode.

If dual-stream mode is enabled, the subscriber can choose to receive the high-stream (high-resolution high-bitrate video stream) or low-stream (low-resolution low-bitrate video stream) video using setRemoteVideoStreamType setRemoteVideoStreamType.

Parameters
modeThe dual-stream mode.
streamConfigThe minor stream config
connectionAn output parameter which is used to control different connection instances.

Extends class AgoraRtcEngineKit.

◆ setSimulcastConfigEx:connection:

- (int) setSimulcastConfigEx: (AgoraSimulcastConfig *)  simulcastConfig
connection: (AgoraRtcConnection *_Nonnull)  connection 

Set the multi-layer video stream configuration.

If multi-layer is configed, the subscriber can choose to receive the coresponding layer of video stream using setRemoteVideoStreamType.

Parameters
simulcastConfig
  • The configuration for multi-layer video stream. It includes seven layers, ranging from STREAM_LAYER_1 to STREAM_LOW. A maximum of 3 layers can be enabled simultaneously.
connectionThe RtcConnection object.
Returns
  • 0: Success.
  • < 0: Failure. @technical preview

Extends class AgoraRtcEngineKit.

◆ setRemoteVideoStreamEx:type:connection:

- (int) setRemoteVideoStreamEx: (NSUInteger)  uid
type: (AgoraVideoStreamType streamType
connection: (AgoraRtcConnection *_Nonnull)  connection 

Sets the remote video stream type.

If the remote user has enabled the dual-stream mode, by default the SDK receives the high-stream video. Call this method to switch to the low-stream video.

Note
This method applies to scenarios where the remote user has enabled the dual-stream mode by enableDualStreamMode: enableDualStreamMode before joining the channel.
Parameters
uidID of the remote user sending the video stream.
streamTypeThe video stream type: AgoraVideoStreamType.
connectionAgoraRtcConnection by channelId and uid combine
Returns
  • 0: Success.
  • < 0: Failure.

Extends class AgoraRtcEngineKit.

◆ setRemoteVideoSubscriptionOptionsEx:options:connection:

- (int) setRemoteVideoSubscriptionOptionsEx: (NSUInteger)  uid
options: (AgoraVideoSubscriptionOptions *_Nonnull)  options
connection: (AgoraRtcConnection *_Nonnull)  connection 

Sets the remote video subscription options

Parameters
uidID of the remote user sending the video stream.
optionsSets the video subscription options.
connectionAgoraRtcConnection by channelId and uid combine
Returns
  • 0: Success.
  • < 0: Failure.

Extends class AgoraRtcEngineKit.

◆ getUserInfoByUserAccountEx:connection:withError:

- (AgoraUserInfo* _Nullable) getUserInfoByUserAccountEx: (NSString *_Nonnull)  userAccount
connection: (AgoraRtcConnection *_Nonnull)  connection
withError: (AgoraErrorCode *_Nullable)  error 

Gets the user information by passing in the user account.

After a remote user joins the channel, the SDK gets the user ID and user account of the remote user, caches them in a mapping table object (AgoraUserInfo), and triggers the [didUpdatedUserInfo]([AgoraRtcEngineDelegate rtcEngine:didUpdatedUserInfo:withUid:]) callback on the local client.

After receiving the [didUpdatedUserInfo]([AgoraRtcEngineDelegate rtcEngine:didUpdatedUserInfo:withUid:]) callback, you can call this method to get the user ID of the remote user from the userInfo object by passing in the user account.

Parameters
userAccountThe user account of the user. Ensure that you set this parameter.
connectionAgoraRtcConnection by channelId and uid combine
Returns
An [AgoraUserInfo](AgoraUserInfo) object that contains the user account and user ID of the user.

Extends class AgoraRtcEngineKit.

◆ getUserInfoByUidEx:connection:withError:

- (AgoraUserInfo* _Nullable) getUserInfoByUidEx: (NSUInteger)  uid
connection: (AgoraRtcConnection *_Nonnull)  connection
withError: (AgoraErrorCode *_Nullable)  error 

Gets the user information by passing in the user ID.

After a remote user joins the channel, the SDK gets the user ID and user account of the remote user, caches them in a mapping table object (userInfo), and triggers the onUserInfoUpdated callback on the local client.

After receiving the onUserInfoUpdated callback, you can call this method to get the user account of the remote user from the userInfo object by passing in the user ID.

Parameters
uidThe user ID of the remote user. Ensure that you set this parameter.
connectionAgoraRtcConnection by channelId and uid combine
Returns
An [AgoraUserInfo](AgoraUserInfo) object that contains the user account and user ID of the user.

Extends class AgoraRtcEngineKit.

◆ getConnectionStateEx:

- (AgoraConnectionState) getConnectionStateEx: (AgoraRtcConnection *_Nonnull)  connection

Gets the connection state of the SDK.

Parameters
connectionAgoraRtcConnection by channelId and uid combine
Returns
The connection state. See AgoraConnectionState.

Extends class AgoraRtcEngineKit.

◆ adjustRecordingSignalVolumeEx:connection:

- (int) adjustRecordingSignalVolumeEx: (NSInteger)  volume
connection: (AgoraRtcConnection *_Nonnull)  connection 

Adjusts the recording volume.

Parameters
volumeThe recording volume, which ranges from 0 to 400:
  • 0 : Mute the recording volume.
  • 100: The original volume.
  • 400: (Maximum) Four times the original volume with signal clipping protection.
connectionAgoraRtcConnection by channelId and uid combine
Returns
  • 0 : Success.
  • < 0: Failure.

Extends class AgoraRtcEngineKit.

◆ muteRecordingSignalEx:connection:

- (int) muteRecordingSignalEx: (BOOL)  mute
connection: (AgoraRtcConnection *_Nonnull)  connection 

Mutes or resume recording signal volume.

Parameters
muteDetermines whether to mute or resume the recording signal volume.
  • YES: Mute the recording signal volume.
  • NO: (Default) Resume the recording signal volume.
connectionAgoraRtcConnection by channelId and uid combine
Returns
  • 0 : Success.
  • < 0: Failure.

Extends class AgoraRtcEngineKit.

◆ adjustUserPlaybackSignalVolumeEx:volume:connection:

- (int) adjustUserPlaybackSignalVolumeEx: (NSUInteger)  uid
volume: (NSInteger)  volume
connection: (AgoraRtcConnection *_Nonnull)  connection 

Adjust the playback signal volume of a specified remote user.

You can call this method as many times as necessary to adjust the playback volume of different remote users, or to repeatedly adjust the playback volume of the same remote user.

Note**

  • The playback volume here refers to the mixed volume of a specified remote user.
  • This method can only adjust the playback volume of one specified remote user at a time. To adjust the playback volume of different remote users, call the method as many times, once for each remote user.
Parameters
uidThe ID of the remote user.
volumeThe playback volume of the specified remote user. The value ranges between 0 and 400, including the following:
  • 0: Mute.
  • 100: (Default) Original volume.
    Parameters
    connectionAgoraRtcConnection by channelId and uid combine
    Returns
  • 0: Success.
  • < 0: Failure.

Extends class AgoraRtcEngineKit.

◆ sendCustomReportMessageEx:category:event:label:value:connection:

- (int) sendCustomReportMessageEx: (NSString *_Nullable)  messageId
category: (NSString *_Nullable)  category
event: (NSString *_Nullable)  event
label: (NSString *_Nullable)  label
value: (NSInteger)  value
connection: (AgoraRtcConnection *_Nonnull)  connection 

Extends class AgoraRtcEngineKit.

◆ enableAudioVolumeIndicationEx:smooth:reportVad:connection:

- (int) enableAudioVolumeIndicationEx: (NSInteger)  interval
smooth: (NSInteger)  smooth
reportVad: (BOOL)  reportVad
connection: (AgoraRtcConnection *_Nonnull)  connection 

Extends class AgoraRtcEngineKit.

◆ setRemoteVoicePositionEx:pan:gain:connection:

- (int) setRemoteVoicePositionEx: (NSUInteger)  uid
pan: (double)  pan
gain: (double)  gain
connection: (AgoraRtcConnection *_Nonnull)  connection 

Sets the sound position and gain of a remote user.

When the local user calls this method to set the sound position of a remote user, the sound difference between the left and right channels allows the local user to track the real-time position of the remote user, creating a real sense of space. This method applies to massively multiplayer online games, such as Battle Royale games.

Note:**

  • Ensure that you call this method after joining a channel. For this method to work, enable stereo panning for remote users by calling [enableSoundPositionIndication]([AgoraRtcEngineKit enableSoundPositionIndication:]) before joining a channel. This method requires hardware support.
  • For the best effect, we recommend using the following audio output devices:
    • (iOS) A stereo headset.
    • (macOS) A stereo loudspeaker.
      Parameters
      uidThe ID of the remote user.
      panThe sound position of the remote user. The value ranges from -1.0 to 1.0:
      0.0: (default) the remote sound comes from the front. -1.0: the remote sound comes from the left. 1.0: the remote sound comes from the right.
Parameters
gainGain of the remote user. The value ranges from 0.0 to 100.0. The default value is 100.0 (the original gain of the remote user). The smaller the value, the less the gain.
connectionAgoraRtcConnection by channelId and uid combine
Returns
* 0: Success. < 0: Failure.

Extends class AgoraRtcEngineKit.

◆ addVideoWatermarkEx:options:connection:

- (int) addVideoWatermarkEx: (NSURL *_Nonnull)  url
options: (WatermarkOptions *_Nonnull)  options
connection: (AgoraRtcConnection *_Nonnull)  connection 

Adds a watermark image to the local video.

This method adds a PNG watermark image to the local video in the interactive live streaming. Once the watermark image is added, all the audience in the channel (CDN audience included), and the capturing device can see and capture it. Agora supports adding only one watermark image onto the local video, and the newly watermark image replaces the previous one.

The watermark position depends on the settings in the [setVideoEncoderConfiguration]([AgoraRtcEngineKit setVideoEncoderConfiguration:]) method:

  • If the orientation mode of the encoding video is AgoraVideoOutputOrientationModeFixedLandscape, or the landscape mode in AgoraVideoOutputOrientationModeAdaptative, the watermark uses the landscape orientation.
  • If the orientation mode of the encoding video is AgoraVideoOutputOrientationModeFixedPortrait, or the portrait mode in AgoraVideoOutputOrientationModeAdaptative, the watermark uses the portrait orientation.
  • When setting the watermark position, the region must be less than the dimensions set in the [setVideoEncoderConfiguration]([AgoraRtcEngineKit setVideoEncoderConfiguration:]) method. Otherwise, the watermark image will be cropped.

    Note**

  • Ensure that you have called the [enableVideo]([AgoraRtcEngineKit enableVideo]) method to enable the video module before calling this method.
  • If you only want to add a watermark image to the local video for the audience in the CDN live streaming channel to see and capture, you can call this method or the [setLiveTranscoding]([AgoraRtcEngineKit setLiveTranscoding:]) method.
  • This method supports adding a watermark image in the PNG file format only. Supported pixel formats of the PNG image are RGBA, RGB, Palette, Gray, and Alpha_gray.
  • If the dimensions of the PNG image differ from your settings in this method, the image will be cropped or zoomed to conform to your settings.
  • If you have enabled the local video preview by calling the [startPreview]([AgoraRtcEngineKit startPreview]) method, you can use the visibleInPreview member in the WatermarkOptions class to set whether or not the watermark is visible in preview.
  • If you have enabled the mirror mode for the local video, the watermark on the local video is also mirrored. To avoid mirroring the watermark, Agora recommends that you do not use the mirror and watermark functions for the local video at the same time. You can implement the watermark function in your application layer.
Parameters
urlThe local file path of the watermark image to be added. This method supports adding a watermark image from the local file path. If the watermark image to be added is in the project file, you need to change the image's Type from PNG image to Data in the Xcode property, otherwise, the Agora Native SDK cannot recognize the image.
optionsThe options of the watermark image to be added. See WatermarkOptions.
connectionAgoraRtcConnection by channelId and uid combine
Returns
* 0: Success. < 0: Failure.

Extends class AgoraRtcEngineKit.

◆ clearVideoWatermarkEx:

- (int) clearVideoWatermarkEx: (AgoraRtcConnection *_Nonnull)  connection

Clears the watermark image on the video stream.

Parameters
connectionAgoraRtcConnection by channelId and uid combine
Returns
* 0: Success. < 0: Failure.

Extends class AgoraRtcEngineKit.

◆ createDataStreamEx:reliable:ordered:connection:

- (int) createDataStreamEx: (NSInteger *_Nonnull)  streamId
reliable: (BOOL)  reliable
ordered: (BOOL)  ordered
connection: (AgoraRtcConnection *_Nonnull)  connection 

Creates a data stream.

Each user can create up to five data streams during the lifecycle of the AgoraRtcEngineKit.

Note
Set both the reliable and ordered parameters to YES or NO. Do not set one as YES and the other as NO.
Parameters
streamIdID of the created data stream.
reliableSets whether or not the recipients are guaranteed to receive the data stream from the sender within five seconds:
  • YES: The recipients receive the data stream from the sender within five seconds. If the recipient does not receive the data stream within five seconds, an error is reported to the app.
  • NO: There is no guarantee that the recipients receive the data stream within five seconds and no error message is reported for any delay or missing data stream.
orderedSets whether or not the recipients receive the data stream in the sent order:
  • YES: The recipients receive the data stream in the sent order.
  • NO: The recipients do not receive the data stream in the sent order.
connectionAgoraRtcConnection by channelId and uid combine.
Returns
  • 0: Success.
  • < 0: Failure.

Extends class AgoraRtcEngineKit.

◆ createDataStreamEx:config:connection:

- (int) createDataStreamEx: (NSInteger *_Nonnull)  streamId
config: (AgoraDataStreamConfig *_Nonnull)  config
connection: (AgoraRtcConnection *_Nonnull)  connection 

Creates a data stream.

Each user can create up to five data streams during the lifecycle of the [AgoraRtcChannel](AgoraRtcChannel).

Parameters
streamIdID of the created data stream.
configthe config of data stream.
connectionAgoraRtcConnection by channelId and uid combine.
Returns
* 0: Success. < 0: Failure.

Extends class AgoraRtcEngineKit.

◆ sendStreamMessageEx:data:connection:

- (int) sendStreamMessageEx: (NSInteger)  streamId
data: (NSData *_Nonnull)  data
connection: (AgoraRtcConnection *_Nonnull)  connection 

Sends data stream messages to all users in a channel.

The SDK has the following restrictions on this method:

  • Up to 60 packets can be sent per second in a channel with each packet having a maximum size of 1 KB.
  • Each client can send up to 30 KB of data per second.
  • Each user can have up to five data streams simultaneously.

If the remote user receives the data stream within five seconds, the SDK triggers the AgoraRtcEngineDelegate.rtcEngine:receiveStreamMessageFromUid:streamId:data: receiveStreamMessageFromUid callback on the remote client, from which the remote user gets the stream message.

If the remote user does not receive the data stream within five seconds, the SDK triggers the AgoraRtcEngineDelegate.rtcEngine:didOccurStreamMessageErrorFromUid:streamId:error:missed:cached: didOccurStreamMessageErrorFromUid callback on the remote client.

Note
  • This method applies only to the Communication profile or to the hosts in the live interactive streaming profile. If an audience in the live interactive streaming profile calls this method, the audience role may be changed to a host.
  • Ensure that you have created the data stream using createDataStream:reliable:ordered: createDataStream before calling this method.
Parameters
streamIdID of the sent data stream returned in the createDataStream method.
dataSent data.
connectionAgoraRtcConnection by channelId and uid combine.
Returns
  • 0: Success.
  • < 0: Failure.

Extends class AgoraRtcEngineKit.

◆ setHighPriorityUserListEx:option:connection:

- (int) setHighPriorityUserListEx: (NSArray< NSNumber * > *_Nullable)  uidList
option: (AgoraStreamFallbackOptions)  option
connection: (AgoraRtcConnection *_Nonnull)  connection 

Sets the high priority user list and related remote subscribe fallback option.

Parameters
uidListThe uid list of high priority users.
optionThe remote subscribe fallback option of high priority users.
connectionAgoraRtcConnection by channelId and uid combine.
Returns
  • 0: Success.
  • < 0: Failure.

Extends class AgoraRtcEngineKit.

◆ setSubscribeAudioAllowlistEx:connection:

- (int) setSubscribeAudioAllowlistEx: (NSArray< NSNumber * > *_Nonnull)  allowlist
connection: (AgoraRtcConnection *_Nonnull)  connection 

Sets the allowlist of subscribe remote stream audio.

Parameters
allowlistThe uid list of users who do subscribe to audio.
connectionAgoraRtcConnection by channelId and uid combine.
Note
If uid is in allowlist, the remote user's audio will be subscribed, even if muteRemoteAudioStream(uid, true) and muteAllRemoteAudioStreams(true) are operated.

If a user is in the blocklist and allowlist at the same time, the user will not subscribe to audio.

Returns
  • 0: Success.
  • < 0: Failure.

Extends class AgoraRtcEngineKit.

◆ setSubscribeVideoAllowlistEx:connection:

- (int) setSubscribeVideoAllowlistEx: (NSArray< NSNumber * > *_Nonnull)  allowlist
connection: (AgoraRtcConnection *_Nonnull)  connection 

Sets the allowlist of subscribe remote stream video.

Parameters
allowlistThe uid list of users who do subscribe to video.
connectionAgoraRtcConnection by channelId and uid combine.
Note
If uid is in whitelist, the remote user's video will be subscribed, even if muteRemoteVideoStream(uid, true) and muteAllRemoteVideoStreams(true) are operated.

If a user is in the blocklist and allowlist at the same time, the user will not subscribe to video.

Returns
  • 0: Success.
  • < 0: Failure.

Extends class AgoraRtcEngineKit.

◆ takeSnapshotEx:uid:filePath:

- (NSInteger) takeSnapshotEx: (AgoraRtcConnection *_Nonnull)  connection
uid: (NSInteger)  uid
filePath: (NSString *_Nonnull)  filePath 

Takes a snapshot of a video stream.

This method takes a snapshot of a video stream from the specified user, generates a JPG image, and saves it to the specified path.

The method is asynchronous, and the SDK has not taken the snapshot when the method call returns. After a successful method call, the SDK triggers the snapshotTaken callback to report whether the snapshot is successfully taken, as well as the details for that snapshot.

Note
  • Call this method after joining a channel.
  • This method takes a snapshot of the published video stream specified in ChannelMediaOptions.
  • If the user's video has been preprocessed, for example, watermarked or beautified, the resulting snapshot includes the pre-processing effect.
Parameters
connectionThe RtcConnection object.
uidThe user ID. Set uid as 0 if you want to take a snapshot of the local user's video.
filePathThe local path (including filename extensions) of the snapshot. For example:
  • Windows: C:\Users\<user_name>\AppData\Local\Agora\<process_name>\example.jpg
  • iOS: /App Sandbox/Library/Caches/example.jpg
  • macOS: ~/Library/Logs/example.jpg
  • Android: /storage/emulated/0/Android/data/<package name>/files/example.jpg

Ensure that the path you specify exists and is writable.

Returns
  • 0 : Success.
  • < 0 : Failure.

Extends class AgoraRtcEngineKit.

◆ takeSnapshotExWithConfig:uid:config:

- (NSInteger) takeSnapshotExWithConfig: (AgoraRtcConnection *_Nonnull)  connection
uid: (NSInteger)  uid
config: (AgoraSnapshotConfig *_Nonnull)  config 

Takes a snapshot of a video stream.

This method takes a snapshot of a video stream from the specified user, generates a JPG image, and saves it to the specified path.

The method is asynchronous, and the SDK has not taken the snapshot when the method call returns. After a successful method call, the SDK triggers the snapshotTaken callback to report whether the snapshot is successfully taken, as well as the details for that snapshot.

Note
  • Call this method after joining a channel.
  • This method takes a snapshot of the published video stream specified in ChannelMediaOptions.
Parameters
connectionThe RtcConnection object.
uidThe user ID. Set uid as 0 if you want to take a snapshot of the local user's video.
configThe configuration for the take snapshot. See SnapshotConfig.

Ensure that the path you specify exists and is writable.

Returns
  • 0 : Success.
  • < 0: Failure.
    • -4: Incorrect observation position. Modify the input observation position according to the reqiurements specified in SnapshotConfig.

Extends class AgoraRtcEngineKit.

◆ sendAudioMetadataEx:metadata:

- (int) sendAudioMetadataEx: (AgoraRtcConnection *_Nonnull)  connection
metadata: (NSData *_Nonnull)  metadata 

send audio metadata

Since
v4.3.1
Parameters
metadataThe NSData of metadata
connectionAgoraRtcConnection.
Returns
  • 0: success
  • <0: failure @technical preview

Extends class AgoraRtcEngineKit.

◆ enableContentInspectEx:config:connection:

- (int) enableContentInspectEx: (BOOL)  enabled
config: (AgoraContentInspectConfig *_Nonnull)  config
connection: (AgoraRtcConnection *_Nonnull)  connection 

Enables video screenshot and upload with the connection ID.

Parameters
enabledWhether to video screenshot and upload:
  • true: Yes.
  • false: No.
configThe configuration for video screenshot and upload.
connectionThe connection information. See AgoraRtcConnection.
Returns
  • 0: Success.
  • < 0: Failure.

Extends class AgoraRtcEngineKit.

◆ startRtmpStreamWithoutTranscodingEx:connection:

- (int) startRtmpStreamWithoutTranscodingEx: (NSString *_Nonnull)  url
connection: (AgoraRtcConnection *_Nonnull)  connection 

Publishes the local stream without transcoding to a specified CDN live RTMP address. (CDN live only.)

Parameters
urlThe CDN streaming URL in the RTMP format. The maximum length of this parameter is 1024 bytes.
connectionAgoraRtcConnection.
Returns
  • 0: Success.
  • < 0: Failure.

Extends class AgoraRtcEngineKit.

◆ startRtmpStreamWithTranscodingEx:transcoding:connection:

- (int) startRtmpStreamWithTranscodingEx: (NSString *_Nonnull)  url
transcoding: (AgoraLiveTranscoding *_Nullable)  transcoding
connection: (AgoraRtcConnection *_Nonnull)  connection 

Publishes the local stream with transcoding to a specified CDN live RTMP address. (CDN live only.)

Parameters
urlThe CDN streaming URL in the RTMP format. The maximum length of this parameter is 1024 bytes.
transcodingSets the CDN live audio/video transcoding settings. See LiveTranscoding.
connectionAgoraRtcConnection.
Returns
  • 0: Success.
  • < 0: Failure.

Extends class AgoraRtcEngineKit.

◆ updateRtmpTranscodingEx:connection:

- (int) updateRtmpTranscodingEx: (AgoraLiveTranscoding *_Nullable)  transcoding
connection: (AgoraRtcConnection *_Nonnull)  connection 

Update the video layout and audio settings for CDN live. (CDN live only.)

Note
This method applies to Live Broadcast only.
Parameters
transcodingSets the CDN live audio/video transcoding settings. See LiveTranscoding.
connectionAgoraRtcConnection.
Returns
  • 0: Success.
  • < 0: Failure.

Extends class AgoraRtcEngineKit.

◆ stopRtmpStreamEx:connection:

- (int) stopRtmpStreamEx: (NSString *_Nonnull)  url
connection: (AgoraRtcConnection *_Nonnull)  connection 

Stop an RTMP stream with transcoding or without transcoding from the CDN. (CDN live only.)

Parameters
urlThe RTMP URL address to be removed. The maximum length of this parameter is 1024 bytes.
connectionAgoraRtcConnection.
Returns
  • 0: Success.
  • < 0: Failure.

Extends class AgoraRtcEngineKit.

◆ startOrUpdateChannelMediaRelayEx:connection:

- (int) startOrUpdateChannelMediaRelayEx: (AgoraChannelMediaRelayConfiguration *_Nonnull)  config
connection: (AgoraRtcConnection *_Nonnull)  connection 

Starts or update to relay media streams across channels.

Since
v4.2.0
Parameters
configThe configuration of the media stream relay:AgoraChannelMediaRelayConfiguration.
connectionAgoraRtcConnection.
Returns
  • 0: Success.
  • < 0: Failure.
    • -1(ERR_FAILED): A general error occurs (no specified reason).
    • -2(ERR_INVALID_ARGUMENT): The argument is invalid.
    • -5(ERR_REFUSED): The request is rejected.
    • -8(ERR_INVALID_STATE): The current status is invalid, only allowed to be called when the role is the broadcaster.

Extends class AgoraRtcEngineKit.

◆ stopChannelMediaRelayEx:

- (int) stopChannelMediaRelayEx: (AgoraRtcConnection *_Nonnull)  connection

Stops the media stream relay.

Once the relay stops, the host quits all the destination channels.

Parameters
connectionAgoraRtcConnection.
Returns
  • 0: Success.
  • < 0: Failure.
    • -1(ERR_FAILED): A general error occurs (no specified reason).
    • -2(ERR_INVALID_ARGUMENT): The argument is invalid.
    • -5(ERR_REFUSED): The request is rejected.
    • -7(ERR_NOT_INITIALIZED): cross channel media streams are not relayed.

Extends class AgoraRtcEngineKit.

◆ pauseAllChannelMediaRelayEx:

- (int) pauseAllChannelMediaRelayEx: (AgoraRtcConnection *_Nonnull)  connection

pause the channels for media stream relay.

Parameters
connectionAgoraRtcConnection.
Returns
  • 0: Success.
  • < 0: Failure.
    • -1(ERR_FAILED): A general error occurs (no specified reason).
    • -2(ERR_INVALID_ARGUMENT): The argument is invalid.
    • -5(ERR_REFUSED): The request is rejected.
    • -7(ERR_NOT_INITIALIZED): cross channel media streams are not relayed.

Extends class AgoraRtcEngineKit.

◆ resumeAllChannelMediaRelayEx:

- (int) resumeAllChannelMediaRelayEx: (AgoraRtcConnection *_Nonnull)  connection

resume the channels for media stream relay.

Parameters
connectionAgoraRtcConnection.
Returns
  • 0: Success.
  • < 0: Failure.
    • -1(ERR_FAILED): A general error occurs (no specified reason).
    • -2(ERR_INVALID_ARGUMENT): The argument is invalid.
    • -5(ERR_REFUSED): The request is rejected.
    • -7(ERR_NOT_INITIALIZED): cross channel media streams are not relayed.

Extends class AgoraRtcEngineKit.

◆ startMediaRenderingTracingEx:

- (int) startMediaRenderingTracingEx: (AgoraRtcConnection *_Nonnull)  connection

Start tracing media rendering events.

Since
v4.1.1 @discussion
  • SDK will trace media rendering events when this API is called.
  • The tracing result can be obtained through callback [AgoraRtcEngineDelegate rtcEngine:videoRenderingTracingResultOfUid:currentEvent:tracingInfo:]
Parameters
connectionAgoraRtcConnection.
Note
  • By default, SDK will trace media rendering events when join channel.
  • The start point of event tracing will be reset after leaving channel.
Returns
  • 0: Success.
  • < 0: Failure.
    • -2(AgoraErrorCodeInvalidArgument): The parameter is invalid. Check the channel ID and local uid set by parameter connection.
    • -7(AgoraErrorCodeNotInitialized): The SDK is not initialized.

Extends class AgoraRtcEngineKit.

◆ setParametersEx:connection:

- (int) setParametersEx: (NSString *_Nonnull)  options
connection: (AgoraRtcConnection *_Nonnull)  connection 

Provides the technical preview functionalities or special customizations by configuring the SDK with JSON options.

Note
The JSON options are not public by default. Agora is working on making commonly used JSON options public in a standard way. Contact suppo.nosp@m.rt@a.nosp@m.gora..nosp@m.io for more information.
Parameters
optionsSDK options in JSON format.
connectionAgoraRtcConnection.

Extends class AgoraRtcEngineKit.

◆ getCallIdEx:

- (NSString * _Nullable) getCallIdEx: (AgoraRtcConnection *_Nonnull)  connection

Gets the current call ID.

When a user joins a channel, a call ID is generated to identify the call.

After a call ends, you can call rate or complain to gather feedback from your customer.

Parameters
connectionThe AgoraRtcConnection object.
Returns
The call ID if the method call is successful.

Extends class AgoraRtcEngineKit.

◆ addDelegateEx:connection:

- (void) addDelegateEx: (id< AgoraRtcEngineDelegate > _Nonnull)  delegate
connection: (AgoraRtcConnection *_Nonnull)  connection 

Adds multiple SDK delegate.

Parameters
delegateThe AgoraRtcEngineDelegate object.
connectionThe AgoraRtcConnection object.

Extends class AgoraRtcEngineKit.

◆ removeDelegateEx:connection:

- (void) removeDelegateEx: (id< AgoraRtcEngineDelegate > _Nonnull)  delegate
connection: (AgoraRtcConnection *_Nonnull)  connection 

Removes multiple SDK delegate.

Parameters
delegateThe AgoraRtcEngineDelegate object.
connectionThe AgoraRtcConnection object.

Extends class AgoraRtcEngineKit.

◆ enableEncryptionEx:encryptionConfig:connection:

- (int) enableEncryptionEx: (BOOL)  enabled
encryptionConfig: (AgoraEncryptionConfig *_Nonnull)  config
connection: (AgoraRtcConnection *_Nonnull)  connection 

Enables/Disables the built-in encryption.

In scenarios requiring high security, Agora recommends calling enableEncryption to enable the built-in encryption before joining a channel.

All users in the same channel must use the same encryption mode and encryption key. Once all users leave the channel, the encryption key of this channel is automatically cleared.

Note**

  • If you enable the built-in encryption, you cannot use the RTMP streaming function.
Parameters
enabledWhether to enable the built-in encryption:
  • YES: Enable the built-in encryption.
  • NO: Disable the built-in encryption.
Parameters
configConfigurations of built-in encryption schemas. See AgoraEncryptionConfig.
connectionAgoraRtcConnection by channelId and uid combine
Returns
- 0: Success.
  • < 0: Failure.
    • -2 (AgoraErrorCodeInvalidArgument): An invalid parameter is used. Set the parameter with a valid value.
    • -7 (AgoraErrorCodeNotInitialized): The SDK is not initialized. Initialize the AgoraRtcEngineKit instance before calling this method.
    • -4 (AgoraErrorCodeNotSupported): The encryption mode is incorrect or the SDK fails to load the external encryption library. Check the enumeration or reload the external encryption library.

Extends class AgoraRtcEngineKit.