AgoraRtcEngineKit(Ex) - All - Agora Documentation

addPublishStreamUrlEx

Publishes the local stream to a specified CDN live streaming URL.

- (int)addPublishStreamUrlEx:(NSString * _Nonnull)url 
          transcodingEnabled:(BOOL)transcodingEnabled
                  connection:(AgoraRtcConnection * _Nonnull)connection;

After calling this method, you can push media streams in RTMP or RTMPS protocol to the CDN according to AgoraRtcConnection. The SDK triggers the rtmpStreamingChangedToState callback on the local client to report the state of adding a local stream to the CDN.

Attention:

Call this method after joining a channel.
Ensure that the media push function is enabled.
This method takes effect only when you are a host in live interactive streaming.
This method adds only one streaming URL to the CDN each time it is called. To push multiple URLs, call this method multiple times.
In one AgoraRtcEngineKit(Ex) instance, you can only push one upstream media stream to the CDN (such as the video stream captured by the camera or the video stream for screen sharing selected by the AgoraRtcConnection).
Agora only supports pushing media streams to the CDN in RTMPS protocol when you enable transcoding.

Parameters

url

The media push URL in the RTMP or RTMPS format. The maximum length of this parameter is 1024 bytes. The URL address must not contain special characters, such as Chinese language characters.

transcodingEnabled

Whether to enable transcoding. Transcoding in a CDN live streaming converts the audio and video streams before pushing them to the CDN server. It applies to scenarios where a channel has multiple broadcasters and composite layout is needed.

YES: Enable transcoding.
NO: Disable transcoding.

Attention: If you set this parameter as YES, ensure that you call the setLiveTranscoding method before calling this method.

connection

The connection info. For details, see AgoraRtcConnection.

Returns

0: Success.
< 0: Failure.
- -2: Invalid parameter, usually an empty URL or a string with a length of 0.
- -7: The engine is not initialized when streaming.

addVideoWatermarkEx

Adds a watermark image to the local video.

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

This method adds a PNG watermark image to the local video in the 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 coordinates are dependent on the settings in the setVideoEncoderConfigurationEx method:

If the orientation mode of the encoding video (AgoraVideoOutputOrientationMode) is FIXED_LANDSCAPE, or the landscape mode in ADAPTIVE, the watermark uses the landscape orientation.
If the orientation mode of the encoding video (AgoraVideoOutputOrientationMode) is FIXED_PORTRAIT, or the portrait mode in ADAPTIVE, the watermark uses the portrait orientation.
When setting the watermark position, the region must be less than the dimensions set in the setVideoEncoderConfigurationEx method. Otherwise, the watermark image will be cropped.

Attention:

Ensure that you have called enableVideo before calling this 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 method, you can use the visibleInPreview member to set whether or not the watermark is visible in the 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 absolute or relative file path.
options: The options of the watermark image to be added. For details, see WatermarkOptions.
connection: The connection info. For details, see AgoraRtcConnection.

Returns

0: Success.
< 0: Failure.

clearVideoWatermarkEx

Removes the watermark image from the video stream.

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

Parameters

connection: The connection info. For details, see AgoraRtcConnection.

Returns

0: Success.
< 0: Failure.

enableLoopbackRecordingEx

Enables loopback audio capturing.

- (int)enableLoopbackRecordingEx:(BOOL)enabled
                    connection:(AgoraRtcConnection * _Nonnull)connection;

If you enable loopback audio capturing, the output of the sound card is mixed into the audio stream sent to the other end.

Parameters

connection

The connection info. For details, see AgoraRtcConnection.

enabled

Sets whether to enable loopback audio capturing.

YES: Enable loopback audio capturing.
NO: (Default) Disable loopback audio capturing.

Returns

0: Success.
< 0: Failure.

getConnectionStateEx

Gets the current connection state of the SDK.

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

You can call this method either before or after joining a channel.

Parameters

connection: The connection info. For details, see AgoraRtcConnection.

Returns

The current connection state. For details, see AgoraConnectionState.

getUserInfoWithUserId

Gets the user information by passing in the user ID.

- (int)getUserInfoWithUserId:(NSUInteger)uid
                    userInfo:(AgoraUserInfo *_Nullable* _Nullable)userInfo
                   channelId:(NSString* _Nonnull)channelId
            localUserAccount:(NSString* _Nonnull)localUserAccount;

After a remote user joins the channel, the SDK gets the UID and user account of the remote user, caches them in a mapping table object, and triggers the didUserInfoUpdatedWithUserId callback on the local client. After receiving the callback, you can call this method to get the user account of the remote user from the AgoraUserInfo object by passing in the user ID.

Parameters

uid

User ID.

userInfo

The AgoraUserInfo object that identifies the user information.

Input value: A AgoraUserInfo object.
Output: A AgoraUserInfo object that contains the user account and user ID of the user.

channelId

The channel name. This parameter signifies the channel in which users engage in real-time audio and video interaction. Under the premise of the same App ID, users who fill in the same channel ID enter the same channel for audio and video interaction. The string length must be less than 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.
Space
"!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "= ", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","

localUserAccount

The user account of the local user.

Returns

0: Success.
< 0: Failure.

getUserInfoWithUserAccount

Gets the user information by passing in the user account.

- (int)getUserInfoWithUserAccount:(NSString * _Nonnull)userAccount
                         userInfo:(AgoraUserInfo *_Nullable* _Nullable)userInfo
                        channelId:(NSString* _Nonnull)channelId
                 localUserAccount:(NSString* _Nonnull)localUserAccount;

After a remote user joins the channel, the SDK gets the UID and user account of the remote user, caches them in a mapping table object, and triggers the didUserInfoUpdatedWithUserId callback on the local client. After receiving the callback, you can call this method to get the user account of the remote user from the AgoraUserInfo object by passing in the user ID.

Parameters

userAccount

The user account.

userInfo

The AgoraUserInfo object that identifies the user information.

Input value: A AgoraUserInfo object.
Output: A AgoraUserInfo object that contains the user account and user ID of the user.

channelId

The channel name. This parameter signifies the channel in which users engage in real-time audio and video interaction. Under the premise of the same App ID, users who fill in the same channel ID enter the same channel for audio and video interaction. The string length must be less than 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.
Space
"!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "= ", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","

localUserAccount

The user account of the local user.

Returns

0: Success.
< 0: Failure.

joinChannelExByToken

Joins a channel with the connection ID.

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

You can call this method multiple times to join more than one channels.

Attention:

If you are already in a channel, you cannot rejoin it with the same user ID.
We recommend using different user IDs for different channels.
If you want to join the same channel from different devices, ensure that the user IDs in all devices are different.
Ensure that the App ID you use to generate the token is the same with the App ID used when creating the AgoraRtcEngineKit instance.

Parameters

token: The token generated on your server for authentication. See Authenticate Your Users with Token.
connection: The connection info. For details, see AgoraRtcConnection.
mediaOptions: The channel media options. See AgoraRtcChannelMediaOptions for details.
delegate: The callback class of AgoraRtcEngineKit(Ex). For details, see AgoraRtcEngineDelegate.
joinSuccessBlock: The block of a user joining the specified channel. joinSuccessBlock takes higher priority than didJoinChannel. If you implement both callbacks, only block is triggered. Agora recommends setting joinSuccessBlock as nil to use the AgoraRtcEngineDelegate callback.

Returns

0: Success.
< 0: Failure.

joinChannelExByToken

Joins the channel with a user account, and configures whether to automatically subscribe to audio or video streams after joining the channel.

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

This method allows a user to join the channel with the user account. After the user successfully joins the channel, the SDK triggers the following callbacks:

The local client: didLocalUserRegisteredWithUserId, didJoinChannel and connectionChangedToState callbacks.
The remote client: The didJoinedOfUid callback if the user is in the COMMUNICATION profile, and the didUserInfoUpdatedWithUserId callback if the user is a host in the LIVE_BROADCASTING profile.

Once a user joins the channel, the user subscribes to the audio and video streams of all the other users in the channel by default, giving rise to usage and billing calculation. To stop subscribing to a specified stream or all remote streams, call the corresponding mute methods.

Attention: 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 ID of the user is set to the same parameter type.

Parameters

token

The token generated on your server for authentication. See Authenticate Your Users with Token.

channelId

The channel name. This parameter signifies the channel in which users engage in real-time audio and video interaction. Under the premise of the same App ID, users who fill in the same channel ID enter the same channel for audio and video interaction. The string length must be less than 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.
Space
"!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "= ", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","

userAccount

The user account. This parameter is used to identify the user in the channel for real-time audio and video engagement. You need to set and manage user accounts yourself and ensure that each user account in the same channel is unique. The maximum length of this parameter is 255 bytes. Ensure that you set this parameter and do not set it as nil. Supported characters are (89 in total):

The 26 lowercase English letters: a to z.
The 26 uppercase English letters: A to Z.
All numeric characters: 0 to 9.
Space
"!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","

mediaOptions

The channel media options. See AgoraRtcChannelMediaOptions for details.

delegate

The callback class of AgoraRtcEngineKit(Ex). For details, see AgoraRtcEngineDelegate.

joinSuccessBlock

The block of a user joining the specified channel. joinSuccessBlock takes higher priority than didJoinChannel. If you implement both callbacks, only block is triggered. Agora recommends setting joinSuccessBlock as nil to use the AgoraRtcEngineDelegate callback.

Returns

0: Success.
< 0: Failure.

leaveChannelEx

Leaves a channel.

- (int)leaveChannelEx:(AgoraRtcConnection * _Nonnull)connection
    leaveChannelBlock:(void(^ _Nullable)(AgoraChannelStats* _Nonnull stat))leaveChannelBlock;

Parameters

connection: The connection info. For details, see AgoraRtcConnection.
leaveChannelBlock: This callback indicates that a user leaves a channel, and provides the statistics of the call in AgoraChannelStats.

Returns

0: Success.
< 0: Failure.

muteRemoteAudioStreamEx

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

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

This method is used to stops or resumes receiving the audio stream of a specified user. You can call this method before or after joining a channel. If a user leaves a channel, the settings in this method become invalid.

Parameters

uid

The ID of the specified user.

mute

Whether to stop receiving the audio stream of the specified user:

YES: Stop receiving the audio stream of the specified user.
NO: (Default) Resume receiving the audio stream of the specified user.

connection

The connection info. For details, see AgoraRtcConnection.

Returns

0: Success.
< 0: Failure.

muteRemoteVideoStreamEx

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

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

This method is used to stops or resumes receiving the video stream of a specified user. You can call this method before or after joining a channel. If a user leaves a channel, the settings in this method become invalid.

Parameters

uid

The user ID of the remote user.

mute

Whether to stop receiving the video stream of the specified user:

YES: Stop receiving the video stream of the specified user.
NO: (Default) Resume receiving the video stream of the specified user.

connection

The connection info. For details, see AgoraRtcConnection.

Returns

0: Success.
< 0: Failure.

pushExternalVideoFrame

Pushes the external raw video frame to the SDK.

- (BOOL)pushExternalVideoFrame:(AgoraVideoFrame * _Nonnull)frame connection:(AgoraRtcConnection * _Nonnull)connection;

If you call setExternalVideoSource and set the enabled parameter as YES and the encodedFrame parameter as NO, you can call this method to push the external raw video frame to the SDK.

Parameters

frame: The external raw video frame to be pushed. See AgoraVideoFrame for details.
connection: The connection info. For details, see AgoraRtcConnection.

Returns

YES: Pushes the external raw video frame to the SDK successfully.
NO: Fails to push external raw video frame to the SDK.

sendCustomReportMessageEx

Agora supports reporting and analyzing customized messages.

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

Agora supports reporting and analyzing customized messages. This function is in the beta stage with a free trial. The ability provided in its beta test version is reporting a maximum of 10 message pieces within 6 seconds, with each message piece not exceeding 256 bytes and each string not exceeding 100 bytes. To try out this function, contact support@agora.io and discuss the format of customized messages with us.

setRemoteRenderModeEx

Sets the video display mode of a specified remote user.

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

After initializing the video view of a remote user, you can call this method to update its rendering and mirror modes. This method affects only the video view that the local user sees.

Attention:

Please call this method after calling the setupRemoteVideo method to initialize the remote view.
During a call, you can call this method as many times as necessary to update the display mode of the video view of a remote user.

Parameters

uid: The ID of the remote user.
renderMode: The video display mode of the remote user. For details, see AgoraVideoRenderMode.
mirrorMode: The mirror mode of the remote user view. For details, see AgoraVideoMirrorMode.
connection: The connection info. For details, see AgoraRtcConnection.

Returns

0: Success.
< 0: Failure.

setRemoteVoicePositionEx

Sets the 2D position (the position on the horizontal plane) of the remote user's voice.

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

This method sets the voice position and volume of a remote user.

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

Attention:

For the best voice positioning, Agora recommends using a wired headset.
Call this method after joining a channel.

Parameters

uid

The user ID of the remote user.

pan

The voice position of the remote user. The value ranges from -1.0 to 1.0:

-1.0: The remote voice comes from the left.
0.0: (Default) The remote voice comes from the front.
1.0: The remote voice comes from the right.

gain

The volume of the remote user. The value ranges from 0.0 to 100.0. The default value is 100.0 (the original volume of the remote user). The smaller the value, the lower the volume.

connection

The connection info. For details, see AgoraRtcConnection.

Returns

0: Success.
< 0: Failure.

setupRemoteVideoEx

Initializes the video view of a remote user.

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

This method initializes the video view of a remote stream on the local device. It affects only the video view that the local user sees. Call this method to bind the remote video stream to a video view and to set the rendering and mirror modes of the video view.

The application specifies the uid of the remote video in the AgoraRtcVideoCanvas method before the remote user joins the channel.

If the remote uid is unknown to the application, set it after the application receives the didJoinedOfUid callback. If the Video Recording function is enabled, the Video Recording Service joins the channel as a dummy client, causing other clients to also receive the onUserJoined callback. Do not bind the dummy client to the application view because the dummy client does not send any video streams.

To unbind the remote user from the view, set the view parameter to NULL.

Once the remote user leaves the channel, the SDK unbinds the remote user.

Attention:

To update the rendering or mirror mode of the remote video view during a call, use the setRemoteRenderModeEx method.

Parameters

remote: The remote video view settings. For details, see AgoraRtcVideoCanvas.
connection: The connection info. For details, see AgoraRtcConnection.

Returns

0: Success.
< 0: Failure.

setVideoEncoderConfigurationEx

Sets the encoder configuration for the local video.

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

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

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

Parameters

config: Video profile. For details, see AgoraVideoEncoderConfiguration.
connection: The connection info. For details, see AgoraRtcConnection.

Returns

0: Success.
< 0: Failure.

updateChannelExWithMediaOptions

Updates the channel media options after joining the channel.

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

Parameters

options: The channel media options. See AgoraRtcChannelMediaOptions.
connection: The connection info. For details, see AgoraRtcConnection.

Returns

0: Success.
< 0: Failure.