Agora Java API Reference for Android

Sets the channel event handler.

After setting the channel event handler, you can listen for channel events and receive the statistics of the corresponding RtcChannel instance.

Parameters

eventHandler

The event handler of the RtcChannel instance: IRtcChannelEventHandler.

Gets the channel event handler.

Returns

• The IRtcChannelEventHandler instance, if the method call succeeds.
• Null, if the method call fails.

Destroys the RtcChannel instance.

Returns

• 0: Success.
• < 0: Fail.
  • ERR_NOT_INITIALIZED(-7): The RtcChannel instance is not initialized before calling this method.

Gets the channel ID of the current RtcChannel instance.

Returns

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

Gets the current call ID. Ensure that you call this method after joining a channel.

Returns

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

Gets the connection state of the SDK.

Returns

The connection state:

• CONNECTION_STATE_DISCONNECTED(1): The SDK is disconnected from Agora edge server.
• CONNECTION_STATE_CONNECTING(2): The SDK is connecting to Agora edge server.
• CONNECTION_STATE_CONNECTED(3): The SDK joined a channel and is connected to Agora edge server. You can now publish or subscribe to a media stream in the channel.
• CONNECTION_STATE_RECONNECTING(4): The SDK keeps rejoining the channel after being disconnected from a joined channel because of network issues.
• CONNECTION_STATE_FAILED(5): The SDK fails to join the channel.

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

Since

v3.5.1

Deprecated:

This method is deprecated as of v3.7.1. Use enableRemoteSuperResolution[2/2] instead.

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 onUserSuperResolutionEnabled callback to report whether you have successfully enabled super resolution.

Note

• Before calling this method, ensure that you have integrated the libagora_super_resolution_extension.so dynamic library into your project.
• Because 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

Parameters

uid	The user 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.

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

Since

v3.7.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 onUserSuperResolutionEnabled callback to report whether you have successfully enabled super resolution.

Note

Before calling this method, ensure that you have integrated the libagora_super_resolution_extension.so dynamic libraries into your project.

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.
  
• The feature cannot be enabled in certain specific devices.

Parameters

enable	Determines whether to enable super resolution for the remote user's video: true: Enable super resolution. false: Do not enable super resolution.
mode	The mode of super resolution: SR_MODE_MANUAL(0): Enables super resolution for the remote user you specify. SR_MODE_AUTO(1): Enables super resolution for the remote user corresponding to the largest rendering window in the channel.
uid	The user ID of the remote user. This parameter only applies when mode is set as SR_MODE_MANUAL(0).

Returns

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

Joins the channel with a user ID.

Compared with the joinChannel method in the RtcEngine class, this method supports joining multiple channels at a time by creating multiple RtcChannel objects and then calling joinChannel in each RtcChannel object.

Once the user joins the channel, 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 by default. Subscribing incurs all associated usage costs. To unsubscribe, set the options parameter or call the mute methods accordingly.

Note

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

Parameters

token	The token generated at your server. For details, see Authenticate Your Users with Tokens.
optionalInfo	Additional information about the channel. This parameter can be set as null. Other users in the channel do not receive this information.
optionalUid	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 onJoinChannelSuccess callback. The app must maintain this user ID.
options	The channel media options: ChannelMediaOptions.

Returns

• 0(ERR_OK): Success.
• < 0: Failure.
  • -2(ERR_INVALID_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. Possible reasons:
    • You have created an RtcChannel object with the same channel name.
    • You have joined and published a stream in a channel created by the RtcChannel object.
  • -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 does not support joining the same RtcChannel channel repeatedly. Therefore, the SDK returns this error code when a user who has already joined an RtcChannel channel calls the joining channel method of this RtcChannel object.

Joins a channel with the user account.

Compared with the joinChannelWithUserAccount[2/2] method in the RtcEngine class, this method supports joining multiple channels at a time by creating multiple RtcChannel objects and then calling joinChannelWithUserAccount in each RtcChannel object.

Once the user joins the channel, 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 by default. Subscribing incurs all associated usage costs. To unsubscribe, set the options parameter or call the mute methods accordingly.

Note

• If you are already in a channel, you cannot rejoin it with the same user account.
• If you want to join the same channel from different devices, ensure that the user accounts 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 RtcEngine instance.
• Before using a String user name, ensure that you read How can I use string user names for getting details about the limitations and implementation steps.

Parameters

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

Returns

• 0: Success.
• < 0: Failure.
  • ERR_INVALID_ARGUMENT(-2)
  • ERR_NOT_READY(-3)
  • ERR_REFUSED(-5)
  • ERR_JOIN_CHANNEL_REJECTED(-17): The request to join the channel is rejected. The SDK does not support joining the same RtcChannel channel repeatedly. Therefore, the SDK returns this error code when a user who has already joined an RtcChannel channel calls the joining channel method of this RtcChannel object.

Leaves the current channel.

A successful leaveChannel method call triggers the following callbacks:

• The local client: onLeaveChannel.
• The remote client: onUserOffline, if the user leaving the channel is in a Communication channel, or is a host in a LIVE_BROADCASTING channel.

Returns

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

Stops or resumes publishing the local audio stream.

Since

v3.4.5

This method only sets the publishing status of the audio stream in the channel of RtcChannel.

A successful method call triggers the onRemoteAudioStateChanged 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 status of the audio-capturing device.
• Whether this method call takes effect is affected by the joinChannel and setClientRole methods. For details, see Set the Publishing Status.

Parameters

muted

Sets whether to stop publishing the local audio stream. true: Stop publishing the local audio stream. false: Resume publishing the local audio stream.

Returns

• 0: Success.
• < 0: Failure.
  • -5 (ERR_REFUSED): The request is rejected.

Stops or resumes publishing the local video stream.

Since

v3.4.5

This method only sets the publishing status of the video stream in the channel of RtcChannel.

A successful method call triggers the onRemoteVideoStateChanged 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 status of the video-capturing device.
• Whether this method call takes effect is affected by the joinChannel and setClientRole methods. For details, see Set the Publishing Status.

Parameters

muted

Sets 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.
  • -5 (ERR_REFUSED): The request is rejected.

Publishes the local stream to the channel.

Deprecated:

This method is deprecated as of v3.4.5. Use muteLocalAudioStream(false) or muteLocalVideoStream(false) instead.

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 RtcChannel instance.
• You can publish a stream to only one channel at a time. For details, see the advanced guide Join Multiple Channels.
• This method is equal to muteLocalAudioStream(false) and muteLocalVideoStream(false).

Returns

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

Stops publishing a stream to the channel.

Deprecated:

This method is deprecated as of v3.4.5. Use muteLocalAudioStream(true) or muteLocalVideoStream(true) instead.

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

• This method is equal to muteLocalAudioStream(true) and muteLocalVideoStream(true).

Returns

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

Renews the token when the current token expires.

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

• The SDK triggers the onTokenPrivilegeWillExpire callback, or
• The onConnectionStateChanged callback reports the CONNECTION_CHANGED_TOKEN_EXPIRED(9) error.

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.

Parameters

token

The new token.

Returns

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

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

Deprecated:

Deprecated as of 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

• 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.
• Do not use this method for CDN streaming.

Parameters

secret

The encryption password.

Returns

• 0: Success.
• < 0: Failure.

Sets the built-in encryption mode.

Deprecated:

Deprecated as of v3.1.0. Use enableEncryption instead.

The Agora SDK supports built-in encryption, which is set to aes-128-xts mode by default. Call this method to set the encryption mode 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

• Do not use this method for CDN streaming.
• Before calling this method, ensure that you have called setEncryptionSecret to enable encryption.

Parameters

encryptionMode

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

Returns

• 0: Success.
• < 0: Failure.

Enables/Disables the built-in encryption.

Since

v3.1.0.

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

After a user leaves the channel, the SDK automatically disables the built-in encryption. To re-enable the built-in encryption, call this method before the user joins the channel again.

As of v3.4.5, Agora recommends using either the AES_128_GCM2 or AES_256_GCM2 encryption mode, both of which support adding a salt and are more secure. For details, see Media Stream Encryption.

Warning

All users in the same channel must use the same encryption mode, encryption key, and salt; otherwise, users cannot communicate with each other.

Note

• If you enable the built-in encryption, you cannot use the RTMP or RTMPS streaming function.
• To enhance security, Agora recommends using a new key and salt every time you enable the media stream encryption.

Parameters

enabled	Whether to enable the built-in encryption. true: Enable the built-in encryption. false: Disable the built-in encryption.
config	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.
  • -7(ERR_NOT_INITIALIZED: The SDK is not initialized. Initialize the IRtcEngine instance before calling this method.
  • -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.

Registers the metadata observer.

You need to implement the IMetadataObserver class and specify the metadata type in this method. A successful call of this method triggers the getMaxMetadataSize callback.

This method enables you to add synchronized metadata in the video stream for more diversified live broadcast interactions, such as sending shopping links, digital coupons, and online quizzes.

Note

Call this method before the joinChannel method.

Parameters

observer	The IMetadataObserver class.
type	The metadata type. Currently, the SDK supports VIDEO_METADATA(0) only. UNKNOWN_METADATA(-1): the metadata type is unknown. VIDEO_METADATA(0): the metadata type is video.

Returns

• 0: Success.
• < 0: Failure.

Sets the role of the user in interactive live streaming.

After calling setChannelProfile(CHANNEL_PROFILE_LIVE_BROADCASTING), the SDK sets the user role as audience by default. You can call setClientRole to set the user role as host.

You can call this method either before or after joining a channel. If you call this method to switch the user role after joining a channel, the SDK automatically does the following:

• Calls muteLocalAudioStream and muteLocalVideoStream to change the publishing state.
• Triggers onClientRoleChanged or onClientRoleChangeFailed on the local client.
• Triggers onUserJoined or onUserOffline(USER_OFFLINE_BECOME_AUDIENCE) on the remote client.

Note

This method applies to the LIVE_BROADCASTING profile only (when the profile parameter in setChannelProfile is set as CHANNEL_PROFILE_LIVE_BROADCASTING).

Parameters

role

The role of a user in interactive live streaming: CLIENT_ROLE_BROADCASTER(1): Host. A host can both send and receive streams. If you set this user role in the channel, the SDK automatically calls muteLocalAudioStream(false) and muteLocalVideoStream(false). CLIENT_ROLE_AUDIENCE(2): Audience. An audience member can only receive streams. If you set this user role in the channel, the SDK automatically calls muteLocalAudioStream(true) and muteLocalVideoStream(true).

Returns

• 0(ERR_OK): Success.
• < 0: Failure.
  • -1(ERR_FAILED): A general error occurs (no specified reason).
  • -2(ERR_INVALID_ARGUMENT): The parameter is invalid.
  • -5(ERR_REFUSED): The request is rejected. In multichannel scenarios, if you have set any of the following in one channel, the SDK returns this error code when the user switches the user role to host in another channel:
    • Call joinChannel with the options parameter and use the default settings publishLocalAudio = true or publishLocalVideo = true.
    • Call setClientRole to set the user role as host.
    • Call muteLocalAudioStream(false) or muteLocalVideoStream(false).
  • -7(ERR_NOT_INITIALIZED): The SDK is not initialized.

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

Since

v3.2.0

After calling setChannelProfile(CHANNEL_PROFILE_LIVE_BROADCASTING), the SDK sets the user role as audience by default. You can call setClientRole to set the user role as host.

You can call this method either before or after joining a channel. If you call this method to switch the user role after joining a channel, the SDK automatically does the following:

• Calls muteLocalAudioStream and muteLocalVideoStream to change the publishing state.
• Triggers onClientRoleChanged or onClientRoleChangeFailed on the local client.
• Triggers onUserJoined or onUserOffline(USER_OFFLINE_BECOME_AUDIENCE) on the remote client.

Note

• This method applies to the LIVE_BROADCASTING profile only (when the profile parameter in setChannelProfile is set as CHANNEL_PROFILE_LIVE_BROADCASTING).
• 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. User level affects the pricing of services.

Sample code

Parameters

role

The role of a user in a live interactive streaming: CLIENT_ROLE_BROADCASTER(1): Host. A host can both send and receive streams. If you set this user role in the channel, the SDK automatically calls muteLocalAudioStream(false) and muteLocalVideoStream(false). CLIENT_ROLE_AUDIENCE(2): Audience. An audience member can only receive streams. If you set this user role in the channel, the SDK automatically calls muteLocalAudioStream(true) and muteLocalVideoStream(true).

options

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_INVALID_ARGUMENT): The parameter is invalid.
  • -5(ERR_REFUSED): The request is rejected. In multichannel scenarios, if you have set any of the following in one channel, the SDK returns this error code when the user switches the user role to host in another channel:
    • Call joinChannel with the options parameter and use the default settings publishLocalAudio = true or publishLocalVideo = true.
    • Call setClientRole to set the user role as host.
    • Call muteLocalAudioStream(false) or muteLocalVideoStream(false).
  • -7(ERR_NOT_INITIALIZED): The SDK is not initialized.

Sets the priority of a remote user's media stream.

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

Ensure that you call this method before joining a channel.

Note

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

Parameters

uid	The ID of the remote user.
userPriority	The priority of the remote user: USER_PRIORITY_HIGH(50): The user's priority is high. USER_PRIORITY_NORMAL(100): (Default) The user's priority is normal.

Returns

• 0: Success.
• < 0: Failure.

Sets the sound position of a remote user.

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

Note

• Ensure that you call this method after joining a channel.
• For this method to work, enable stereo panning for remote users by calling the enableSoundPositionIndication method before joining a channel.
• This method requires hardware support. For the best sound positioning, we recommend using a stereo 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.
• -1: Failure.

Updates the remote video display mode.

This method can be called multiple times during a call to change the display mode.

Parameters

uid	ID of the remote user.
renderMode	The remote video render mode: RENDER_MODE_HIDDEN(1): Uniformly scale the video until it fills the visible boundaries (cropped). One dimension of the video may have clipped contents. RENDER_MODE_FIT(2): Uniformly scale the video until one of its dimension fits the boundary (zoomed to fit). Areas that are not filled due to the disparity in the aspect ratio are filled with black. RENDER_MODE_ADAPTIVE(3): This mode is deprecated and Agora does not recommend using this mode.
mirrorMode	The remote video render mode: VIDEO_MIRROR_MODE_AUTO(0): (Default) The SDK determines the mirror mode. The SDK disables the mirror mode by default. VIDEO_MIRROR_MODE_ENABLED(1): Enable the mirror mode. VIDEO_MIRROR_MODE_DISABLED(2): Disable the mirror mode.

Returns

• 0: Success.
• < 0: Failure.

Sets whether to receive all remote audio streams by default.

Deprecated:

This method is deprecated from v3.3.0.

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

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.

Parameters

muted

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.

Sets whether to receive all remote video streams by default.

Deprecated:

This method is deprecated from v3.3.0.

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

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.

Parameters

muted

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.

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

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.
• As of v3.3.0, this method contains the function of setDefaultMuteAllRemoteAudioStreams. Agora recommend not calling muteAllRemoteAudioStreams and setDefaultMuteAllRemoteAudioStreams together; otherwise, the settings may not take effect. See Set the Subscribing State.

Parameters

muted

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.

Adjusts the playback signal volume of a specified remote user.

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

Note

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

Parameters

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

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

Parameters

uid	The user ID of the specified remote user.
muted	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 streams of all remote users.

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.
• As of v3.3.0, this method contains the function of setDefaultMuteAllRemoteVideoStreams. Agora recommend not calling muteAllRemoteVideoStreams and setDefaultMuteAllRemoteVideoStreams together; otherwise, the settings may not take effect. See Set the Subscribing State.

Parameters

muted

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 subscribing to the video stream of a specified user.

Note

• Call this method after joining a channel.
• See recommended settings in Set Subscription Status.

Parameters

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

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-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 the remote stream type 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 onApiCallExecuted callback.

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

Parameters

uid	ID of the remote user sending the video stream.
streamType	Sets the video stream type: VIDEO_STREAM_HIGH(0): High-resolution, high-bitrate video. VIDEO_STREAM_LOW(1): Low-resolution, high-bitrate video.

Returns

• 0: Success.
• < 0: Failure.

Sets the default video-stream type of the remote video stream when the remote user sends dual streams.

Note

• This method can only be called before joining a channel. Agora does not support you to change the default subscribed video stream type after joining a channel.
• If you call both this method and setRemoteVideoStreamType , the SDK applies the settings in the setRemoteVideoStreamType method.

Parameters

streamType

Sets the video stream type: VIDEO_STREAM_HIGH(0): High-resolution, high-bitrate video. VIDEO_STREAM_LOW(1): Low-resolution, high-bitrate video.

Returns

• 0: Success.
• < 0: Failure.

Creates a data stream.

Deprecated:

This method is deprecated from v3.3.0. Use the createDataStream[2/2] method instead.

Each user can create up to five data streams during the life cycle of the RtcChannel instance.

Ensure that you call this method after joining a channel.

Note

Do not set reliable as true while setting ordered as false.

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 from the sender within five seconds. If the recipient does not receive the data within five seconds, the SDK triggers the onStreamMessageError callback and returns an error code. 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

Determines whether or not the recipients receive the data stream in the sent order: true: The recipients receive the data in the sent order. false: The recipients do not receive the data in the sent order.

Note

Set both the reliable and ordered parameters to true or false. Do not set one as true and the other as false.

Returns

• The stream ID, if the method call succeeds.
• The negative integer, if the method call fails.

Creates a data stream.

Since

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

The createDataStream[2/2] 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

• Returns the stream ID if you successfully create the data stream.
• < 0: Failure. The error code is related to the integer displayed in Error Codes. For example, if it returns -2, then it indicates ERR_INVALID_ARGUMENT(-2) in Error Codes.

Sends the data stream message.

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

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

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

Parameters

streamId	ID of the sent data stream returned by the createDataStream method.
message	The message data in byte[].

Returns

• 0: Success.
• < 0: Failure.

Publishes the local stream to a specified CDN streaming URL.

Deprecated:

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

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

Parameters

url	The CDN streaming 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	Sets whether transcoding is enabled/disabled. If you set this parameter as true, ensure that you call the setLiveTranscoding method before this method. 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. false: Disable transcoding.

Note

• Ensure that you enable the Media Push service before using this function. See Prerequisites in Media Push.
• Ensure that the user joins a channel before calling this method.
• This method can only be called by a host in a LIVE_BROADCASTING channel.
• This method adds only one CDN streaming URL each time it is called.
• Agora supports pushing media streams in RTMPS protocol to the CDN only when you enable transcoding.*

Returns

• 0: Success.
• < 0: Failure.
  • ERR_INVALID_ARGUMENT(2): Invalid parameter, usually because the URL address is null or the string length is 0.
  • ERR_NOT_INITIALIZED(7): You have not initialized RtcChannel when publishing the stream.

Removes an RTMP or RTMPS stream from the CDN.

Deprecated:

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

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

Note

• Ensure that you enable the Media Push service before using this function. See Prerequisites in Media Push.
• This method can only be called by a host in a LIVE_BROADCASTING channel.
• This method removes only one stream HTTP/HTTPS URL address each time it is called.

Parameters

url	The CDN streaming URL to be removed. The maximum length of this parameter is 1024 bytes. The URL address must not contain special characters, such as Chinese language characters.

Returns

• 0: Success.
• < 0: Failure.

Sets the video layout and audio settings for CDN live.

Deprecated:

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

The SDK triggers the onTranscodingUpdated callback when you call this method to update the LiveTranscodingclass. If you call this method to set the LiveTranscoding class for the first time, the SDK does not trigger the onTranscodingUpdated callback.

Note

• Ensure that you enable the Media Push service before using this function. See Prerequisites in Media Push.
• Ensure that you call this method after joining a channel.
• This method can only be called by a host in a LIVE_BROADCASTING channel.
• Ensure that you call this method before calling the addPublishStreamUrl method.
• Agora supports pushing media streams in RTMPS protocol to the CDN only when you enable transcoding.

Parameters

transcoding

Sets the CDN live audio/video transcoding settings: LiveTranscoding.

Returns

• 0: Success.
• < 0: Failure.

Starts pushing media streams to a CDN without transcoding.

Since

v3.6.0

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 onRtmpStreamingStateChanged callback on the local client to report the state of the streaming.

Note

• Ensure that you enable the Media Push service before using this function. See Prerequisites in Media Push.
• 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.

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.
  • ERR_INVALID_ARGUMENT(2): url 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.0

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 onRtmpStreamingStateChanged callback on the local client to report the state of the streaming.

Note

• Ensure that you enable the Media Push service before using this function. See Prerequisites in Media Push.
• 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.

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.
transcoding	The transcoding configuration for CDN live streaming. LiveTranscoding.

Returns

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

Updates the transcoding configuration.

Since

v3.6.0

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 onTranscodingUpdated callback after the transcoding configuration is updated.

Parameters

transcoding

The transcoding configuration for CDN live streaming. LiveTranscoding.

Returns

• 0: Success.
• < 0: Failure.

Stops pushing media streams to a CDN.

Since

v3.6.0

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

Starts to relay media streams across channels.

After a successful method call, the SDK triggers the onChannelMediaRelayStateChanged and onChannelMediaRelayEvent callbacks, and these callbacks report the state and events of the media stream relay.

• If the onChannelMediaRelayStateChanged callback reports RELAY_STATE_RUNNING(2) and RELAY_OK(0), and the onChannelMediaRelayEvent callback reports RELAY_EVENT_PACKET_SENT_TO_DEST_CHANNEL(4), the SDK starts relaying media streams between the original and the destination channel.
• If the onChannelMediaRelayStateChanged callback returns RELAY_STATE_FAILURE(3), an exception occurs during the media stream relay.

Note

• Contact support@agora.io before implementing this function.
• Call this method after joining the channel.
• This method can only be called by a host in a LIVE_BROADCASTING 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.

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 onChannelMediaRelayStateChanged callback. If the callback reports RELAY_STATE_IDLE(0) and RELAY_OK(0), the host successfully stops the relay.

Note

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

Returns

• 0: Success.
• < 0: Failure.

Updates the channels for media relay.

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, the SDK triggers the onChannelMediaRelayEvent callback with the RELAY_EVENT_PACKET_UPDATE_DEST_CHANNEL(7) state code.

Note

• Call this method after successfully calling the startChannelMediaRelay method and receiving the onChannelMediaRelayStateChanged(RELAY_STATE_RUNNING, RELAY_OK) callback; otherwise, this method call fails.
• 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 removeDestChannelInfo method in ChannelMediaRelayConfiguration before calling this method.

Parameters

channelMediaRelayConfiguration

The media stream relay configuration: ChannelMediaRelayConfiguration.

Returns

• 0: Success.
• < 0: Failure.

Pauses the media stream relay to all destination channels.

Since

v3.5.1

After the cross-channel media stream relay starts, you can call this method to pause relaying media streams to all destination channels; after the pause, if you want to resume the relay, call resumeAllChannelMediaRelay

After a successful method call, the SDK triggers the onChannelMediaRelayEvent callback to report whether the media stream relay is successfully paused.

Note

Call this method after the startChannelMediaRelay method.

Returns

• 0: Success.
• < 0: Failure.

Resumes the media stream relay to all destination channels.

Since

v3.5.1

After calling the pauseAllChannelMediaRelay method, you can call this method to resume relaying media streams to all destination channels.

After a successful method call, the SDK triggers the onChannelMediaRelayEvent callback to report whether the media stream relay is successfully resumed.

Note

Call this method after the pauseAllChannelMediaRelay method.

Returns

• 0: Success.
• < 0: Failure.

Customizes the remote video renderer for the RtcChannel object.

Since

3.0.1

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 the IVideoSink class, and call setRemoteVideoRenderer to add the customized sink into the RtcChannel object.

Parameters

uid	The ID of the remote user.
render	The customized remote video renderer: IVideoSink.

Returns

• 0: Success.
• < 0: Failure.