RtcChannel

Provides methods that enable real-time communications in an channel.

Call create to create an RtcChannel object.

create

Creates and gets an RtcChannel object. 

static Future<RtcChannel> create(String channelId) async

You can call this method multiple times to create multiple RtcChannel objects, and then call the joinChannel methods in of each RtcChannel to join multiple channels at the same time.

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

Parameters

channelId
The channel name. This parameter signifies the channel in which users engage in real-time audio and video interaction. Under the premise of the same App ID, users who fill in the same channel ID enter the same channel for audio and video interaction. The string length must be less than 64 bytes. Supported characters:
  • The 26 lowercase English letters: a to z.
  • The 26 uppercase English letters: A to Z.
  • The 10 numeric characters: 0 to 9.
  • Space
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","
Attention:
  • The parameter does not have a default value. You must set it.
  • Do not set this parameter as the empty string "". Otherwise, the SDK returns ERR_REFUSED(5).

Returns

  • A pointer to the RtcChannel instance, if the method call succeeds.
  • If the call fails, returns null.

addPublishStreamUrl

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

Future<void> 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 rtmpStreamingStateChanged 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.

adjustUserPlaybackSignalVolume

Adjusts the playback signal volume of a specified remote user. 

Future<void> adjustUserPlaybackSignalVolume(int 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.

channelId

Gets the current channel ID. 

String channelId;

Returns

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

createDataStream

Creates a data stream. 

Future<int?> createDataStream(bool reliable, bool ordered);
Deprecated:
Please use createDataStreamWithConfig instead.

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

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

createDataStreamWithConfig

Creates a data stream. 

Future<int?> createDataStreamWithConfig(DataStreamConfig config);

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

Compared with createDataStream[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

enableEncryption

Enables/Disables the built-in encryption. 

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

enableRemoteSuperResolution

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

Future<void> enableRemoteSuperResolution(int userId, bool enable);

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 you call this method, the SDK triggers the userSuperResolutionEnabled callback to report whether you have successfully enabled super resolution.

CAUTION:

The super resolution feature requires extra system resources. To balance the visual experience and system consumption, this feature can only be enabled for a single remote user. If the local user uses super resolution on Android, the original resolution of the remote user's video cannot exceed 640 × 360 pixels; if the local user uses super resolution on iOS, the original resolution of the remote user's video cannot exceed 640 × 480 pixels.

If you exceed these limitations, the SDK triggers the warning callback and returns all corresponding warning codes:
  • SuperResolutionStreamOverLimitation: 1610. The origin resolution of the remote video is beyond the range where super resolution can be applied.
  • SuperResolutionUserCountOverLimitation: 1611. Super resolution is already being used on another remote user's video.
  • SuperResolutionDeviceNotSupported: 1612. The device does not support using super resolution.
Attention:
  • This method applies to Android and iOS only.
  • Before calling this method, ensure that you have integrated the following dynamic libraries:
    • Android: libagora_super_resolution_extension.so
    • iOS: AgoraSuperResolutionExtension.xcframework
  • Because this method has certain system performance requirements, Agora recommends that you use the following devices or better:
    • Android:
      • 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 M6, MatePad 10.8
    • iOS:
      • 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 3 (3rd generation)
      • iPad Air 3 (4th generation)

Parameters

userId
The user ID of the remote user.
enable
Whether to enable super resolution for the remote user’s video:
  • true: Enable super resolution.
  • false: Disable super resolution.

getCallId

Retrieves the call ID. 

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

Future<ConnectionStateType> getConnectionState();

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

Returns

The current connection state.

joinChannel

Joins the channel with a user ID. 

Future<void> joinChannel(String? token, String? optionalInfo, int optionalUid,
      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 createWithContext method for initializing the RTC engine.
optionalInfo

Reserved for future use.

optionalUid
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 232 -1. If the user ID is not assigned (or set as 0), the SDK assigns a user ID and reports it in the joinChannelSuccess callback. Your app must maintain this user ID.
options

The channel media options. For details, see ChannelMediaOptions.

joinChannelWithUserAccount

Joins the channel with a user account. 

Future<void> 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 createWithContext 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.

leaveChannel

Leaves a channel. 

Future<void> 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: leaveChannel.
  • The remote client: userOffline, 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 destroy, the SDK will not be able to trigger the leaveChannel callback.
  • If you call the leaveChannel method during a CDN live streaming, the SDK automatically calls the removePublishStreamUrl method.

muteAllRemoteAudioStreams

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

Future<void> muteAllRemoteAudioStreams(bool muted);

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

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

muteAllRemoteVideoStreams

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

Future<void> muteAllRemoteVideoStreams(bool muted);

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:

Parameters

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

muteLocalAudioStream

Stops or resumes publishing the local audio stream. 

Future<void> muteLocalAudioStream(bool mute);

Parameters

mute
Whether to stop publishing the local audio stream.
  • true: Stop publishing the local audio stream.
  • false: (Default) Resumes publishing the local audio stream.

muteLocalVideoStream

Stops or resumes publishing the local video stream. 

Future<void> muteLocalVideoStream(bool muted);

Parameters

muted
Whether to stop publishing the local video stream.
  • true: Stop publishing the local video stream.
  • false: (Default) Publish the local video stream.

muteRemoteAudioStream

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

Future<void> muteRemoteAudioStream(int userId, bool muted);
Attention:
  • Call this method after joining a channel.
  • See recommended settings in Set the Subscribing State.
userId
The user ID of the specified user.
muted
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.

muteRemoteVideoStream

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

Future<void> muteRemoteVideoStream(int userId, bool muted);
Attention:
  • Call this method after joining a channel.
  • See recommended settings in Set the Subscribing State.
userId
The ID of the specified user.
muted
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.

pauseAllChannelMediaRelay

Pauses the media stream relay to all destination channels. 

Future<void> pauseAllChannelMediaRelay();

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 channelMediaRelayEvent callback to report whether the media stream relay is successfully paused.

Attention: Call this method after startChannelMediaRelay.

publish

Publish local audio and video streams to the channel. 

Future<void> 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 RtcChannel object.
  • In the interactive live streaming channel, only a host can call this method. To switch the client role, call setClientRole of the current RtcChannel 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.

registerMediaMetadataObserver

Registers the metadata observer. 

Future<void> registerMediaMetadataObserver();
Attention:
  • Call this method before joinChannel.
  • This method applies only to interactive live streaming.

destroyAll

Destroys all RtcChannel instances. 

static void destroyAll()

removePublishStreamUrl

Removes an RTMP or RTMPS stream from the CDN. 

Future<void> removePublishStreamUrl(String url);
Deprecated:
This method is deprecated.

After a successful method call, the SDK triggers rtmpStreamingStateChanged 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.

renewToken

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

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

Parameters

token
The new token.

sendMetadata

Sends media metadata. 

Future<void> sendMetadata(Uint8List metadata);

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

Parameters

metadata
Media metadata. See Metadata.

sendStreamMessage

Sends data stream messages. 

Future<void> sendStreamMessage(int streamId, Uint8List message);
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 streamMessage callback on the remote client, from which the remote user gets the stream message. A failed method call triggers the streamMessageError callback on the remote client.

Attention:
  • Ensure that you call createDataStreamWithConfig 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 createDataStreamWithConfig.
message
The message to be sent.

setEventHandler

Sets the event handler for the RtcChannel object. 

void setEventHandler(RtcChannelEventHandler handler)

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

Parameters

handler
The event handler for the RtcChannel object. For details, see RtcChannelEventHandler.

Returns

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

setClientRole

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

Future<void> setClientRole(ClientRole 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:
Attention:
  • This method only takes effect when the channel profile is live interactive streaming (when the profile parameter in setChannelProfile set as LiveBroadcasting).

Parameters

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

setDefaultMuteAllRemoteAudioStreams

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

Future<void> setDefaultMuteAllRemoteAudioStreams(bool muted);
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

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

setDefaultMuteAllRemoteVideoStreams

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

Future<void> setDefaultMuteAllRemoteVideoStreams(bool muted);
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

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

setEncryptionMode

Sets the built-in encryption mode. 

Future<void> setEncryptionMode(EncryptionMode 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.

setEncryptionSecret

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

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

setMaxMetadataSize

Sets the maximum size of the media metadata. 

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

setRemoteDefaultVideoStreamType

Sets the default stream type of remote video streams. 

Future<void> setRemoteDefaultVideoStreamType(VideoStreamType 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 apiCallExecuted 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 VideoStreamType.

setRemoteUserPriority

Prioritizes a remote user's stream. 

Future<void> setRemoteUserPriority(int uid, UserPriority 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 UserPriority.

setRemoteVideoStreamType

Sets the stream type of the remote video. 

Future<void> setRemoteVideoStreamType(int userId, VideoStreamType 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 apiCallExecuted 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: VideoStreamType.

setRemoteVoicePosition

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

Future<void> setRemoteVoicePosition(int 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.

startChannelMediaRelay

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

Future<void> startChannelMediaRelay(
      ChannelMediaRelayConfiguration channelMediaRelayConfiguration);
After a successful method call, the SDK triggers the channelMediaRelayStateChanged and channelMediaRelayEvent callbacks, and these callbacks return the state and events of the media stream relay.
  • If the channelMediaRelayStateChanged callback returns Running (2) and None (0), and the channelMediaRelayEvent callback returns SentToDestinationChannel (4), it means that the SDK starts relaying media streams between the source channel and the destination channel.
  • If the channelMediaRelayStateChanged callback returns 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 mailto:support@agora.io before implementing this function.
  • We do not support string user accounts in this API.

Parameters

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

startRtmpStreamWithoutTranscoding

Starts pushing media streams to a CDN without transcoding. 

Future<void> 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 rtmpStreamingStateChanged 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.

startRtmpStreamWithTranscoding

Starts Media Push and sets the transcoding configuration. 

Future<void> startRtmpStreamWithTranscoding(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 rtmpStreamingStateChanged 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.

stopChannelMediaRelay

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

Future<void> stopChannelMediaRelay();

After a successful method call, the SDK triggers the channelMediaRelayStateChanged callback. If the callback reports Idle(0) and None(0), the host successfully stops the relay.

Attention: If the method call fails, the SDK triggers the channelMediaRelayStateChanged callback with the ServerNoResponse(2) or ServerConnectionLost(8) status code. You can call the leaveChannel method to leave the channel, and the media stream relay automatically stops.

stopRtmpStream

Stops pushing media streams to a CDN. 

Future<void> 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 rtmpStreamingStateChanged 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.

unpublish

Stops publishing a stream to the channel. 

Future<void> unpublish();

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

updateChannelMediaRelay

Updates the channels for media stream relay. 

Future<void> updateChannelMediaRelay(
      ChannelMediaRelayConfiguration channelMediaRelayConfiguration);

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 channelMediaRelayEvent callback with the UpdateDestinationChannel(7) state code.

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

Parameters

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