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:
(int) | - enableVideoImageSourceEx:options: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

  token | The 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.
  connection | AgoraRtcConnection by channelId and uid combine
  delegate | AgoraRtcEngineDelegate protocol.(Need a new object when called)
  mediaOptions | AgoraRtcChannelMediaOptions Object.
  joinSuccessBlock | Same 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:

- The local client: onLocalUserRegistered and onJoinChannelSuccess . The remote client: onUserJoined and onUserInfoUpdated , if the user joining the channel is in the `COMMUNICATION` profile, or is a host in the `LIVE_BROADCASTING` profile.

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

  token | The 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.
  channelId | The 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: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
  userAccount | The 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: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
  delegate | AgoraRtcEngineDelegate protocol.
  mediaOptions | The 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

  mediaOptions | The channel media options: ChannelMediaOptions.
  connection | AgoraRtcConnection 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

  delegate | The AgoraRtcEngineDelegate protocol.
  connection | The 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

  mute | Determines whether to send or stop sending the local audio stream: `YES`: Stop sending the local audio stream. `NO`: Send the local audio stream.
  connection | AgoraRtcConnection 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

  mute | Determines whether to send or stop sending the local video stream: `YES`: Stop sending the local video stream. `NO`: Send the local video stream.
  connection | AgoraRtcConnection 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

  uid | User 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.
  connection | AgoraRtcConnection 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

  mute | Whether to stop receiving remote audio streams: `YES`: Stop receiving any remote audio stream. `NO`: Resume receiving all remote audio streams.
  connection | AgoraRtcConnection 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

  config | The local video encoder configuration, see #AgoraVideoEncoderConfiguration.
  connection | AgoraRtcConnection 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

  remote | AgoraRtcVideoCanvas
  connection | AgoraRtcConnection 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

  uid | User id of the user whose video streams are received.
  mode | AgoraVideoRenderMode
  mirror | AgoraVideoMirrorMode
  connection | AgoraRtcConnection 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

  uid | ID of the specified remote user.
  mute | Determines whether to receive or stop receiving a specified video stream: `YES`: Stop receiving the specified video stream. `NO`: (Default) Receive the specified video stream.
  connection | AgoraRtcConnection 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

  mute | Whether to stop receiving remote video streams: `YES`: Stop receiving any remote video stream. `NO`: Resume receiving all remote video streams.
  connection | AgoraRtcConnection 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.
  streamConfig | The minor stream config
  connection | An 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

  mode | The dual-stream mode.
  streamConfig | The minor stream config
  connection | An 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.
  connection | The 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

  uid | ID of the remote user sending the video stream.
  streamType | The video stream type: AgoraVideoStreamType.
  connection | AgoraRtcConnection 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

  uid | ID of the remote user sending the video stream.
  options | Sets the video subscription options.
  connection | AgoraRtcConnection 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

  userAccount | The user account of the user. Ensure that you set this parameter.
  connection | AgoraRtcConnection 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

  uid | The user ID of the remote user. Ensure that you set this parameter.
  connection | AgoraRtcConnection 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

  connection | AgoraRtcConnection 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

  volume | The 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.
  connection | AgoraRtcConnection 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

  mute | Determines whether to mute or resume the recording signal volume. YES: Mute the recording signal volume. NO: (Default) Resume the recording signal volume.
  connection | AgoraRtcConnection 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

  uid | The ID of the remote user.
  volume | The playback volume of the specified remote user. The value ranges between 0 and 400, including the following:

- 0: Mute.
- 100: (Default) Original volume.
  Parameters

    connection | AgoraRtcConnection 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

      uid | The ID of the remote user.
      pan | The 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

  gain | Gain 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.
  connection | AgoraRtcConnection 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

  url | The 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.
  options | The options of the watermark image to be added. See WatermarkOptions.
  connection | AgoraRtcConnection 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

  connection | AgoraRtcConnection 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

  streamId | ID of the created data stream.
  reliable | Sets 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.
  ordered | Sets 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.
  connection | AgoraRtcConnection 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

  streamId | ID of the created data stream.
  config | the config of data stream.
  connection | AgoraRtcConnection 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

  streamId | ID of the sent data stream returned in the `createDataStream` method.
  data | Sent data.
  connection | AgoraRtcConnection 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

  uidList | The uid list of high priority users.
  option | The remote subscribe fallback option of high priority users.
  connection | AgoraRtcConnection 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

  allowlist | The uid list of users who do subscribe to audio.
  connection | AgoraRtcConnection 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

  allowlist | The uid list of users who do subscribe to video.
  connection | AgoraRtcConnection 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

  connection | The RtcConnection object.
  uid | The user ID. Set uid as 0 if you want to take a snapshot of the local user's video.
  filePath | The 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

  connection | The RtcConnection object.
  uid | The user ID. Set uid as 0 if you want to take a snapshot of the local user's video.
  config | The 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

  metadata | The NSData of metadata
  connection | AgoraRtcConnection.

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

  enabled | Whether to video screenshot and upload: `true`: Yes. `false`: No.
  config | The configuration for video screenshot and upload.
  connection | The 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

  url | The CDN streaming URL in the RTMP format. The maximum length of this parameter is 1024 bytes.
  connection | AgoraRtcConnection.

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

  url | The CDN streaming URL in the RTMP format. The maximum length of this parameter is 1024 bytes.
  transcoding | Sets the CDN live audio/video transcoding settings. See LiveTranscoding.
  connection | AgoraRtcConnection.

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

  transcoding | Sets the CDN live audio/video transcoding settings. See LiveTranscoding.
  connection | AgoraRtcConnection.

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

  url | The RTMP URL address to be removed. The maximum length of this parameter is 1024 bytes.
  connection | AgoraRtcConnection.

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

  config | The configuration of the media stream relay:AgoraChannelMediaRelayConfiguration.
  connection | AgoraRtcConnection.

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

  connection | AgoraRtcConnection.

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

  connection | AgoraRtcConnection.

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

  connection | AgoraRtcConnection.

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

  connection | AgoraRtcConnection.

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

  options | SDK options in JSON format.
  connection | AgoraRtcConnection.

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

  connection | The 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

  delegate | The AgoraRtcEngineDelegate object.
  connection | The AgoraRtcConnection object.

Extends class AgoraRtcEngineKit.

## ◆ removeDelegateEx:connection:

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

Removes multiple SDK delegate.

Parameters

  delegate | The AgoraRtcEngineDelegate object.
  connection | The 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

  enabled | Whether to enable the built-in encryption:

- YES: Enable the built-in encryption.
- NO: Disable the built-in encryption.

Parameters

  config | Configurations of built-in encryption schemas. See AgoraEncryptionConfig.
  connection | AgoraRtcConnection 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.

## ◆ enableVideoImageSourceEx:options:connection:

- (int) enableVideoImageSourceEx: |  | (BOOL) | enable
options: |  | (AgoraImageTrackOptions *_Nullable) | options
connection: |  | (AgoraRtcConnection *_Nonnull) | connection

Enable or disable video image source to replace the current video source published or resume it

Parameters

  enable | true for enable, false for disable
  options | options for image track
  connection | The AgoraRtcConnection object.

Extends class AgoraRtcEngineKit.