Agora Unity SDK API Reference

The AgoraChannel class.

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

The OnStreamPublishedHandler callback returns the inject status. 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:
  • ChannelOnStreamInjectedStatusHandler , with the state of the injecting the online stream.
  • ChannelOnUserJoinedHandler (uid: 666), if the method call is successful and the online media stream is injected into the channel.
• The remote client:
  • ChannelOnUserJoinedHandler (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 enable the RTMP Converter service before using this function.
• This method applies to the Live-Broadcast profile only.
• You can inject only one media stream into the channel at the same time.

Parameters

url	The URL address which is added to the ongoing interactive live streaming. Valid protocols are RTMP, HLS, and FLV. Supported FLV audio codec type: AAC. Supported FLV video codec type: H264 (AVC).
config	The InjectStreamConfig object that contains the configuration of the added voice or video stream.

Returns

• 0: Success.
• < 0: Failure. -ERR_INVALID_ARGUMENT(-2): The injected URL does not exist. Call this method again to inject the stream and ensure that the URL is valid. -ERR_NOT_READY(-3): The user is not in the channel. -ERR_NOT_SUPPORTED(-4): The channel profile is not interactive live streaming. Call the SetChannelProfile method and set the channel profile to interactive live streaming before calling this method. -ERR_NOT_INITIALIZED(-7): The SDK is not initialized. Ensure that the IRtcEngine object is initialized before calling this method.

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

Deprecated:

This method is deprecated as of v3.6.1.1. See Release Notes for an alternative solution.

The SDK returns the result of this method call in the OnStreamPublishedHandler callback.

The AddPublishStreamUrl method call triggers the ChannelOnRtmpStreamingStateChangedHandler callback on the local client to report the state of adding a local stream to the CDN.

Note

• Ensure that the user joins the channel before calling this method.
• Ensure that you enable the RTMP Converter service before using this function.
• This method adds only one stream CDN streaming URL each time it is called.
• This method applies to Live Broadcast only.

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 or disabled: true: 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 true, ensure that you call the SetLiveTranscoding method before this method. false: Disable transcoding.

Returns

• 0: Success.
• < 0: Failure.
  • ERR_INVALID_ARGUMENT(-2): The CDN streaming URL is null or has a string length of 0.
  • ERR_NOT_INITIALIZED(-7): You have not initialized the RTC engine when publishing the stream.

Adjusts the playback signal volume of a specified remote user.

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

Note

• Call this method after joining a channel.
• The playback signal volume here refers to the mixed volume of a specified remote user.
• This method can only adjust the playback signal volume of one specified remote user at a time. To adjust the playback signal volume of different remote users, call the method as many times, once for each remote user.

Parameters

userId	The ID of the remote user.
volume	The playback signal volume of the specified remote user. The value ranges from 0 to 100: 0: Mute. 100: Original volume.

Returns

• 0: Success.
• < 0: Failure.

Gets the channel ID of the current AgoraChannel object.

Returns

• The channel ID of the current AgoraChannel object, if the method call succeeds.
• The empty string "", if the method call fails.

Creates and gets an AgoraChannel object.

To join more than one channel, call this method multiple times to create as many AgoraChannel objects as needed, and call the JoinChannel method of each created AgoraChannel object.

After joining multiple channels, you can simultaneously subscribe to streams of all the channels, but publish a stream in only one channel at one time.

Parameters

rtcEngine

IRtcEngine.

channelId

The unique channel name for an Agora RTC session. It must be in the string format and not exceed 64 bytes in length. 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: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".

Note

• This parameter does not have a default value. You must set it.
• Do not set it as the empty string "". Otherwise, the SDK returns ERR_REFUSED(5).

Returns

• The AgoraChannel object, if the method call succeeds.
• An empty pointer NULL, if the method call fails.
• ERR_REFUSED(5), if you set channelId as the empty string "".

Creates a data stream.

Deprecated:

This method is deprecated from v3.3.1. Use the CreateDataStream2 method instead.

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

Note

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

Parameters

reliable

Sets whether or not the recipients are guaranteed to receive the data stream from the sender within five seconds: true: 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 application. false: 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: true: The recipients receive the data stream in the sent order. false: The recipients do not receive the data stream in the sent order.

Returns

• ≥ 0: The ID of the data stream, if this method call succeeds.
• < 0: Failure.

Creates a data stream.

Since

v3.3.1

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.

Parameters

config

The configurations for the data stream: DataStreamConfig.

Returns

• ≥ 0: The ID of the data stream, if this method call succeeds.
• < 0: Fails to create the data stream.

Enables/Disables the built-in encryption.

Since

v3.2.1

In scenarios requiring high security, Agora recommends calling this method 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.

Note

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

Parameters

enabled	Whether to enable the built-in encryption: true: Enable the built-in encryption. false: Disable the built-in encryption.
encryptionConfig	Configurations of built-in encryption schemas. See EncryptionConfig.

Returns

• 0: Success.
• < 0: Failure.
  • -2(ERR_INVALID_ARGUMENT): An invalid parameter is used. Set the parameter with a valid value.
  • -4(ERR_NOT_SUPPORTED): The encryption mode is incorrect or the SDK fails to load the external encryption library. Check the enumeration or reload the external encryption library.
  • -7(ERR_NOT_INITIALIZED): The SDK is not initialized. Initialize the AgoraChannel instance before calling this method.

Enables/Disables the super-resolution algorithm for a remote user's video stream.

Since

v3.6.1.1

This feature effectively boosts the resolution of a remote user's video seen by the local user. If the original resolution of a remote user's video is a × b, the local user's device can render the remote video at a resolution of 2a × 2b after you enable this feature.

After calling this method, the SDK triggers the ChannelOnUserSuperResolutionEnabledHandler callback to report whether you have successfully enabled super resolution.

Warning

The super resolution feature requires extra system resources. To balance the visual experience and system consumption, the SDK poses the following restrictions:

• This feature can only be enabled for a single remote user.
• The original resolution of the remote user's video cannot exceed 640 × 360 pixels. If you exceed these limitations, the SDK triggers the ChannelOnWarningHandler callback with the corresponding warning codes:
• WARN_SUPER_RESOLUTION_STREAM_OVER_LIMITATION (1610): The original resolution of the remote user's video is beyond the range where super resolution can be applied.
• WARN_SUPER_RESOLUTION_USER_COUNT_OVER_LIMITATION (1611): Super resolution is already being used to boost another remote user's video.
• WARN_SUPER_RESOLUTION_DEVICE_NOT_SUPPORTED (1612): The device does not support using super resolution.

Note

• This method is for Android and iOS only.
• Before calling this method, ensure that you have integrated the following dynamic library into your project:
  • Android: libagora_super_resolution_extension.so
  • iOS: AgoraSuperResolutionExtension.xcframework
• As this method has certain system performance requirements, Agora recommends that you use the following devices or better:
  • VIVO: V1821A, NEX S, 1914A, 1916A, 1962A, 1824BA, X60, X60 Pro
  • OPPO: PCCM00, Find X3
  • OnePlus: A6000
  • Xiaomi: Mi 8, Mi 9, Mi 10, Mi 11, MIX3, Redmi K20 Pro
  • SAMSUNG: SM-G9600, SM-G9650, SM-N9600, SM-G9708, SM-G960U, SM-G9750, S20, S21
  • HUAWEI: SEA-AL00, ELE-AL00, VOG-AL00, YAL-AL10, HMA-AL00, EVR-AN00, nova 4, nova 5 Pro, nova 6 5G, nova 7 5G, Mate 30, Mate 30 Pro, Mate 40, Mate 40 Pro, P40 P40 Pro, HUAWEI MediaPad M6, MatePad 10.8
  • iOS (iOS 12.0 or later):
    • iPhone XR
    • iPhone XS
    • iPhone XS Max
    • iPhone 11
    • iPhone 11 Pro
    • iPhone 11 Pro Max
    • iPhone 12
    • iPhone 12 mini
    • iPhone 12 Pro
    • iPhone 12 Pro Max
    • iPhone 12 SE (2nd generation)
    • iPad Pro 11-inch (3rd generation)
    • iPad Pro 12.9-inch (3rd generation)
    • iPad Air (3rd generation)
    • iPad Air (4th generation)

Parameters

userId	The ID of the remote user.
enable	Determines whether to enable super resolution for the remote user's video: true: Enable super resolution. false: Do not enable super resolution.

Returns

• 0: Success.
• < 0: Failure.
  • -157 (ERR_MODULE_NOT_FOUND): The dynamic library for super resolution is not integrated.

Retrieves the current call ID.

When a user joins a channel on a client, a call ID is generated to identify the call from the client. Feedback methods, such as Rate and Complain, must be called after the call ends to submit feedback to the SDK.

The Rate and Complain methods require the call ID retrieved from the GetCallId method during a call. The call ID is passed as an argument into the Rate and Complain methods after the call ends.

Returns

• ≥ 0: The current call ID, if this method call succeeds.
• < 0: Failure.

Retrieves the connection state of the SDK.

Note

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

Returns

CONNECTION_STATE_TYPE.

Joins a channel with the user ID, and configures whether to publish or automatically subscribe to the audio or video streams.

Users in the same channel can talk to each other, and multiple users in the same channel can start a group chat. Users with different App IDs cannot call each other.

You must call the LeaveChannel method to exit the current call before entering another channel.

A successful JoinChannel method call triggers the following callbacks:

• The local client: OnJoinChannelSuccessHandler.
• The remote client: OnUserJoinedHandler, if the user joining the channel is in the COMMUNICATION profile, or is a host in the LIVE_BROADCASTING profile.

When the connection between the client and the Agora server is interrupted due to poor network conditions, the SDK tries reconnecting to the server. When the local client successfully rejoins the channel, the SDK triggers the OnReJoinChannelSuccessHandler callback on the local client.

Note

• Compared with the JoinChannel method in the IRtcEngine class, this method has the options parameter, which configures whether the user publishes or automatically subscribes to the audio and video streams in the channel when joining the channel. By default, the user publishes the local audio and video streams and automatically subscribes to the audio and video streams of all the other users in the channel. Subscribing incurs all associated usage costs. To unsubscribe, set the options parameter or call the Mute methods accordingly.
• Ensure that the App ID used for generating the token is the same App ID used in the GetEngine method for creating an IRtcEngine object.

Parameters

token	The token generated at your server. See Authenticate Your Users with Tokens.
info	(Optional) Reserved for future use.
uid	The user ID. A 32-bit unsigned integer with a value ranging from 1 to 232-1. The uid must be unique. If a uid is not assigned (or set to 0), the SDK assigns and returns a uid in the OnJoinChannelSuccessHandler callback. Your application must record and maintain the returned uid, because the SDK does not do so. Note: The ID of each user in the channel should be unique. If you want to join the same channel from different devices, ensure that the user IDs in all devices are different.
channelMediaOptions	The channel media options: ChannelMediaOptions.

Returns

• 0(ERR_OK): Success.
• < 0: Failure.
  • -2(ERR_INALID_ARGUMENT): The parameter is invalid.
  • -3(ERR_NOT_READY): The SDK fails to be initialized. You can try re-initializing the SDK.
  • -5(ERR_REFUSED): The request is rejected. This may be caused by the following:
    • You have created an AgoraChannel object with the same channel name.
    • You have joined and published a stream in a channel created by the AgoraChannel object. When you join a channel created by the IRtcEngine object, the SDK publishes the local audio and video streams to that channel by default. Because the SDK does not support publishing a local stream to more than one channel simultaneously, an error occurs in this occasion.
  • -7(ERR_NOT_INITIALIZED): The SDK is not initialized before calling this method.
  • -17(ERR_JOIN_CHANNEL_REJECTED): The request to join the channel is rejected. The SDK supports joining only one channel at a time. Therefore, the SDK returns this error code when a user who has already joined a channel.

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

A successful method call triggers the following callbacks:

• The local client: OnLocalUserRegisteredHandler and OnJoinChannelSuccessHandler.
• The remote client: OnUserJoinedHandler and OnUserInfoUpdatedHandler, if the user joining the channel is in the COMMUNICATION profile, or is a host in the LIVE_BROADCASTING profile.

Note

• Compared with JoinChannelWithUserAccount, this method has the options parameter, which configures whether the user publishes or automatically subscribes to the audio and video streams in the channel when joining the channel. By default, the user publishes the local audio and video streams and automatically subscribes to the audio and video streams of all the other users in the channel. Subscribing incurs all associated usage costs. To unsubscribe, set the options parameter or call the mute methods accordingly.
• 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.
• Before using a String user name, ensure that you read How can I use string user names for details about the limitations and implementation steps.

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 your server. For details, see Generate a token.
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: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
channelMediaOptions	The channel media options: ChannelMediaOptions.

Returns

• 0: Success.
• < 0: Failure.
  • ERR_INVALID_ARGUMENT(-2)
  • ERR_NOT_READY(-3)
  • ERR_REFUSED(-5)

Allows a user to leave a channel, such as hanging up or exiting a call.

After joining a channel, the user must call the LeaveChannel method to end the call before joining another channel.

This method returns 0 if the user leaves the channel and releases all resources related to the call.

This method call is asynchronous, and the user has not left the channel when the method call returns. Once the user leaves the channel, the SDK triggers the ChannelOnLeaveChannelHandler callback.

A successful LeaveChannel method call triggers the following callbacks:

• The local client: ChannelOnLeaveChannelHandler
• The remote client: ChannelOnUserOffLineHandler, if the user leaving the channel is in the Communication channel, or is a host in the Live Broadcast profile.

Note

• If you call the ReleaseChannel method immediately after the LeaveChannel method, the LeaveChannel process interrupts, and the ChannelOnLeaveChannelHandler callback is not triggered.
• If you call the LeaveChannel method during a CDN live streaming, the SDK triggers the RemovePublishStreamUrl method.

Returns

• 0(ERR_OK): Success.
• < 0: Failure.
  • -1(ERR_FAILED): A general error occurs (no specified reason).
  • -2(ERR_INALID_ARGUMENT): The parameter is invalid.
  • -7(ERR_NOT_INITIALIZED): The SDK is not initialized.

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

As of v3.3.1, 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.

Parameters

mute	Sets whether to stop subscribing to the audio streams of all remote users. true: Stop subscribing to the audio streams of all remote users. false: (Default) Resume subscribing to the audio streams of all remote users.

Returns

• 0: Success.
• < 0: Failure.

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

As of v3.3.1, 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.

Parameters

mute	Sets whether to stop subscribing to the video streams of all remote users. true: Stop subscribing to the video streams of all remote users. false: (Default) Resume subscribing to the video streams of all remote users.

Returns

• 0: Success.
• < 0: Failure.

Stops or resumes publishing the local audio stream.

This method only sets the publishing state of the audio stream in the channel of AgoraChannel. A successful method call triggers the OnRemoteAudioStateChangedHandler callback on the remote client.

You can only publish the local stream in one channel at a time. If you create multiple channels, ensure that you only call MuteLocalAudioStream(false) in one channel; otherwise, the method call fails, and the SDK returns -5(ERR_REFUSED).

Note

• This method does not change the usage state of the audio-capturing device.
• Whether this method call takes effect is affected by the JoinChannel and SetClientRole methods.

Parameters

mute	Whether to stop publishing the local audio stream. true: Stop publishing the local video stream. false: Resume publishing the local video stream.

Returns

• 0: Success.
• < 0: Failure.

Stops or resumes publishing the local video stream.

This method only sets the publishing state of the video stream in the channel of AgoraChannel. A successful method call triggers the OnRemoteVideoStateChangedHandler callback on the remote client.

You can only publish the local stream in one channel at a time. If you create multiple channels, ensure that you only call MuteLocalVideoStream(false) in one channel; otherwise, the method call fails, and the SDK returns -5(ERR_REFUSED).

Note

• This method does not change the usage state of the video-capturing device.
• Whether this method call takes effect is affected by the JoinChannel and SetClientRole methods.

Parameters

mute	Whether to stop publishing the local video stream. true: Stop publishing the local video stream. false: Resume publishing the local video stream.

Returns

• 0: Success.
• < 0: Failure.

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

Note

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

Parameters

userId	The user ID of the specified remote user.
mute	Sets whether to stop subscribing to the audio stream of a specified user. true: Stop subscribing to the audio stream of a specified user. false: (Default) Resume subscribing to the audio stream of a specified user.

Returns

• 0: Success.
• < 0: Failure.

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

Note

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

Parameters

userId	The user ID of the specified remote user.
mute	Sets whether to stop subscribing to the video stream of a specified user. true: Stop subscribing to the video stream of a specified user. false: (Default) Resume subscribing to the video stream of a specified user.

Returns

• 0: Success.
• < 0: Failure.

Publishes the local stream to the channel.

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

• This method publishes one stream only to the channel corresponding to the current AgoraChannel object.
• In a Live Broadcast channel, only a host can call this method. To switch the client role, call SetClientRole of the current AgoraChannel object.
• You can publish a stream to only one channel at a time.

Returns

• 0: Success.
• < 0: Failure.
  • ERR_REFUSED(-5): The method call is refused.

Releases all AgoraChannel resources.

Returns

• 0: Success.
• < 0: Failure.
  • ERR_NOT_INITIALIZED(7): The SDK is not initialized before calling this method.

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

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

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

If this method is called successfully, the SDK triggers the ChannelOnUserOffLineHandler callback and returns a stream uid of 666.

Parameters

url	The URL address of the added stream to be removed.

Returns

• 0: Success.
• < 0: Failure.

Removes an RTMP or RTMPS stream from the CDN. (CDN live only.)

Deprecated:

This method is deprecated as of v3.6.1.1. See Release Notes for an alternative solution.

This method removes the CDN streaming URL (added by the AddPublishStreamUrl method) from a CDN live stream. The SDK returns the result of this method call in the OnStreamUnpublishedHandler callback.

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

Note

• This method removes only one CDN streaming URL each time it is called.
• The CDN streaming URL must not contain special characters, such as Chinese language characters.
• This method applies to Live Broadcast only.

Parameters

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

Returns

• 0: Success.
• < 0: Failure.

Gets a new token when the current token expires after a period of time.

The token expires after a period of time once the token schema is enabled when:

• The SDK triggers the ChannelOnTokenPrivilegeWillExpireHandler callback, or
• The ChannelOnConnectionStateChangedHandler reports CONNECTION_CHANGED_TOKEN_EXPIRED(9).

The application should call this method to get the new token. Failure to do so will result in the SDK disconnecting from the server.

Parameters

token

Pointer to the new token.

Returns

• 0(ERR_OK): Success.
• < 0: Failure.
  • -1(ERR_FAILED): A general error occurs (no specified reason).
  • -2(ERR_INALID_ARGUMENT): The parameter is invalid.
  • -7(ERR_NOT_INITIALIZED): The SDK is not initialized.

Sends data stream messages to all users in a channel.

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 ChannelOnStreamMessageHandler callback on the remote client, from which the remote user gets the stream message.

A failed SendStreamMessage method call triggers the ChannelOnStreamMessageHandler callback on the remote client.

Note

• This method applies only to the Communication profile or to the hosts in the Live-broadcast profile. If an audience in the Live-broadcast profile calls this method, the audience may be switched to a host.
• Ensure that you have created the data stream using CreateDataStream before calling this method.

Parameters

streamId	The ID of the sent data stream, returned in the CreateDataStream method.
data	The sent data.
length	The data length.

Returns

• 0: Success.
• < 0: Failure.

Sets the role of the user, such as a host or an audience (default), before joining a channel in an interactive live streaming.

This method can be used to switch the user role in the interactive live streaming after the user joins a channel.

In the Live Broadcast profile, when a user switches user roles after joining a channel, a successful SetClientRole method call triggers the following callbacks:

• The local client: ChannelOnClientRoleChangedHandler
• The remote client: ChannelOnUserJoinedHandler or ChannelOnUserOffLineHandler (BECOME_AUDIENCE)

Note

This method applies only to the Live-broadcast profile.

Parameters

role	Sets the role of the user. See CLIENT_ROLE_TYPE.

Returns

• 0: Success.
• < 0: Failure.

Sets the role of a user in interactive live streaming.

Since

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:

• The local client: ChannelOnClientRoleChangedHandler.
• The remote client: ChannelOnUserJoinedHandler or ChannelOnUserOffLineHandler.

Note

• This method applies to the LIVE_BROADCASTING profile only.
• 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.

Parameters

role	The role of a user in interactive live streaming. See CLIENT_ROLE_TYPE.
audienceLatencyLevel	The detailed options of a user, including user level. See ClientRoleOptions.

Returns

• 0(ERR_OK): Success.
• < 0: Failure.
  • -1(ERR_FAILED): A general error occurs (no specified reason).
  • -2(ERR_INALID_ARGUMENT): The parameter is invalid.
  • -7(ERR_NOT_INITIALIZED): The SDK is not initialized.

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

Deprecated:

This method is deprecated from v3.3.1.

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 stream of multiple remote users, call MuteRemoteAudioStream(false) multiple times.

Parameters

mute	Sets whether to stop subscribing to the audio streams of all remote users by default. true: Stop subscribing to the audio streams of all remote users by default. false: (Default) Resume subscribing to the audio streams of all remote users by default.

Returns

• 0: Success.
• < 0: Failure.

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

Deprecated:

This method is deprecated from v3.3.1.

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 stream of multiple remote users, call MuteRemoteVideoStream(false) multiple times.

Parameters

mute	Sets whether to stop subscribing to the video streams of all remote users by default. true: Stop subscribing to the video streams of all remote users by default. false: (Default) Resume subscribing to the video streams of all remote users by default.

Returns

• 0: Success.
• < 0: Failure.

Sets the built-in encryption mode.

Deprecated:

Deprecated as of v3.2.0. Use the EnableEncryption instead.

The Agora Unity 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.

Parameters

encryptionMode

The set encryption mode: "aes-128-xts": (Default) 128-bit AES encryption, XTS mode. "aes-128-ecb": 128-bit AES encryption, ECB mode. "aes-256-xts": 256-bit AES encryption, XTS mode. "": When encryptionMode is set as null, the encryption mode is set as "aes-128-xts" by default.

Returns

• 0: Success.
• < 0: Failure.

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

Deprecated:

Deprecated as of v3.2.0. Use the EnableEncryption instead.

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

If an encryption password is not specified, the encryption functionality will be 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.

Parameters

secret

The encryption password.

Returns

• 0: Success.
• < 0: Failure.

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

Deprecated:

This method is deprecated as of v3.6.1.1. See Release Notes for an alternative solution.

The SDK triggers the ChannelOnTranscodingUpdatedHandler callback when you call the SetLiveTranscoding method to update the transcoding setting.

Note

• Ensure that you enable the RTMP Converter service before using this function.
• If you call the SetLiveTranscoding method to update the transcoding setting for the first time, the SDK does not trigger the ChannelOnTranscodingUpdatedHandler callback.
• Ensure that you call this method after joining a channel.
• Agora supports pushing media streams in RTMPS protocol to the CDN only when you enable transcoding.

Parameters

liveTranscoding

Sets the CDN live audio or video transcoding settings. See LiveTranscoding.

Returns

• 0: Success.
• < 0: Failure.

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

• If the dual-stream mode is enabled by calling the EnableDualStreamMode method, the user receives the high-stream video by default. The SetRemoteDefaultVideoStreamType method allows the application to adjust the corresponding video-stream type according to the size of the video window, reducing the bandwidth and resources.
• If the dual-stream mode is not enabled, the user receives the high-stream video by default.

The result after calling this method is returned in the OnApiExecutedHandler callback. The Agora RTC SDK receives the high-stream video by default to reduce the bandwidth. If needed, users can switch to the low-stream video through this method.

Note

You can call this method either before or after joining a channel. If you call both SetRemoteDefaultVideoStreamType and SetRemoteVideoStreamType, the SDK applies the settings in the SetRemoteVideoStreamType.

Parameters

streamType

Sets the default video stream type. See REMOTE_VIDEO_STREAM_TYPE.

Returns

• 0: Success.
• < 0: Failure.

Prioritizes a remote user's stream.

Use this method with the SetRemoteSubscribeFallbackOption method. If the fallback function is enabled for a subscribed stream, the SDK ensures the high-priority user gets the best possible stream quality.

Note

• The Agora RTC SDK supports setting userPriority as high for one user only.
• Ensure that you call this method before joining a channel.

Parameters

uid	The ID of the remote user.
userPriority	Sets the priority of the remote user. See PRIORITY_TYPE.

Returns

• 0: Success.
• < 0: Failure.

Sets the stream type of the remote video.

Under limited network conditions, if the publisher has not disabled the dual-stream mode using EnableDualStreamMode(false), the receiver can choose to receive either the high-quality video stream (the high resolution, and high bitrate video stream) or the low-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-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-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-video stream.

The method result returns in the OnApiExecutedHandler callback.

Note

You can call this method either before or after joining a channel. If you call both SetRemoteVideoStreamType and SetRemoteDefaultVideoStreamType, the SDK applies the settings in the SetRemoteVideoStreamType.

Parameters

userId	ID of the remote user sending the video stream.
streamType	Sets the video-stream type. See REMOTE_VIDEO_STREAM_TYPE.

Returns

• 0: Success.
• < 0: Failure.

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

• For this method to work, enable stereo panning for remote users by calling the EnableSoundPositionIndication method before joining a channel.
• This method requires hardware support. For the best sound positioning, we recommend using a wired headset.

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

Returns

• 0: Success.
• < 0: Failure.

Starts to relay media streams across channels.

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

• If the ChannelOnMediaRelayStateChangedHandler callback returns RELAY_STATE_RUNNING(2) and RELAY_OK(0), and the ChannelOnMediaRelayEventHandler callback returns RELAY_EVENT_PACKET_SENT_TO_DEST_CHANNEL(4), the host starts sending data to the destination channel.
• If the ChannelOnMediaRelayStateChangedHandler callback returns RELAY_STATE_FAILURE(3), an exception occurs during the media stream relay.

Note

• Call this method after the JoinChannel method.
• This method takes effect only when you are a host in a Live-broadcast 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.

Parameters

channelMediaRelayConfiguration

The configuration of the media stream relay: ChannelMediaRelayConfiguration.

Returns

• 0: Success.
• < 0: Failure.

Starts pushing media streams to a CDN without transcoding.

Since

v3.6.1.1

You can call this method to push a live audio-and-video stream to the specified CDN address. This method can push media streams to only one CDN address at a time, so if you need to push streams to multiple addresses, call this method multiple times.

After you call this method, the SDK triggers the OnRtmpStreamingStateChangedHandler callback on the local client to report the state of the streaming.

Note

• Ensure that you enable the RTMP Converter service before using this function. See Prerequisites in Push Streams to CDN.
• Call this method after joining a channel.
• Only hosts in the LIVE_BROADCASTING profile can call this method.
• If you want to retry pushing streams after a failed push, make sure to call StopRtmpStream first, then call this method to retry pushing streams; otherwise, the SDK returns the same error code as the last failed push.
• If you want to push media streams in the RTMPS protocol to CDN, call StartRtmpStreamWithTranscoding instead of StartRtmpStreamWithoutTranscoding.

Parameters

url	The address of the CDN live streaming. The format is RTMP. The character length cannot exceed 1024 bytes. Special characters such as Chinese characters are not supported.

Returns

• 0: Success.
• < 0: Failure.
  • ERR_INVALID_ARGUMENT (2): The RTMP URL address is NULL or the string length is 0.
  • ERR_NOT_INITIALIZED (7): The SDK is not initialized before calling this method.

Starts pushing media streams to a CDN and sets the transcoding configuration.

Since

v3.6.1.1

You can call this method to push a live audio-and-video stream to the specified CDN address and set the transcoding configuration. This method can push media streams to only one CDN address at a time, so if you need to push streams to multiple addresses, call this method multiple times.

After you call this method, the SDK triggers the OnRtmpStreamingStateChangedHandler callback on the local client to report the state of the streaming.

Note

• Ensure that you enable the RTMP Converter service before using this function. See Prerequisites in Push Streams to CDN.
• Call this method after joining a channel.
• Only hosts in the LIVE_BROADCASTING profile can call this method.
• If you want to retry pushing streams after a failed push, make sure to call StopRtmpStream first, then call this method to retry pushing streams; otherwise, the SDK returns the same error code as the last failed push.
• If you want to push media streams in the RTMPS protocol to CDN, call StartRtmpStreamWithTranscoding instead of StartRtmpStreamWithoutTranscoding.

Parameters

url	The address of the CDN live streaming. The format is RTMP or RTMPS. The character length cannot exceed 1024 bytes. Special characters such as Chinese characters are not supported.
liveTranscoding	The transcoding configuration for CDN live streaming. See LiveTranscoding.

Returns

• 0: Success.
• < 0: Failure.

Stops the media stream relay.

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

After a successful method call, the SDK triggers the ChannelOnMediaRelayStateChangedHandler callback. If the callback returns RELAY_STATE_IDLE(0) and RELAY_OK(0), the host successfully stops the relay.

Note

If the method call fails, the SDK triggers the ChannelOnMediaRelayStateChangedHandler callback with the RELAY_ERROR_SERVER_NO_RESPONSE(2) or RELAY_ERROR_SERVER_CONNECTION_LOST(8) state code. You can leave the channel by calling the LeaveChannel method, and the media stream relay automatically stops.

Returns

• 0: Success.
• < 0: Failure.

Stops pushing media streams to a CDN.

Since

v3.6.1.1

You can call this method to stop the live stream on the specified CDN address. This method can stop pushing media streams to only one CDN address at a time, so if you need to stop pushing streams to multiple addresses, call this method multiple times.

After you call this method, the SDK triggers the OnRtmpStreamingStateChangedHandler callback on the local client to report the state of the streaming.

Parameters

url	The address of the CDN live streaming. The format is RTMP or RTMPS. The character length cannot exceed 1024 bytes. Special characters such as Chinese characters are not supported.

Returns

• 0: Success.
• < 0: Failure.

Stops publishing a stream to the channel.

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

Returns

• 0: Success.
• < 0: Failure.
  • ERR_REFUSED(5): The method call is refused.

Updates the channels for media stream relay. After a successful StartChannelMediaRelay method call, 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 ChannelOnMediaRelayEventHandler callback with the RELAY_EVENT_PACKET_UPDATE_DEST_CHANNEL(7) state code.

Note

Call this method after the StartChannelMediaRelay method to update the destination channel.

Parameters

channelMediaRelayConfiguration

The media stream relay configuration: ChannelMediaRelayConfiguration.

Returns

• 0: Success.
• < 0: Failure.

Updates the transcoding configuration.

Since

v3.6.1.1

After you start pushing media streams to CDN with transcoding, you can dynamically update the transcoding configuration according to the scenario. The SDK triggers the OnTranscodingUpdatedHandler callback after the transcoding configuration is updated.

Parameters

liveTranscoding

The transcoding configuration for CDN live streaming. See LiveTranscoding.

Returns

• 0: Success.
• < 0: Failure.