IAgoraRtcChannel

AddPublishStreamUrl

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

public abstract int AddPublishStreamUrl(string url, bool transcodingEnabled);

Deprecated:: This method is deprecated.

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.

Attention:

Call this method after joining a channel.
Ensure that the media push function is enabled. For details, see the prerequisites in Media Push.
This method takes effect only when you are a host in live interactive streaming.
This method adds only one streaming URL to the CDN each time it is called. To push multiple URLs, call this method multiple times.
Agora only supports pushing media streams to the CDN in RTMPS protocol when you enable transcoding.

Parameters

url

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

transcodingEnabled

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

true: Enable transcoding.
false: Disable transcoding.

Attention: If you set this parameter as true , ensure that you call the SetLiveTranscoding method before this method.

Returns

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

AdjustUserPlaybackSignalVolume

Adjusts the playback signal volume of a specified remote user.

public abstract int AdjustUserPlaybackSignalVolume(uint uid, int volume);

You can call this method to adjust the playback volume of a specified remote user. To adjust the playback volume of different remote users, call the method as many times, once for each remote user.

Attention:

Call this method after joining a channel.
The playback volume here refers to the mixed volume of a specified remote user.

Parameters

uid: The ID of the remote user.
volume: Audio mixing volume. The value ranges between 0 and 100. The default value is 100, the original volume.

Returns

0: Success.
< 0: Failure.

ChannelId

Gets the current channel ID.

public abstract string ChannelId();

Returns

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

CreateDataStream [1/2]

Creates a data stream.

public abstract int CreateDataStream(bool reliable, bool ordered);

Deprecated:: Please use CreateDataStream [2/2] instead.

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

Attention:

Call this method after joining a channel.
Agora does not support setting reliable as true and ordered as true.

Parameters

reliable

Whether or not the data stream is reliable:

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

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.

Returns

ID of the created data stream, if the method call succeeds.
< 0: Failure. You can refer to Error Codes and Warning Codes for troubleshooting.

CreateDataStream [2/2]

Creates a data stream.

public abstract int CreateDataStream(DataStreamConfig config);

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

Compared with CreateDataStream [1/2][1/2], this method does not support data reliability. If a data packet is not received five seconds after it was sent, the SDK directly discards the data.

Parameters

config: The configurations for the data stream. For details, see DataStreamConfig.

Returns

ID of the created data stream, if the method call succeeds.
< 0: Failure. You can refer to Error Codes and Warning Codes for troubleshooting.

EnableEncryption

Enables/Disables the built-in encryption.

public abstract int EnableEncryption(bool enabled, EncryptionConfig config);

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

Attention: If you enable the built-in encryption, you cannot use the media push function.

Parameters

enabled

Whether to enable built-in encryption:

true: Enable the built-in encryption.
false: Disable the built-in encryption.

config

Built-in encryption configurations. See EncryptionConfig for details.

Returns

0: Success.
< 0: Failure.
- -2: An invalid parameter is used. Set the parameter with a valid value.
- -4: 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: The SDK is not initialized. Initialize the IAgoraRtcEngine instance before calling this method.

GetCallId

Retrieves the call ID.

public abstract string GetCallId();

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

Attention: Call this method after joining a channel.

Returns

The current call ID.

GetConnectionState

Gets the current connection state of the SDK.

public abstract CONNECTION_STATE_TYPE GetConnectionState();

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

Returns

The current connection state. For details, see CONNECTION_STATE_TYPE.

JoinChannel

Joins the channel with a user ID.

public abstract int JoinChannel(string token, string info, uint uid, ChannelMediaOptions options);

Once the user joins the channel, the user subscribes to the audio and video streams of all the other users in the channel by default, giving rise to usage and billing calculation. If you do not want to subscribe to a specified stream or all remote streams, call the mute methods accordingly.

Attention:

If you are already in a channel, you cannot rejoin it with the user ID.
We recommend using different UIDs for different channels.
If you want to join the same channel from different devices, ensure that the user IDs in all devices are different.

Parameters

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

CAUTION: Ensure that the App ID used for creating the token is the same App ID used by the Initialize method for initializing the RTC engine.
info: Reserved for future use.
uid: User ID. This parameter is used to identify the user in the channel for real-time audio and video interaction. You need to set and manage user IDs yourself, and ensure that each user ID in the same channel is unique. This parameter is a 32-bit unsigned integer with a value ranging from 1 to 2³² -1. If the user ID is not assigned (or set as 0), the SDK assigns a user ID and reports it in the OnJoinChannelSuccess callback. Your app must maintain this user ID.
options: The channel media options. For details, see 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. This may be caused by the following:
  - You have created an IAgoraRtcChannel object with the same channel name.
  - You have joined a channel by using IAgoraRtcChannel and published a stream in the IAgoraRtcChannel channel.
- -7(ERR_NOT_INITIALIZED): The SDK is not initialized before calling this method. Initialize the IAgoraRtcEngine instance before calling this method.
- -17(ERR_JOIN_CHANNEL_REJECTED): The request to join the channel is rejected. The SDK supports joining only one IAgoraRtcEngine channel at a time. Therefore, the SDK returns this error code when a user who has already joined an IAgoraRtcEngine channel calls the joining channel method of the IAgoraRtcEngine class with a valid channel name.

JoinChannelWithUserAccount

Joins the channel with a user account.

public abstract int JoinChannelWithUserAccount(string token, string userAccount, ChannelMediaOptions options);

Once the user joins the channel, the user subscribes to the audio and video streams of all the other users in the channel by default, giving rise to usage and billing calculation. If you do not want to subscribe to a specified stream or all remote streams, call the mute methods accordingly.

Attention:

If you are already in a channel, you cannot rejoin it with the user ID.
We recommend using different user accounts for different channels.
If you want to join the same channel from different devices, ensure that the user accounts in all devices are different.

Parameters

token

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

CAUTION: Ensure that the App ID used for creating the token is the same App ID used by the Initialize method for initializing the RTC engine.

userAccount

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

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

options

The channel media options. For details, see 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. This may be caused by the following:
  - You have created an IAgoraRtcChannel object with the same channel name.
  - You have joined a channel by using IAgoraRtcChannel and published a stream in the IAgoraRtcChannel channel.
- -7(ERR_NOT_INITIALIZED): The SDK is not initialized before calling this method. Initialize the IAgoraRtcEngine instance before calling this method.
- -17(ERR_JOIN_CHANNEL_REJECTED): The request to join the channel is rejected. The SDK supports joining only one IAgoraRtcEngine channel at a time. Therefore, the SDK returns this error code when a user who has already joined an IAgoraRtcEngine channel calls the joining channel method of the IAgoraRtcEngine class with a valid channel name.

LeaveChannel

Leaves a channel.

public abstract int LeaveChannel();

This method lets the user leave the channel, for example, by hanging up or exiting the call. This method releases all resources related to the session. This method call is asynchronous, and the user has not left the channel when the method call returns.

After calling JoinChannel, you must call LeaveChannel to end the call, otherwise the next call cannot be started.

No matter whether you are currently in a call or not, you can call LeaveChannel without side effects.

A successful call of this method triggers the following callbacks:

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

Attention:

If you call the LeaveChannel method immediately after calling Dispose, the SDK will not be able to trigger the OnLeaveChannel callback.
If you call the LeaveChannel method during a CDN live streaming, the SDK automatically calls the RemovePublishStreamUrl method.

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.

MuteAllRemoteAudioStreams

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

public abstract int MuteAllRemoteAudioStreams(bool mute);

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

Attention:

Call this method after joining a channel.

Parameters

mute

Whether to subscribe to the audio streams of all remote users:

true: Do not subscribe to the audio streams of all remote users.
false: (Default) Subscribe to the audio streams of all remote users by default.

Returns

0: Success.
< 0: Failure.

MuteAllRemoteVideoStreams

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

public abstract int MuteAllRemoteVideoStreams(bool mute);

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

Attention:

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

Parameters

mute

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) Subscribe to the audio streams of all remote users by default.

Returns

0: Success.
< 0: Failure.

MuteRemoteAudioStream

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

public abstract int MuteRemoteAudioStream(uint userId, bool mute);

Attention:

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

userId

The user ID of the specified user.

mute

Whether to stop subscribing to the audio stream of the specified user.

true: Stop subscribing to the audio stream of the specified user.
false: (Default) Subscribe to the audio stream of the specified user.

Returns

0: Success.
< 0: Failure.

MuteRemoteVideoStream

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

public abstract int MuteRemoteVideoStream(uint userId, bool mute);

Attention:

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

userId

The ID of the specified user.

mute

Whether to stop subscribing to the video stream of the specified user.

true: Stop subscribing to the video streams of the specified user.
false: (Default) Subscribe to the video stream of the specified user.

Returns

0: Success.
< 0: Failure.

Publish

Publish local audio and video streams to the channel.

public abstract int Publish();

The call of this method must meet the following requirements, otherwise the SDK returns -5(ERR_REFUSED):

This method only supports publishing audio and video streams to the channel corresponding to the current IAgoraRtcChannel object.
In the interactive live streaming channel, only a host can call this method. To switch the client role, call SetClientRole [2/2] of the current IAgoraRtcChannel object.
You can publish a stream to only one channel at a time. For details on joining multiple channels, see the advanced guide Join Multiple Channels.

Returns

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

RegisterMediaMetadataObserver

Registers the metadata observer.

public abstract int RegisterMediaMetadataObserver(METADATA_TYPE type);

Attention:

Call this method before JoinChannel.
This method applies only to interactive live streaming.

Parameters

type: The metadata type. The SDK currently only supports VIDEO_METADATA. See METADATA_TYPE.

Returns

0: Success.
< 0: Failure.

RegisterPacketObserver

Registers a packet observer.

public abstract int RegisterPacketObserver(IPacketObserver observer);

Call this method registers a packet observer. When the Agora SDK triggers callbacks registered by IPacketObserver for voice or video packet transmission, you can call this method to process the packets, such as encryption and decryption.

Attention:

The size of the packet sent to the network after processing should not exceed 1200 bytes, otherwise, the SDK may fail to send the packet.
Ensure that both receivers and senders call this method; otherwise, you may meet undefined behaviors such as no voice and black screen.
When you use media push, recording, or storage functions, Agora doesn't recommend calling this method.
Call this method before joining a channel.

Parameters

observer: IPacketObserver.

Returns

0: Success.
< 0: Failure.

Dispose

Releases the IAgoraRtcChannel instance.

public abstract void Dispose();

Returns

0: Success.
< 0: Failure.
- -7(ERR_NOT_INITIALIZED): The SDK is not initialized before calling this method. Create and initialize the IAgoraRtcChannel instance before calling this method.

RemovePublishStreamUrl

Removes an RTMP or RTMPS stream from the CDN.

public abstract int RemovePublishStreamUrl(string url);

Deprecated:: This method is deprecated.

After a successful method call, the SDK triggers OnRtmpStreamingStateChanged on the local client to report the result of deleting the address.

Attention:

Before calling this method, make sure that the media push function has been enabled. .
This method takes effect only when you are a host in live interactive streaming.
Call this method after joining a channel.
This method removes only one media push URL each time it is called. To remove multiple URLs, call this method multiple times.

Parameters

url: The media push URL to be removed. The maximum length of this parameter is 1024 bytes. The media push URL must not contain special characters, such as Chinese characters.

Returns

0: Success.
< 0: Failure.

RenewToken

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

public abstract int RenewToken(string token);

Passes a new token to the SDK. A token expires after a certain period of time. The app should get a new token and call this method to pass the token to the SDK. Failure to do so results in the SDK disconnecting from the server.

The SDK triggers the OnTokenPrivilegeWillExpire callback.
The OnConnectionStateChanged callback reports CONNECTION_CHANGED_TOKEN_EXPIRED(9).

Parameters

token: The new token.

SendMetadata

Sends media metadata.

public abstract int SendMetadata(Metadata metadata);

After a successful method call of RegisterMediaMetadataObserver, the SDK triggers the OnReadyToSendMetadata callback, and then you can call this method to send media metadata.

If the metadata is sent successfully, the SDK triggers the OnMetadataReceived callback on the receiver.

Parameters

metadata: Media metadata. See Metadata.

Returns

0: Success.
< 0: Failure.

SendStreamMessage

Sends data stream messages.

public abstract int SendStreamMessage(int streamId, byte[] data);

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 method call triggers the OnStreamMessage callback on the remote client, from which the remote user gets the stream message. A failed method call triggers the OnStreamMessageError callback on the remote client.

Attention:

Ensure that you call CreateDataStream [2/2] to create a data channel before calling this method.
In live streaming scenarios, this method only applies to hosts.

Parameters

streamId: The data stream ID. You can get the data stream ID by calling CreateDataStream [2/2].
data: The message to be sent.

Returns

0: Success.
< 0: Failure.

InitEventHandler

Sets the event handler for the IAgoraRtcChannel object.

public abstract void InitEventHandler(IAgoraRtcChannelEventHandler channelEventHandler);

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

Parameters

channelEventHandler: The event handler for the IAgoraRtcChannel object. For details, see IAgoraRtcChannelEventHandler.

Returns

0(ERR_OK): Success.
< 0: Failure.

SetClientRole [1/2]

Sets the client role.

public abstract int SetClientRole(CLIENT_ROLE_TYPE role);

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: OnClientRoleChanged.
The remote client: OnUserJoined or OnUserOffline (USER_OFFLINE_BECOME_AUDIENCE).

Attention: This method applies only to interactive live streaming.

Parameters

role: The user role. See CLIENT_ROLE_TYPE for details.

Returns

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

SetClientRole [2/2]

Sets the user role and level in an interactive live streaming channel.

public abstract int SetClientRole(CLIENT_ROLE_TYPE role, ClientRoleOptions options);

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: OnClientRoleChanged.
The remote client: OnUserJoined or OnUserOffline.

Attention:

This method only takes effect when the channel profile is live interactive streaming (when the profile parameter in SetChannelProfile set as CHANNEL_PROFILE_LIVE_BROADCASTING).

Parameters

role: The user role in the interactive live streaming. For details, see CLIENT_ROLE_TYPE.
options: The detailed options of a user, including the user level. See ClientRoleOptions for details.

Returns

0: Success.
< 0: Failure.
- -1: A general error occurs (no specified reason).
- -2: The parameter is invalid.
- -5: The request is rejected.
- -7: The SDK is not initialized.

SetDefaultMuteAllRemoteAudioStreams

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

public abstract int SetDefaultMuteAllRemoteAudioStreams(bool mute);

Deprecated:: This method is deprecated.

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.

Attention:

If you need to resume subscribing to the audio streams of remote users in the channel after calling this method, 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

mute

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) Subscribe to the audio streams of all remote users by default.

Returns

0: Success.
< 0: Failure.

SetDefaultMuteAllRemoteVideoStreams

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

public abstract int SetDefaultMuteAllRemoteVideoStreams(bool mute);

Deprecated:: This method is deprecated.

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.

Attention:

If you need to resume subscribing to the video streams of remote users in the channel, do the following:

If you need to resume subscribing to a single user, call MuteRemoteVideoStream(false) and specify the ID of the remote user you want to subscribe to.
If you want to resume subscribing to multiple users, call MuteRemoteVideoStream(false) multiple times.

Parameters

mute

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.

SetEncryptionMode

Sets the built-in encryption mode.

public abstract int SetEncryptionMode(string encryptionMode);

Deprecated:: Please use the EnableEncryption method instead.

The Agora 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 secret. Refer to the information related to the AES encryption algorithm on the differences between the encryption modes.

Attention: Before calling this method, please call SetEncryptionSecret to enable the built-in encryption function.

Parameters

encryptionMode

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.
"sm4-128-ecb": 128-bit SM4 encryption, ECB mode.
"aes-128-gcm": 128-bit AES encryption, GCM mode.
"aes-256-gcm": 256-bit AES encryption, GCM mode.
"": When setting as NULL, the encryption mode is set as "aes-128-xts" by default.

Returns

0: Success.
< 0: Failure.

SetEncryptionSecret

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

public abstract int SetEncryptionSecret(string secret);

Deprecated:: Please use the EnableEncryption method instead.

Before joining the channel, you need to call this method to set the secret parameter to enable the built-in encryption. All users in the same channel should use the same secret. The secret is automatically cleared once a user leaves the channel. If you do not specify the secret or secret is set as null, the built-in encryption is disabled.

Attention:

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.

SetMaxMetadataSize

Sets the maximum size of the media metadata.

public abstract int SetMaxMetadataSize(int size);

After calling RegisterMediaMetadataObserver, you can call this method to set the maximum size of the media metadata.

Parameters

size: The maximum size of media metadata.

Returns

0: Success.
< 0: Failure.

SetLiveTranscoding

Sets the transcoding configurations for media push.

public abstract int SetLiveTranscoding(LiveTranscoding transcoding);

Deprecated:: This method is deprecated.

This method sets the video layout and audio settings for CDN live streaming. The SDK triggers the OnTranscodingUpdated callback when you call this method to update the transcoding setting.

Attention:

This method takes effect only when you are a host in live interactive streaming.
Ensure that you enable the Media Push service before using this function. See Prerequisites in the advanced guide Media Push.
If you call this method to set the transcoding configuration for the first time, the SDK does not trigger the OnTranscodingUpdated callback.
Call this method after joining a channel.
Agora only supports pushing media streams to the CDN in RTMPS protocol when you enable transcoding.

Parameters

transcoding: The transcoding configurations for the media push. See LiveTranscoding for details.

Returns

0: Success.
< 0: Failure.

SetRemoteDefaultVideoStreamType

Sets the default stream type of remote video streams.

public abstract int SetRemoteDefaultVideoStreamType(REMOTE_VIDEO_STREAM_TYPE streamType);

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

By default, users receive the high-quality video stream. Call this method if you want to switch to the low-quality video stream. This method allows the app to adjust the corresponding video stream type based on the size of the video window to reduce the bandwidth and resources. The aspect ratio of the low-quality video stream is the same as the high-quality video stream. Once the resolution of the high-quality video stream is set, the system automatically sets the resolution, frame rate, and bitrate of the low-quality video stream.

The result of this method returns in the OnApiCallExecuted callback.

Attention: Call this method after joining a channel. If you call both SetRemoteVideoStreamType and SetRemoteDefaultVideoStreamType, the setting of SetRemoteVideoStreamType takes effect.

Parameters

streamType: The default stream type of the remote video, see REMOTE_VIDEO_STREAM_TYPE.

Returns

0: Success.
< 0: Failure.

SetRemoteRenderMode

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

public abstract int SetRemoteRenderMode(uint userId, RENDER_MODE_TYPE renderMode,
            VIDEO_MIRROR_MODE_TYPE mirrorMode);

Since: v3.0.0

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

Attention:

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

Parameters

userId: The ID of the remote user.
renderMode: The rendering mode of the remote user view. For details, see RENDER_MODE_TYPE.
mirrorMode: The mirror mode of the remote user view. For details, see VIDEO_MIRROR_MODE_TYPE.

Returns

0: Success.
< 0: Failure.

SetRemoteUserPriority

Prioritizes a remote user's stream.

public abstract int SetRemoteUserPriority(uint uid, PRIORITY_TYPE userPriority);

Prioritizes a remote user's stream. The SDK ensures the high-priority user gets the best possible stream quality. The SDK ensures the high-priority user gets the best possible stream quality.

Attention:

The SDK supports setting only one user as high priority.
Ensure that you call this method before joining a channel.

Parameters

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

Returns

0: Success.
< 0: Failure.

SetRemoteVideoStreamType

Sets the stream type of the remote video.

public abstract int SetRemoteVideoStreamType(uint userId, REMOTE_VIDEO_STREAM_TYPE streamType);

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). The high-quality video stream has a higher resolution and bitrate, and the low-quality video stream has a lower resolution and bitrate.

By default, users receive the high-quality video stream. Call this method if you want to switch to the low-quality video stream. This method allows the app to adjust the corresponding video stream type based on the size of the video window to reduce the bandwidth and resources. The aspect ratio of the low-quality video stream is the same as the high-quality video stream. Once the resolution of the high-quality video stream is set, the system automatically sets the resolution, frame rate, and bitrate of the low-quality video stream.

The method result returns in the OnApiCallExecuted callback.

Attention: Call this method after joining a channel. If you call both SetRemoteVideoStreamType and SetRemoteDefaultVideoStreamType, the setting of SetRemoteVideoStreamType takes effect.

Parameters

userId: User ID.
streamType: The video stream type: REMOTE_VIDEO_STREAM_TYPE.

Returns

0: Success.
< 0: Failure.

SetRemoteVoicePosition

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

public abstract int SetRemoteVoicePosition(uint uid, double pan, double gain);

This method sets the 2D position and volume of a remote user, so that the local user can easily hear and identify the remote user's position.

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

Attention:

For this method to work, enable stereo panning for remote users by calling the EnableSoundPositionIndication method before joining a channel.
For the best voice positioning, Agora recommends using a wired headset.
Call this method after joining a channel.

Parameters

uid

The user ID of the remote user.

pan

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

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

gain

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

Returns

0: Success.
< 0: Failure.

StartChannelMediaRelay

Starts relaying media streams across channels. This method can be used to implement scenarios such as co-host across channels.

public abstract int StartChannelMediaRelay(ChannelMediaRelayConfiguration configuration);

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

If the OnChannelMediaRelayStateChanged callback returns RELAY_STATE_RUNNING (2) and RELAY_OK (0), and the OnChannelMediaRelayEvent callback returns RELAY_EVENT_PACKET_SENT_TO_DEST_CHANNEL (4), it means that the SDK starts relaying media streams between the source channel and the destination channel.
If the OnChannelMediaRelayStateChanged callback returns RELAY_STATE_FAILURE (3), an exception occurs during the media stream relay.

Attention:

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

Parameters

configuration: The configuration of the media stream relay. See ChannelMediaRelayConfiguration for details.

Returns

Success.
<Failure.

StartRtmpStreamWithTranscoding

Starts Media Push and sets the transcoding configuration.

public abstract int StartRtmpStreamWithTranscoding(string url, LiveTranscoding transcoding);

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.

Attention:

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.

Parameters

url: The address of Media Push. 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 Media Push. See LiveTranscoding.

Returns

0: Success.
< 0: Failure.

StartRtmpStreamWithoutTranscoding

Starts pushing media streams to a CDN without transcoding.

public abstract int StartRtmpStreamWithoutTranscoding(string url);

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.

Attention:

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.

Parameters

url: The address of Media Push. The format is RTMP or RTMPS. The character length cannot exceed 1024 bytes. Special characters such as Chinese characters are not supported.

StopRtmpStream

Stops pushing media streams to a CDN.

public abstract int StopRtmpStream(string url);

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 Media Push. The format is RTMP or RTMPS. The character length cannot exceed 1024 bytes. Special characters such as Chinese characters are not supported.

StopChannelMediaRelay

Stops the media stream relay. Once the relay stops, the host quits all the destination channels.

public abstract int StopChannelMediaRelay();

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.

Attention: 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) status code. You can call the LeaveChannel method to leave the channel, and the media stream relay automatically stops.

Returns

0: Success.
< 0: Failure.

UpdateRtmpTranscoding

Updates the transcoding configuration.

public abstract int UpdateRtmpTranscoding(LiveTranscoding transcoding);

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 Media Push. See LiveTranscoding.

Unpublish

Stops publishing a stream to the channel.

public abstract int Unpublish();

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

Returns

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

UnRegisterMediaMetadataObserver

Unregisters the media metadata observer.

public abstract int UnRegisterMediaMetadataObserver(METADATA_TYPE type);

Parameters

type: The metadata type. The SDK currently only supports VIDEO_METADATA. For details, see METADATA_TYPE.

Returns

0: Success.
< 0: Failure.

UpdateChannelMediaRelay

Updates the channels for media stream relay.

public abstract int UpdateChannelMediaRelay(ChannelMediaRelayConfiguration configuration);

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

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

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

Parameters

configuration: The configuration of the media stream relay. For more details, see ChannelMediaRelayConfiguration.

Returns

0: Success.
< 0: Failure.