|
| 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 |
| |
| 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
-
| token | The 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. |
| uid | The user ID. A 32-bit unsigned integer with a value ranging from 1 to (232-1). This parameter must be unique. If uid is not assigned (or set as 0), the SDK assigns a uid and reports it in the onJoinChannelSuccess callback. The app must maintain this user ID. |
| options | The channel media options: ChannelMediaOptions |
- Returns
- 0(ERR_OK): Success.
- < 0: Failure.
- -2(ERR_INVALID_ARGUMENT): The parameter is invalid.
- -3(ERR_NOT_READY): The SDK fails to be initialized. You can try re-initializing the SDK.
- -5(ERR_REFUSED): The request is rejected. 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.
| 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
-
| token | The token generated at your server. See Authenticate Your Users with Tokens. |
| userAccount | The 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: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
|
| options | The channel media options: agora::rtc::ChannelMediaOptions::ChannelMediaOptions “ChannelMediaOptions”. |
- Returns
- 0: Success.
- < 0: Failure.
| 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.
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
-
| callId | The current call ID. |
- Returns
- 0: Success.
- < 0: Failure.
| 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
-
| encryptionMode | The set encryption mode:
- "aes-128-xts": (Default) 128-bit AES encryption, XTS mode.
- "aes-128-ecb": 128-bit AES encryption, ECB mode.
- "aes-256-xts": 256-bit AES encryption, XTS mode.
- "": When encryptionMode is set as NULL, the encryption mode is set as "aes-128-xts" by default.
|
- Returns
- 0: Success.
- < 0: Failure.
| 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
-
| enabled | Whether to enable the built-in encryption:
- true: Enable the built-in encryption.
- false: Disable the built-in encryption.
|
| config | Configurations of built-in encryption schemas. See EncryptionConfig. |
- Returns
- 0: Success.
- < 0: Failure.
- -2(ERR_INVALID_ARGUMENT): An invalid parameter is used. Set the parameter with a valid value.
- -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.
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
-
- 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.
| 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
-
| mute | Sets whether to stop publishing the local audio stream.
- true: Stop publishing the local audio stream.
- false: Resume publishing the local audio stream.
|
- Returns
- 0: Success.
- < 0: Failure.
-5 (ERR_REFUSED): The request is rejected.
| 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
-
| mute | Sets whether to stop publishing the local video stream.
- true: Stop publishing the local video stream.
- false: Resume publishing the local video stream.
|
- Returns
- 0: Success.
- < 0: Failure.
-5 (ERR_REFUSED): The request is rejected.
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
-
| userId | The ID of the remote user sending the video stream. |
| streamType | Sets the video-stream type. See REMOTE_VIDEO_STREAM_TYPE. |
- Returns
- 0: Success.
- < 0: Failure.
Sets the 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
-
- Returns
- 0: Success.
- < 0: Failure.
| 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
-
| streamId | The ID of the sent data stream, returned in the createDataStream method. |
| data | The sent data. |
| length | The length of the sent data. |
- Returns
- 0: Success.
- < 0: Failure.
| 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
-
| url | The address of the CDN live streaming. The format is RTMP or RTMPS. The character length cannot exceed 1024 bytes. Special characters such as Chinese characters are not supported. |
- Returns
- 0: Success.
- < 0: Failure.
ERR_INVALID_ARGUMENT(-2): url is null or the string length is 0.ERR_NOT_INITIALIZED(-7): The SDK is not initialized before calling this method.
| 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
-
| url | The address of the CDN live streaming. The format is RTMP or RTMPS. The character length cannot exceed 1024 bytes. Special characters such as Chinese characters are not supported. |
| transcoding | The transcoding configuration for CDN live streaming. 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.
| 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
-
| url | The address of the CDN live streaming. The format is RTMP or RTMPS. The character length cannot exceed 1024 bytes. Special characters such as Chinese characters are not supported. |
- Returns
- 0: Success.
- < 0: Failure.
| 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.
| 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
-
| userId | The user ID of the remote user. |
| enable | Determines whether to enable super resolution for the remote user's video:
- true: Enable super resolution.
- false: Disable super resolution.
|
- Returns
- 0: Success.
- < 0: Failure.
-157 (ERR_MODULE_NOT_FOUND): The dynamic library for super resolution is not integrated.
| 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
-
| enabled | Determines whether to enable super resolution for the remote user's video:
- true: Enable super resolution.
- false: Disable super resolution.
|
| mode | The mode of super resolution. See SR_MODE. |
| userId | The user ID of the remote user. This parameter only applies when mode is set as SR_MODE_MANUAL(0). |
- Returns
- 0: Success.
- < 0: Failure.
-157 (ERR_MODULE_NOT_FOUND): The dynamic library for super resolution is not integrated.
1.8.15