Video SDK v3.7.1 API Reference for All Platforms (C++)
agora::rtc::IChannel Class Referenceabstract

Public Member Functions

virtual ~IChannel ()
 
virtual int release ()=0
 
virtual int setChannelEventHandler (IChannelEventHandler *channelEh)=0
 
virtual int joinChannel (const char *token, const char *info, uid_t uid, const ChannelMediaOptions &options)=0
 
virtual int joinChannelWithUserAccount (const char *token, const char *userAccount, const ChannelMediaOptions &options)=0
 
virtual int leaveChannel ()=0
 
virtual int publish () AGORA_DEPRECATED_ATTRIBUTE=0
 
virtual int unpublish () AGORA_DEPRECATED_ATTRIBUTE=0
 
virtual const char * channelId ()=0
 
virtual int getCallId (agora::util::AString &callId)=0
 
virtual int renewToken (const char *token)=0
 
virtual int setEncryptionSecret (const char *secret) AGORA_DEPRECATED_ATTRIBUTE=0
 
virtual int setEncryptionMode (const char *encryptionMode) AGORA_DEPRECATED_ATTRIBUTE=0
 
virtual int enableEncryption (bool enabled, const EncryptionConfig &config)=0
 
virtual int registerPacketObserver (IPacketObserver *observer)=0
 
virtual int registerMediaMetadataObserver (IMetadataObserver *observer, IMetadataObserver::METADATA_TYPE type)=0
 
virtual int setClientRole (CLIENT_ROLE_TYPE role)=0
 
virtual int setClientRole (CLIENT_ROLE_TYPE role, const ClientRoleOptions &options)=0
 
virtual int setRemoteUserPriority (uid_t uid, PRIORITY_TYPE userPriority)=0
 
virtual int setRemoteVoicePosition (uid_t uid, double pan, double gain)=0
 
virtual int setRemoteRenderMode (uid_t userId, RENDER_MODE_TYPE renderMode, VIDEO_MIRROR_MODE_TYPE mirrorMode)=0
 
virtual int setDefaultMuteAllRemoteAudioStreams (bool mute) AGORA_DEPRECATED_ATTRIBUTE=0
 
virtual int setDefaultMuteAllRemoteVideoStreams (bool mute) AGORA_DEPRECATED_ATTRIBUTE=0
 
virtual int muteLocalAudioStream (bool mute)=0
 
virtual int muteLocalVideoStream (bool mute)=0
 
virtual int muteAllRemoteAudioStreams (bool mute)=0
 
virtual int adjustUserPlaybackSignalVolume (uid_t userId, int volume)=0
 
virtual int muteRemoteAudioStream (uid_t userId, bool mute)=0
 
virtual int muteAllRemoteVideoStreams (bool mute)=0
 
virtual int muteRemoteVideoStream (uid_t userId, bool mute)=0
 
virtual int setRemoteVideoStreamType (uid_t userId, REMOTE_VIDEO_STREAM_TYPE streamType)=0
 
virtual int setRemoteDefaultVideoStreamType (REMOTE_VIDEO_STREAM_TYPE streamType)=0
 
virtual int createDataStream (int *streamId, bool reliable, bool ordered) AGORA_DEPRECATED_ATTRIBUTE=0
 
virtual int createDataStream (int *streamId, DataStreamConfig &config)=0
 
virtual int sendStreamMessage (int streamId, const char *data, size_t length)=0
 
virtual int addPublishStreamUrl (const char *url, bool transcodingEnabled) AGORA_DEPRECATED_ATTRIBUTE=0
 
virtual int removePublishStreamUrl (const char *url) AGORA_DEPRECATED_ATTRIBUTE=0
 
virtual int setLiveTranscoding (const LiveTranscoding &transcoding) AGORA_DEPRECATED_ATTRIBUTE=0
 
virtual int startRtmpStreamWithoutTranscoding (const char *url)=0
 
virtual int startRtmpStreamWithTranscoding (const char *url, const LiveTranscoding &transcoding)=0
 
virtual int updateRtmpTranscoding (const LiveTranscoding &transcoding)=0
 
virtual int stopRtmpStream (const char *url)=0
 
virtual int addInjectStreamUrl (const char *url, const InjectStreamConfig &config)=0
 
virtual int removeInjectStreamUrl (const char *url)=0
 
virtual int startChannelMediaRelay (const ChannelMediaRelayConfiguration &configuration)=0
 
virtual int updateChannelMediaRelay (const ChannelMediaRelayConfiguration &configuration)=0
 
virtual int pauseAllChannelMediaRelay ()=0
 
virtual int resumeAllChannelMediaRelay ()=0
 
virtual int stopChannelMediaRelay ()=0
 
virtual CONNECTION_STATE_TYPE getConnectionState ()=0
 
virtual int enableRemoteSuperResolution (uid_t userId, bool enable) AGORA_DEPRECATED_ATTRIBUTE=0
 
virtual int enableRemoteSuperResolution (bool enabled, SR_MODE mode, uid_t userId)=0
 

Detailed Description

The IChannel class.

Constructor & Destructor Documentation

◆ ~IChannel()

virtual agora::rtc::IChannel::~IChannel ( )
inlinevirtual

Member Function Documentation

◆ release()

virtual int agora::rtc::IChannel::release ( )
pure virtual

Releases all IChannel resources.

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

◆ setChannelEventHandler()

virtual int agora::rtc::IChannel::setChannelEventHandler ( IChannelEventHandler channelEh)
pure virtual

Sets the channel event handler.

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

Parameters
channelEhThe event handler of the IChannel object. For details, see IChannelEventHandler.
Returns
  • 0: Success.
  • < 0: Failure.

◆ joinChannel()

virtual int agora::rtc::IChannel::joinChannel ( const char *  token,
const char *  info,
uid_t  uid,
const ChannelMediaOptions options 
)
pure virtual

Joins the channel with a user ID.

Compared with the joinChannel method in the IRtcEngine class, this method supports joining multiple channels at a time by creating multiple IChannel objects and then calling joinChannel in each IChannel 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 IRtcEngine object.
Parameters
tokenThe token generated at your server. See Authenticate Your Users with Tokens.
info(Optional) Additional information about the channel. This parameter can be set as null. Other users in the channel do not receive this information.
uidThe 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.
optionsThe 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. This may be caused by the following:
      • You have created an IChannel object with the same channel name.
      • You have joined and published a stream in a channel created by the IChannel object. When you join a channel created by the IRtcEngine object, the SDK publishes the local audio and video streams to that channel by default. Because the SDK does not support publishing a local stream to more than one channel simultaneously, an error occurs in this occasion.
    • -7(ERR_NOT_INITIALIZED): The SDK is not initialized before calling this method.
    • ERR_JOIN_CHANNEL_REJECTED(-17): The request to join the channel is rejected. The SDK does not support joining the same IChannel channel repeatedly. Therefore, the SDK returns this error code when a user who has already joined an IChannel channel calls the joining channel method of this IChannel object.

◆ joinChannelWithUserAccount()

virtual int agora::rtc::IChannel::joinChannelWithUserAccount ( const char *  token,
const char *  userAccount,
const ChannelMediaOptions options 
)
pure virtual

Joins the channel with a user account.

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

After the user successfully joins the channel, the SDK triggers the following callbacks:

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 parameters or call the mute methods accordingly.

Note
  • To ensure smooth communication, use the same parameter type to identify the user. For example, if a user joins the channel with a user ID, then ensure all the other users use the user ID too. The same applies to the user account. If a user joins the channel with the Agora Web SDK, ensure that the uid of the user is set to the same parameter type.
  • Before using a String user name, ensure that you read How can I use string user names for getting details about the limitations and implementation steps.
Parameters
tokenThe token generated at your server. See Authenticate Your Users with Tokens.
userAccountThe user account. The maximum length of this parameter is 255 bytes. Ensure that the user account is unique and do not set it as null. Supported character scopes are:
  • All lowercase English letters: a to z.
  • All uppercase English letters: A to Z.
  • All numeric characters: 0 to 9.
  • The space character.
  • Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
optionsThe channel media options: agora::rtc::ChannelMediaOptions::ChannelMediaOptions “ChannelMediaOptions”.
Returns

◆ leaveChannel()

virtual int agora::rtc::IChannel::leaveChannel ( )
pure virtual

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

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

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

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

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 the Communication channel, or is a host in the LIVE_BROADCASTING profile.
Note
  • If you call the release method immediately after the leaveChannel method, the leaveChannel process interrupts, and the onLeaveChannel callback is not triggered.
  • If you call the leaveChannel method during a CDN live streaming, the SDK triggers the removePublishStreamUrl method.
Returns
  • 0(ERR_OK): Success.
  • < 0: Failure.
    • -1(ERR_FAILED): A general error occurs (no specified reason).
    • -2(ERR_INVALID_ARGUMENT): The parameter is invalid.
    • -7(ERR_NOT_INITIALIZED): The SDK is not initialized.

◆ publish()

virtual int agora::rtc::IChannel::publish ( )
pure virtual

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

◆ unpublish()

virtual int agora::rtc::IChannel::unpublish ( )
pure virtual

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

Returns
  • 0: Success.
  • < 0: Failure.

◆ channelId()

virtual const char* agora::rtc::IChannel::channelId ( )
pure virtual

Gets the channel ID of the current IChannel object.

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

◆ getCallId()

virtual int agora::rtc::IChannel::getCallId ( agora::util::AString callId)
pure virtual

Gets the current call ID.

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

The rate and complain methods require the callId parameter retrieved from the getCallId method during a call. callId is passed as an argument into the rate and complain methods after the call ends.

Note
Ensure that you call this method after joining a channel.
Parameters
callIdThe current call ID.
Returns
  • 0: Success.
  • < 0: Failure.

◆ renewToken()

virtual int agora::rtc::IChannel::renewToken ( const char *  token)
pure virtual

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

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

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

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

◆ setEncryptionSecret()

virtual int agora::rtc::IChannel::setEncryptionSecret ( const char *  secret)
pure virtual

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

Deprecated:
Deprecated as of v3.1.0. Use the enableEncryption instead.

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

If an encryption password is not specified, the encryption functionality will be disabled.

Note
  • Do not use this method for CDN live streaming.
  • For optimal transmission, ensure that the encrypted data size does not exceed the original data size + 16 bytes. 16 bytes is the maximum padding size for AES encryption.
Parameters
secretPointer to the encryption password.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setEncryptionMode()

virtual int agora::rtc::IChannel::setEncryptionMode ( const char *  encryptionMode)
pure virtual

Sets the built-in encryption mode.

Deprecated:
Deprecated as of v3.1.0. Use the enableEncryption 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 password.

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

Note
Call the setEncryptionSecret method to enable the built-in encryption function before calling this method.
Parameters
encryptionModeThe set encryption mode:
  • "aes-128-xts": (Default) 128-bit AES encryption, XTS mode.
  • "aes-128-ecb": 128-bit AES encryption, ECB mode.
  • "aes-256-xts": 256-bit AES encryption, XTS mode.
  • "": When encryptionMode is set as NULL, the encryption mode is set as "aes-128-xts" by default.
Returns
  • 0: Success.
  • < 0: Failure.

◆ enableEncryption()

virtual int agora::rtc::IChannel::enableEncryption ( bool  enabled,
const EncryptionConfig config 
)
pure virtual

Enables/Disables the built-in encryption.

Since
v3.1.0

In scenarios requiring high security, Agora recommends calling this method 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
enabledWhether to enable the built-in encryption:
  • true: Enable the built-in encryption.
  • false: Disable the built-in encryption.
configConfigurations of built-in encryption schemas. See EncryptionConfig.
Returns
  • 0: Success.
  • < 0: Failure.
    • -2(ERR_INVALID_ARGUMENT): An invalid parameter is used. Set the parameter with a valid value.
    • -4(ERR_NOT_SUPPORTED): The encryption mode is incorrect or the SDK fails to load the external encryption library. Check the enumeration or reload the external encryption library.
    • -7(ERR_NOT_INITIALIZED): The SDK is not initialized. Initialize the IRtcEngine instance before calling this method.

◆ registerPacketObserver()

virtual int agora::rtc::IChannel::registerPacketObserver ( IPacketObserver observer)
pure virtual

Registers a packet observer.

The Agora SDK allows your application to register a packet observer to receive callbacks for voice or video packet transmission.

Note
  • The size of the packet sent to the network after processing should not exceed 1200 bytes, otherwise, the packet may fail to be sent.
  • 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 CDN live streaming and recording functions, Agora doesn't recommend calling this method.
  • Call this method before joining a channel.
Parameters
observerThe registered packet observer. See IPacketObserver.
Returns
  • 0: Success.
  • < 0: Failure.

◆ registerMediaMetadataObserver()

virtual int agora::rtc::IChannel::registerMediaMetadataObserver ( IMetadataObserver observer,
IMetadataObserver::METADATA_TYPE  type 
)
pure virtual

Registers the metadata observer.

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 interactive live streaming, such as sending shopping links, digital coupons, and online quizzes.

Note
Call this method before the joinChannel method.
Parameters
observerThe IMetadataObserver class. See the definition of IMetadataObserver for details.
typeSee METADATA_TYPE. The SDK supports VIDEO_METADATA (0) only for now.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setClientRole() [1/2]

virtual int agora::rtc::IChannel::setClientRole ( CLIENT_ROLE_TYPE  role)
pure virtual

Sets the role of the user in interactive live streaming.

In the LIVE_BROADCASTING channel profile, 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:

Note
This method applies to the LIVE_BROADCASTING profile only.
Parameters
roleThe role of a user in interactive live streaming. See CLIENT_ROLE_TYPE.
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.

◆ setClientRole() [2/2]

virtual int agora::rtc::IChannel::setClientRole ( CLIENT_ROLE_TYPE  role,
const ClientRoleOptions options 
)
pure virtual

Sets the role of the user in interactive live streaming.

Since
v3.2.0

In the LIVE_BROADCASTING channel profile, 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:

Note
  • This method applies to the LIVE_BROADCASTING profile only.
  • The difference between this method and setClientRole [1/2] 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 member can choose to receive remote streams with low latency or ultra low latency. User level affects the pricing of services.
Parameters
roleThe role of a user in interactive live streaming. See CLIENT_ROLE_TYPE.
optionsThe 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.

◆ setRemoteUserPriority()

virtual int agora::rtc::IChannel::setRemoteUserPriority ( uid_t  uid,
PRIORITY_TYPE  userPriority 
)
pure virtual

Prioritizes a remote user's stream.

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

Note
  • The Agora SDK supports setting serPriority as high for one user only.
  • Ensure that you call this method before joining a channel.
Parameters
uidThe ID of the remote user.
userPrioritySets the priority of the remote user. See PRIORITY_TYPE.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setRemoteVoicePosition()

virtual int agora::rtc::IChannel::setRemoteVoicePosition ( uid_t  uid,
double  pan,
double  gain 
)
pure virtual

Sets the sound position and gain of a remote user.

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

Note
  • For this method to work, enable stereo panning for remote users by calling the enableSoundPositionIndication method before joining a channel.
  • This method requires hardware support. For the best sound positioning, we recommend using a wired headset.
  • Ensure that you call this method after joining a channel.
Parameters
uidThe ID of the remote user.
panThe 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.
gainGain of the remote user. The value ranges from 0.0 to 100.0. The default value is 100.0 (the original gain of the remote user). The smaller the value, the less the gain.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setRemoteRenderMode()

virtual int agora::rtc::IChannel::setRemoteRenderMode ( uid_t  userId,
RENDER_MODE_TYPE  renderMode,
VIDEO_MIRROR_MODE_TYPE  mirrorMode 
)
pure virtual

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

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

Note
  • Call this method after calling the setupRemoteVideo method to initialize the remote video view.
  • 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
userIdThe ID of the remote user.
renderModeThe rendering mode of the remote video view. See RENDER_MODE_TYPE.
mirrorMode
  • The mirror mode of the remote video view. See VIDEO_MIRROR_MODE_TYPE.
  • Note: The SDK disables the mirror mode by default.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setDefaultMuteAllRemoteAudioStreams()

virtual int agora::rtc::IChannel::setDefaultMuteAllRemoteAudioStreams ( bool  mute)
pure virtual

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

Deprecated:
This method is deprecated from v3.3.0.

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

Note
If you need to resume subscribing to the audio streams of remote users in the channel after calling setDefaultMuteAllRemoteAudioStreams (true), do the following:
  • If you need to resume subscribing to the audio stream of a specified user, call muteRemoteAudioStream (false), and specify the user ID.
  • If you need to resume subscribing to the audio streams of multiple remote users, call muteRemoteAudioStream (false) multiple times.
Parameters
muteSets 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.

◆ setDefaultMuteAllRemoteVideoStreams()

virtual int agora::rtc::IChannel::setDefaultMuteAllRemoteVideoStreams ( bool  mute)
pure virtual

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

Deprecated:
This method is deprecated from v3.3.0.

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

Note
If you need to resume subscribing to the video streams of remote users in the channel after calling setDefaultMuteAllRemoteVideoStreams (true), do the following:
  • If you need to resume subscribing to the video stream of a specified user, call muteRemoteVideoStream (false), and specify the user ID.
  • If you need to resume subscribing to the video streams of multiple remote users, call muteRemoteVideoStream (false) multiple times.
Parameters
muteSets 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.

◆ muteLocalAudioStream()

virtual int agora::rtc::IChannel::muteLocalAudioStream ( bool  mute)
pure virtual

Stops or resumes publishing the local audio stream.

Since
v3.4.5

This method only sets the publishing state of the audio stream in the channel of IChannel.

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 state 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 State.
Parameters
muteSets 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.

◆ muteLocalVideoStream()

virtual int agora::rtc::IChannel::muteLocalVideoStream ( bool  mute)
pure virtual

Stops or resumes publishing the local video stream.

Since
v3.4.5

This method only sets the publishing state of the video stream in the channel of IChannel.

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 state 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 State.
Parameters
muteSets 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.

◆ muteAllRemoteAudioStreams()

virtual int agora::rtc::IChannel::muteAllRemoteAudioStreams ( bool  mute)
pure virtual

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 recommends not calling muteAllRemoteAudioStreams and setDefaultMuteAllRemoteAudioStreams together; otherwise, the settings may not take effect. See Set the Subscribing State.
Parameters
muteSets 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.

◆ adjustUserPlaybackSignalVolume()

virtual int agora::rtc::IChannel::adjustUserPlaybackSignalVolume ( uid_t  userId,
int  volume 
)
pure virtual

Adjust the playback signal volume of the specified remote user.

After joining a channel, call adjustPlaybackSignalVolume to adjust the playback volume of different remote users, or adjust multiple times for one remote user.

Note
  • Call this method after joining a channel.
  • This method adjusts the playback volume, which is the mixed volume for the specified remote user.
  • This method can only adjust the playback volume of one specified remote user at a time. If you want to adjust the playback volume of several remote users, call the method multiple times, once for each remote user.
Parameters
userIdThe user ID, which should be the same as the uid of joinChannel
volumeThe playback volume of the voice. The value ranges between 0 and 100, including the following:
  • 0: Mute.
  • 100: (Default) Original volume.
Returns
  • 0: Success.
  • < 0: Failure.

◆ muteRemoteAudioStream()

virtual int agora::rtc::IChannel::muteRemoteAudioStream ( uid_t  userId,
bool  mute 
)
pure virtual

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

Note
  • Call this method after joining a channel.
  • See recommended settings in Set the Subscribing State.
Parameters
userIdThe user ID of the specified remote user.
muteSets 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.

◆ muteAllRemoteVideoStreams()

virtual int agora::rtc::IChannel::muteAllRemoteVideoStreams ( bool  mute)
pure virtual

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.
  • See recommended settings in Set the Subscribing State.
Parameters
muteSets 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.

◆ muteRemoteVideoStream()

virtual int agora::rtc::IChannel::muteRemoteVideoStream ( uid_t  userId,
bool  mute 
)
pure virtual

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

Note
  • Call this method after joining a channel.
  • See recommended settings in Set the Subscribing State.
Parameters
userIdThe user ID of the specified remote user.
muteSets 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.

◆ setRemoteVideoStreamType()

virtual int agora::rtc::IChannel::setRemoteVideoStreamType ( uid_t  userId,
REMOTE_VIDEO_STREAM_TYPE  streamType 
)
pure virtual

Sets the stream type of the remote video.

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

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

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

The method result returns in the onApiCallExecuted callback.

Note
You can call this method either before or after joining a channel. If you call both setRemoteVideoStreamType and setRemoteDefaultVideoStreamType, the SDK applies the settings in the setRemoteVideoStreamType method.
Parameters
userIdThe ID of the remote user sending the video stream.
streamTypeSets the video-stream type. See REMOTE_VIDEO_STREAM_TYPE.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setRemoteDefaultVideoStreamType()

virtual int agora::rtc::IChannel::setRemoteDefaultVideoStreamType ( REMOTE_VIDEO_STREAM_TYPE  streamType)
pure virtual

Sets the default stream type of remote videos.

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

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

The method result returns in the onApiCallExecuted callback.

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
streamTypeSets the default video-stream type. See REMOTE_VIDEO_STREAM_TYPE.
Returns
  • 0: Success.
  • < 0: Failure.

◆ createDataStream() [1/2]

virtual int agora::rtc::IChannel::createDataStream ( int *  streamId,
bool  reliable,
bool  ordered 
)
pure virtual

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 lifecycle of the IChannel.

Note
  • Do not set reliable as true while setting ordered as false.
  • Ensure that you call this method after joining a channel.
Parameters
[out]streamIdThe ID of the created data stream.
reliableSets whether or not the recipients are guaranteed to receive the data stream from the sender within five seconds:
  • true: The recipients receive the data stream from the sender within five seconds. If the recipient does not receive the data stream within five seconds, an error is reported to the application.
  • false: There is no guarantee that the recipients receive the data stream within five seconds and no error message is reported for any delay or missing data stream.
orderedSets whether or not the recipients receive the data stream in the sent order:
  • true: The recipients receive the data stream in the sent order.
  • false: The recipients do not receive the data stream in the sent order.
Returns
  • Returns 0: Success.
  • < 0: Failure.

◆ createDataStream() [2/2]

virtual int agora::rtc::IChannel::createDataStream ( int *  streamId,
DataStreamConfig config 
)
pure virtual

Creates a data stream.

Since
v3.3.0

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

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

Parameters
[out]streamIdThe ID of the created data stream.
configThe configurations for the data stream: DataStreamConfig.
Returns
  • 0: Creates the data stream successfully.
  • < 0: Fails to create the data stream.

◆ sendStreamMessage()

virtual int agora::rtc::IChannel::sendStreamMessage ( int  streamId,
const char *  data,
size_t  length 
)
pure virtual

Sends data stream messages to all users in a channel.

The SDK has the following restrictions on this method:

  • Up to 30 packets can be sent per second in a channel with each packet having a maximum size of 1 kB.
  • Each client can send up to 6 kB of data per second.
  • Each user can have up to five data streams simultaneously.

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

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

Note
  • This method applies only to the COMMUNICATION profile or to the hosts in the LIVE_BROADCASTING profile. If an audience in the LIVE_BROADCASTING profile calls this method, the audience may be switched to a host.
  • Ensure that you have created the data stream using createDataStream before calling this method.
Parameters
streamIdThe ID of the sent data stream, returned in the createDataStream method.
dataThe sent data.
lengthThe length of the sent data.
Returns
  • 0: Success.
  • < 0: Failure.

◆ addPublishStreamUrl()

virtual int agora::rtc::IChannel::addPublishStreamUrl ( const char *  url,
bool  transcodingEnabled 
)
pure virtual

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

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

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

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.

Note
  • Ensure that the user joins the channel before calling this method.
  • Ensure that you enable the Media Push service before using this function. See Prerequisites in the advanced guide Media Push.
  • This method adds only one stream CDN streaming URL each time it is called.
  • Agora supports pushing media streams in RTMPS protocol to the CDN only when you enable transcoding.
Parameters
urlThe CDN streaming URL in the RTMP or RTMPS format. The maximum length of this parameter is 1024 bytes. The CDN streaming URL must not contain special characters, such as Chinese language characters.
transcodingEnabledSets whether transcoding is enabled/disabled:
  • true: Enable transcoding. To transcode the audio or video streams when publishing them to CDN live, often used for combining the audio and video streams of multiple hosts in CDN live. If you set this parameter as true, ensure that you call the setLiveTranscoding method before this method.
  • false: Disable transcoding.
Returns

◆ removePublishStreamUrl()

virtual int agora::rtc::IChannel::removePublishStreamUrl ( const char *  url)
pure virtual

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 the addPublishStreamUrl method) from a CDN live stream. The SDK returns the result of this method call in the onStreamUnpublished callback.

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

Note
  • This method removes only one CDN streaming URL each time it is called.
  • The CDN streaming URL must not contain special characters, such as Chinese language characters.
Parameters
urlThe CDN streaming URL to be removed. The maximum length of this parameter is 1024 bytes.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setLiveTranscoding()

virtual int agora::rtc::IChannel::setLiveTranscoding ( const LiveTranscoding transcoding)
pure virtual

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

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 the setLiveTranscoding method to update the transcoding setting.

Note
  • Ensure that you enable the Media Push service before using this function. See Prerequisites in the advanced guide Media Push..
  • If you call the setLiveTranscoding method to set the transcoding setting for the first time, the SDK does not trigger the onTranscodingUpdated callback.
  • Ensure that you call this method after joining a channel.
  • Agora supports pushing media streams in RTMPS protocol to the CDN only when you enable transcoding.
Parameters
transcodingSets the CDN live audio/video transcoding settings. See LiveTranscoding.
Returns
  • 0: Success.
  • < 0: Failure.

◆ startRtmpStreamWithoutTranscoding()

virtual int agora::rtc::IChannel::startRtmpStreamWithoutTranscoding ( const char *  url)
pure virtual

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

◆ startRtmpStreamWithTranscoding()

virtual int agora::rtc::IChannel::startRtmpStreamWithTranscoding ( const char *  url,
const LiveTranscoding transcoding 
)
pure virtual

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
urlThe 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.
transcodingThe transcoding configuration for CDN live streaming. See 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.

◆ updateRtmpTranscoding()

virtual int agora::rtc::IChannel::updateRtmpTranscoding ( const LiveTranscoding transcoding)
pure virtual

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
transcodingThe transcoding configuration for CDN live streaming. See LiveTranscoding.
Returns
  • 0: Success.
  • < 0: Failure.

◆ stopRtmpStream()

virtual int agora::rtc::IChannel::stopRtmpStream ( const char *  url)
pure virtual

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

◆ addInjectStreamUrl()

virtual int agora::rtc::IChannel::addInjectStreamUrl ( const char *  url,
const InjectStreamConfig config 
)
pure virtual

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

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

The addInjectStreamUrl method call triggers the following callbacks:

  • The local client:
    • onStreamInjectedStatus , with the state of the injecting the online stream.
    • onUserJoined (uid: 666), if the method call is successful and the online media stream is injected into the channel.
  • The remote client:

    • onUserJoined (uid: 666), if the method call is successful and the online media stream is injected into the channel.
    Warning
    Agora will soon stop the service for injecting online media streams on the client. If you have not implemented this service, Agora recommends that you do not use it.
    Note
    • Ensure that you enable the RTMP Converter service before using this function. See Prerequisites in the advanced guide Media Push.
    • This method applies to the Native SDK v2.4.1 and later.
    • This method applies to the LIVE_BROADCASTING profile only.
    • You can inject only one media stream into the channel at the same time.
    • Ensure that you call this method after joining a channel.
    Parameters
    urlThe URL address to be added to the ongoing live streaming. Valid protocols are RTMP, HLS, and HTTP-FLV.
    • Supported audio codec type: AAC.
    • Supported video codec type: H264 (AVC).
    configThe InjectStreamConfig object that contains the configuration of the added voice or video stream.
    Returns
    • 0: Success.
    • < 0: Failure.
      • ERR_INVALID_ARGUMENT (-2): The injected URL does not exist. Call this method again to inject the stream and ensure that the URL is valid.
      • ERR_NOT_READY (-3): The user is not in the channel.
      • ERR_NOT_SUPPORTED (-4): The channel profile is not LIVE_BROADCASTING. Call the setChannelProfile method and set the channel profile to LIVE_BROADCASTING before calling this method.
      • ERR_NOT_INITIALIZED (-7): The SDK is not initialized. Ensure that the IChannel object is initialized before calling this method.

◆ removeInjectStreamUrl()

virtual int agora::rtc::IChannel::removeInjectStreamUrl ( const char *  url)
pure virtual

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

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

Warning
Agora will soon stop the service for injecting online media streams on the client. If you have not implemented this service, Agora recommends that you do not use it.
Note
If this method is called successfully, the SDK triggers the onUserOffline callback and returns a stream uid of 666.
Parameters
urlPointer to the URL address of the added stream to be removed.
Returns
  • 0: Success.
  • < 0: Failure.

◆ startChannelMediaRelay()

virtual int agora::rtc::IChannel::startChannelMediaRelay ( const ChannelMediaRelayConfiguration configuration)
pure virtual

Starts to relay media streams across channels.

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.

Note
  • Call this method after the joinChannel method.
  • This method takes effect only when you are 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.
  • Contact sales.nosp@m.-us@.nosp@m.agora.nosp@m..io before implementing this function.
  • We do not support string user accounts in this API.
Parameters
configurationThe configuration of the media stream relay: ChannelMediaRelayConfiguration.
Returns
  • 0: Success.
  • < 0: Failure.

◆ updateChannelMediaRelay()

virtual int agora::rtc::IChannel::updateChannelMediaRelay ( const ChannelMediaRelayConfiguration configuration)
pure virtual

Updates the channels for media stream relay.

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

After a successful method call, the SDK triggers the 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.
Parameters
configurationThe media stream relay configuration: ChannelMediaRelayConfiguration.
Returns
  • 0: Success.
  • < 0: Failure.

◆ pauseAllChannelMediaRelay()

virtual int agora::rtc::IChannel::pauseAllChannelMediaRelay ( )
pure virtual

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.

◆ resumeAllChannelMediaRelay()

virtual int agora::rtc::IChannel::resumeAllChannelMediaRelay ( )
pure virtual

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.

◆ stopChannelMediaRelay()

virtual int agora::rtc::IChannel::stopChannelMediaRelay ( )
pure virtual

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

Note
If the method call fails, the SDK triggers the onChannelMediaRelayStateChanged callback with the RELAY_ERROR_SERVER_NO_RESPONSE (2) or RELAY_ERROR_SERVER_CONNECTION_LOST (8) error code. You can leave the channel by calling the leaveChannel method, and the media stream relay automatically stops.
Returns
  • 0: Success.
  • < 0: Failure.

◆ getConnectionState()

virtual CONNECTION_STATE_TYPE agora::rtc::IChannel::getConnectionState ( )
pure virtual

Gets the current connection state of the SDK.

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

◆ enableRemoteSuperResolution() [1/2]

virtual int agora::rtc::IChannel::enableRemoteSuperResolution ( uid_t  userId,
bool  enable 
)
pure virtual

Enables/Disables the super resolution feature for a remote user's video. (beta feature)

Deprecated:
This method is deprecated as of v3.7.1. Use enableRemoteSuperResolution [2/2] instead.
Since
v3.5.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.

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 a certain range. If the local user use super resolution on Android, the original resolution of the remote user's video cannot exceed 640 × 360 pixels; if the local user use 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 onWarning callback and returns the corresponding warning codes:
Note
  • This method is for Android and iOS only.
  • Before calling this method, ensure that you have integrated the following dynamic library into your project:
    • Android: libagora_super_resolution_extension.so
    • iOS: AgoraSuperResolutionExtension.xcframework
  • 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 MediaPad M6, MatePad 10.8
    • iOS (iOS 12.0 or later):
      • iPhone XR
      • iPhone XS
      • iPhone XS Max
      • iPhone 11
      • iPhone 11 Pro
      • iPhone 11 Pro Max
      • iPhone 12
      • iPhone 12 mini
      • iPhone 12 Pro
      • iPhone 12 Pro Max
      • iPhone 12 SE (2nd generation)
      • iPad Pro 11-inch (3rd generation)
      • iPad Pro 12.9-inch (3rd generation)
      • iPad Air (3rd generation)
      • iPad Air (4th generation)
Parameters
userIdThe user ID of the remote user.
enableDetermines whether to enable super resolution for the remote user's video:
  • true: Enable super resolution.
  • false: Disable super resolution.
Returns
  • 0: Success.
  • < 0: Failure.
    • -157 (ERR_MODULE_NOT_FOUND): The dynamic library for super resolution is not integrated.

◆ enableRemoteSuperResolution() [2/2]

virtual int agora::rtc::IChannel::enableRemoteSuperResolution ( bool  enabled,
SR_MODE  mode,
uid_t  userId 
)
pure virtual

Enables/Disables the super-resolution feature 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 following dynamic libraries into your project:
  • Android: libagora_super_resolution_extension.so
  • iOS/macOS: AgoraSuperResolutionExtension.xcframework
  • Windows: libagora_super_resolution_extension.dll
Warning
The super resolution feature requires extra system resources. To balance the visual experience and system consumption, the SDK poses the following restrictions:
Parameters
enabledDetermines whether to enable super resolution for the remote user's video:
  • true: Enable super resolution.
  • false: Disable super resolution.
modeThe mode of super resolution. See SR_MODE.
userIdThe 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.