diff --git a/Android/APIExample/app/src/main/java/io/agora/api/example/MainApplication.java b/Android/APIExample/app/src/main/java/io/agora/api/example/MainApplication.java index 877dc71e4..2aa2be04d 100644 --- a/Android/APIExample/app/src/main/java/io/agora/api/example/MainApplication.java +++ b/Android/APIExample/app/src/main/java/io/agora/api/example/MainApplication.java @@ -26,6 +26,9 @@ private void initExamples() { try { Set packageName = ClassUtils.getFileNameByPackageName(this, "io.agora.api.example.examples"); for (String name : packageName) { + if (android.os.Build.VERSION.SDK_INT < android.os.Build.VERSION_CODES.N && name.contains("io.agora.api.example.examples.advanced.ARCore")) { + continue; + } Class aClass = Class.forName(name); Annotation[] declaredAnnotations = aClass.getAnnotations(); for (Annotation annotation : declaredAnnotations) { diff --git a/Android/APIExample/app/src/main/java/io/agora/api/example/examples/advanced/ProcessRawData.java b/Android/APIExample/app/src/main/java/io/agora/api/example/examples/advanced/ProcessRawData.java index 0bbb444e5..65cfb4bd5 100644 --- a/Android/APIExample/app/src/main/java/io/agora/api/example/examples/advanced/ProcessRawData.java +++ b/Android/APIExample/app/src/main/java/io/agora/api/example/examples/advanced/ProcessRawData.java @@ -403,7 +403,7 @@ public void onCaptureVideoFrame(byte[] data, int frameType, int width, int heigh return; } Bitmap bitmap = YUVUtils.i420ToBitmap(width, height, rotation, bufferLength, data, yStride, uStride, vStride); - Bitmap bmp = YUVUtils.blur(getContext(), bitmap, 4); + Bitmap bmp = YUVUtils.blur(getContext(), bitmap, 8f); System.arraycopy(YUVUtils.bitmapToI420(width, height, bmp), 0, data, 0, bufferLength); } @@ -412,7 +412,7 @@ public void onRenderVideoFrame(int uid, byte[] data, int frameType, int width, i if (blur) { return; } - Bitmap bmp = YUVUtils.blur(getContext(), YUVUtils.i420ToBitmap(width, height, rotation, bufferLength, data, yStride, uStride, vStride), 4); + Bitmap bmp = YUVUtils.blur(getContext(), YUVUtils.i420ToBitmap(width, height, rotation, bufferLength, data, yStride, uStride, vStride), 8f); System.arraycopy(YUVUtils.bitmapToI420(width, height, bmp), 0, data, 0, bufferLength); } diff --git a/Android/APIExample/lib-raw-data/src/main/cpp/include/AgoraBase.h b/Android/APIExample/lib-raw-data/src/main/cpp/include/AgoraBase.h index ecb0c5a3b..654bb9cd5 100644 --- a/Android/APIExample/lib-raw-data/src/main/cpp/include/AgoraBase.h +++ b/Android/APIExample/lib-raw-data/src/main/cpp/include/AgoraBase.h @@ -150,7 +150,7 @@ enum WARN_CODE_TYPE /** 111: A timeout occurs when switching to the live video. */ WARN_SWITCH_LIVE_VIDEO_TIMEOUT = 111, - /** 118: A timeout occurs when setting the client role in the live interactive streaming profile. + /** 118: A timeout occurs when setting the client role in the interactive live streaming profile. */ WARN_SET_CLIENT_ROLE_TIMEOUT = 118, /** 121: The ticket to open the channel is invalid. @@ -177,19 +177,19 @@ enum WARN_CODE_TYPE /** 1014: Audio Device Module: A warning occurs in the playback device. */ WARN_ADM_RUNTIME_PLAYOUT_WARNING = 1014, - /** 1016: Audio Device Module: a warning occurs in the recording device. + /** 1016: Audio Device Module: A warning occurs in the audio capturing device. */ WARN_ADM_RUNTIME_RECORDING_WARNING = 1016, - /** 1019: Audio Device Module: no valid audio data is recorded. + /** 1019: Audio Device Module: No valid audio data is captured. */ WARN_ADM_RECORD_AUDIO_SILENCE = 1019, /** 1020: Audio device module: The audio playback frequency is abnormal, which may cause audio freezes. This abnormality is caused by high CPU usage. Agora recommends stopping other apps. */ WARN_ADM_PLAYOUT_MALFUNCTION = 1020, - /** 1021: Audio device module: the audio recording frequency is abnormal, which may cause audio freezes. This abnormality is caused by high CPU usage. Agora recommends stopping other apps. + /** 1021: Audio device module: the audio capturing frequency is abnormal, which may cause audio freezes. This abnormality is caused by high CPU usage. Agora recommends stopping other apps. */ WARN_ADM_RECORD_MALFUNCTION = 1021, - /** 1025: The audio playback or recording is interrupted by system events (such as a phone call). + /** 1025: The audio playback or capturing is interrupted by system events (such as a phone call). */ WARN_ADM_CALL_INTERRUPTION = 1025, /** 1029: During a call, the audio session category should be set to @@ -199,13 +199,13 @@ enum WARN_CODE_TYPE * AVAudioSessionCategoryPlayAndRecord. */ WARN_ADM_IOS_CATEGORY_NOT_PLAYANDRECORD = 1029, - /** 1031: Audio Device Module: The recorded audio voice is too low. + /** 1031: Audio Device Module: The captured audio voice is too low. */ WARN_ADM_RECORD_AUDIO_LOWLEVEL = 1031, /** 1032: Audio Device Module: The playback audio voice is too low. */ WARN_ADM_PLAYOUT_AUDIO_LOWLEVEL = 1032, - /** 1033: Audio device module: The audio recording device is occupied. + /** 1033: Audio device module: The audio capturing device is occupied. */ WARN_ADM_RECORD_AUDIO_IS_ACTIVE = 1033, /** 1040: Audio device module: An exception occurs with the audio drive. @@ -215,12 +215,12 @@ enum WARN_CODE_TYPE * - Update the sound card drive. */ WARN_ADM_WINDOWS_NO_DATA_READY_EVENT = 1040, - /** 1042: Audio device module: The audio recording device is different from the audio playback device, - * which may cause echoes problem. Agora recommends using the same audio device to record and playback + /** 1042: Audio device module: The audio capturing device is different from the audio playback device, + * which may cause echoes problem. Agora recommends using the same audio device to capture and playback * audio. */ WARN_ADM_INCONSISTENT_AUDIO_DEVICE = 1042, - /** 1051: (Communication profile only) Audio processing module: A howling sound is detected when recording the audio data. + /** 1051: (Communication profile only) Audio processing module: A howling sound is detected when capturing the audio data. */ WARN_APM_HOWLING = 1051, /** 1052: Audio Device Module: The device is in the glitch state. @@ -300,7 +300,7 @@ enum ERROR_CODE_TYPE /** 11: The request is canceled. This is for internal SDK use only, and it does not return to the application through any method or callback. */ ERR_CANCELED = 11, - /** 12: The method is called too often. This is for internal SDK use only, and it does not return to the application through any method or callback. + /** 12: The method is called too often. */ ERR_TOO_OFTEN = 12, /** 13: The SDK fails to bind to the network socket. This is for internal SDK use only, and it does not return to the application through any method or callback. @@ -395,7 +395,7 @@ enum ERROR_CODE_TYPE /** 120: Decryption fails. The user may have used a different encryption password to join the channel. Check your settings or try rejoining the channel. */ ERR_DECRYPTION_FAILED = 120, - /** 123: The user is banned by the server. This error occurs when the user is kicked off the channel from the server. + /** 123: The user is banned by the server. This error occurs when the user is kicked out the channel from the server. */ ERR_CLIENT_IS_BANNED_BY_SERVER = 123, /** 124: Incorrect watermark file parameter. @@ -437,9 +437,23 @@ enum ERROR_CODE_TYPE /** 155: The server fails to find the stream. */ ERR_PUBLISH_STREAM_NOT_FOUND = 155, - /** 156: The format of the RTMP stream URL is not supported. Check whether the URL format is correct. + /** 156: The format of the RTMP or RTMPS stream URL is not supported. Check whether the URL format is correct. */ ERR_PUBLISH_STREAM_FORMAT_NOT_SUPPORTED = 156, + /** 157: The necessary dynamical library is not integrated. For example, if you call + * the \ref agora::rtc::IRtcEngine::enableDeepLearningDenoise "enableDeepLearningDenoise" but do not integrate the dynamical + * library for the deep-learning noise reduction into your project, the SDK reports this error code. + * + */ + ERR_MODULE_NOT_FOUND = 157, + /// @cond + /** 158: The dynamical library for the super-resolution algorithm is not integrated. + * When you call the \ref agora::rtc::IRtcEngine::enableRemoteSuperResolution "enableRemoteSuperResolution" method but + * do not integrate the dynamical library for the super-resolution algorithm + * into your project, the SDK reports this error code. + */ + ERR_MODULE_SUPER_RESOLUTION_NOT_FOUND = 158, + /// @endcond //signaling: 400~600 ERR_LOGOUT_OTHER = 400, // @@ -512,19 +526,19 @@ enum ERROR_CODE_TYPE /** 1010: Audio Device Module: An error occurs in stopping the playback device. */ ERR_ADM_STOP_PLAYOUT = 1010, - /** 1011: Audio Device Module: An error occurs in initializing the recording device. + /** 1011: Audio Device Module: An error occurs in initializing the capturing device. */ ERR_ADM_INIT_RECORDING = 1011, - /** 1012: Audio Device Module: An error occurs in starting the recording device. + /** 1012: Audio Device Module: An error occurs in starting the capturing device. */ ERR_ADM_START_RECORDING = 1012, - /** 1013: Audio Device Module: An error occurs in stopping the recording device. + /** 1013: Audio Device Module: An error occurs in stopping the capturing device. */ ERR_ADM_STOP_RECORDING = 1013, /** 1015: Audio Device Module: A playback error occurs. Check your playback device and try rejoining the channel. */ ERR_ADM_RUNTIME_PLAYOUT_ERROR = 1015, - /** 1017: Audio Device Module: A recording error occurs. + /** 1017: Audio Device Module: A capturing error occurs. */ ERR_ADM_RUNTIME_RECORDING_ERROR = 1017, /** 1018: Audio Device Module: Fails to record. @@ -548,8 +562,8 @@ enum ERROR_CODE_TYPE /** 1101: Audio device module: A fatal exception occurs. */ ERR_ADM_ANDROID_JNI_JAVA_RESOURCE = 1101, - /** 1108: Audio device module: The recording frequency is lower than 50. - * 0 indicates that the recording is not yet started. We recommend + /** 1108: Audio device module: The capturing frequency is lower than 50. + * 0 indicates that the capturing is not yet started. We recommend * checking your recording permission. */ ERR_ADM_ANDROID_JNI_NO_RECORD_FREQUENCY = 1108, @@ -646,7 +660,7 @@ enum ERROR_CODE_TYPE * - Replace the device. */ ERR_ADM_WIN_CORE_RENDER_NOT_STARTUP = 1320, /** 1322: Audio device module: No audio sampling device is available. - * Solutions: Plug in a proper recording device. */ + * Solutions: Plug in a proper capturing device. */ ERR_ADM_WIN_CORE_NO_RECORDING_DEVICE = 1322, /** 1323: Audio device module: No audio playout device is available. * Solutions: Plug in a proper playback device.*/ @@ -693,7 +707,7 @@ enum ERROR_CODE_TYPE * - Reboot the system. * - Upgrade your audio card driver.*/ ERR_ADM_WIN_WAVE_START_PLAYOUT = 1358, - /** 1359: Audio Device Module: No recording device exists. + /** 1359: Audio Device Module: No capturing device exists. */ ERR_ADM_NO_RECORDING_DEVICE = 1359, /** 1360: Audio Device Module: No playback device exists. @@ -727,7 +741,7 @@ enum ERROR_CODE_TYPE ERR_VCM_ENCODER_SET_ERROR = 1603, }; - /** Output log filter level. */ +/** Output log filter level. */ enum LOG_FILTER_TYPE { /** 0: Do not output any log information. */ @@ -750,6 +764,24 @@ enum LOG_FILTER_TYPE LOG_FILTER_MASK = 0x80f, /// @endcond }; +/** The output log level of the SDK. + * + * @since v3.3.0 + */ +enum class LOG_LEVEL { + /** 0: Do not output any log. */ + LOG_LEVEL_NONE = 0x0000, + /** 0x0001: (Default) Output logs of the FATAL, ERROR, WARN and INFO level. We recommend setting your log filter as this level. + */ + LOG_LEVEL_INFO = 0x0001, + /** 0x0002: Output logs of the FATAL, ERROR and WARN level. + */ + LOG_LEVEL_WARN = 0x0002, + /** 0x0004: Output logs of the FATAL and ERROR level. */ + LOG_LEVEL_ERROR = 0x0004, + /** 0x0008: Output logs of the FATAL level. */ + LOG_LEVEL_FATAL = 0x0008, +}; } // namespace agora #endif diff --git a/Android/APIExample/lib-raw-data/src/main/cpp/include/IAgoraMediaEngine.h b/Android/APIExample/lib-raw-data/src/main/cpp/include/IAgoraMediaEngine.h index e44fb6c43..c740a72af 100644 --- a/Android/APIExample/lib-raw-data/src/main/cpp/include/IAgoraMediaEngine.h +++ b/Android/APIExample/lib-raw-data/src/main/cpp/include/IAgoraMediaEngine.h @@ -59,12 +59,12 @@ class IAudioFrameObserver { }; public: - /** Retrieves the recorded audio frame. + /** Retrieves the captured audio frame. @param audioFrame Pointer to AudioFrame. @return - - true: Valid buffer in AudioFrame, and the recorded audio frame is sent out. - - false: Invalid buffer in AudioFrame, and the recorded audio frame is discarded. + - true: Valid buffer in AudioFrame, and the captured audio frame is sent out. + - false: Invalid buffer in AudioFrame, and the captured audio frame is discarded. */ virtual bool onRecordAudioFrame(AudioFrame& audioFrame) = 0; /** Retrieves the audio playback frame for getting the audio. @@ -75,15 +75,15 @@ class IAudioFrameObserver { - false: Invalid buffer in AudioFrame, and the audio playback frame is discarded. */ virtual bool onPlaybackAudioFrame(AudioFrame& audioFrame) = 0; - /** Retrieves the mixed recorded and playback audio frame. + /** Retrieves the mixed captured and playback audio frame. @note This callback only returns the single-channel data. @param audioFrame Pointer to AudioFrame. @return - - true: Valid buffer in AudioFrame and the mixed recorded and playback audio frame is sent out. - - false: Invalid buffer in AudioFrame and the mixed recorded and playback audio frame is discarded. + - true: Valid buffer in AudioFrame and the mixed captured and playback audio frame is sent out. + - false: Invalid buffer in AudioFrame and the mixed captured and playback audio frame is discarded. */ virtual bool onMixedAudioFrame(AudioFrame& audioFrame) = 0; /** Retrieves the audio frame of a specified user before mixing. @@ -93,8 +93,8 @@ class IAudioFrameObserver { @param uid The user ID @param audioFrame Pointer to AudioFrame. @return - - true: Valid buffer in AudioFrame, and the mixed recorded and playback audio frame is sent out. - - false: Invalid buffer in AudioFrame, and the mixed recorded and playback audio frame is discarded. + - true: Valid buffer in AudioFrame, and the mixed captured and playback audio frame is sent out. + - false: Invalid buffer in AudioFrame, and the mixed captured and playback audio frame is discarded. */ virtual bool onPlaybackAudioFrameBeforeMixing(unsigned int uid, AudioFrame& audioFrame) = 0; diff --git a/Android/APIExample/lib-raw-data/src/main/cpp/include/IAgoraRtcChannel.h b/Android/APIExample/lib-raw-data/src/main/cpp/include/IAgoraRtcChannel.h index f354183dc..8527078ea 100644 --- a/Android/APIExample/lib-raw-data/src/main/cpp/include/IAgoraRtcChannel.h +++ b/Android/APIExample/lib-raw-data/src/main/cpp/include/IAgoraRtcChannel.h @@ -10,29 +10,6 @@ namespace agora { namespace rtc { -/** The channel media options. */ -struct ChannelMediaOptions { - /** Determines whether to subscribe to audio streams when the user joins the channel: - - true: (Default) Subscribe. - - false: Do not subscribe. - - This member serves a similar function to the \ref agora::rtc::IChannel::muteAllRemoteAudioStreams "muteAllRemoteAudioStreams" method. After joining the channel, - you can call the `muteAllRemoteAudioStreams` method to set whether to subscribe to audio streams in the channel. - */ - bool autoSubscribeAudio; - /** Determines whether to subscribe to video streams when the user joins the channel: - - true: (Default) Subscribe. - - false: Do not subscribe. - - This member serves a similar function to the \ref agora::rtc::IChannel::muteAllRemoteVideoStreams "muteAllRemoteVideoStreams" method. After joining the channel, - you can call the `muteAllRemoteVideoStreams` method to set whether to subscribe to video streams in the channel. - */ - bool autoSubscribeVideo; - ChannelMediaOptions() - : autoSubscribeAudio(true) - , autoSubscribeVideo(true) - {} -}; /** The IChannel class. */ class IChannel; /** The IChannelEventHandler class. */ @@ -102,7 +79,7 @@ class IChannelEventHandler (void)rtcChannel; (void)stats; } - /** Occurs when the user role switches in the live interactive streaming. For example, from a host to an audience or vice versa. + /** Occurs when the user role switches in the interactive live streaming. For example, from a host to an audience or vice versa. This callback notifies the application of a user role switch when the application calls the \ref IChannel::setClientRole "setClientRole" method. @@ -481,15 +458,15 @@ class IChannelEventHandler (void)code; } /** - Occurs when the state of the RTMP streaming changes. + Occurs when the state of the RTMP or RTMPS streaming changes. The SDK triggers this callback to report the result of the local user calling the \ref agora::rtc::IChannel::addPublishStreamUrl "addPublishStreamUrl" or \ref agora::rtc::IChannel::removePublishStreamUrl "removePublishStreamUrl" method. - This callback indicates the state of the RTMP streaming. When exceptions occur, you can troubleshoot issues by referring to the detailed error descriptions in the *errCode* parameter. + This callback indicates the state of the RTMP or RTMPS streaming. When exceptions occur, you can troubleshoot issues by referring to the detailed error descriptions in the *errCode* parameter. @param rtcChannel IChannel - @param url The RTMP URL address. - @param state The RTMP streaming state. See: #RTMP_STREAM_PUBLISH_STATE. + @param url The CDN streaming URL. + @param state The RTMP or RTMPS streaming state. See: #RTMP_STREAM_PUBLISH_STATE. @param errCode The detailed error information for streaming. See: #RTMP_STREAM_PUBLISH_ERROR. */ virtual void onRtmpStreamingStateChanged(IChannel *rtcChannel, const char *url, RTMP_STREAM_PUBLISH_STATE state, RTMP_STREAM_PUBLISH_ERROR errCode) { @@ -499,12 +476,12 @@ class IChannelEventHandler (RTMP_STREAM_PUBLISH_ERROR) errCode; } - /** Reports events during the RTMP streaming. + /** Reports events during the RTMP or RTMPS streaming. * * @since v3.1.0 * * @param rtcChannel IChannel - * @param url The RTMP streaming URL. + * @param url The RTMP or RTMPS streaming URL. * @param eventCode The event code. See #RTMP_STREAMING_EVENT */ virtual void onRtmpStreamingEvent(IChannel *rtcChannel, const char* url, RTMP_STREAMING_EVENT eventCode) { @@ -524,7 +501,7 @@ class IChannelEventHandler virtual void onTranscodingUpdated(IChannel *rtcChannel) { (void)rtcChannel; } - /** Occurs when a voice or video stream URL address is added to the live interactive streaming. + /** Occurs when a voice or video stream URL address is added to the interactive live streaming. @param rtcChannel IChannel @param url The URL address of the externally injected stream. @@ -629,6 +606,8 @@ class IChannel | Users can join multiple channels simultaneously by creating multiple `IChannel` objects and calling the `joinChannel` method of each object. | Users can join only one channel. | | By default, the SDK does not publish any stream after the user joins the channel. You need to call the publish method to do that. | By default, the SDK publishes streams once the user joins the channel. | + 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. + @note - If you are already in a channel, you cannot rejoin it with the same `uid`. - We recommend using different UIDs for different channels. @@ -662,13 +641,15 @@ class IChannel - The local client: \ref agora::rtc::IRtcEngineEventHandler::onLocalUserRegistered "onLocalUserRegistered" and \ref agora::rtc::IChannelEventHandler::onJoinChannelSuccess "onJoinChannelSuccess" . - The remote client: \ref agora::rtc::IChannelEventHandler::onUserJoined "onUserJoined" and \ref agora::rtc::IRtcEngineEventHandler::onUserInfoUpdated "onUserInfoUpdated" , if the user joining the channel is in the `COMMUNICATION` profile, or is a host in the `LIVE_BROADCASTING` profile. + 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. + @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. @param token The token generated at your server: - For low-security requirements: You can use the temporary token generated at Console. For details, see [Get a temporary toke](https://docs.agora.io/en/Voice/token?platform=All%20Platforms#get-a-temporary-token). - For high-security requirements: Set it as the token generated at your server. For details, see [Get a token](https://docs.agora.io/en/Voice/token?platform=All%20Platforms#get-a-token). - @param userAccount The user account. The maximum length of this parameter is 255 bytes. Ensure that you set this parameter and do not set it as null. Supported character scopes are: + @param 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. @@ -715,7 +696,7 @@ class IChannel 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 live interactive streaming channel, only a host can call this method. To switch the client role, call \ref agora::rtc::IChannel::setClientRole "setClientRole" of the current `IChannel` object. + - In the interactive live streaming channel, only a host can call this method. To switch the client role, call \ref agora::rtc::IChannel::setClientRole "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*. @return @@ -829,8 +810,8 @@ class IChannel * All users in the same channel must use the same encryption mode and encryption key. Once all users leave the channel, the encryption key of this channel is automatically cleared. * * @note - * - If you enable the built-in encryption, you cannot use the RTMP streaming function. - * - Agora supports four encryption modes. If you choose an encryption mode (excepting `SM4_128_ECB` mode), you need to add an external encryption library when integrating the Android and iOS SDK. See the advanced guide *Channel Encryption*. + * - If you enable the built-in encryption, you cannot use the RTMP or RTMPS streaming function. + * - You need to add an external encryption library when integrating the Android and iOS SDK. See the advanced guide *Channel Encryption*. * * @param enabled Whether to enable the built-in encryption: * - true: Enable the built-in encryption. @@ -842,7 +823,7 @@ class IChannel * - < 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. + * - -7(ERR_NOT_INITIALIZED): The SDK is not initialized. Initialize the `IChannel` instance before calling this method. */ virtual int enableEncryption(bool enabled, const EncryptionConfig& config) = 0; /** Registers a packet observer. @@ -895,21 +876,20 @@ class IChannel - < 0: Failure. */ virtual int setClientRole(CLIENT_ROLE_TYPE role) = 0; - /// @cond - /** Sets the role of a user in a live interactive streaming. + + /** Sets the role of a user in interactive live streaming. * * @since v3.2.0 * * You can call this method either before or after joining the channel to set the user role as audience or host. If * you call this method to switch the user role after joining the channel, the SDK triggers the following callbacks: - * - The local client: \ref IRtcChannelEventHandler::onClientRoleChanged "onClientRoleChanged". - * - The remote client: \ref IRtcChannelEventHandler::onUserJoined "onUserJoined" - * or \ref IRtcChannelEventHandler::onUserOffline "onUserOffline". + * - The local client: \ref IChannelEventHandler::onClientRoleChanged "onClientRoleChanged". + * - The remote client: \ref IChannelEventHandler::onUserJoined "onUserJoined" + * or \ref IChannelEventHandler::onUserOffline "onUserOffline". * * @note - * - This method applies to the `LIVE_BROADCASTING` profile only (when the `profile` parameter in - * \ref IRtcChannel::setChannelProfile "setChannelProfile" is set as `CHANNEL_PROFILE_LIVE_BROADCASTING`). - * - The difference between this method and \ref IRtcChannel::setClientRole(CLIENT_ROLE_TYPE) "setClientRole1" is that + * - This method applies to the `LIVE_BROADCASTING` profile only. + * - The difference between this method and \ref IChannel::setClientRole(CLIENT_ROLE_TYPE) "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. @@ -917,15 +897,7 @@ class IChannel * role. For example, an audience can choose to receive remote streams with low latency or ultra low latency. Levels * affect prices. * - * **Example** - * ```cpp - * ClientRoleOptions options; - * options.audienceLatencyLevel = AUDIENCE_LATENCY_LEVEL_ULTRA_LOW_LATENCY; - * options.audienceLatencyLevel = AUDIENCE_LATENCY_LEVEL_LOW_LATENCY; - * agoraChannel->setClientRole(role, options); - * ``` - * - * @param role The role of a user in a live interactive streaming. See #CLIENT_ROLE_TYPE. + * @param role The role of a user in interactive live streaming. See #CLIENT_ROLE_TYPE. * @param options The detailed options of a user, including user level. See ClientRoleOptions. * * @return @@ -936,7 +908,7 @@ class IChannel * - -7(ERR_NOT_INITIALIZED): The SDK is not initialized. */ virtual int setClientRole(CLIENT_ROLE_TYPE role, const ClientRoleOptions& options) = 0; - /// @endcond + /** Prioritizes a remote user's stream. * * The SDK ensures the high-priority user gets the best possible stream quality. @@ -997,58 +969,69 @@ class IChannel - < 0: Failure. */ virtual int setRemoteRenderMode(uid_t userId, RENDER_MODE_TYPE renderMode, VIDEO_MIRROR_MODE_TYPE mirrorMode) = 0; - /** Sets whether to receive all remote audio streams by default. - - You can call this method either before or after joining a channel. If you call `setDefaultMuteAllRemoteAudioStreams (true)` after joining a channel, the remote audio streams of all subsequent users are not received. - - @note If you want to resume receiving the audio stream, call \ref agora::rtc::IChannel::muteRemoteAudioStream "muteRemoteAudioStream (false)", - and specify the ID of the remote user whose audio stream you want to receive. - To receive the audio streams of multiple remote users, call `muteRemoteAudioStream (false)` as many times. - Calling `setDefaultMuteAllRemoteAudioStreams (false)` resumes receiving the audio streams of subsequent users only. - - @param mute Sets whether to receive/stop receiving all remote users' audio streams by default: - - true: Stops receiving all remote users' audio streams by default. - - false: (Default) Receives all remote users' audio streams by default. - - @return - - 0: Success. - - < 0: Failure. + /** 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 \ref IRtcEngine::setDefaultMuteAllRemoteAudioStreams "setDefaultMuteAllRemoteAudioStreams" (true), do the following: + * - If you need to resume subscribing to the audio stream of a specified user, call \ref IRtcEngine::muteRemoteAudioStream "muteRemoteAudioStream" (false), and specify the user ID. + * - If you need to resume subscribing to the audio streams of multiple remote users, call \ref IRtcEngine::muteRemoteAudioStream "muteRemoteAudioStream" (false) multiple times. + * + * @param mute Sets whether to stop subscribing to the audio streams of all remote users by default. + * - true: Stop subscribing to the audio streams of all remote users by default. + * - false: (Default) Resume subscribing to the audio streams of all remote users by default. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int setDefaultMuteAllRemoteAudioStreams(bool mute) = 0; - /** Sets whether to receive all remote video streams by default. - - You can call this method either before or after joining a channel. If you - call `setDefaultMuteAllRemoteVideoStreams (true)` after joining a channel, - the remote video streams of all subsequent users are not received. - - @note If you want to resume receiving the video stream, call - \ref agora::rtc::IChannel::muteRemoteVideoStream "muteRemoteVideoStream (false)", - and specify the ID of the remote user whose video stream you want to receive. - To receive the video streams of multiple remote users, call `muteRemoteVideoStream (false)` - as many times. Calling `setDefaultMuteAllRemoteVideoStreams (false)` resumes - receiving the video streams of subsequent users only. - - @param mute Sets whether to receive/stop receiving all remote users' video streams by default: - - true: Stop receiving all remote users' video streams by default. - - false: (Default) Receive all remote users' video streams by default. - - @return - - 0: Success. - - < 0: Failure. + /** 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 \ref IChannel::setDefaultMuteAllRemoteVideoStreams "setDefaultMuteAllRemoteVideoStreams" (true), do the following: + * - If you need to resume subscribing to the video stream of a specified user, call \ref IChannel::muteRemoteVideoStream "muteRemoteVideoStream" (false), and specify the user ID. + * - If you need to resume subscribing to the video streams of multiple remote users, call \ref IChannel::muteRemoteVideoStream "muteRemoteVideoStream" (false) multiple times. + * + * @param mute Sets whether to stop subscribing to the video streams of all remote users by default. + * - true: Stop subscribing to the video streams of all remote users by default. + * - false: (Default) Resume subscribing to the video streams of all remote users by default. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int setDefaultMuteAllRemoteVideoStreams(bool mute) = 0; - /** Stops/Resumes receiving all remote users' audio streams. - - @param mute Sets whether to receive/stop receiving all remote users' audio streams. - - true: Stops receiving all remote users' audio streams. - - false: (Default) Receives all remote users' audio streams. - - @return - - 0: Success. - - < 0: Failure. + /** + * Stops or resumes subscribing to the audio streams of all remote users. + * + * 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. + * + * @note + * - Call this method after joining a channel. + * - See recommended settings in *Set the Subscribing State*. + * + * @param mute Sets whether to stop subscribing to the audio streams of all remote users. + * - true: Stop subscribing to the audio streams of all remote users. + * - false: (Default) Resume subscribing to the audio streams of all remote users. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int muteAllRemoteAudioStreams(bool mute) = 0; - /** Adjust the playback volume of the specified remote user. + /** Adjust the playback signal volume of the specified remote user. After joining a channel, call \ref agora::rtc::IRtcEngine::adjustPlaybackSignalVolume "adjustPlaybackSignalVolume" to adjust the playback volume of different remote users, or adjust multiple times for one remote user. @@ -1069,56 +1052,57 @@ class IChannel - < 0: Failure. */ virtual int adjustUserPlaybackSignalVolume(uid_t userId, int volume) = 0; - /** Stops/Resumes receiving a specified remote user's audio stream. - - @note - - You can call this method either before or after joining a channel. If you call it before joining a channel, - you need to maintain the `uid` of the remote user on your app level. - - If you called the \ref agora::rtc::IChannel::muteAllRemoteAudioStreams "muteAllRemoteAudioStreams" method and set `mute` as `true` to stop - receiving all remote users' audio streams, call the `muteAllRemoteAudioStreams` method and set `mute` as `false` before calling this method. - The `muteAllRemoteAudioStreams` method sets all remote audio streams, while the `muteRemoteAudioStream` method sets a specified remote audio stream. - - @param userId The user ID of the specified remote user sending the audio. - @param mute Sets whether to receive/stop receiving a specified remote user's audio stream: - - true: Stops receiving the specified remote user's audio stream. - - false: (Default) Receives the specified remote user's audio stream. - - @return - - 0: Success. - - < 0: Failure. - - */ + /** + * Stops or resumes subscribing to the audio stream of a specified user. + * + * @note + * - Call this method after joining a channel. + * - See recommended settings in *Set the Subscribing State*. + * + * @param userId The user ID of the specified remote user. + * @param mute Sets whether to stop subscribing to the audio stream of a specified user. + * - true: Stop subscribing to the audio stream of a specified user. + * - false: (Default) Resume subscribing to the audio stream of a specified user. + * + * @return + * - 0: Success. + * - < 0: Failure. + */ virtual int muteRemoteAudioStream(uid_t userId, bool mute) = 0; - /** Stops/Resumes receiving all video stream from a specified remote user. - - @note You can call this method either before or after joining a channel. - - @param mute Sets whether to receive/stop receiving all remote users' video streams: - - true: Stop receiving all remote users' video streams. - - false: (Default) Receive all remote users' video streams. - - @return - - 0: Success. - - < 0: Failure. + /** + * Stops or resumes subscribing to the video streams of all remote users. + * + * 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. + * + * @note + * - Call this method after joining a channel. + * - See recommended settings in *Set the Subscribing State*. + * + * @param mute Sets whether to stop subscribing to the video streams of all remote users. + * - true: Stop subscribing to the video streams of all remote users. + * - false: (Default) Resume subscribing to the video streams of all remote users. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int muteAllRemoteVideoStreams(bool mute) = 0; - /** Stops/Resumes receiving the video stream from a specified remote user. - - @note - - You can call this method either before or after joining a channel. If you call it before joining a channel, you - need to maintain the `uid` of the remote user on your app level. - - If you called the \ref agora::rtc::IChannel::muteAllRemoteVideoStreams "muteAllRemoteVideoStreams" method and - set `mute` as `true` to stop receiving all remote video streams, call the `muteAllRemoteVideoStreams` method and - set `mute` as `false` before calling this method. - - @param userId The user ID of the specified remote user. - @param mute Sets whether to stop/resume receiving the video stream from a specified remote user: - - true: Stop receiving the specified remote user's video stream. - - false: (Default) Receive the specified remote user's video stream. - - @return - - 0: Success. - - < 0: Failure. + /** + * Stops or resumes subscribing to the video stream of a specified user. + * + * @note + * - Call this method after joining a channel. + * - See recommended settings in *Set the Subscribing State*. + * + * @param userId The user ID of the specified remote user. + * @param mute Sets whether to stop subscribing to the video stream of a specified user. + * - true: Stop subscribing to the video stream of a specified user. + * - false: (Default) Resume subscribing to the video stream of a specified user. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int muteRemoteVideoStream(uid_t userId, bool mute) = 0; /** Sets the stream type of the remote video. @@ -1168,10 +1152,12 @@ class IChannel virtual int setRemoteDefaultVideoStreamType(REMOTE_VIDEO_STREAM_TYPE streamType) = 0; /** Creates a data stream. + @deprecated This method is deprecated from v3.3.0. Use the \ref IChannel::createDataStream(int* streamId, DataStreamConfig& config) "createDataStream" [2/2] method instead. + Each user can create up to five data streams during the lifecycle of the IChannel. @note - - Set both the `reliable` and `ordered` parameters to `true` or `false`. Do not set one as `true` and the other as `false`. + - Do not set `reliable` as `true` while setting `ordered` as `false`. - Ensure that you call this method after joining a channel. @param[out] streamId The ID of the created data stream. @@ -1189,6 +1175,23 @@ class IChannel - < 0: Failure. */ virtual int createDataStream(int* streamId, bool reliable, bool ordered) = 0; + /** 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. + * + * @param[out] streamId The ID of the created data stream. + * @param config The configurations for the data stream: DataStreamConfig. + * + * @return + * - 0: Creates the data stream successfully. + * - < 0: Fails to create the data stream. + */ + virtual int createDataStream(int* streamId, DataStreamConfig& config) = 0; /** Sends data stream messages to all users in a channel. The SDK has the following restrictions on this method: @@ -1215,44 +1218,45 @@ class IChannel - < 0: Failure. */ virtual int sendStreamMessage(int streamId, const char* data, size_t length) = 0; - /** Publishes the local stream to a specified CDN live RTMP address. (CDN live only.) + /** Publishes the local stream to a specified CDN streaming URL. (CDN live only.) The SDK returns the result of this method call in the \ref IRtcEngineEventHandler::onStreamPublished "onStreamPublished" callback. - The \ref agora::rtc::IChannel::addPublishStreamUrl "addPublishStreamUrl" method call triggers + After calling this method, you can push media streams in RTMP or RTMPS protocol to the CDN. The SDK triggers the \ref agora::rtc::IChannelEventHandler::onRtmpStreamingStateChanged "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 RTMP Converter service before using this function. See Prerequisites in the advanced guide *Push Streams to CDN*. - - This method adds only one stream RTMP URL address each time it is called. + - 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. - @param url The CDN streaming URL in the RTMP format. The maximum length of this parameter is 1024 bytes. The RTMP URL address must not contain special characters, such as Chinese language characters. - @param transcodingEnabled Sets whether transcoding is enabled/disabled: + @param url The 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. + @param transcodingEnabled Sets whether transcoding is enabled/disabled: - true: Enable transcoding. To [transcode](https://docs.agora.io/en/Agora%20Platform/terms?platform=All%20Platforms#transcoding) 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 \ref IChannel::setLiveTranscoding "setLiveTranscoding" method before this method. - false: Disable transcoding. @return - 0: Success. - < 0: Failure. - - #ERR_INVALID_ARGUMENT (2): The RTMP URL address is NULL or has a string length of 0. - - #ERR_NOT_INITIALIZED (7): You have not initialized `IChannel` when publishing the stream. + - #ERR_INVALID_ARGUMENT (-2): The CDN streaming URL is NULL or has a string length of 0. + - #ERR_NOT_INITIALIZED (-7): You have not initialized `IChannel` when publishing the stream. */ virtual int addPublishStreamUrl(const char *url, bool transcodingEnabled) = 0; - /** Removes an RTMP stream from the CDN. + /** Removes an RTMP or RTMPS stream from the CDN. - This method removes the RTMP URL address (added by the \ref IChannel::addPublishStreamUrl "addPublishStreamUrl" method) from a CDN live stream. + This method removes the CDN streaming URL (added by the \ref IChannel::addPublishStreamUrl "addPublishStreamUrl" method) from a CDN live stream. The SDK returns the result of this method call in the \ref IRtcEngineEventHandler::onStreamUnpublished "onStreamUnpublished" callback. The \ref agora::rtc::IChannel::removePublishStreamUrl "removePublishStreamUrl" method call triggers - the \ref agora::rtc::IChannelEventHandler::onRtmpStreamingStateChanged "onRtmpStreamingStateChanged" callback on the local client to report the state of removing an RTMP stream from the CDN. + the \ref agora::rtc::IChannelEventHandler::onRtmpStreamingStateChanged "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 RTMP URL address each time it is called. - - The RTMP URL address must not contain special characters, such as Chinese language characters. + - 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. - @param url The RTMP URL address to be removed. The maximum length of this parameter is 1024 bytes. + @param url The CDN streaming URL to be removed. The maximum length of this parameter is 1024 bytes. @return - 0: Success. @@ -1268,6 +1272,7 @@ class IChannel - Ensure that you enable the RTMP Converter service before using this function. See Prerequisites in the advanced guide *Push Streams to CDN*.. - 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. @param transcoding Sets the CDN live audio/video transcoding settings. See LiveTranscoding. @@ -1304,10 +1309,10 @@ class IChannel @return - 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 \ref IRtcEngine::setChannelProfile "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. + - #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 \ref IRtcEngine::setChannelProfile "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. */ virtual int addInjectStreamUrl(const char* url, const InjectStreamConfig& config) = 0; /** Removes the voice or video stream URL address from a live streaming. diff --git a/Android/APIExample/lib-raw-data/src/main/cpp/include/IAgoraRtcEngine.h b/Android/APIExample/lib-raw-data/src/main/cpp/include/IAgoraRtcEngine.h index ab6b753f4..044772eb4 100644 --- a/Android/APIExample/lib-raw-data/src/main/cpp/include/IAgoraRtcEngine.h +++ b/Android/APIExample/lib-raw-data/src/main/cpp/include/IAgoraRtcEngine.h @@ -196,7 +196,10 @@ enum MEDIA_DEVICE_STATE_TYPE MEDIA_DEVICE_STATE_NOT_PRESENT = 4, /** 8: The device is unplugged. */ - MEDIA_DEVICE_STATE_UNPLUGGED = 8 + MEDIA_DEVICE_STATE_UNPLUGGED = 8, + /** 16: The device is not recommended. + */ + MEDIA_DEVICE_STATE_UNRECOMMENDED = 16 }; /** Media device types. @@ -209,7 +212,7 @@ enum MEDIA_DEVICE_TYPE /** 0: Audio playback device. */ AUDIO_PLAYOUT_DEVICE = 0, - /** 1: Audio recording device. + /** 1: Audio capturing device. */ AUDIO_RECORDING_DEVICE = 1, /** 2: Video renderer. @@ -255,6 +258,10 @@ enum LOCAL_VIDEO_STREAM_ERROR { LOCAL_VIDEO_STREAM_ERROR_CAPTURE_FAILURE = 4, /** 5: The local video encoding fails. */ LOCAL_VIDEO_STREAM_ERROR_ENCODE_FAILURE = 5, + /** 6: capture InBackground. */ + LOCAL_VIDEO_STREAM_ERROR_CAPTURE_INBACKGROUND = 6, + /** 7:capture MultipleForegroundApps. */ + LOCAL_VIDEO_STREAM_ERROR_CAPTURE_MULTIPLE_FOREGROUND_APPS = 7, /** 11: The shared window is minimized when you call \ref IRtcEngine::startScreenCaptureByWindowId "startScreenCaptureByWindowId" to share a window. */ LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_WINDOW_MINIMIZED = 11, @@ -280,7 +287,7 @@ enum LOCAL_AUDIO_STREAM_STATE /** 0: The local audio is in the initial state. */ LOCAL_AUDIO_STREAM_STATE_STOPPED = 0, - /** 1: The recording device starts successfully. + /** 1: The capturing device starts successfully. */ LOCAL_AUDIO_STREAM_STATE_RECORDING = 1, /** 2: The first audio frame encodes successfully. @@ -307,7 +314,7 @@ enum LOCAL_AUDIO_STREAM_ERROR /** 3: The microphone is in use. */ LOCAL_AUDIO_STREAM_ERROR_DEVICE_BUSY = 3, - /** 4: The local audio recording fails. Check whether the recording device + /** 4: The local audio capturing fails. Check whether the capturing device * is working properly. */ LOCAL_AUDIO_STREAM_ERROR_RECORD_FAILURE = 4, @@ -635,8 +642,8 @@ enum CHANNEL_PROFILE_TYPE */ CHANNEL_PROFILE_GAME = 2, }; -/// @cond -/** The role of a user in a live interactive streaming. */ + +/** The role of a user in interactive live streaming. */ enum CLIENT_ROLE_TYPE { /** 1: Host. A host can both send and receive streams. */ @@ -645,9 +652,9 @@ enum CLIENT_ROLE_TYPE CLIENT_ROLE_AUDIENCE = 2, }; -/** The latency level of an audience member in a live interactive streaming. +/** The latency level of an audience member in interactive live streaming. * - * @note Takes effect only when the user role is `CLIENT_ROLE_BROADCASTER`. + * @note Takes effect only when the user role is `CLIENT_ROLE_AUDIENCE`. */ enum AUDIENCE_LATENCY_LEVEL_TYPE { @@ -688,68 +695,68 @@ enum USER_OFFLINE_REASON_TYPE USER_OFFLINE_BECOME_AUDIENCE = 2, }; /** - States of the RTMP streaming. + States of the RTMP or RTMPS streaming. */ enum RTMP_STREAM_PUBLISH_STATE { - /** The RTMP streaming has not started or has ended. This state is also triggered after you remove an RTMP address from the CDN by calling removePublishStreamUrl. + /** The RTMP or RTMPS streaming has not started or has ended. This state is also triggered after you remove an RTMP or RTMPS stream from the CDN by calling `removePublishStreamUrl`. */ RTMP_STREAM_PUBLISH_STATE_IDLE = 0, - /** The SDK is connecting to Agora's streaming server and the RTMP server. This state is triggered after you call the \ref IRtcEngine::addPublishStreamUrl "addPublishStreamUrl" method. + /** The SDK is connecting to Agora's streaming server and the CDN server. This state is triggered after you call the \ref IRtcEngine::addPublishStreamUrl "addPublishStreamUrl" method. */ RTMP_STREAM_PUBLISH_STATE_CONNECTING = 1, - /** The RTMP streaming publishes. The SDK successfully publishes the RTMP streaming and returns this state. + /** The RTMP or RTMPS streaming publishes. The SDK successfully publishes the RTMP or RTMPS streaming and returns this state. */ RTMP_STREAM_PUBLISH_STATE_RUNNING = 2, - /** The RTMP streaming is recovering. When exceptions occur to the CDN, or the streaming is interrupted, the SDK tries to resume RTMP streaming and returns this state. + /** The RTMP or RTMPS streaming is recovering. When exceptions occur to the CDN, or the streaming is interrupted, the SDK tries to resume RTMP or RTMPS streaming and returns this state. - If the SDK successfully resumes the streaming, #RTMP_STREAM_PUBLISH_STATE_RUNNING (2) returns. - If the streaming does not resume within 60 seconds or server errors occur, #RTMP_STREAM_PUBLISH_STATE_FAILURE (4) returns. You can also reconnect to the server by calling the \ref IRtcEngine::removePublishStreamUrl "removePublishStreamUrl" and \ref IRtcEngine::addPublishStreamUrl "addPublishStreamUrl" methods. */ RTMP_STREAM_PUBLISH_STATE_RECOVERING = 3, - /** The RTMP streaming fails. See the errCode parameter for the detailed error information. You can also call the \ref IRtcEngine::addPublishStreamUrl "addPublishStreamUrl" method to publish the RTMP streaming again. + /** The RTMP or RTMPS streaming fails. See the errCode parameter for the detailed error information. You can also call the \ref IRtcEngine::addPublishStreamUrl "addPublishStreamUrl" method to publish the RTMP or RTMPS streaming again. */ RTMP_STREAM_PUBLISH_STATE_FAILURE = 4, }; /** - Error codes of the RTMP streaming. + Error codes of the RTMP or RTMPS streaming. */ enum RTMP_STREAM_PUBLISH_ERROR { - /** The RTMP streaming publishes successfully. */ + /** The RTMP or RTMPS streaming publishes successfully. */ RTMP_STREAM_PUBLISH_ERROR_OK = 0, /** Invalid argument used. If, for example, you do not call the \ref IRtcEngine::setLiveTranscoding "setLiveTranscoding" method to configure the LiveTranscoding parameters before calling the addPublishStreamUrl method, the SDK returns this error. Check whether you set the parameters in the *setLiveTranscoding* method properly. */ RTMP_STREAM_PUBLISH_ERROR_INVALID_ARGUMENT = 1, - /** The RTMP streaming is encrypted and cannot be published. */ + /** The RTMP or RTMPS streaming is encrypted and cannot be published. */ RTMP_STREAM_PUBLISH_ERROR_ENCRYPTED_STREAM_NOT_ALLOWED = 2, - /** Timeout for the RTMP streaming. Call the \ref IRtcEngine::addPublishStreamUrl "addPublishStreamUrl" method to publish the streaming again. */ + /** Timeout for the RTMP or RTMPS streaming. Call the \ref IRtcEngine::addPublishStreamUrl "addPublishStreamUrl" method to publish the streaming again. */ RTMP_STREAM_PUBLISH_ERROR_CONNECTION_TIMEOUT = 3, - /** An error occurs in Agora's streaming server. Call the addPublishStreamUrl method to publish the streaming again. */ + /** An error occurs in Agora's streaming server. Call the `addPublishStreamUrl` method to publish the streaming again. */ RTMP_STREAM_PUBLISH_ERROR_INTERNAL_SERVER_ERROR = 4, - /** An error occurs in the RTMP server. */ + /** An error occurs in the CDN server. */ RTMP_STREAM_PUBLISH_ERROR_RTMP_SERVER_ERROR = 5, - /** The RTMP streaming publishes too frequently. */ + /** The RTMP or RTMPS streaming publishes too frequently. */ RTMP_STREAM_PUBLISH_ERROR_TOO_OFTEN = 6, /** The host publishes more than 10 URLs. Delete the unnecessary URLs before adding new ones. */ RTMP_STREAM_PUBLISH_ERROR_REACH_LIMIT = 7, /** The host manipulates other hosts' URLs. Check your app logic. */ RTMP_STREAM_PUBLISH_ERROR_NOT_AUTHORIZED = 8, - /** Agora's server fails to find the RTMP streaming. */ + /** Agora's server fails to find the RTMP or RTMPS streaming. */ RTMP_STREAM_PUBLISH_ERROR_STREAM_NOT_FOUND = 9, - /** The format of the RTMP streaming URL is not supported. Check whether the URL format is correct. */ + /** The format of the RTMP or RTMPS streaming URL is not supported. Check whether the URL format is correct. */ RTMP_STREAM_PUBLISH_ERROR_FORMAT_NOT_SUPPORTED = 10, }; -/** Events during the RTMP streaming. */ +/** Events during the RTMP or RTMPS streaming. */ enum RTMP_STREAMING_EVENT { - /** An error occurs when you add a background image or a watermark image to the RTMP stream. + /** An error occurs when you add a background image or a watermark image to the RTMP or RTMPS stream. */ RTMP_STREAMING_EVENT_FAILED_LOAD_IMAGE = 1, }; -/** States of importing an external video stream in the live interactive streaming. */ +/** States of importing an external video stream in the interactive live streaming. */ enum INJECT_STREAM_STATUS { /** 0: The external video stream imported successfully. */ @@ -783,12 +790,31 @@ enum REMOTE_VIDEO_STREAM_TYPE /** 1: Low-stream video. */ REMOTE_VIDEO_STREAM_LOW = 1, }; +/** The brightness level of the video image captured by the local camera. + * + * @since v3.3.0 + */ +enum CAPTURE_BRIGHTNESS_LEVEL_TYPE { + /** -1: The SDK does not detect the brightness level of the video image. + * Wait a few seconds to get the brightness level from `CAPTURE_BRIGHTNESS_LEVEL_TYPE` in the next callback. + */ + CAPTURE_BRIGHTNESS_LEVEL_INVALID = -1, + /** 0: The brightness level of the video image is normal. + */ + CAPTURE_BRIGHTNESS_LEVEL_NORMAL = 0, + /** 1: The brightness level of the video image is too bright. + */ + CAPTURE_BRIGHTNESS_LEVEL_BRIGHT = 1, + /** 2: The brightness level of the video image is too dark. + */ + CAPTURE_BRIGHTNESS_LEVEL_DARK = 2, +}; /** The use mode of the audio data in the \ref media::IAudioFrameObserver::onRecordAudioFrame "onRecordAudioFrame" or \ref media::IAudioFrameObserver::onPlaybackAudioFrame "onPlaybackAudioFrame" callback. */ enum RAW_AUDIO_FRAME_OP_MODE_TYPE { - /** 0: Read-only mode: Users only read the \ref agora::media::IAudioFrameObserver::AudioFrame "AudioFrame" data without modifying anything. For example, when users acquire the data with the Agora SDK, then push the RTMP streams. */ + /** 0: Read-only mode: Users only read the \ref agora::media::IAudioFrameObserver::AudioFrame "AudioFrame" data without modifying anything. For example, when users acquire the data with the Agora SDK, then push the RTMP or RTMPS streams. */ RAW_AUDIO_FRAME_OP_MODE_READ_ONLY = 0, /** 1: Write-only mode: Users replace the \ref agora::media::IAudioFrameObserver::AudioFrame "AudioFrame" data with their own data and pass the data to the SDK for encoding. For example, when users acquire the data. */ RAW_AUDIO_FRAME_OP_MODE_WRITE_ONLY = 1, @@ -1064,6 +1090,17 @@ enum VOICE_BEAUTIFIER_PRESET * @note Agora recommends using this enumerator to process a female-sounding voice; otherwise, you may experience vocal distortion. */ CHAT_BEAUTIFIER_VITALITY = 0x01010300, + /** + * @since v3.3.0 + * + * Singing beautifier effect. + * - If you call \ref IRtcEngine::setVoiceBeautifierPreset "setVoiceBeautifierPreset" (SINGING_BEAUTIFIER), you can beautify a male-sounding voice and add a reverberation + * effect that sounds like singing in a small room. Agora recommends not using \ref IRtcEngine::setVoiceBeautifierPreset "setVoiceBeautifierPreset" (SINGING_BEAUTIFIER) + * to process a female-sounding voice; otherwise, you may experience vocal distortion. + * - If you call \ref IRtcEngine::setVoiceBeautifierParameters "setVoiceBeautifierParameters"(SINGING_BEAUTIFIER, param1, param2), you can beautify a male- or + * female-sounding voice and add a reverberation effect. + */ + SINGING_BEAUTIFIER = 0x01020100, /** A more vigorous voice. */ TIMBRE_TRANSFORMATION_VIGOROUS = 0x01030100, @@ -1076,7 +1113,7 @@ enum VOICE_BEAUTIFIER_PRESET /** A falsetto voice. */ TIMBRE_TRANSFORMATION_FALSETTO = 0x01030400, - /** A falsetto voice. + /** A fuller voice. */ TIMBRE_TRANSFORMATION_FULL = 0x01030500, /** A clearer voice. @@ -1216,16 +1253,16 @@ enum AUDIO_EFFECT_PRESET VOICE_CHANGER_EFFECT_HULK = 0x02020700, /** An audio effect typical of R&B music. * - * @note To achieve better audio effect quality, Agora recommends calling \ref IRtcEngine::setAudioProfile "setAudioProfile" and - * setting the `profile` parameter to `AUDIO_PROFILE_MUSIC_HIGH_QUALITY(4)` or `AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5)` before - * setting this enumerator. + * @note Call \ref IRtcEngine::setAudioProfile "setAudioProfile" and + * set the `profile` parameter to `AUDIO_PROFILE_MUSIC_HIGH_QUALITY(4)` or `AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5)` before + * setting this enumerator; otherwise, the enumerator setting does not take effect. */ STYLE_TRANSFORMATION_RNB = 0x02030100, /** An audio effect typical of popular music. * - * @note To achieve better audio effect quality, Agora recommends calling \ref IRtcEngine::setAudioProfile "setAudioProfile" and - * setting the `profile` parameter to `AUDIO_PROFILE_MUSIC_HIGH_QUALITY(4)` or `AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5)` before - * setting this enumerator. + * @note Call \ref IRtcEngine::setAudioProfile "setAudioProfile" and + * set the `profile` parameter to `AUDIO_PROFILE_MUSIC_HIGH_QUALITY(4)` or `AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5)` before + * setting this enumerator; otherwise, the enumerator setting does not take effect. */ STYLE_TRANSFORMATION_POPULAR = 0x02030200, /** A pitch correction effect that corrects the user's pitch based on the pitch of the natural C major scale. @@ -1237,6 +1274,14 @@ enum AUDIO_EFFECT_PRESET */ PITCH_CORRECTION = 0x02040100 }; +enum VOICE_CONVERSION_PRESET +{ + VOICE_CONVERSION_OFF = 0x00000000, + VOICE_CHANGER_NEUTRAL = 0x03010100, + VOICE_CHANGER_SWEET = 0x03010200, + VOICE_CHANGER_SOLID = 0x03010300, + VOICE_CHANGER_BASS = 0x03010400 +}; /** Audio codec profile types. The default value is LC_ACC. */ enum AUDIO_CODEC_PROFILE_TYPE { @@ -1525,7 +1570,7 @@ enum STREAM_FALLBACK_OPTIONS STREAM_FALLBACK_OPTION_AUDIO_ONLY = 2, }; - /** Camera capturer configuration. + /** Camera capture preference. */ enum CAPTURER_OUTPUT_PREFERENCE { @@ -1538,6 +1583,11 @@ enum STREAM_FALLBACK_OPTIONS /** 2: Prioritizes the local preview quality. The SDK chooses higher camera output parameters to improve the local video preview quality. This option requires extra CPU and RAM usage for video pre-processing. */ CAPTURER_OUTPUT_PREFERENCE_PREVIEW = 2, + /** 3: Allows you to customize the width and height of the video image captured by the local camera. + * + * @since v3.3.0 + */ + CAPTURER_OUTPUT_PREFERENCE_MANUAL = 3, }; /** The priority of the remote user. @@ -1599,7 +1649,7 @@ enum CONNECTION_CHANGED_REASON_TYPE CONNECTION_CHANGED_JOIN_SUCCESS = 1, /** 2: The connection between the SDK and Agora's edge server is interrupted. */ CONNECTION_CHANGED_INTERRUPTED = 2, - /** 3: The connection between the SDK and Agora's edge server is banned by Agora's edge server. */ + /** 3: The user is banned by the server. This error occurs when the user is kicked out the channel from the server. */ CONNECTION_CHANGED_BANNED_BY_SERVER = 3, /** 4: The SDK fails to join the channel for more than 20 minutes and stops reconnecting to the channel. */ CONNECTION_CHANGED_JOIN_FAILED = 4, @@ -1633,6 +1683,8 @@ enum CONNECTION_CHANGED_REASON_TYPE CONNECTION_CHANGED_CLIENT_IP_ADDRESS_CHANGED = 13, /** 14: Timeout for the keep-alive of the connection between the SDK and Agora's edge server. The connection state changes to CONNECTION_STATE_RECONNECTING(4). */ CONNECTION_CHANGED_KEEP_ALIVE_TIMEOUT = 14, + /** 15: In cloud proxy mode, the proxy server connection interrupted. */ + CONNECTION_CHANGED_PROXY_SERVER_INTERRUPTED = 15, }; /** Network type. */ @@ -1644,7 +1696,7 @@ enum NETWORK_TYPE NETWORK_TYPE_DISCONNECTED = 0, /** 1: The network type is LAN. */ NETWORK_TYPE_LAN = 1, - /** 2: The network type is Wi-Fi(including hotspots). */ + /** 2: The network type is Wi-Fi (including hotspots). */ NETWORK_TYPE_WIFI = 2, /** 3: The network type is mobile 2G. */ NETWORK_TYPE_MOBILE_2G = 3, @@ -1653,6 +1705,27 @@ enum NETWORK_TYPE /** 5: The network type is mobile 4G. */ NETWORK_TYPE_MOBILE_4G = 5, }; +/// @cond +/** + * The reason for the upload failure. + * + * @since v3.3.0 + */ +enum UPLOAD_ERROR_REASON +{ + /** 0: The log file is successfully uploaded. + */ + UPLOAD_SUCCESS = 0, + /** + * 1: Network error. Check the network connection and call \ref IRtcEngine::uploadLogFile "uploadLogFile" again to upload the log file. + */ + UPLOAD_NET_ERROR = 1, + /** + * 2: An error occurs in the Agora server. Try uploading the log files later. + */ + UPLOAD_SERVER_ERROR = 2, +}; +/// @endcond /** States of the last-mile network probe test. */ enum LASTMILE_PROBE_RESULT_STATE { @@ -1700,6 +1773,24 @@ enum AUDIO_ROUTE_TYPE { AUDIO_ROUTE_AIRPLAY = 9, }; +/** The cloud proxy type. + * + * @since v3.3.0 + */ +enum CLOUD_PROXY_TYPE { + /** 0: Do not use the cloud proxy. + */ + NONE_PROXY = 0, + /** 1: The cloud proxy for the UDP protocol. + */ + UDP_PROXY = 1, + /// @cond + /** 2: The cloud proxy for the TCP (encrypted) protocol. + */ + TCP_PROXY = 2, + /// @endcond +}; + #if (defined(__APPLE__) && TARGET_OS_IOS) /** Audio session restriction. */ enum AUDIO_SESSION_OPERATION_RESTRICTION { @@ -1763,44 +1854,45 @@ struct LastmileProbeConfig { unsigned int expectedDownlinkBitrate; }; -/** Properties of the audio volume information. - - An array containing the user ID and volume information for each speaker. +/** The volume information of users. */ struct AudioVolumeInfo { /** - User ID of the speaker. The uid of the local user is 0. + * The user ID. + * - In the local user's callback, `uid = 0`. + * - In the remote users' callback, `uid` is the ID of a remote user whose instantaneous volume is one of the three highest. */ uid_t uid; - /** The volume of the speaker. The volume ranges between 0 (lowest volume) and 255 (highest volume). + /** The volume of each user after audio mixing. The value ranges between 0 (lowest volume) and 255 (highest volume). + * In the local user's callback, `volume = totalVolume`. */ unsigned int volume; /** Voice activity status of the local user. - * - 0: The local user is not speaking. - * - 1: The local user is speaking. + * - `0`: The local user is not speaking. + * - `1`: The local user is speaking. * * @note - * - The `vad` parameter cannot report the voice activity status of the remote users. In the remote users' callback, `vad` = 0. - * - Ensure that you set `report_vad`(true) in the \ref agora::rtc::IRtcEngine::enableAudioVolumeIndication(int, int, bool) "enableAudioVolumeIndication" method to enable the voice activity detection of the local user. + * - The `vad` parameter cannot report the voice activity status of remote users. + * In the remote users' callback, `vad` is always `0`. + * - To use this parameter, you must set the `report_vad` parameter to `true` + * when calling \ref agora::rtc::IRtcEngine::enableAudioVolumeIndication(int, int, bool) "enableAudioVolumeIndication". */ unsigned int vad; - /** The channel ID, which indicates which channel the speaker is in. + /** The name of the channel where the user is in. */ const char * channelId; }; -/// @cond /** The detailed options of a user. */ struct ClientRoleOptions { - /** The latency level of an audience member in a live interactive streaming. See #AUDIENCE_LATENCY_LEVEL_TYPE. + /** The latency level of an audience member in interactive live streaming. See #AUDIENCE_LATENCY_LEVEL_TYPE. */ AUDIENCE_LATENCY_LEVEL_TYPE audienceLatencyLevel; ClientRoleOptions() : audienceLatencyLevel(AUDIENCE_LATENCY_LEVEL_ULTRA_LOW_LATENCY) {} }; -/// @endcond /** Statistics of the channel. */ struct RtcStats @@ -1945,6 +2037,41 @@ enum QUALITY_ADAPT_INDICATION { /** The quality worsens because the network bandwidth decreases. */ ADAPT_DOWN_BANDWIDTH = 2, }; +/** Quality of experience (QoE) of the local user when receiving a remote audio stream. + * + * @since v3.3.0 + */ +enum EXPERIENCE_QUALITY_TYPE +{ + /** 0: QoE of the local user is good. */ + EXPERIENCE_QUALITY_GOOD = 0, + /** 1: QoE of the local user is poor. */ + EXPERIENCE_QUALITY_BAD = 1, +}; + +/** + * The reason for poor QoE of the local user when receiving a remote audio stream. + * + * @since v3.3.0 + */ +enum EXPERIENCE_POOR_REASON { + /** 0: No reason, indicating good QoE of the local user. + */ + EXPERIENCE_REASON_NONE = 0, + /** 1: The remote user's network quality is poor. + */ + REMOTE_NETWORK_QUALITY_POOR = 1, + /** 2: The local user's network quality is poor. + */ + LOCAL_NETWORK_QUALITY_POOR = 2, + /** 4: The local user's Wi-Fi or mobile network signal is weak. + */ + WIRELESS_SIGNAL_POOR = 4, + /** 8: The local user enables both Wi-Fi and bluetooth, and their signals interfere with each other. + * As a result, audio transmission quality is undermined. + */ + WIFI_BLUETOOTH_COEXIST = 8, +}; /** The error code in CHANNEL_MEDIA_RELAY_ERROR. */ enum CHANNEL_MEDIA_RELAY_ERROR { @@ -2110,6 +2237,11 @@ struct LocalVideoStats /** The capture frame rate (fps) of the local video. */ int captureFrameRate; + /** The brightness level of the video image captured by the local camera. See #CAPTURE_BRIGHTNESS_LEVEL_TYPE. + * + * @since v3.3.0 + */ + CAPTURE_BRIGHTNESS_LEVEL_TYPE captureBrightnessLevel; }; /** Statistics of the remote video stream. @@ -2232,6 +2364,22 @@ struct RemoteAudioStats * The total publish duration (ms) of the remote audio stream. */ int publishDuration; + /** + * Quality of experience (QoE) of the local user when receiving a remote audio stream. See #EXPERIENCE_QUALITY_TYPE. + * + * @since v3.3.0 + */ + int qoeQuality; + /** + * The reason for poor QoE of the local user when receiving a remote audio stream. See #EXPERIENCE_POOR_REASON. + * + * @since v3.3.0 + */ + int qualityChangedReason; + /** + * The mos value of remote audio. + */ + int mosValue; }; /** @@ -2252,7 +2400,7 @@ struct VideoDimensions { /** (Recommended) The standard bitrate set in the \ref IRtcEngine::setVideoEncoderConfiguration "setVideoEncoderConfiguration" method. - In this mode, the bitrates differ between the live interactive streaming and communication profiles: + In this mode, the bitrates differ between the interactive live streaming and communication profiles: - `COMMUNICATION` profile: The video bitrate is the same as the base bitrate. - `LIVE_BROADCASTING` profile: The video bitrate is twice the base bitrate. @@ -2352,7 +2500,7 @@ struct VideoEncoderConfiguration { DEGRADATION_PREFERENCE degradationPreference; /** Sets the mirror mode of the published local video stream. It only affects the video that the remote user sees. See #VIDEO_MIRROR_MODE_TYPE - @note: The SDK disables the mirror mode by default. + @note The SDK disables the mirror mode by default. */ VIDEO_MIRROR_MODE_TYPE mirrorMode; @@ -2419,16 +2567,17 @@ typedef struct TranscodingUser { - 1.0: (Default) Opaque */ double alpha; - /** The audio channel of the sound. The default value is 0: + /** The audio channel where the host's audio is located. The value range is [0,5]. - 0: (Default) Supports dual channels at most, depending on the upstream of the host. - - 1: The audio stream of the host uses the FL audio channel. If the upstream of the host uses multiple audio channels, these channels are mixed into mono first. - - 2: The audio stream of the host uses the FC audio channel. If the upstream of the host uses multiple audio channels, these channels are mixed into mono first. - - 3: The audio stream of the host uses the FR audio channel. If the upstream of the host uses multiple audio channels, these channels are mixed into mono first. - - 4: The audio stream of the host uses the BL audio channel. If the upstream of the host uses multiple audio channels, these channels are mixed into mono first. - - 5: The audio stream of the host uses the BR audio channel. If the upstream of the host uses multiple audio channels, these channels are mixed into mono first. + - 1: The host's audio uses the FL audio channel. If the host's upstream uses multiple audio channels, these channels are mixed into mono first. + - 2: The host's audio uses the FC audio channel. If the host's upstream uses multiple audio channels, these channels are mixed into mono first. + - 3: The host's audio uses the FR audio channel. If the host's upstream uses multiple audio channels, these channels are mixed into mono first. + - 4: The host's audio uses the BL audio channel. If the host's upstream uses multiple audio channels, these channels are mixed into mono first. + - 5: The host's audio uses the BR audio channel. If the host's upstream uses multiple audio channels, these channels are mixed into mono first. + - `0xFF` or a value greater than `5`: The host's audio is muted. The Agora server removes the host's audio. - @note If your setting is not 0, you may need a specialized player. + @note If the value is not `0`, a special player is required. */ int audioChannel; TranscodingUser() @@ -2468,7 +2617,7 @@ typedef struct RtcImage { int height; } RtcImage; /// @cond -/** The configuration for advanced features of the RTMP streaming with transcoding. +/** The configuration for advanced features of the RTMP or RTMPS streaming with transcoding. */ typedef struct LiveStreamAdvancedFeature { LiveStreamAdvancedFeature() : featureName(NULL) , opened(false) { @@ -2536,7 +2685,7 @@ typedef struct LiveTranscoding { /** video codec type */ VIDEO_CODEC_TYPE_FOR_STREAM videoCodecType; - /** The number of users in the live interactive streaming. + /** The number of users in the interactive live streaming. */ unsigned int userCount; /** TranscodingUser @@ -2581,7 +2730,7 @@ typedef struct LiveTranscoding { AUDIO_CODEC_PROFILE_TYPE audioCodecProfile; /// @cond - /** Advanced features of the RTMP streaming with transcoding. See LiveStreamAdvancedFeature. + /** Advanced features of the RTMP or RTMPS streaming with transcoding. See LiveStreamAdvancedFeature. * * @since v3.1.0 */ @@ -2621,43 +2770,102 @@ typedef struct LiveTranscoding { /** Camera capturer preference settings. See: #CAPTURER_OUTPUT_PREFERENCE. */ CAPTURER_OUTPUT_PREFERENCE preference; + /** The width (px) of the video image captured by the local camera. + * To customize the width of the video image, set `preference` as #CAPTURER_OUTPUT_PREFERENCE_MANUAL (3) first, + * and then use `captureWidth`. + * + * @since v3.3.0 + */ + int captureWidth; + /** The height (px) of the video image captured by the local camera. + * To customize the height of the video image, set `preference` as #CAPTURER_OUTPUT_PREFERENCE_MANUAL (3) first, + * and then use `captureHeight`. + * + * @since v3.3.0 + */ + int captureHeight; #if defined(__ANDROID__) || (defined(__APPLE__) && TARGET_OS_IOS) /** Camera direction settings (for Android/iOS only). See: #CAMERA_DIRECTION. */ CAMERA_DIRECTION cameraDirection; #endif - }; + CameraCapturerConfiguration() + :preference(CAPTURER_OUTPUT_PREFERENCE_AUTO) + ,captureWidth(640) + ,captureHeight(480) + {} + + CameraCapturerConfiguration(int width, int height) + :preference(CAPTURER_OUTPUT_PREFERENCE_MANUAL) + ,captureWidth(width) + ,captureHeight(height) + {} + }; +/** The configurations for the data stream. + * + * @since v3.3.0 + * + * |`syncWithAudio` |`ordered`| SDK behaviors| + * |--------------|--------|-------------| + * | false | false |The SDK triggers the `onStreamMessage` callback immediately after the receiver receives a data packet | + * | true | false |

If the data packet delay is within the audio delay, the SDK triggers the `onStreamMessage` callback when the synchronized audio packet is played out.

If the data packet delay exceeds the audio delay, the SDK triggers the `onStreamMessage` callback as soon as the data packet is received. In this case, the data packet is not synchronized with the audio packet.

| + * | false | true |

If the delay of a data packet is within five seconds, the SDK corrects the order of the data packet.

If the delay of a data packet exceeds five seconds, the SDK discards the data packet.

| + * | true | true |

If the delay of a data packet is within the audio delay, the SDK corrects the order of the data packet.

If the delay of a data packet exceeds the audio delay, the SDK discards this data packet.

| + */ +struct DataStreamConfig { + /** Whether to synchronize the data packet with the published audio packet. + * + * - true: Synchronize the data packet with the audio packet. + * - false: Do not synchronize the data packet with the audio packet. + * + * When you set the data packet to synchronize with the audio, then if the data + * packet delay is within the audio delay, the SDK triggers the `onStreamMessage` callback when + * the synchronized audio packet is played out. Do not set this parameter as `true` if you + * need the receiver to receive the data packet immediately. Agora recommends that you set + * this parameter to `true` only when you need to implement specific functions, for example + * lyric synchronization. + */ + bool syncWithAudio; + /** Whether the SDK guarantees that the receiver receives the data in the sent order. + * + * - true: Guarantee that the receiver receives the data in the sent order. + * - false: Do not guarantee that the receiver receives the data in the sent order. + * + * Do not set this parameter to `true` if you need the receiver to receive the data immediately. + */ + bool ordered; +}; /** Configuration of the injected media stream. */ struct InjectStreamConfig { - /** Width of the injected stream in the live interactive streaming. The default value is 0 (same width as the original stream). + /** Width of the injected stream in the interactive live streaming. The default value is 0 (same width as the original stream). */ int width; - /** Height of the injected stream in the live interactive streaming. The default value is 0 (same height as the original stream). + /** Height of the injected stream in the interactive live streaming. The default value is 0 (same height as the original stream). */ int height; - /** Video GOP (in frames) of the injected stream in the live interactive streaming. The default value is 30 fps. + /** Video GOP (in frames) of the injected stream in the interactive live streaming. The default value is 30 fps. */ int videoGop; - /** Video frame rate of the injected stream in the live interactive streaming. The default value is 15 fps. + /** Video frame rate of the injected stream in the interactive live streaming. The default value is 15 fps. */ int videoFramerate; - /** Video bitrate of the injected stream in the live interactive streaming. The default value is 400 Kbps. + /** Video bitrate of the injected stream in the interactive live streaming. The default value is 400 Kbps. @note The setting of the video bitrate is closely linked to the resolution. If the video bitrate you set is beyond a reasonable range, the SDK sets it within a reasonable range. */ int videoBitrate; - /** Audio-sample rate of the injected stream in the live interactive streaming: #AUDIO_SAMPLE_RATE_TYPE. The default value is 48000 Hz. + /** Audio-sample rate of the injected stream in the interactive live streaming: #AUDIO_SAMPLE_RATE_TYPE. The default value is 48000 Hz. @note We recommend setting the default value. */ AUDIO_SAMPLE_RATE_TYPE audioSampleRate; - /** Audio bitrate of the injected stream in the live interactive streaming. The default value is 48. + /** Audio bitrate of the injected stream in the interactive live streaming. The default value is 48. @note We recommend setting the default value. */ int audioBitrate; - /** Audio channels in the live interactive streaming. + /** Audio channels in the interactive live streaming. - 1: (Default) Mono @@ -2716,7 +2924,7 @@ struct ChannelMediaRelayConfiguration { */ ChannelMediaInfo *destInfos; /** The number of destination channels. The default value is 0, and the - * value range is [0,4). Ensure that the value of this parameter + * value range is [0,4]. Ensure that the value of this parameter * corresponds to the number of ChannelMediaInfo structs you define in * `destInfos`. */ @@ -3302,7 +3510,7 @@ class IRtcEngineEventHandler (void)stats; } - /** Occurs when the user role switches in the live interactive streaming. For example, from a host to an audience or vice versa. + /** Occurs when the user role switches in the interactive live streaming. For example, from a host to an audience or vice versa. This callback notifies the application of a user role switch when the application calls the \ref IRtcEngine::setClientRole "setClientRole" method. @@ -3542,7 +3750,7 @@ class IRtcEngineEventHandler /** Occurs when the local audio state changes. * This callback indicates the state change of the local audio stream, - * including the state of the audio recording and encoding, and allows + * including the state of the audio capturing and encoding, and allows * you to troubleshoot issues when exceptions occur. * * @note @@ -3654,40 +3862,37 @@ class IRtcEngineEventHandler (void)elapseSinceLastState; } - /** Reports which users are speaking, the speakers' volume and whether the local user is speaking. - - This callback reports the IDs and volumes of the loudest speakers (at most 3 users) at the moment in the channel, and whether the local user is speaking. - - By default, this callback is disabled. You can enable it by calling the \ref IRtcEngine::enableAudioVolumeIndication(int, int, bool) "enableAudioVolumeIndication" method. - Once enabled, this callback is triggered at the set interval, regardless of whether a user speaks or not. - - The SDK triggers two independent `onAudioVolumeIndication` callbacks at one time, which separately report the volume information of the local user and all the remote speakers. - For more information, see the detailed parameter descriptions. - - @note - - To enable the voice activity detection of the local user, ensure that you set `report_vad`(true) in the `enableAudioVolumeIndication` method. - - Calling the \ref agora::rtc::IRtcEngine::muteLocalAudioStream "muteLocalAudioStream" method affects the SDK's behavior: - - If the local user calls the \ref agora::rtc::IRtcEngine::muteLocalAudioStream "muteLocalAudioStream" method, the SDK stops triggering the local user's callback. - - 20 seconds after a remote speaker calls the *muteLocalAudioStream* method, the remote speakers' callback excludes this remote user's information; 20 seconds after all remote users call the *muteLocalAudioStream* method, the SDK stops triggering the remote speakers' callback. - - An empty @p speakers array in the *onAudioVolumeIndication* callback suggests that no remote user is speaking at the moment. - - @param speakers A pointer to AudioVolumeInfo: - - In the local user's callback, this struct contains the following members: - - `uid` = 0, - - `volume` = `totalVolume`, which reports the sum of the voice volume and audio-mixing volume of the local user, and - - `vad`, which reports the voice activity status of the local user. - - In the remote speakers' callback, this array contains the following members: - - `uid` of the remote speaker, - - `volume`, which reports the sum of the voice volume and audio-mixing volume of each remote speaker, and - - `vad` = 0. - - An empty speakers array in the callback indicates that no remote user is speaking at the moment. - @param speakerNumber Total number of speakers. The value range is [0, 3]. - - In the local user’s callback, `speakerNumber` = 1, regardless of whether the local user speaks or not. - - In the remote speakers' callback, the callback reports the IDs and volumes of the three loudest speakers when there are more than three remote users in the channel, and `speakerNumber` = 3. - @param totalVolume Total volume after audio mixing. The value ranges between 0 (lowest volume) and 255 (highest volume). - - In the local user’s callback, `totalVolume` is the sum of the voice volume and audio-mixing volume of the local user. - - In the remote speakers' callback, `totalVolume` is the sum of the voice volume and audio-mixing volume of all the remote speakers. + /** Reports the volume information of users. + * + * By default, this callback is disabled. You can enable it by calling \ref IRtcEngine::enableAudioVolumeIndication(int, int, bool) "enableAudioVolumeIndication". + * Once this callback is enabled and users send streams in the channel, the SDK triggers the `onAudioVolumeIndication` callback + * at the time interval set in `enableAudioVolumeIndication`. + * + * The SDK triggers two independent `onAudioVolumeIndication` callbacks simultaneously, which separately report the + * volume information of the local user who sends a stream and the remote users (up to three) whose instantaneous + * volumes are the highest. + * + * @note After you enable this callback, calling \ref agora::rtc::IRtcEngine::muteLocalAudioStream "muteLocalAudioStream" + * affects the SDK's behavior as follows: + * - If the local user calls `muteLocalAudioStream`, the SDK stops triggering the local user's callback. + * - 20 seconds after a remote user whose volume is one of the three highest calls `muteLocalAudioStream`, the + * remote users' callback excludes this remote user's information; 20 seconds after all remote users call + * `muteLocalAudioStream`, the SDK stops triggering the remote users' callback. + * + * @param speakers The volume information of users. See AudioVolumeInfo. + * + * An empty speakers array in the callback indicates that no remote user is in the channel or sending a stream at the moment. + * @param speakerNumber Total number of users. + * - In the local user's callback, when the local user sends a stream, `speakerNumber = 1`. + * - In the remote users' callback, the value ranges between 0 and 3. If the number of remote users who send + * streams is greater than or equal to three, `speakerNumber = 3`. + * @param totalVolume Total volume after audio mixing. The value ranges between 0 (lowest volume) and 255 (highest volume). + * - In the local user's callback, totalVolume is the volume of the local user who sends a stream. + * - In the remote users' callback, totalVolume is the sum of the volume of all remote users (up to three) whose + * instantaneous volumes are the highest. + * + * If the user calls \ref agora::rtc::IRtcEngine::startAudioMixing "startAudioMixing", `totalVolume` is the sum of + * the voice volume and audio-mixing volume. */ virtual void onAudioVolumeIndication(const AudioVolumeInfo* speakers, unsigned int speakerNumber, int totalVolume) { (void)speakers; @@ -4075,13 +4280,22 @@ class IRtcEngineEventHandler } /** Occurs when the local video stream state changes. - - This callback indicates the state of the local video stream, including camera capturing and video encoding, and allows you to troubleshoot issues when exceptions occur. - - @note For some device models, the SDK will not trigger this callback when the state of the local video changes while the local video capturing device is in use, so you have to make your own timeout judgment. - - @param localVideoState State type #LOCAL_VIDEO_STREAM_STATE. When the state is LOCAL_VIDEO_STREAM_STATE_FAILED (3), see the `error` parameter for details. - @param error The detailed error information: #LOCAL_VIDEO_STREAM_ERROR. + * + * This callback indicates the state of the local video stream, including camera capturing and video encoding, and allows you to troubleshoot issues when exceptions occur. + * + * The SDK triggers the `onLocalVideoStateChanged(LOCAL_VIDEO_STREAM_STATE_FAILED，LOCAL_VIDEO_STREAM_ERROR_CAPTURE_FAILURE)` callback in the following situations: + * - The application exits to the background, and the system recycles the camera. + * - The camera starts normally, but the captured video is not output for four seconds. + * + * When the camera outputs the captured video frames, if all the video frames are the same for 15 consecutive frames, the SDK triggers the + * `onLocalVideoStateChanged(LOCAL_VIDEO_STREAM_STATE_CAPTURING，LOCAL_VIDEO_STREAM_ERROR_CAPTURE_FAILURE)` callback. Note that the + * video frame duplication detection is only available for video frames with a resolution greater than 200 × 200, a frame rate greater than or equal to 10 fps, + * and a bitrate less than 20 Kbps. + * + * @note For some device models, the SDK will not trigger this callback when the state of the local video changes while the local video capturing device is in use, so you have to make your own timeout judgment. + * + * @param localVideoState State type #LOCAL_VIDEO_STREAM_STATE. + * @param error The detailed error information: #LOCAL_VIDEO_STREAM_ERROR. */ virtual void onLocalVideoStateChanged(LOCAL_VIDEO_STREAM_STATE localVideoState, LOCAL_VIDEO_STREAM_ERROR error) { (void)localVideoState; @@ -4273,14 +4487,14 @@ class IRtcEngineEventHandler } /** - Occurs when the state of the RTMP streaming changes. + Occurs when the state of the RTMP or RTMPS streaming changes. The SDK triggers this callback to report the result of the local user calling the \ref agora::rtc::IRtcEngine::addPublishStreamUrl "addPublishStreamUrl" or \ref agora::rtc::IRtcEngine::removePublishStreamUrl "removePublishStreamUrl" method. - This callback indicates the state of the RTMP streaming. When exceptions occur, you can troubleshoot issues by referring to the detailed error descriptions in the *errCode* parameter. + This callback indicates the state of the RTMP or RTMPS streaming. When exceptions occur, you can troubleshoot issues by referring to the detailed error descriptions in the *errCode* parameter. - @param url The RTMP URL address. - @param state The RTMP streaming state. See: #RTMP_STREAM_PUBLISH_STATE. + @param url The CDN streaming URL. + @param state The RTMP or RTMPS streaming state. See: #RTMP_STREAM_PUBLISH_STATE. @param errCode The detailed error information for streaming. See: #RTMP_STREAM_PUBLISH_ERROR. */ virtual void onRtmpStreamingStateChanged(const char *url, RTMP_STREAM_PUBLISH_STATE state, RTMP_STREAM_PUBLISH_ERROR errCode) { @@ -4289,11 +4503,11 @@ class IRtcEngineEventHandler (void) errCode; } - /** Reports events during the RTMP streaming. + /** Reports events during the RTMP or RTMPS streaming. * * @since v3.1.0 * - * @param url The RTMP streaming URL. + * @param url The RTMP or RTMPS streaming URL. * @param eventCode The event code. See #RTMP_STREAMING_EVENT */ virtual void onRtmpStreamingEvent(const char* url, RTMP_STREAMING_EVENT eventCode) { @@ -4305,14 +4519,14 @@ class IRtcEngineEventHandler Reports the result of calling the \ref IRtcEngine::addPublishStreamUrl "addPublishStreamUrl" method. (CDN live only.) - @param url The RTMP URL address. + @param url The CDN streaming URL. @param error Error code: #ERROR_CODE_TYPE. Main errors include: - #ERR_OK (0): The publishing succeeds. - #ERR_FAILED (1): The publishing fails. - - #ERR_INVALID_ARGUMENT (2): Invalid argument used. If, for example, you did not call \ref agora::rtc::IRtcEngine::setLiveTranscoding "setLiveTranscoding" to configure LiveTranscoding before calling \ref agora::rtc::IRtcEngine::addPublishStreamUrl "addPublishStreamUrl", the SDK reports #ERR_INVALID_ARGUMENT. - - #ERR_TIMEDOUT (10): The publishing timed out. - - #ERR_ALREADY_IN_USE (19): The chosen URL address is already in use for CDN live streaming. - - #ERR_RESOURCE_LIMITED (22): The backend system does not have enough resources for the CDN live streaming. + - #ERR_INVALID_ARGUMENT (-2): Invalid argument used. If, for example, you did not call \ref agora::rtc::IRtcEngine::setLiveTranscoding "setLiveTranscoding" to configure LiveTranscoding before calling \ref agora::rtc::IRtcEngine::addPublishStreamUrl "addPublishStreamUrl", the SDK reports #ERR_INVALID_ARGUMENT. + - #ERR_TIMEDOUT (-10): The publishing timed out. + - #ERR_ALREADY_IN_USE (-19): The chosen URL address is already in use for CDN live streaming. + - #ERR_RESOURCE_LIMITED (-22): The backend system does not have enough resources for the CDN live streaming. - #ERR_ENCRYPTED_STREAM_NOT_ALLOWED_PUBLISH (130): You cannot publish an encrypted stream. - #ERR_PUBLISH_STREAM_CDN_ERROR (151) - #ERR_PUBLISH_STREAM_NUM_REACH_LIMIT (152) @@ -4328,23 +4542,23 @@ class IRtcEngineEventHandler Reports the result of calling the \ref agora::rtc::IRtcEngine::removePublishStreamUrl "removePublishStreamUrl" method. (CDN live only.) - This callback indicates whether you have successfully removed an RTMP stream from the CDN. + This callback indicates whether you have successfully removed an RTMP or RTMPS stream from the CDN. - @param url The RTMP URL address. + @param url The CDN streaming URL. */ virtual void onStreamUnpublished(const char *url) { (void)url; } -/** Occurs when the publisher's transcoding is updated. - * - * When the `LiveTranscoding` class in the \ref agora::rtc::IRtcEngine::setLiveTranscoding "setLiveTranscoding" method updates, the SDK triggers the `onTranscodingUpdated` callback to report the update information to the local host. - * - * @note If you call the `setLiveTranscoding` method to set the LiveTranscoding class for the first time, the SDK does not trigger the `onTranscodingUpdated` callback. - * - */ + /** Occurs when the publisher's transcoding is updated. + * + * When the `LiveTranscoding` class in the \ref agora::rtc::IRtcEngine::setLiveTranscoding "setLiveTranscoding" method updates, the SDK triggers the `onTranscodingUpdated` callback to report the update information to the local host. + * + * @note If you call the `setLiveTranscoding` method to set the LiveTranscoding class for the first time, the SDK does not trigger the `onTranscodingUpdated` callback. + * + */ virtual void onTranscodingUpdated() { } - /** Occurs when a voice or video stream URL address is added to the live interactive streaming. + /** Occurs when a voice or video stream URL address is added to the interactive live streaming. @param url Pointer to the URL address of the externally injected stream. @param uid User ID. @@ -4522,6 +4736,27 @@ class IRtcEngineEventHandler (void)uid; (void)info; } + /// @cond + /** Reports the result of uploading the SDK log files. + * + * @since v3.3.0 + * + * After the method call of \ref IRtcEngine::uploadLogFile "uploadLogFile", the SDK triggers this callback to report the + * result of uploading the log files. If the upload fails, refer to the `reason` parameter to troubleshoot. + * + * @param requestId The request ID. This request ID is the same as `requestId` returned by \ref IRtcEngine::uploadLogFile "uploadLogFile", + * and you can use `requestId` to match a specific upload with a callback. + * @param success Whether the log files are successfully uploaded. + * - true: Successfully uploads the log files. + * - false: Fails to upload the log files. For details, see the `reason` parameter. + * @param reason The reason for the upload failure. See #UPLOAD_ERROR_REASON. + */ + virtual void onUploadLogResult(const char* requestId, bool success, UPLOAD_ERROR_REASON reason) { + (void)requestId; + (void)success; + (void)reason; + } + /// @endcond }; /** @@ -4643,11 +4878,11 @@ class IAudioDeviceCollection virtual ~IAudioDeviceCollection(){} public: - /** Retrieves the total number of audio playback or audio recording devices. + /** Retrieves the total number of audio playback or audio capturing devices. - @note You must first call the \ref IAudioDeviceManager::enumeratePlaybackDevices "enumeratePlaybackDevices" or \ref IAudioDeviceManager::enumerateRecordingDevices "enumerateRecordingDevices" method before calling this method to return the number of audio playback or audio recording devices. + @note You must first call the \ref IAudioDeviceManager::enumeratePlaybackDevices "enumeratePlaybackDevices" or \ref IAudioDeviceManager::enumerateRecordingDevices "enumerateRecordingDevices" method before calling this method to return the number of audio playback or audio capturing devices. - @return Number of audio playback or audio recording devices. + @return Number of audio playback or audio capturing devices. */ virtual int getCount() = 0; @@ -4739,14 +4974,14 @@ class IAudioDeviceManager */ virtual IAudioDeviceCollection* enumeratePlaybackDevices() = 0; - /** Enumerates the audio recording devices. + /** Enumerates the audio capturing devices. - This method returns an IAudioDeviceCollection object that includes all audio recording devices in the system. With the IAudioDeviceCollection object, the application can enumerate the audio recording devices. + This method returns an IAudioDeviceCollection object that includes all audio capturing devices in the system. With the IAudioDeviceCollection object, the application can enumerate the audio capturing devices. @note The application needs to call the \ref IAudioDeviceCollection::release "release" method to release the returned object after using it. @return - - Returns an IAudioDeviceCollection object that includes all audio recording devices in the system: Success. + - Returns an IAudioDeviceCollection object that includes all audio capturing devices in the system: Success. - Returns NULL: Failure. */ virtual IAudioDeviceCollection* enumerateRecordingDevices() = 0; @@ -4763,9 +4998,9 @@ class IAudioDeviceManager */ virtual int setPlaybackDevice(const char deviceId[MAX_DEVICE_ID_LENGTH]) = 0; - /** Sets the audio recording device using the device ID. + /** Sets the audio capturing device using the device ID. - @param deviceId Device ID of the audio recording device, retrieved by calling the \ref IAudioDeviceManager::enumerateRecordingDevices "enumerateRecordingDevices" method. + @param deviceId Device ID of the audio capturing device, retrieved by calling the \ref IAudioDeviceManager::enumerateRecordingDevices "enumerateRecordingDevices" method. @note Plugging or unplugging the audio device does not change the device ID. @@ -4776,16 +5011,25 @@ class IAudioDeviceManager virtual int setRecordingDevice(const char deviceId[MAX_DEVICE_ID_LENGTH]) = 0; /** Starts the audio playback device test. - - This method tests if the playback device works properly. In the test, the SDK plays an audio file specified by the user. If the user can hear the audio, the playback device works properly. - - @param testAudioFilePath Pointer to the path of the audio file for the audio playback device test in UTF-8: - - Supported file formats: wav, mp3, m4a, and aac. - - Supported file sample rates: 8000, 16000, 32000, 44100, and 48000 Hz. - - @return - - 0: Success, and you can hear the sound of the specified audio file. - - < 0: Failure. + * + * This method tests if the audio playback device works properly. Once a user starts the test, the SDK plays an + * audio file specified by the user. If the user can hear the audio, the playback device works properly. + * + * After calling this method, the SDK triggers the + * \ref IRtcEngineEventHandler::onAudioVolumeIndication "onAudioVolumeIndication" callback every 100 ms, which + * reports `uid = 1` and the volume of the playback device. + * + * @note + * - Call this method before joining a channel. + * - This method is for Windows and macOS only. + * + * @param testAudioFilePath Pointer to the path of the audio file for the audio playback device test in UTF-8: + * - Supported file formats: wav, mp3, m4a, and aac. + * - Supported file sample rates: 8000, 16000, 32000, 44100, and 48000 Hz. + * + * @return + * - 0: Success, and you can hear the sound of the specified audio file. + * - < 0: Failure. */ virtual int startPlaybackDeviceTest(const char* testAudioFilePath) = 0; @@ -4881,11 +5125,21 @@ class IAudioDeviceManager */ virtual int getRecordingDeviceMute(bool *mute) = 0; - /** Starts the microphone test. + /** Starts the audio capturing device test. + + This method tests whether the audio sampling device works properly. - This method tests whether the microphone works properly. Once the test starts, the SDK uses the \ref IRtcEngineEventHandler::onAudioVolumeIndication "onAudioVolumeIndication" callback to notify the application with the volume information. + After calling this method, the SDK triggers the + \ref IRtcEngineEventHandler::onAudioVolumeIndication "onAudioVolumeIndication" callback at the time interval set + in this method, which reports `uid = 0` and the volume of the sampling device. + + @note + - Call this method before joining a channel. + - This method is for Windows and macOS only. - @param indicationInterval Interval period (ms) of the \ref IRtcEngineEventHandler::onAudioVolumeIndication "onAudioVolumeIndication" callback cycle. + @param indicationInterval The time interval (ms) at which the `onAudioVolumeIndication` callback returns. We + recommend a setting greater than 200 ms. This value must not be less than 10 ms; otherwise, you can not receive + the `onAudioVolumeIndication` callback. @return - 0: Success. @@ -4922,36 +5176,47 @@ class IAudioDeviceManager */ virtual int getPlaybackDeviceInfo(char deviceId[MAX_DEVICE_ID_LENGTH], char deviceName[MAX_DEVICE_ID_LENGTH]) = 0; - /** Retrieves the audio recording device associated with the device ID. + /** Retrieves the audio capturing device associated with the device ID. - @param deviceId Pointer to the device ID of the audio recording device. + @param deviceId Pointer to the device ID of the audio capturing device. @return - 0: Success. - < 0: Failure. */ virtual int getRecordingDevice(char deviceId[MAX_DEVICE_ID_LENGTH]) = 0; - /** Retrieves the audio recording device information associated with the device ID and device name. + /** Retrieves the audio capturing device information associated with the device ID and device name. - @param deviceId Pointer to the device ID of the recording audio device. - @param deviceName Pointer to the device name of the recording audio device. + @param deviceId Pointer to the device ID of the audio capturing device. + @param deviceName Pointer to the device name of the audio capturing device. @return - 0: Success. - < 0: Failure. */ virtual int getRecordingDeviceInfo(char deviceId[MAX_DEVICE_ID_LENGTH], char deviceName[MAX_DEVICE_ID_LENGTH]) = 0; - /** Starts the audio device loopback test. - - This method tests whether the local audio devices are working properly. After calling this method, the microphone captures the local audio and plays it through the speaker. The \ref IRtcEngineEventHandler::onAudioVolumeIndication "onAudioVolumeIndication" callback returns the local audio volume information at the set interval. - - @note This method tests the local audio devices and does not report the network conditions. - - @param indicationInterval The time interval (ms) at which the \ref IRtcEngineEventHandler::onAudioVolumeIndication "onAudioVolumeIndication" callback returns. - - @return - - 0: Success. - - < 0: Failure. + /** Starts the audio device loopback test. + * + * This method tests whether the local audio sampling device and playback device are working properly. After calling + * this method, the audio sampling device samples the local audio, and the audio playback device plays the sampled + * audio. The SDK triggers two independent + * \ref IRtcEngineEventHandler::onAudioVolumeIndication "onAudioVolumeIndication" callbacks at the time interval set + * in this method, which reports the following information: + * - `uid = 0` and the volume information of the sampling device. + * - `uid = 1` and the volume information of the playback device. + * + * @note + * - Call this method before joining a channel. + * - This method tests local audio devices and does not report the network conditions. + * - This method is for Windows and macOS only. + * + * @param indicationInterval The time interval (ms) at which the `onAudioVolumeIndication` callback returns. We + * recommend a setting greater than 200 ms. This value must not be less than 10 ms; otherwise, you can not receive + * the `onAudioVolumeIndication` callback. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int startAudioDeviceLoopbackTest(int indicationInterval) = 0; @@ -4970,6 +5235,41 @@ class IAudioDeviceManager virtual void release() = 0; }; +/** The configuration of the log files. + * + * @since v3.3.0 + */ +struct LogConfig +{ + /** The absolute path of log files. + * + * The default file path is: + * - Android: `/storage/emulated/0/Android/data//files/agorasdk.log` + * - iOS: `App Sandbox/Library/caches/agorasdk.log` + * - macOS: + * - Sandbox enabled: `App Sandbox/Library/Logs/agorasdk.log`, such as `/Users//Library/Containers//Data/Library/Logs/agorasdk.log`. + * - Sandbox disabled: `～/Library/Logs/agorasdk.log`. + * - Windows: `C:\Users\\AppData\Local\Agora\\agorasdk.log` + * + * Ensure that the directory for the log files exists and is writable. You can use this parameter to rename the log files. + */ + const char* filePath; + /** The size (KB) of a log file. The default value is 1024 KB. If you set `fileSize` to 1024 KB, the SDK outputs at most 5 MB log files; + * if you set it to less than 1024 KB, the setting is invalid, and the maximum size of a log file is still 1024 KB. + */ + int fileSize; + /** The output log level of the SDK. See #LOG_LEVEL. + * + * For example, if you set the log level to WARN, the SDK outputs the logs within levels FATAL, ERROR, and WARN. + */ + LOG_LEVEL level; + LogConfig() + :filePath(NULL) + ,fileSize(-1) + ,level(LOG_LEVEL::LOG_LEVEL_INFO) + {} +}; + /** Definition of RtcEngineContext. */ struct RtcEngineContext @@ -4998,6 +5298,17 @@ struct RtcEngineContext * @note The SDK supports specify only one region. */ unsigned int areaCode; + /** The configuration of the log files that the SDK outputs. See LogConfig. + * + * @since v3.3.0 + * + * By default, the SDK outputs five log files, `agorasdk.log`, `agorasdk_1.log`, `agorasdk_2.log`, `agorasdk_3.log`, `agorasdk_4.log`, each with + * a default size of 1024 KB. These log files are encoded in UTF-8. The SDK writes the latest logs in `agorasdk.log`. When `agorasdk.log` is + * full, the SDK deletes the log file with the earliest modification time among the other four, renames `agorasdk.log` to the name of the + * deleted log file, and creates a new `agorasdk.log` to record latest logs. + * + */ + LogConfig logConfig; RtcEngineContext() :eventHandler(NULL) ,appId(NULL) @@ -5090,9 +5401,17 @@ enum ENCRYPTION_MODE /** 3: 256-bit AES encryption, XTS mode. */ AES_256_XTS = 3, + /// @cond /** 4: 128-bit SM4 encryption, ECB mode. */ SM4_128_ECB = 4, + /// @endcond + /** 5: 128-bit AES encryption, GCM mode. + */ + AES_128_GCM = 5, + /** 6: 256-bit AES encryption, GCM mode. + */ + AES_256_GCM = 6, /** Enumerator boundary. */ MODE_END, @@ -5128,6 +5447,10 @@ struct EncryptionConfig{ return "aes-256-xts"; case SM4_128_ECB: return "sm4-128-ecb"; + case AES_128_GCM: + return "aes-128-gcm"; + case AES_256_GCM: + return "aes-256-gcm"; default: return "aes-128-xts"; } @@ -5136,6 +5459,31 @@ struct EncryptionConfig{ /// @endcond }; +/** The channel media options. + */ +struct ChannelMediaOptions { + /** Determines whether to automatically subscribe to all remote audio streams when the user joins a channel: + - true: (Default) Subscribe. + - false: Do not subscribe. + + This member serves a similar function to the `muteAllRemoteAudioStreams` method. After joining the channel, + you can call the `muteAllRemoteAudioStreams` method to set whether to subscribe to audio streams in the channel. + */ + bool autoSubscribeAudio; + /** Determines whether to subscribe to video streams when the user joins the channel: + - true: (Default) Subscribe. + - false: Do not subscribe. + + This member serves a similar function to the `muteAllRemoteVideoStreams` method. After joining the channel, + you can call the `muteAllRemoteVideoStreams` method to set whether to subscribe to video streams in the channel. + */ + bool autoSubscribeVideo; + ChannelMediaOptions() + : autoSubscribeAudio(true) + , autoSubscribeVideo(true) + {} +}; + /** IRtcEngine is the base interface class of the Agora SDK that provides the main Agora SDK methods invoked by your application. Enable the Agora SDK's communication functionality through the creation of an IRtcEngine object, then call the methods of this object. @@ -5194,7 +5542,7 @@ class IRtcEngine /** Sets the channel profile of the Agora IRtcEngine. * * The Agora IRtcEngine differentiates channel profiles and applies optimization algorithms accordingly. - * For example, it prioritizes smoothness and low latency for a video call, and prioritizes video quality for the live interactive video streaming. + * For example, it prioritizes smoothness and low latency for a video call, and prioritizes video quality for the interactive live video streaming. * * @warning * - To ensure the quality of real-time communication, we recommend that all users in a channel use the same channel profile. @@ -5211,9 +5559,9 @@ class IRtcEngine */ virtual int setChannelProfile(CHANNEL_PROFILE_TYPE profile) = 0; - /** Sets the role of the user, such as a host or an audience (default), before joining a channel in the live interactive streaming. + /** Sets the role of the user, such as a host or an audience (default), before joining a channel in the interactive live streaming. * - * This method can be used to switch the user role in the live interactive streaming after the user joins a channel. + * This method can be used to switch the user role in the interactive live streaming after the user joins a channel. * * In the `LIVE_BROADCASTING` profile, when a user switches user roles after joining a channel, a successful \ref agora::rtc::IRtcEngine::setClientRole "setClientRole" method call triggers the following callbacks: * - The local client: \ref agora::rtc::IRtcEngineEventHandler::onClientRoleChanged "onClientRoleChanged" @@ -5232,8 +5580,8 @@ class IRtcEngine * - -7(ERR_NOT_INITIALIZED): The SDK is not initialized. */ virtual int setClientRole(CLIENT_ROLE_TYPE role) = 0; - /// @cond - /** Sets the role of a user in a live interactive streaming. + + /** Sets the role of a user in interactive live streaming. * * @since v3.2.0 * @@ -5246,7 +5594,7 @@ class IRtcEngine * @note * - This method applies to the `LIVE_BROADCASTING` profile only (when the `profile` parameter in * \ref IRtcEngine::setChannelProfile "setChannelProfile" is set as `CHANNEL_PROFILE_LIVE_BROADCASTING`). - * - The difference between this method and \ref IRtcEngine::setClientRole(CLIENT_ROLE_TYPE) "setClientRole1" is that + * - The difference between this method and \ref IRtcEngine::setClientRole(CLIENT_ROLE_TYPE) "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. @@ -5254,15 +5602,7 @@ class IRtcEngine * role. For example, an audience can choose to receive remote streams with low latency or ultra low latency. Levels * affect prices. * - * **Example** - * ```cpp - * ClientRoleOptions options; - * options.audienceLatencyLevel = AUDIENCE_LATENCY_LEVEL_ULTRA_LOW_LATENCY; - * options.audienceLatencyLevel = AUDIENCE_LATENCY_LEVEL_LOW_LATENCY; - * agoraEngine->setClientRole(role, options); - * ``` - * - * @param role The role of a user in a live interactive streaming. See #CLIENT_ROLE_TYPE. + * @param role The role of a user in interactive live streaming. See #CLIENT_ROLE_TYPE. * @param options The detailed options of a user, including user level. See ClientRoleOptions. * * @return @@ -5273,7 +5613,7 @@ class IRtcEngine * - -7(ERR_NOT_INITIALIZED): The SDK is not initialized. */ virtual int setClientRole(CLIENT_ROLE_TYPE role, const ClientRoleOptions& options) = 0; - /// @endcond + /** Joins a channel with the user ID. Users in the same channel can talk to each other, and multiple users in the same channel can start a group chat. Users with different App IDs cannot call each other. @@ -5282,11 +5622,13 @@ class IRtcEngine You must call the \ref IRtcEngine::leaveChannel "leaveChannel" method to exit the current call before entering another channel. A successful \ref agora::rtc::IRtcEngine::joinChannel "joinChannel" method call triggers the following callbacks: - - The local client: \ref agora::rtc::IRtcEngineEventHandler::onJoinChannelSuccess "onJoinChannelSuccess" + - The local client: \ref agora::rtc::IRtcEngineEventHandler::onJoinChannelSuccess "onJoinChannelSuccess". - The remote client: \ref agora::rtc::IRtcEngineEventHandler::onUserJoined "onUserJoined" , if the user joining the channel is in the `COMMUNICATION` profile, or is a host in the `LIVE_BROADCASTING` profile. When the connection between the client and Agora's server is interrupted due to poor network conditions, the SDK tries reconnecting to the server. When the local client successfully rejoins the channel, the SDK triggers the \ref agora::rtc::IRtcEngineEventHandler::onRejoinChannelSuccess "onRejoinChannelSuccess" callback on the local client. + 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. + @note A channel does not accept duplicate uids, such as two users with the same @p uid. If you set @p uid as 0, the system automatically assigns a @p uid. If you want to join a channel from different devices, ensure that each device has a different uid. @warning Ensure that the App ID used for creating the token is the same App ID used by the \ref IRtcEngine::initialize "initialize" method for initializing the RTC engine. Otherwise, the CDN live streaming may fail. @@ -5300,7 +5642,7 @@ class IRtcEngine - The space character. - Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",". @param info (Optional) Pointer to additional information about the channel. This parameter can be set to NULL or contain channel related information. Other users in the channel will not receive this message. - @param uid (Optional) User ID. A 32-bit unsigned integer with a value ranging from 1 to 232-1. The @p uid must be unique. If a @p uid is not assigned (or set to 0), the SDK assigns and returns a @p uid in the \ref IRtcEngineEventHandler::onJoinChannelSuccess "onJoinChannelSuccess" callback. Your application must record and maintain the returned *uid* since the SDK does not do so. + @param uid (Optional) User ID. A 32-bit unsigned integer with a value ranging from 1 to 232-1. The @p uid must be unique. If a @p uid is not assigned (or set to 0), the SDK assigns and returns a @p uid in the \ref IRtcEngineEventHandler::onJoinChannelSuccess "onJoinChannelSuccess" callback. Your application must record and maintain the returned `uid`, because the SDK does not do so. @return - 0(ERR_OK): Success. @@ -5310,8 +5652,60 @@ class IRtcEngine - -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. + - -7(ERR_NOT_INITIALIZED): The SDK is not initialized before calling this method. */ virtual int joinChannel(const char* token, const char* channelId, const char* info, uid_t uid) = 0; + /** Joins a channel with the user ID, and configures whether to automatically subscribe to the audio or video streams. + * + * @since v3.3.0 + * + * Users in the same channel can talk to each other, and multiple users in the same channel can start a group chat. Users with different App IDs cannot call each other. + * + * You must call the \ref IRtcEngine::leaveChannel "leaveChannel" method to exit the current call before entering another channel. + * + * A successful \ref IRtcEngine::joinChannel "joinChannel" method call triggers the following callbacks: + * - The local client: \ref IRtcEngineEventHandler::onJoinChannelSuccess "onJoinChannelSuccess". + * - The remote client: \ref IRtcEngineEventHandler::onUserJoined "onUserJoined", if the user joining the channel is in the `COMMUNICATION` profile, or is a host in the `LIVE_BROADCASTING` profile. + * + * When the connection between the client and the Agora server is interrupted due to poor network conditions, the SDK tries reconnecting to the server. + * When the local client successfully rejoins the channel, the SDK triggers the \ref IRtcEngineEventHandler::onRejoinChannelSuccess "onRejoinChannelSuccess" callback on the local client. + * + * @note + * - Compared with \ref IRtcEngine::joinChannel(const char* token, const char* channelId, const char* info, uid_t uid) "joinChannel" [1/2], this method + * has the options parameter which configures whether the user automatically subscribes to all remote audio and video streams in the channel when + * joining the channel. By default, the user subscribes to the audio and video streams of all the other users in the channel, thus incurring all + * associated usage costs. To unsubscribe, set the `options` parameter or call the `mute` methods accordingly. + * - Ensure that the App ID used for generating the token is the same App ID used in the \ref IRtcEngine::initialize "initialize" method for + * creating an `IRtcEngine` object. + * + * @param token The token generated at your server. For details, see [Generate a token](https://docs.agora.io/en/Interactive%20Broadcast/token_server?platform=Windows). + * @param channelId Pointer to the unique channel name for the Agora RTC session in the string format smaller than 64 bytes. Supported characters: + * - 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: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",". + * @param info (Optional) Reserved for future use. + * @param uid (Optional) User ID. A 32-bit unsigned integer with a value ranging from 1 to 232-1. The @p uid must be unique. If a @p uid is + * not assigned (or set to 0), the SDK assigns and returns a @p uid in the \ref IRtcEngineEventHandler::onJoinChannelSuccess "onJoinChannelSuccess" callback. + * Your application must record and maintain the returned `uid`, because the SDK does not do so. **Note**: The ID of each user in the channel should be unique. + * If you want to join the same channel from different devices, ensure that the user IDs in all devices are different. + * @param options The channel media options: ChannelMediaOptions. + @return + * - 0(ERR_OK): Success. + * - < 0: Failure. + * - -2(ERR_INALID_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. + * - -7(ERR_NOT_INITIALIZED): The SDK is not initialized before calling this method. + */ + virtual int joinChannel(const char* token, + const char* channelId, + const char* info, + uid_t uid, + const ChannelMediaOptions& options) = 0; /** Switches to a different channel. * * This method allows the audience of a `LIVE_BROADCASTING` channel to switch @@ -5323,6 +5717,12 @@ class IRtcEngine * "onJoinChannelSuccess" callbacks are triggered to indicate that the * user has left the original channel and joined a new one. * + * Once the user switches to another 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. + * * @note * This method applies to the audience role in a `LIVE_BROADCASTING` channel * only. @@ -5354,6 +5754,45 @@ class IRtcEngine * - -113(ERR_NOT_IN_CHANNEL): The user is not in the channel. */ virtual int switchChannel(const char* token, const char* channelId) = 0; + /** Switches to a different channel, and configures whether to automatically subscribe to audio or video streams in the target channel. + * + * @since v3.3.0 + * + * This method allows the audience of a `LIVE_BROADCASTING` channel to switch to a different channel. + * + * After the user successfully switches to another channel, the \ref IRtcEngineEventHandler::onLeaveChannel "onLeaveChannel" + * and \ref IRtcEngineEventHandler::onJoinChannelSuccess "onJoinChannelSuccess" callbacks are triggered to indicate that + * the user has left the original channel and joined a new one. + * + * @note + * - This method applies to the audience role in a `LIVE_BROADCASTING` channel only. + * - The difference between this method and \ref IRtcEngine::switchChannel(const char* token, const char* channelId) "switchChannel[1/2]" + * is that the former adds the options parameter to configure whether the user automatically subscribes to all remote audio and video streams in the target channel. + * By default, the user subscribes to the audio and video streams of all the other users in the target channel, thus incurring all associated usage costs. + * To unsubscribe, set the `options` parameter or call the `mute` methods accordingly. + * + * @param token The token generated at your server. For details, see [Generate a token](https://docs.agora.io/en/Interactive%20Broadcast/token_server?platform=Windows). + * @param channelId Unique channel name for the AgoraRTC session in the + * string format. The string length must be less than 64 bytes. 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: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",". + * @param options The channel media options: ChannelMediaOptions. + * + * @return + * - 0(ERR_OK): Success. + * - < 0: Failure. + * - -1(ERR_FAILED): A general error occurs (no specified reason). + * - -2(ERR_INALID_ARGUMENT): The parameter is invalid. + * - -5(ERR_REFUSED): The request is rejected, probably because the user is not an audience. + * - -7(ERR_NOT_INITIALIZED): The SDK is not initialized. + * - -102(ERR_INVALID_CHANNEL_NAME): The channel name is invalid. + * - -113(ERR_NOT_IN_CHANNEL): The user is not in the channel. + */ + virtual int switchChannel(const char* token, const char* channelId, const ChannelMediaOptions& options) = 0; /** Allows a user to leave a channel, such as hanging up or exiting a call. @@ -5430,7 +5869,7 @@ class IRtcEngine - 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. @param appId The App ID of your project. - @param userAccount The user account. The maximum length of this parameter is 255 bytes. Ensure that you set this parameter and do not set it as null. Supported character scopes are: + @param 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. @@ -5448,7 +5887,9 @@ class IRtcEngine After the user successfully joins the channel, the SDK triggers the following callbacks: - The local client: \ref agora::rtc::IRtcEngineEventHandler::onLocalUserRegistered "onLocalUserRegistered" and \ref agora::rtc::IRtcEngineEventHandler::onJoinChannelSuccess "onJoinChannelSuccess" . - The remote client: \ref agora::rtc::IRtcEngineEventHandler::onUserJoined "onUserJoined" and \ref agora::rtc::IRtcEngineEventHandler::onUserInfoUpdated "onUserInfoUpdated" , if the user joining the channel is in the `COMMUNICATION` profile, or is a host in the `LIVE_BROADCASTING` profile. + - The remote client: \ref agora::rtc::IRtcEngineEventHandler::onUserJoined "onUserJoined" and \ref agora::rtc::IRtcEngineEventHandler::onUserInfoUpdated "onUserInfoUpdated" , if the user joining the channel is in the `COMMUNICATION` profile, or is a host in the `LIVE_BROADCASTING` profile. + + 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. @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. @@ -5462,7 +5903,7 @@ class IRtcEngine - All numeric characters: 0 to 9. - The space character. - Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",". - @param userAccount The user account. The maximum length of this parameter is 255 bytes. Ensure that you set this parameter and do not set it as null. Supported character scopes are: + @param 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. @@ -5479,6 +5920,48 @@ class IRtcEngine virtual int joinChannelWithUserAccount(const char* token, const char* channelId, const char* userAccount) = 0; + /** Joins the channel with a user account, and configures whether to automatically subscribe to audio or video streams after joining the channel. + * + * @since v3.3.0 + * + * After the user successfully joins the channel, the SDK triggers the following callbacks: + * - The local client: \ref agora::rtc::IRtcEngineEventHandler::onLocalUserRegistered "onLocalUserRegistered" and \ref agora::rtc::IRtcEngineEventHandler::onJoinChannelSuccess "onJoinChannelSuccess" . + * - The remote client: \ref agora::rtc::IRtcEngineEventHandler::onUserJoined "onUserJoined" and \ref agora::rtc::IRtcEngineEventHandler::onUserInfoUpdated "onUserInfoUpdated" , if the user joining the channel is in the `COMMUNICATION` profile, or is a host in the `LIVE_BROADCASTING` profile. + * + * @note + * - Compared with \ref IRtcEngine::joinChannelWithUserAccount(const char* token, const char* channelId, const char* userAccount) "joinChannelWithUserAccount" [1/2], + * this method has the options parameter to configure whether the end user automatically subscribes to all remote audio and video streams in a + * channel when joining the channel. By default, the user subscribes to the audio and video streams of all the other users in the channel, thus + * incurring all associated usage costs. To unsubscribe, set the `options` parameter or call the `mute` methods accordingly. + * - 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. + * + * @param token The token generated at your server. For details, see [Generate a token](https://docs.agora.io/en/Interactive%20Broadcast/token_server?platform=Windows). + * @param channelId The channel name. The maximum length of this parameter is 64 bytes. 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: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",". + * @param 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: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",". + * @param options The channel media options: ChannelMediaOptions. + * @return + * - 0: Success. + * - < 0: Failure. + * - #ERR_INVALID_ARGUMENT (-2) + * - #ERR_NOT_READY (-3) + * - #ERR_REFUSED (-5) + */ + virtual int joinChannelWithUserAccount(const char* token, + const char* channelId, + const char* userAccount, + const ChannelMediaOptions& options) = 0; /** Gets the user information by passing in the user account. @@ -5563,7 +6046,32 @@ class IRtcEngine - < 0: Failure. */ virtual int stopEchoTest() = 0; - + /** Sets the Agora cloud proxy service. + * + * @since v3.3.0 + * + * When the user's firewall restricts the IP address and port, refer to *Use Cloud Proxy* to add the specific + * IP addresses and ports to the firewall whitelist; then, call this method to enable the cloud proxy and set + * the `proxyType` parameter as `UDP_PROXY(1)`, which is the cloud proxy for the UDP protocol. + * + * After a successfully cloud proxy connection, the SDK triggers the \ref IRtcEngineEventHandler::onConnectionStateChanged "onConnectionStateChanged" (CONNECTION_STATE_CONNECTING, CONNECTION_CHANGED_SETTING_PROXY_SERVER) callback. + * + * To disable the cloud proxy that has been set, call `setCloudProxy(NONE_PROXY)`. To change the cloud proxy type that has been set, + * call `setCloudProxy(NONE_PROXY)` first, and then call `setCloudProxy`, and pass the value that you expect in `proxyType`. + * + * @note + * - Agora recommends that you call this method before joining the channel or after leaving the channel. + * - When you use the cloud proxy for the UDP protocol, the services for pushing streams to CDN and co-hosting across channels are not available. + * + * @param proxyType The cloud proxy type, see #CLOUD_PROXY_TYPE. This parameter is required, and the SDK reports an error if you do not pass in a value. + * + * @return + * - 0: Success. + * - < 0: Failure. + * - `-2（ERR_INVALID_ARGUMENT)`: The parameter is invalid. + * - `-7(ERR_NOT_INITIALIZED)`: The SDK is not initialized. + */ + virtual int setCloudProxy(CLOUD_PROXY_TYPE proxyType) = 0; /** Enables the video module. Call this method either before joining a channel or during a call. If this method is called before joining a channel, the call starts in the video mode. If this method is called during an audio call, the audio mode switches to the video mode. To disable the video module, call the \ref IRtcEngine::disableVideo "disableVideo" method. @@ -5644,11 +6152,12 @@ class IRtcEngine virtual int setVideoEncoderConfiguration(const VideoEncoderConfiguration& config) = 0; /** Sets the camera capture configuration. - For a video call or the live interactive video streaming, generally the SDK controls the camera output parameters. When the default camera capturer settings do not meet special requirements or cause performance problems, we recommend using this method to set the camera capturer configuration: + For a video call or the interactive live video streaming, generally the SDK controls the camera output parameters. When the default camera capturer settings do not meet special requirements or cause performance problems, we recommend using this method to set the camera capturer configuration: - - If the resolution or frame rate of the captured raw video data are higher than those set by \ref IRtcEngine::setVideoEncoderConfiguration "setVideoEncoderConfiguration", processing video frames requires extra CPU and RAM usage and degrades performance. We recommend setting config as CAPTURER_OUTPUT_PREFERENCE_PERFORMANCE = 1 to avoid such problems. - - If you do not need local video preview or are willing to sacrifice preview quality, we recommend setting config as CAPTURER_OUTPUT_PREFERENCE_PERFORMANCE = 1 to optimize CPU and RAM usage. - - If you want better quality for the local video preview, we recommend setting config as CAPTURER_OUTPUT_PREFERENCE_PREVIEW = 2. + - If the resolution or frame rate of the captured raw video data are higher than those set by \ref IRtcEngine::setVideoEncoderConfiguration "setVideoEncoderConfiguration", processing video frames requires extra CPU and RAM usage and degrades performance. We recommend setting config as #CAPTURER_OUTPUT_PREFERENCE_PERFORMANCE (1) to avoid such problems. + - If you do not need local video preview or are willing to sacrifice preview quality, we recommend setting config as #CAPTURER_OUTPUT_PREFERENCE_PERFORMANCE (1) to optimize CPU and RAM usage. + - If you want better quality for the local video preview, we recommend setting config as #CAPTURER_OUTPUT_PREFERENCE_PREVIEW (2). + - To customize the width and height of the video image captured by the local camera, set the camera capture configuration as #CAPTURER_OUTPUT_PREFERENCE_MANUAL (3). @note Call this method before enabling the local camera. That said, you can call this method before calling \ref agora::rtc::IRtcEngine::joinChannel "joinChannel", \ref agora::rtc::IRtcEngine::enableVideo "enableVideo", or \ref IRtcEngine::enableLocalVideo "enableLocalVideo", depending on which method you use to turn on your local camera. @@ -5742,8 +6251,8 @@ class IRtcEngine The audio mode is enabled by default. @note - - This method affects the internal engine and can be called after the \ref agora::rtc::IRtcEngine::leaveChannel "leaveChannel" method. You can call this method either before or after joining a channel. - - This method resets the internal engine and takes some time to take effect. We recommend using the following API methods to control the audio engine modules separately: + - This method affects the audio module and can be called after the \ref agora::rtc::IRtcEngine::leaveChannel "leaveChannel" method. You can call this method either before or after joining a channel. + - This method enables the audio module and takes some time to take effect. Agora recommends using the following API methods to control the audio module separately: - \ref IRtcEngine::enableLocalAudio "enableLocalAudio": Whether to enable the microphone to create the local audio stream. - \ref IRtcEngine::muteLocalAudioStream "muteLocalAudioStream": Whether to publish the local audio stream. - \ref IRtcEngine::muteRemoteAudioStream "muteRemoteAudioStream": Whether to subscribe to and play the remote audio stream. @@ -5768,7 +6277,7 @@ class IRtcEngine @note - This method is different from the \ref agora::rtc::IRtcEngine::muteLocalAudioStream "muteLocalAudioStream" method: - \ref agora::rtc::IRtcEngine::enableLocalAudio "enableLocalAudio": Disables/Re-enables the local audio capturing and processing. - If you disable or re-enable local audio recording using the `enableLocalAudio` method, the local user may hear a pause in the remote audio playback. + If you disable or re-enable local audio capturing using the `enableLocalAudio` method, the local user may hear a pause in the remote audio playback. - \ref agora::rtc::IRtcEngine::muteLocalAudioStream "muteLocalAudioStream": Sends/Stops sending the local audio streams. - You can call this method either before or after joining a channel. @@ -5811,56 +6320,70 @@ class IRtcEngine - < 0: Failure. */ virtual int setAudioProfile(AUDIO_PROFILE_TYPE profile, AUDIO_SCENARIO_TYPE scenario) = 0; - /** Stops/Resumes sending the local audio stream. - - A successful \ref agora::rtc::IRtcEngine::muteLocalAudioStream "muteLocalAudioStream" method call triggers the \ref agora::rtc::IRtcEngineEventHandler::onUserMuteAudio "onUserMuteAudio" callback on the remote client. - - @note - - When @p mute is set as @p true, this method does not disable the microphone, which does not affect any ongoing recording. - - You can call this method either before or after joining a channel. If you call \ref agora::rtc::IRtcEngine::setChannelProfile "setChannelProfile" after this method, the SDK resets whether or not to mute the local audio according to the channel profile and user role. Therefore, we recommend calling this method after the `setChannelProfile` method. - - @param mute Sets whether to send/stop sending the local audio stream: - - true: Stops sending the local audio stream. - - false: (Default) Sends the local audio stream. - - @return - - 0: Success. - - < 0: Failure. + /** + * Stops or resumes publishing the local audio stream. + * + * A successful \ref agora::rtc::IRtcEngine::muteLocalAudioStream "muteLocalAudioStream" method call + * triggers the \ref agora::rtc::IRtcEngineEventHandler::onUserMuteAudio "onUserMuteAudio" callback on the remote client. + * + * @note + * - When @p mute is set as @p true, this method does not affect any ongoing audio recording, because it does not disable the microphone. + * - You can call this method either before or after joining a channel. If you call \ref agora::rtc::IRtcEngine::setChannelProfile "setChannelProfile" + * after this method, the SDK resets whether or not to stop publishing the local audio according to the channel profile and user role. + * Therefore, we recommend calling this method after the `setChannelProfile` method. + * + * @param mute Sets whether to stop publishing the local audio stream. + * - true: Stop publishing the local audio stream. + * - false: (Default) Resumes publishing the local audio stream. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int muteLocalAudioStream(bool mute) = 0; - /** Stops/Resumes receiving all remote users' audio streams. - - @note You can call this method either before or after joining a channel. - - @param mute Sets whether to receive/stop receiving all remote users' audio streams. - - true: Stops receiving all remote users' audio streams. - - false: (Default) Receives all remote users' audio streams. - - @return - - 0: Success. - - < 0: Failure. + /** + * Stops or resumes subscribing to the audio streams of all remote users. + * + * 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. + * + * @note + * - Call this method after joining a channel. + * - See recommended settings in *Set the Subscribing State*. + * + * @param mute Sets whether to stop subscribing to the audio streams of all remote users. + * - true: Stop subscribing to the audio streams of all remote users. + * - false: (Default) Resume subscribing to the audio streams of all remote users. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int muteAllRemoteAudioStreams(bool mute) = 0; - /** Stops/Resumes receiving all remote users' audio streams by default. - - You can call this method either before or after joining a channel. If you call `setDefaultMuteAllRemoteAudioStreams (true)` after joining a channel, the remote audio streams of all subsequent users are not received. - - @note If you want to resume receiving the audio stream, call \ref agora::rtc::IRtcEngine::muteRemoteAudioStream "muteRemoteAudioStream (false)", - and specify the ID of the remote user whose audio stream you want to receive. - To receive the audio streams of multiple remote users, call `muteRemoteAudioStream (false)` as many times. - Calling `setDefaultMuteAllRemoteAudioStreams (false)` resumes receiving the audio streams of subsequent users only. - - @param mute Sets whether to receive/stop receiving all remote users' audio streams by default: - - true: Stops receiving all remote users' audio streams by default. - - false: (Default) Receives all remote users' audio streams by default. - - @return - - 0: Success. - - < 0: Failure. + /** 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 \ref IRtcEngine::setDefaultMuteAllRemoteAudioStreams "setDefaultMuteAllRemoteAudioStreams" (true), do the following: + * - If you need to resume subscribing to the audio stream of a specified user, call \ref IRtcEngine::muteRemoteAudioStream "muteRemoteAudioStream" (false), and specify the user ID. + * - If you need to resume subscribing to the audio streams of multiple remote users, call \ref IRtcEngine::muteRemoteAudioStream "muteRemoteAudioStream" (false) multiple times. + * + * @param mute Sets whether to stop subscribing to the audio streams of all remote users by default. + * - true: Stop subscribing to the audio streams of all remote users by default. + * - false: (Default) Resume subscribing to the audio streams of all remote users by default. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int setDefaultMuteAllRemoteAudioStreams(bool mute) = 0; - /** Adjusts the playback volume of a specified remote user. + /** Adjusts the playback signal volume of a specified remote user. You can call this method as many times as necessary to adjust the playback volume of different remote users, or to repeatedly adjust the playback volume of the same remote user. @@ -5879,39 +6402,44 @@ class IRtcEngine - < 0: Failure. */ virtual int adjustUserPlaybackSignalVolume(unsigned int uid, int volume) = 0; - /** Stops/Resumes receiving a specified remote user's audio stream. - - @note - - You can call this method either before or after joining a channel. If you call it before joining a channel, - you need to maintain the `uid` of the remote user on your app level. - - If you called the \ref agora::rtc::IRtcEngine::muteAllRemoteAudioStreams "muteAllRemoteAudioStreams" method and set @p mute as @p true to stop receiving all remote users' audio streams, call the *muteAllRemoteAudioStreams* method and set @p mute as @p false before calling this method. The *muteAllRemoteAudioStreams* method sets all remote audio streams, while the *muteRemoteAudioStream* method sets a specified remote audio stream. - - @param userId User ID of the specified remote user sending the audio. - @param mute Sets whether to receive/stop receiving a specified remote user's audio stream: - - true: Stops receiving the specified remote user's audio stream. - - false: (Default) Receives the specified remote user's audio stream. - - @return - - 0: Success. - - < 0: Failure. - + /** + * Stops or resumes subscribing to the audio stream of a specified user. + * + * @note + * - Call this method after joining a channel. + * - See recommended settings in *Set the Subscribing State*. + * + * @param userId The user ID of the specified remote user. + * @param mute Sets whether to stop subscribing to the audio stream of a specified user. + * - true: Stop subscribing to the audio stream of a specified user. + * - false: (Default) Resume subscribing to the audio stream of a specified user. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int muteRemoteAudioStream(uid_t userId, bool mute) = 0; - /** Stops/Resumes sending the local video stream. - - A successful \ref agora::rtc::IRtcEngine::muteLocalVideoStream "muteLocalVideoStream" method call triggers the \ref agora::rtc::IRtcEngineEventHandler::onUserMuteVideo "onUserMuteVideo" callback on the remote client. - - @note - - When set to *true*, this method does not disable the camera which does not affect the retrieval of the local video streams. This method executes faster than the \ref agora::rtc::IRtcEngine::enableLocalVideo "enableLocalVideo" method which controls the sending of the local video stream. - - You can call this method either before or after joining a channel. If you call \ref agora::rtc::IRtcEngine::setChannelProfile "setChannelProfile" after this method, the SDK resets whether or not to mute the local video according to the channel profile and user role. Therefore, we recommend calling this method after the `setChannelProfile` method. - - @param mute Sets whether to send/stop sending the local video stream: - - true: Stop sending the local video stream. - - false: (Default) Send the local video stream. - - @return - - 0: Success. - - < 0: Failure. + /** Stops or resumes publishing the local video stream. + * + * A successful \ref agora::rtc::IRtcEngine::muteLocalVideoStream "muteLocalVideoStream" method call + * triggers the \ref agora::rtc::IRtcEngineEventHandler::onUserMuteVideo "onUserMuteVideo" callback on + * the remote client. + * + * @note + * - This method executes faster than the \ref IRtcEngine::enableLocalVideo "enableLocalVideo" method, + * which controls the sending of the local video stream. + * - When `mute` is set as `true`, this method does not affect any ongoing video recording, because it does not disable the camera. + * - You can call this method either before or after joining a channel. If you call \ref IRtcEngine::setChannelProfile "setChannelProfile" + * after this method, the SDK resets whether or not to stop publishing the local video according to the channel profile and user role. + * Therefore, Agora recommends calling this method after the `setChannelProfile` method. + * + * @param mute Sets whether to stop publishing the local video stream. + * - true: Stop publishing the local video stream. + * - false: (Default) Resumes publishing the local video stream. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int muteLocalVideoStream(bool mute) = 0; /** Enables/Disables the local video capture. @@ -5935,49 +6463,61 @@ class IRtcEngine - < 0: Failure. */ virtual int enableLocalVideo(bool enabled) = 0; - /** Stops/Resumes receiving all video stream from a specified remote user. - - @note You can call this method either before or after joining a channel. - - @param mute Sets whether to receive/stop receiving all remote users' video streams: - - true: Stop receiving all remote users' video streams. - - false: (Default) Receive all remote users' video streams. - - @return - - 0: Success. - - < 0: Failure. + /** + * Stops or resumes subscribing to the video streams of all remote users. + * + * 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. + * + * @note + * - Call this method after joining a channel. + * - See recommended settings in *Set the Subscribing State*. + * + * @param mute Sets whether to stop subscribing to the video streams of all remote users. + * - true: Stop subscribing to the video streams of all remote users. + * - false: (Default) Resume subscribing to the video streams of all remote users. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int muteAllRemoteVideoStreams(bool mute) = 0; - /** Stops/Resumes receiving all remote users' video streams by default. - - You can call this method either before or after joining a channel. If you call `setDefaultMuteAllRemoteVideoStreams (true)` after joining a channel, the remote video streams of all subsequent users are not received. - - @note If you want to resume receiving the video stream, call \ref agora::rtc::IRtcEngine::muteRemoteVideoStream "muteRemoteVideoStream (false)", and specify the ID of the remote user whose video stream you want to receive. To receive the video streams of multiple remote users, call `muteRemoteVideoStream (false)` as many times. Calling `setDefaultMuteAllRemoteVideoStreams (false)` resumes receiving the video streams of subsequent users only. - - @param mute Sets whether to receive/stop receiving all remote users' video streams by default: - - true: Stop receiving all remote users' video streams by default. - - false: (Default) Receive all remote users' video streams by default. - - @return - - 0: Success. - - < 0: Failure. + /** 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 \ref IRtcEngine::setDefaultMuteAllRemoteVideoStreams "setDefaultMuteAllRemoteVideoStreams" (true), do the following: + * - If you need to resume subscribing to the video stream of a specified user, call \ref IRtcEngine::muteRemoteVideoStream "muteRemoteVideoStream" (false), and specify the user ID. + * - If you need to resume subscribing to the video streams of multiple remote users, call \ref IRtcEngine::muteRemoteVideoStream "muteRemoteVideoStream" (false) multiple times. + * + * @param mute Sets whether to stop subscribing to the video streams of all remote users by default. + * - true: Stop subscribing to the video streams of all remote users by default. + * - false: (Default) Resume subscribing to the video streams of all remote users by default. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int setDefaultMuteAllRemoteVideoStreams(bool mute) = 0; - /** Stops/Resumes receiving the video stream from a specified remote user. - - @note - - You can call this method either before or after joining a channel. If you call it before joining a channel, you - need to maintain the `uid` of the remote user on your app level. - - If you called the \ref agora::rtc::IRtcEngine::muteAllRemoteVideoStreams "muteAllRemoteVideoStreams" method and set @p mute as @p true to stop receiving all remote video streams, call the *muteAllRemoteVideoStreams* method and set @p mute as @p false before calling this method. - - @param userId User ID of the specified remote user. - @param mute Sets whether to stop/resume receiving the video stream from a specified remote user: - - true: Stop receiving the specified remote user's video stream. - - false: (Default) Receive the specified remote user's video stream. - - @return - - 0: Success. - - < 0: Failure. + /** + * Stops or resumes subscribing to the video stream of a specified user. + * + * @note + * - Call this method after joining a channel. + * - See recommended settings in *Set the Subscribing State*. + * + * @param userId The user ID of the specified remote user. + * @param mute Sets whether to stop subscribing to the video stream of a specified user. + * - true: Stop subscribing to the video stream of a specified user. + * - false: (Default) Resume subscribing to the video stream of a specified user. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int muteRemoteVideoStream(uid_t userId, bool mute) = 0; /** Sets the stream type of the remote video. @@ -6034,18 +6574,21 @@ class IRtcEngine */ virtual int setRemoteDefaultVideoStreamType(REMOTE_VIDEO_STREAM_TYPE streamType) = 0; - /** Enables the \ref agora::rtc::IRtcEngineEventHandler::onAudioVolumeIndication "onAudioVolumeIndication" callback at a set time interval to report on which users are speaking and the speakers' volume. + /** Enables the reporting of users' volume indication. - Once this method is enabled, the SDK returns the volume indication in the \ref agora::rtc::IRtcEngineEventHandler::onAudioVolumeIndication "onAudioVolumeIndication" callback at the set time interval, whether or not any user is speaking in the channel. + This method enables the SDK to regularly report the volume information of the local user who sends a stream and + remote users (up to three) whose instantaneous volumes are the highest to the app. Once you call this method and + users send streams in the channel, the SDK triggers the + \ref IRtcEngineEventHandler::onAudioVolumeIndication "onAudioVolumeIndication" callback at the time interval set + in this method. @note You can call this method either before or after joining a channel. @param interval Sets the time interval between two consecutive volume indications: - ≤ 0: Disables the volume indication. - > 0: Time interval (ms) between two consecutive volume indications. We recommend setting @p interval > 200 ms. Do not set @p interval < 10 ms, or the *onAudioVolumeIndication* callback will not be triggered. - @param smooth Smoothing factor sets the sensitivity of the audio volume indicator. The value ranges between 0 and 10. The greater the value, the more sensitive the indicator. The recommended value is 3. + @param smooth Smoothing factor sets the sensitivity of the audio volume indicator. The value ranges between 0 and 10. The greater the value, the more sensitive the indicator. The recommended value is 3. @param report_vad - - true: Enable the voice activity detection of the local user. Once it is enabled, the `vad` parameter of the `onAudioVolumeIndication` callback reports the voice activity status of the local user. - false: (Default) Disable the voice activity detection of the local user. Once it is disabled, the `vad` parameter of the `onAudioVolumeIndication` callback does not report the voice activity status of the local user, except for the scenario where the engine automatically detects the voice activity of the local user. @return @@ -6053,9 +6596,9 @@ class IRtcEngine - < 0: Failure. */ virtual int enableAudioVolumeIndication(int interval, int smooth, bool report_vad) = 0; - /** @deprecated Starts an audio recording. + /** Starts an audio recording. - Use \ref IRtcEngine::startAudioRecording(const char* filePath, int sampleRate, AUDIO_RECORDING_QUALITY_TYPE quality) "startAudioRecording"2 instead. + @deprecated Use \ref IRtcEngine::startAudioRecording(const char* filePath, int sampleRate, AUDIO_RECORDING_QUALITY_TYPE quality) "startAudioRecording" [2/2] instead. The SDK allows recording during a call. Supported formats: @@ -6458,6 +7001,48 @@ class IRtcEngine - < 0: Failure. */ virtual int resumeAllEffects() = 0; + /** Enables or disables deep-learning noise reduction. + * + * The SDK enables traditional noise reduction mode by default to reduce most of the stationary background noise. + * If you need to reduce most of the non-stationary background noise, Agora recommends enabling deep-learning + * noise reduction as follows: + * + * 1. Integrate the dynamical library under the libs folder to your project: + * - Android: `libagora_ai_denoise_extension.so` + * - iOS: `AgoraAIDenoiseExtension.xcframework` + * - macOS: `AgoraAIDenoiseExtension.framework` + * - Windows: `libagora_ai_denoise_extension.dll` + * 2. Call `enableDeepLearningDenoise(true)`. + * + * Deep-learning noise reduction requires high-performance devices. For example, the following devices and later + * models are known to support deep-learning noise reduction: + * - iPhone 6S + * - MacBook Pro 2015 + * - iPad Pro (2nd generation) + * - iPad mini (5th generation) + * - iPad Air (3rd generation) + * + * After successfully enabling deep-learning noise reduction, if the SDK detects that the device performance + * is not sufficient, it automatically disables deep-learning noise reduction and enables traditional noise reduction. + * + * If you call `enableDeepLearningDenoise(false)` or the SDK automatically disables deep-learning noise reduction + * in the channel, when you need to re-enable deep-learning noise reduction, you need to call \ref IRtcEngine::leaveChannel "leaveChannel" + * first, and then call `enableDeepLearningDenoise(true)`. + * + * @note + * - This method dynamically loads the library, so Agora recommends calling this method before joining a channel. + * - This method works best with the human voice. Agora does not recommend using this method for audio containing music. + * + * @param enable Sets whether to enable deep-learning noise reduction. + * - true: (Default) Enables deep-learning noise reduction. + * - false: Disables deep-learning noise reduction. + * + * @return + * - 0: Success. + * - < 0: Failure. + * - -157 (ERR_MODULE_NOT_FOUND): The dynamical library for enabling deep-learning noise reduction is not integrated. + */ + virtual int enableDeepLearningDenoise(bool enable) = 0; /** Enables/Disables stereo panning for remote users. Ensure that you call this method before joinChannel to enable stereo panning for remote users so that the local user can track the position of a remote user by calling \ref agora::rtc::IRtcEngine::setRemoteVoicePosition "setRemoteVoicePosition". @@ -6604,14 +7189,15 @@ class IRtcEngine * - Do not set the `profile` parameter of \ref IRtcEngine::setAudioProfile "setAudioProfile" to `AUDIO_PROFILE_SPEECH_STANDARD(1)` * or `AUDIO_PROFILE_IOT(6)`; otherwise, this method call fails. * - This method works best with the human voice. Agora does not recommend using this method for audio containing music. - * - After calling this method, Agora recommends not calling the following methods, because they can override \ref IRtcEngine::setAudioEffectParameters "setAudioEffectParameters": + * - After calling this method, Agora recommends not calling the following methods, because they can override \ref IRtcEngine::setVoiceBeautifierPreset "setVoiceBeautifierPreset": * - \ref IRtcEngine::setAudioEffectPreset "setAudioEffectPreset" - * - \ref IRtcEngine::setVoiceBeautifierPreset "setVoiceBeautifierPreset" + * - \ref IRtcEngine::setAudioEffectParameters "setAudioEffectParameters" * - \ref IRtcEngine::setLocalVoiceReverbPreset "setLocalVoiceReverbPreset" * - \ref IRtcEngine::setLocalVoiceChanger "setLocalVoiceChanger" * - \ref IRtcEngine::setLocalVoicePitch "setLocalVoicePitch" * - \ref IRtcEngine::setLocalVoiceEqualization "setLocalVoiceEqualization" * - \ref IRtcEngine::setLocalVoiceReverb "setLocalVoiceReverb" + * - \ref IRtcEngine::setVoiceBeautifierParameters "setVoiceBeautifierParameters" * * @param preset The options for SDK preset voice beautifier effects: #VOICE_BEAUTIFIER_PRESET. * @@ -6648,6 +7234,7 @@ class IRtcEngine * - \ref IRtcEngine::setLocalVoicePitch "setLocalVoicePitch" * - \ref IRtcEngine::setLocalVoiceEqualization "setLocalVoiceEqualization" * - \ref IRtcEngine::setLocalVoiceReverb "setLocalVoiceReverb" + * - \ref IRtcEngine::setVoiceBeautifierParameters "setVoiceBeautifierParameters" * * @param preset The options for SDK preset audio effects. See #AUDIO_EFFECT_PRESET. * @@ -6656,6 +7243,7 @@ class IRtcEngine * - < 0: Failure. */ virtual int setAudioEffectPreset(AUDIO_EFFECT_PRESET preset) = 0; + virtual int setVoiceConversionPreset(VOICE_CONVERSION_PRESET preset) = 0; /** Sets parameters for SDK preset audio effects. * * @since v3.2.0 @@ -6688,7 +7276,7 @@ class IRtcEngine * - \ref IRtcEngine::setLocalVoicePitch "setLocalVoicePitch" * - \ref IRtcEngine::setLocalVoiceEqualization "setLocalVoiceEqualization" * - \ref IRtcEngine::setLocalVoiceReverb "setLocalVoiceReverb" - * + * - \ref IRtcEngine::setVoiceBeautifierParameters "setVoiceBeautifierParameters" * @param preset The options for SDK preset audio effects: * - 3D voice effect: `ROOM_ACOUSTICS_3D_VOICE`. * - Call \ref IRtcEngine::setAudioProfile "setAudioProfile" and set the `profile` parameter to `AUDIO_PROFILE_MUSIC_STANDARD_STEREO(3)` @@ -6706,7 +7294,7 @@ class IRtcEngine * - `2`: Natural minor scale. * - `3`: Japanese pentatonic scale. * @param param2 - * - If you set `preset` to `ROOM_ACOUSTICS_3D_VOICE`, you do not need to set `param2`. + * - If you set `preset` to `ROOM_ACOUSTICS_3D_VOICE`, you need to set `param2` to `0`. * - If you set `preset` to `PITCH_CORRECTION`, `param2` sets the tonic pitch of the pitch correction effect: * - `1`: A * - `2`: A# @@ -6726,7 +7314,49 @@ class IRtcEngine * - < 0: Failure. */ virtual int setAudioEffectParameters(AUDIO_EFFECT_PRESET preset, int param1, int param2) = 0; + /** Sets parameters for SDK preset voice beautifier effects. + * + * @since v3.3.0 + * + * Call this method to set a gender characteristic and a reverberation effect for the singing beautifier effect. This method sets parameters for the local user who sends an audio stream. + * + * After you call this method successfully, all users in the channel can hear the relevant effect. + * + * To achieve better audio effect quality, before you call this method, Agora recommends calling \ref IRtcEngine::setAudioProfile "setAudioProfile", and setting the `scenario` parameter + * as `AUDIO_SCENARIO_GAME_STREAMING(3)` and the `profile` parameter as `AUDIO_PROFILE_MUSIC_HIGH_QUALITY(4)` or `AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5)`. + * + * @note + * - You can call this method either before or after joining a channel. + * - Do not set the `profile` parameter of \ref IRtcEngine::setAudioProfile "setAudioProfile" as `AUDIO_PROFILE_SPEECH_STANDARD(1)` or `AUDIO_PROFILE_IOT(6)`; otherwise, this method call does not take effect. + * - This method works best with the human voice. Agora does not recommend using this method for audio containing music. + * - After you call this method, Agora recommends not calling the following methods, because they can override `setVoiceBeautifierParameters`: + * - \ref IRtcEngine::setAudioEffectPreset "setAudioEffectPreset" + * - \ref IRtcEngine::setAudioEffectParameters "setAudioEffectParameters" + * - \ref IRtcEngine::setVoiceBeautifierPreset "setVoiceBeautifierPreset" + * - \ref IRtcEngine::setLocalVoiceReverbPreset "setLocalVoiceReverbPreset" + * - \ref IRtcEngine::setLocalVoiceChanger "setLocalVoiceChanger" + * - \ref IRtcEngine::setLocalVoicePitch "setLocalVoicePitch" + * - \ref IRtcEngine::setLocalVoiceEqualization "setLocalVoiceEqualization" + * - \ref IRtcEngine::setLocalVoiceReverb "setLocalVoiceReverb" + * + * @param preset The options for SDK preset voice beautifier effects: + * - `SINGING_BEAUTIFIER`: Singing beautifier effect. + * @param param1 The gender characteristics options for the singing voice: + * - `1`: A male-sounding voice. + * - `2`: A female-sounding voice. + * @param param2 The reverberation effects options: + * - `1`: The reverberation effect sounds like singing in a small room. + * - `2`: The reverberation effect sounds like singing in a large room. + * - `3`: The reverberation effect sounds like singing in a hall. + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int setVoiceBeautifierParameters(VOICE_BEAUTIFIER_PRESET preset, int param1, int param2) = 0; /** Sets the log files that the SDK outputs. + * + * @deprecated This method is deprecated from v3.3.0. Use `logConfig` in the \ref IRtcEngine::initialize "initialize" method instead. * * By default, the SDK outputs five log files, `agorasdk.log`, `agorasdk_1.log`, `agorasdk_2.log`, `agorasdk_3.log`, `agorasdk_4.log`, each with a default size of 1024 KB. * These log files are encoded in UTF-8. The SDK writes the latest logs in `agorasdk.log`. When `agorasdk.log` is full, the SDK deletes the log file with the earliest @@ -6747,6 +7377,8 @@ class IRtcEngine virtual int setLogFile(const char* filePath) = 0; /** Sets the output log level of the SDK. + @deprecated This method is deprecated from v3.3.0. Use `logConfig` in the \ref IRtcEngine::initialize "initialize" method instead. + You can use one or a combination of the log filter levels. The log level follows the sequence of OFF, CRITICAL, ERROR, WARNING, INFO, and DEBUG. Choose a level to see the logs preceding that level. If you set the log level to WARNING, you see the logs within levels CRITICAL, ERROR, and WARNING. @@ -6763,6 +7395,7 @@ class IRtcEngine virtual int setLogFilter(unsigned int filter) = 0; /** Sets the size of a log file that the SDK outputs. * + * @deprecated This method is deprecated from v3.3.0. Use `logConfig` in the \ref IRtcEngine::initialize "initialize" method instead. * * @note If you want to set the log file size, ensure that you call * this method before \ref IRtcEngine::setLogFile "setLogFile", or the logs are cleared. @@ -6782,8 +7415,33 @@ class IRtcEngine * - < 0: Failure. */ virtual int setLogFileSize(unsigned int fileSizeInKBytes) = 0; + /// @cond + /** Uploads all SDK log files. + * + * @since v3.3.0 + * + * Uploads all SDK log files from the client to the Agora server. + * After a successful method call, the SDK triggers the \ref agora::rtc::IRtcEngineEventHandler::onUploadLogResult "onUploadLogResult" callback + * to report whether the log files are successfully uploaded to the Agora server. + * + * + * For easier debugging, Agora recommends that you bind this method to the UI element of your App, so as to instruct the + * user to upload a log file when a quality issue occurs. + * + * @note Do not call this method more than once per minute, otherwise the SDK reports #ERR_TOO_OFTEN (12). + * + * @param[out] requestId The request ID. This request ID is the same as requestId in the \ref IRtcEngineEventHandler::onUploadLogResult "onUploadLogResult" callback, + * and you can use the request ID to match a specific upload with a callback. + * + * @return + * - 0: Success. + * - < 0: Failure. + * - -12(ERR_TOO_OFTEN): The call frequency exceeds the limit. + */ + virtual int uploadLogFile(agora::util::AString& requestId) = 0; + /// @endcond /** - @deprecated This method is deprecated, use the \ref IRtcEngine::setLocalRenderMode(RENDER_MODE_TYPE renderMode, VIDEO_MIRROR_MODE_TYPE mirrorMode) "setLocalRenderMode"2 method instead. + @deprecated This method is deprecated, use the \ref IRtcEngine::setLocalRenderMode(RENDER_MODE_TYPE renderMode, VIDEO_MIRROR_MODE_TYPE mirrorMode) "setLocalRenderMode" [2/2] method instead. Sets the local video display mode. This method can be called multiple times during a call to change the display mode. @@ -6813,7 +7471,7 @@ class IRtcEngine */ virtual int setLocalRenderMode(RENDER_MODE_TYPE renderMode, VIDEO_MIRROR_MODE_TYPE mirrorMode) = 0; /** - @deprecated This method is deprecated, use the \ref IRtcEngine::setRemoteRenderMode(uid_t userId, RENDER_MODE_TYPE renderMode, VIDEO_MIRROR_MODE_TYPE mirrorMode) "setRemoteRenderMode"2 method instead. + @deprecated This method is deprecated, use the \ref IRtcEngine::setRemoteRenderMode(uid_t userId, RENDER_MODE_TYPE renderMode, VIDEO_MIRROR_MODE_TYPE mirrorMode) "setRemoteRenderMode" [2/2] method instead. Sets the video display mode of a specified remote user. This method can be called multiple times during a call to change the display mode. @@ -6923,7 +7581,7 @@ class IRtcEngine - 1: Mono - 2: Stereo @param mode Sets the use mode (see #RAW_AUDIO_FRAME_OP_MODE_TYPE) of the *onRecordAudioFrame* callback. - @param samplesPerCall Sets the number of samples returned in the *onRecordAudioFrame* callback. `samplesPerCall` is usually set as 1024 for RTMP streaming. + @param samplesPerCall Sets the number of samples returned in the *onRecordAudioFrame* callback. `samplesPerCall` is usually set as 1024 for RTMP or RTMPS streaming. @note The SDK triggers the `onRecordAudioFrame` callback according to the sample interval. Ensure that the sample interval ≥ 0.01 (s). And, Sample interval (sec) = `samplePerCall`/(`sampleRate` × `channel`). @@ -6942,7 +7600,7 @@ class IRtcEngine - 1: Mono - 2: Stereo @param mode Sets the use mode (see #RAW_AUDIO_FRAME_OP_MODE_TYPE) of the *onPlaybackAudioFrame* callback. - @param samplesPerCall Sets the number of samples returned in the *onPlaybackAudioFrame* callback. `samplesPerCall` is usually set as 1024 for RTMP streaming. + @param samplesPerCall Sets the number of samples returned in the *onPlaybackAudioFrame* callback. `samplesPerCall` is usually set as 1024 for RTMP or RTMPS streaming. @note The SDK triggers the `onPlaybackAudioFrame` callback according to the sample interval. Ensure that the sample interval ≥ 0.01 (s). And, Sample interval (sec) = `samplePerCall`/(`sampleRate` × `channel`). @@ -6956,7 +7614,7 @@ class IRtcEngine @note Ensure that you call this method before joining a channel. @param sampleRate Sets the sample rate (@p samplesPerSec) returned in the *onMixedAudioFrame* callback, which can be set as 8000, 16000, 32000, 44100, or 48000 Hz. - @param samplesPerCall Sets the number of samples (`samples`) returned in the *onMixedAudioFrame* callback. `samplesPerCall` is usually set as 1024 for RTMP streaming. + @param samplesPerCall Sets the number of samples (`samples`) returned in the *onMixedAudioFrame* callback. `samplesPerCall` is usually set as 1024 for RTMP or RTMPS streaming. @note The SDK triggers the `onMixedAudioFrame` callback according to the sample interval. Ensure that the sample interval ≥ 0.01 (s). And, Sample interval (sec) = `samplePerCall`/(`sampleRate` × `channels`). @@ -6965,11 +7623,11 @@ class IRtcEngine - < 0: Failure. */ virtual int setMixedAudioFrameParameters(int sampleRate, int samplesPerCall) = 0; - /** Adjusts the recording volume. + /** Adjusts the capturing signal volume. @note You can call this method either before or after joining a channel. - @param volume Recording volume. To avoid echoes and + @param volume Volume. To avoid echoes and improve call quality, Agora recommends setting the value of volume between 0 and 100. If you need to set the value higher than 100, contact support@agora.io first. @@ -6982,7 +7640,7 @@ class IRtcEngine - < 0: Failure. */ virtual int adjustRecordingSignalVolume(int volume) = 0; - /** Adjusts the playback volume of all remote users. + /** Adjusts the playback signal volume of all remote users. @note - This method adjusts the playback volume that is the mixed volume of all remote users. @@ -7140,6 +7798,13 @@ class IRtcEngine - Ensure that you have successfully called the \ref IRtcEngine::joinChannel "joinChannel" method before calling this method. - After calling this method, the SDK returns the \ref IRtcEngineEventHandler::onAudioRouteChanged "onAudioRouteChanged" callback to indicate the changes. - This method does not take effect if a headset is used. + - Settings of \ref IRtcEngine::setAudioProfile "setAudioProfile" and \ref IRtcEngine::setChannelProfile "setChannelProfile" affect the call + result of `setEnableSpeakerphone`. The following are scenarios where `setEnableSpeakerphone` does not take effect: + - If you set `scenario` as `AUDIO_SCENARIO_GAME_STREAMING`, no user can change the audio playback route. + - If you set `scenario` as `AUDIO_SCENARIO_DEFAULT` or `AUDIO_SCENARIO_SHOWROOM`, the audience cannot change + the audio playback route. If there is only one broadcaster is in the channel, the broadcaster cannot change + the audio playback route either. + - If you set `scenario` as `AUDIO_SCENARIO_EDUCATION`, the audience cannot change the audio playback route. @param speakerOn Sets whether to route the audio to the speakerphone or earpiece: - true: Route the audio to the speakerphone. If the playback device connects to the earpiece or Bluetooth, the audio cannot be routed to the speakerphone. @@ -7214,42 +7879,41 @@ class IRtcEngine #endif #if (defined(__APPLE__) && TARGET_OS_MAC && !TARGET_OS_IPHONE) || defined(_WIN32) - /** Enables loopback recording. + /** Enables loopback audio capturing. - If you enable loopback recording, the output of the sound card is mixed into the audio stream sent to the other end. + If you enable loopback audio capturing, the output of the sound card is mixed into the audio stream sent to the other end. @note You can call this method either before or after joining a channel. - @param enabled Sets whether to enable/disable loopback recording. - - true: Enable loopback recording. - - false: (Default) Disable loopback recording. + @param enabled Sets whether to enable/disable loopback capturing. + - true: Enable loopback capturing. + - false: (Default) Disable loopback capturing. @param deviceName Pointer to the device name of the sound card. The default value is NULL (the default sound card). @note - This method is for macOS and Windows only. - - macOS does not support loopback recording of the default sound card. If you need to use this method, please use a virtual sound card and pass its name to the deviceName parameter. Agora has tested and recommends using soundflower. + - macOS does not support loopback capturing of the default sound card. If you need to use this method, please use a virtual sound card and pass its name to the deviceName parameter. Agora has tested and recommends using soundflower. */ virtual int enableLoopbackRecording(bool enabled, const char* deviceName = NULL) = 0; #if (defined(__APPLE__) && TARGET_OS_MAC && !TARGET_OS_IPHONE) /** Shares the whole or part of a screen by specifying the display ID. - * + * * @note * - This method is for macOS only. * - Ensure that you call this method after joining a channel. - * - * @param displayId The display ID of the screen to be shared. This parameter specifies which screen you want to share. - * @param regionRect (Optional) Sets the relative location of the region to the screen. NIL means sharing the whole screen. See Rectangle. If the specified region overruns the screen, the SDK shares only the region within it; if you set width or height as 0, the SDK shares the whole screen. - * @param captureParams Sets the screen sharing encoding parameters. See ScreenCaptureParameters. - * - * + * + * @param displayId The display ID of the screen to be shared. This parameter specifies which screen you want to share. + * @param regionRect (Optional) Sets the relative location of the region to the screen. NIL means sharing the whole screen. See Rectangle. If the specified region overruns the screen, the SDK shares only the region within it; if you set width or height as 0, the SDK shares the whole screen. + * @param captureParams The screen sharing encoding parameters. The default video dimension is 1920 x 1080, that is, 2,073,600 pixels. Agora uses the value of `videoDimension` to calculate the charges. + * For details, see descriptions in ScreenCaptureParameters. + * + * * @return * - 0: Success. * - < 0: Failure: - * - #ERR_INVALID_STATE: the screen sharing state is invalid, probably because another screen or window is being - * shared. Call \ref IRtcEngine::stopScreenCapture "stopScreenCapture" to stop the current screen sharing. - * - #ERR_INVALID_ARGUMENT: the argument is invalid. + * - #ERR_INVALID_ARGUMENT: The argument is invalid. */ virtual int startScreenCaptureByDisplayId(unsigned int displayId, const Rectangle& regionRect, const ScreenCaptureParameters& captureParams) = 0; #endif @@ -7261,16 +7925,15 @@ class IRtcEngine * - Ensure that you call this method after joining a channel. * - Applies to the Windows platform only. * - * @param screenRect Sets the relative location of the screen to the virtual screen. For information on how to get screenRect, see the advanced guide *Share Screen*. - * @param regionRect (Optional) Sets the relative location of the region to the screen. NULL means sharing the whole screen. See Rectangle. If the specified region overruns the screen, the SDK shares only the region within it; if you set width or height as 0, the SDK shares the whole screen. - * @param captureParams Sets the screen sharing encoding parameters. See ScreenCaptureParameters. + * @param screenRect Sets the relative location of the screen to the virtual screen. For information on how to get screenRect, see the advanced guide *Share Screen*. + * @param regionRect (Optional) Sets the relative location of the region to the screen. NULL means sharing the whole screen. See Rectangle. If the specified region overruns the screen, the SDK shares only the region within it; if you set width or height as 0, the SDK shares the whole screen. + * @param captureParams The screen sharing encoding parameters. The default video dimension is 1920 x 1080, that is, 2,073,600 pixels. + * Agora uses the value of `videoDimension` to calculate the charges. For details, see descriptions in ScreenCaptureParameters. * * @return * - 0: Success. * - < 0: Failure: - * - #ERR_INVALID_STATE: the screen sharing state is invalid, probably because another screen or window is being - * shared. Call \ref IRtcEngine::stopScreenCapture "stopScreenCapture" to stop the current screen sharing. - * - #ERR_INVALID_ARGUMENT : the argument is invalid. + * - #ERR_INVALID_ARGUMENT : The argument is invalid. */ virtual int startScreenCaptureByScreenRect(const Rectangle& screenRect, const Rectangle& regionRect, const ScreenCaptureParameters& captureParams) = 0; #endif @@ -7398,14 +8061,12 @@ class IRtcEngine * * @param windowId The ID of the window to be shared. For information on how to get the windowId, see the advanced guide *Share Screen*. * @param regionRect (Optional) The relative location of the region to the window. NULL/NIL means sharing the whole window. See Rectangle. If the specified region overruns the window, the SDK shares only the region within it; if you set width or height as 0, the SDK shares the whole window. - * @param captureParams Window sharing encoding parameters. See ScreenCaptureParameters. + * @param captureParams The screen sharing encoding parameters. The default video dimension is 1920 x 1080, that is, 2,073,600 pixels. Agora uses the value of `videoDimension` to calculate the charges. For details, see descriptions in ScreenCaptureParameters. * * @return * - 0: Success. * - < 0: Failure: - * - #ERR_INVALID_STATE: the screen sharing state is invalid, probably because another screen or window is being - * shared. Call \ref IRtcEngine::stopScreenCapture "stopScreenCapture" to stop the current screen sharing. - * - #ERR_INVALID_ARGUMENT: the argument is invalid. + * - #ERR_INVALID_ARGUMENT: The argument is invalid. */ virtual int startScreenCaptureByWindowId(view_t windowId, const Rectangle& regionRect, const ScreenCaptureParameters& captureParams) = 0; @@ -7425,7 +8086,9 @@ class IRtcEngine /** Updates the screen sharing parameters. - @param captureParams Sets the screen sharing encoding parameters. See ScreenCaptureParameters. + @param captureParams The screen sharing encoding parameters. The default video dimension is 1920 x 1080, that is, + 2,073,600 pixels. Agora uses the value of `videoDimension` to calculate the charges. For details, + see descriptions in ScreenCaptureParameters. @return - 0: Success. @@ -7580,7 +8243,7 @@ class IRtcEngine @note - Do not call any other methods before receiving the \ref IRtcEngineEventHandler::onLastmileQuality "onLastmileQuality" callback. Otherwise, the callback may be interrupted by other methods, and hence may not be triggered. - A host should not call this method after joining a channel (when in a call). - - If you call this method to test the last-mile quality, the SDK consumes the bandwidth of a video stream, whose bitrate corresponds to the bitrate you set in the \ref agora::rtc::IRtcEngine::setVideoEncoderConfiguration "setVideoEncoderConfiguration" method. After you join the channel, whether you have called the `disableLastmileTest` method or not, the SDK automatically stops consuming the bandwidth. + - If you call this method to test the last mile network quality, the SDK consumes the bandwidth of a video stream, whose bitrate corresponds to the bitrate you set in the \ref agora::rtc::IRtcEngine::setVideoEncoderConfiguration "setVideoEncoderConfiguration" method. After you join the channel, whether you have called the `disableLastmileTest` method or not, the SDK automatically stops consuming the bandwidth. @return - 0: Success. @@ -7598,7 +8261,7 @@ class IRtcEngine /** Starts the last-mile network probe test. - This method starts the last-mile network probe test before joining a channel to get the uplink and downlink last-mile network statistics, including the bandwidth, packet loss, jitter, and round-trip time (RTT). + This method starts the last-mile network probe test before joining a channel to get the uplink and downlink last mile network statistics, including the bandwidth, packet loss, jitter, and round-trip time (RTT). Call this method to check the uplink network quality before users join a channel or before an audience switches to a host. Once this method is enabled, the SDK returns the following callbacks: @@ -7682,8 +8345,8 @@ class IRtcEngine * All users in the same channel must use the same encryption mode and encryption key. Once all users leave the channel, the encryption key of this channel is automatically cleared. * * @note - * - If you enable the built-in encryption, you cannot use the RTMP streaming function. - * - Agora supports four encryption modes. If you choose an encryption mode (excepting `SM4_128_ECB` mode), you need to add an external encryption library when integrating the Android and iOS SDK. See the advanced guide *Channel Encryption*. + * - If you enable the built-in encryption, you cannot use the RTMP or RTMPS streaming function. + * - You need to add an external encryption library when integrating the Android and iOS SDK. See the advanced guide *Channel Encryption*. * * @param enabled Whether to enable the built-in encryption: * - true: Enable the built-in encryption. @@ -7719,10 +8382,12 @@ class IRtcEngine /** Creates a data stream. + @deprecated This method is deprecated from v3.3.0. Use the \ref IRtcEngine::createDataStream(int* streamId, DataStreamConfig& config) "createDataStream" [2/2] method instead. + Each user can create up to five data streams during the lifecycle of the IRtcEngine. @note - - Set both the @p reliable and @p ordered parameters to true or false. Do not set one as true and the other as false. + - Do not set `reliable` as `true` while setting `ordered` as `false`. - Ensure that you call this method after joining a channel. @param[out] streamId Pointer to the ID of the created data stream. @@ -7738,6 +8403,23 @@ class IRtcEngine - < 0: Failure. */ virtual int createDataStream(int* streamId, bool reliable, bool ordered) = 0; + /** 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. + * + * @param[out] streamId The ID of the created data stream. + * @param config The configurations for the data stream: DataStreamConfig. + * + * @return + * - 0: Creates the data stream successfully. + * - < 0: Fails to create the data stream. + */ + virtual int createDataStream(int* streamId, DataStreamConfig& config) = 0; /** Sends data stream messages to all users in a channel. @@ -7762,7 +8444,7 @@ class IRtcEngine */ virtual int sendStreamMessage(int streamId, const char* data, size_t length) = 0; - /** Publishes the local stream to a specified CDN live RTMP address. (CDN live only.) + /** Publishes the local stream to a specified CDN live address. (CDN live only.) The SDK returns the result of this method call in the \ref IRtcEngineEventHandler::onStreamPublished "onStreamPublished" callback. @@ -7770,10 +8452,10 @@ class IRtcEngine @note - Ensure that the user joins the channel before calling this method. - Ensure that you enable the RTMP Converter service before using this function. See *Prerequisites* in the advanced guide *Push Streams to CDN*. - - This method adds only one stream RTMP URL address each time it is called. + - This method adds only one stream CDN streaming URL each time it is called. - This method applies to `LIVE_BROADCASTING` only. - @param url The CDN streaming URL in the RTMP format. The maximum length of this parameter is 1024 bytes. The RTMP URL address must not contain special characters, such as Chinese language characters. + @param url The 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. @param transcodingEnabled Sets whether transcoding is enabled/disabled: - true: Enable transcoding. To [transcode](https://docs.agora.io/en/Agora%20Platform/terms?platform=All%20Platforms#transcoding) 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 \ref IRtcEngine::setLiveTranscoding "setLiveTranscoding" method before this method. - false: Disable transcoding. @@ -7781,22 +8463,23 @@ class IRtcEngine @return - 0: Success. - < 0: Failure. - - #ERR_INVALID_ARGUMENT (2): The RTMP URL address is NULL or has a string length of 0. - - #ERR_NOT_INITIALIZED (7): You have not initialized the RTC engine when publishing the stream. + - #ERR_INVALID_ARGUMENT (-2): The CDN streaming URL is NULL or has a string length of 0. + - #ERR_NOT_INITIALIZED (-7): You have not initialized the RTC engine when publishing the stream. */ virtual int addPublishStreamUrl(const char *url, bool transcodingEnabled) = 0; - /** Removes an RTMP stream from the CDN. (CDN live only.) + /** Removes an RTMP or RTMPS stream from the CDN. (CDN live only.) - This method removes the RTMP URL address (added by the \ref IRtcEngine::addPublishStreamUrl "addPublishStreamUrl" method) from a CDN live stream. The SDK returns the result of this method call in the \ref IRtcEngineEventHandler::onStreamUnpublished "onStreamUnpublished" callback. + This method removes the CDN streaming URL (added by the \ref IRtcEngine::addPublishStreamUrl "addPublishStreamUrl" method) from a CDN live stream. The SDK returns the result of this method call in the \ref IRtcEngineEventHandler::onStreamUnpublished "onStreamUnpublished" callback. + + The \ref agora::rtc::IRtcEngine::removePublishStreamUrl "removePublishStreamUrl" method call triggers the \ref agora::rtc::IRtcEngineEventHandler::onRtmpStreamingStateChanged "onRtmpStreamingStateChanged" callback on the local client to report the state of removing an RTMP or RTMPS stream from the CDN. - The \ref agora::rtc::IRtcEngine::removePublishStreamUrl "removePublishStreamUrl" method call triggers the \ref agora::rtc::IRtcEngineEventHandler::onRtmpStreamingStateChanged "onRtmpStreamingStateChanged" callback on the local client to report the state of removing an RTMP stream from the CDN. @note - - This method removes only one RTMP URL address each time it is called. - - The RTMP URL address must not contain special characters, such as Chinese language characters. + - 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. - This method applies to `LIVE_BROADCASTING` only. - @param url The RTMP URL address to be removed. The maximum length of this parameter is 1024 bytes. + @param url The CDN streaming URL to be removed. The maximum length of this parameter is 1024 bytes. @return - 0: Success. @@ -7813,6 +8496,7 @@ class IRtcEngine - Ensure that you enable the RTMP Converter service before using this function. See *Prerequisites* in the advanced guide *Push Streams to CDN*. - If you call the `setLiveTranscoding` method to update 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. @param transcoding Sets the CDN live audio/video transcoding settings. See LiveTranscoding. @@ -7824,9 +8508,9 @@ class IRtcEngine /** **DEPRECATED** Adds a watermark image to the local video or CDN live stream. - This method is deprecated from v2.9.1. Use \ref agora::rtc::IRtcEngine::addVideoWatermark(const char* watermarkUrl, const WatermarkOptions& options) "addVideoWatermark"2 instead. + This method is deprecated from v2.9.1. Use \ref agora::rtc::IRtcEngine::addVideoWatermark(const char* watermarkUrl, const WatermarkOptions& options) "addVideoWatermark" [2/2] instead. - This method adds a PNG watermark image to the local video stream for the recording device, channel audience, and CDN live audience to view and capture. + This method adds a PNG watermark image to the local video stream for the capturing device, channel audience, and CDN live audience to view and capture. To add the PNG file to the CDN live publishing stream, see the \ref IRtcEngine::setLiveTranscoding "setLiveTranscoding" method. @@ -7848,7 +8532,7 @@ class IRtcEngine /** Adds a watermark image to the local video. This method adds a PNG watermark image to the local video in the live streaming. Once the watermark image is added, all the audience in the channel (CDN audience included), - and the recording device can see and capture it. Agora supports adding only one watermark image onto the local video, and the newly watermark image replaces the previous one. + and the capturing device can see and capture it. Agora supports adding only one watermark image onto the local video, and the newly watermark image replaces the previous one. The watermark position depends on the settings in the \ref IRtcEngine::setVideoEncoderConfiguration "setVideoEncoderConfiguration" method: - If the orientation mode of the encoding video is #ORIENTATION_MODE_FIXED_LANDSCAPE, or the landscape mode in #ORIENTATION_MODE_ADAPTIVE, the watermark uses the landscape orientation. @@ -7881,9 +8565,9 @@ class IRtcEngine virtual int clearVideoWatermarks() = 0; /** Enables/Disables image enhancement and sets the options. - * + * * @note Call this method after calling the \ref IRtcEngine::enableVideo "enableVideo" method. - * + * * @param enabled Sets whether or not to enable image enhancement: * - true: enables image enhancement. * - false: disables image enhancement. @@ -7917,10 +8601,10 @@ class IRtcEngine @return - 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 \ref agora::rtc::IRtcEngine::setChannelProfile "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 IRtcEngine object is initialized before calling this method. + - #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 \ref agora::rtc::IRtcEngine::setChannelProfile "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 IRtcEngine object is initialized before calling this method. */ virtual int addInjectStreamUrl(const char* url, const InjectStreamConfig& config) = 0; /** Starts to relay media streams across channels. @@ -8105,7 +8789,7 @@ class IRtcEngine /** 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 \ref agora::rtc::IMetadataObserver::getMaxMetadataSize "getMaxMetadataSize" callback. - This method enables you to add synchronized metadata in the video stream for more diversified live interactive streaming, such as sending shopping links, digital coupons, and online quizzes. + 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. @@ -8749,12 +9433,9 @@ class RtcEngineParameters if(preset == CHAT_BEAUTIFIER_VITALITY) { return m_parameter->setInt("che.audio.morph.beauty_voice", 3); } - /*if(preset == SINGING_BEAUTIFICATION_MAN) { - return m_parameter->setInt("che.audio.morph.beauty_sing", 1); + if(preset == SINGING_BEAUTIFIER) { + return setObject( "che.audio.morph.beauty_sing", "{\"key\":%d,\"value\":%d}", 1, 1); } - if(preset == SINGING_BEAUTIFICATION_WOMAN) { - return m_parameter->setInt("che.audio.morph.beauty_sing", 2); - }*/ if(preset == TIMBRE_TRANSFORMATION_VIGOROUS) { return m_parameter->setInt("che.audio.morph.voice_changer", 7); } @@ -8782,6 +9463,27 @@ class RtcEngineParameters return -ERR_INVALID_ARGUMENT; } + int setVoiceConversionPreset(VOICE_CONVERSION_PRESET preset) { + if(!m_parameter) + return -ERR_NOT_INITIALIZED; + if (preset == VOICE_CONVERSION_OFF) { + return m_parameter->setInt("che.audio.morph.voice_changer", 0); + } + if (preset == VOICE_CHANGER_NEUTRAL) { + return m_parameter->setInt("che.audio.morph.vocal_changer", 1); + } + if (preset == VOICE_CHANGER_SWEET) { + return m_parameter->setInt("che.audio.morph.vocal_changer", 2); + } + if (preset == VOICE_CHANGER_SOLID) { + return m_parameter->setInt("che.audio.morph.vocal_changer", 3); + } + if (preset == VOICE_CHANGER_BASS) { + return m_parameter->setInt("che.audio.morph.vocal_changer", 4); + } + return -ERR_INVALID_ARGUMENT; + } + int setAudioEffectParameters(AUDIO_EFFECT_PRESET preset, int param1, int param2){ if(!m_parameter) return -ERR_NOT_INITIALIZED; @@ -8794,6 +9496,15 @@ class RtcEngineParameters return -ERR_INVALID_ARGUMENT; } + int setVoiceBeautifierParameters(VOICE_BEAUTIFIER_PRESET preset, int param1, int param2){ + if(!m_parameter) + return -ERR_NOT_INITIALIZED; + if(preset == SINGING_BEAUTIFIER){ + return setObject( "che.audio.morph.beauty_sing", "{\"key\":%d,\"value\":%d}", param1, param2); + } + return -ERR_INVALID_ARGUMENT; + } + /** **DEPRECATED** Use \ref IRtcEngine::disableAudio "disableAudio" instead. Disables the audio function in the channel. @return @@ -8912,6 +9623,10 @@ class RtcEngineParameters int setCameraCapturerConfiguration(const CameraCapturerConfiguration& config) { if (!m_parameter) return -ERR_NOT_INITIALIZED; + if (config.preference == CAPTURER_OUTPUT_PREFERENCE_MANUAL) { + m_parameter->setInt("che.video.capture_width", config.captureWidth); + m_parameter->setInt("che.video.capture_height", config.captureHeight); + } return m_parameter->setInt("che.video.camera_capture_mode", (int)config.preference); } diff --git a/Android/APIExample/lib-stream-encrypt/src/main/cpp/include/agora/AgoraBase.h b/Android/APIExample/lib-stream-encrypt/src/main/cpp/include/agora/AgoraBase.h index ecb0c5a3b..654bb9cd5 100644 --- a/Android/APIExample/lib-stream-encrypt/src/main/cpp/include/agora/AgoraBase.h +++ b/Android/APIExample/lib-stream-encrypt/src/main/cpp/include/agora/AgoraBase.h @@ -150,7 +150,7 @@ enum WARN_CODE_TYPE /** 111: A timeout occurs when switching to the live video. */ WARN_SWITCH_LIVE_VIDEO_TIMEOUT = 111, - /** 118: A timeout occurs when setting the client role in the live interactive streaming profile. + /** 118: A timeout occurs when setting the client role in the interactive live streaming profile. */ WARN_SET_CLIENT_ROLE_TIMEOUT = 118, /** 121: The ticket to open the channel is invalid. @@ -177,19 +177,19 @@ enum WARN_CODE_TYPE /** 1014: Audio Device Module: A warning occurs in the playback device. */ WARN_ADM_RUNTIME_PLAYOUT_WARNING = 1014, - /** 1016: Audio Device Module: a warning occurs in the recording device. + /** 1016: Audio Device Module: A warning occurs in the audio capturing device. */ WARN_ADM_RUNTIME_RECORDING_WARNING = 1016, - /** 1019: Audio Device Module: no valid audio data is recorded. + /** 1019: Audio Device Module: No valid audio data is captured. */ WARN_ADM_RECORD_AUDIO_SILENCE = 1019, /** 1020: Audio device module: The audio playback frequency is abnormal, which may cause audio freezes. This abnormality is caused by high CPU usage. Agora recommends stopping other apps. */ WARN_ADM_PLAYOUT_MALFUNCTION = 1020, - /** 1021: Audio device module: the audio recording frequency is abnormal, which may cause audio freezes. This abnormality is caused by high CPU usage. Agora recommends stopping other apps. + /** 1021: Audio device module: the audio capturing frequency is abnormal, which may cause audio freezes. This abnormality is caused by high CPU usage. Agora recommends stopping other apps. */ WARN_ADM_RECORD_MALFUNCTION = 1021, - /** 1025: The audio playback or recording is interrupted by system events (such as a phone call). + /** 1025: The audio playback or capturing is interrupted by system events (such as a phone call). */ WARN_ADM_CALL_INTERRUPTION = 1025, /** 1029: During a call, the audio session category should be set to @@ -199,13 +199,13 @@ enum WARN_CODE_TYPE * AVAudioSessionCategoryPlayAndRecord. */ WARN_ADM_IOS_CATEGORY_NOT_PLAYANDRECORD = 1029, - /** 1031: Audio Device Module: The recorded audio voice is too low. + /** 1031: Audio Device Module: The captured audio voice is too low. */ WARN_ADM_RECORD_AUDIO_LOWLEVEL = 1031, /** 1032: Audio Device Module: The playback audio voice is too low. */ WARN_ADM_PLAYOUT_AUDIO_LOWLEVEL = 1032, - /** 1033: Audio device module: The audio recording device is occupied. + /** 1033: Audio device module: The audio capturing device is occupied. */ WARN_ADM_RECORD_AUDIO_IS_ACTIVE = 1033, /** 1040: Audio device module: An exception occurs with the audio drive. @@ -215,12 +215,12 @@ enum WARN_CODE_TYPE * - Update the sound card drive. */ WARN_ADM_WINDOWS_NO_DATA_READY_EVENT = 1040, - /** 1042: Audio device module: The audio recording device is different from the audio playback device, - * which may cause echoes problem. Agora recommends using the same audio device to record and playback + /** 1042: Audio device module: The audio capturing device is different from the audio playback device, + * which may cause echoes problem. Agora recommends using the same audio device to capture and playback * audio. */ WARN_ADM_INCONSISTENT_AUDIO_DEVICE = 1042, - /** 1051: (Communication profile only) Audio processing module: A howling sound is detected when recording the audio data. + /** 1051: (Communication profile only) Audio processing module: A howling sound is detected when capturing the audio data. */ WARN_APM_HOWLING = 1051, /** 1052: Audio Device Module: The device is in the glitch state. @@ -300,7 +300,7 @@ enum ERROR_CODE_TYPE /** 11: The request is canceled. This is for internal SDK use only, and it does not return to the application through any method or callback. */ ERR_CANCELED = 11, - /** 12: The method is called too often. This is for internal SDK use only, and it does not return to the application through any method or callback. + /** 12: The method is called too often. */ ERR_TOO_OFTEN = 12, /** 13: The SDK fails to bind to the network socket. This is for internal SDK use only, and it does not return to the application through any method or callback. @@ -395,7 +395,7 @@ enum ERROR_CODE_TYPE /** 120: Decryption fails. The user may have used a different encryption password to join the channel. Check your settings or try rejoining the channel. */ ERR_DECRYPTION_FAILED = 120, - /** 123: The user is banned by the server. This error occurs when the user is kicked off the channel from the server. + /** 123: The user is banned by the server. This error occurs when the user is kicked out the channel from the server. */ ERR_CLIENT_IS_BANNED_BY_SERVER = 123, /** 124: Incorrect watermark file parameter. @@ -437,9 +437,23 @@ enum ERROR_CODE_TYPE /** 155: The server fails to find the stream. */ ERR_PUBLISH_STREAM_NOT_FOUND = 155, - /** 156: The format of the RTMP stream URL is not supported. Check whether the URL format is correct. + /** 156: The format of the RTMP or RTMPS stream URL is not supported. Check whether the URL format is correct. */ ERR_PUBLISH_STREAM_FORMAT_NOT_SUPPORTED = 156, + /** 157: The necessary dynamical library is not integrated. For example, if you call + * the \ref agora::rtc::IRtcEngine::enableDeepLearningDenoise "enableDeepLearningDenoise" but do not integrate the dynamical + * library for the deep-learning noise reduction into your project, the SDK reports this error code. + * + */ + ERR_MODULE_NOT_FOUND = 157, + /// @cond + /** 158: The dynamical library for the super-resolution algorithm is not integrated. + * When you call the \ref agora::rtc::IRtcEngine::enableRemoteSuperResolution "enableRemoteSuperResolution" method but + * do not integrate the dynamical library for the super-resolution algorithm + * into your project, the SDK reports this error code. + */ + ERR_MODULE_SUPER_RESOLUTION_NOT_FOUND = 158, + /// @endcond //signaling: 400~600 ERR_LOGOUT_OTHER = 400, // @@ -512,19 +526,19 @@ enum ERROR_CODE_TYPE /** 1010: Audio Device Module: An error occurs in stopping the playback device. */ ERR_ADM_STOP_PLAYOUT = 1010, - /** 1011: Audio Device Module: An error occurs in initializing the recording device. + /** 1011: Audio Device Module: An error occurs in initializing the capturing device. */ ERR_ADM_INIT_RECORDING = 1011, - /** 1012: Audio Device Module: An error occurs in starting the recording device. + /** 1012: Audio Device Module: An error occurs in starting the capturing device. */ ERR_ADM_START_RECORDING = 1012, - /** 1013: Audio Device Module: An error occurs in stopping the recording device. + /** 1013: Audio Device Module: An error occurs in stopping the capturing device. */ ERR_ADM_STOP_RECORDING = 1013, /** 1015: Audio Device Module: A playback error occurs. Check your playback device and try rejoining the channel. */ ERR_ADM_RUNTIME_PLAYOUT_ERROR = 1015, - /** 1017: Audio Device Module: A recording error occurs. + /** 1017: Audio Device Module: A capturing error occurs. */ ERR_ADM_RUNTIME_RECORDING_ERROR = 1017, /** 1018: Audio Device Module: Fails to record. @@ -548,8 +562,8 @@ enum ERROR_CODE_TYPE /** 1101: Audio device module: A fatal exception occurs. */ ERR_ADM_ANDROID_JNI_JAVA_RESOURCE = 1101, - /** 1108: Audio device module: The recording frequency is lower than 50. - * 0 indicates that the recording is not yet started. We recommend + /** 1108: Audio device module: The capturing frequency is lower than 50. + * 0 indicates that the capturing is not yet started. We recommend * checking your recording permission. */ ERR_ADM_ANDROID_JNI_NO_RECORD_FREQUENCY = 1108, @@ -646,7 +660,7 @@ enum ERROR_CODE_TYPE * - Replace the device. */ ERR_ADM_WIN_CORE_RENDER_NOT_STARTUP = 1320, /** 1322: Audio device module: No audio sampling device is available. - * Solutions: Plug in a proper recording device. */ + * Solutions: Plug in a proper capturing device. */ ERR_ADM_WIN_CORE_NO_RECORDING_DEVICE = 1322, /** 1323: Audio device module: No audio playout device is available. * Solutions: Plug in a proper playback device.*/ @@ -693,7 +707,7 @@ enum ERROR_CODE_TYPE * - Reboot the system. * - Upgrade your audio card driver.*/ ERR_ADM_WIN_WAVE_START_PLAYOUT = 1358, - /** 1359: Audio Device Module: No recording device exists. + /** 1359: Audio Device Module: No capturing device exists. */ ERR_ADM_NO_RECORDING_DEVICE = 1359, /** 1360: Audio Device Module: No playback device exists. @@ -727,7 +741,7 @@ enum ERROR_CODE_TYPE ERR_VCM_ENCODER_SET_ERROR = 1603, }; - /** Output log filter level. */ +/** Output log filter level. */ enum LOG_FILTER_TYPE { /** 0: Do not output any log information. */ @@ -750,6 +764,24 @@ enum LOG_FILTER_TYPE LOG_FILTER_MASK = 0x80f, /// @endcond }; +/** The output log level of the SDK. + * + * @since v3.3.0 + */ +enum class LOG_LEVEL { + /** 0: Do not output any log. */ + LOG_LEVEL_NONE = 0x0000, + /** 0x0001: (Default) Output logs of the FATAL, ERROR, WARN and INFO level. We recommend setting your log filter as this level. + */ + LOG_LEVEL_INFO = 0x0001, + /** 0x0002: Output logs of the FATAL, ERROR and WARN level. + */ + LOG_LEVEL_WARN = 0x0002, + /** 0x0004: Output logs of the FATAL and ERROR level. */ + LOG_LEVEL_ERROR = 0x0004, + /** 0x0008: Output logs of the FATAL level. */ + LOG_LEVEL_FATAL = 0x0008, +}; } // namespace agora #endif diff --git a/Android/APIExample/lib-stream-encrypt/src/main/cpp/include/agora/IAgoraMediaEngine.h b/Android/APIExample/lib-stream-encrypt/src/main/cpp/include/agora/IAgoraMediaEngine.h index e44fb6c43..c740a72af 100644 --- a/Android/APIExample/lib-stream-encrypt/src/main/cpp/include/agora/IAgoraMediaEngine.h +++ b/Android/APIExample/lib-stream-encrypt/src/main/cpp/include/agora/IAgoraMediaEngine.h @@ -59,12 +59,12 @@ class IAudioFrameObserver { }; public: - /** Retrieves the recorded audio frame. + /** Retrieves the captured audio frame. @param audioFrame Pointer to AudioFrame. @return - - true: Valid buffer in AudioFrame, and the recorded audio frame is sent out. - - false: Invalid buffer in AudioFrame, and the recorded audio frame is discarded. + - true: Valid buffer in AudioFrame, and the captured audio frame is sent out. + - false: Invalid buffer in AudioFrame, and the captured audio frame is discarded. */ virtual bool onRecordAudioFrame(AudioFrame& audioFrame) = 0; /** Retrieves the audio playback frame for getting the audio. @@ -75,15 +75,15 @@ class IAudioFrameObserver { - false: Invalid buffer in AudioFrame, and the audio playback frame is discarded. */ virtual bool onPlaybackAudioFrame(AudioFrame& audioFrame) = 0; - /** Retrieves the mixed recorded and playback audio frame. + /** Retrieves the mixed captured and playback audio frame. @note This callback only returns the single-channel data. @param audioFrame Pointer to AudioFrame. @return - - true: Valid buffer in AudioFrame and the mixed recorded and playback audio frame is sent out. - - false: Invalid buffer in AudioFrame and the mixed recorded and playback audio frame is discarded. + - true: Valid buffer in AudioFrame and the mixed captured and playback audio frame is sent out. + - false: Invalid buffer in AudioFrame and the mixed captured and playback audio frame is discarded. */ virtual bool onMixedAudioFrame(AudioFrame& audioFrame) = 0; /** Retrieves the audio frame of a specified user before mixing. @@ -93,8 +93,8 @@ class IAudioFrameObserver { @param uid The user ID @param audioFrame Pointer to AudioFrame. @return - - true: Valid buffer in AudioFrame, and the mixed recorded and playback audio frame is sent out. - - false: Invalid buffer in AudioFrame, and the mixed recorded and playback audio frame is discarded. + - true: Valid buffer in AudioFrame, and the mixed captured and playback audio frame is sent out. + - false: Invalid buffer in AudioFrame, and the mixed captured and playback audio frame is discarded. */ virtual bool onPlaybackAudioFrameBeforeMixing(unsigned int uid, AudioFrame& audioFrame) = 0; diff --git a/Android/APIExample/lib-stream-encrypt/src/main/cpp/include/agora/IAgoraRtcChannel.h b/Android/APIExample/lib-stream-encrypt/src/main/cpp/include/agora/IAgoraRtcChannel.h index f354183dc..8527078ea 100644 --- a/Android/APIExample/lib-stream-encrypt/src/main/cpp/include/agora/IAgoraRtcChannel.h +++ b/Android/APIExample/lib-stream-encrypt/src/main/cpp/include/agora/IAgoraRtcChannel.h @@ -10,29 +10,6 @@ namespace agora { namespace rtc { -/** The channel media options. */ -struct ChannelMediaOptions { - /** Determines whether to subscribe to audio streams when the user joins the channel: - - true: (Default) Subscribe. - - false: Do not subscribe. - - This member serves a similar function to the \ref agora::rtc::IChannel::muteAllRemoteAudioStreams "muteAllRemoteAudioStreams" method. After joining the channel, - you can call the `muteAllRemoteAudioStreams` method to set whether to subscribe to audio streams in the channel. - */ - bool autoSubscribeAudio; - /** Determines whether to subscribe to video streams when the user joins the channel: - - true: (Default) Subscribe. - - false: Do not subscribe. - - This member serves a similar function to the \ref agora::rtc::IChannel::muteAllRemoteVideoStreams "muteAllRemoteVideoStreams" method. After joining the channel, - you can call the `muteAllRemoteVideoStreams` method to set whether to subscribe to video streams in the channel. - */ - bool autoSubscribeVideo; - ChannelMediaOptions() - : autoSubscribeAudio(true) - , autoSubscribeVideo(true) - {} -}; /** The IChannel class. */ class IChannel; /** The IChannelEventHandler class. */ @@ -102,7 +79,7 @@ class IChannelEventHandler (void)rtcChannel; (void)stats; } - /** Occurs when the user role switches in the live interactive streaming. For example, from a host to an audience or vice versa. + /** Occurs when the user role switches in the interactive live streaming. For example, from a host to an audience or vice versa. This callback notifies the application of a user role switch when the application calls the \ref IChannel::setClientRole "setClientRole" method. @@ -481,15 +458,15 @@ class IChannelEventHandler (void)code; } /** - Occurs when the state of the RTMP streaming changes. + Occurs when the state of the RTMP or RTMPS streaming changes. The SDK triggers this callback to report the result of the local user calling the \ref agora::rtc::IChannel::addPublishStreamUrl "addPublishStreamUrl" or \ref agora::rtc::IChannel::removePublishStreamUrl "removePublishStreamUrl" method. - This callback indicates the state of the RTMP streaming. When exceptions occur, you can troubleshoot issues by referring to the detailed error descriptions in the *errCode* parameter. + This callback indicates the state of the RTMP or RTMPS streaming. When exceptions occur, you can troubleshoot issues by referring to the detailed error descriptions in the *errCode* parameter. @param rtcChannel IChannel - @param url The RTMP URL address. - @param state The RTMP streaming state. See: #RTMP_STREAM_PUBLISH_STATE. + @param url The CDN streaming URL. + @param state The RTMP or RTMPS streaming state. See: #RTMP_STREAM_PUBLISH_STATE. @param errCode The detailed error information for streaming. See: #RTMP_STREAM_PUBLISH_ERROR. */ virtual void onRtmpStreamingStateChanged(IChannel *rtcChannel, const char *url, RTMP_STREAM_PUBLISH_STATE state, RTMP_STREAM_PUBLISH_ERROR errCode) { @@ -499,12 +476,12 @@ class IChannelEventHandler (RTMP_STREAM_PUBLISH_ERROR) errCode; } - /** Reports events during the RTMP streaming. + /** Reports events during the RTMP or RTMPS streaming. * * @since v3.1.0 * * @param rtcChannel IChannel - * @param url The RTMP streaming URL. + * @param url The RTMP or RTMPS streaming URL. * @param eventCode The event code. See #RTMP_STREAMING_EVENT */ virtual void onRtmpStreamingEvent(IChannel *rtcChannel, const char* url, RTMP_STREAMING_EVENT eventCode) { @@ -524,7 +501,7 @@ class IChannelEventHandler virtual void onTranscodingUpdated(IChannel *rtcChannel) { (void)rtcChannel; } - /** Occurs when a voice or video stream URL address is added to the live interactive streaming. + /** Occurs when a voice or video stream URL address is added to the interactive live streaming. @param rtcChannel IChannel @param url The URL address of the externally injected stream. @@ -629,6 +606,8 @@ class IChannel | Users can join multiple channels simultaneously by creating multiple `IChannel` objects and calling the `joinChannel` method of each object. | Users can join only one channel. | | By default, the SDK does not publish any stream after the user joins the channel. You need to call the publish method to do that. | By default, the SDK publishes streams once the user joins the channel. | + 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. + @note - If you are already in a channel, you cannot rejoin it with the same `uid`. - We recommend using different UIDs for different channels. @@ -662,13 +641,15 @@ class IChannel - The local client: \ref agora::rtc::IRtcEngineEventHandler::onLocalUserRegistered "onLocalUserRegistered" and \ref agora::rtc::IChannelEventHandler::onJoinChannelSuccess "onJoinChannelSuccess" . - The remote client: \ref agora::rtc::IChannelEventHandler::onUserJoined "onUserJoined" and \ref agora::rtc::IRtcEngineEventHandler::onUserInfoUpdated "onUserInfoUpdated" , if the user joining the channel is in the `COMMUNICATION` profile, or is a host in the `LIVE_BROADCASTING` profile. + 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. + @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. @param token The token generated at your server: - For low-security requirements: You can use the temporary token generated at Console. For details, see [Get a temporary toke](https://docs.agora.io/en/Voice/token?platform=All%20Platforms#get-a-temporary-token). - For high-security requirements: Set it as the token generated at your server. For details, see [Get a token](https://docs.agora.io/en/Voice/token?platform=All%20Platforms#get-a-token). - @param userAccount The user account. The maximum length of this parameter is 255 bytes. Ensure that you set this parameter and do not set it as null. Supported character scopes are: + @param 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. @@ -715,7 +696,7 @@ class IChannel 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 live interactive streaming channel, only a host can call this method. To switch the client role, call \ref agora::rtc::IChannel::setClientRole "setClientRole" of the current `IChannel` object. + - In the interactive live streaming channel, only a host can call this method. To switch the client role, call \ref agora::rtc::IChannel::setClientRole "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*. @return @@ -829,8 +810,8 @@ class IChannel * All users in the same channel must use the same encryption mode and encryption key. Once all users leave the channel, the encryption key of this channel is automatically cleared. * * @note - * - If you enable the built-in encryption, you cannot use the RTMP streaming function. - * - Agora supports four encryption modes. If you choose an encryption mode (excepting `SM4_128_ECB` mode), you need to add an external encryption library when integrating the Android and iOS SDK. See the advanced guide *Channel Encryption*. + * - If you enable the built-in encryption, you cannot use the RTMP or RTMPS streaming function. + * - You need to add an external encryption library when integrating the Android and iOS SDK. See the advanced guide *Channel Encryption*. * * @param enabled Whether to enable the built-in encryption: * - true: Enable the built-in encryption. @@ -842,7 +823,7 @@ class IChannel * - < 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. + * - -7(ERR_NOT_INITIALIZED): The SDK is not initialized. Initialize the `IChannel` instance before calling this method. */ virtual int enableEncryption(bool enabled, const EncryptionConfig& config) = 0; /** Registers a packet observer. @@ -895,21 +876,20 @@ class IChannel - < 0: Failure. */ virtual int setClientRole(CLIENT_ROLE_TYPE role) = 0; - /// @cond - /** Sets the role of a user in a live interactive streaming. + + /** Sets the role of a user in interactive live streaming. * * @since v3.2.0 * * You can call this method either before or after joining the channel to set the user role as audience or host. If * you call this method to switch the user role after joining the channel, the SDK triggers the following callbacks: - * - The local client: \ref IRtcChannelEventHandler::onClientRoleChanged "onClientRoleChanged". - * - The remote client: \ref IRtcChannelEventHandler::onUserJoined "onUserJoined" - * or \ref IRtcChannelEventHandler::onUserOffline "onUserOffline". + * - The local client: \ref IChannelEventHandler::onClientRoleChanged "onClientRoleChanged". + * - The remote client: \ref IChannelEventHandler::onUserJoined "onUserJoined" + * or \ref IChannelEventHandler::onUserOffline "onUserOffline". * * @note - * - This method applies to the `LIVE_BROADCASTING` profile only (when the `profile` parameter in - * \ref IRtcChannel::setChannelProfile "setChannelProfile" is set as `CHANNEL_PROFILE_LIVE_BROADCASTING`). - * - The difference between this method and \ref IRtcChannel::setClientRole(CLIENT_ROLE_TYPE) "setClientRole1" is that + * - This method applies to the `LIVE_BROADCASTING` profile only. + * - The difference between this method and \ref IChannel::setClientRole(CLIENT_ROLE_TYPE) "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. @@ -917,15 +897,7 @@ class IChannel * role. For example, an audience can choose to receive remote streams with low latency or ultra low latency. Levels * affect prices. * - * **Example** - * ```cpp - * ClientRoleOptions options; - * options.audienceLatencyLevel = AUDIENCE_LATENCY_LEVEL_ULTRA_LOW_LATENCY; - * options.audienceLatencyLevel = AUDIENCE_LATENCY_LEVEL_LOW_LATENCY; - * agoraChannel->setClientRole(role, options); - * ``` - * - * @param role The role of a user in a live interactive streaming. See #CLIENT_ROLE_TYPE. + * @param role The role of a user in interactive live streaming. See #CLIENT_ROLE_TYPE. * @param options The detailed options of a user, including user level. See ClientRoleOptions. * * @return @@ -936,7 +908,7 @@ class IChannel * - -7(ERR_NOT_INITIALIZED): The SDK is not initialized. */ virtual int setClientRole(CLIENT_ROLE_TYPE role, const ClientRoleOptions& options) = 0; - /// @endcond + /** Prioritizes a remote user's stream. * * The SDK ensures the high-priority user gets the best possible stream quality. @@ -997,58 +969,69 @@ class IChannel - < 0: Failure. */ virtual int setRemoteRenderMode(uid_t userId, RENDER_MODE_TYPE renderMode, VIDEO_MIRROR_MODE_TYPE mirrorMode) = 0; - /** Sets whether to receive all remote audio streams by default. - - You can call this method either before or after joining a channel. If you call `setDefaultMuteAllRemoteAudioStreams (true)` after joining a channel, the remote audio streams of all subsequent users are not received. - - @note If you want to resume receiving the audio stream, call \ref agora::rtc::IChannel::muteRemoteAudioStream "muteRemoteAudioStream (false)", - and specify the ID of the remote user whose audio stream you want to receive. - To receive the audio streams of multiple remote users, call `muteRemoteAudioStream (false)` as many times. - Calling `setDefaultMuteAllRemoteAudioStreams (false)` resumes receiving the audio streams of subsequent users only. - - @param mute Sets whether to receive/stop receiving all remote users' audio streams by default: - - true: Stops receiving all remote users' audio streams by default. - - false: (Default) Receives all remote users' audio streams by default. - - @return - - 0: Success. - - < 0: Failure. + /** 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 \ref IRtcEngine::setDefaultMuteAllRemoteAudioStreams "setDefaultMuteAllRemoteAudioStreams" (true), do the following: + * - If you need to resume subscribing to the audio stream of a specified user, call \ref IRtcEngine::muteRemoteAudioStream "muteRemoteAudioStream" (false), and specify the user ID. + * - If you need to resume subscribing to the audio streams of multiple remote users, call \ref IRtcEngine::muteRemoteAudioStream "muteRemoteAudioStream" (false) multiple times. + * + * @param mute Sets whether to stop subscribing to the audio streams of all remote users by default. + * - true: Stop subscribing to the audio streams of all remote users by default. + * - false: (Default) Resume subscribing to the audio streams of all remote users by default. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int setDefaultMuteAllRemoteAudioStreams(bool mute) = 0; - /** Sets whether to receive all remote video streams by default. - - You can call this method either before or after joining a channel. If you - call `setDefaultMuteAllRemoteVideoStreams (true)` after joining a channel, - the remote video streams of all subsequent users are not received. - - @note If you want to resume receiving the video stream, call - \ref agora::rtc::IChannel::muteRemoteVideoStream "muteRemoteVideoStream (false)", - and specify the ID of the remote user whose video stream you want to receive. - To receive the video streams of multiple remote users, call `muteRemoteVideoStream (false)` - as many times. Calling `setDefaultMuteAllRemoteVideoStreams (false)` resumes - receiving the video streams of subsequent users only. - - @param mute Sets whether to receive/stop receiving all remote users' video streams by default: - - true: Stop receiving all remote users' video streams by default. - - false: (Default) Receive all remote users' video streams by default. - - @return - - 0: Success. - - < 0: Failure. + /** 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 \ref IChannel::setDefaultMuteAllRemoteVideoStreams "setDefaultMuteAllRemoteVideoStreams" (true), do the following: + * - If you need to resume subscribing to the video stream of a specified user, call \ref IChannel::muteRemoteVideoStream "muteRemoteVideoStream" (false), and specify the user ID. + * - If you need to resume subscribing to the video streams of multiple remote users, call \ref IChannel::muteRemoteVideoStream "muteRemoteVideoStream" (false) multiple times. + * + * @param mute Sets whether to stop subscribing to the video streams of all remote users by default. + * - true: Stop subscribing to the video streams of all remote users by default. + * - false: (Default) Resume subscribing to the video streams of all remote users by default. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int setDefaultMuteAllRemoteVideoStreams(bool mute) = 0; - /** Stops/Resumes receiving all remote users' audio streams. - - @param mute Sets whether to receive/stop receiving all remote users' audio streams. - - true: Stops receiving all remote users' audio streams. - - false: (Default) Receives all remote users' audio streams. - - @return - - 0: Success. - - < 0: Failure. + /** + * Stops or resumes subscribing to the audio streams of all remote users. + * + * 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. + * + * @note + * - Call this method after joining a channel. + * - See recommended settings in *Set the Subscribing State*. + * + * @param mute Sets whether to stop subscribing to the audio streams of all remote users. + * - true: Stop subscribing to the audio streams of all remote users. + * - false: (Default) Resume subscribing to the audio streams of all remote users. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int muteAllRemoteAudioStreams(bool mute) = 0; - /** Adjust the playback volume of the specified remote user. + /** Adjust the playback signal volume of the specified remote user. After joining a channel, call \ref agora::rtc::IRtcEngine::adjustPlaybackSignalVolume "adjustPlaybackSignalVolume" to adjust the playback volume of different remote users, or adjust multiple times for one remote user. @@ -1069,56 +1052,57 @@ class IChannel - < 0: Failure. */ virtual int adjustUserPlaybackSignalVolume(uid_t userId, int volume) = 0; - /** Stops/Resumes receiving a specified remote user's audio stream. - - @note - - You can call this method either before or after joining a channel. If you call it before joining a channel, - you need to maintain the `uid` of the remote user on your app level. - - If you called the \ref agora::rtc::IChannel::muteAllRemoteAudioStreams "muteAllRemoteAudioStreams" method and set `mute` as `true` to stop - receiving all remote users' audio streams, call the `muteAllRemoteAudioStreams` method and set `mute` as `false` before calling this method. - The `muteAllRemoteAudioStreams` method sets all remote audio streams, while the `muteRemoteAudioStream` method sets a specified remote audio stream. - - @param userId The user ID of the specified remote user sending the audio. - @param mute Sets whether to receive/stop receiving a specified remote user's audio stream: - - true: Stops receiving the specified remote user's audio stream. - - false: (Default) Receives the specified remote user's audio stream. - - @return - - 0: Success. - - < 0: Failure. - - */ + /** + * Stops or resumes subscribing to the audio stream of a specified user. + * + * @note + * - Call this method after joining a channel. + * - See recommended settings in *Set the Subscribing State*. + * + * @param userId The user ID of the specified remote user. + * @param mute Sets whether to stop subscribing to the audio stream of a specified user. + * - true: Stop subscribing to the audio stream of a specified user. + * - false: (Default) Resume subscribing to the audio stream of a specified user. + * + * @return + * - 0: Success. + * - < 0: Failure. + */ virtual int muteRemoteAudioStream(uid_t userId, bool mute) = 0; - /** Stops/Resumes receiving all video stream from a specified remote user. - - @note You can call this method either before or after joining a channel. - - @param mute Sets whether to receive/stop receiving all remote users' video streams: - - true: Stop receiving all remote users' video streams. - - false: (Default) Receive all remote users' video streams. - - @return - - 0: Success. - - < 0: Failure. + /** + * Stops or resumes subscribing to the video streams of all remote users. + * + * 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. + * + * @note + * - Call this method after joining a channel. + * - See recommended settings in *Set the Subscribing State*. + * + * @param mute Sets whether to stop subscribing to the video streams of all remote users. + * - true: Stop subscribing to the video streams of all remote users. + * - false: (Default) Resume subscribing to the video streams of all remote users. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int muteAllRemoteVideoStreams(bool mute) = 0; - /** Stops/Resumes receiving the video stream from a specified remote user. - - @note - - You can call this method either before or after joining a channel. If you call it before joining a channel, you - need to maintain the `uid` of the remote user on your app level. - - If you called the \ref agora::rtc::IChannel::muteAllRemoteVideoStreams "muteAllRemoteVideoStreams" method and - set `mute` as `true` to stop receiving all remote video streams, call the `muteAllRemoteVideoStreams` method and - set `mute` as `false` before calling this method. - - @param userId The user ID of the specified remote user. - @param mute Sets whether to stop/resume receiving the video stream from a specified remote user: - - true: Stop receiving the specified remote user's video stream. - - false: (Default) Receive the specified remote user's video stream. - - @return - - 0: Success. - - < 0: Failure. + /** + * Stops or resumes subscribing to the video stream of a specified user. + * + * @note + * - Call this method after joining a channel. + * - See recommended settings in *Set the Subscribing State*. + * + * @param userId The user ID of the specified remote user. + * @param mute Sets whether to stop subscribing to the video stream of a specified user. + * - true: Stop subscribing to the video stream of a specified user. + * - false: (Default) Resume subscribing to the video stream of a specified user. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int muteRemoteVideoStream(uid_t userId, bool mute) = 0; /** Sets the stream type of the remote video. @@ -1168,10 +1152,12 @@ class IChannel virtual int setRemoteDefaultVideoStreamType(REMOTE_VIDEO_STREAM_TYPE streamType) = 0; /** Creates a data stream. + @deprecated This method is deprecated from v3.3.0. Use the \ref IChannel::createDataStream(int* streamId, DataStreamConfig& config) "createDataStream" [2/2] method instead. + Each user can create up to five data streams during the lifecycle of the IChannel. @note - - Set both the `reliable` and `ordered` parameters to `true` or `false`. Do not set one as `true` and the other as `false`. + - Do not set `reliable` as `true` while setting `ordered` as `false`. - Ensure that you call this method after joining a channel. @param[out] streamId The ID of the created data stream. @@ -1189,6 +1175,23 @@ class IChannel - < 0: Failure. */ virtual int createDataStream(int* streamId, bool reliable, bool ordered) = 0; + /** 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. + * + * @param[out] streamId The ID of the created data stream. + * @param config The configurations for the data stream: DataStreamConfig. + * + * @return + * - 0: Creates the data stream successfully. + * - < 0: Fails to create the data stream. + */ + virtual int createDataStream(int* streamId, DataStreamConfig& config) = 0; /** Sends data stream messages to all users in a channel. The SDK has the following restrictions on this method: @@ -1215,44 +1218,45 @@ class IChannel - < 0: Failure. */ virtual int sendStreamMessage(int streamId, const char* data, size_t length) = 0; - /** Publishes the local stream to a specified CDN live RTMP address. (CDN live only.) + /** Publishes the local stream to a specified CDN streaming URL. (CDN live only.) The SDK returns the result of this method call in the \ref IRtcEngineEventHandler::onStreamPublished "onStreamPublished" callback. - The \ref agora::rtc::IChannel::addPublishStreamUrl "addPublishStreamUrl" method call triggers + After calling this method, you can push media streams in RTMP or RTMPS protocol to the CDN. The SDK triggers the \ref agora::rtc::IChannelEventHandler::onRtmpStreamingStateChanged "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 RTMP Converter service before using this function. See Prerequisites in the advanced guide *Push Streams to CDN*. - - This method adds only one stream RTMP URL address each time it is called. + - 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. - @param url The CDN streaming URL in the RTMP format. The maximum length of this parameter is 1024 bytes. The RTMP URL address must not contain special characters, such as Chinese language characters. - @param transcodingEnabled Sets whether transcoding is enabled/disabled: + @param url The 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. + @param transcodingEnabled Sets whether transcoding is enabled/disabled: - true: Enable transcoding. To [transcode](https://docs.agora.io/en/Agora%20Platform/terms?platform=All%20Platforms#transcoding) 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 \ref IChannel::setLiveTranscoding "setLiveTranscoding" method before this method. - false: Disable transcoding. @return - 0: Success. - < 0: Failure. - - #ERR_INVALID_ARGUMENT (2): The RTMP URL address is NULL or has a string length of 0. - - #ERR_NOT_INITIALIZED (7): You have not initialized `IChannel` when publishing the stream. + - #ERR_INVALID_ARGUMENT (-2): The CDN streaming URL is NULL or has a string length of 0. + - #ERR_NOT_INITIALIZED (-7): You have not initialized `IChannel` when publishing the stream. */ virtual int addPublishStreamUrl(const char *url, bool transcodingEnabled) = 0; - /** Removes an RTMP stream from the CDN. + /** Removes an RTMP or RTMPS stream from the CDN. - This method removes the RTMP URL address (added by the \ref IChannel::addPublishStreamUrl "addPublishStreamUrl" method) from a CDN live stream. + This method removes the CDN streaming URL (added by the \ref IChannel::addPublishStreamUrl "addPublishStreamUrl" method) from a CDN live stream. The SDK returns the result of this method call in the \ref IRtcEngineEventHandler::onStreamUnpublished "onStreamUnpublished" callback. The \ref agora::rtc::IChannel::removePublishStreamUrl "removePublishStreamUrl" method call triggers - the \ref agora::rtc::IChannelEventHandler::onRtmpStreamingStateChanged "onRtmpStreamingStateChanged" callback on the local client to report the state of removing an RTMP stream from the CDN. + the \ref agora::rtc::IChannelEventHandler::onRtmpStreamingStateChanged "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 RTMP URL address each time it is called. - - The RTMP URL address must not contain special characters, such as Chinese language characters. + - 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. - @param url The RTMP URL address to be removed. The maximum length of this parameter is 1024 bytes. + @param url The CDN streaming URL to be removed. The maximum length of this parameter is 1024 bytes. @return - 0: Success. @@ -1268,6 +1272,7 @@ class IChannel - Ensure that you enable the RTMP Converter service before using this function. See Prerequisites in the advanced guide *Push Streams to CDN*.. - 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. @param transcoding Sets the CDN live audio/video transcoding settings. See LiveTranscoding. @@ -1304,10 +1309,10 @@ class IChannel @return - 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 \ref IRtcEngine::setChannelProfile "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. + - #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 \ref IRtcEngine::setChannelProfile "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. */ virtual int addInjectStreamUrl(const char* url, const InjectStreamConfig& config) = 0; /** Removes the voice or video stream URL address from a live streaming. diff --git a/Android/APIExample/lib-stream-encrypt/src/main/cpp/include/agora/IAgoraRtcEngine.h b/Android/APIExample/lib-stream-encrypt/src/main/cpp/include/agora/IAgoraRtcEngine.h index ab6b753f4..044772eb4 100644 --- a/Android/APIExample/lib-stream-encrypt/src/main/cpp/include/agora/IAgoraRtcEngine.h +++ b/Android/APIExample/lib-stream-encrypt/src/main/cpp/include/agora/IAgoraRtcEngine.h @@ -196,7 +196,10 @@ enum MEDIA_DEVICE_STATE_TYPE MEDIA_DEVICE_STATE_NOT_PRESENT = 4, /** 8: The device is unplugged. */ - MEDIA_DEVICE_STATE_UNPLUGGED = 8 + MEDIA_DEVICE_STATE_UNPLUGGED = 8, + /** 16: The device is not recommended. + */ + MEDIA_DEVICE_STATE_UNRECOMMENDED = 16 }; /** Media device types. @@ -209,7 +212,7 @@ enum MEDIA_DEVICE_TYPE /** 0: Audio playback device. */ AUDIO_PLAYOUT_DEVICE = 0, - /** 1: Audio recording device. + /** 1: Audio capturing device. */ AUDIO_RECORDING_DEVICE = 1, /** 2: Video renderer. @@ -255,6 +258,10 @@ enum LOCAL_VIDEO_STREAM_ERROR { LOCAL_VIDEO_STREAM_ERROR_CAPTURE_FAILURE = 4, /** 5: The local video encoding fails. */ LOCAL_VIDEO_STREAM_ERROR_ENCODE_FAILURE = 5, + /** 6: capture InBackground. */ + LOCAL_VIDEO_STREAM_ERROR_CAPTURE_INBACKGROUND = 6, + /** 7:capture MultipleForegroundApps. */ + LOCAL_VIDEO_STREAM_ERROR_CAPTURE_MULTIPLE_FOREGROUND_APPS = 7, /** 11: The shared window is minimized when you call \ref IRtcEngine::startScreenCaptureByWindowId "startScreenCaptureByWindowId" to share a window. */ LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_WINDOW_MINIMIZED = 11, @@ -280,7 +287,7 @@ enum LOCAL_AUDIO_STREAM_STATE /** 0: The local audio is in the initial state. */ LOCAL_AUDIO_STREAM_STATE_STOPPED = 0, - /** 1: The recording device starts successfully. + /** 1: The capturing device starts successfully. */ LOCAL_AUDIO_STREAM_STATE_RECORDING = 1, /** 2: The first audio frame encodes successfully. @@ -307,7 +314,7 @@ enum LOCAL_AUDIO_STREAM_ERROR /** 3: The microphone is in use. */ LOCAL_AUDIO_STREAM_ERROR_DEVICE_BUSY = 3, - /** 4: The local audio recording fails. Check whether the recording device + /** 4: The local audio capturing fails. Check whether the capturing device * is working properly. */ LOCAL_AUDIO_STREAM_ERROR_RECORD_FAILURE = 4, @@ -635,8 +642,8 @@ enum CHANNEL_PROFILE_TYPE */ CHANNEL_PROFILE_GAME = 2, }; -/// @cond -/** The role of a user in a live interactive streaming. */ + +/** The role of a user in interactive live streaming. */ enum CLIENT_ROLE_TYPE { /** 1: Host. A host can both send and receive streams. */ @@ -645,9 +652,9 @@ enum CLIENT_ROLE_TYPE CLIENT_ROLE_AUDIENCE = 2, }; -/** The latency level of an audience member in a live interactive streaming. +/** The latency level of an audience member in interactive live streaming. * - * @note Takes effect only when the user role is `CLIENT_ROLE_BROADCASTER`. + * @note Takes effect only when the user role is `CLIENT_ROLE_AUDIENCE`. */ enum AUDIENCE_LATENCY_LEVEL_TYPE { @@ -688,68 +695,68 @@ enum USER_OFFLINE_REASON_TYPE USER_OFFLINE_BECOME_AUDIENCE = 2, }; /** - States of the RTMP streaming. + States of the RTMP or RTMPS streaming. */ enum RTMP_STREAM_PUBLISH_STATE { - /** The RTMP streaming has not started or has ended. This state is also triggered after you remove an RTMP address from the CDN by calling removePublishStreamUrl. + /** The RTMP or RTMPS streaming has not started or has ended. This state is also triggered after you remove an RTMP or RTMPS stream from the CDN by calling `removePublishStreamUrl`. */ RTMP_STREAM_PUBLISH_STATE_IDLE = 0, - /** The SDK is connecting to Agora's streaming server and the RTMP server. This state is triggered after you call the \ref IRtcEngine::addPublishStreamUrl "addPublishStreamUrl" method. + /** The SDK is connecting to Agora's streaming server and the CDN server. This state is triggered after you call the \ref IRtcEngine::addPublishStreamUrl "addPublishStreamUrl" method. */ RTMP_STREAM_PUBLISH_STATE_CONNECTING = 1, - /** The RTMP streaming publishes. The SDK successfully publishes the RTMP streaming and returns this state. + /** The RTMP or RTMPS streaming publishes. The SDK successfully publishes the RTMP or RTMPS streaming and returns this state. */ RTMP_STREAM_PUBLISH_STATE_RUNNING = 2, - /** The RTMP streaming is recovering. When exceptions occur to the CDN, or the streaming is interrupted, the SDK tries to resume RTMP streaming and returns this state. + /** The RTMP or RTMPS streaming is recovering. When exceptions occur to the CDN, or the streaming is interrupted, the SDK tries to resume RTMP or RTMPS streaming and returns this state. - If the SDK successfully resumes the streaming, #RTMP_STREAM_PUBLISH_STATE_RUNNING (2) returns. - If the streaming does not resume within 60 seconds or server errors occur, #RTMP_STREAM_PUBLISH_STATE_FAILURE (4) returns. You can also reconnect to the server by calling the \ref IRtcEngine::removePublishStreamUrl "removePublishStreamUrl" and \ref IRtcEngine::addPublishStreamUrl "addPublishStreamUrl" methods. */ RTMP_STREAM_PUBLISH_STATE_RECOVERING = 3, - /** The RTMP streaming fails. See the errCode parameter for the detailed error information. You can also call the \ref IRtcEngine::addPublishStreamUrl "addPublishStreamUrl" method to publish the RTMP streaming again. + /** The RTMP or RTMPS streaming fails. See the errCode parameter for the detailed error information. You can also call the \ref IRtcEngine::addPublishStreamUrl "addPublishStreamUrl" method to publish the RTMP or RTMPS streaming again. */ RTMP_STREAM_PUBLISH_STATE_FAILURE = 4, }; /** - Error codes of the RTMP streaming. + Error codes of the RTMP or RTMPS streaming. */ enum RTMP_STREAM_PUBLISH_ERROR { - /** The RTMP streaming publishes successfully. */ + /** The RTMP or RTMPS streaming publishes successfully. */ RTMP_STREAM_PUBLISH_ERROR_OK = 0, /** Invalid argument used. If, for example, you do not call the \ref IRtcEngine::setLiveTranscoding "setLiveTranscoding" method to configure the LiveTranscoding parameters before calling the addPublishStreamUrl method, the SDK returns this error. Check whether you set the parameters in the *setLiveTranscoding* method properly. */ RTMP_STREAM_PUBLISH_ERROR_INVALID_ARGUMENT = 1, - /** The RTMP streaming is encrypted and cannot be published. */ + /** The RTMP or RTMPS streaming is encrypted and cannot be published. */ RTMP_STREAM_PUBLISH_ERROR_ENCRYPTED_STREAM_NOT_ALLOWED = 2, - /** Timeout for the RTMP streaming. Call the \ref IRtcEngine::addPublishStreamUrl "addPublishStreamUrl" method to publish the streaming again. */ + /** Timeout for the RTMP or RTMPS streaming. Call the \ref IRtcEngine::addPublishStreamUrl "addPublishStreamUrl" method to publish the streaming again. */ RTMP_STREAM_PUBLISH_ERROR_CONNECTION_TIMEOUT = 3, - /** An error occurs in Agora's streaming server. Call the addPublishStreamUrl method to publish the streaming again. */ + /** An error occurs in Agora's streaming server. Call the `addPublishStreamUrl` method to publish the streaming again. */ RTMP_STREAM_PUBLISH_ERROR_INTERNAL_SERVER_ERROR = 4, - /** An error occurs in the RTMP server. */ + /** An error occurs in the CDN server. */ RTMP_STREAM_PUBLISH_ERROR_RTMP_SERVER_ERROR = 5, - /** The RTMP streaming publishes too frequently. */ + /** The RTMP or RTMPS streaming publishes too frequently. */ RTMP_STREAM_PUBLISH_ERROR_TOO_OFTEN = 6, /** The host publishes more than 10 URLs. Delete the unnecessary URLs before adding new ones. */ RTMP_STREAM_PUBLISH_ERROR_REACH_LIMIT = 7, /** The host manipulates other hosts' URLs. Check your app logic. */ RTMP_STREAM_PUBLISH_ERROR_NOT_AUTHORIZED = 8, - /** Agora's server fails to find the RTMP streaming. */ + /** Agora's server fails to find the RTMP or RTMPS streaming. */ RTMP_STREAM_PUBLISH_ERROR_STREAM_NOT_FOUND = 9, - /** The format of the RTMP streaming URL is not supported. Check whether the URL format is correct. */ + /** The format of the RTMP or RTMPS streaming URL is not supported. Check whether the URL format is correct. */ RTMP_STREAM_PUBLISH_ERROR_FORMAT_NOT_SUPPORTED = 10, }; -/** Events during the RTMP streaming. */ +/** Events during the RTMP or RTMPS streaming. */ enum RTMP_STREAMING_EVENT { - /** An error occurs when you add a background image or a watermark image to the RTMP stream. + /** An error occurs when you add a background image or a watermark image to the RTMP or RTMPS stream. */ RTMP_STREAMING_EVENT_FAILED_LOAD_IMAGE = 1, }; -/** States of importing an external video stream in the live interactive streaming. */ +/** States of importing an external video stream in the interactive live streaming. */ enum INJECT_STREAM_STATUS { /** 0: The external video stream imported successfully. */ @@ -783,12 +790,31 @@ enum REMOTE_VIDEO_STREAM_TYPE /** 1: Low-stream video. */ REMOTE_VIDEO_STREAM_LOW = 1, }; +/** The brightness level of the video image captured by the local camera. + * + * @since v3.3.0 + */ +enum CAPTURE_BRIGHTNESS_LEVEL_TYPE { + /** -1: The SDK does not detect the brightness level of the video image. + * Wait a few seconds to get the brightness level from `CAPTURE_BRIGHTNESS_LEVEL_TYPE` in the next callback. + */ + CAPTURE_BRIGHTNESS_LEVEL_INVALID = -1, + /** 0: The brightness level of the video image is normal. + */ + CAPTURE_BRIGHTNESS_LEVEL_NORMAL = 0, + /** 1: The brightness level of the video image is too bright. + */ + CAPTURE_BRIGHTNESS_LEVEL_BRIGHT = 1, + /** 2: The brightness level of the video image is too dark. + */ + CAPTURE_BRIGHTNESS_LEVEL_DARK = 2, +}; /** The use mode of the audio data in the \ref media::IAudioFrameObserver::onRecordAudioFrame "onRecordAudioFrame" or \ref media::IAudioFrameObserver::onPlaybackAudioFrame "onPlaybackAudioFrame" callback. */ enum RAW_AUDIO_FRAME_OP_MODE_TYPE { - /** 0: Read-only mode: Users only read the \ref agora::media::IAudioFrameObserver::AudioFrame "AudioFrame" data without modifying anything. For example, when users acquire the data with the Agora SDK, then push the RTMP streams. */ + /** 0: Read-only mode: Users only read the \ref agora::media::IAudioFrameObserver::AudioFrame "AudioFrame" data without modifying anything. For example, when users acquire the data with the Agora SDK, then push the RTMP or RTMPS streams. */ RAW_AUDIO_FRAME_OP_MODE_READ_ONLY = 0, /** 1: Write-only mode: Users replace the \ref agora::media::IAudioFrameObserver::AudioFrame "AudioFrame" data with their own data and pass the data to the SDK for encoding. For example, when users acquire the data. */ RAW_AUDIO_FRAME_OP_MODE_WRITE_ONLY = 1, @@ -1064,6 +1090,17 @@ enum VOICE_BEAUTIFIER_PRESET * @note Agora recommends using this enumerator to process a female-sounding voice; otherwise, you may experience vocal distortion. */ CHAT_BEAUTIFIER_VITALITY = 0x01010300, + /** + * @since v3.3.0 + * + * Singing beautifier effect. + * - If you call \ref IRtcEngine::setVoiceBeautifierPreset "setVoiceBeautifierPreset" (SINGING_BEAUTIFIER), you can beautify a male-sounding voice and add a reverberation + * effect that sounds like singing in a small room. Agora recommends not using \ref IRtcEngine::setVoiceBeautifierPreset "setVoiceBeautifierPreset" (SINGING_BEAUTIFIER) + * to process a female-sounding voice; otherwise, you may experience vocal distortion. + * - If you call \ref IRtcEngine::setVoiceBeautifierParameters "setVoiceBeautifierParameters"(SINGING_BEAUTIFIER, param1, param2), you can beautify a male- or + * female-sounding voice and add a reverberation effect. + */ + SINGING_BEAUTIFIER = 0x01020100, /** A more vigorous voice. */ TIMBRE_TRANSFORMATION_VIGOROUS = 0x01030100, @@ -1076,7 +1113,7 @@ enum VOICE_BEAUTIFIER_PRESET /** A falsetto voice. */ TIMBRE_TRANSFORMATION_FALSETTO = 0x01030400, - /** A falsetto voice. + /** A fuller voice. */ TIMBRE_TRANSFORMATION_FULL = 0x01030500, /** A clearer voice. @@ -1216,16 +1253,16 @@ enum AUDIO_EFFECT_PRESET VOICE_CHANGER_EFFECT_HULK = 0x02020700, /** An audio effect typical of R&B music. * - * @note To achieve better audio effect quality, Agora recommends calling \ref IRtcEngine::setAudioProfile "setAudioProfile" and - * setting the `profile` parameter to `AUDIO_PROFILE_MUSIC_HIGH_QUALITY(4)` or `AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5)` before - * setting this enumerator. + * @note Call \ref IRtcEngine::setAudioProfile "setAudioProfile" and + * set the `profile` parameter to `AUDIO_PROFILE_MUSIC_HIGH_QUALITY(4)` or `AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5)` before + * setting this enumerator; otherwise, the enumerator setting does not take effect. */ STYLE_TRANSFORMATION_RNB = 0x02030100, /** An audio effect typical of popular music. * - * @note To achieve better audio effect quality, Agora recommends calling \ref IRtcEngine::setAudioProfile "setAudioProfile" and - * setting the `profile` parameter to `AUDIO_PROFILE_MUSIC_HIGH_QUALITY(4)` or `AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5)` before - * setting this enumerator. + * @note Call \ref IRtcEngine::setAudioProfile "setAudioProfile" and + * set the `profile` parameter to `AUDIO_PROFILE_MUSIC_HIGH_QUALITY(4)` or `AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5)` before + * setting this enumerator; otherwise, the enumerator setting does not take effect. */ STYLE_TRANSFORMATION_POPULAR = 0x02030200, /** A pitch correction effect that corrects the user's pitch based on the pitch of the natural C major scale. @@ -1237,6 +1274,14 @@ enum AUDIO_EFFECT_PRESET */ PITCH_CORRECTION = 0x02040100 }; +enum VOICE_CONVERSION_PRESET +{ + VOICE_CONVERSION_OFF = 0x00000000, + VOICE_CHANGER_NEUTRAL = 0x03010100, + VOICE_CHANGER_SWEET = 0x03010200, + VOICE_CHANGER_SOLID = 0x03010300, + VOICE_CHANGER_BASS = 0x03010400 +}; /** Audio codec profile types. The default value is LC_ACC. */ enum AUDIO_CODEC_PROFILE_TYPE { @@ -1525,7 +1570,7 @@ enum STREAM_FALLBACK_OPTIONS STREAM_FALLBACK_OPTION_AUDIO_ONLY = 2, }; - /** Camera capturer configuration. + /** Camera capture preference. */ enum CAPTURER_OUTPUT_PREFERENCE { @@ -1538,6 +1583,11 @@ enum STREAM_FALLBACK_OPTIONS /** 2: Prioritizes the local preview quality. The SDK chooses higher camera output parameters to improve the local video preview quality. This option requires extra CPU and RAM usage for video pre-processing. */ CAPTURER_OUTPUT_PREFERENCE_PREVIEW = 2, + /** 3: Allows you to customize the width and height of the video image captured by the local camera. + * + * @since v3.3.0 + */ + CAPTURER_OUTPUT_PREFERENCE_MANUAL = 3, }; /** The priority of the remote user. @@ -1599,7 +1649,7 @@ enum CONNECTION_CHANGED_REASON_TYPE CONNECTION_CHANGED_JOIN_SUCCESS = 1, /** 2: The connection between the SDK and Agora's edge server is interrupted. */ CONNECTION_CHANGED_INTERRUPTED = 2, - /** 3: The connection between the SDK and Agora's edge server is banned by Agora's edge server. */ + /** 3: The user is banned by the server. This error occurs when the user is kicked out the channel from the server. */ CONNECTION_CHANGED_BANNED_BY_SERVER = 3, /** 4: The SDK fails to join the channel for more than 20 minutes and stops reconnecting to the channel. */ CONNECTION_CHANGED_JOIN_FAILED = 4, @@ -1633,6 +1683,8 @@ enum CONNECTION_CHANGED_REASON_TYPE CONNECTION_CHANGED_CLIENT_IP_ADDRESS_CHANGED = 13, /** 14: Timeout for the keep-alive of the connection between the SDK and Agora's edge server. The connection state changes to CONNECTION_STATE_RECONNECTING(4). */ CONNECTION_CHANGED_KEEP_ALIVE_TIMEOUT = 14, + /** 15: In cloud proxy mode, the proxy server connection interrupted. */ + CONNECTION_CHANGED_PROXY_SERVER_INTERRUPTED = 15, }; /** Network type. */ @@ -1644,7 +1696,7 @@ enum NETWORK_TYPE NETWORK_TYPE_DISCONNECTED = 0, /** 1: The network type is LAN. */ NETWORK_TYPE_LAN = 1, - /** 2: The network type is Wi-Fi(including hotspots). */ + /** 2: The network type is Wi-Fi (including hotspots). */ NETWORK_TYPE_WIFI = 2, /** 3: The network type is mobile 2G. */ NETWORK_TYPE_MOBILE_2G = 3, @@ -1653,6 +1705,27 @@ enum NETWORK_TYPE /** 5: The network type is mobile 4G. */ NETWORK_TYPE_MOBILE_4G = 5, }; +/// @cond +/** + * The reason for the upload failure. + * + * @since v3.3.0 + */ +enum UPLOAD_ERROR_REASON +{ + /** 0: The log file is successfully uploaded. + */ + UPLOAD_SUCCESS = 0, + /** + * 1: Network error. Check the network connection and call \ref IRtcEngine::uploadLogFile "uploadLogFile" again to upload the log file. + */ + UPLOAD_NET_ERROR = 1, + /** + * 2: An error occurs in the Agora server. Try uploading the log files later. + */ + UPLOAD_SERVER_ERROR = 2, +}; +/// @endcond /** States of the last-mile network probe test. */ enum LASTMILE_PROBE_RESULT_STATE { @@ -1700,6 +1773,24 @@ enum AUDIO_ROUTE_TYPE { AUDIO_ROUTE_AIRPLAY = 9, }; +/** The cloud proxy type. + * + * @since v3.3.0 + */ +enum CLOUD_PROXY_TYPE { + /** 0: Do not use the cloud proxy. + */ + NONE_PROXY = 0, + /** 1: The cloud proxy for the UDP protocol. + */ + UDP_PROXY = 1, + /// @cond + /** 2: The cloud proxy for the TCP (encrypted) protocol. + */ + TCP_PROXY = 2, + /// @endcond +}; + #if (defined(__APPLE__) && TARGET_OS_IOS) /** Audio session restriction. */ enum AUDIO_SESSION_OPERATION_RESTRICTION { @@ -1763,44 +1854,45 @@ struct LastmileProbeConfig { unsigned int expectedDownlinkBitrate; }; -/** Properties of the audio volume information. - - An array containing the user ID and volume information for each speaker. +/** The volume information of users. */ struct AudioVolumeInfo { /** - User ID of the speaker. The uid of the local user is 0. + * The user ID. + * - In the local user's callback, `uid = 0`. + * - In the remote users' callback, `uid` is the ID of a remote user whose instantaneous volume is one of the three highest. */ uid_t uid; - /** The volume of the speaker. The volume ranges between 0 (lowest volume) and 255 (highest volume). + /** The volume of each user after audio mixing. The value ranges between 0 (lowest volume) and 255 (highest volume). + * In the local user's callback, `volume = totalVolume`. */ unsigned int volume; /** Voice activity status of the local user. - * - 0: The local user is not speaking. - * - 1: The local user is speaking. + * - `0`: The local user is not speaking. + * - `1`: The local user is speaking. * * @note - * - The `vad` parameter cannot report the voice activity status of the remote users. In the remote users' callback, `vad` = 0. - * - Ensure that you set `report_vad`(true) in the \ref agora::rtc::IRtcEngine::enableAudioVolumeIndication(int, int, bool) "enableAudioVolumeIndication" method to enable the voice activity detection of the local user. + * - The `vad` parameter cannot report the voice activity status of remote users. + * In the remote users' callback, `vad` is always `0`. + * - To use this parameter, you must set the `report_vad` parameter to `true` + * when calling \ref agora::rtc::IRtcEngine::enableAudioVolumeIndication(int, int, bool) "enableAudioVolumeIndication". */ unsigned int vad; - /** The channel ID, which indicates which channel the speaker is in. + /** The name of the channel where the user is in. */ const char * channelId; }; -/// @cond /** The detailed options of a user. */ struct ClientRoleOptions { - /** The latency level of an audience member in a live interactive streaming. See #AUDIENCE_LATENCY_LEVEL_TYPE. + /** The latency level of an audience member in interactive live streaming. See #AUDIENCE_LATENCY_LEVEL_TYPE. */ AUDIENCE_LATENCY_LEVEL_TYPE audienceLatencyLevel; ClientRoleOptions() : audienceLatencyLevel(AUDIENCE_LATENCY_LEVEL_ULTRA_LOW_LATENCY) {} }; -/// @endcond /** Statistics of the channel. */ struct RtcStats @@ -1945,6 +2037,41 @@ enum QUALITY_ADAPT_INDICATION { /** The quality worsens because the network bandwidth decreases. */ ADAPT_DOWN_BANDWIDTH = 2, }; +/** Quality of experience (QoE) of the local user when receiving a remote audio stream. + * + * @since v3.3.0 + */ +enum EXPERIENCE_QUALITY_TYPE +{ + /** 0: QoE of the local user is good. */ + EXPERIENCE_QUALITY_GOOD = 0, + /** 1: QoE of the local user is poor. */ + EXPERIENCE_QUALITY_BAD = 1, +}; + +/** + * The reason for poor QoE of the local user when receiving a remote audio stream. + * + * @since v3.3.0 + */ +enum EXPERIENCE_POOR_REASON { + /** 0: No reason, indicating good QoE of the local user. + */ + EXPERIENCE_REASON_NONE = 0, + /** 1: The remote user's network quality is poor. + */ + REMOTE_NETWORK_QUALITY_POOR = 1, + /** 2: The local user's network quality is poor. + */ + LOCAL_NETWORK_QUALITY_POOR = 2, + /** 4: The local user's Wi-Fi or mobile network signal is weak. + */ + WIRELESS_SIGNAL_POOR = 4, + /** 8: The local user enables both Wi-Fi and bluetooth, and their signals interfere with each other. + * As a result, audio transmission quality is undermined. + */ + WIFI_BLUETOOTH_COEXIST = 8, +}; /** The error code in CHANNEL_MEDIA_RELAY_ERROR. */ enum CHANNEL_MEDIA_RELAY_ERROR { @@ -2110,6 +2237,11 @@ struct LocalVideoStats /** The capture frame rate (fps) of the local video. */ int captureFrameRate; + /** The brightness level of the video image captured by the local camera. See #CAPTURE_BRIGHTNESS_LEVEL_TYPE. + * + * @since v3.3.0 + */ + CAPTURE_BRIGHTNESS_LEVEL_TYPE captureBrightnessLevel; }; /** Statistics of the remote video stream. @@ -2232,6 +2364,22 @@ struct RemoteAudioStats * The total publish duration (ms) of the remote audio stream. */ int publishDuration; + /** + * Quality of experience (QoE) of the local user when receiving a remote audio stream. See #EXPERIENCE_QUALITY_TYPE. + * + * @since v3.3.0 + */ + int qoeQuality; + /** + * The reason for poor QoE of the local user when receiving a remote audio stream. See #EXPERIENCE_POOR_REASON. + * + * @since v3.3.0 + */ + int qualityChangedReason; + /** + * The mos value of remote audio. + */ + int mosValue; }; /** @@ -2252,7 +2400,7 @@ struct VideoDimensions { /** (Recommended) The standard bitrate set in the \ref IRtcEngine::setVideoEncoderConfiguration "setVideoEncoderConfiguration" method. - In this mode, the bitrates differ between the live interactive streaming and communication profiles: + In this mode, the bitrates differ between the interactive live streaming and communication profiles: - `COMMUNICATION` profile: The video bitrate is the same as the base bitrate. - `LIVE_BROADCASTING` profile: The video bitrate is twice the base bitrate. @@ -2352,7 +2500,7 @@ struct VideoEncoderConfiguration { DEGRADATION_PREFERENCE degradationPreference; /** Sets the mirror mode of the published local video stream. It only affects the video that the remote user sees. See #VIDEO_MIRROR_MODE_TYPE - @note: The SDK disables the mirror mode by default. + @note The SDK disables the mirror mode by default. */ VIDEO_MIRROR_MODE_TYPE mirrorMode; @@ -2419,16 +2567,17 @@ typedef struct TranscodingUser { - 1.0: (Default) Opaque */ double alpha; - /** The audio channel of the sound. The default value is 0: + /** The audio channel where the host's audio is located. The value range is [0,5]. - 0: (Default) Supports dual channels at most, depending on the upstream of the host. - - 1: The audio stream of the host uses the FL audio channel. If the upstream of the host uses multiple audio channels, these channels are mixed into mono first. - - 2: The audio stream of the host uses the FC audio channel. If the upstream of the host uses multiple audio channels, these channels are mixed into mono first. - - 3: The audio stream of the host uses the FR audio channel. If the upstream of the host uses multiple audio channels, these channels are mixed into mono first. - - 4: The audio stream of the host uses the BL audio channel. If the upstream of the host uses multiple audio channels, these channels are mixed into mono first. - - 5: The audio stream of the host uses the BR audio channel. If the upstream of the host uses multiple audio channels, these channels are mixed into mono first. + - 1: The host's audio uses the FL audio channel. If the host's upstream uses multiple audio channels, these channels are mixed into mono first. + - 2: The host's audio uses the FC audio channel. If the host's upstream uses multiple audio channels, these channels are mixed into mono first. + - 3: The host's audio uses the FR audio channel. If the host's upstream uses multiple audio channels, these channels are mixed into mono first. + - 4: The host's audio uses the BL audio channel. If the host's upstream uses multiple audio channels, these channels are mixed into mono first. + - 5: The host's audio uses the BR audio channel. If the host's upstream uses multiple audio channels, these channels are mixed into mono first. + - `0xFF` or a value greater than `5`: The host's audio is muted. The Agora server removes the host's audio. - @note If your setting is not 0, you may need a specialized player. + @note If the value is not `0`, a special player is required. */ int audioChannel; TranscodingUser() @@ -2468,7 +2617,7 @@ typedef struct RtcImage { int height; } RtcImage; /// @cond -/** The configuration for advanced features of the RTMP streaming with transcoding. +/** The configuration for advanced features of the RTMP or RTMPS streaming with transcoding. */ typedef struct LiveStreamAdvancedFeature { LiveStreamAdvancedFeature() : featureName(NULL) , opened(false) { @@ -2536,7 +2685,7 @@ typedef struct LiveTranscoding { /** video codec type */ VIDEO_CODEC_TYPE_FOR_STREAM videoCodecType; - /** The number of users in the live interactive streaming. + /** The number of users in the interactive live streaming. */ unsigned int userCount; /** TranscodingUser @@ -2581,7 +2730,7 @@ typedef struct LiveTranscoding { AUDIO_CODEC_PROFILE_TYPE audioCodecProfile; /// @cond - /** Advanced features of the RTMP streaming with transcoding. See LiveStreamAdvancedFeature. + /** Advanced features of the RTMP or RTMPS streaming with transcoding. See LiveStreamAdvancedFeature. * * @since v3.1.0 */ @@ -2621,43 +2770,102 @@ typedef struct LiveTranscoding { /** Camera capturer preference settings. See: #CAPTURER_OUTPUT_PREFERENCE. */ CAPTURER_OUTPUT_PREFERENCE preference; + /** The width (px) of the video image captured by the local camera. + * To customize the width of the video image, set `preference` as #CAPTURER_OUTPUT_PREFERENCE_MANUAL (3) first, + * and then use `captureWidth`. + * + * @since v3.3.0 + */ + int captureWidth; + /** The height (px) of the video image captured by the local camera. + * To customize the height of the video image, set `preference` as #CAPTURER_OUTPUT_PREFERENCE_MANUAL (3) first, + * and then use `captureHeight`. + * + * @since v3.3.0 + */ + int captureHeight; #if defined(__ANDROID__) || (defined(__APPLE__) && TARGET_OS_IOS) /** Camera direction settings (for Android/iOS only). See: #CAMERA_DIRECTION. */ CAMERA_DIRECTION cameraDirection; #endif - }; + CameraCapturerConfiguration() + :preference(CAPTURER_OUTPUT_PREFERENCE_AUTO) + ,captureWidth(640) + ,captureHeight(480) + {} + + CameraCapturerConfiguration(int width, int height) + :preference(CAPTURER_OUTPUT_PREFERENCE_MANUAL) + ,captureWidth(width) + ,captureHeight(height) + {} + }; +/** The configurations for the data stream. + * + * @since v3.3.0 + * + * |`syncWithAudio` |`ordered`| SDK behaviors| + * |--------------|--------|-------------| + * | false | false |The SDK triggers the `onStreamMessage` callback immediately after the receiver receives a data packet | + * | true | false |

If the data packet delay is within the audio delay, the SDK triggers the `onStreamMessage` callback when the synchronized audio packet is played out.

If the data packet delay exceeds the audio delay, the SDK triggers the `onStreamMessage` callback as soon as the data packet is received. In this case, the data packet is not synchronized with the audio packet.

| + * | false | true |

If the delay of a data packet is within five seconds, the SDK corrects the order of the data packet.

If the delay of a data packet exceeds five seconds, the SDK discards the data packet.

| + * | true | true |

If the delay of a data packet is within the audio delay, the SDK corrects the order of the data packet.

If the delay of a data packet exceeds the audio delay, the SDK discards this data packet.

| + */ +struct DataStreamConfig { + /** Whether to synchronize the data packet with the published audio packet. + * + * - true: Synchronize the data packet with the audio packet. + * - false: Do not synchronize the data packet with the audio packet. + * + * When you set the data packet to synchronize with the audio, then if the data + * packet delay is within the audio delay, the SDK triggers the `onStreamMessage` callback when + * the synchronized audio packet is played out. Do not set this parameter as `true` if you + * need the receiver to receive the data packet immediately. Agora recommends that you set + * this parameter to `true` only when you need to implement specific functions, for example + * lyric synchronization. + */ + bool syncWithAudio; + /** Whether the SDK guarantees that the receiver receives the data in the sent order. + * + * - true: Guarantee that the receiver receives the data in the sent order. + * - false: Do not guarantee that the receiver receives the data in the sent order. + * + * Do not set this parameter to `true` if you need the receiver to receive the data immediately. + */ + bool ordered; +}; /** Configuration of the injected media stream. */ struct InjectStreamConfig { - /** Width of the injected stream in the live interactive streaming. The default value is 0 (same width as the original stream). + /** Width of the injected stream in the interactive live streaming. The default value is 0 (same width as the original stream). */ int width; - /** Height of the injected stream in the live interactive streaming. The default value is 0 (same height as the original stream). + /** Height of the injected stream in the interactive live streaming. The default value is 0 (same height as the original stream). */ int height; - /** Video GOP (in frames) of the injected stream in the live interactive streaming. The default value is 30 fps. + /** Video GOP (in frames) of the injected stream in the interactive live streaming. The default value is 30 fps. */ int videoGop; - /** Video frame rate of the injected stream in the live interactive streaming. The default value is 15 fps. + /** Video frame rate of the injected stream in the interactive live streaming. The default value is 15 fps. */ int videoFramerate; - /** Video bitrate of the injected stream in the live interactive streaming. The default value is 400 Kbps. + /** Video bitrate of the injected stream in the interactive live streaming. The default value is 400 Kbps. @note The setting of the video bitrate is closely linked to the resolution. If the video bitrate you set is beyond a reasonable range, the SDK sets it within a reasonable range. */ int videoBitrate; - /** Audio-sample rate of the injected stream in the live interactive streaming: #AUDIO_SAMPLE_RATE_TYPE. The default value is 48000 Hz. + /** Audio-sample rate of the injected stream in the interactive live streaming: #AUDIO_SAMPLE_RATE_TYPE. The default value is 48000 Hz. @note We recommend setting the default value. */ AUDIO_SAMPLE_RATE_TYPE audioSampleRate; - /** Audio bitrate of the injected stream in the live interactive streaming. The default value is 48. + /** Audio bitrate of the injected stream in the interactive live streaming. The default value is 48. @note We recommend setting the default value. */ int audioBitrate; - /** Audio channels in the live interactive streaming. + /** Audio channels in the interactive live streaming. - 1: (Default) Mono @@ -2716,7 +2924,7 @@ struct ChannelMediaRelayConfiguration { */ ChannelMediaInfo *destInfos; /** The number of destination channels. The default value is 0, and the - * value range is [0,4). Ensure that the value of this parameter + * value range is [0,4]. Ensure that the value of this parameter * corresponds to the number of ChannelMediaInfo structs you define in * `destInfos`. */ @@ -3302,7 +3510,7 @@ class IRtcEngineEventHandler (void)stats; } - /** Occurs when the user role switches in the live interactive streaming. For example, from a host to an audience or vice versa. + /** Occurs when the user role switches in the interactive live streaming. For example, from a host to an audience or vice versa. This callback notifies the application of a user role switch when the application calls the \ref IRtcEngine::setClientRole "setClientRole" method. @@ -3542,7 +3750,7 @@ class IRtcEngineEventHandler /** Occurs when the local audio state changes. * This callback indicates the state change of the local audio stream, - * including the state of the audio recording and encoding, and allows + * including the state of the audio capturing and encoding, and allows * you to troubleshoot issues when exceptions occur. * * @note @@ -3654,40 +3862,37 @@ class IRtcEngineEventHandler (void)elapseSinceLastState; } - /** Reports which users are speaking, the speakers' volume and whether the local user is speaking. - - This callback reports the IDs and volumes of the loudest speakers (at most 3 users) at the moment in the channel, and whether the local user is speaking. - - By default, this callback is disabled. You can enable it by calling the \ref IRtcEngine::enableAudioVolumeIndication(int, int, bool) "enableAudioVolumeIndication" method. - Once enabled, this callback is triggered at the set interval, regardless of whether a user speaks or not. - - The SDK triggers two independent `onAudioVolumeIndication` callbacks at one time, which separately report the volume information of the local user and all the remote speakers. - For more information, see the detailed parameter descriptions. - - @note - - To enable the voice activity detection of the local user, ensure that you set `report_vad`(true) in the `enableAudioVolumeIndication` method. - - Calling the \ref agora::rtc::IRtcEngine::muteLocalAudioStream "muteLocalAudioStream" method affects the SDK's behavior: - - If the local user calls the \ref agora::rtc::IRtcEngine::muteLocalAudioStream "muteLocalAudioStream" method, the SDK stops triggering the local user's callback. - - 20 seconds after a remote speaker calls the *muteLocalAudioStream* method, the remote speakers' callback excludes this remote user's information; 20 seconds after all remote users call the *muteLocalAudioStream* method, the SDK stops triggering the remote speakers' callback. - - An empty @p speakers array in the *onAudioVolumeIndication* callback suggests that no remote user is speaking at the moment. - - @param speakers A pointer to AudioVolumeInfo: - - In the local user's callback, this struct contains the following members: - - `uid` = 0, - - `volume` = `totalVolume`, which reports the sum of the voice volume and audio-mixing volume of the local user, and - - `vad`, which reports the voice activity status of the local user. - - In the remote speakers' callback, this array contains the following members: - - `uid` of the remote speaker, - - `volume`, which reports the sum of the voice volume and audio-mixing volume of each remote speaker, and - - `vad` = 0. - - An empty speakers array in the callback indicates that no remote user is speaking at the moment. - @param speakerNumber Total number of speakers. The value range is [0, 3]. - - In the local user’s callback, `speakerNumber` = 1, regardless of whether the local user speaks or not. - - In the remote speakers' callback, the callback reports the IDs and volumes of the three loudest speakers when there are more than three remote users in the channel, and `speakerNumber` = 3. - @param totalVolume Total volume after audio mixing. The value ranges between 0 (lowest volume) and 255 (highest volume). - - In the local user’s callback, `totalVolume` is the sum of the voice volume and audio-mixing volume of the local user. - - In the remote speakers' callback, `totalVolume` is the sum of the voice volume and audio-mixing volume of all the remote speakers. + /** Reports the volume information of users. + * + * By default, this callback is disabled. You can enable it by calling \ref IRtcEngine::enableAudioVolumeIndication(int, int, bool) "enableAudioVolumeIndication". + * Once this callback is enabled and users send streams in the channel, the SDK triggers the `onAudioVolumeIndication` callback + * at the time interval set in `enableAudioVolumeIndication`. + * + * The SDK triggers two independent `onAudioVolumeIndication` callbacks simultaneously, which separately report the + * volume information of the local user who sends a stream and the remote users (up to three) whose instantaneous + * volumes are the highest. + * + * @note After you enable this callback, calling \ref agora::rtc::IRtcEngine::muteLocalAudioStream "muteLocalAudioStream" + * affects the SDK's behavior as follows: + * - If the local user calls `muteLocalAudioStream`, the SDK stops triggering the local user's callback. + * - 20 seconds after a remote user whose volume is one of the three highest calls `muteLocalAudioStream`, the + * remote users' callback excludes this remote user's information; 20 seconds after all remote users call + * `muteLocalAudioStream`, the SDK stops triggering the remote users' callback. + * + * @param speakers The volume information of users. See AudioVolumeInfo. + * + * An empty speakers array in the callback indicates that no remote user is in the channel or sending a stream at the moment. + * @param speakerNumber Total number of users. + * - In the local user's callback, when the local user sends a stream, `speakerNumber = 1`. + * - In the remote users' callback, the value ranges between 0 and 3. If the number of remote users who send + * streams is greater than or equal to three, `speakerNumber = 3`. + * @param totalVolume Total volume after audio mixing. The value ranges between 0 (lowest volume) and 255 (highest volume). + * - In the local user's callback, totalVolume is the volume of the local user who sends a stream. + * - In the remote users' callback, totalVolume is the sum of the volume of all remote users (up to three) whose + * instantaneous volumes are the highest. + * + * If the user calls \ref agora::rtc::IRtcEngine::startAudioMixing "startAudioMixing", `totalVolume` is the sum of + * the voice volume and audio-mixing volume. */ virtual void onAudioVolumeIndication(const AudioVolumeInfo* speakers, unsigned int speakerNumber, int totalVolume) { (void)speakers; @@ -4075,13 +4280,22 @@ class IRtcEngineEventHandler } /** Occurs when the local video stream state changes. - - This callback indicates the state of the local video stream, including camera capturing and video encoding, and allows you to troubleshoot issues when exceptions occur. - - @note For some device models, the SDK will not trigger this callback when the state of the local video changes while the local video capturing device is in use, so you have to make your own timeout judgment. - - @param localVideoState State type #LOCAL_VIDEO_STREAM_STATE. When the state is LOCAL_VIDEO_STREAM_STATE_FAILED (3), see the `error` parameter for details. - @param error The detailed error information: #LOCAL_VIDEO_STREAM_ERROR. + * + * This callback indicates the state of the local video stream, including camera capturing and video encoding, and allows you to troubleshoot issues when exceptions occur. + * + * The SDK triggers the `onLocalVideoStateChanged(LOCAL_VIDEO_STREAM_STATE_FAILED，LOCAL_VIDEO_STREAM_ERROR_CAPTURE_FAILURE)` callback in the following situations: + * - The application exits to the background, and the system recycles the camera. + * - The camera starts normally, but the captured video is not output for four seconds. + * + * When the camera outputs the captured video frames, if all the video frames are the same for 15 consecutive frames, the SDK triggers the + * `onLocalVideoStateChanged(LOCAL_VIDEO_STREAM_STATE_CAPTURING，LOCAL_VIDEO_STREAM_ERROR_CAPTURE_FAILURE)` callback. Note that the + * video frame duplication detection is only available for video frames with a resolution greater than 200 × 200, a frame rate greater than or equal to 10 fps, + * and a bitrate less than 20 Kbps. + * + * @note For some device models, the SDK will not trigger this callback when the state of the local video changes while the local video capturing device is in use, so you have to make your own timeout judgment. + * + * @param localVideoState State type #LOCAL_VIDEO_STREAM_STATE. + * @param error The detailed error information: #LOCAL_VIDEO_STREAM_ERROR. */ virtual void onLocalVideoStateChanged(LOCAL_VIDEO_STREAM_STATE localVideoState, LOCAL_VIDEO_STREAM_ERROR error) { (void)localVideoState; @@ -4273,14 +4487,14 @@ class IRtcEngineEventHandler } /** - Occurs when the state of the RTMP streaming changes. + Occurs when the state of the RTMP or RTMPS streaming changes. The SDK triggers this callback to report the result of the local user calling the \ref agora::rtc::IRtcEngine::addPublishStreamUrl "addPublishStreamUrl" or \ref agora::rtc::IRtcEngine::removePublishStreamUrl "removePublishStreamUrl" method. - This callback indicates the state of the RTMP streaming. When exceptions occur, you can troubleshoot issues by referring to the detailed error descriptions in the *errCode* parameter. + This callback indicates the state of the RTMP or RTMPS streaming. When exceptions occur, you can troubleshoot issues by referring to the detailed error descriptions in the *errCode* parameter. - @param url The RTMP URL address. - @param state The RTMP streaming state. See: #RTMP_STREAM_PUBLISH_STATE. + @param url The CDN streaming URL. + @param state The RTMP or RTMPS streaming state. See: #RTMP_STREAM_PUBLISH_STATE. @param errCode The detailed error information for streaming. See: #RTMP_STREAM_PUBLISH_ERROR. */ virtual void onRtmpStreamingStateChanged(const char *url, RTMP_STREAM_PUBLISH_STATE state, RTMP_STREAM_PUBLISH_ERROR errCode) { @@ -4289,11 +4503,11 @@ class IRtcEngineEventHandler (void) errCode; } - /** Reports events during the RTMP streaming. + /** Reports events during the RTMP or RTMPS streaming. * * @since v3.1.0 * - * @param url The RTMP streaming URL. + * @param url The RTMP or RTMPS streaming URL. * @param eventCode The event code. See #RTMP_STREAMING_EVENT */ virtual void onRtmpStreamingEvent(const char* url, RTMP_STREAMING_EVENT eventCode) { @@ -4305,14 +4519,14 @@ class IRtcEngineEventHandler Reports the result of calling the \ref IRtcEngine::addPublishStreamUrl "addPublishStreamUrl" method. (CDN live only.) - @param url The RTMP URL address. + @param url The CDN streaming URL. @param error Error code: #ERROR_CODE_TYPE. Main errors include: - #ERR_OK (0): The publishing succeeds. - #ERR_FAILED (1): The publishing fails. - - #ERR_INVALID_ARGUMENT (2): Invalid argument used. If, for example, you did not call \ref agora::rtc::IRtcEngine::setLiveTranscoding "setLiveTranscoding" to configure LiveTranscoding before calling \ref agora::rtc::IRtcEngine::addPublishStreamUrl "addPublishStreamUrl", the SDK reports #ERR_INVALID_ARGUMENT. - - #ERR_TIMEDOUT (10): The publishing timed out. - - #ERR_ALREADY_IN_USE (19): The chosen URL address is already in use for CDN live streaming. - - #ERR_RESOURCE_LIMITED (22): The backend system does not have enough resources for the CDN live streaming. + - #ERR_INVALID_ARGUMENT (-2): Invalid argument used. If, for example, you did not call \ref agora::rtc::IRtcEngine::setLiveTranscoding "setLiveTranscoding" to configure LiveTranscoding before calling \ref agora::rtc::IRtcEngine::addPublishStreamUrl "addPublishStreamUrl", the SDK reports #ERR_INVALID_ARGUMENT. + - #ERR_TIMEDOUT (-10): The publishing timed out. + - #ERR_ALREADY_IN_USE (-19): The chosen URL address is already in use for CDN live streaming. + - #ERR_RESOURCE_LIMITED (-22): The backend system does not have enough resources for the CDN live streaming. - #ERR_ENCRYPTED_STREAM_NOT_ALLOWED_PUBLISH (130): You cannot publish an encrypted stream. - #ERR_PUBLISH_STREAM_CDN_ERROR (151) - #ERR_PUBLISH_STREAM_NUM_REACH_LIMIT (152) @@ -4328,23 +4542,23 @@ class IRtcEngineEventHandler Reports the result of calling the \ref agora::rtc::IRtcEngine::removePublishStreamUrl "removePublishStreamUrl" method. (CDN live only.) - This callback indicates whether you have successfully removed an RTMP stream from the CDN. + This callback indicates whether you have successfully removed an RTMP or RTMPS stream from the CDN. - @param url The RTMP URL address. + @param url The CDN streaming URL. */ virtual void onStreamUnpublished(const char *url) { (void)url; } -/** Occurs when the publisher's transcoding is updated. - * - * When the `LiveTranscoding` class in the \ref agora::rtc::IRtcEngine::setLiveTranscoding "setLiveTranscoding" method updates, the SDK triggers the `onTranscodingUpdated` callback to report the update information to the local host. - * - * @note If you call the `setLiveTranscoding` method to set the LiveTranscoding class for the first time, the SDK does not trigger the `onTranscodingUpdated` callback. - * - */ + /** Occurs when the publisher's transcoding is updated. + * + * When the `LiveTranscoding` class in the \ref agora::rtc::IRtcEngine::setLiveTranscoding "setLiveTranscoding" method updates, the SDK triggers the `onTranscodingUpdated` callback to report the update information to the local host. + * + * @note If you call the `setLiveTranscoding` method to set the LiveTranscoding class for the first time, the SDK does not trigger the `onTranscodingUpdated` callback. + * + */ virtual void onTranscodingUpdated() { } - /** Occurs when a voice or video stream URL address is added to the live interactive streaming. + /** Occurs when a voice or video stream URL address is added to the interactive live streaming. @param url Pointer to the URL address of the externally injected stream. @param uid User ID. @@ -4522,6 +4736,27 @@ class IRtcEngineEventHandler (void)uid; (void)info; } + /// @cond + /** Reports the result of uploading the SDK log files. + * + * @since v3.3.0 + * + * After the method call of \ref IRtcEngine::uploadLogFile "uploadLogFile", the SDK triggers this callback to report the + * result of uploading the log files. If the upload fails, refer to the `reason` parameter to troubleshoot. + * + * @param requestId The request ID. This request ID is the same as `requestId` returned by \ref IRtcEngine::uploadLogFile "uploadLogFile", + * and you can use `requestId` to match a specific upload with a callback. + * @param success Whether the log files are successfully uploaded. + * - true: Successfully uploads the log files. + * - false: Fails to upload the log files. For details, see the `reason` parameter. + * @param reason The reason for the upload failure. See #UPLOAD_ERROR_REASON. + */ + virtual void onUploadLogResult(const char* requestId, bool success, UPLOAD_ERROR_REASON reason) { + (void)requestId; + (void)success; + (void)reason; + } + /// @endcond }; /** @@ -4643,11 +4878,11 @@ class IAudioDeviceCollection virtual ~IAudioDeviceCollection(){} public: - /** Retrieves the total number of audio playback or audio recording devices. + /** Retrieves the total number of audio playback or audio capturing devices. - @note You must first call the \ref IAudioDeviceManager::enumeratePlaybackDevices "enumeratePlaybackDevices" or \ref IAudioDeviceManager::enumerateRecordingDevices "enumerateRecordingDevices" method before calling this method to return the number of audio playback or audio recording devices. + @note You must first call the \ref IAudioDeviceManager::enumeratePlaybackDevices "enumeratePlaybackDevices" or \ref IAudioDeviceManager::enumerateRecordingDevices "enumerateRecordingDevices" method before calling this method to return the number of audio playback or audio capturing devices. - @return Number of audio playback or audio recording devices. + @return Number of audio playback or audio capturing devices. */ virtual int getCount() = 0; @@ -4739,14 +4974,14 @@ class IAudioDeviceManager */ virtual IAudioDeviceCollection* enumeratePlaybackDevices() = 0; - /** Enumerates the audio recording devices. + /** Enumerates the audio capturing devices. - This method returns an IAudioDeviceCollection object that includes all audio recording devices in the system. With the IAudioDeviceCollection object, the application can enumerate the audio recording devices. + This method returns an IAudioDeviceCollection object that includes all audio capturing devices in the system. With the IAudioDeviceCollection object, the application can enumerate the audio capturing devices. @note The application needs to call the \ref IAudioDeviceCollection::release "release" method to release the returned object after using it. @return - - Returns an IAudioDeviceCollection object that includes all audio recording devices in the system: Success. + - Returns an IAudioDeviceCollection object that includes all audio capturing devices in the system: Success. - Returns NULL: Failure. */ virtual IAudioDeviceCollection* enumerateRecordingDevices() = 0; @@ -4763,9 +4998,9 @@ class IAudioDeviceManager */ virtual int setPlaybackDevice(const char deviceId[MAX_DEVICE_ID_LENGTH]) = 0; - /** Sets the audio recording device using the device ID. + /** Sets the audio capturing device using the device ID. - @param deviceId Device ID of the audio recording device, retrieved by calling the \ref IAudioDeviceManager::enumerateRecordingDevices "enumerateRecordingDevices" method. + @param deviceId Device ID of the audio capturing device, retrieved by calling the \ref IAudioDeviceManager::enumerateRecordingDevices "enumerateRecordingDevices" method. @note Plugging or unplugging the audio device does not change the device ID. @@ -4776,16 +5011,25 @@ class IAudioDeviceManager virtual int setRecordingDevice(const char deviceId[MAX_DEVICE_ID_LENGTH]) = 0; /** Starts the audio playback device test. - - This method tests if the playback device works properly. In the test, the SDK plays an audio file specified by the user. If the user can hear the audio, the playback device works properly. - - @param testAudioFilePath Pointer to the path of the audio file for the audio playback device test in UTF-8: - - Supported file formats: wav, mp3, m4a, and aac. - - Supported file sample rates: 8000, 16000, 32000, 44100, and 48000 Hz. - - @return - - 0: Success, and you can hear the sound of the specified audio file. - - < 0: Failure. + * + * This method tests if the audio playback device works properly. Once a user starts the test, the SDK plays an + * audio file specified by the user. If the user can hear the audio, the playback device works properly. + * + * After calling this method, the SDK triggers the + * \ref IRtcEngineEventHandler::onAudioVolumeIndication "onAudioVolumeIndication" callback every 100 ms, which + * reports `uid = 1` and the volume of the playback device. + * + * @note + * - Call this method before joining a channel. + * - This method is for Windows and macOS only. + * + * @param testAudioFilePath Pointer to the path of the audio file for the audio playback device test in UTF-8: + * - Supported file formats: wav, mp3, m4a, and aac. + * - Supported file sample rates: 8000, 16000, 32000, 44100, and 48000 Hz. + * + * @return + * - 0: Success, and you can hear the sound of the specified audio file. + * - < 0: Failure. */ virtual int startPlaybackDeviceTest(const char* testAudioFilePath) = 0; @@ -4881,11 +5125,21 @@ class IAudioDeviceManager */ virtual int getRecordingDeviceMute(bool *mute) = 0; - /** Starts the microphone test. + /** Starts the audio capturing device test. + + This method tests whether the audio sampling device works properly. - This method tests whether the microphone works properly. Once the test starts, the SDK uses the \ref IRtcEngineEventHandler::onAudioVolumeIndication "onAudioVolumeIndication" callback to notify the application with the volume information. + After calling this method, the SDK triggers the + \ref IRtcEngineEventHandler::onAudioVolumeIndication "onAudioVolumeIndication" callback at the time interval set + in this method, which reports `uid = 0` and the volume of the sampling device. + + @note + - Call this method before joining a channel. + - This method is for Windows and macOS only. - @param indicationInterval Interval period (ms) of the \ref IRtcEngineEventHandler::onAudioVolumeIndication "onAudioVolumeIndication" callback cycle. + @param indicationInterval The time interval (ms) at which the `onAudioVolumeIndication` callback returns. We + recommend a setting greater than 200 ms. This value must not be less than 10 ms; otherwise, you can not receive + the `onAudioVolumeIndication` callback. @return - 0: Success. @@ -4922,36 +5176,47 @@ class IAudioDeviceManager */ virtual int getPlaybackDeviceInfo(char deviceId[MAX_DEVICE_ID_LENGTH], char deviceName[MAX_DEVICE_ID_LENGTH]) = 0; - /** Retrieves the audio recording device associated with the device ID. + /** Retrieves the audio capturing device associated with the device ID. - @param deviceId Pointer to the device ID of the audio recording device. + @param deviceId Pointer to the device ID of the audio capturing device. @return - 0: Success. - < 0: Failure. */ virtual int getRecordingDevice(char deviceId[MAX_DEVICE_ID_LENGTH]) = 0; - /** Retrieves the audio recording device information associated with the device ID and device name. + /** Retrieves the audio capturing device information associated with the device ID and device name. - @param deviceId Pointer to the device ID of the recording audio device. - @param deviceName Pointer to the device name of the recording audio device. + @param deviceId Pointer to the device ID of the audio capturing device. + @param deviceName Pointer to the device name of the audio capturing device. @return - 0: Success. - < 0: Failure. */ virtual int getRecordingDeviceInfo(char deviceId[MAX_DEVICE_ID_LENGTH], char deviceName[MAX_DEVICE_ID_LENGTH]) = 0; - /** Starts the audio device loopback test. - - This method tests whether the local audio devices are working properly. After calling this method, the microphone captures the local audio and plays it through the speaker. The \ref IRtcEngineEventHandler::onAudioVolumeIndication "onAudioVolumeIndication" callback returns the local audio volume information at the set interval. - - @note This method tests the local audio devices and does not report the network conditions. - - @param indicationInterval The time interval (ms) at which the \ref IRtcEngineEventHandler::onAudioVolumeIndication "onAudioVolumeIndication" callback returns. - - @return - - 0: Success. - - < 0: Failure. + /** Starts the audio device loopback test. + * + * This method tests whether the local audio sampling device and playback device are working properly. After calling + * this method, the audio sampling device samples the local audio, and the audio playback device plays the sampled + * audio. The SDK triggers two independent + * \ref IRtcEngineEventHandler::onAudioVolumeIndication "onAudioVolumeIndication" callbacks at the time interval set + * in this method, which reports the following information: + * - `uid = 0` and the volume information of the sampling device. + * - `uid = 1` and the volume information of the playback device. + * + * @note + * - Call this method before joining a channel. + * - This method tests local audio devices and does not report the network conditions. + * - This method is for Windows and macOS only. + * + * @param indicationInterval The time interval (ms) at which the `onAudioVolumeIndication` callback returns. We + * recommend a setting greater than 200 ms. This value must not be less than 10 ms; otherwise, you can not receive + * the `onAudioVolumeIndication` callback. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int startAudioDeviceLoopbackTest(int indicationInterval) = 0; @@ -4970,6 +5235,41 @@ class IAudioDeviceManager virtual void release() = 0; }; +/** The configuration of the log files. + * + * @since v3.3.0 + */ +struct LogConfig +{ + /** The absolute path of log files. + * + * The default file path is: + * - Android: `/storage/emulated/0/Android/data//files/agorasdk.log` + * - iOS: `App Sandbox/Library/caches/agorasdk.log` + * - macOS: + * - Sandbox enabled: `App Sandbox/Library/Logs/agorasdk.log`, such as `/Users//Library/Containers//Data/Library/Logs/agorasdk.log`. + * - Sandbox disabled: `～/Library/Logs/agorasdk.log`. + * - Windows: `C:\Users\\AppData\Local\Agora\\agorasdk.log` + * + * Ensure that the directory for the log files exists and is writable. You can use this parameter to rename the log files. + */ + const char* filePath; + /** The size (KB) of a log file. The default value is 1024 KB. If you set `fileSize` to 1024 KB, the SDK outputs at most 5 MB log files; + * if you set it to less than 1024 KB, the setting is invalid, and the maximum size of a log file is still 1024 KB. + */ + int fileSize; + /** The output log level of the SDK. See #LOG_LEVEL. + * + * For example, if you set the log level to WARN, the SDK outputs the logs within levels FATAL, ERROR, and WARN. + */ + LOG_LEVEL level; + LogConfig() + :filePath(NULL) + ,fileSize(-1) + ,level(LOG_LEVEL::LOG_LEVEL_INFO) + {} +}; + /** Definition of RtcEngineContext. */ struct RtcEngineContext @@ -4998,6 +5298,17 @@ struct RtcEngineContext * @note The SDK supports specify only one region. */ unsigned int areaCode; + /** The configuration of the log files that the SDK outputs. See LogConfig. + * + * @since v3.3.0 + * + * By default, the SDK outputs five log files, `agorasdk.log`, `agorasdk_1.log`, `agorasdk_2.log`, `agorasdk_3.log`, `agorasdk_4.log`, each with + * a default size of 1024 KB. These log files are encoded in UTF-8. The SDK writes the latest logs in `agorasdk.log`. When `agorasdk.log` is + * full, the SDK deletes the log file with the earliest modification time among the other four, renames `agorasdk.log` to the name of the + * deleted log file, and creates a new `agorasdk.log` to record latest logs. + * + */ + LogConfig logConfig; RtcEngineContext() :eventHandler(NULL) ,appId(NULL) @@ -5090,9 +5401,17 @@ enum ENCRYPTION_MODE /** 3: 256-bit AES encryption, XTS mode. */ AES_256_XTS = 3, + /// @cond /** 4: 128-bit SM4 encryption, ECB mode. */ SM4_128_ECB = 4, + /// @endcond + /** 5: 128-bit AES encryption, GCM mode. + */ + AES_128_GCM = 5, + /** 6: 256-bit AES encryption, GCM mode. + */ + AES_256_GCM = 6, /** Enumerator boundary. */ MODE_END, @@ -5128,6 +5447,10 @@ struct EncryptionConfig{ return "aes-256-xts"; case SM4_128_ECB: return "sm4-128-ecb"; + case AES_128_GCM: + return "aes-128-gcm"; + case AES_256_GCM: + return "aes-256-gcm"; default: return "aes-128-xts"; } @@ -5136,6 +5459,31 @@ struct EncryptionConfig{ /// @endcond }; +/** The channel media options. + */ +struct ChannelMediaOptions { + /** Determines whether to automatically subscribe to all remote audio streams when the user joins a channel: + - true: (Default) Subscribe. + - false: Do not subscribe. + + This member serves a similar function to the `muteAllRemoteAudioStreams` method. After joining the channel, + you can call the `muteAllRemoteAudioStreams` method to set whether to subscribe to audio streams in the channel. + */ + bool autoSubscribeAudio; + /** Determines whether to subscribe to video streams when the user joins the channel: + - true: (Default) Subscribe. + - false: Do not subscribe. + + This member serves a similar function to the `muteAllRemoteVideoStreams` method. After joining the channel, + you can call the `muteAllRemoteVideoStreams` method to set whether to subscribe to video streams in the channel. + */ + bool autoSubscribeVideo; + ChannelMediaOptions() + : autoSubscribeAudio(true) + , autoSubscribeVideo(true) + {} +}; + /** IRtcEngine is the base interface class of the Agora SDK that provides the main Agora SDK methods invoked by your application. Enable the Agora SDK's communication functionality through the creation of an IRtcEngine object, then call the methods of this object. @@ -5194,7 +5542,7 @@ class IRtcEngine /** Sets the channel profile of the Agora IRtcEngine. * * The Agora IRtcEngine differentiates channel profiles and applies optimization algorithms accordingly. - * For example, it prioritizes smoothness and low latency for a video call, and prioritizes video quality for the live interactive video streaming. + * For example, it prioritizes smoothness and low latency for a video call, and prioritizes video quality for the interactive live video streaming. * * @warning * - To ensure the quality of real-time communication, we recommend that all users in a channel use the same channel profile. @@ -5211,9 +5559,9 @@ class IRtcEngine */ virtual int setChannelProfile(CHANNEL_PROFILE_TYPE profile) = 0; - /** Sets the role of the user, such as a host or an audience (default), before joining a channel in the live interactive streaming. + /** Sets the role of the user, such as a host or an audience (default), before joining a channel in the interactive live streaming. * - * This method can be used to switch the user role in the live interactive streaming after the user joins a channel. + * This method can be used to switch the user role in the interactive live streaming after the user joins a channel. * * In the `LIVE_BROADCASTING` profile, when a user switches user roles after joining a channel, a successful \ref agora::rtc::IRtcEngine::setClientRole "setClientRole" method call triggers the following callbacks: * - The local client: \ref agora::rtc::IRtcEngineEventHandler::onClientRoleChanged "onClientRoleChanged" @@ -5232,8 +5580,8 @@ class IRtcEngine * - -7(ERR_NOT_INITIALIZED): The SDK is not initialized. */ virtual int setClientRole(CLIENT_ROLE_TYPE role) = 0; - /// @cond - /** Sets the role of a user in a live interactive streaming. + + /** Sets the role of a user in interactive live streaming. * * @since v3.2.0 * @@ -5246,7 +5594,7 @@ class IRtcEngine * @note * - This method applies to the `LIVE_BROADCASTING` profile only (when the `profile` parameter in * \ref IRtcEngine::setChannelProfile "setChannelProfile" is set as `CHANNEL_PROFILE_LIVE_BROADCASTING`). - * - The difference between this method and \ref IRtcEngine::setClientRole(CLIENT_ROLE_TYPE) "setClientRole1" is that + * - The difference between this method and \ref IRtcEngine::setClientRole(CLIENT_ROLE_TYPE) "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. @@ -5254,15 +5602,7 @@ class IRtcEngine * role. For example, an audience can choose to receive remote streams with low latency or ultra low latency. Levels * affect prices. * - * **Example** - * ```cpp - * ClientRoleOptions options; - * options.audienceLatencyLevel = AUDIENCE_LATENCY_LEVEL_ULTRA_LOW_LATENCY; - * options.audienceLatencyLevel = AUDIENCE_LATENCY_LEVEL_LOW_LATENCY; - * agoraEngine->setClientRole(role, options); - * ``` - * - * @param role The role of a user in a live interactive streaming. See #CLIENT_ROLE_TYPE. + * @param role The role of a user in interactive live streaming. See #CLIENT_ROLE_TYPE. * @param options The detailed options of a user, including user level. See ClientRoleOptions. * * @return @@ -5273,7 +5613,7 @@ class IRtcEngine * - -7(ERR_NOT_INITIALIZED): The SDK is not initialized. */ virtual int setClientRole(CLIENT_ROLE_TYPE role, const ClientRoleOptions& options) = 0; - /// @endcond + /** Joins a channel with the user ID. Users in the same channel can talk to each other, and multiple users in the same channel can start a group chat. Users with different App IDs cannot call each other. @@ -5282,11 +5622,13 @@ class IRtcEngine You must call the \ref IRtcEngine::leaveChannel "leaveChannel" method to exit the current call before entering another channel. A successful \ref agora::rtc::IRtcEngine::joinChannel "joinChannel" method call triggers the following callbacks: - - The local client: \ref agora::rtc::IRtcEngineEventHandler::onJoinChannelSuccess "onJoinChannelSuccess" + - The local client: \ref agora::rtc::IRtcEngineEventHandler::onJoinChannelSuccess "onJoinChannelSuccess". - The remote client: \ref agora::rtc::IRtcEngineEventHandler::onUserJoined "onUserJoined" , if the user joining the channel is in the `COMMUNICATION` profile, or is a host in the `LIVE_BROADCASTING` profile. When the connection between the client and Agora's server is interrupted due to poor network conditions, the SDK tries reconnecting to the server. When the local client successfully rejoins the channel, the SDK triggers the \ref agora::rtc::IRtcEngineEventHandler::onRejoinChannelSuccess "onRejoinChannelSuccess" callback on the local client. + 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. + @note A channel does not accept duplicate uids, such as two users with the same @p uid. If you set @p uid as 0, the system automatically assigns a @p uid. If you want to join a channel from different devices, ensure that each device has a different uid. @warning Ensure that the App ID used for creating the token is the same App ID used by the \ref IRtcEngine::initialize "initialize" method for initializing the RTC engine. Otherwise, the CDN live streaming may fail. @@ -5300,7 +5642,7 @@ class IRtcEngine - The space character. - Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",". @param info (Optional) Pointer to additional information about the channel. This parameter can be set to NULL or contain channel related information. Other users in the channel will not receive this message. - @param uid (Optional) User ID. A 32-bit unsigned integer with a value ranging from 1 to 232-1. The @p uid must be unique. If a @p uid is not assigned (or set to 0), the SDK assigns and returns a @p uid in the \ref IRtcEngineEventHandler::onJoinChannelSuccess "onJoinChannelSuccess" callback. Your application must record and maintain the returned *uid* since the SDK does not do so. + @param uid (Optional) User ID. A 32-bit unsigned integer with a value ranging from 1 to 232-1. The @p uid must be unique. If a @p uid is not assigned (or set to 0), the SDK assigns and returns a @p uid in the \ref IRtcEngineEventHandler::onJoinChannelSuccess "onJoinChannelSuccess" callback. Your application must record and maintain the returned `uid`, because the SDK does not do so. @return - 0(ERR_OK): Success. @@ -5310,8 +5652,60 @@ class IRtcEngine - -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. + - -7(ERR_NOT_INITIALIZED): The SDK is not initialized before calling this method. */ virtual int joinChannel(const char* token, const char* channelId, const char* info, uid_t uid) = 0; + /** Joins a channel with the user ID, and configures whether to automatically subscribe to the audio or video streams. + * + * @since v3.3.0 + * + * Users in the same channel can talk to each other, and multiple users in the same channel can start a group chat. Users with different App IDs cannot call each other. + * + * You must call the \ref IRtcEngine::leaveChannel "leaveChannel" method to exit the current call before entering another channel. + * + * A successful \ref IRtcEngine::joinChannel "joinChannel" method call triggers the following callbacks: + * - The local client: \ref IRtcEngineEventHandler::onJoinChannelSuccess "onJoinChannelSuccess". + * - The remote client: \ref IRtcEngineEventHandler::onUserJoined "onUserJoined", if the user joining the channel is in the `COMMUNICATION` profile, or is a host in the `LIVE_BROADCASTING` profile. + * + * When the connection between the client and the Agora server is interrupted due to poor network conditions, the SDK tries reconnecting to the server. + * When the local client successfully rejoins the channel, the SDK triggers the \ref IRtcEngineEventHandler::onRejoinChannelSuccess "onRejoinChannelSuccess" callback on the local client. + * + * @note + * - Compared with \ref IRtcEngine::joinChannel(const char* token, const char* channelId, const char* info, uid_t uid) "joinChannel" [1/2], this method + * has the options parameter which configures whether the user automatically subscribes to all remote audio and video streams in the channel when + * joining the channel. By default, the user subscribes to the audio and video streams of all the other users in the channel, thus incurring all + * associated usage costs. To unsubscribe, set the `options` parameter or call the `mute` methods accordingly. + * - Ensure that the App ID used for generating the token is the same App ID used in the \ref IRtcEngine::initialize "initialize" method for + * creating an `IRtcEngine` object. + * + * @param token The token generated at your server. For details, see [Generate a token](https://docs.agora.io/en/Interactive%20Broadcast/token_server?platform=Windows). + * @param channelId Pointer to the unique channel name for the Agora RTC session in the string format smaller than 64 bytes. Supported characters: + * - 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: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",". + * @param info (Optional) Reserved for future use. + * @param uid (Optional) User ID. A 32-bit unsigned integer with a value ranging from 1 to 232-1. The @p uid must be unique. If a @p uid is + * not assigned (or set to 0), the SDK assigns and returns a @p uid in the \ref IRtcEngineEventHandler::onJoinChannelSuccess "onJoinChannelSuccess" callback. + * Your application must record and maintain the returned `uid`, because the SDK does not do so. **Note**: The ID of each user in the channel should be unique. + * If you want to join the same channel from different devices, ensure that the user IDs in all devices are different. + * @param options The channel media options: ChannelMediaOptions. + @return + * - 0(ERR_OK): Success. + * - < 0: Failure. + * - -2(ERR_INALID_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. + * - -7(ERR_NOT_INITIALIZED): The SDK is not initialized before calling this method. + */ + virtual int joinChannel(const char* token, + const char* channelId, + const char* info, + uid_t uid, + const ChannelMediaOptions& options) = 0; /** Switches to a different channel. * * This method allows the audience of a `LIVE_BROADCASTING` channel to switch @@ -5323,6 +5717,12 @@ class IRtcEngine * "onJoinChannelSuccess" callbacks are triggered to indicate that the * user has left the original channel and joined a new one. * + * Once the user switches to another 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. + * * @note * This method applies to the audience role in a `LIVE_BROADCASTING` channel * only. @@ -5354,6 +5754,45 @@ class IRtcEngine * - -113(ERR_NOT_IN_CHANNEL): The user is not in the channel. */ virtual int switchChannel(const char* token, const char* channelId) = 0; + /** Switches to a different channel, and configures whether to automatically subscribe to audio or video streams in the target channel. + * + * @since v3.3.0 + * + * This method allows the audience of a `LIVE_BROADCASTING` channel to switch to a different channel. + * + * After the user successfully switches to another channel, the \ref IRtcEngineEventHandler::onLeaveChannel "onLeaveChannel" + * and \ref IRtcEngineEventHandler::onJoinChannelSuccess "onJoinChannelSuccess" callbacks are triggered to indicate that + * the user has left the original channel and joined a new one. + * + * @note + * - This method applies to the audience role in a `LIVE_BROADCASTING` channel only. + * - The difference between this method and \ref IRtcEngine::switchChannel(const char* token, const char* channelId) "switchChannel[1/2]" + * is that the former adds the options parameter to configure whether the user automatically subscribes to all remote audio and video streams in the target channel. + * By default, the user subscribes to the audio and video streams of all the other users in the target channel, thus incurring all associated usage costs. + * To unsubscribe, set the `options` parameter or call the `mute` methods accordingly. + * + * @param token The token generated at your server. For details, see [Generate a token](https://docs.agora.io/en/Interactive%20Broadcast/token_server?platform=Windows). + * @param channelId Unique channel name for the AgoraRTC session in the + * string format. The string length must be less than 64 bytes. 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: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",". + * @param options The channel media options: ChannelMediaOptions. + * + * @return + * - 0(ERR_OK): Success. + * - < 0: Failure. + * - -1(ERR_FAILED): A general error occurs (no specified reason). + * - -2(ERR_INALID_ARGUMENT): The parameter is invalid. + * - -5(ERR_REFUSED): The request is rejected, probably because the user is not an audience. + * - -7(ERR_NOT_INITIALIZED): The SDK is not initialized. + * - -102(ERR_INVALID_CHANNEL_NAME): The channel name is invalid. + * - -113(ERR_NOT_IN_CHANNEL): The user is not in the channel. + */ + virtual int switchChannel(const char* token, const char* channelId, const ChannelMediaOptions& options) = 0; /** Allows a user to leave a channel, such as hanging up or exiting a call. @@ -5430,7 +5869,7 @@ class IRtcEngine - 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. @param appId The App ID of your project. - @param userAccount The user account. The maximum length of this parameter is 255 bytes. Ensure that you set this parameter and do not set it as null. Supported character scopes are: + @param 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. @@ -5448,7 +5887,9 @@ class IRtcEngine After the user successfully joins the channel, the SDK triggers the following callbacks: - The local client: \ref agora::rtc::IRtcEngineEventHandler::onLocalUserRegistered "onLocalUserRegistered" and \ref agora::rtc::IRtcEngineEventHandler::onJoinChannelSuccess "onJoinChannelSuccess" . - The remote client: \ref agora::rtc::IRtcEngineEventHandler::onUserJoined "onUserJoined" and \ref agora::rtc::IRtcEngineEventHandler::onUserInfoUpdated "onUserInfoUpdated" , if the user joining the channel is in the `COMMUNICATION` profile, or is a host in the `LIVE_BROADCASTING` profile. + - The remote client: \ref agora::rtc::IRtcEngineEventHandler::onUserJoined "onUserJoined" and \ref agora::rtc::IRtcEngineEventHandler::onUserInfoUpdated "onUserInfoUpdated" , if the user joining the channel is in the `COMMUNICATION` profile, or is a host in the `LIVE_BROADCASTING` profile. + + 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. @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. @@ -5462,7 +5903,7 @@ class IRtcEngine - All numeric characters: 0 to 9. - The space character. - Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",". - @param userAccount The user account. The maximum length of this parameter is 255 bytes. Ensure that you set this parameter and do not set it as null. Supported character scopes are: + @param 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. @@ -5479,6 +5920,48 @@ class IRtcEngine virtual int joinChannelWithUserAccount(const char* token, const char* channelId, const char* userAccount) = 0; + /** Joins the channel with a user account, and configures whether to automatically subscribe to audio or video streams after joining the channel. + * + * @since v3.3.0 + * + * After the user successfully joins the channel, the SDK triggers the following callbacks: + * - The local client: \ref agora::rtc::IRtcEngineEventHandler::onLocalUserRegistered "onLocalUserRegistered" and \ref agora::rtc::IRtcEngineEventHandler::onJoinChannelSuccess "onJoinChannelSuccess" . + * - The remote client: \ref agora::rtc::IRtcEngineEventHandler::onUserJoined "onUserJoined" and \ref agora::rtc::IRtcEngineEventHandler::onUserInfoUpdated "onUserInfoUpdated" , if the user joining the channel is in the `COMMUNICATION` profile, or is a host in the `LIVE_BROADCASTING` profile. + * + * @note + * - Compared with \ref IRtcEngine::joinChannelWithUserAccount(const char* token, const char* channelId, const char* userAccount) "joinChannelWithUserAccount" [1/2], + * this method has the options parameter to configure whether the end user automatically subscribes to all remote audio and video streams in a + * channel when joining the channel. By default, the user subscribes to the audio and video streams of all the other users in the channel, thus + * incurring all associated usage costs. To unsubscribe, set the `options` parameter or call the `mute` methods accordingly. + * - 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. + * + * @param token The token generated at your server. For details, see [Generate a token](https://docs.agora.io/en/Interactive%20Broadcast/token_server?platform=Windows). + * @param channelId The channel name. The maximum length of this parameter is 64 bytes. 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: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",". + * @param 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: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",". + * @param options The channel media options: ChannelMediaOptions. + * @return + * - 0: Success. + * - < 0: Failure. + * - #ERR_INVALID_ARGUMENT (-2) + * - #ERR_NOT_READY (-3) + * - #ERR_REFUSED (-5) + */ + virtual int joinChannelWithUserAccount(const char* token, + const char* channelId, + const char* userAccount, + const ChannelMediaOptions& options) = 0; /** Gets the user information by passing in the user account. @@ -5563,7 +6046,32 @@ class IRtcEngine - < 0: Failure. */ virtual int stopEchoTest() = 0; - + /** Sets the Agora cloud proxy service. + * + * @since v3.3.0 + * + * When the user's firewall restricts the IP address and port, refer to *Use Cloud Proxy* to add the specific + * IP addresses and ports to the firewall whitelist; then, call this method to enable the cloud proxy and set + * the `proxyType` parameter as `UDP_PROXY(1)`, which is the cloud proxy for the UDP protocol. + * + * After a successfully cloud proxy connection, the SDK triggers the \ref IRtcEngineEventHandler::onConnectionStateChanged "onConnectionStateChanged" (CONNECTION_STATE_CONNECTING, CONNECTION_CHANGED_SETTING_PROXY_SERVER) callback. + * + * To disable the cloud proxy that has been set, call `setCloudProxy(NONE_PROXY)`. To change the cloud proxy type that has been set, + * call `setCloudProxy(NONE_PROXY)` first, and then call `setCloudProxy`, and pass the value that you expect in `proxyType`. + * + * @note + * - Agora recommends that you call this method before joining the channel or after leaving the channel. + * - When you use the cloud proxy for the UDP protocol, the services for pushing streams to CDN and co-hosting across channels are not available. + * + * @param proxyType The cloud proxy type, see #CLOUD_PROXY_TYPE. This parameter is required, and the SDK reports an error if you do not pass in a value. + * + * @return + * - 0: Success. + * - < 0: Failure. + * - `-2（ERR_INVALID_ARGUMENT)`: The parameter is invalid. + * - `-7(ERR_NOT_INITIALIZED)`: The SDK is not initialized. + */ + virtual int setCloudProxy(CLOUD_PROXY_TYPE proxyType) = 0; /** Enables the video module. Call this method either before joining a channel or during a call. If this method is called before joining a channel, the call starts in the video mode. If this method is called during an audio call, the audio mode switches to the video mode. To disable the video module, call the \ref IRtcEngine::disableVideo "disableVideo" method. @@ -5644,11 +6152,12 @@ class IRtcEngine virtual int setVideoEncoderConfiguration(const VideoEncoderConfiguration& config) = 0; /** Sets the camera capture configuration. - For a video call or the live interactive video streaming, generally the SDK controls the camera output parameters. When the default camera capturer settings do not meet special requirements or cause performance problems, we recommend using this method to set the camera capturer configuration: + For a video call or the interactive live video streaming, generally the SDK controls the camera output parameters. When the default camera capturer settings do not meet special requirements or cause performance problems, we recommend using this method to set the camera capturer configuration: - - If the resolution or frame rate of the captured raw video data are higher than those set by \ref IRtcEngine::setVideoEncoderConfiguration "setVideoEncoderConfiguration", processing video frames requires extra CPU and RAM usage and degrades performance. We recommend setting config as CAPTURER_OUTPUT_PREFERENCE_PERFORMANCE = 1 to avoid such problems. - - If you do not need local video preview or are willing to sacrifice preview quality, we recommend setting config as CAPTURER_OUTPUT_PREFERENCE_PERFORMANCE = 1 to optimize CPU and RAM usage. - - If you want better quality for the local video preview, we recommend setting config as CAPTURER_OUTPUT_PREFERENCE_PREVIEW = 2. + - If the resolution or frame rate of the captured raw video data are higher than those set by \ref IRtcEngine::setVideoEncoderConfiguration "setVideoEncoderConfiguration", processing video frames requires extra CPU and RAM usage and degrades performance. We recommend setting config as #CAPTURER_OUTPUT_PREFERENCE_PERFORMANCE (1) to avoid such problems. + - If you do not need local video preview or are willing to sacrifice preview quality, we recommend setting config as #CAPTURER_OUTPUT_PREFERENCE_PERFORMANCE (1) to optimize CPU and RAM usage. + - If you want better quality for the local video preview, we recommend setting config as #CAPTURER_OUTPUT_PREFERENCE_PREVIEW (2). + - To customize the width and height of the video image captured by the local camera, set the camera capture configuration as #CAPTURER_OUTPUT_PREFERENCE_MANUAL (3). @note Call this method before enabling the local camera. That said, you can call this method before calling \ref agora::rtc::IRtcEngine::joinChannel "joinChannel", \ref agora::rtc::IRtcEngine::enableVideo "enableVideo", or \ref IRtcEngine::enableLocalVideo "enableLocalVideo", depending on which method you use to turn on your local camera. @@ -5742,8 +6251,8 @@ class IRtcEngine The audio mode is enabled by default. @note - - This method affects the internal engine and can be called after the \ref agora::rtc::IRtcEngine::leaveChannel "leaveChannel" method. You can call this method either before or after joining a channel. - - This method resets the internal engine and takes some time to take effect. We recommend using the following API methods to control the audio engine modules separately: + - This method affects the audio module and can be called after the \ref agora::rtc::IRtcEngine::leaveChannel "leaveChannel" method. You can call this method either before or after joining a channel. + - This method enables the audio module and takes some time to take effect. Agora recommends using the following API methods to control the audio module separately: - \ref IRtcEngine::enableLocalAudio "enableLocalAudio": Whether to enable the microphone to create the local audio stream. - \ref IRtcEngine::muteLocalAudioStream "muteLocalAudioStream": Whether to publish the local audio stream. - \ref IRtcEngine::muteRemoteAudioStream "muteRemoteAudioStream": Whether to subscribe to and play the remote audio stream. @@ -5768,7 +6277,7 @@ class IRtcEngine @note - This method is different from the \ref agora::rtc::IRtcEngine::muteLocalAudioStream "muteLocalAudioStream" method: - \ref agora::rtc::IRtcEngine::enableLocalAudio "enableLocalAudio": Disables/Re-enables the local audio capturing and processing. - If you disable or re-enable local audio recording using the `enableLocalAudio` method, the local user may hear a pause in the remote audio playback. + If you disable or re-enable local audio capturing using the `enableLocalAudio` method, the local user may hear a pause in the remote audio playback. - \ref agora::rtc::IRtcEngine::muteLocalAudioStream "muteLocalAudioStream": Sends/Stops sending the local audio streams. - You can call this method either before or after joining a channel. @@ -5811,56 +6320,70 @@ class IRtcEngine - < 0: Failure. */ virtual int setAudioProfile(AUDIO_PROFILE_TYPE profile, AUDIO_SCENARIO_TYPE scenario) = 0; - /** Stops/Resumes sending the local audio stream. - - A successful \ref agora::rtc::IRtcEngine::muteLocalAudioStream "muteLocalAudioStream" method call triggers the \ref agora::rtc::IRtcEngineEventHandler::onUserMuteAudio "onUserMuteAudio" callback on the remote client. - - @note - - When @p mute is set as @p true, this method does not disable the microphone, which does not affect any ongoing recording. - - You can call this method either before or after joining a channel. If you call \ref agora::rtc::IRtcEngine::setChannelProfile "setChannelProfile" after this method, the SDK resets whether or not to mute the local audio according to the channel profile and user role. Therefore, we recommend calling this method after the `setChannelProfile` method. - - @param mute Sets whether to send/stop sending the local audio stream: - - true: Stops sending the local audio stream. - - false: (Default) Sends the local audio stream. - - @return - - 0: Success. - - < 0: Failure. + /** + * Stops or resumes publishing the local audio stream. + * + * A successful \ref agora::rtc::IRtcEngine::muteLocalAudioStream "muteLocalAudioStream" method call + * triggers the \ref agora::rtc::IRtcEngineEventHandler::onUserMuteAudio "onUserMuteAudio" callback on the remote client. + * + * @note + * - When @p mute is set as @p true, this method does not affect any ongoing audio recording, because it does not disable the microphone. + * - You can call this method either before or after joining a channel. If you call \ref agora::rtc::IRtcEngine::setChannelProfile "setChannelProfile" + * after this method, the SDK resets whether or not to stop publishing the local audio according to the channel profile and user role. + * Therefore, we recommend calling this method after the `setChannelProfile` method. + * + * @param mute Sets whether to stop publishing the local audio stream. + * - true: Stop publishing the local audio stream. + * - false: (Default) Resumes publishing the local audio stream. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int muteLocalAudioStream(bool mute) = 0; - /** Stops/Resumes receiving all remote users' audio streams. - - @note You can call this method either before or after joining a channel. - - @param mute Sets whether to receive/stop receiving all remote users' audio streams. - - true: Stops receiving all remote users' audio streams. - - false: (Default) Receives all remote users' audio streams. - - @return - - 0: Success. - - < 0: Failure. + /** + * Stops or resumes subscribing to the audio streams of all remote users. + * + * 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. + * + * @note + * - Call this method after joining a channel. + * - See recommended settings in *Set the Subscribing State*. + * + * @param mute Sets whether to stop subscribing to the audio streams of all remote users. + * - true: Stop subscribing to the audio streams of all remote users. + * - false: (Default) Resume subscribing to the audio streams of all remote users. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int muteAllRemoteAudioStreams(bool mute) = 0; - /** Stops/Resumes receiving all remote users' audio streams by default. - - You can call this method either before or after joining a channel. If you call `setDefaultMuteAllRemoteAudioStreams (true)` after joining a channel, the remote audio streams of all subsequent users are not received. - - @note If you want to resume receiving the audio stream, call \ref agora::rtc::IRtcEngine::muteRemoteAudioStream "muteRemoteAudioStream (false)", - and specify the ID of the remote user whose audio stream you want to receive. - To receive the audio streams of multiple remote users, call `muteRemoteAudioStream (false)` as many times. - Calling `setDefaultMuteAllRemoteAudioStreams (false)` resumes receiving the audio streams of subsequent users only. - - @param mute Sets whether to receive/stop receiving all remote users' audio streams by default: - - true: Stops receiving all remote users' audio streams by default. - - false: (Default) Receives all remote users' audio streams by default. - - @return - - 0: Success. - - < 0: Failure. + /** 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 \ref IRtcEngine::setDefaultMuteAllRemoteAudioStreams "setDefaultMuteAllRemoteAudioStreams" (true), do the following: + * - If you need to resume subscribing to the audio stream of a specified user, call \ref IRtcEngine::muteRemoteAudioStream "muteRemoteAudioStream" (false), and specify the user ID. + * - If you need to resume subscribing to the audio streams of multiple remote users, call \ref IRtcEngine::muteRemoteAudioStream "muteRemoteAudioStream" (false) multiple times. + * + * @param mute Sets whether to stop subscribing to the audio streams of all remote users by default. + * - true: Stop subscribing to the audio streams of all remote users by default. + * - false: (Default) Resume subscribing to the audio streams of all remote users by default. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int setDefaultMuteAllRemoteAudioStreams(bool mute) = 0; - /** Adjusts the playback volume of a specified remote user. + /** Adjusts the playback signal volume of a specified remote user. You can call this method as many times as necessary to adjust the playback volume of different remote users, or to repeatedly adjust the playback volume of the same remote user. @@ -5879,39 +6402,44 @@ class IRtcEngine - < 0: Failure. */ virtual int adjustUserPlaybackSignalVolume(unsigned int uid, int volume) = 0; - /** Stops/Resumes receiving a specified remote user's audio stream. - - @note - - You can call this method either before or after joining a channel. If you call it before joining a channel, - you need to maintain the `uid` of the remote user on your app level. - - If you called the \ref agora::rtc::IRtcEngine::muteAllRemoteAudioStreams "muteAllRemoteAudioStreams" method and set @p mute as @p true to stop receiving all remote users' audio streams, call the *muteAllRemoteAudioStreams* method and set @p mute as @p false before calling this method. The *muteAllRemoteAudioStreams* method sets all remote audio streams, while the *muteRemoteAudioStream* method sets a specified remote audio stream. - - @param userId User ID of the specified remote user sending the audio. - @param mute Sets whether to receive/stop receiving a specified remote user's audio stream: - - true: Stops receiving the specified remote user's audio stream. - - false: (Default) Receives the specified remote user's audio stream. - - @return - - 0: Success. - - < 0: Failure. - + /** + * Stops or resumes subscribing to the audio stream of a specified user. + * + * @note + * - Call this method after joining a channel. + * - See recommended settings in *Set the Subscribing State*. + * + * @param userId The user ID of the specified remote user. + * @param mute Sets whether to stop subscribing to the audio stream of a specified user. + * - true: Stop subscribing to the audio stream of a specified user. + * - false: (Default) Resume subscribing to the audio stream of a specified user. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int muteRemoteAudioStream(uid_t userId, bool mute) = 0; - /** Stops/Resumes sending the local video stream. - - A successful \ref agora::rtc::IRtcEngine::muteLocalVideoStream "muteLocalVideoStream" method call triggers the \ref agora::rtc::IRtcEngineEventHandler::onUserMuteVideo "onUserMuteVideo" callback on the remote client. - - @note - - When set to *true*, this method does not disable the camera which does not affect the retrieval of the local video streams. This method executes faster than the \ref agora::rtc::IRtcEngine::enableLocalVideo "enableLocalVideo" method which controls the sending of the local video stream. - - You can call this method either before or after joining a channel. If you call \ref agora::rtc::IRtcEngine::setChannelProfile "setChannelProfile" after this method, the SDK resets whether or not to mute the local video according to the channel profile and user role. Therefore, we recommend calling this method after the `setChannelProfile` method. - - @param mute Sets whether to send/stop sending the local video stream: - - true: Stop sending the local video stream. - - false: (Default) Send the local video stream. - - @return - - 0: Success. - - < 0: Failure. + /** Stops or resumes publishing the local video stream. + * + * A successful \ref agora::rtc::IRtcEngine::muteLocalVideoStream "muteLocalVideoStream" method call + * triggers the \ref agora::rtc::IRtcEngineEventHandler::onUserMuteVideo "onUserMuteVideo" callback on + * the remote client. + * + * @note + * - This method executes faster than the \ref IRtcEngine::enableLocalVideo "enableLocalVideo" method, + * which controls the sending of the local video stream. + * - When `mute` is set as `true`, this method does not affect any ongoing video recording, because it does not disable the camera. + * - You can call this method either before or after joining a channel. If you call \ref IRtcEngine::setChannelProfile "setChannelProfile" + * after this method, the SDK resets whether or not to stop publishing the local video according to the channel profile and user role. + * Therefore, Agora recommends calling this method after the `setChannelProfile` method. + * + * @param mute Sets whether to stop publishing the local video stream. + * - true: Stop publishing the local video stream. + * - false: (Default) Resumes publishing the local video stream. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int muteLocalVideoStream(bool mute) = 0; /** Enables/Disables the local video capture. @@ -5935,49 +6463,61 @@ class IRtcEngine - < 0: Failure. */ virtual int enableLocalVideo(bool enabled) = 0; - /** Stops/Resumes receiving all video stream from a specified remote user. - - @note You can call this method either before or after joining a channel. - - @param mute Sets whether to receive/stop receiving all remote users' video streams: - - true: Stop receiving all remote users' video streams. - - false: (Default) Receive all remote users' video streams. - - @return - - 0: Success. - - < 0: Failure. + /** + * Stops or resumes subscribing to the video streams of all remote users. + * + * 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. + * + * @note + * - Call this method after joining a channel. + * - See recommended settings in *Set the Subscribing State*. + * + * @param mute Sets whether to stop subscribing to the video streams of all remote users. + * - true: Stop subscribing to the video streams of all remote users. + * - false: (Default) Resume subscribing to the video streams of all remote users. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int muteAllRemoteVideoStreams(bool mute) = 0; - /** Stops/Resumes receiving all remote users' video streams by default. - - You can call this method either before or after joining a channel. If you call `setDefaultMuteAllRemoteVideoStreams (true)` after joining a channel, the remote video streams of all subsequent users are not received. - - @note If you want to resume receiving the video stream, call \ref agora::rtc::IRtcEngine::muteRemoteVideoStream "muteRemoteVideoStream (false)", and specify the ID of the remote user whose video stream you want to receive. To receive the video streams of multiple remote users, call `muteRemoteVideoStream (false)` as many times. Calling `setDefaultMuteAllRemoteVideoStreams (false)` resumes receiving the video streams of subsequent users only. - - @param mute Sets whether to receive/stop receiving all remote users' video streams by default: - - true: Stop receiving all remote users' video streams by default. - - false: (Default) Receive all remote users' video streams by default. - - @return - - 0: Success. - - < 0: Failure. + /** 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 \ref IRtcEngine::setDefaultMuteAllRemoteVideoStreams "setDefaultMuteAllRemoteVideoStreams" (true), do the following: + * - If you need to resume subscribing to the video stream of a specified user, call \ref IRtcEngine::muteRemoteVideoStream "muteRemoteVideoStream" (false), and specify the user ID. + * - If you need to resume subscribing to the video streams of multiple remote users, call \ref IRtcEngine::muteRemoteVideoStream "muteRemoteVideoStream" (false) multiple times. + * + * @param mute Sets whether to stop subscribing to the video streams of all remote users by default. + * - true: Stop subscribing to the video streams of all remote users by default. + * - false: (Default) Resume subscribing to the video streams of all remote users by default. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int setDefaultMuteAllRemoteVideoStreams(bool mute) = 0; - /** Stops/Resumes receiving the video stream from a specified remote user. - - @note - - You can call this method either before or after joining a channel. If you call it before joining a channel, you - need to maintain the `uid` of the remote user on your app level. - - If you called the \ref agora::rtc::IRtcEngine::muteAllRemoteVideoStreams "muteAllRemoteVideoStreams" method and set @p mute as @p true to stop receiving all remote video streams, call the *muteAllRemoteVideoStreams* method and set @p mute as @p false before calling this method. - - @param userId User ID of the specified remote user. - @param mute Sets whether to stop/resume receiving the video stream from a specified remote user: - - true: Stop receiving the specified remote user's video stream. - - false: (Default) Receive the specified remote user's video stream. - - @return - - 0: Success. - - < 0: Failure. + /** + * Stops or resumes subscribing to the video stream of a specified user. + * + * @note + * - Call this method after joining a channel. + * - See recommended settings in *Set the Subscribing State*. + * + * @param userId The user ID of the specified remote user. + * @param mute Sets whether to stop subscribing to the video stream of a specified user. + * - true: Stop subscribing to the video stream of a specified user. + * - false: (Default) Resume subscribing to the video stream of a specified user. + * + * @return + * - 0: Success. + * - < 0: Failure. */ virtual int muteRemoteVideoStream(uid_t userId, bool mute) = 0; /** Sets the stream type of the remote video. @@ -6034,18 +6574,21 @@ class IRtcEngine */ virtual int setRemoteDefaultVideoStreamType(REMOTE_VIDEO_STREAM_TYPE streamType) = 0; - /** Enables the \ref agora::rtc::IRtcEngineEventHandler::onAudioVolumeIndication "onAudioVolumeIndication" callback at a set time interval to report on which users are speaking and the speakers' volume. + /** Enables the reporting of users' volume indication. - Once this method is enabled, the SDK returns the volume indication in the \ref agora::rtc::IRtcEngineEventHandler::onAudioVolumeIndication "onAudioVolumeIndication" callback at the set time interval, whether or not any user is speaking in the channel. + This method enables the SDK to regularly report the volume information of the local user who sends a stream and + remote users (up to three) whose instantaneous volumes are the highest to the app. Once you call this method and + users send streams in the channel, the SDK triggers the + \ref IRtcEngineEventHandler::onAudioVolumeIndication "onAudioVolumeIndication" callback at the time interval set + in this method. @note You can call this method either before or after joining a channel. @param interval Sets the time interval between two consecutive volume indications: - ≤ 0: Disables the volume indication. - > 0: Time interval (ms) between two consecutive volume indications. We recommend setting @p interval > 200 ms. Do not set @p interval < 10 ms, or the *onAudioVolumeIndication* callback will not be triggered. - @param smooth Smoothing factor sets the sensitivity of the audio volume indicator. The value ranges between 0 and 10. The greater the value, the more sensitive the indicator. The recommended value is 3. + @param smooth Smoothing factor sets the sensitivity of the audio volume indicator. The value ranges between 0 and 10. The greater the value, the more sensitive the indicator. The recommended value is 3. @param report_vad - - true: Enable the voice activity detection of the local user. Once it is enabled, the `vad` parameter of the `onAudioVolumeIndication` callback reports the voice activity status of the local user. - false: (Default) Disable the voice activity detection of the local user. Once it is disabled, the `vad` parameter of the `onAudioVolumeIndication` callback does not report the voice activity status of the local user, except for the scenario where the engine automatically detects the voice activity of the local user. @return @@ -6053,9 +6596,9 @@ class IRtcEngine - < 0: Failure. */ virtual int enableAudioVolumeIndication(int interval, int smooth, bool report_vad) = 0; - /** @deprecated Starts an audio recording. + /** Starts an audio recording. - Use \ref IRtcEngine::startAudioRecording(const char* filePath, int sampleRate, AUDIO_RECORDING_QUALITY_TYPE quality) "startAudioRecording"2 instead. + @deprecated Use \ref IRtcEngine::startAudioRecording(const char* filePath, int sampleRate, AUDIO_RECORDING_QUALITY_TYPE quality) "startAudioRecording" [2/2] instead. The SDK allows recording during a call. Supported formats: @@ -6458,6 +7001,48 @@ class IRtcEngine - < 0: Failure. */ virtual int resumeAllEffects() = 0; + /** Enables or disables deep-learning noise reduction. + * + * The SDK enables traditional noise reduction mode by default to reduce most of the stationary background noise. + * If you need to reduce most of the non-stationary background noise, Agora recommends enabling deep-learning + * noise reduction as follows: + * + * 1. Integrate the dynamical library under the libs folder to your project: + * - Android: `libagora_ai_denoise_extension.so` + * - iOS: `AgoraAIDenoiseExtension.xcframework` + * - macOS: `AgoraAIDenoiseExtension.framework` + * - Windows: `libagora_ai_denoise_extension.dll` + * 2. Call `enableDeepLearningDenoise(true)`. + * + * Deep-learning noise reduction requires high-performance devices. For example, the following devices and later + * models are known to support deep-learning noise reduction: + * - iPhone 6S + * - MacBook Pro 2015 + * - iPad Pro (2nd generation) + * - iPad mini (5th generation) + * - iPad Air (3rd generation) + * + * After successfully enabling deep-learning noise reduction, if the SDK detects that the device performance + * is not sufficient, it automatically disables deep-learning noise reduction and enables traditional noise reduction. + * + * If you call `enableDeepLearningDenoise(false)` or the SDK automatically disables deep-learning noise reduction + * in the channel, when you need to re-enable deep-learning noise reduction, you need to call \ref IRtcEngine::leaveChannel "leaveChannel" + * first, and then call `enableDeepLearningDenoise(true)`. + * + * @note + * - This method dynamically loads the library, so Agora recommends calling this method before joining a channel. + * - This method works best with the human voice. Agora does not recommend using this method for audio containing music. + * + * @param enable Sets whether to enable deep-learning noise reduction. + * - true: (Default) Enables deep-learning noise reduction. + * - false: Disables deep-learning noise reduction. + * + * @return + * - 0: Success. + * - < 0: Failure. + * - -157 (ERR_MODULE_NOT_FOUND): The dynamical library for enabling deep-learning noise reduction is not integrated. + */ + virtual int enableDeepLearningDenoise(bool enable) = 0; /** Enables/Disables stereo panning for remote users. Ensure that you call this method before joinChannel to enable stereo panning for remote users so that the local user can track the position of a remote user by calling \ref agora::rtc::IRtcEngine::setRemoteVoicePosition "setRemoteVoicePosition". @@ -6604,14 +7189,15 @@ class IRtcEngine * - Do not set the `profile` parameter of \ref IRtcEngine::setAudioProfile "setAudioProfile" to `AUDIO_PROFILE_SPEECH_STANDARD(1)` * or `AUDIO_PROFILE_IOT(6)`; otherwise, this method call fails. * - This method works best with the human voice. Agora does not recommend using this method for audio containing music. - * - After calling this method, Agora recommends not calling the following methods, because they can override \ref IRtcEngine::setAudioEffectParameters "setAudioEffectParameters": + * - After calling this method, Agora recommends not calling the following methods, because they can override \ref IRtcEngine::setVoiceBeautifierPreset "setVoiceBeautifierPreset": * - \ref IRtcEngine::setAudioEffectPreset "setAudioEffectPreset" - * - \ref IRtcEngine::setVoiceBeautifierPreset "setVoiceBeautifierPreset" + * - \ref IRtcEngine::setAudioEffectParameters "setAudioEffectParameters" * - \ref IRtcEngine::setLocalVoiceReverbPreset "setLocalVoiceReverbPreset" * - \ref IRtcEngine::setLocalVoiceChanger "setLocalVoiceChanger" * - \ref IRtcEngine::setLocalVoicePitch "setLocalVoicePitch" * - \ref IRtcEngine::setLocalVoiceEqualization "setLocalVoiceEqualization" * - \ref IRtcEngine::setLocalVoiceReverb "setLocalVoiceReverb" + * - \ref IRtcEngine::setVoiceBeautifierParameters "setVoiceBeautifierParameters" * * @param preset The options for SDK preset voice beautifier effects: #VOICE_BEAUTIFIER_PRESET. * @@ -6648,6 +7234,7 @@ class IRtcEngine * - \ref IRtcEngine::setLocalVoicePitch "setLocalVoicePitch" * - \ref IRtcEngine::setLocalVoiceEqualization "setLocalVoiceEqualization" * - \ref IRtcEngine::setLocalVoiceReverb "setLocalVoiceReverb" + * - \ref IRtcEngine::setVoiceBeautifierParameters "setVoiceBeautifierParameters" * * @param preset The options for SDK preset audio effects. See #AUDIO_EFFECT_PRESET. * @@ -6656,6 +7243,7 @@ class IRtcEngine * - < 0: Failure. */ virtual int setAudioEffectPreset(AUDIO_EFFECT_PRESET preset) = 0; + virtual int setVoiceConversionPreset(VOICE_CONVERSION_PRESET preset) = 0; /** Sets parameters for SDK preset audio effects. * * @since v3.2.0 @@ -6688,7 +7276,7 @@ class IRtcEngine * - \ref IRtcEngine::setLocalVoicePitch "setLocalVoicePitch" * - \ref IRtcEngine::setLocalVoiceEqualization "setLocalVoiceEqualization" * - \ref IRtcEngine::setLocalVoiceReverb "setLocalVoiceReverb" - * + * - \ref IRtcEngine::setVoiceBeautifierParameters "setVoiceBeautifierParameters" * @param preset The options for SDK preset audio effects: * - 3D voice effect: `ROOM_ACOUSTICS_3D_VOICE`. * - Call \ref IRtcEngine::setAudioProfile "setAudioProfile" and set the `profile` parameter to `AUDIO_PROFILE_MUSIC_STANDARD_STEREO(3)` @@ -6706,7 +7294,7 @@ class IRtcEngine * - `2`: Natural minor scale. * - `3`: Japanese pentatonic scale. * @param param2 - * - If you set `preset` to `ROOM_ACOUSTICS_3D_VOICE`, you do not need to set `param2`. + * - If you set `preset` to `ROOM_ACOUSTICS_3D_VOICE`, you need to set `param2` to `0`. * - If you set `preset` to `PITCH_CORRECTION`, `param2` sets the tonic pitch of the pitch correction effect: * - `1`: A * - `2`: A# @@ -6726,7 +7314,49 @@ class IRtcEngine * - < 0: Failure. */ virtual int setAudioEffectParameters(AUDIO_EFFECT_PRESET preset, int param1, int param2) = 0; + /** Sets parameters for SDK preset voice beautifier effects. + * + * @since v3.3.0 + * + * Call this method to set a gender characteristic and a reverberation effect for the singing beautifier effect. This method sets parameters for the local user who sends an audio stream. + * + * After you call this method successfully, all users in the channel can hear the relevant effect. + * + * To achieve better audio effect quality, before you call this method, Agora recommends calling \ref IRtcEngine::setAudioProfile "setAudioProfile", and setting the `scenario` parameter + * as `AUDIO_SCENARIO_GAME_STREAMING(3)` and the `profile` parameter as `AUDIO_PROFILE_MUSIC_HIGH_QUALITY(4)` or `AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5)`. + * + * @note + * - You can call this method either before or after joining a channel. + * - Do not set the `profile` parameter of \ref IRtcEngine::setAudioProfile "setAudioProfile" as `AUDIO_PROFILE_SPEECH_STANDARD(1)` or `AUDIO_PROFILE_IOT(6)`; otherwise, this method call does not take effect. + * - This method works best with the human voice. Agora does not recommend using this method for audio containing music. + * - After you call this method, Agora recommends not calling the following methods, because they can override `setVoiceBeautifierParameters`: + * - \ref IRtcEngine::setAudioEffectPreset "setAudioEffectPreset" + * - \ref IRtcEngine::setAudioEffectParameters "setAudioEffectParameters" + * - \ref IRtcEngine::setVoiceBeautifierPreset "setVoiceBeautifierPreset" + * - \ref IRtcEngine::setLocalVoiceReverbPreset "setLocalVoiceReverbPreset" + * - \ref IRtcEngine::setLocalVoiceChanger "setLocalVoiceChanger" + * - \ref IRtcEngine::setLocalVoicePitch "setLocalVoicePitch" + * - \ref IRtcEngine::setLocalVoiceEqualization "setLocalVoiceEqualization" + * - \ref IRtcEngine::setLocalVoiceReverb "setLocalVoiceReverb" + * + * @param preset The options for SDK preset voice beautifier effects: + * - `SINGING_BEAUTIFIER`: Singing beautifier effect. + * @param param1 The gender characteristics options for the singing voice: + * - `1`: A male-sounding voice. + * - `2`: A female-sounding voice. + * @param param2 The reverberation effects options: + * - `1`: The reverberation effect sounds like singing in a small room. + * - `2`: The reverberation effect sounds like singing in a large room. + * - `3`: The reverberation effect sounds like singing in a hall. + * + * @return + * - 0: Success. + * - < 0: Failure. + */ + virtual int setVoiceBeautifierParameters(VOICE_BEAUTIFIER_PRESET preset, int param1, int param2) = 0; /** Sets the log files that the SDK outputs. + * + * @deprecated This method is deprecated from v3.3.0. Use `logConfig` in the \ref IRtcEngine::initialize "initialize" method instead. * * By default, the SDK outputs five log files, `agorasdk.log`, `agorasdk_1.log`, `agorasdk_2.log`, `agorasdk_3.log`, `agorasdk_4.log`, each with a default size of 1024 KB. * These log files are encoded in UTF-8. The SDK writes the latest logs in `agorasdk.log`. When `agorasdk.log` is full, the SDK deletes the log file with the earliest @@ -6747,6 +7377,8 @@ class IRtcEngine virtual int setLogFile(const char* filePath) = 0; /** Sets the output log level of the SDK. + @deprecated This method is deprecated from v3.3.0. Use `logConfig` in the \ref IRtcEngine::initialize "initialize" method instead. + You can use one or a combination of the log filter levels. The log level follows the sequence of OFF, CRITICAL, ERROR, WARNING, INFO, and DEBUG. Choose a level to see the logs preceding that level. If you set the log level to WARNING, you see the logs within levels CRITICAL, ERROR, and WARNING. @@ -6763,6 +7395,7 @@ class IRtcEngine virtual int setLogFilter(unsigned int filter) = 0; /** Sets the size of a log file that the SDK outputs. * + * @deprecated This method is deprecated from v3.3.0. Use `logConfig` in the \ref IRtcEngine::initialize "initialize" method instead. * * @note If you want to set the log file size, ensure that you call * this method before \ref IRtcEngine::setLogFile "setLogFile", or the logs are cleared. @@ -6782,8 +7415,33 @@ class IRtcEngine * - < 0: Failure. */ virtual int setLogFileSize(unsigned int fileSizeInKBytes) = 0; + /// @cond + /** Uploads all SDK log files. + * + * @since v3.3.0 + * + * Uploads all SDK log files from the client to the Agora server. + * After a successful method call, the SDK triggers the \ref agora::rtc::IRtcEngineEventHandler::onUploadLogResult "onUploadLogResult" callback + * to report whether the log files are successfully uploaded to the Agora server. + * + * + * For easier debugging, Agora recommends that you bind this method to the UI element of your App, so as to instruct the + * user to upload a log file when a quality issue occurs. + * + * @note Do not call this method more than once per minute, otherwise the SDK reports #ERR_TOO_OFTEN (12). + * + * @param[out] requestId The request ID. This request ID is the same as requestId in the \ref IRtcEngineEventHandler::onUploadLogResult "onUploadLogResult" callback, + * and you can use the request ID to match a specific upload with a callback. + * + * @return + * - 0: Success. + * - < 0: Failure. + * - -12(ERR_TOO_OFTEN): The call frequency exceeds the limit. + */ + virtual int uploadLogFile(agora::util::AString& requestId) = 0; + /// @endcond /** - @deprecated This method is deprecated, use the \ref IRtcEngine::setLocalRenderMode(RENDER_MODE_TYPE renderMode, VIDEO_MIRROR_MODE_TYPE mirrorMode) "setLocalRenderMode"2 method instead. + @deprecated This method is deprecated, use the \ref IRtcEngine::setLocalRenderMode(RENDER_MODE_TYPE renderMode, VIDEO_MIRROR_MODE_TYPE mirrorMode) "setLocalRenderMode" [2/2] method instead. Sets the local video display mode. This method can be called multiple times during a call to change the display mode. @@ -6813,7 +7471,7 @@ class IRtcEngine */ virtual int setLocalRenderMode(RENDER_MODE_TYPE renderMode, VIDEO_MIRROR_MODE_TYPE mirrorMode) = 0; /** - @deprecated This method is deprecated, use the \ref IRtcEngine::setRemoteRenderMode(uid_t userId, RENDER_MODE_TYPE renderMode, VIDEO_MIRROR_MODE_TYPE mirrorMode) "setRemoteRenderMode"2 method instead. + @deprecated This method is deprecated, use the \ref IRtcEngine::setRemoteRenderMode(uid_t userId, RENDER_MODE_TYPE renderMode, VIDEO_MIRROR_MODE_TYPE mirrorMode) "setRemoteRenderMode" [2/2] method instead. Sets the video display mode of a specified remote user. This method can be called multiple times during a call to change the display mode. @@ -6923,7 +7581,7 @@ class IRtcEngine - 1: Mono - 2: Stereo @param mode Sets the use mode (see #RAW_AUDIO_FRAME_OP_MODE_TYPE) of the *onRecordAudioFrame* callback. - @param samplesPerCall Sets the number of samples returned in the *onRecordAudioFrame* callback. `samplesPerCall` is usually set as 1024 for RTMP streaming. + @param samplesPerCall Sets the number of samples returned in the *onRecordAudioFrame* callback. `samplesPerCall` is usually set as 1024 for RTMP or RTMPS streaming. @note The SDK triggers the `onRecordAudioFrame` callback according to the sample interval. Ensure that the sample interval ≥ 0.01 (s). And, Sample interval (sec) = `samplePerCall`/(`sampleRate` × `channel`). @@ -6942,7 +7600,7 @@ class IRtcEngine - 1: Mono - 2: Stereo @param mode Sets the use mode (see #RAW_AUDIO_FRAME_OP_MODE_TYPE) of the *onPlaybackAudioFrame* callback. - @param samplesPerCall Sets the number of samples returned in the *onPlaybackAudioFrame* callback. `samplesPerCall` is usually set as 1024 for RTMP streaming. + @param samplesPerCall Sets the number of samples returned in the *onPlaybackAudioFrame* callback. `samplesPerCall` is usually set as 1024 for RTMP or RTMPS streaming. @note The SDK triggers the `onPlaybackAudioFrame` callback according to the sample interval. Ensure that the sample interval ≥ 0.01 (s). And, Sample interval (sec) = `samplePerCall`/(`sampleRate` × `channel`). @@ -6956,7 +7614,7 @@ class IRtcEngine @note Ensure that you call this method before joining a channel. @param sampleRate Sets the sample rate (@p samplesPerSec) returned in the *onMixedAudioFrame* callback, which can be set as 8000, 16000, 32000, 44100, or 48000 Hz. - @param samplesPerCall Sets the number of samples (`samples`) returned in the *onMixedAudioFrame* callback. `samplesPerCall` is usually set as 1024 for RTMP streaming. + @param samplesPerCall Sets the number of samples (`samples`) returned in the *onMixedAudioFrame* callback. `samplesPerCall` is usually set as 1024 for RTMP or RTMPS streaming. @note The SDK triggers the `onMixedAudioFrame` callback according to the sample interval. Ensure that the sample interval ≥ 0.01 (s). And, Sample interval (sec) = `samplePerCall`/(`sampleRate` × `channels`). @@ -6965,11 +7623,11 @@ class IRtcEngine - < 0: Failure. */ virtual int setMixedAudioFrameParameters(int sampleRate, int samplesPerCall) = 0; - /** Adjusts the recording volume. + /** Adjusts the capturing signal volume. @note You can call this method either before or after joining a channel. - @param volume Recording volume. To avoid echoes and + @param volume Volume. To avoid echoes and improve call quality, Agora recommends setting the value of volume between 0 and 100. If you need to set the value higher than 100, contact support@agora.io first. @@ -6982,7 +7640,7 @@ class IRtcEngine - < 0: Failure. */ virtual int adjustRecordingSignalVolume(int volume) = 0; - /** Adjusts the playback volume of all remote users. + /** Adjusts the playback signal volume of all remote users. @note - This method adjusts the playback volume that is the mixed volume of all remote users. @@ -7140,6 +7798,13 @@ class IRtcEngine - Ensure that you have successfully called the \ref IRtcEngine::joinChannel "joinChannel" method before calling this method. - After calling this method, the SDK returns the \ref IRtcEngineEventHandler::onAudioRouteChanged "onAudioRouteChanged" callback to indicate the changes. - This method does not take effect if a headset is used. + - Settings of \ref IRtcEngine::setAudioProfile "setAudioProfile" and \ref IRtcEngine::setChannelProfile "setChannelProfile" affect the call + result of `setEnableSpeakerphone`. The following are scenarios where `setEnableSpeakerphone` does not take effect: + - If you set `scenario` as `AUDIO_SCENARIO_GAME_STREAMING`, no user can change the audio playback route. + - If you set `scenario` as `AUDIO_SCENARIO_DEFAULT` or `AUDIO_SCENARIO_SHOWROOM`, the audience cannot change + the audio playback route. If there is only one broadcaster is in the channel, the broadcaster cannot change + the audio playback route either. + - If you set `scenario` as `AUDIO_SCENARIO_EDUCATION`, the audience cannot change the audio playback route. @param speakerOn Sets whether to route the audio to the speakerphone or earpiece: - true: Route the audio to the speakerphone. If the playback device connects to the earpiece or Bluetooth, the audio cannot be routed to the speakerphone. @@ -7214,42 +7879,41 @@ class IRtcEngine #endif #if (defined(__APPLE__) && TARGET_OS_MAC && !TARGET_OS_IPHONE) || defined(_WIN32) - /** Enables loopback recording. + /** Enables loopback audio capturing. - If you enable loopback recording, the output of the sound card is mixed into the audio stream sent to the other end. + If you enable loopback audio capturing, the output of the sound card is mixed into the audio stream sent to the other end. @note You can call this method either before or after joining a channel. - @param enabled Sets whether to enable/disable loopback recording. - - true: Enable loopback recording. - - false: (Default) Disable loopback recording. + @param enabled Sets whether to enable/disable loopback capturing. + - true: Enable loopback capturing. + - false: (Default) Disable loopback capturing. @param deviceName Pointer to the device name of the sound card. The default value is NULL (the default sound card). @note - This method is for macOS and Windows only. - - macOS does not support loopback recording of the default sound card. If you need to use this method, please use a virtual sound card and pass its name to the deviceName parameter. Agora has tested and recommends using soundflower. + - macOS does not support loopback capturing of the default sound card. If you need to use this method, please use a virtual sound card and pass its name to the deviceName parameter. Agora has tested and recommends using soundflower. */ virtual int enableLoopbackRecording(bool enabled, const char* deviceName = NULL) = 0; #if (defined(__APPLE__) && TARGET_OS_MAC && !TARGET_OS_IPHONE) /** Shares the whole or part of a screen by specifying the display ID. - * + * * @note * - This method is for macOS only. * - Ensure that you call this method after joining a channel. - * - * @param displayId The display ID of the screen to be shared. This parameter specifies which screen you want to share. - * @param regionRect (Optional) Sets the relative location of the region to the screen. NIL means sharing the whole screen. See Rectangle. If the specified region overruns the screen, the SDK shares only the region within it; if you set width or height as 0, the SDK shares the whole screen. - * @param captureParams Sets the screen sharing encoding parameters. See ScreenCaptureParameters. - * - * + * + * @param displayId The display ID of the screen to be shared. This parameter specifies which screen you want to share. + * @param regionRect (Optional) Sets the relative location of the region to the screen. NIL means sharing the whole screen. See Rectangle. If the specified region overruns the screen, the SDK shares only the region within it; if you set width or height as 0, the SDK shares the whole screen. + * @param captureParams The screen sharing encoding parameters. The default video dimension is 1920 x 1080, that is, 2,073,600 pixels. Agora uses the value of `videoDimension` to calculate the charges. + * For details, see descriptions in ScreenCaptureParameters. + * + * * @return * - 0: Success. * - < 0: Failure: - * - #ERR_INVALID_STATE: the screen sharing state is invalid, probably because another screen or window is being - * shared. Call \ref IRtcEngine::stopScreenCapture "stopScreenCapture" to stop the current screen sharing. - * - #ERR_INVALID_ARGUMENT: the argument is invalid. + * - #ERR_INVALID_ARGUMENT: The argument is invalid. */ virtual int startScreenCaptureByDisplayId(unsigned int displayId, const Rectangle& regionRect, const ScreenCaptureParameters& captureParams) = 0; #endif @@ -7261,16 +7925,15 @@ class IRtcEngine * - Ensure that you call this method after joining a channel. * - Applies to the Windows platform only. * - * @param screenRect Sets the relative location of the screen to the virtual screen. For information on how to get screenRect, see the advanced guide *Share Screen*. - * @param regionRect (Optional) Sets the relative location of the region to the screen. NULL means sharing the whole screen. See Rectangle. If the specified region overruns the screen, the SDK shares only the region within it; if you set width or height as 0, the SDK shares the whole screen. - * @param captureParams Sets the screen sharing encoding parameters. See ScreenCaptureParameters. + * @param screenRect Sets the relative location of the screen to the virtual screen. For information on how to get screenRect, see the advanced guide *Share Screen*. + * @param regionRect (Optional) Sets the relative location of the region to the screen. NULL means sharing the whole screen. See Rectangle. If the specified region overruns the screen, the SDK shares only the region within it; if you set width or height as 0, the SDK shares the whole screen. + * @param captureParams The screen sharing encoding parameters. The default video dimension is 1920 x 1080, that is, 2,073,600 pixels. + * Agora uses the value of `videoDimension` to calculate the charges. For details, see descriptions in ScreenCaptureParameters. * * @return * - 0: Success. * - < 0: Failure: - * - #ERR_INVALID_STATE: the screen sharing state is invalid, probably because another screen or window is being - * shared. Call \ref IRtcEngine::stopScreenCapture "stopScreenCapture" to stop the current screen sharing. - * - #ERR_INVALID_ARGUMENT : the argument is invalid. + * - #ERR_INVALID_ARGUMENT : The argument is invalid. */ virtual int startScreenCaptureByScreenRect(const Rectangle& screenRect, const Rectangle& regionRect, const ScreenCaptureParameters& captureParams) = 0; #endif @@ -7398,14 +8061,12 @@ class IRtcEngine * * @param windowId The ID of the window to be shared. For information on how to get the windowId, see the advanced guide *Share Screen*. * @param regionRect (Optional) The relative location of the region to the window. NULL/NIL means sharing the whole window. See Rectangle. If the specified region overruns the window, the SDK shares only the region within it; if you set width or height as 0, the SDK shares the whole window. - * @param captureParams Window sharing encoding parameters. See ScreenCaptureParameters. + * @param captureParams The screen sharing encoding parameters. The default video dimension is 1920 x 1080, that is, 2,073,600 pixels. Agora uses the value of `videoDimension` to calculate the charges. For details, see descriptions in ScreenCaptureParameters. * * @return * - 0: Success. * - < 0: Failure: - * - #ERR_INVALID_STATE: the screen sharing state is invalid, probably because another screen or window is being - * shared. Call \ref IRtcEngine::stopScreenCapture "stopScreenCapture" to stop the current screen sharing. - * - #ERR_INVALID_ARGUMENT: the argument is invalid. + * - #ERR_INVALID_ARGUMENT: The argument is invalid. */ virtual int startScreenCaptureByWindowId(view_t windowId, const Rectangle& regionRect, const ScreenCaptureParameters& captureParams) = 0; @@ -7425,7 +8086,9 @@ class IRtcEngine /** Updates the screen sharing parameters. - @param captureParams Sets the screen sharing encoding parameters. See ScreenCaptureParameters. + @param captureParams The screen sharing encoding parameters. The default video dimension is 1920 x 1080, that is, + 2,073,600 pixels. Agora uses the value of `videoDimension` to calculate the charges. For details, + see descriptions in ScreenCaptureParameters. @return - 0: Success. @@ -7580,7 +8243,7 @@ class IRtcEngine @note - Do not call any other methods before receiving the \ref IRtcEngineEventHandler::onLastmileQuality "onLastmileQuality" callback. Otherwise, the callback may be interrupted by other methods, and hence may not be triggered. - A host should not call this method after joining a channel (when in a call). - - If you call this method to test the last-mile quality, the SDK consumes the bandwidth of a video stream, whose bitrate corresponds to the bitrate you set in the \ref agora::rtc::IRtcEngine::setVideoEncoderConfiguration "setVideoEncoderConfiguration" method. After you join the channel, whether you have called the `disableLastmileTest` method or not, the SDK automatically stops consuming the bandwidth. + - If you call this method to test the last mile network quality, the SDK consumes the bandwidth of a video stream, whose bitrate corresponds to the bitrate you set in the \ref agora::rtc::IRtcEngine::setVideoEncoderConfiguration "setVideoEncoderConfiguration" method. After you join the channel, whether you have called the `disableLastmileTest` method or not, the SDK automatically stops consuming the bandwidth. @return - 0: Success. @@ -7598,7 +8261,7 @@ class IRtcEngine /** Starts the last-mile network probe test. - This method starts the last-mile network probe test before joining a channel to get the uplink and downlink last-mile network statistics, including the bandwidth, packet loss, jitter, and round-trip time (RTT). + This method starts the last-mile network probe test before joining a channel to get the uplink and downlink last mile network statistics, including the bandwidth, packet loss, jitter, and round-trip time (RTT). Call this method to check the uplink network quality before users join a channel or before an audience switches to a host. Once this method is enabled, the SDK returns the following callbacks: @@ -7682,8 +8345,8 @@ class IRtcEngine * All users in the same channel must use the same encryption mode and encryption key. Once all users leave the channel, the encryption key of this channel is automatically cleared. * * @note - * - If you enable the built-in encryption, you cannot use the RTMP streaming function. - * - Agora supports four encryption modes. If you choose an encryption mode (excepting `SM4_128_ECB` mode), you need to add an external encryption library when integrating the Android and iOS SDK. See the advanced guide *Channel Encryption*. + * - If you enable the built-in encryption, you cannot use the RTMP or RTMPS streaming function. + * - You need to add an external encryption library when integrating the Android and iOS SDK. See the advanced guide *Channel Encryption*. * * @param enabled Whether to enable the built-in encryption: * - true: Enable the built-in encryption. @@ -7719,10 +8382,12 @@ class IRtcEngine /** Creates a data stream. + @deprecated This method is deprecated from v3.3.0. Use the \ref IRtcEngine::createDataStream(int* streamId, DataStreamConfig& config) "createDataStream" [2/2] method instead. + Each user can create up to five data streams during the lifecycle of the IRtcEngine. @note - - Set both the @p reliable and @p ordered parameters to true or false. Do not set one as true and the other as false. + - Do not set `reliable` as `true` while setting `ordered` as `false`. - Ensure that you call this method after joining a channel. @param[out] streamId Pointer to the ID of the created data stream. @@ -7738,6 +8403,23 @@ class IRtcEngine - < 0: Failure. */ virtual int createDataStream(int* streamId, bool reliable, bool ordered) = 0; + /** 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. + * + * @param[out] streamId The ID of the created data stream. + * @param config The configurations for the data stream: DataStreamConfig. + * + * @return + * - 0: Creates the data stream successfully. + * - < 0: Fails to create the data stream. + */ + virtual int createDataStream(int* streamId, DataStreamConfig& config) = 0; /** Sends data stream messages to all users in a channel. @@ -7762,7 +8444,7 @@ class IRtcEngine */ virtual int sendStreamMessage(int streamId, const char* data, size_t length) = 0; - /** Publishes the local stream to a specified CDN live RTMP address. (CDN live only.) + /** Publishes the local stream to a specified CDN live address. (CDN live only.) The SDK returns the result of this method call in the \ref IRtcEngineEventHandler::onStreamPublished "onStreamPublished" callback. @@ -7770,10 +8452,10 @@ class IRtcEngine @note - Ensure that the user joins the channel before calling this method. - Ensure that you enable the RTMP Converter service before using this function. See *Prerequisites* in the advanced guide *Push Streams to CDN*. - - This method adds only one stream RTMP URL address each time it is called. + - This method adds only one stream CDN streaming URL each time it is called. - This method applies to `LIVE_BROADCASTING` only. - @param url The CDN streaming URL in the RTMP format. The maximum length of this parameter is 1024 bytes. The RTMP URL address must not contain special characters, such as Chinese language characters. + @param url The 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. @param transcodingEnabled Sets whether transcoding is enabled/disabled: - true: Enable transcoding. To [transcode](https://docs.agora.io/en/Agora%20Platform/terms?platform=All%20Platforms#transcoding) 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 \ref IRtcEngine::setLiveTranscoding "setLiveTranscoding" method before this method. - false: Disable transcoding. @@ -7781,22 +8463,23 @@ class IRtcEngine @return - 0: Success. - < 0: Failure. - - #ERR_INVALID_ARGUMENT (2): The RTMP URL address is NULL or has a string length of 0. - - #ERR_NOT_INITIALIZED (7): You have not initialized the RTC engine when publishing the stream. + - #ERR_INVALID_ARGUMENT (-2): The CDN streaming URL is NULL or has a string length of 0. + - #ERR_NOT_INITIALIZED (-7): You have not initialized the RTC engine when publishing the stream. */ virtual int addPublishStreamUrl(const char *url, bool transcodingEnabled) = 0; - /** Removes an RTMP stream from the CDN. (CDN live only.) + /** Removes an RTMP or RTMPS stream from the CDN. (CDN live only.) - This method removes the RTMP URL address (added by the \ref IRtcEngine::addPublishStreamUrl "addPublishStreamUrl" method) from a CDN live stream. The SDK returns the result of this method call in the \ref IRtcEngineEventHandler::onStreamUnpublished "onStreamUnpublished" callback. + This method removes the CDN streaming URL (added by the \ref IRtcEngine::addPublishStreamUrl "addPublishStreamUrl" method) from a CDN live stream. The SDK returns the result of this method call in the \ref IRtcEngineEventHandler::onStreamUnpublished "onStreamUnpublished" callback. + + The \ref agora::rtc::IRtcEngine::removePublishStreamUrl "removePublishStreamUrl" method call triggers the \ref agora::rtc::IRtcEngineEventHandler::onRtmpStreamingStateChanged "onRtmpStreamingStateChanged" callback on the local client to report the state of removing an RTMP or RTMPS stream from the CDN. - The \ref agora::rtc::IRtcEngine::removePublishStreamUrl "removePublishStreamUrl" method call triggers the \ref agora::rtc::IRtcEngineEventHandler::onRtmpStreamingStateChanged "onRtmpStreamingStateChanged" callback on the local client to report the state of removing an RTMP stream from the CDN. @note - - This method removes only one RTMP URL address each time it is called. - - The RTMP URL address must not contain special characters, such as Chinese language characters. + - 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. - This method applies to `LIVE_BROADCASTING` only. - @param url The RTMP URL address to be removed. The maximum length of this parameter is 1024 bytes. + @param url The CDN streaming URL to be removed. The maximum length of this parameter is 1024 bytes. @return - 0: Success. @@ -7813,6 +8496,7 @@ class IRtcEngine - Ensure that you enable the RTMP Converter service before using this function. See *Prerequisites* in the advanced guide *Push Streams to CDN*. - If you call the `setLiveTranscoding` method to update 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. @param transcoding Sets the CDN live audio/video transcoding settings. See LiveTranscoding. @@ -7824,9 +8508,9 @@ class IRtcEngine /** **DEPRECATED** Adds a watermark image to the local video or CDN live stream. - This method is deprecated from v2.9.1. Use \ref agora::rtc::IRtcEngine::addVideoWatermark(const char* watermarkUrl, const WatermarkOptions& options) "addVideoWatermark"2 instead. + This method is deprecated from v2.9.1. Use \ref agora::rtc::IRtcEngine::addVideoWatermark(const char* watermarkUrl, const WatermarkOptions& options) "addVideoWatermark" [2/2] instead. - This method adds a PNG watermark image to the local video stream for the recording device, channel audience, and CDN live audience to view and capture. + This method adds a PNG watermark image to the local video stream for the capturing device, channel audience, and CDN live audience to view and capture. To add the PNG file to the CDN live publishing stream, see the \ref IRtcEngine::setLiveTranscoding "setLiveTranscoding" method. @@ -7848,7 +8532,7 @@ class IRtcEngine /** Adds a watermark image to the local video. This method adds a PNG watermark image to the local video in the live streaming. Once the watermark image is added, all the audience in the channel (CDN audience included), - and the recording device can see and capture it. Agora supports adding only one watermark image onto the local video, and the newly watermark image replaces the previous one. + and the capturing device can see and capture it. Agora supports adding only one watermark image onto the local video, and the newly watermark image replaces the previous one. The watermark position depends on the settings in the \ref IRtcEngine::setVideoEncoderConfiguration "setVideoEncoderConfiguration" method: - If the orientation mode of the encoding video is #ORIENTATION_MODE_FIXED_LANDSCAPE, or the landscape mode in #ORIENTATION_MODE_ADAPTIVE, the watermark uses the landscape orientation. @@ -7881,9 +8565,9 @@ class IRtcEngine virtual int clearVideoWatermarks() = 0; /** Enables/Disables image enhancement and sets the options. - * + * * @note Call this method after calling the \ref IRtcEngine::enableVideo "enableVideo" method. - * + * * @param enabled Sets whether or not to enable image enhancement: * - true: enables image enhancement. * - false: disables image enhancement. @@ -7917,10 +8601,10 @@ class IRtcEngine @return - 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 \ref agora::rtc::IRtcEngine::setChannelProfile "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 IRtcEngine object is initialized before calling this method. + - #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 \ref agora::rtc::IRtcEngine::setChannelProfile "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 IRtcEngine object is initialized before calling this method. */ virtual int addInjectStreamUrl(const char* url, const InjectStreamConfig& config) = 0; /** Starts to relay media streams across channels. @@ -8105,7 +8789,7 @@ class IRtcEngine /** 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 \ref agora::rtc::IMetadataObserver::getMaxMetadataSize "getMaxMetadataSize" callback. - This method enables you to add synchronized metadata in the video stream for more diversified live interactive streaming, such as sending shopping links, digital coupons, and online quizzes. + 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. @@ -8749,12 +9433,9 @@ class RtcEngineParameters if(preset == CHAT_BEAUTIFIER_VITALITY) { return m_parameter->setInt("che.audio.morph.beauty_voice", 3); } - /*if(preset == SINGING_BEAUTIFICATION_MAN) { - return m_parameter->setInt("che.audio.morph.beauty_sing", 1); + if(preset == SINGING_BEAUTIFIER) { + return setObject( "che.audio.morph.beauty_sing", "{\"key\":%d,\"value\":%d}", 1, 1); } - if(preset == SINGING_BEAUTIFICATION_WOMAN) { - return m_parameter->setInt("che.audio.morph.beauty_sing", 2); - }*/ if(preset == TIMBRE_TRANSFORMATION_VIGOROUS) { return m_parameter->setInt("che.audio.morph.voice_changer", 7); } @@ -8782,6 +9463,27 @@ class RtcEngineParameters return -ERR_INVALID_ARGUMENT; } + int setVoiceConversionPreset(VOICE_CONVERSION_PRESET preset) { + if(!m_parameter) + return -ERR_NOT_INITIALIZED; + if (preset == VOICE_CONVERSION_OFF) { + return m_parameter->setInt("che.audio.morph.voice_changer", 0); + } + if (preset == VOICE_CHANGER_NEUTRAL) { + return m_parameter->setInt("che.audio.morph.vocal_changer", 1); + } + if (preset == VOICE_CHANGER_SWEET) { + return m_parameter->setInt("che.audio.morph.vocal_changer", 2); + } + if (preset == VOICE_CHANGER_SOLID) { + return m_parameter->setInt("che.audio.morph.vocal_changer", 3); + } + if (preset == VOICE_CHANGER_BASS) { + return m_parameter->setInt("che.audio.morph.vocal_changer", 4); + } + return -ERR_INVALID_ARGUMENT; + } + int setAudioEffectParameters(AUDIO_EFFECT_PRESET preset, int param1, int param2){ if(!m_parameter) return -ERR_NOT_INITIALIZED; @@ -8794,6 +9496,15 @@ class RtcEngineParameters return -ERR_INVALID_ARGUMENT; } + int setVoiceBeautifierParameters(VOICE_BEAUTIFIER_PRESET preset, int param1, int param2){ + if(!m_parameter) + return -ERR_NOT_INITIALIZED; + if(preset == SINGING_BEAUTIFIER){ + return setObject( "che.audio.morph.beauty_sing", "{\"key\":%d,\"value\":%d}", param1, param2); + } + return -ERR_INVALID_ARGUMENT; + } + /** **DEPRECATED** Use \ref IRtcEngine::disableAudio "disableAudio" instead. Disables the audio function in the channel. @return @@ -8912,6 +9623,10 @@ class RtcEngineParameters int setCameraCapturerConfiguration(const CameraCapturerConfiguration& config) { if (!m_parameter) return -ERR_NOT_INITIALIZED; + if (config.preference == CAPTURER_OUTPUT_PREFERENCE_MANUAL) { + m_parameter->setInt("che.video.capture_width", config.captureWidth); + m_parameter->setInt("che.video.capture_height", config.captureHeight); + } return m_parameter->setInt("che.video.camera_capture_mode", (int)config.preference); }