AgoraRtcChannel Class Reference

Inherits from NSObject
Declared in AgoraRtcChannel.h

Overview

The AgoraRtcChannel class.

Since v3.0.0.

– destroy

Destroys the AgoraRtcChannel instance.

- (int)destroy

Return Value

  • 0: Success.

  • < 0: Failure.

    • AgoraErrorCodeNotInitialized(-7): The AgoraRtcChannel instance is not initialized before calling this method.

Declared In

AgoraRtcChannel.h

– setRtcChannelDelegate:

Sets the channel delegate.

- (void)setRtcChannelDelegate:(id<AgoraRtcChannelDelegate> _Nullable)channelDelegate

Parameters

channelDelegate

The delegate of the AgoraRtcChannel instance. For details, see AgoraRtcChannelDelegate.

Discussion

After setting the channel delegate, you can listen for channel events and receive the statistics of the corresponding AgoraRtcChannel instance.

Declared In

AgoraRtcChannel.h

– getChannelId

Gets the channel ID of the current AgoraRtcChannel instance.

- (NSString *_Nullable)getChannelId

Return Value

  • The channel ID of the current AgoraRtcChannel instance, if the method call succeeds.
  • The empty string “”, if the method call fails.

Declared In

AgoraRtcChannel.h

– getCallId

Gets the current call ID.

- (NSString *_Nullable)getCallId

Return Value

  • The current call ID, if the method call succeeds.
  • The empty string “”, if the method call fails.

Discussion

Note: Ensure that you call this method after joining a channel.

Declared In

AgoraRtcChannel.h

– getConnectionState

Gets the connection state of the SDK.

- (AgoraConnectionStateType)getConnectionState

Return Value

The connection state, see AgoraConnectionStateType:

  • AgoraConnectionStateDisconnected(1): The SDK is disconnected from Agora’s edge server.
  • AgoraConnectionStateConnecting(2): The SDK is connecting to Agora’s edge server.
  • AgoraConnectionStateConnected(3): The SDK joined a channel and is connected to Agora’s edge server. You can now publish or subscribe to a media stream in the channel.
  • AgoraConnectionStateReconnecting(4): The SDK keeps rejoining the channel after being disconnected from a joined channel because of network issues.
  • AgoraConnectionStateFailed(5): The SDK fails to join the channel.

Discussion

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

Declared In

AgoraRtcChannel.h

– joinChannelByToken:info:uid:options:

Joins the channel with a user ID.

- (int)joinChannelByToken:(NSString *_Nullable)token info:(NSString *_Nullable)info uid:(NSUInteger)uid options:(AgoraRtcChannelMediaOptions *_Nonnull)options

Parameters

token

The token for authentication:

  • In situations not requiring high security: You can use the temporary token generated at Agora Console. For details, see Get a temporary token.
  • In situations requiring high security: Set it as the token generated at your server. For details, see Generate a token.
info

(Optional) Additional information about the channel. This parameter can be set as nil. Other users in the channel do not receive this information.
uid

The user ID. A 32-bit unsigned integer with a value ranging from 1 to (232-1). This parameter must be unique. If uid is not assigned (or set as 0), the SDK assigns a uid and reports it in the rtcChannelDidJoinChannel callback. The app must maintain this user ID.
options

The channel media options: AgoraRtcChannelMediaOptions

Return Value

  • 0(AgoraErrorCodeNoError): Success.

  • < 0: Failure.

    • -2(AgoraErrorCodeInvalidArgument): The parameter is invalid.
    • -3(AgoraErrorCodeNotReady): The SDK fails to be initialized. You can try re-initializing the SDK.

    • -5(AgoraErrorCodeRefused): The request is rejected. This may be caused by the following:

      • You have created an AgoraRtcChannel object with the same channel name.
      • You have joined and published a stream in a channel created by the AgoraRtcChannel object.

Discussion

This method differs from the joinChannelByToken1 method in the AgoraRtcEngineKit class in the following aspects:

AgoraRtcChannel joinChannelByToken AgoraRtcEngineKit joinChannelByToken1
Does not contain the channelId parameter, because channelId is specified when creating the AgoraRtcChannel instance. Contains the channelId parameter, which specifies the channel to join.
Contains the options parameter, which decides whether to subscribe to all streams before joining the channel. Does not contain the options parameter. By default, users subscribe to all streams when joining the channel. To configure media subscribing options when joining the channel, use joinChannelByToken2 instead.
Users can join multiple channels simultaneously by creating multiple AgoraRtcChannel instances and calling the joinChannelByToken method of each instance. Users can join only one channel.
By default, the SDK does not publish any stream after the user joins the channel. You need to call the publish method to do that. By default, the SDK publishes streams once the user joins the channel.

Note

  • If you are already in a channel, you cannot rejoin it with the same uid.
  • We recommend using different uid for different channels.
  • If you want to join the same channel from different devices, ensure that the uid 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.

Declared In

AgoraRtcChannel.h

– joinChannelByUserAccount:token:options:

Joins a channel with the user account.

- (int)joinChannelByUserAccount:(NSString *_Nonnull)userAccount token:(NSString *_Nullable)token options:(AgoraRtcChannelMediaOptions *_Nonnull)options

Parameters

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 nil.

  • 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: “!”, “#”, “$”, “%”, “&”, “(”, “)”, “+”, “-”, “:”, “;”, “<”, “=”, “.”, “>”, “?”, “@”, “[”, “]”, “^”, “_”, “{”, “}”, “|”, “~”, “,”.
token

The token generated at your server:

  • 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 your server. For details, see Generate a token.
options

The channel media options: AgoraRtcChannelMediaOptions

Return Value

  • 0: Success.

  • < 0: Failure.

    • AgoraErrorCodeInvalidArgument(-2)
    • AgoraErrorCodeNotReady(-3)
    • AgoraErrorCodeRefused(-5)

Discussion

This method differs from the joinChannelByUserAccount1 method in the AgoraRtcEngineKit class in the following aspects:

AgoraRtcChannel joinChannelByUserAccount AgoraRtcEngineKit joinChannelByUserAccount1
Does not contain the channelId parameter, because channelId is specified when creating the AgoraRtcChannel instance. Contains the channelId parameter, which specifies the channel to join.
Contains the options parameter, which decides whether to subscribe to all streams before joining the channel. Does not contain the options parameter. By default, users subscribe to all streams when joining the channel. To configure media subscribing options when joining the channel, use joinChannelByUserAccount2 instead.
Users can join multiple channels simultaneously by creating multiple AgoraRtcChannel instances and calling the joinChannelByUserAccount method of each instance. Users can join only one channel.
By default, the SDK does not publish any stream after the user joins the channel. You need to call the publish method to do that. By default, the SDK publishes streams once the user joins the channel.

Note

  • If you are already in a channel, you cannot rejoin it with the same uid.
  • We recommend using different uid for different channels.
  • If you want to join the same channel from different devices, ensure that the uid 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.

Declared In

AgoraRtcChannel.h

– leaveChannel

Leaves the current channel.

- (int)leaveChannel

Return Value

  • 0(AgoraErrorCodeNoError): Success.

  • < 0: Failure.

    • -1(AgoraErrorCodeFailed): A general error occurs (no specified reason).
    • -2(AgoraErrorCodeInvalidArgument): The parameter is invalid.
    • -7(AgoraErrorCodeNotInitialized): The SDK is not initialized.

Discussion

A successful leaveChannel method call triggers the following callbacks:

Declared In

AgoraRtcChannel.h

– publish

Publishes the local stream to the channel.

- (int)publish

Return Value

  • 0: Success.

  • < 0: Failure.

    • AgoraErrorCodeRefused(-5): The method call is refused.

Discussion

You must keep the following restrictions in mind when calling this method. Otherwise, the SDK returns the AgoraErrorCodeRefused(-5)：

  • This method publishes one stream only to the channel corresponding to the current AgoraRtcChannel instance.
  • In a Live-Broadcast channel, only a host can call this method. To switch the client role, call setClientRole of the current AgoraRtcChannel instance.
  • You can publish a stream to only one channel at a time. For details, see the advanced guide Join Multiple Channels.

Declared In

AgoraRtcChannel.h

– unpublish

Stops publishing a stream to the channel.

- (int)unpublish

Return Value

  • 0: Success.

  • < 0: Failure.

    • AgoraErrorCodeRefused(-5): The method call is refused.

Discussion

If you call this method in a channel where you are not publishing streams, the SDK returns AgoraErrorCodeRefused(-5).

Declared In

AgoraRtcChannel.h

– setClientRole:

Sets the role of a user.

- (int)setClientRole:(AgoraClientRole)role

Parameters

role

The role of the user:

  • AgoraClientRoleBroadcaster(1): Host. A host can both send and receive streams.
  • AgoraClientRoleAudience(2): Audience, the default role. An audience can only receive streams.

Return Value

  • 0(AgoraErrorCodeNoError): Success.

  • < 0: Failure.

    • -1(AgoraErrorCodeFailed): A general error occurs (no specified reason).
    • -2(AgoraErrorCodeInvalidArgument): The parameter is invalid.
    • -7(AgoraErrorCodeNotInitialized): The SDK is not initialized.

Discussion

This method sets the role of a user, such as a host or an audience. In an interactive live streaming channel, only a host can call the publish method in the AgoraRtcChannel class.

A successful call of this method triggers the following callbacks:

Declared In

AgoraRtcChannel.h

– setClientRole:options:

Sets the role of a user in a interactive live streaming.

- (int)setClientRole:(AgoraClientRole)role options:(AgoraClientRoleOptions *_Nullable)options

Parameters

role

The role of a user in a interactive live streaming. See AgoraClientRole.
options

The detailed options of a user, including user level. See AgoraClientRoleOptions.

Return Value

  • 0(AgoraErrorCodeNoError): Success.

  • < 0: Failure.

    • -1(AgoraErrorCodeFailed): A general error occurs (no specified reason).
    • -2(AgoraErrorCodeInvalidArgument): The parameter is invalid.
    • -7(AgoraErrorCodeNotInitialized): The SDK is not initialized.

Availability

v3.2.0

You can call this method either before or after joining the channel to set the user role as audience or host. If you call this method to switch the user role after joining the channel, the SDK triggers the following callbacks:

Note:

  • This method applies to the LiveBroadcasting profile only (when the profile parameter in setChannelProfile is set as AgoraChannelProfileLiveBroadcasting).

  • The difference between this method and setClientRole1 is that this method can set the user level in addition to the user role.

    • The user role determines the permissions that the SDK grants to a user, such as permission to send local streams, receive remote streams, and push streams to a CDN address.
    • The user level determines the level of services that a user can enjoy within the permissions of the user’s role. For example, an audience can choose to receive remote streams with low latency or ultra low latency. Levels affect prices.

Declared In

AgoraRtcChannel.h

– renewToken:

Renews the token when the current token expires.

- (int)renewToken:(NSString *_Nonnull)token

Parameters

token

The new token.

Return Value

  • 0(AgoraErrorCodeNoError): Success.

  • < 0: Failure.

    • -1(AgoraErrorCodeFailed): A general error occurs (no specified reason).
    • -2(AgoraErrorCodeInvalidArgument): The parameter is invalid.
    • -7(AgoraErrorCodeNotInitialized): The SDK is not initialized.

Discussion

In the following situations, the SDK decides that the current token has expired:

You should get a new token from your server and call this method to renew it. Failure to do so results in the SDK disconnecting from the Agora server.

Note

Agora recommends using the rtcChannelRequestToken callback to report the AgoraErrorCodeTokenExpired(-109) error, not using the didOccurError callback.

Declared In

AgoraRtcChannel.h

– setEncryptionSecret:

Enables built-in encryption with an encryption password before joining a channel.

- (int)setEncryptionSecret:(NSString *_Nullable)secret

Parameters

secret

Encryption password.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

DEPRECATED from v3.1.0. Use enableEncryption instead.

All users in a channel must set the same encryption password. The encryption password is automatically cleared once a user leaves the channel.

If the encryption password is not specified or set to empty, the encryption functionality is disabled.

Note

  • Do not use this method for CDN live streaming.
  • For optimal transmission, ensure that the encrypted data size does not exceed the original data size + 16 bytes. 16 bytes is the maximum padding size for AES encryption.

Declared In

AgoraRtcChannel.h

– setEncryptionMode:

Sets the built-in encryption mode.

- (int)setEncryptionMode:(NSString *_Nullable)encryptionMode

Parameters

encryptionMode

Sets the encryption mode.

  • “aes-128-xts”: (default) 128-bit AES encryption, XTS mode.
  • “aes-256-xts”: 256-bit AES encryption, XTS mode.
  • “aes-128-ecb”: 128-bit AES encryption, ECB mode.
  • “”: (Default) When encryptionMode is set as the empty string, the encryption is in “aes-128-xts” by default.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

DEPRECATED from v3.1.0. Use enableEncryption instead.

The SDK supports built-in encryption, which is set to the “aes-128-xts” mode by default. Call this method to use other encryption modes.

All users in the same channel must use the same encryption mode and password.

Refer to the information related to the AES encryption algorithm on the differences between the encryption modes.

Note

  • Call the setEncryptionSecret method to enable the built-in encryption function before calling this method.
  • Do not use this method for CDN live streaming.

Declared In

AgoraRtcChannel.h

– enableEncryption:encryptionConfig:

Enables/Disables the built-in encryption.

- (int)enableEncryption:(bool)enabled encryptionConfig:(AgoraEncryptionConfig *)config

Parameters

enabled

Whether to enable the built-in encryption:

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

Configurations of built-in encryption schemas. See AgoraEncryptionConfig.

Return Value

  • 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.

Availability

v3.1.0

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. After a user leaves the channel, the SDK automatically disables the built-in encryption. To enable the built-in encryption, call this method before the user joins the channel again.

Discussion

Note: If you enable the built-in encryption, you cannot use the RTMP or RTMPS streaming function.

Declared In

AgoraRtcChannel.h

– setRemoteUserPriority:type:

Sets the priority of a remote user’s stream.

- (int)setRemoteUserPriority:(NSUInteger)uid type:(AgoraUserPriority)userPriority

Parameters

uid

The ID of the remote user.
userPriority

The priority of the remote user, see AgoraUserPriority.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

The SDK ensures the high-priority user gets the best possible stream quality.

Note

The SDK supports setting userPriority as high for one user only.

Declared In

AgoraRtcChannel.h

– setRemoteVoicePosition:pan:gain:

Sets the sound position and gain of a remote user.

- (int)setRemoteVoicePosition:(NSUInteger)uid pan:(double)pan gain:(double)gain

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.
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.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

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 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.

Declared In

AgoraRtcChannel.h

– setRemoteRenderMode:renderMode:mirrorMode:

Updates the display mode of the video view of a remote user.

- (int)setRemoteRenderMode:(NSUInteger)uid renderMode:(AgoraVideoRenderMode)renderMode mirrorMode:(AgoraVideoMirrorMode)mirrorMode

Parameters

uid

The ID of the remote user.
renderMode

The rendering mode of the remote video view. See AgoraVideoRenderMode.
mirrorMode

The mirror mode of the remote video view. See AgoraVideoMirrorMode.

Note

The SDK disables the mirror mode by default.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

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.

Note

  • Ensure that you have called setupRemoteVideo to initialize the remote video view before calling this method.
  • 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.

Declared In

AgoraRtcChannel.h

– setDefaultMuteAllRemoteAudioStreams:

Stops or resumes subscribing to the audio streams of all remote users by default.

- (int)setDefaultMuteAllRemoteAudioStreams:(BOOL)mute

Parameters

mute

Sets whether to stop subscribing to the audio streams of all remote users by default.

  • YES: Stop subscribing to the audio streams of all remote users by default.
  • NO: (Default) Resume subscribing to the audio streams of all remote users by default.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

Deprecated This method is deprecated from v3.3.0.

Call this method after joining a channel. After successfully calling this method, the local user stops or resumes subscribing to the audio streams of all subsequent users.

Note

If you need to resume subscribing to the audio streams of remote users in the channel after calling setDefaultMuteAllRemoteAudioStreams(true), do the following:

  • If you need to resume subscribing to the audio stream of a specified user, call muteRemoteAudioStream(false), and specify the user ID.
  • If you need to resume subscribing to the audio streams of multiple remote users, call muteRemoteAudioStream(false) multiple times.

Declared In

AgoraRtcChannel.h

– setDefaultMuteAllRemoteVideoStreams:

Stops or resumes subscribing to the video streams of all remote users by default.

- (int)setDefaultMuteAllRemoteVideoStreams:(BOOL)mute

Parameters

mute

Sets whether to stop subscribing to the video streams of all remote users by default.

  • YES: Stop subscribing to the video streams of all remote users by default.
  • NO: (Default) Resume subscribing to the video streams of all remote users by default.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

Deprecated This method is deprecated from v3.3.0.

Call this method after joining a channel. After successfully calling this method, the local user stops or resumes subscribing to the video streams of all subsequent users.

Note

If you need to resume subscribing to the video streams of remote users in the channel after calling setDefaultMuteAllRemoteVideoStreams(true), do the following:

  • If you need to resume subscribing to the video stream of a specified user, call muteRemoteVideoStream(false), and specify the user ID.
  • If you need to resume subscribing to the video streams of multiple remote users, call muteRemoteVideoStream(false) multiple times.

Declared In

AgoraRtcChannel.h

– muteRemoteAudioStream:mute:

Stops or resumes subscribing to the audio stream of a specified user.

- (int)muteRemoteAudioStream:(NSUInteger)uid mute:(BOOL)mute

Parameters

uid

The user ID of the specified remote user.
mute

Sets whether to stop subscribing to the audio stream of a specified user.

  • YES: Stop subscribing to the audio stream of a specified user.
  • NO: (Default) Resume subscribing to the audio stream of a specified user.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

Note:

  • Call this method after joining a channel.
  • See recommended settings in Set the Subscribing State.

Declared In

AgoraRtcChannel.h

– adjustUserPlaybackSignalVolume:volume:

Adjust the playback signal volume of a specified remote user.

- (int)adjustUserPlaybackSignalVolume:(NSUInteger)uid volume:(int)volume

Parameters

uid

The ID of the remote user.
volume

The playback volume of the specified remote user. The value ranges from 0 to 100:

  • 0: Mute.
  • 100: Original volume.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

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

  • Call this method after joining a channel.
  • 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.

Declared In

AgoraRtcChannel.h

– muteAllRemoteAudioStreams:

Stops or resumes subscribing to the audio streams of all remote users.

- (int)muteAllRemoteAudioStreams:(BOOL)mute

Parameters

mute

Sets whether to stop subscribing to the audio streams of all remote users.

  • YES: Stop subscribing to the audio streams of all remote users.
  • NO: (Default) Resume subscribing to the audio streams of all remote users.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

As of v3.3.0, after successfully calling this method, the local user stops or resumes subscribing to the audio streams of all remote users, including all subsequent users.

Note

  • Call this method after joining a channel.
  • See recommended settings in Set the Subscribing State.

Declared In

AgoraRtcChannel.h

– muteRemoteVideoStream:mute:

Stops or resumes subscribing to the video stream of a specified user.

- (int)muteRemoteVideoStream:(NSUInteger)uid mute:(BOOL)mute

Parameters

uid

The user ID of the specified remote user.
mute

Sets whether to stop subscribing to the video stream of a specified user.

  • YES: Stop subscribing to the video stream of a specified user.
  • NO: (Default) Resume subscribing to the video stream of a specified user.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

Note:

  • Call this method after joining a channel.
  • See recommended settings in Set the Subscribing State.

Declared In

AgoraRtcChannel.h

– muteAllRemoteVideoStreams:

Stops or resumes subscribing to the video streams of all remote users.

- (int)muteAllRemoteVideoStreams:(BOOL)mute

Parameters

mute

Sets whether to stop subscribing to the video streams of all remote users.

  • YES: Stop subscribing to the video streams of all remote users.
  • NO: (Default) Resume subscribing to the video streams of all remote users.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

As of v3.3.0, after successfully calling this method, the local user stops or resumes subscribing to the video streams of all remote users, including all subsequent users.

Note

  • Call this method after joining a channel.
  • See recommended settings in Set the Subscribing State.

Declared In

AgoraRtcChannel.h

– setRemoteVideoStream:type:

Sets the stream type of the remote video.

- (int)setRemoteVideoStream:(NSUInteger)uid type:(AgoraVideoStreamType)streamType

Parameters

uid

ID of the remote user sending the video stream.
streamType

Sets the video-stream type. See AgoraVideoStreamType.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

Under limited network conditions, if the publisher has not disabled the dual-stream mode using enableDualStreamMode(NO)enableDualStreamMode(NO), the receiver can choose to receive either the high-quality video stream (the high resolution, and high bitrate video stream) or the low-quality video stream (the low resolution, and low bitrate video stream).

By default, users receive the high-quality video stream. Call this method if you want to switch to the low-quality video stream. This method allows the app to adjust the corresponding video stream type based on the size of the video window to reduce the bandwidth and resources.

The aspect ratio of the low-quality video stream is the same as the high-quality video stream. Once the resolution of the high-quality video stream is set, the system automatically sets the resolution, frame rate, and bitrate of the low-quality video stream.

The SDK reports the result of calling this method in the didApiCallExecute callback.

Note: You can call this method either before or after joining a channel. If you call both setRemoteVideoStream and setRemoteDefaultVideoStreamType, the SDK applies the settings in the setRemoteVideoStream method.

Declared In

AgoraRtcChannel.h

– setRemoteDefaultVideoStreamType:

Sets the default video-stream type for the video received by the local user when the remote user sends dual streams.

- (int)setRemoteDefaultVideoStreamType:(AgoraVideoStreamType)streamType

Parameters

streamType

Sets the default video-stream type. See AgoraVideoStreamType.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

Note: You can call this method either before or after joining a channel. If you call both setRemoteDefaultVideoStreamType and setRemoteVideoStream, the SDK applies the settings in the setRemoteDefaultVideoStreamType method.

Declared In

AgoraRtcChannel.h

– addInjectStreamUrl:config:

Adds a voice or video stream CDN streaming URL to the interactive live streaming.

- (int)addInjectStreamUrl:(NSString *_Nonnull)url config:(AgoraLiveInjectStreamConfig *_Nonnull)config

Parameters

url

URL address to be added to the ongoing interactive live streaming. Valid protocols are RTMP, HLS, and HTTP-FLV.

  • Supported audio codec type: AAC.
  • Supported video codec type: H264 (AVC).
config

AgoraLiveInjectStreamConfig object which contains the configuration information for the added voice or video stream.

Return Value

  • 0: Success.

  • < 0: Failure.

    • AgoraErrorCodeInvalidArgument(-2): The injected URL does not exist. Call this method again to inject the stream and ensure that the URL is valid.
    • AgoraErrorCodeNotReady(-3): The user is not in the channel.
    • AgoraErrorCodeNotSupported(-4): The channel profile is not Live Broadcast.
    • AgoraErrorCodeNotInitialized(-7): The SDK is not initialized. Ensure that the AgoraRtcChannel object is initialized before using this method.

Discussion

If this method call is successful, the server pulls the voice or video stream and injects it into a live channel. This is applicable to scenarios where all audience members in the channel can watch a live show and interact with each other.

The addInjectStreamUrl method call triggers the following callbacks:

  • The local client:

    • streamInjectedStatusOfUrl, with the state of the injecting the online stream.
    • didJoinedOfUid(uid: 666), if the method call is successful and the online media stream is injected into the channel.

  • The remote client:

    • didJoinedOfUid(uid: 666), if the method call is successful and the online media stream is injected into the channel.

Warning: Agora will soon stop the service for injecting online media streams on the client. If you have not implemented this service, Agora recommends that you do not use it.

Note:

  • Ensure that you call this method after joining a channel.
  • You can inject only one media stream into the channel at the same time.
  • Ensure that you enable the RTMP Converter service before using this function. See Prerequisites.
  • This method applies to the Native SDK v2.4.1 and later.

Declared In

AgoraRtcChannel.h

– removeInjectStreamUrl:

Removes the voice or video stream CDN streaming URL from the interactive live streaming.

- (int)removeInjectStreamUrl:(NSString *_Nonnull)url

Parameters

url

URL address of the added stream to be removed.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

This method removes the URL address (added by the addInjectStreamUrl method) from the interactive live streaming.

If this method call is successful, the SDK triggers the didOfflineOfUid callback and returns a stream uid of 666.

Warning: Agora will soon stop the service for injecting online media streams on the client. If you have not implemented this service, Agora recommends that you do not use it.

Declared In

AgoraRtcChannel.h

– addPublishStreamUrl:transcodingEnabled:

Publishes the local stream to the CDN.

- (int)addPublishStreamUrl:(NSString *_Nonnull)url transcodingEnabled:(BOOL)transcodingEnabled

Parameters

url

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

Sets whether transcoding is enabled/disabled:

  • YES: Enable transcoding. To transcode the audio or video streams when publishing them to CDN live, often used for combining the audio and video streams of multiple hosts in CDN live. If you set this parameter as YES, ensure that you call the setLiveTranscoding method before this method.
  • NO: Disable transcoding.

Return Value

  • 0: Success.

  • < 0: Failure.

    • AgoraErrorCodeInvalidArgument(-2): Invalid parameter. The URL is nil or the string length is 0.
    • AgoraErrorCodeNotInitialized(-7): You have not initialized the RTC Engine when publishing the stream.

Discussion

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

Note:

  • This method applies to the interactive live streaming profile only.
  • Ensure that the user joins the channel before calling this method.
  • Ensure that you enable the RTMP Converter service before using this function. See Prerequisites.
  • This method adds only one stream URL each time it is called.
  • Agora supports pushing media streams in RTMPS protocol to the CDN only when you enable transcoding.

Declared In

AgoraRtcChannel.h

– removePublishStreamUrl:

Removes an RTMP or RTMPS stream from the CDN.

- (int)removePublishStreamUrl:(NSString *_Nonnull)url

Parameters

url

The CDN streaming URL to be removed. The maximum length of this parameter is 1024 bytes.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

This method removes the CDN streaming URL added by the addPublishStreamUrl method from a CDN live stream.

This method call triggers the rtmpStreamingChangedToState callback on the local client to report the state of removing an RTMP or RTMPS stream from the CDN.

Note:

  • This method applies to the interactive live streaming profile only.
  • This method removes only one URL each time it is called.
  • The URL must not contain special characters, such as Chinese language characters.

Declared In

AgoraRtcChannel.h

– setLiveTranscoding:

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

- (int)setLiveTranscoding:(AgoraLiveTranscoding *_Nullable)transcoding

Parameters

transcoding

Sets the CDN live audio/video transcoding settings. See AgoraLiveTranscoding.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

The SDK triggers the rtcEngineTranscodingUpdated callback when you call the setLiveTranscoding method to update the transcoding setting.

Note

  • Ensure that you call this method after joining a channel.
  • This method applies to the interactive live streaming profile only.
  • Ensure that you enable the RTMP Converter service before using this function. See Prerequisites.
  • If you call the setLiveTranscoding method to update the transcoding setting for the first time, the SDK does not trigger the rtcEngineTranscodingUpdated callback.
  • Agora supports pushing media streams in RTMPS protocol to the CDN only when you enable transcoding.

Declared In

AgoraRtcChannel.h

– createDataStream:reliable:ordered:

Creates a data stream.

- (int)createDataStream:(NSInteger *_Nonnull)streamId reliable:(BOOL)reliable ordered:(BOOL)ordered

Parameters

streamId

(Output parameter) The 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.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

Deprecated This method is deprecated from v3.3.0. Use the createDataStream2 method instead.

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

Note:

  • Ensure that you call this method after joining a channel.
  • Do not set reliable as YES while setting ordered as NO.

Declared In

AgoraRtcChannel.h

– createDataStream:config:

Creates a data stream.

- (int)createDataStream:(NSInteger *_Nonnull)streamId config:(AgoraDataStreamConfig *_Nonnull)config

Parameters

streamId

ID of the created data stream.
config

The configurations for the data stream: AgoraDataStreamConfig.

Return Value

  • Returns the stream ID if you successfully create the data stream.
  • < 0: Fails to create the data stream.

Availability

v3.3.0

Each user can create up to five data streams in a single channel.

This method does not support data reliability. If the receiver receives a data packet five seconds or more after it was sent, the SDK directly discards the data.

Declared In

AgoraRtcChannel.h

– sendStreamMessage:data:

Sends data stream messages to all users in a channel.

- (int)sendStreamMessage:(NSInteger)streamId data:(NSData *_Nonnull)data

Parameters

streamId

ID of the sent data stream returned in the createDataStream method.
data

Sent data.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

The SDK has the following restrictions on this method:

  • Up to 30 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 6 kB of data per second.
  • Each user can have up to five data streams simultaneously.

A successful sendStreamMessage method call triggers the receiveStreamMessageFromUid callback on the remote client, from which the remote user gets the stream message.

A failed sendStreamMessage method call triggers the didOccurStreamMessageErrorFromUid callback on the remote client.

Note

  • This method applies only to the Communication profile or to the hosts in the interactive live streaming profile. If an audience in the interactive live streaming profile calls this method, the audience role may be changed to a host.
  • Ensure that you have created the data stream using createDataStream before calling this method.

Declared In

AgoraRtcChannel.h

– startChannelMediaRelay:

Starts to relay media streams across channels.

- (int)startChannelMediaRelay:(AgoraChannelMediaRelayConfiguration *_Nonnull)config

Parameters

config

The configuration of the media stream relay: AgoraChannelMediaRelayConfiguration.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

After a successful method call, the SDK triggers the channelMediaRelayStateDidChange and didReceiveChannelMediaRelayEvent callbacks, and these callbacks return the state and events of the media stream relay.

  • If the channelMediaRelayStateDidChange callback returns AgoraChannelMediaRelayStateRunning(2) and AgoraChannelMediaRelayStateIdle(0), and the didReceiveChannelMediaRelayEvent callback returns AgoraChannelMediaRelayEventSentToDestinationChannel(4), the SDK starts relaying media streams between the original and the destination channel.
  • If the channelMediaRelayStateDidChange callback returns AgoraChannelMediaRelayStateFailure(3), an exception occurs during the media stream relay.

Note

  • Call this method after the joinChannelByToken method.
  • This method takes effect only when you are a host in the interactive live streaming channel.
  • After a successful method call, if you want to call this method again, ensure that you call the stopChannelMediaRelay method to quit the current relay.
  • Contact support@agora.io before implementing this function.
  • We do not support string user accounts in this API.

Declared In

AgoraRtcChannel.h

– updateChannelMediaRelay:

Updates the channels for media stream relay.

- (int)updateChannelMediaRelay:(AgoraChannelMediaRelayConfiguration *_Nonnull)config

Parameters

config

The media stream relay configuration: AgoraChannelMediaRelayConfiguration.

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

After the channel media relay starts, if you want to relay the media stream to more channels, or leave the current relay channel, you can call the updateChannelMediaRelay method.

After a successful method call, the SDK triggers the didReceiveChannelMediaRelayEvent callback with the AgoraChannelMediaRelayEventUpdateDestinationChannel(7) state code.

Note

  • Call this method after the startChannelMediaRelay method to update the destination channel.
  • This method supports adding at most four destination channels in the relay. If there are already four destination channels in the relay, remove the unnecessary ones with the removeDestinationInfoForChannelName method in channelMediaRelayConfiguration before calling this method.

Declared In

AgoraRtcChannel.h

– stopChannelMediaRelay

Stops the media stream relay.

- (int)stopChannelMediaRelay

Return Value

  • 0: Success.
  • < 0: Failure.

Discussion

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

After a successful method call, the SDK triggers the channelMediaRelayStateDidChange callback. If the callback returns AgoraChannelMediaRelayStateIdle(0) and AgoraChannelMediaRelayErrorNone(0), the host successfully stops the relay.

Note: If the method call fails, the SDK triggers the channelMediaRelayStateDidChange callback with the AgoraChannelMediaRelayErrorServerNoResponse(2) or AgoraChannelMediaRelayEventUpdateDestinationChannelRefused(8) state code. You can leave the channel by calling the leaveChannel method, and the media stream relay automatically stops.

Declared In

AgoraRtcChannel.h

– setRemoteVideoRenderer:forUserId:

Customizes the remote video renderer for the AgoraRtcChannel object.

- (void)setRemoteVideoRenderer:(id<AgoraVideoSinkProtocol> _Nullable)videoRenderer forUserId:(NSUInteger)userId

Parameters

videoRenderer

The customized remote video renderer: AgoraVideoSinkProtocol.
userId

The ID of the remote user.

Discussion

During real-time engagements, the Agora SDK enables the default video sink to render the video. In the multi-channel scenario, if you want to customize the video renderer, you can create a customized video sink using AgoraVideoSinkProtocol, and call setRemoteVideoRenderer to add the customized sink into the AgoraRtcChannel object.

You can call this method either before or after joining a channel. If you call it before joining a channel, you need to maintain the uid of the remote user on your app level.

Declared In

AgoraRtcChannel.h

– remoteVideoRendererOfUserId:

Gets the customized remote video renderer for the AgoraRtcChannel object.

- (id<AgoraVideoSinkProtocol> _Nullable)remoteVideoRendererOfUserId:(NSUInteger)userId

Parameters

userId

The ID of the remote user.

Return Value

The customized remote video renderer: AgoraVideoSourceProtocol.

Declared In

AgoraRtcChannel.h

– setMediaMetadataDataSource:withType:

Sets the data source of the metadata.

- (BOOL)setMediaMetadataDataSource:(id<AgoraMediaMetadataDataSource> _Nullable)metadataDataSource withType:(AgoraMetadataType)type

Parameters

metadataDataSource

The AgoraMediaMetadataDataSource protocol.
type

The metadata type. See AgoraMetadataType. Currently, the SDK supports video metadata only.

Return Value

  • YES: Success.
  • NO: Failure.

Discussion

You need to implement the AgoraMediaMetadataDataSource protocol and specify the type of metadata in this method.

Use this method with the setMediaMetadataDelegate method to add synchronized metadata in the video stream. You can create more diversified interactive live streaming interactions, such as sending shopping links, digital coupons, and online quizzes.

Note

  • Call this method before the joinChannelByToken method.
  • This method applies to the interactive live streaming channel profile only.

Declared In

AgoraRtcChannel.h

– setMediaMetadataDelegate:withType:

Sets the delegate of the metadata.

- (BOOL)setMediaMetadataDelegate:(id<AgoraMediaMetadataDelegate> _Nullable)metadataDelegate withType:(AgoraMetadataType)type

Parameters

metadataDelegate

The AgoraMediaMetadataDelegate protocol.
type

The metadata type. See AgoraMetadataType. Currently, the SDK supports video metadata only.

Return Value

  • YES: Success.
  • NO: Failure.

Discussion

You need to implement the AgoraMediaMetadataDelegate protocol and specify the type of metadata in this method.

Note

  • Call this method before the joinChannelByToken method.
  • This method applies to the interactive live streaming channel profile only.

Declared In

AgoraRtcChannel.h