Options
All
  • Public
  • Public/Protected
  • All
Menu

Class AgoraRtcEngine

The AgoraRtcEngine class. The AgoraRtcEngine interface.

Hierarchy

  • EventEmitter
    • AgoraRtcEngine

Index

Constructors

Properties

Methods

Constructors

constructor

Properties

customRenderer

customRenderer: any

pauseRender

pauseRender: boolean

renderMode

renderMode: 1 | 2 | 3 | 4

rtcEngine

rtcEngine: NodeRtcEngine

streams

streams: Map<string, Map<string, IRenderer[]>>

Methods

_checkWebGL2

  • _checkWebGL2(): boolean
  • Returns boolean

_getChannelRenderers

  • _getChannelRenderers(channelId: string): Map<string, IRenderer[]>
  • Parameters

    • channelId: string

    Returns Map<string, IRenderer[]>

addInjectStreamUrl

  • Adds a voice or video stream HTTP/HTTPS URL address to a live streaming.

    This method applies to the Native SDK v2.4.1 and later.

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

    The addInjectStreamUrl method call triggers the following callbacks:

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

    Agora will soon stop the service for injecting online media streams on the client. If you have not implemented this service, Agora recommends that you do not use it.

    note
    • Only the host in the Live-braodcast profile can call this method.
    • Ensure that you enable the Media Push service before using this function. See Prerequisites in the Media Push guide.
    • Ensure that the user joins a channel before calling this method.
    • This method adds only one stream URL address each time it is called.

    Parameters

    • url: string

      The HTTP/HTTPS URL address to be added to the ongoing live streaming. Valid protocols are RTMP, HLS, and FLV.

      • Supported FLV audio codec type: AAC.
      • Supported FLV video codec type: H264 (AVC).
    • config: InjectStreamConfig

      The InjectStreamConfig object which contains the configuration information for the added voice or video stream.

    Returns number

    • 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 streaming. Call the setChannelProfile method and set the channel profile to Live streaming before calling this method.
      • ERR_NOT_INITIALIZED (7): The SDK is not initialized. Ensure that the AgoraRtcEngine object is initialized before using this method.

addPublishStreamUrl

  • addPublishStreamUrl(url: string, transcodingEnabled: boolean): number
  • Publishes the local stream to a specified CDN live RTMP address.

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

    note
    • Only the host in the 1 (live streaming) profile can call this method.
    • Call this method after the host joins the channel.
    • Ensure that you enable the Media Push service before using this function. See Prerequisites in the Media Push guide.
    • This method adds only one stream URL address each time it is called.

    Parameters

    • url: string

      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.

    • transcodingEnabled: boolean

      Sets whether transcoding is enabled/disabled:

      • true: Enable transcoding. To transcode the audio or video streams when publishing them to CDN live, often used for combining the audio and video streams of multiple hosts in CDN live. If set the parameter as true, you should call the setLiveTranscoding method before this method.
      • false: Disable transcoding.

    Returns number

    • 0: Success.
    • < 0: Failure.

addVideoRenderToHighFPS

  • addVideoRenderToHighFPS(uid: number): void
  • Adds a video stream to the high frame rate stream. Streams added to the high frame rate stream will be controlled by the setVideoRenderHighFPS method.

    Parameters

    • uid: number

      The User ID.

    Returns void

addVideoWatermark

  • since

    v3.0.0

    Adds a watermark image to the local video.

    This method adds a PNG watermark image to the local video in a live broadcast. 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.

    The watermark position depends on the settings in the setVideoEncoderConfiguration method:

    • If the orientation mode of the encoding video is LANDSCAPE, the landscape mode in ADAPTIVE, the watermark uses the landscape orientation.
    • If the orientation mode of the encoding video is PORTRAIT, or the portrait mode in ADAPTIVE, the watermark uses the portrait orientation.
    • hen setting the watermark position, the region must be less than the dimensions set in the setVideoEncoderConfiguration method. Otherwise, the watermark image will be cropped.
    note
    • Ensure that you have called enableVideo before this method.
    • If you only want to add a watermark image to the local video for the audience in the Media Push channel to see and capture, you can call this method or setLiveTranscoding.
    • This method supports adding a watermark image in the PNG file format only. Supported pixel formats of the PNG image are RGBA, RGB, Palette, Gray, and Alpha_gray.
    • If the dimensions of the PNG image differ from your settings in this method, the image will be cropped or zoomed to conform to your settings.
    • If you have enabled the local video preview by calling startPreview, you can use the visibleInPreview member in the WatermarkOptions class to set whether or not the watermark is visible in preview.
    • If you have enabled the mirror mode for the local video, the watermark on the local video is also mirrored. To avoid mirroring the watermark, Agora recommends that you do not use the mirror and watermark functions for the local video at the same time. You can implement the watermark function in your application layer.

    Parameters

    • path: string

      The local file path of the watermark image to be added. This method supports adding a watermark image from the local absolute or relative file path.

    • options: WatermarkOptions

      The watermark's options. See WatermarkOptions

    Returns number

    • 0: Success
    • < 0: Failure

adjustAudioMixingPlayoutVolume

  • adjustAudioMixingPlayoutVolume(volume: number): number
  • Adjusts the audio mixing volume for local playback.

    Parameters

    • volume: number

      Audio mixing volume for local playback. The value ranges between 0 and 100 (default). 100 is the original volume.

    Returns number

    • 0: Success.
    • < 0: Failure.

adjustAudioMixingPublishVolume

  • adjustAudioMixingPublishVolume(volume: number): number
  • Adjusts the audio mixing volume for publishing (sending to other users).

    Parameters

    • volume: number

      Audio mixing volume for publishing. The value ranges between 0 and 100 (default). 100 is the original volume.

    Returns number

    • 0: Success.
    • < 0: Failure.

adjustAudioMixingVolume

  • adjustAudioMixingVolume(volume: number): number
  • Adjusts the volume of audio mixing.

    Call this API when you are in a channel.

    note

    Calling this method does not affect the volume of audio effect file playback invoked by the playEffect method.

    Parameters

    • volume: number

      Audio mixing volume. The value ranges between 0 and 100 (default). 100 is the original volume.

    Returns number

    • 0: Success.
    • < 0: Failure.

adjustLoopbackRecordingSignalVolume

  • adjustLoopbackRecordingSignalVolume(volume: number): number
  • Adjusts the volume of the signal captured by the sound card.

    since

    v3.4.2

    After calling enableLoopbackRecording to enable loopback audio capturing, you can call this method to adjust the volume of the signal captured by the sound card.

    Parameters

    • volume: number

      The volume of the signal captured by the sound card. The range is 0 to 100. The default value is 100, which represents the unadjusted volume.

    Returns number

    • 0: Success.
    • < 0: Failure.

adjustLoopbackSignalVolume

  • adjustLoopbackSignalVolume(volume: number): number
  • Parameters

    • volume: number

    Returns number

adjustPlaybackSignalVolume

  • adjustPlaybackSignalVolume(volume: number): number
  • 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.
    • You can call this method either before or after joining a channel.
    • To mute the local audio playback, call both the adjustPlaybackSignalVolume and adjustAudioMixingVolume methods and set the volume as 0.

    Parameters

    • volume: number

      The playback volume. The range is 0 to 400. The default value is 100, which represents the original volume.

      • 0: Mute.
      • 100: Original volume.
      • 400: Four times the original volume with signal-clipping protection.

    Returns number

    • 0: Success.
    • < 0: Failure.

adjustRecordingSignalVolume

  • adjustRecordingSignalVolume(volume: number): number
  • Adjusts the volume of the signal captured by the microphone.

    note

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

    Parameters

    • volume: number

      The volume of the signal captured by the microphone. The range is 0 to 400. The default value is 100, which represents the original volume.

      • 0: Mute.
      • 100: Original volume.
      • 400: Four times the original volume with signal-clipping protection.

    Returns number

    • 0: Success.
    • < 0: Failure.

adjustUserPlaybackSignalVolume

  • adjustUserPlaybackSignalVolume(uid: number, volume: number): number
  • Adjusts the playback 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.

    note
    • Call this method after joining a channel.
    • The playback volume here refers to the mixed volume of a specified remote user.
    • This method can only adjust the playback volume of one specified remote user at a time. To adjust the playback volume of different remote users, call the method as many times, once for each remote user.

    Parameters

    • uid: number

      The ID of the remote user.

    • volume: number

      The playback volume of the specified remote user. The value ranges from 0 to 100:

      • 0: Mute.
      • 100: Original volume.

    Returns number

    • 0: Success.
    • < 0: Failure.

clearVideoWatermarks

  • clearVideoWatermarks(): number
  • Removes the watermark image from the video stream added by the addVideoWatermark method.

    Returns number

    • 0: Success
    • < 0: Failure

complain

  • complain(callId: string, desc: string): number
  • Allows a user to complain about the call quality after a call ends.

    Parameters

    • callId: string

      Call ID retrieved from the getCallId method.

    • desc: string

      (Optional) The description of the complaint, with a string length of less than 800 bytes.

    Returns number

    • 0: Success.
    • < 0: Failure.

createChannel

  • Creates and gets an AgoraRtcChannel object.

    To join more than one channel, call this method multiple times to create as many AgoraRtcChannel objects as needed, and call the joinChannel method of each created AgoraRtcChannel object.

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

    note
    • This parameter does not have a default value. You must set it.
    • Do not set it as the empty string "". Otherwise, the SDK returns ERR_REFUSED (5).

    Parameters

    • channelName: string

      The unique channel name for an Agora RTC session. It must be in the string format and not exceed 64 bytes in length. 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: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".

    Returns AgoraRtcChannel | null

    • If the method call succeeds, returns the AgoraRtcChannel object.
    • If the method call fails, returns empty or ERR_REFUSED (5).

createDataStream

  • createDataStream(reliable: boolean, ordered: boolean): number
  • Creates a data stream.

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

    deprecated

    This method is deprecated from v3.3.1. Use the createDataStreamWithConfig method instead.

    Note: Set both the reliable and ordered parameters to true or false. Do not set one as true and the other as false.

    Parameters

    • reliable: boolean

      Sets whether or not the recipients are guaranteed to receive the data stream from the sender within five seconds:

      • true: The recipients will receive data from the sender within 5 seconds. If the recipient does not receive the sent data within 5 seconds, the data channel will report an error to the application.
      • false: There is no guarantee that the recipients receive the data stream within five seconds and no error message is reported for any delay or missing data stream.
    • ordered: boolean

      Sets whether or not the recipients receive the data stream in the sent order:

      • true: The recipients receive the data stream in the sent order.
      • false: The recipients do not receive the data stream in the sent order.

    Returns number

    • Returns the ID of the data stream, if this method call succeeds.
    • < 0: Failure and returns an error code.

createDataStreamWithConfig

  • Creates a data stream.

    since

    v3.3.1

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

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

    Parameters

    Returns number

    • Returns the ID of the created data stream, if this method call succeeds.
    • < 0: Fails to create the data stream.

destroyRender

  • destroyRender(key: "local" | "videosource" | number, channelId: string | undefined, onFailure?: undefined | function): void
  • Destroys the renderer.

    Parameters

    • key: "local" | "videosource" | number

      Key for the map that store the renderers, e.g, uid or videosource or local.

    • channelId: string | undefined
    • Optional onFailure: undefined | function

      The error callback for the {@link destroyRenderer} method.

    Returns void

destroyRenderView

  • destroyRenderView(key: "local" | "videosource" | number, channelId: string | undefined, view: Element, onFailure?: undefined | function): void
  • Parameters

    • key: "local" | "videosource" | number
    • channelId: string | undefined
    • view: Element
    • Optional onFailure: undefined | function

    Returns void

disableAudio

  • disableAudio(): number
  • Disables the audio module.

    Note:

    • This method affects the internal engine and can be called after calling the 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:

    Returns number

    • 0: Success.
    • < 0: Failure.

disableLastmileTest

  • disableLastmileTest(): number
  • This method disables the network connection quality test.

    Returns number

    • 0: Success.
    • < 0: Failure.

disableVideo

  • disableVideo(): number
  • Disables the video module.

    You can call this method before joining a channel or during a call. If you call this method before joining a channel, the service starts in audio mode. If you call this method during a video call, the video mode switches to the audio mode.

    To enable the video mode, call the enableVideo method.

    Note:

    • This method affects the internal engine and can be called after calling the 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 video engine modules separately:

    Returns number

    • 0: Success.
    • < 0: Failure.

enableAudio

  • enableAudio(): number
  • Enables the audio module.

    The audio module is enabled by default.

    Note:

    • This method affects the internal engine and can be called after calling the 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:

    Returns number

    • 0: Success.
    • < 0: Failure.

enableAudioVolumeIndication

  • enableAudioVolumeIndication(interval: number, smooth: number, report_vad?: boolean): number
  • Enables the groupAudioVolumeIndication callback at a set time interval to report on which users are speaking and the speakers' volume.

    Once this method is enabled, the SDK returns the volume indication in the groupAudioVolumeIndication callback at the set time interval, regardless of whether any user is speaking in the channel.

    Parameters

    • interval: number

      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 interval ≥ 200 ms.
    • smooth: number

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

    • Default value report_vad: boolean = false
      • true: Enable the voice activity detection of the local user. Once it is enabled, vad in the groupAudioVolumeIndication callback reports the voice activity status of the local user.
      • false: (Default) Disables the voice activity detection of the local user. Once it is disabled, vad in the groupAudioVolumeIndication callback does not report the voice activity status of the local user, except for scenarios where the engine automatically detects the voice activity of the local user.

    Returns number

    • 0: Success.
    • < 0: Failure.

enableDeepLearningDenoise

  • enableDeepLearningDenoise(enabled: boolean): number
  • Enables or disables deep-learning noise reduction.

    since

    v3.3.1

    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 Release folder to your project:
      • macOS: AgoraAIDenoiseExtension.framework
      • Windows: libagora_ai_denoise_extension.dll
    2. Call enableDeepLearningDenoise(true).

    Deep-learning noise reduction requires high-performance devices, such as MacBook Pro 2015.

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

    Parameters

    • enabled: boolean

    Returns number

    • 0: Success.
    • < 0: Failure.
      • `-157: The dynamical library for enabling deep-learning noise reduction is not integrated.

enableDualStreamMode

  • enableDualStreamMode(enable: boolean): number
  • Enables/Disables the dual video stream mode.

    If dual-stream mode is enabled, the receiver can choose to receive the high stream (high-resolution high-bitrate video stream) or low stream (low-resolution low-bitrate video stream) video.

    Parameters

    • enable: boolean

      Sets the stream mode:

      • true: Dual-stream mode.
      • false: (Default) Single-stream mode.

    Returns number

    • 0: Success.
    • < 0: Failure.

enableEncryption

  • Enables/Disables the built-in encryption.

    since

    v3.2.0

    In scenarios requiring high security, Agora recommends calling this method to enable the built-in encryption before joining a channel.

    All users in the same channel must use the same encryption mode and encryption key. 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 or RTMPS streaming function.

    Parameters

    • enabled: boolean

      Whether to enable the built-in encryption:

      • true: Enable the built-in encryption.
      • false: Disable the built-in encryption.
    • config: EncryptionConfig

      Configurations of built-in encryption schemas. See EncryptionConfig.

    Returns number

    • 0: Success.
    • < 0: Failure.

enableLastmileTest

  • enableLastmileTest(): number
  • Enables the network connection quality test.

    This method tests the quality of the users' network connections and is disabled by default.

    Before users join a channel or before an audience switches to a host, call this method to check the uplink network quality.

    This method consumes additional network traffic, which may affect the communication quality.

    Call the disableLastmileTest method to disable this test after receiving the lastMileQuality callback, and before the user joins a channel or switches the user role.

    note
    • Do not call any other methods before receiving the lastMileQuality 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 setVideoEncoderConfiguration method. After you join the channel, whether you have called the disableLastmileTest method or not, the SDK automatically stops consuming the bandwidth.

    Returns number

    • 0: Success.
    • < 0: Failure.

enableLocalAudio

  • enableLocalAudio(enable: boolean): number
  • Enables/Disables the local audio capture.

    The audio function is enabled by default. This method disables/re-enables the local audio function, that is, to stop or restart local audio capture and processing.

    This method does not affect receiving or playing the remote audio streams, and enableLocalAudio(false) is applicable to scenarios where the user wants to receive remote audio streams without sending any audio stream to other users in the channel.

    The SDK triggers the microphoneEnabled callback once the local audio function is disabled or re-enabled.

    note

    This method is different from the muteLocalAudioStream method:

    • enableLocalAudio: 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.
    • muteLocalAudioStream: Stops/Continues sending the local audio streams and the local user will not hear a pause in the remote audio playback.

    Parameters

    • enable: boolean

      Sets whether to disable/re-enable the local audio function:

      • true: (Default) Re-enable the local audio function, that is, to start local audio capture and processing.
      • false: Disable the local audio function, that is, to stop local audio capture and processing.

    Returns number

    • 0: Success.
    • < 0: Failure.

enableLocalVideo

  • enableLocalVideo(enable: boolean): number
  • Disables/Re-enables the local video capture.

    This method disables or re-enables the local video capturer, and does not affect receiving the remote video stream.

    After you call the enableVideo method, the local video capturer is enabled by default. You can call enableLocalVideo(false) to disable the local video capturer. If you want to re-enable it, call enableLocalVideo(true).

    After the local video capturer is successfully disabled or re-enabled, the SDK triggers the userEnableVideo callback on the remote client.

    Parameters

    • enable: boolean

      Sets whether to disable/re-enable the local video, including the capturer, renderer, and sender:

      • true: (Default) Re-enable the local video.
      • false: Disable the local video. Once the local video is disabled, the remote users can no longer receive the video stream of this user, while this user can still receive the video streams of other remote users. When you set enabled as false, this method does not require a local camera.

    Returns number

    • 0: Success.
    • < 0: Failure.

enableLocalVoicePitchCallback

  • enableLocalVoicePitchCallback(interval: number): number
  • Enables reporting the voice pitch of the local user.

    since

    v3.7.0

    This method enables the SDK to regularly report the voice pitch of the local user. After the local audio capture is enabled, and you call this method, the SDK triggers the localVoicePitchInHz callback at the time interval set in this method.

    note

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

    Parameters

    • interval: number

      Sets the time interval at which the SDK triggers the localVoicePitchInHz callback:

      • ≤ 0: Disables the localVoicePitchInHz callback.
      • > 0: The time interval (ms) at which the SDK triggers the localVoicePitchInHz callback. The value must be greater than or equal to 10. If the value is less than 10, the SDK automatically changes it to 10.

    Returns number

    • 0: Success.
    • < 0: Failure.

enableLoopbackRecording

  • enableLoopbackRecording(enable?: boolean, deviceName?: string | null): number
  • Enables loopback audio capturing.

    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.

    Parameters

    • Default value enable: boolean = false

      Sets whether to enable/disable loopback capturing.

      • true: Enable loopback capturing.
      • false: (Default) Disable loopback capturing.
    • Default value deviceName: string | null = null

      The device name of the sound card. The default value is NULL (the default sound card). Note: 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.

    Returns number

    • 0: Success
    • < 0: Failure

enableSoundPositionIndication

  • enableSoundPositionIndication(enable: boolean): number
  • 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 setRemoteVoicePosition.

    Parameters

    • enable: boolean

      Sets whether or not to enable stereo panning for remote users:

      • true: enables stereo panning.
      • false: disables stereo panning.

    Returns number

    • 0: Success.
    • < 0: Failure.

enableSpatialAudio

  • enableSpatialAudio(enabled: boolean): number
  • Parameters

    • enabled: boolean

    Returns number

enableVideo

  • enableVideo(): number
  • Enables the video module.

    You can call this method either before joining a channel or during a call. If you call this method before joining a channel, the service starts in the video mode. If you call this method during an audio call, the audio mode switches to the video mode.

    To disable the video, call the disableVideo method.

    Note:

    • This method affects the internal engine and can be called after calling the 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 video engine modules separately:

    Returns number

    • 0: Success.
    • < 0: Failure.

enableVirtualBackground

  • Enables/Disables the virtual background. (beta function)

    since

    3.4.5

    After enabling the virtual background function, you can replace the original background image of the local user with a custom background image. After the replacement, all users in the channel can see the custom background image. You can find out from the virtualBackgroundSourceEnabled callback whether the virtual background is successfully enabled or the cause of any errors.

    note
    • Before calling this method, ensure that you have integrated the following dynamic library into your project:
      • macOS: AgoraVideoSegmentationExtension.framework
      • Windows: libagora_segmentation_extension.dll
    • Call this method after enableVideo.
    • This functions requires a high-performance device. Agora recommends that you use this function on devices with an i5 CPU and better.
    • Agora recommends that you use this function in scenarios that meet the following conditions:
    • A high-definition camera device is used, and the environment is uniformly lit.
    • The captured video image is uncluttered, the user's portrait is half-length and largely unobstructed, and the background is a single color that differs from the color of the user's clothing.

    Parameters

    • enabled: Boolean

      Sets whether to enable the virtual background:

      • true: Enable.
      • false: Disable.
    • backgroundSource: VirtualBackgroundSource

      The custom background image. See VirtualBackgroundSource.

      Note: To adapt the resolution of the custom background image to the resolution of the SDK capturing video, the SDK scales and crops the custom background image while ensuring that the content of the custom background image is not distorted.

    Returns number

    • 0: Success.
    • < 0: Failure.

enableWebSdkInteroperability

  • enableWebSdkInteroperability(enable: boolean): number
  • deprecated

    This method is deprecated. As of v3.0.0, the Electron SDK automatically enables interoperability with the Web SDK, so you no longer need to call this method.

    Enables interoperability with the Agora Web SDK (live streaming only).

    Use this method when the channel profile is 1 (live streaming). Interoperability with the Agora Web SDK is enabled by default when the channel profile is Communication.

    If the channel has Web SDK users, ensure that you call this method, or the video of the Native user will be a black screen for the Web user.

    Parameters

    • enable: boolean

      Sets whether to enable/disable interoperability with the Agora Web SDK:

      • true: Enable.
      • false: (Default) Disable.

    Returns number

    • 0: Success.
    • < 0: Failure.

followSystemPlaybackDevice

  • followSystemPlaybackDevice(enable: boolean): number
  • Sets the audio playback device used by the SDK to follow the system default audio playback device.

    since

    v3.6.1.4

    Parameters

    • enable: boolean

      Whether to follow the system default audio playback device:

      • true: Follow. The SDK immediately switches the audio playback device when the system default audio playback device changes.
      • false: Do not follow. The SDK switches the audio playback device to the system default audio playback device only when the currently used audio playback device is disconnected.

    Returns number

    • 0: Success.
    • < 0: Failure.

followSystemRecordingDevice

  • followSystemRecordingDevice(enable: boolean): number
  • Sets the audio recording device used by the SDK to follow the system default audio recording device.

    since

    v3.6.1.4

    Parameters

    • enable: boolean

      Whether to follow the system default audio recording device:

      • true: Follow. The SDK immediately switches the audio recording device when the system default audio recording device changes.
      • false: Do not follow. The SDK switches the audio recording device to the system default audio recording device only when the currently used audio recording device is disconnected.

    Returns number

    • 0: Success.
    • < 0: Failure.

getAudioFileInfo

  • getAudioFileInfo(filePath: string): number
  • Gets the information of a specified audio file.

    since

    v3.6.1.4

    After calling this method successfully, the SDK triggers the requestAudioFileInfo callback to report the information of an audio file, such as audio duration. You can call this method multiple times to get the information of multiple audio files.

    note

    Parameters

    • filePath: string

      The file path:

      • Windows: The absolute path or URL address (including the filename extensions) of the audio file. For example: C:\music\audio.mp4.
      • Android: The file path, including the filename extensions. To access an online file, Agora supports using a URL address; to access a local file, Agora supports using a URI address, an absolute path, or a path that starts with /assets/. You might encounter permission issues if you use an absolute path to access a local file, so Agora recommends using a URI address instead. For example: content://com.android.providers.media.documents/document/audio%3A14441.
      • iOS or macOS: The absolute path or URL address (including the filename extensions) of the audio file. For example: /var/mobile/Containers/Data/audio.mp4.

    Returns number

    • 0: Success.
    • < 0: Failure.

getAudioMixingCurrentPosition

  • getAudioMixingCurrentPosition(): number
  • Gets the playback position (ms) of the music file.

    Call this API when you are in a channel.

    Returns number

    • ≥ 0: The current playback position of the audio mixing, if this method call succeeds.
    • < 0: Failure.

getAudioMixingDuration

  • getAudioMixingDuration(): number
  • Gets the duration (ms) of the music file.

    deprecated

    Deprecated from v3.4.2. Use {@link getAudioMixingFileDuration} instead.

    note
    • Call this method when you are in a channel.
    • Call this method after calling startAudioMixing and receiving the audioMixingStateChanged(710) callback.

    Returns number

    • ≥ 0: The audio mixing duration, if this method call succeeds.
    • < 0: Failure.

getAudioMixingPlayoutVolume

  • getAudioMixingPlayoutVolume(): number
  • Adjusts the audio mixing volume for publishing (for remote users).

    Call this API when you are in a channel.

    Returns number

    • ≥ 0: The audio mixing volume for local playout, if this method call succeeds. The value range is [0,100].
    • < 0: Failure.

getAudioMixingPublishVolume

  • getAudioMixingPublishVolume(): number
  • Retrieves the audio mixing volume for publishing.

    Call this API when you are in a channel.

    Returns number

    • ≥ 0: The audio mixing volume for publishing, if this method call succeeds. The value range is [0,100].
    • < 0: Failure.

getAudioPlaybackDeviceMute

  • getAudioPlaybackDeviceMute(): boolean
  • check whether selected audio playback device is muted

    Returns boolean

    muted/unmuted

getAudioPlaybackDevices

  • getAudioPlaybackDevices(): Array<Object>
  • Retrieves the audio playback device associated with the device ID.

    Returns Array<Object>

    The array of the audio playback device.

getAudioPlaybackVolume

  • getAudioPlaybackVolume(): number
  • Retrieves the volume of the audio playback device.

    Returns number

    The audio playback device volume.

getAudioRecordingDeviceMute

  • getAudioRecordingDeviceMute(): boolean
  • Retrieves the mute status of the audio playback device.

    Returns boolean

    Whether to mute/unmute the audio playback device:

    • true: Mutes.
    • false: Unmutes.

getAudioRecordingDevices

  • getAudioRecordingDevices(): Array<Object>
  • Retrieves the audio recording device associated with the device ID.

    Returns Array<Object>

    The array of the audio recording device.

getAudioRecordingVolume

  • getAudioRecordingVolume(): number
  • Retrieves the volume of the microphone.

    Returns number

    The microphone volume. The volume value ranges between 0 (lowest volume) and 255 (highest volume).

getAudioTrackCount

  • getAudioTrackCount(): number
  • Gets the audio track index of the current music file.

    since

    v3.6.1.4

    note

    Returns number

    • ≥ 0: The audio track index of the current music file, if this method call succeeds.
    • < 0: Failure.

getCallId

  • getCallId(): string
  • Retrieves the current call ID. When a user joins a channel on a client, a callId is generated to identify the call from the client. Feedback methods, such as rate and complain, must be called after the call ends to submit feedback to the SDK.

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

    Returns string

    The current call ID.

getConfigObject

  • getConfigObject(): Config
  • return sdk config object

    Returns Config

getConnectionState

  • Gets the connection state of the SDK.

    Returns CONNECTION_STATE_TYPE

    Connect states. See {@link ConnectionState}.

getCurrentAudioPlaybackDevice

  • getCurrentAudioPlaybackDevice(): Object
  • Gets the current audio playback device.

    Returns Object

    The current audio playback device.

getCurrentAudioRecordingDevice

  • getCurrentAudioRecordingDevice(): Object
  • Gets the current audio recording device.

    Returns Object

    The audio recording device.

getCurrentVideoDevice

  • getCurrentVideoDevice(): Object
  • Gets the current video device.

    Returns Object

    The video device.

getDefaultAudioPlaybackDevices

  • getDefaultAudioPlaybackDevices(): Object
  • Gets the default audio playback device of the system.

    since

    v3.6.1.4

    Returns Object

getDefaultAudioRecordingDevices

  • getDefaultAudioRecordingDevices(): Object
  • Gets the default audio recording device of the system.

    since

    v3.6.1.4

    Returns Object

getEffectCurrentPosition

  • getEffectCurrentPosition(soundId: number): number
  • Gets the playback position of the audio effect file.

    since

    v3.4.2

    note

    Call this method after playEffect.

    Parameters

    • soundId: number

      Audio effect ID. Ensure that this parameter is set to the same value as in playEffect.

    Returns number

    • ≥ 0: A successful method call. Returns the playback position (ms) of the specified audio effect file.
    • < 0: Failure.
      • -22: Cannot find the audio effect file. Please set a correct soundId.

getEffectDuration

  • getEffectDuration(filePath: string): number
  • Gets the duration of the audio effect file.

    since

    v3.4.2

    note

    Call this method after joining a channel.

    Parameters

    • filePath: string

      The absolute path or URL address (including the filename extensions) of the music file. For example: C:\music\audio.mp4. Supported audio formats include MP3, AAC, M4A, MP4, WAV, and 3GP. For more information, see Supported Media Formats in Media Foundation.

    Returns number

    • ≥ 0: A successful method call. Returns the total duration (ms) of the specified audio effect file.
    • < 0: Failure.
      • -22: Cannot find the audio effect file. Please set a correct filePath.

getEffectsVolume

  • getEffectsVolume(): number
  • Retrieves the volume of the audio effects.

    The value ranges between 0.0 and 100.0.

    Returns number

    • ≥ 0: Volume of the audio effects, if this method call succeeds.
    • < 0: Failure.

getErrorDescription

  • getErrorDescription(errorCode: number): string
  • Retrieves the error description.

    Parameters

    • errorCode: number

      The error code.

    Returns string

    The error description.

getPlaybackDeviceInfo

  • getPlaybackDeviceInfo(deviceId: string, deviceName: string): number
  • Retrieves the audio playback device information associated with the device ID and device name.

    Parameters

    • deviceId: string

      The device ID of the audio playback device.

    • deviceName: string

      The device name of the audio playback device.

    Returns number

    • 0: Success.
    • < 0: Failure.

getRealScreenDisplaysInfo

  • getRealScreenDisplaysInfo(callback: function): void

getRecordingDeviceInfo

  • getRecordingDeviceInfo(deviceId: string, deviceName: string): number
  • Retrieves the audio recording device information associated with the device ID and device name.

    Parameters

    • deviceId: string

      The device ID of the recording audio device.

    • deviceName: string

      The device name of the recording audio device.

    Returns number

    • 0: Success.
    • < 0: Failure.

getScreenCaptureSources

  • getScreenCaptureSources(thumbSize: SIZE, iconSize: SIZE, includeScreen: boolean): Array<Object>
  • Gets a list of shareable screens and windows.

    since

    v3.6.1.4

    You can call this method before sharing a screen or window to get a list of shareable screens and windows, which enables a user to use thumbnails in the list to easily choose a particular screen or window to share. This list also contains important information such as window ID and screen ID, with which you can call startScreenCaptureByWindow or startScreenCaptureByDisplayId to start the sharing.

    note

    This method applies to macOS and Windows only.

    Parameters

    • thumbSize: SIZE

      The target size of the screen or window thumbnail. The width and height are in pixels. See SIZE. The SDK scales the original image to make the length of the longest side of the image the same as that of the target size without distorting the original image. For example, if the original image is 400 × 300 and thumbSize is 100 × 100, the actual size of the thumbnail is 100 × 75. If the target size is larger than the original size, the thumbnail is the original image and the SDK does not scale it.

    • iconSize: SIZE

      The target size of the icon corresponding to the application program. The width and height are in pixels. See SIZE. The SDK scales the original image to make the length of the longest side of the image the same as that of the target size without distorting the original image. For example, if the original image is 400 × 300 and iconSize is 100 × 100, the actual size of the icon is 100 × 75. If the target size is larger than the original size, the icon is the original image and the SDK does not scale it.

    • includeScreen: boolean

      Whether the SDK returns screen information in addition to window information:

      • true: The SDK returns screen and window information.
      • false: The SDK returns window information only.

    Returns Array<Object>

    Array of ScreenCaptureSources objects

getScreenDisplaysInfo

  • getScreenDisplaysInfo(callback: function): void
  • Gets the display ID when using the video source.

    This method gets the ID of the whole display and relevant inforamtion. You can share the whole or part of a display by specifying the display ID.

    Parameters

    Returns void

getScreenWindowsInfo

  • getScreenWindowsInfo(callback: function): void
  • Gets the window ID when using the video source.

    This method gets the ID of the whole window and relevant inforamtion. You can share the whole or part of a window by specifying the window ID.

    Parameters

    Returns void

getUserInfoByUid

  • getUserInfoByUid(uid: number): object
  • Gets the user information by passing in the user ID.

    After a remote user joins the channel, the SDK gets the user ID and user account of the remote user, caches them in a mapping table object (UserInfo), and triggers the userInfoUpdated callback on the local client. After receiving the callback, you can call this method to get the user account of the remote user from the UserInfo object by passing in the user ID.

    Parameters

    • uid: number

      The user ID. Ensure that you set this parameter.

    Returns object

    • errCode Error code.
    • userInfo [in/out] A UserInfo object that identifies the user:
      • Input: A UserInfo object.
      • Output: A UserInfo object that contains the user account and user ID of the user.

getUserInfoByUserAccount

  • getUserInfoByUserAccount(userAccount: string): object
  • Parameters

    • userAccount: string

    Returns object

getVersion

  • getVersion(): string
  • Returns the version and the build information of the current SDK.

    Returns string

    The version of the current SDK.

getVideoDevices

  • getVideoDevices(): Array<Object>
  • Gets the list of the video devices.

    Returns Array<Object>

    The array of the video devices.

initRender

  • initRender(key: "local" | "videosource" | number, view: Element, channelId: string | undefined, options?: RendererOptions): void
  • Initializes the renderer.

    Parameters

    • key: "local" | "videosource" | number

      Key for the map that store the renderers, e.g, uid or videosource or local.

    • view: Element

      The Dom elements to render the video.

    • channelId: string | undefined
    • Optional options: RendererOptions

    Returns void

initialize

  • Initializes the Agora service.

    Parameters

    • appid: string

      The App ID issued to you by Agora. See How to get the App ID. Only users in apps with the same App ID can join the same channel and communicate with each other. Use an App ID to create only one AgoraRtcEngine. To change your App ID, call release to destroy the current AgoraRtcEngine and then call initialize to create AgoraRtcEngine with the new App ID.

    • Default value areaCode: AREA_CODE = 4294967295

      The region for connection. This advanced feature applies to scenarios that have regional restrictions. For the regions that Agora supports, see AREA_CODE. After specifying the region, the SDK connects to the Agora servers within that region.

    • Optional logConfig: LogConfig

      The configuration of the log files that the SDK outputs. See LogConfig. 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.

    Returns number

    • 0: Success.
    • < 0: Failure.

joinChannel

  • joinChannel(token: string, channel: string, info: string, uid: number, options?: ChannelMediaOptions): number
  • Joins a channel with the user ID, and configures whether to automatically subscribe to the audio or video streams.

    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 leaveChannel method to exit the current call before entering another channel.

    A successful joinChannel method call triggers the following callbacks:

    • The local client: joinChannelSuccess.
    • The remote client: userJoined, if the user joining the channel is in the 0 (communication) profile, or is a host in the 1 (live streaming) 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 rejoinChannelSuccess callback on the local client.

    note

    Ensure that the App ID used for generating the token is the same App ID used in the initialize method for creating an AgoraRtcEngine object.

    Parameters

    • token: string

      The token generated at your server. For details, see Generate a token.

    • channel: string

      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: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
    • info: string

      (Optional) Reserved for future use.

    • uid: number

      (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 joinChannelSuccess 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.

    • Optional options: ChannelMediaOptions

      The channel media options. See ChannelMediaOptions.

    Returns number

    • 0: Success.
    • < 0: Failure.
      • -2: The parameter is invalid.
      • -3: The SDK fails to be initialized. You can try re-initializing the SDK.
      • `-5: The request is rejected. This may be caused by the following:
        • You have created an AgoraRtcChannel object with the same channel name.
        • You have joined and published a stream in a channel created by the AgoraRtcChannel object. When you join a channel created by the AgoraRtcEngine object, the SDK publishes the local audio and video streams to that channel by default. Because the SDK does not support publishing a local stream to more than one channel simultaneously, an error occurs in this occasion.
      • -7: The SDK is not initialized before calling this method.

joinChannelWithUserAccount

  • joinChannelWithUserAccount(token: string, channel: string, userAccount: string, options?: ChannelMediaOptions): number
  • Joins the channel with a user account.

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

    • The local client: localUserRegistered and userInfoUpdated.
    • The remote client: userJoined and userInfoUpdated, if the user joining the channel is in the communication(0) profile, or is a host in the 1 (live streaming) profile.
    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.

    Parameters

    • token: string

      The token generated at your server. For details, see Generate a token.

    • channel: string

      The channel name. The maximum length of this parameter is 64 bytes. Supported character scopes are:

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

      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:

      • 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: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
    • Optional options: ChannelMediaOptions

      The channel media options. See ChannelMediaOptions.

    Returns number

    • 0: Success.
    • < 0: Failure.
      • -2
      • -3
      • -5
      • -7

leaveChannel

  • leaveChannel(): number
  • Allows a user to leave a channel.

    Allows a user to leave a channel, such as hanging up or exiting a call. The user must call the method to end the call before joining another channel after call the joinChannel method. This method returns 0 if the user leaves the channel and releases all resources related to the call. This method call is asynchronous, and the user has not left the channel when the method call returns.

    Once the user leaves the channel, the SDK triggers the leavechannel callback.

    A successful leavechannel method call triggers the removeStream callback for the remote client when the user leaving the channel is in the Communication channel, or is a host in the 1 (live streaming) profile.

    Returns number

    • 0: Success.
    • < 0: Failure.

muteAllRemoteAudioStreams

  • muteAllRemoteAudioStreams(mute: boolean): number
  • Stops or resumes subscribing to the audio streams of all remote users.

    As of v3.3.1, 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.

    Parameters

    • mute: boolean

      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.

    Returns number

    • 0: Success.
    • < 0: Failure.

muteAllRemoteVideoStreams

  • muteAllRemoteVideoStreams(mute: boolean): number
  • Stops or resumes subscribing to the video streams of all remote users.

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

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

    Parameters

    • mute: boolean

      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.

    Returns number

    • 0: Success.
    • < 0: Failure.

muteLocalAudioStream

  • muteLocalAudioStream(mute: boolean): number
  • Stops or resumes publishing the local audio stream.

    A successful muteLocalAudioStream method call triggers the userMuteAudio 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 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.

    Parameters

    • mute: boolean

      Sets whether to stop publishing the local audio stream.

      • true: Stop publishing the local audio stream.
      • false: (Default) Resumes publishing the local audio stream.

    Returns number

    • 0: Success.
    • < 0: Failure.

muteLocalVideoStream

  • muteLocalVideoStream(mute: boolean): number
  • Stops or resumes publishing the local video stream.

    A successful muteLocalVideoStream method call triggers the userMuteVideo callback on the remote client.

    note
    • This method executes faster than the 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 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.

    Parameters

    • mute: boolean

      Sets whether to stop publishing the local video stream.

      • true: Stop publishing the local video stream.
      • false: (Default) Resumes publishing the local video stream.

    Returns number

    • 0: Success.
    • < 0: Failure.

muteRemoteAudioStream

  • muteRemoteAudioStream(uid: number, mute: boolean): number
  • Stops or resumes subscribing to the audio stream of a specified user.

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

    Parameters

    • uid: number
    • mute: boolean

      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.

    Returns number

    • 0: Success.
    • < 0: Failure.

muteRemoteVideoStream

  • muteRemoteVideoStream(uid: number, mute: boolean): number
  • Stops or resumes subscribing to the video stream of a specified user.

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

    Parameters

    • uid: number
    • mute: boolean

      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.

    Returns number

    • 0: Success.
    • < 0: Failure.

off

  • off(event: string | symbol, listener: function): this
  • Parameters

    • event: string | symbol
    • listener: function
        • (...args: any[]): void
        • Parameters

          • Rest ...args: any[]

          Returns void

    Returns this

on

  • on(event: string | symbol, listener: function): this
  • on(evt: "apiCallExecuted", cb: function): this
  • on(evt: "warning", cb: function): this
  • on(evt: "error", cb: function): this
  • on(evt: "joinedChannel", cb: function): this
  • on(evt: "rejoinedChannel", cb: function): this
  • on(evt: "audioVolumeIndication", cb: function): this
  • on(evt: "groupAudioVolumeIndication", cb: function): this
  • on(evt: "leaveChannel", cb: function): this
  • on(evt: "rtcStats", cb: function): this
  • on(evt: "localVideoStats", cb: function): this
  • on(evt: "localAudioStats", cb: function): this
  • on(evt: "remoteVideoStats", cb: function): this
  • on(evt: "remoteAudioStats", cb: function): this
  • on(evt: "remoteVideoTransportStats", cb: function): this
  • on(evt: "remoteAudioTransportStats", cb: function): this
  • on(evt: "requestAudioFileInfo", cb: function): this
  • on(evt: "audioDeviceStateChanged", cb: function): this
  • on(evt: "audioMixingStateChanged", cb: function): this
  • on(evt: "remoteAudioMixingBegin", cb: function): this
  • on(evt: "remoteAudioMixingEnd", cb: function): this
  • on(evt: "audioEffectFinished", cb: function): this
  • on(evt: "videoDeviceStateChanged", cb: function): this
  • on(evt: "networkQuality", cb: function): this
  • on(evt: "lastMileQuality", cb: function): this
  • on(evt: "lastmileProbeResult", cb: function): this
  • on(evt: "firstLocalVideoFrame", cb: function): this
  • on(evt: "addStream", cb: function): this
  • on(evt: "videoSizeChanged", cb: function): this
  • on(evt: "firstRemoteVideoFrame", cb: function): this
  • on(evt: "firstRemoteVideoDecoded", cb: function): this
  • on(evt: "userJoined", cb: function): this
  • on(evt: "removeStream", cb: function): this
  • on(evt: "userOffline", cb: function): this
  • on(evt: "userMuteAudio", cb: function): this
  • on(evt: "userMuteVideo", cb: function): this
  • on(evt: "userEnableVideo", cb: function): this
  • on(evt: "userEnableLocalVideo", cb: function): this
  • on(evt: "cameraReady", cb: function): this
  • on(evt: "videoStopped", cb: function): this
  • on(evt: "connectionLost", cb: function): this
  • on(evt: "connectionBanned", cb: function): this
  • on(evt: "streamMessage", cb: function): this
  • on(evt: "streamMessageError", cb: function): this
  • on(evt: "mediaEngineStartCallSuccess", cb: function): this
  • on(evt: "requestChannelKey", cb: function): this
  • on(evt: "firstLocalAudioFrame", cb: function): this
  • on(evt: "firstRemoteAudioFrame", cb: function): this
  • on(evt: "firstRemoteAudioDecoded", cb: function): this
  • on(evt: "activeSpeaker", cb: function): this
  • on(evt: "clientRoleChanged", cb: function): this
  • on(evt: "audioDeviceVolumeChanged", cb: function): this
  • on(evt: "videoSourceJoinedSuccess", cb: function): this
  • on(evt: "videoSourceRequestNewToken", cb: function): this
  • on(evt: "videoSourceLeaveChannel", cb: function): this
  • on(evt: "videoSourceScreenCaptureInfoUpdated", cb: function): this
  • on(evt: "videoSourceLocalAudioStats", cb: function): this
  • on(evt: "videoSourceLocalVideoStats", cb: function): this
  • on(evt: "videoSourceVideoSizeChanged", cb: function): this
  • on(evt: "videoSourceLocalVideoStateChanged", cb: function): this
  • on(evt: "videoSourceLocalAudioStateChanged", cb: function): this
  • on(evt: "remoteVideoStateChanged", cb: function): this
  • on(evt: "cameraFocusAreaChanged", cb: function): this
  • on(evt: "cameraExposureAreaChanged", cb: function): this
  • on(evt: "tokenPrivilegeWillExpire", cb: function): this
  • on(evt: "streamPublished", cb: function): this
  • on(evt: "streamUnpublished", cb: function): this
  • on(evt: "rtmpStreamingStateChanged", cb: function): this
  • on(evt: "transcodingUpdated", cb: function): this
  • on(evt: "streamInjectStatus", cb: function): this
  • on(evt: "localPublishFallbackToAudioOnly", cb: function): this
  • on(evt: "remoteSubscribeFallbackToAudioOnly", cb: function): this
  • on(evt: "microphoneEnabled", cb: function): this
  • on(evt: "connectionStateChanged", cb: function): this
  • on(evt: "networkTypeChanged", cb: function): this
  • on(evt: "localUserRegistered", cb: function): this
  • on(evt: "userInfoUpdated", cb: function): this
  • on(evt: "localVideoStateChanged", cb: function): this
  • on(evt: "localAudioStateChanged", cb: function): this
  • on(evt: "remoteAudioStateChanged", cb: function): this
  • on(evt: "channelMediaRelayState", cb: function): this
  • on(evt: "channelMediaRelayEvent", cb: function): this
  • on(evt: "receiveMetadata", cb: function): this
  • on(evt: "sendMetadataSuccess", cb: function): this
  • on(evt: "firstLocalAudioFramePublished", cb: function): this
  • on(evt: "firstLocalVideoFramePublished", cb: function): this
  • on(evt: "rtmpStreamingEvent", cb: function): this
  • on(evt: "audioPublishStateChanged", cb: function): this
  • on(evt: "videoPublishStateChanged", cb: function): this
  • on(evt: "audioSubscribeStateChanged", cb: function): this
  • on(evt: "videoSubscribeStateChanged", cb: function): this
  • on(evt: "uploadLogResult", cb: function): this
  • on(evt: "virtualBackgroundSourceEnabled", cb: function): this
  • on(evt: "localVoicePitchInHz", cb: function): this
  • on(evt: "clientRoleChangeFailed", cb: function): this
  • on(evt: "proxyConnected", cb: function): this
  • on(evt: "agoraVideoRawData", cb: function): this
  • on(evt: string, listener: Function): this
  • Parameters

    • event: string | symbol
    • listener: function
        • (...args: any[]): void
        • Parameters

          • Rest ...args: any[]

          Returns void

    Returns this

  • Occurs when an API method is executed.

    api: The method executed by the SDK.

    err: Error code that the SDK returns when the method call fails.

    Parameters

    • evt: "apiCallExecuted"
    • cb: function
        • (api: string, err: number): void
        • Parameters

          • api: string
          • err: number

          Returns void

    Returns this

  • Reports a warning during SDK runtime.

    Parameters

    • evt: "warning"
    • cb: function
        • (warn: number, msg: string): void
        • Parameters

          • warn: number

            Warning code.

          • msg: string

            The warning message.

          Returns void

    Returns this

  • Reports an error during SDK runtime.

    Parameters

    • evt: "error"
    • cb: function
        • (err: number, msg: string): void
        • Parameters

          • err: number

            Error code.

          • msg: string

            The error message.

          Returns void

    Returns this

  • Occurs when a user joins a specified channel.

    Parameters

    • evt: "joinedChannel"
    • cb: function
        • (channel: string, uid: number, elapsed: number): void
        • Parameters

          • channel: string

            The channel name.

          • uid: number

            User ID of the user joining the channel.

          • elapsed: number

            Time elapsed (ms) from the user calling the joinChannel method until the SDK triggers this callback.

          Returns void

    Returns this

  • Occurs when a user rejoins the channel after disconnection due to network problems. When a user loses connection with the server because of network problems, the SDK automatically tries to reconnect and triggers this callback upon reconnection.

    Parameters

    • evt: "rejoinedChannel"
    • cb: function
        • (channel: string, uid: number, elapsed: number): void
        • Parameters

          • channel: string

            The channel name.

          • uid: number

            User ID of the user joining the channel.

          • elapsed: number

            Time elapsed (ms) from the user calling the joinChannel method until the SDK triggers this callback.

          Returns void

    Returns this

  • deprecated

    Deprecated. Use the groupAudioVolumeIndication callback instead.

    Parameters

    • evt: "audioVolumeIndication"
    • cb: function
        • (uid: number, volume: number, speakerNumber: number, totalVolume: number): void
        • Parameters

          • uid: number
          • volume: number
          • speakerNumber: number
          • totalVolume: number

          Returns void

    Returns this

  • 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 enableAudioVolumeIndication method.

    The SDK triggers two independent groupudioVolumeIndication 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 muteLocalAudioStream method affects the SDK's behavior:
      • If the local user calls muteLocalAudioStream, the SDK stops triggering the local user's callback.
      • 20 seconds after a remote speaker calls muteLocalAudioStream, the remote speakers' callback excludes this remote user's information; 20 seconds after all remote users call muteLocalAudioStream, the SDK stops triggering the remote speakers' callback.

    Parameters

    • evt: "groupAudioVolumeIndication"
    • cb: function
        • (speakers: object[], speakerNumber: number, totalVolume: number): void
        • Parameters

          • speakers: object[]

            The speakers' information:

            • In the local client:
              • uid: 0.
              • volume: The volume of the local speaker.
              • vad: The voice activity status of the local user.
            • In each remote client:
              • uid: The ID of the remote user.
              • volume: The sum of the voice volume and audio-mixing volume of each remote speaker.
              • vad: 0.
          • speakerNumber: number

            Total number of speakers. The value range is [0, 3].

            • In the local client: 1.
            • In each remote client: 3, the three loudest speakers.
          • totalVolume: number

            Total volume after audio mixing. The value ranges between 0 (lowest volume) and 255 (highest volume).

            • In the local client: The sum of the voice volume and audio-mixing volume of the local user.
            • In each remote client: The sum of the voice volume and audio-mixing volume of all the remote speakers.

          Returns void

    Returns this

  • Occurs when the user leaves the channel. When the app calls the leaveChannel method, the SDK uses this callback to notify the app when the user leaves the channel.

    Parameters

    • evt: "leaveChannel"
    • cb: function

    Returns this

  • Reports the statistics of the AgoraRtcEngine once every two seconds.

    Parameters

    • evt: "rtcStats"
    • cb: function

    Returns this

  • Reports the statistics of the local video streams.

    Note:

    If you have called the enableDualStreamMode method, the localVideoStats callback reports the statistics of the high-video stream (high bitrate, and high-resolution video stream).

    Parameters

    Returns this

  • Reports the statistics of the local audio streams.

    The SDK triggers this callback once every two seconds.

    Parameters

    Returns this

  • Reports the statistics of the video stream from each remote user/host.

    Parameters

    Returns this

  • Reports the statistics of the audio stream from each remote user/host.

    Parameters

    Returns this

  • deprecated

    This callback is deprecated. Use remoteVideoStats instead.

    Reports the transport-layer statistics of each remote video stream.

    This callback reports the transport-layer statistics, such as the packet loss rate and time delay, once every two seconds after the local user receives the video packet from a remote user.

    Parameters

    Returns this

  • deprecated

    This callback is deprecated. Use remoteAudioStats instead.

    Reports the transport-layer statistics of each remote audio stream.

    Parameters

    Returns this

  • Parameters

    Returns this

  • Occurs when the audio device state changes.

    Parameters

    • evt: "audioDeviceStateChanged"
    • cb: function
        • (deviceId: string, deviceType: number, deviceState: number): void
        • Parameters

          • deviceId: string

            The device ID.

          • deviceType: number

            The device type. See MediaDeviceType.

          • deviceState: number

            The device state:

            • macOS:
              • 0: The device is ready for use.
              • 8: The device is unplugged.
            • Windows:
              • 0: The device is ready for use.
              • 1: The device is in use.
              • 2: The device is disabled.
              • 4: The device is not present.
              • 8: The device is unplugged.
              • 16: The device is not recommended.

          Returns void

    Returns this

  • Occurs when the state of the local user's music file changes.

    since

    v3.4.2

    When the playback state of the local user's music file changes, the SDK triggers this callback and reports the current playback state and the reason for the change.

    Parameters

    • evt: "audioMixingStateChanged"
    • cb: function
        • (state: number, reason: number): void
        • Parameters

          • state: number

            The current music file playback state:

            • 710: The music file is playing. This state comes with reason 720, 721, 722, or 726.
            • 711: The music file pauses playing. This state comes with reason 725.
            • 713: The music file stops playing. This state comes with reason 723 or 724.
            • 714: An exception occurs during the playback of the music file. This state comes with reason 701, 702, or 703.
          • reason: number

            The reason for the change of the music file playback state.

            • 701: The SDK cannot open the music file. Possible causes include the local music file does not exist, the SDK does not support the file format, or the SDK cannot access the music file URL.
            • 702: The SDK opens the music file too frequently. If you need to call startAudioMixing multiple times, ensure that the call interval is longer than 500 ms.
            • 703: The music file playback is interrupted.
            • 720: Successfully calls startAudioMixing to play a music file.
            • 721: The music file completes a loop playback.
            • 722: The music file starts a new loop playback.
            • 723: The music file completes all loop playback.
            • 724: Successfully calls stopAudioMixing to stop playing the music file.
            • 725: Successfully calls pauseAudioMixing to pause playing the music file.
            • 726: Successfully calls resumeAudioMixing to resume playing the music file.

          Returns void

    Returns this

  • Occurs when a remote user starts audio mixing. When a remote user calls startAudioMixing to play the background music, the SDK reports this callback.

    Parameters

    • evt: "remoteAudioMixingBegin"
    • cb: function
        • (): void
        • Returns void

    Returns this

  • Occurs when a remote user finishes audio mixing.

    Parameters

    • evt: "remoteAudioMixingEnd"
    • cb: function
        • (): void
        • Returns void

    Returns this

  • Occurs when the local audio effect playback finishes.

    Parameters

    • evt: "audioEffectFinished"
    • cb: function
        • (soundId: number): void
        • Parameters

          • soundId: number

          Returns void

    Returns this

  • Occurs when the video device state changes.

    Parameters

    • evt: "videoDeviceStateChanged"
    • cb: function
        • (deviceId: string, deviceType: number, deviceState: number): void
        • Parameters

          • deviceId: string

            The device ID.

          • deviceType: number

            The device type. See MediaDeviceType.

          • deviceState: number

            The device state:

            • macOS:
              • 0: The device is added.
              • 1: The device is removed.
            • Windows:
              • 1: The device is idle.
              • 2: The device is disabled.
              • 4: The device is not present.
              • 8: The device is unplugged.
              • 16: The device is not recommended.

          Returns void

    Returns this

  • Reports the last mile network quality of each user in the channel once every two seconds.

    Last mile refers to the connection between the local device and Agora's edge server.

    Parameters

    • evt: "networkQuality"
    • cb: function
        • Parameters

          • uid: number

            User ID. The network quality of the user with this uid is reported. If uid is 0, the local network quality is reported.

          • txquality: AgoraNetworkQuality

            Uplink transmission quality rating of the user in terms of the transmission bitrate, packet loss rate, average RTT (Round-Trip Time), and jitter of the uplink network. See AgoraNetworkQuality.

          • rxquality: AgoraNetworkQuality

            Downlink network quality rating of the user in terms of the packet loss rate, average RTT, and jitter of the downlink network. See AgoraNetworkQuality.

          Returns void

    Returns this

  • Reports the last mile network quality of the local user once every two seconds before the user joins the channel.

    Last mile refers to the connection between the local device and Agora's edge server. After the application calls the enableLastmileTest method, this callback reports once every two seconds the uplink and downlink last mile network conditions of the local user before the user joins the channel.

    Parameters

    Returns this

  • Reports the last-mile network probe result.

    • result: The uplink and downlink last-mile network probe test result. See LastmileProbeResult.

    The SDK triggers this callback within 30 seconds after the app calls the startLastmileProbeTest method.

    Parameters

    Returns this

  • Occurs when the first local video frame is displayed/rendered on the local video view.

    • width: Width (px) of the first local video frame.
    • height: Height (px) of the first local video frame.
    • elapsed: Time elapsed (ms) from the local user calling the joinChannel method until the SDK triggers this callback.

    Parameters

    • evt: "firstLocalVideoFrame"
    • cb: function
        • (width: number, height: number, elapsed: number): void
        • Parameters

          • width: number
          • height: number
          • elapsed: number

          Returns void

    Returns this

  • deprecated

    This callback is deprecated. Use the remoteVideoStateChanged callback instead.

    Occurs when the first remote video frame is received and decoded.

    • uid: User ID of the remote user sending the video stream.
    • elapsed: Time elapsed (ms) from the local user calling the joinChannel method until the SDK triggers this callback. This callback is triggered in either of the following scenarios:
    • The remote user joins the channel and sends the video stream.
    • The remote user stops sending the video stream and re-sends it after 15 seconds. Reasons for such an interruption include:
      • The remote user leaves the channel.
      • The remote user drops offline.
      • The remote user calls the muteLocalVideoStream method to stop sending the video stream.
      • The remote user calls the disableVideo method to disable video.

    Parameters

    • evt: "addStream"
    • cb: function
        • (uid: number, elapsed: number): void
        • Parameters

          • uid: number
          • elapsed: number

          Returns void

    Returns this

  • Occurs when the video size or rotation of a specified user changes.

    Parameters

    • evt: "videoSizeChanged"
    • cb: function
        • (uid: number, width: number, height: number, rotation: number): void
        • Parameters

          • uid: number

            User ID of the remote user or local user (0) whose video size or rotation changes.

          • width: number

            New width (pixels) of the video.

          • height: number

            New height (pixels) of the video.

          • rotation: number

          Returns void

    Returns this

  • deprecated

    This callback is deprecated, please use remoteVideoStateChanged instead.

    Occurs when the first remote video frame is rendered.

    The SDK triggers this callback when the first frame of the remote video is displayed in the user's video window.

    Parameters

    • evt: "firstRemoteVideoFrame"
    • cb: function
        • (uid: number, width: number, height: number, elapsed: number): void
        • Parameters

          • uid: number

            User ID of the remote user sending the video stream.

          • width: number

            Width (pixels) of the video frame.

          • height: number

            Height (pixels) of the video stream.

          • elapsed: number

            Time elapsed (ms) from the local user calling the joinChannel method until the SDK triggers this callback.

          Returns void

    Returns this

  • Occurs when the first remote video frame is decoded. The SDK triggers this callback when the first frame of the remote video is decoded.

    • uid: User ID of the remote user sending the video stream.
    • width: Width (pixels) of the video frame.
    • height: Height (pixels) of the video stream.
    • elapsed: Time elapsed (ms) from the local user calling the joinChannel method until the SDK triggers this callback.

    Parameters

    • evt: "firstRemoteVideoDecoded"
    • cb: function
        • (uid: number, width: number, height: number, elapsed: number): void
        • Parameters

          • uid: number
          • width: number
          • height: number
          • elapsed: number

          Returns void

    Returns this

  • Occurs when a user or host joins the channel.

    The SDK triggers this callback under one of the following circumstances:

    • A remote user/host joins the channel by calling the joinChannel method.
    • A remote user switches the user role to the host by calling the setClientRole method after joining the channel.
    • A remote user/host rejoins the channel after a network interruption.
    • The host injects an online media stream into the channel by calling the addInjectStreamUrl method.
    note

    In the 1 (live streaming) profile:

    • The host receives this callback when another host joins the channel.
    • The audience in the channel receives this callback when a new host joins the channel.
    • When a web application joins the channel, the SDK triggers this callback as long as the web application publishes streams.

    Parameters

    • evt: "userJoined"
    • cb: function
        • (uid: number, elapsed: number): void
        • Parameters

          • uid: number

            User ID of the user or host joining the channel.

          • elapsed: number

            Time delay (ms) from the local user calling the joinChannel method until the SDK triggers this callback.

          Returns void

    Returns this

  • deprecated

    This callback is deprecated. Use userOffline instead.

    Occurs when a remote user leaves the channel.

    • uid: User ID of the user leaving the channel or going offline.
    • reason: Reason why the user is offline:
      • 0: The user quits the call.
      • 1: The SDK times out and the user drops offline because no data packet is received within a certain period of time. If the user quits the call and the message is not passed to the SDK (due to an unreliable channel), the SDK assumes the user dropped offline.
      • 2: The client role switched from the host to the audience. Reasons why the user is offline:
    • Leave the channel: When the user leaves the channel, the user sends a goodbye message. When the message is received, the SDK assumes that the user leaves the channel.
    • Drop offline: When no data packet of the user or host is received for a certain period of time (20 seconds for the communication(0) profile, and more for the 1 (live streaming) profile), the SDK assumes that the user drops offline. Unreliable network connections may lead to false detections, so we recommend using a signaling system for more reliable offline detection.

    Parameters

    • evt: "removeStream"
    • cb: function
        • (uid: number, reason: number): void
        • Parameters

          • uid: number
          • reason: number

          Returns void

    Returns this

  • Occurs when a remote user (Communication)/host (Live streaming) leaves the channel.

    There are two reasons for users to become offline:

    • Leave the channel: When the user/host leaves the channel, the user/host sends a goodbye message. When this message is received, the SDK determines that the user/host leaves the channel.
    • Drop offline: When no data packet of the user or host is received for a certain period of time, the SDK assumes that the user/host drops offline. A poor network connection may lead to false detections, so we recommend using the signaling system for reliable offline detection.

    Parameters

    • evt: "userOffline"
    • cb: function
        • (uid: number, reason: number): void
        • Parameters

          • uid: number

            ID of the user or host who leaves the channel or goes offline.

          • reason: number

            Reason why the user goes offline:

            • The user left the current channel.
            • The SDK timed out and the user dropped offline because no data packet was received within a certain period of time. If a user quits the call and the message is not passed to the SDK (due to an unreliable channel), the SDK assumes the user dropped offline.
            • (Live streaming only.) The client role switched from the host to the audience.

          Returns void

    Returns this

  • deprecated

    This callback is deprecated, please use remoteAudioStateChanged instead.

    Occurs when a remote user's audio stream is muted/unmuted.

    The SDK triggers this callback when the remote user stops or resumes sending the audio stream by calling the muteLocalAudioStream method.

    • uid: User ID of the remote user.
    • muted: Whether the remote user's audio stream is muted/unmuted:
      • true: Muted.
      • false: Unmuted.

    Parameters

    • evt: "userMuteAudio"
    • cb: function
        • (uid: number, muted: boolean): void
        • Parameters

          • uid: number
          • muted: boolean

          Returns void

    Returns this

  • Occurs when a remote user's video stream playback pauses/resumes.

    The SDK triggers this callback when the remote user stops or resumes sending the video stream by calling the muteLocalVideoStream method.

    • uid: User ID of the remote user.
    • muted: Whether the remote user's video stream playback is paused/resumed:
      • true: Paused.
      • false: Resumed.

    Note: This callback returns invalid when the number of users in a channel exceeds 20.

    Parameters

    • evt: "userMuteVideo"
    • cb: function
        • (uid: number, muted: boolean): void
        • Parameters

          • uid: number
          • muted: boolean

          Returns void

    Returns this

  • deprecated

    This callback is deprecated. Use the remoteVideoStateChanged callback instead.

    Occurs when a specific remote user enables/disables the video module.

    The SDK triggers this callback when the remote user enables or disables the video module by calling the enableVideo or disableVideo method.

    • uid: User ID of the remote user.
    • enabled: Whether the remote user enables/disables the video module:
      • true: Enable. The remote user can enter a video session.
      • false: Disable. The remote user can only enter a voice session, and cannot send or receive any video stream.

    Parameters

    • evt: "userEnableVideo"
    • cb: function
        • (uid: number, enabled: boolean): void
        • Parameters

          • uid: number
          • enabled: boolean

          Returns void

    Returns this

  • deprecated

    This callback is deprecated. Use the remoteVideoStateChanged callback instead.

    Occurs when a specified remote user enables/disables the local video capturing function.

    The SDK triggers this callback when the remote user resumes or stops capturing the video stream by calling the enableLocalVideo method.

    • uid: User ID of the remote user.
    • enabled: Whether the remote user enables/disables the local video capturing function:
      • true: Enable. Other users in the channel can see the video of this remote user.
      • false: Disable. Other users in the channel can no longer receive the video stream from this remote user, while this remote user can still receive the video streams from other users.

    Parameters

    • evt: "userEnableLocalVideo"
    • cb: function
        • (uid: number, enabled: boolean): void
        • Parameters

          • uid: number
          • enabled: boolean

          Returns void

    Returns this

  • deprecated

    Replaced by the localVideoStateChanged callback. Occurs when the camera turns on and is ready to capture the video.

    Parameters

    • evt: "cameraReady"
    • cb: function
        • (): void
        • Returns void

    Returns this

  • deprecated

    Replaced by the localVideoStateChanged callback. Occurs when the video stops playing.

    Parameters

    • evt: "videoStopped"
    • cb: function
        • (): void
        • Returns void

    Returns this

  • Occurs when the SDK cannot reconnect to Agora's edge server 10 seconds after its connection to the server is interrupted.

    The SDK triggers this callback when it cannot connect to the server 10 seconds after calling the joinChannel method, whether or not it is in the channel.

    • If the SDK fails to rejoin the channel 20 minutes after being disconnected from Agora's edge server, the SDK stops rejoining the channel.

    Parameters

    • evt: "connectionLost"
    • cb: function
        • (): void
        • Returns void

    Returns this

  • deprecated

    Replaced by the connectionStateChanged callback. Occurs when your connection is banned by the Agora Server.

    Parameters

    • evt: "connectionBanned"
    • cb: function
        • (): void
        • Returns void

    Returns this

  • Occurs when the local user receives the data stream from the remote user within five seconds.

    The SDK triggers this callback when the local user receives the stream message that the remote user sends by calling the sendStreamMessage method.

    Parameters

    • evt: "streamMessage"
    • cb: function
        • (uid: number, streamId: number, msg: string, len: number): void
        • Parameters

          • uid: number

            User ID of the remote user sending the message.

          • streamId: number

            Stream ID.

          • msg: string

            The data received bt the local user.

          • len: number

            Length of the data in bytes.

          Returns void

    Returns this

  • Occurs when the local user does not receive the data stream from the remote user within five seconds.

    The SDK triggers this callback when the local user fails to receive the stream message that the remote user sends by calling the sendStreamMessage method.

    Parameters

    • evt: "streamMessageError"
    • cb: function
        • (uid: number, streamId: number, code: number, missed: number, cached: number): void
        • Parameters

          • uid: number

            User ID of the remote user sending the message.

          • streamId: number

            Stream ID.

          • code: number
          • missed: number

            Number of the lost messages.

          • cached: number

            Number of incoming cached messages when the data stream is interrupted.

          Returns void

    Returns this

  • Occurs when the media engine call starts.

    Parameters

    • evt: "mediaEngineStartCallSuccess"
    • cb: function
        • (): void
        • Returns void

    Returns this

  • Occurs when the token expires.

    After a token(channel key) is specified by calling the joinChannel method, if the SDK losses connection with the Agora server due to network issues, the token may expire after a certain period of time and a new token may be required to reconnect to the server.

    This callback notifies the application to generate a new token. Call the renewToken method to renew the token

    Parameters

    • evt: "requestChannelKey"
    • cb: function
        • (): void
        • Returns void

    Returns this

  • Occurs when the engine sends the first local audio frame.

    deprecated

    This callback is deprecated from v3.2.0. Use the firstLocalAudioFramePublished instead.

    • elapsed: Time elapsed (ms) from the local user calling joinChannel until the SDK triggers this callback.

    Parameters

    • evt: "firstLocalAudioFrame"
    • cb: function
        • (elapsed: number): void
        • Parameters

          • elapsed: number

          Returns void

    Returns this

  • deprecated

    This callback is deprecated. Please use remoteAudioStateChanged instead.

    Occurs when the engine receives the first audio frame from a specific remote user.

    • uid: User ID of the remote user.
    • elapsed: Time elapsed (ms) from the local user calling joinChannel until the SDK triggers this callback.

    Parameters

    • evt: "firstRemoteAudioFrame"
    • cb: function
        • (uid: number, elapsed: number): void
        • Parameters

          • uid: number
          • elapsed: number

          Returns void

    Returns this

  • deprecated

    This callback is deprecated, please use remoteAudioStateChanged instead.

    Occurs when the engine receives the first audio frame from a specified remote user.

    Parameters

    • evt: "firstRemoteAudioDecoded"
    • cb: function
        • (uid: number, elapsed: number): void
        • Parameters

          • uid: number

            User ID of the remote user sending the audio stream.

          • elapsed: number

            The time elapsed (ms) from the local user calling the joinChannel method until the SDK triggers this callback.

          Returns void

    Returns this

  • Reports which user is the loudest speaker.

    This callback returns the user ID of the user with the highest voice volume during a period of time, instead of at the moment.

    note

    To receive this callback, you need to call the enableAudioVolumeIndication method.

    Parameters

    • evt: "activeSpeaker"
    • cb: function
        • (uid: number): void
        • Parameters

          • uid: number

            User ID of the active speaker. If the user enables the audio volume indication by calling the enableAudioVolumeIndication method, this callback returns the uid of the active speaker detected by the audio volume detection module of the SDK.

          Returns void

    Returns this

  • Occurs when the user role switches in a 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 setClientRole method.

    Parameters

    Returns this

  • Occurs when the volume of the playback device, microphone, or application changes.

    Parameters

    • evt: "audioDeviceVolumeChanged"
    • cb: function
        • Parameters

          • deviceType: MediaDeviceType

            Device type. See {@link AgoraRtcEngine.MediaDeviceType MediaDeviceType}.

          • volume: number

            Volume of the device. The value ranges between 0 and 255.

          • muted: boolean
            • true: The audio device is muted.
            • false: The audio device is not muted.

          Returns void

    Returns this

  • Occurs when the local video source joins the channel.

    Parameters

    • evt: "videoSourceJoinedSuccess"
    • cb: function
        • (uid: number): void
        • Parameters

          • uid: number

            The User ID.

          Returns void

    Returns this

  • Occurs when the token expires.

    Parameters

    • evt: "videoSourceRequestNewToken"
    • cb: function
        • (): void
        • Returns void

    Returns this

  • Occurs when the video source leaves the channel.

    Parameters

    • evt: "videoSourceLeaveChannel"
    • cb: function
        • (): void
        • Returns void

    Returns this

  • Occurs when screencapture fail to filter window

    Parameters

    Returns this

  • Reports the statistics of the audio stream of the local video source.

    The SDK triggers this callback once every two seconds.

    Parameters

    • evt: "videoSourceLocalAudioStats"
    • cb: function

    Returns this

  • Reports the statistics of the video stream of the local video source.

    The SDK triggers this callback once every two seconds for each user/host. If there are multiple users/hosts in the channel, the SDK triggers this callback as many times.

    Parameters

    • evt: "videoSourceLocalVideoStats"
    • cb: function

    Returns this

  • Occurs when the video size or rotation of the video source changes.

    Parameters

    • evt: "videoSourceVideoSizeChanged"
    • cb: function
        • (uid: number, width: number, height: number, rotation: number): void
        • Parameters

          • uid: number

            User ID of the remote video source or local video source (0) whose video size or rotation changes.

          • width: number

            New width (pixels) of the video.

          • height: number

            New height (pixels) of the video.

          • rotation: number

            New rotation of the video [0 to 360).

          Returns void

    Returns this

  • Occurs when the local video state of the video source 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.

    The SDK triggers the videoSourceLocalVideoStateChanged(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 videoSourceLocalVideoStateChanged(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 Windows 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.

    Parameters

    Returns this

  • Occurs when the local audio state of the video source changes.

    This callback indicates the state change of the local audio stream, including the state of the audio recording and encoding, and allows you to troubleshoot issues when exceptions occur.

    Parameters

    Returns this

  • Occurs when the remote video state changes.

    Parameters

    Returns this

  • Occurs when the camera focus area changes.

    • x: x coordinate of the changed camera focus area.
    • y: y coordinate of the changed camera focus area.
    • width: Width of the changed camera focus area.
    • height: Height of the changed camera focus area.

    Parameters

    • evt: "cameraFocusAreaChanged"
    • cb: function
        • (x: number, y: number, width: number, height: number): void
        • Parameters

          • x: number
          • y: number
          • width: number
          • height: number

          Returns void

    Returns this

  • Occurs when the camera exposure area changes.

    • x: x coordinate of the changed camera exposure area.
    • y: y coordinate of the changed camera exposure area.
    • width: Width of the changed camera exposure area.
    • height: Height of the changed camera exposure area.

    Parameters

    • evt: "cameraExposureAreaChanged"
    • cb: function
        • (x: number, y: number, width: number, height: number): void
        • Parameters

          • x: number
          • y: number
          • width: number
          • height: number

          Returns void

    Returns this

  • Occurs when the token expires in 30 seconds.

    The user becomes offline if the token used in the joinChannel method expires. The SDK triggers this callback 30 seconds before the token expires to remind the application to get a new token. Upon receiving this callback, generate a new token on the server and call the renewToken method to pass the new token to the SDK.

    Parameters

    • evt: "tokenPrivilegeWillExpire"
    • cb: function
        • (token: string): void
        • Parameters

          • token: string

            The token that expires in 30 seconds.

          Returns void

    Returns this

  • deprecated

    This callback is deprecated. Please use rtmpStreamingStateChanged instead.

    Reports the result of Media Push.

    • url: The RTMP URL address.
    • error: Error code:
      • 0: The publishing succeeds.
      • 1: The publishing fails.
      • 2: Invalid argument used. For example, you did not call setLiveTranscoding to configure LiveTranscoding before calling addPublishStreamUrl.
      • 10: The publishing timed out.
      • 19: The publishing timed out.
      • 130: You cannot publish an encrypted stream.

    Parameters

    • evt: "streamPublished"
    • cb: function
        • (url: string, error: number): void
        • Parameters

          • url: string
          • error: number

          Returns void

    Returns this

  • deprecated

    This callback is deprecated. Please use rtmpStreamingStateChanged instead.

    This callback indicates whether you have successfully removed an RTMP stream from the CDN.

    Reports the result of calling the removePublishStreamUrl method.

    • url: The RTMP URL address.

    Parameters

    • evt: "streamUnpublished"
    • cb: function
        • (url: string): void
        • Parameters

          • url: string

          Returns void

    Returns this

  • Occurs when the state of Media Push changes.

    The SDK triggers this callback to report the result of the local user calling the addPublishStreamUrl and removePublishStreamUrl method.

    This callback indicates the state of Media Push. When exceptions occur, you can troubleshoot issues by referring to the detailed error descriptions in the code parameter.

    Parameters

    • evt: "rtmpStreamingStateChanged"
    • cb: function
        • (url: string, state: number, code: number): void
        • Parameters

          • url: string

            The RTMP URL address.

          • state: number

            Media Push state:

            • 0: Media Push has not started or has ended. This state is also triggered after you remove an RTMP address from the CDN by calling removePublishStreamUrl.
            • 1: The SDK is connecting to Agora's streaming server and the RTMP server. This state is triggered after you call the addPublishStreamUrl method.
            • 2: Media Push publishes. The SDK successfully publishes the Media Push stream and returns this state.
            • 3: Media Push is recovering. When exceptions occur to the CDN, or the streaming is interrupted, the SDK tries to resume Media Push and returns this state.
              • If the SDK successfully resumes the streaming, 2 returns.
              • If the streaming does not resume within 60 seconds or server errors occur, 4 returns. You can also reconnect to the server by calling the removePublishStreamUrl and then addPublishStreamUrl method.
            • 4: Media Push fails. See the code parameter for the detailed error information. You can also call the addPublishStreamUrl method to publish Media Push again.
            • 5: The SDK is disconnecting from the Agora streaming server and CDN. When you call remove or stop to stop the streaming normally, the SDK reports the streaming state as DISCONNECTING, IDLE in sequence.
          • code: number

            The detailed error information:

            • 0: Media Push publishes successfully.
            • 1: Invalid argument used.
            • 2: The RTMP streams is encrypted and cannot be published.
            • 3: Timeout for Media Push. Call the addPublishStreamUrl to publish the stream again.
            • 4: An error occurs in Agora's streaming server. Call the addPublishStreamUrl to publish the stream again.
            • 5: An error occurs in the RTMP server.
            • 6: Media Push publishes too frequently.
            • 7: The host publishes more than 10 URLs. Delete the unnecessary URLs before adding new ones.
            • 8: The host manipulates other hosts' URLs. Check your app logic.
            • 9: Agora's server fails to find the RTMP stream.
            • 10: The format of the stream's URL address is not supported. Check whether the URL format is correct.
            • 11: The user role is not host, so the user cannot use the CDN live streaming function. Check your application code logic.
            • 13: The updateRtmpTranscoding or setLiveTranscoding method is called to update the transcoding configuration in a scenario where there is streaming without transcoding. Check your application code logic.
            • 14: Errors occurred in the host's network.
            • 15: Your App ID does not have permission to use the CDN live streaming function. Refer to Prerequisites to enable the CDN live streaming permission.
            • 100: The streaming has been stopped normally. After you call removePublishStreamUrl to stop streaming, the SDK returns this value.

          Returns void

    Returns this

  • Occurs when the publisher's transcoding is updated.

    When the LiveTranscoding class in the setLiveTranscoding method updates, the SDK triggers the transcodingUpdated 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 transcodingUpdated callback.

    Parameters

    • evt: "transcodingUpdated"
    • cb: function
        • (): void
        • Returns void

    Returns this

  • Occurs when a voice or video stream URL address is added to a live broadcast.

    warning

    Agora will soon stop the service for injecting online media streams on the client. If you have not implemented this service, Agora recommends that you do not use it.

    • url: The URL address of the externally injected stream.
    • uid: User ID.
    • status: State of the externally injected stream:
      • 0: The external video stream imported successfully.
      • 1: The external video stream already exists.
      • 2: The external video stream to be imported is unauthorized.
      • 3: Import external video stream timeout.
      • 4: Import external video stream failed.
      • 5: The external video stream stopped importing successfully.
      • 6: No external video stream is found.
      • 7: No external video stream is found.
      • 8: Stop importing external video stream timeout.
      • 9: Stop importing external video stream failed.
      • 10: The external video stream is corrupted.

    Parameters

    • evt: "streamInjectStatus"
    • cb: function
        • (url: string, uid: number, status: number): void
        • Parameters

          • url: string
          • uid: number
          • status: number

          Returns void

    Returns this

  • Occurs when the locally published media stream falls back to an audio-only stream due to poor network conditions or switches back to the video after the network conditions improve.

    If you call setLocalPublishFallbackOption and set option as AUDIO_ONLY(2), the SDK triggers this callback when the locally published stream falls back to audio-only mode due to poor uplink conditions, or when the audio stream switches back to the video after the uplink network condition improves.

    • isFallbackOrRecover: Whether the locally published stream falls back to audio-only or switches back to the video:
      • true: The locally published stream falls back to audio-only due to poor network conditions.
      • false: The locally published stream switches back to the video after the network conditions improve.

    Parameters

    • evt: "localPublishFallbackToAudioOnly"
    • cb: function
        • (isFallbackOrRecover: boolean): void
        • Parameters

          • isFallbackOrRecover: boolean

          Returns void

    Returns this

  • Occurs when the remote media stream falls back to audio-only stream due to poor network conditions or switches back to the video stream after the network conditions improve.

    If you call setRemoteSubscribeFallbackOption and set option as AUDIO_ONLY(2), the SDK triggers this callback when the remotely subscribed media stream falls back to audio-only mode due to poor uplink conditions, or when the remotely subscribed media stream switches back to the video after the uplink network condition improves.

    Parameters

    • evt: "remoteSubscribeFallbackToAudioOnly"
    • cb: function
        • (uid: number, isFallbackOrRecover: boolean): void
        • Parameters

          • uid: number

            ID of the remote user sending the stream.

          • isFallbackOrRecover: boolean

            Whether the remote media stream falls back to audio-only or switches back to the video:

            • true: The remote media stream falls back to audio-only due to poor network conditions.
            • false: The remote media stream switches back to the video stream after the network conditions improved.

          Returns void

    Returns this

  • deprecated

    This callback is deprecated. Use the localAudioStateChanged callback instead.

    Occurs when the microphone is enabled/disabled.

    • enabled: Whether the microphone is enabled/disabled:
      • true: Enabled.
      • false: Disabled.

    Parameters

    • evt: "microphoneEnabled"
    • cb: function
        • (enabled: boolean): void
        • Parameters

          • enabled: boolean

          Returns void

    Returns this

  • Occurs when the connection state between the SDK and the server changes.

    Parameters

    Returns this

  • Occurs when the local network type changes.

    When the network connection is interrupted, this callback indicates whether the interruption is caused by a network type change or poor network conditions.

    Parameters

    Returns this

  • Occurs when the local user successfully registers a user account by calling the registerLocalUserAccount method. This callback reports the user ID and user account of the local user.

    • uid: The ID of the local user.
    • userAccount: The user account of the local user.

    Parameters

    • evt: "localUserRegistered"
    • cb: function
        • (uid: number, userAccount: string): void
        • Parameters

          • uid: number
          • userAccount: string

          Returns void

    Returns this

  • Occurs when the SDK gets the user ID and user account of the remote user.

    After a remote user joins the channel, the SDK gets the UID and user account of the remote user, caches them in a mapping table object (UserInfo), and triggers this callback on the local client.

    • uid: The ID of the remote user.
    • userInfo: The UserInfo Object that contains the user ID and user account of the remote user.

    Parameters

    • evt: "userInfoUpdated"
    • cb: function
        • (uid: number, userInfo: UserInfo): void
        • Parameters

          Returns void

    Returns this

  • Occurs when the local video 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.

    The SDK triggers the LocalVideoStateChanged(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 LocalVideoStateChanged(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 Windows 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.

    Parameters

    Returns this

  • 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 you to troubleshoot issues when exceptions occur.

    Parameters

    Returns this

  • Occurs when the remote audio state changes.

    This callback indicates the state change of the remote audio stream.

    Parameters

    Returns this

  • Occurs when the state of the media stream relay changes.

    The SDK reports the state of the current media relay and possible error messages in this callback.

    Parameters

    Returns this

  • Reports events during the media stream relay.

    Parameters

    Returns this

  • Receives the media metadata.

    After the sender sends the media metadata by calling the sendMetadata method and the receiver receives the media metadata, the SDK triggers this callback and reports the metadata to the receiver.

    Parameters

    • evt: "receiveMetadata"
    • cb: function
        • Parameters

          • metadata: Metadata

            The media metadata.

          Returns void

    Returns this

  • Sends the media metadata successfully.

    After the sender sends the media metadata successfully by calling the sendMetadata method, the SDK triggers this calback to reports the media metadata to the sender.

    Parameters

    • evt: "sendMetadataSuccess"
    • cb: function
        • Parameters

          • metadata: Metadata

            The media metadata.

          Returns void

    Returns this

  • Occurs when the first audio frame is published.

    since

    v3.2.0

    The SDK triggers this callback under one of the following circumstances:

    Parameters

    • evt: "firstLocalAudioFramePublished"
    • cb: function
        • (elapsed: number): void
        • Parameters

          • elapsed: number

            The time elapsed (ms) from the local client calling joinChannel until the SDK triggers this callback.

          Returns void

    Returns this

  • Occurs when the first video frame is published.

    since

    v3.2.0

    The SDK triggers this callback under one of the following circumstances:

    Parameters

    • evt: "firstLocalVideoFramePublished"
    • cb: function
        • (elapsed: number): void
        • Parameters

          • elapsed: number

            The time elapsed (ms) from the local client calling joinChannel until the SDK triggers this callback.

          Returns void

    Returns this

  • Reports events during the RTMP or RTMPS streaming.

    since

    v3.2.0

    Parameters

    • evt: "rtmpStreamingEvent"
    • cb: function

    Returns this

  • Occurs when the audio publishing state changes.

    since

    v3.2.0

    This callback indicates the publishing state change of the local audio stream.

    Parameters

    • evt: "audioPublishStateChanged"
    • cb: function

    Returns this

  • Occurs when the video publishing state changes.

    since

    v3.2.0

    This callback indicates the publishing state change of the local video stream.

    Parameters

    • evt: "videoPublishStateChanged"
    • cb: function

    Returns this

  • Occurs when the audio subscribing state changes.

    since

    v3.2.0

    This callback indicates the subscribing state change of a remote audio stream.

    Parameters

    • evt: "audioSubscribeStateChanged"
    • cb: function
        • Parameters

          • channel: string

            The channel name.

          • uid: number

            The ID of the remote user.

          • oldState: STREAM_SUBSCRIBE_STATE

            The previous subscribing state.

          • newState: STREAM_SUBSCRIBE_STATE

            The current subscribing state.

          • elapseSinceLastState: number

            The time elapsed (ms) from the previous state to the current state.

          Returns void

    Returns this

  • Occurs when the video subscribing state changes.

    since

    v3.2.0

    This callback indicates the subscribing state change of a remote video stream.

    Parameters

    • evt: "videoSubscribeStateChanged"
    • cb: function
        • Parameters

          • channel: string

            The channel name.

          • uid: number

            The ID of the remote user.

          • oldState: STREAM_SUBSCRIBE_STATE

            The previous subscribing state.

          • newState: STREAM_SUBSCRIBE_STATE

            The current subscribing state.

          • elapseSinceLastState: number

            The time elapsed (ms) from the previous state to the current state.

          Returns void

    Returns this

  • Reserved callback.

    Parameters

    • evt: "uploadLogResult"
    • cb: function
        • (requestId: string, success: boolean, reason: number): void
        • Parameters

          • requestId: string
          • success: boolean
          • reason: number

          Returns void

    Returns this

  • Reports whether the virtual background is successfully enabled. (beta function)

    since

    v3.4.5

    After you call enableVirtualBackground, the SDK triggers this callback to report whether the virtual background is successfully enabled.

    note

    If the background image customized in the virtual background is in PNG or JPG format, the triggering of this callback is delayed until the image is read.

    Parameters

    Returns this

  • Reports the voice pitch of the local user.

    since

    v3.7.0

    After the local audio capture is enabled, and you call enableLocalVoicePitchCallback , the SDK triggers this callback at the time interval set in enableLocalVoicePitchCallback.

    note

    After this callback is enabled, if the user disables the local audio capture, for example, by calling enableLocalAudio(false), the SDK immediately stops sending the localVoicePitchInHz callback.

    Parameters

    • evt: "localVoicePitchInHz"
    • cb: function
        • (pitchInHz: number): void
        • Parameters

          • pitchInHz: number

            The voice pitch (Hz) of the local user.

          Returns void

    Returns this

  • Occurs when the user role switch fails in the interactive live streaming.

    since

    v3.7.0

    In the LIVE_BROADCASTING channel profile, when the local user calls setClientRole to switch their user role after joining the channel but the switch fails, the SDK triggers this callback to report the reason for the failure and the current user role.

    Parameters

    Returns this

  • Reports the proxy connection state.

    since

    v3.7.0

    You can use this callback to listen for the state of the SDK connecting to a proxy. For example, when a user calls setCloudProxy and joins a channel successfully, the SDK triggers this callback to report the user ID, the proxy type connected, and the time elapsed from the user calling joinChannel until this callback is triggered.

    Parameters

    • evt: "proxyConnected"
    • cb: function
        • (channel: string, uid: number, proxyType: PROXY_TYPE, localProxyIp: string, elapsed: number): void
        • Parameters

          • channel: string

            The channel name.

          • uid: number

            The user ID.

          • proxyType: PROXY_TYPE

            The proxy type connected. See PROXY_TYPE.

          • localProxyIp: string

            Reserved for future use.

          • elapsed: number

            The time elapsed (ms) from the user calling joinChannel until this callback is triggered.

          Returns void

    Returns this

  • Parameters

    • evt: "agoraVideoRawData"
    • cb: function
        • (info: object): void
        • Parameters

          • info: object
            • channelId: string
            • header: any
            • type: number
            • udata: Uint8Array
            • uid: number
            • vdata: Uint8Array
            • ydata: Uint8Array

          Returns void

    Returns this

  • Parameters

    • evt: string
    • listener: Function

    Returns this

pauseAllChannelMediaRelay

  • pauseAllChannelMediaRelay(): number
  • Pauses the media stream relay to all destination channels.

    since

    v3.6.1.4

    After the cross-channel media stream relay starts, you can call this method to pause relaying media streams to all destination channels; after the pause, if you want to resume the relay, call resumeAllChannelMediaRelay.

    After a successful method call, the SDK triggers the channelMediaRelayEvent callback to report whether the media stream relay is successfully paused.

    note

    Call this method after the startChannelMediaRelay method.

    Returns number

    • 0: Success.
    • < 0: Failure.

pauseAllEffects

  • pauseAllEffects(): number
  • Pauses all the audio effects.

    Returns number

    • 0: Success.
    • < 0: Failure.

pauseAudio

  • pauseAudio(): number
  • deprecated

    This method is deprecated. Use disableAudio instead. Disables the audio function in the channel.

    Returns number

    • 0: Success.
    • < 0: Failure.

pauseAudioMixing

  • pauseAudioMixing(): number
  • Pauses playing and mixing the music file.

    Call this API when you are in a channel.

    Returns number

    • 0: Success.
    • < 0: Failure.

pauseEffect

  • pauseEffect(soundId: number): number
  • Pauses a specified audio effect.

    Parameters

    • soundId: number

      ID of the audio effect. Each audio effect has a unique ID.

    Returns number

    • 0: Success.
    • < 0: Failure.

playEffect

  • playEffect(soundId: number, filePath: string, loopcount: number, pitch: number, pan: number, gain: number, publish: boolean, startPos?: undefined | number): number
  • Plays a specified local or online audio effect file.

    To play multiple audio effect files at the same time, call this method multiple times with different soundId and filePath values. For the best user experience, Agora recommends playing no more than three audio effect files at the same time.

    After completing playing an audio effect file, the SDK triggers the audioEffectFinished callback.

    note

    Call this method after joining a channel.

    Parameters

    • soundId: number

      Audio effect ID. The ID of each audio effect file is unique. If you preloaded an audio effect into memory by calling preloadEffect, ensure that this parameter is set to the same value as in preloadEffect.

    • filePath: string

      The absolute path or URL address (including the filename extensions) of the music file. For example: C:\music\audio.mp4. Supported audio formats include MP3, AAC, M4A, MP4, WAV, and 3GP. For more information, see Supported Media Formats in Media Foundation. If you preloaded an audio effect into memory by calling preloadEffect, ensure that this parameter is set to the same value as in preloadEffect.

    • loopcount: number

      The number of times the audio effect loops:

      • ≥ 0: The number of loops. For example, 1 means loop one time, which means play the audio effect two times in total.
      • -1: Play the audio effect in an indefinite loop.
    • pitch: number

      The pitch of the audio effect. The range is 0.5 to 2.0. The default value is 1.0, which means the original pitch. The lower the value, the lower the pitch.

    • pan: number

      The spatial position of the audio effect. The range is -1.0 to 1.0. For example:

      • -1.0: The audio effect occurs on the left.
      • 0.0: The audio effect occurs in the front.
      • 1.0: The audio effect occurs on the right.
    • gain: number

      The volume of the audio effect. The range is 0.0 to 100.0. The default value is 100.0, which means the original volume. The smaller the value, the less the gain.

    • publish: boolean

      Whether to publish the audio effect to the remote users:

      • true: Publish. Both the local user and remote users can hear the audio effect.
      • false: Do not publish. Only the local user can hear the audio effect.
    • Optional startPos: undefined | number

      The playback position (ms) of the audio effect file.

    Returns number

    • 0: Success.
    • < 0: Failure.

preloadEffect

  • preloadEffect(soundId: number, filePath: string): number
  • Preloads a specified audio effect file into the memory.

    To ensure smooth communication, limit the size of the audio effect file. We recommend using this method to preload the audio effect before calling the joinChannel method.

    Supported audio formats: mp3, aac, m4a, 3gp, and wav.

    Note: This method does not support online audio effect files.

    Parameters

    • soundId: number

      ID of the audio effect. Each audio effect has a unique ID.

    • filePath: string

      The absolute path of the audio effect file.

    Returns number

    • 0: Success.
    • < 0: Failure.

rate

  • rate(callId: string, rating: number, desc: string): number
  • Allows a user to rate a call after the call ends.

    Parameters

    • callId: string

      The ID of the call, retrieved from the getCallId method.

    • rating: number

      Rating of the call. The value is between 1 (lowest score) and 5 (highest score).

    • desc: string

      (Optional) The description of the rating, with a string length of less than 800 bytes.

    Returns number

    • 0: Success.
    • < 0: Failure.

registerLocalUserAccount

  • registerLocalUserAccount(appId: string, userAccount: string): number
  • Registers a user account. Once registered, the user account can be used to identify the local user when the user joins the channel. After the user successfully registers a user account, the SDK triggers the onLocalUserRegistered callback on the local client, reporting the user ID and user account of the local user.

    To join a channel with a user account, you can choose either of the following:

    The difference between the two is that for the former, the time elapsed between calling the joinChannelWithUserAccount method and joining the channel is shorter than the latter.

    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.

    Note:

    • Ensure that you set the userAccount parameter. Otherwise, this method does not take effect.
    • Ensure that the value of the userAccount parameter is unique in the channel.

    Parameters

    • appId: string

      The App ID of your project.

    • userAccount: string

      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. Ensure that you set this parameter 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: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".

    Returns number

    • 0: Success.
    • < 0: Failure.

registerMediaMetadataObserver

  • registerMediaMetadataObserver(): number
  • Registers a media metadata observer.

    Returns number

    • 0: Success.
    • < 0: Failure.

release

  • release(sync?: boolean): number
  • Releases the AgoraRtcEngine instance.

    Once the App calls this method to release the created AgoraRtcEngine instance, no other methods in the SDK can be used and no callbacks can occur. To start it again, initialize initialize to establish a new AgoraRtcEngine instance.

    Note: Call this method in the subthread.

    Parameters

    • Default value sync: boolean = false

    Returns number

    • 0: Success.
    • < 0: Failure.

removeInjectStreamUrl

  • removeInjectStreamUrl(url: string): number
  • Removes the injected online media stream from a live streaming.

    warning

    Agora will soon stop the service for injecting online media streams on the client. If you have not implemented this service, Agora recommends that you do not use it.

    Parameters

    • url: string

      HTTP/HTTPS URL address of the added stream to be removed.

    Returns number

    • 0: Success.
    • < 0: Failure.

removePublishStreamUrl

  • removePublishStreamUrl(url: string): number
  • Removes an RTMP stream from the CDN.

    note
    • Only the host in the 1 (live streaming) profile can call this method.
    • 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.

    Parameters

    • url: string

      The RTMP URL address to be removed. The maximum length of this parameter is 1024 bytes.

    Returns number

    • 0: Success.
    • < 0: Failure.

removeVideoRenderFromHighFPS

  • removeVideoRenderFromHighFPS(uid: number): void
  • Removes a stream from the high frame rate stream. Streams removed from the high frame rate stream will be controlled by the setVideoRenderFPS method.

    Parameters

    • uid: number

      The User ID.

    Returns void

renewToken

  • renewToken(newtoken: string): number
  • Renews the token when the current token expires.

    The key expires after a certain period of time once the Token schema is enabled when:

    • The onError callback reports the ERR_TOKEN_EXPIRED(109) error, or
    • The requestChannelKey callback reports the ERR_TOKEN_EXPIRED(109) error, or
    • The user receives the tokenPrivilegeWillExpire callback.

    The app should retrieve a new token from the server and then call this method to renew it. Failure to do so results in the SDK disconnecting from the server.

    Parameters

    • newtoken: string

      The new token.

    Returns number

    • 0: Success.
    • < 0: Failure.

resizeRender

  • resizeRender(key: "local" | "videosource" | number, channelId: string | undefined): void
  • Resizes the renderer.

    When the size of the view changes, this method refresh the zoom level so that video is sized appropriately while waiting for the next video frame to arrive.

    Calling this method prevents a view discontinutity.

    Parameters

    • key: "local" | "videosource" | number

      Key for the map that store the renderers, e.g, uid or videosource or local.

    • channelId: string | undefined

    Returns void

resumeAllChannelMediaRelay

  • resumeAllChannelMediaRelay(): number
  • Resumes the media stream relay to all destination channels.

    since

    v3.6.1.4

    After calling the pauseAllChannelMediaRelay method, you can call this method to resume relaying media streams to all destination channels.

    After a successful method call, the SDK triggers the channelMediaRelayEvent callback to report whether the media stream relay is successfully resumed.

    note

    Call this method after the pauseAllChannelMediaRelay method.

    Returns number

    • 0: Success.
    • < 0: Failure.

resumeAllEffects

  • resumeAllEffects(): number
  • Resumes playing all audio effects.

    Returns number

    • 0: Success.
    • < 0: Failure.

resumeAudio

  • resumeAudio(): number
  • deprecated

    This method is deprecated. Use enableAudio instead. Resumes the audio function in the channel.

    Returns number

    • 0: Success.
    • < 0: Failure.

resumeAudioMixing

  • resumeAudioMixing(): number
  • Resumes playing and mixing the music file.

    Call this API when you are in a channel.

    Returns number

    • 0: Success.
    • < 0: Failure.

resumeEffect

  • resumeEffect(soundId: number): number
  • Resumes playing a specified audio effect.

    Parameters

    • soundId: number

      sound id

    Returns number

    • 0: Success.
    • < 0: Failure.

selectAudioTrack

  • selectAudioTrack(index: number): number
  • Specifies the playback track of the current music file.

    since

    v3.6.1.4

    After getting the audio track index of the current music file, call this method to specify any audio track to play. For example, if different tracks of a multitrack file store songs in different languages, you can call this method to set the language of the music file to play.

    note

    Parameters

    • index: number

      The specified playback track. This parameter must be less than or equal to the return value of getAudioTrackCount.

    Returns number

    • 0: Success.
    • < 0: Failure.

sendCustomReportMessage

  • sendCustomReportMessage(id: string, category: string, event: string, label: string, value: number): number
  • Agora supports reporting and analyzing customized messages.

    since

    v3.2.0

    This function is in the beta stage with a free trial. The ability provided in its beta test version is reporting a maximum of 10 message pieces within 6 seconds, with each message piece not exceeding 256 bytes and each string not exceeding 100 bytes.

    To try out this function, contact support@agora.io and discuss the format of customized messages with us.

    Parameters

    • id: string
    • category: string
    • event: string
    • label: string
    • value: number

    Returns number

sendMetadata

  • sendMetadata(metadata: Metadata): number
  • Sends the media metadata.

    After calling the registerMediaMetadataObserver method, you can call the setMetadata method to send the media metadata.

    If it is a successful sending, the sender receives the sendMetadataSuccess callback, and the receiver receives the receiveMetadata callback.

    Parameters

    • metadata: Metadata

      The media metadata.

    Returns number

    • 0: Success.
    • < 0: Failure.

sendStreamMessage

  • sendStreamMessage(streamId: number, msg: string): number
  • Sends data stream messages to all users in a channel.

    The SDK has the following restrictions on this method:

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

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

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

    note

    This method applies only to the communication(0) profile or to the hosts in the 1 (live streaming) profile. If an audience in the 1 (live streaming) profile calls this method, the audience may be switched to a host.

    Parameters

    • streamId: number

      ID of the sent data stream, returned in the createDataStream method.

    • msg: string

      Data to be sent.

    Returns number

    • 0: Success.
    • < 0: Failure.

setAddonLogFile

  • setAddonLogFile(filepath: string): number
  • Specifies an SDK output log file.

    The log file records all log data for the SDK’s operation. Ensure that the directory for the log file exists and is writable.

    Parameters

    • filepath: string

      File path of the log file. The string of the log file is in UTF-8.

    Returns number

    • 0: Success.
    • < 0: Failure.

setAudioEffectParameters

  • setAudioEffectParameters(preset: AUDIO_EFFECT_PRESET, param1: number, param2: number): number
  • Sets parameters for SDK preset audio effects.

    since

    v3.2.0

    Call this method to set the following parameters for the local user who send an audio stream:

    • 3D voice effect: Sets the cycle period of the 3D voice effect.
    • Pitch correction effect: Sets the basic mode and tonic pitch of the pitch correction effect. Different songs have different modes and tonic pitches. Agora recommends bounding this method with interface elements to enable users to adjust the pitch correction interactively.

    After setting parameters, all users in the channel can hear the relevant effect.

    You can call this method directly or after setAudioEffectPreset. If you call this method after setAudioEffectPreset, ensure that you set the preset parameter of setAudioEffectPreset to ROOM_ACOUSTICS_3D_VOICE or PITCH_CORRECTION and then call this method to set the same enumerator; otherwise, this method overrides setAudioEffectPreset.

    note

    Parameters

    • preset: AUDIO_EFFECT_PRESET

      The options for SDK preset audio effects:

      • 3D voice effect: ROOM_ACOUSTICS_3D_VOICE.
        • Call setAudioProfile and set the profile parameter to 3 or 5 before setting this enumerator; otherwise, the enumerator setting does not take effect.
        • If the 3D voice effect is enabled, users need to use stereo audio playback devices to hear the anticipated voice effect.
      • Pitch correction effect: PITCH_CORRECTION. To achieve better audio effect quality, Agora recommends calling setAudioProfile and setting the profile parameter to 4 or 5 before setting this enumerator.
    • param1: number
      • If you set preset to ROOM_ACOUSTICS_3D_VOICE, the param1 sets the cycle period of the 3D voice effect. The value range is [1,60] and the unit is a second. The default value is 10 seconds, indicating that the voice moves around you every 10 seconds.
      • If you set preset to PITCH_CORRECTION, param1 sets the basic mode of the pitch correction effect:
        • 1: (Default) Natural major scale.
        • 2: Natural minor scale.
        • 3: Japanese pentatonic scale.
    • param2: number
      • 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#
        • 3: B
        • 4: (Default) C
        • 5: C#
        • 6: D
        • 7: D#
        • 8: E
        • 9: F
        • 10: F#
        • 11: G
        • 12: G#

    Returns number

    • 0: Success.
    • < 0: Failure.

setAudioEffectPreset

  • Sets an SDK preset audio effect.

    since

    v3.2.0

    Call this method to set an SDK preset audio effect for the local user who sends an audio stream. This audio effect does not change the gender characteristics of the original voice. After setting an audio effect, all users in the channel can hear the effect.

    You can set different audio effects for different scenarios.

    To achieve better audio effect quality, Agora recommends calling setAudioProfile and setting the scenario parameter to 3 before calling this method.

    Note:

    Parameters

    Returns number

    • 0: Success.
    • < 0: Failure.

setAudioMixingDualMonoMode

  • Sets the channel mode of the current music file.

    since

    v3.6.1.4

    In a stereo music file, the left and right channels can store different audio data. According to your needs, you can set the channel mode to original mode, left channel mode, right channel mode, or mixed channel mode. For example, in the KTV scenario, the left channel of the music file stores the musical accompaniment, and the right channel stores the singing voice. If you only need to listen to the accompaniment, call this method to set the channel mode of the music file to left channel mode; if you need to listen to the accompaniment and the singing voice at the same time, call this method to set the channel mode to mixed channel mode.

    note
    • Call this method after calling startAudioMixing and receiving the audioMixingStateChanged (710) callback.
    • This method only applies to stereo audio files.

    Parameters

    Returns number

    • 0: Success.
    • < 0: Failure.

setAudioMixingPitch

  • setAudioMixingPitch(pitch: number): number
  • Sets the pitch of the local music file.

    since

    v3.2.0

    When a local music file is mixed with a local human voice, call this method to set the pitch of the local music file only.

    note

    Call this method after calling startAudioMixing.

    Parameters

    • pitch: number

      Sets the pitch of the local music file by chromatic scale. The default value is 0, which means keeping the original pitch. The value ranges from -12 to 12, and the pitch value between consecutive values is a chromatic value. The greater the absolute value of this parameter, the higher or lower the pitch of the local music file.

    Returns number

    • 0: Success.
    • < 0: Failure.

setAudioMixingPlaybackSpeed

  • setAudioMixingPlaybackSpeed(speed?: number): number
  • Sets the playback speed of the current music file.

    since

    v3.6.1.4

    note

    Call this method after calling startAudioMixing and receiving the audioMixingStateChanged (710) callback.

    Parameters

    • Default value speed: number = 100

      The playback speed. Agora recommends that you limit this value to between 50 and 400, defined as follows:

      • 50: Half the original speed.
      • 100: The original speed.
      • 400: 4 times the original speed.

    Returns number

    • 0: Success.
    • < 0: Failure.

setAudioMixingPosition

  • setAudioMixingPosition(position: number): number
  • Sets the playback position of the music file to a different starting position.

    This method drags the playback progress bar of the audio mixing file to where you want to play instead of playing it from the beginning.

    note

    Call this method after calling startAudioMixing and receiving the audioMixingStateChanged callback with the state code 710.

    Parameters

    • position: number

      The playback starting position (ms) of the music file.

    Returns number

    • 0: Success.
    • < 0: Failure.

setAudioPlaybackDevice

  • setAudioPlaybackDevice(deviceId: string): number
  • Sets the audio playback device using the device ID.

    Parameters

    • deviceId: string

      The device ID of the audio playback device.

    Returns number

    • 0: Success.
    • < 0: Failure.

setAudioPlaybackDeviceMute

  • setAudioPlaybackDeviceMute(mute: boolean): number
  • Mutes the audio playback device.

    Parameters

    • mute: boolean

      Sets whether to mute/unmute the audio playback device:

      • true: Mutes.
      • false: Unmutes.

    Returns number

    • 0: Success.
    • < 0: Failure.

setAudioPlaybackVolume

  • setAudioPlaybackVolume(volume: number): number
  • Sets the volume of the audio playback device.

    Parameters

    • volume: number

      Sets the volume of the audio playback device. The value ranges between 0 (lowest volume) and 255 (highest volume).

    Returns number

    • 0: Success.
    • < 0: Failure.

setAudioProfile

  • setAudioProfile(profile: 0 | 1 | 2 | 3 | 4 | 5, scenario: 0 | 1 | 2 | 3 | 4 | 5 | 8): number
  • Sets audio parameters and application scenarios.

    Note:

    • This method must be called before the joinChannel method.
    • In the communication(0) and 1 (live streaming) profiles, the bitrate may be different from your settings due to network self-adaptation.
    • In scenarios requiring high-quality audio, for example, a music teaching scenario, we recommend setting profile as 4 and scenario as 3.

    Parameters

    • profile: 0 | 1 | 2 | 3 | 4 | 5

      Sets the sample rate, bitrate, encoding mode, and the number of channels.

      • 0: Default audio profile.
        • For the 1 (live streaming) profile: A sample rate of 48 KHz, music encoding, mono, and a bitrate of up to 64 Kbps.
        • For the communication(0) profile:
          • macOS: A sample rate of 32 KHz, music encoding, mono, and a bitrate of up to 18 Kbps.
          • Windows: A sample rate of 16 KHz, music encoding, mono, and a bitrate of up to 16 Kbps.
      • 1: Speech standard. A sample rate of 32 kHz, audio encoding, mono, and a bitrate of up to 18 Kbps.
      • 2: Music standard. A sample rate of 48 kHz, music encoding, mono, and a bitrate of up to 48 Kbps.
      • 3: Music standard stereo. A sample rate of 48 kHz, music encoding, stereo, and a bitrate of up to 56 Kbps.
      • 4: Music high quality. A sample rate of 48 kHz, music encoding, mono, and a bitrate of up to 128 Kbps.
      • 5: Music high quality stereo. A sample rate of 48 kHz, music encoding, stereo, and a bitrate of up to 192 Kbps.
      • 6: IOT.
    • scenario: 0 | 1 | 2 | 3 | 4 | 5 | 8

      Sets the audio application scenario.

      • 0: (Default) Standard audio scenario.
      • 1: Entertainment scenario where users need to frequently switch the user role.
      • 2: Education scenario where users want smoothness and stability.
      • 3: High-quality audio chatroom scenario where hosts mainly play music.
      • 4: Showroom scenario where a single host wants high-quality audio.
      • 5: Gaming scenario for group chat that only contains the human voice.
      • 8: Meeting scenario that mainly contains the human voice.

      Under different audio scenarios, the device uses different volume types. For details, see What is the difference between the in-call volume and the media volume?.

    Returns number

    • 0: Success.
    • < 0: Failure.

setAudioRecordingDevice

  • setAudioRecordingDevice(deviceId: string): number
  • Sets the audio recording device using the device ID.

    Parameters

    • deviceId: string

      The device ID of the audio recording device.

    Returns number

    • 0: Success.
    • < 0: Failure.

setAudioRecordingDeviceMute

  • setAudioRecordingDeviceMute(mute: boolean): number
  • Mutes/Unmutes the microphone.

    Parameters

    • mute: boolean

      Sets whether to mute/unmute the audio playback device:

      • true: Mutes.
      • false: Unmutes.

    Returns number

    • 0: Success.
    • < 0: Failure.

setAudioRecordingVolume

  • setAudioRecordingVolume(volume: number): number
  • Sets the volume of the microphone.

    Parameters

    • volume: number

      Sets the volume of the microphone. The value ranges between 0 (lowest volume) and 255 (highest volume).

    Returns number

    • 0: Success.
    • < 0: Failure.

setBeautyEffectOptions

  • setBeautyEffectOptions(enable: boolean, options: BeautyOptions): number
  • Enables/Disables image enhancement and sets the options.

    since

    v3.0.0 for Windows

    since

    v3.2.0 for macOS

    note

    Call this method after calling the enableVideo method.

    Parameters

    • enable: boolean

      Sets whether or not to enable image enhancement:

      • true: Enables image enhancement.
      • false: Disables image enhancement.
    • options: BeautyOptions

      The image enhancement options. It contains the following parameters:

    Returns number

    • 0: Success.
    • < 0: Failure.

setCameraCapturerConfiguration

  • Sets the camera capturer configuration.

    For a video call or live streaming, generally the SDK controls the camera output parameters. When the default camera capture settings do not meet special requirements or cause performance problems, we recommend using this method to set the camera capture preference:

    • If the resolution or frame rate of the captured raw video data are higher than those set by 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 joinChannel, enableVideo, or enableLocalVideo, depending on which method you use to turn on your local camera.

    Parameters

    Returns number

    • 0: Success.
    • < 0: Failure.

setChannelProfile

  • setChannelProfile(profile: number): number
  • Sets the channel profile.

    The AgoraRtcEngine applies different optimization according to the app scenario.

    Note:

    • Call this method before the joinChannel method.
    • Users in the same channel must use the same channel profile.

    Parameters

    • profile: number

      The channel profile:

      • 0: for communication
      • 1: for live streaming
      • 2: for in-game

    Returns number

    • 0: Success.
    • < 0: Failure.

setClientRole

  • Sets the role of a user (live streaming only).

    This method sets the role of a user, such as a host or an audience (default), before joining a channel.

    This method can be used to switch the user role after a user joins a channel. In the 1 (live streaming)profile, when a user switches user roles after joining a channel, a successful setClientRole method call triggers the following callbacks:

    • The local client: clientRoleChanged
    • The remote client: userJoined

    Parameters

    Returns number

    • 0: Success.
    • < 0: Failure.

setClientRoleWithOptions

  • 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: clientRoleChanged.
    • The remote client: userJoined or userOffline.
    note
    • This method applies to the LIVE_BROADCASTING profile only.
    • The difference between this method and setClientRole is that this method can set the user level in addition to the user role.
      • The user role determines the permissions that the SDK grants to a user, such as permission to send local streams, receive remote streams, and push streams to a CDN address.
      • The user level determines the level of services that a user can enjoy within the permissions of the user's role. For example, an audience can choose to receive remote streams with low latency or ultra low latency. Levels affect prices.

    Parameters

    Returns number

    • 0: Success.
    • < 0: Failure.

setCloudProxy

  • Sets the Agora cloud proxy service.

    since

    v3.3.1

    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 type parameter as 1, which is the cloud proxy for the UDP protocol.

    After a successfully cloud proxy connection, the SDK triggers the connectionStateChanged(2, 11) callback.

    To disable the cloud proxy that has been set, call setCloudProxy(0). To change the cloud proxy type that has been set, call setCloudProxy(0) first, and then call setCloudProxy, and pass the value that you expect in type.

    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.

    Parameters

    Returns number

    • 0: Success.
    • < 0: Failure.
      • -2: The parameter is invalid.
      • -7: The SDK is not initialized.

setColorEnhanceOptions

  • Sets color enhancement.

    since

    v3.7.0

    The video images captured by the camera can have color distortion. The color enhancement feature intelligently adjusts video characteristics such as saturation and contrast to enhance the video color richness and color reproduction, making the video more vivid.

    You can call this method to enable the color enhancement feature and set the options of the color enhancement effect.

    note
    • Before calling this method, ensure that you have integrated the following dynamic library into your project:
      • macOS: AgoraVideoSegmentationExtension.xcframework
      • Windows: libagora_segmentation_extension.dll
    • Call this method after enableVideo.
    • The color enhancement feature has certain performance requirements on devices. If your device overheats after you enable color enhancement, Agora recommends modifying the color enhancement options to a less performance-consuming level or disabling color enhancement entirely.

    Parameters

    Returns number

    • 0: Success.
    • < 0: Failure.

setCustomRenderer

  • setCustomRenderer(customRenderer: IRenderer): void
  • Use this method to set custom Renderer when set renderMode in the setRenderMode method to 3. CustomRender should be a class.

    Parameters

    • customRenderer: IRenderer

      Customizes the video renderer.

    Returns void

setDefaultMuteAllRemoteAudioStreams

  • setDefaultMuteAllRemoteAudioStreams(mute: boolean): number
  • Stops or resumes subscribing to the audio streams of all remote users by default.

    deprecated

    This method is deprecated from v3.3.1.

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

    note

    If you need to resume subscribing to the audio streams of remote users in the channel after calling setDefaultMuteAllRemoteAudioStreams(true), do the following:

    • If you need to resume subscribing to the audio stream of a specified user, call muteRemoteAudioStream(false), and specify the user ID.
    • If you need to resume subscribing to the audio streams of multiple remote users, call muteRemoteAudioStream(false) multiple times.

    Parameters

    • mute: boolean

      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.

    Returns number

    • 0: Success.
    • < 0: Failure.

setDefaultMuteAllRemoteVideoStreams

  • setDefaultMuteAllRemoteVideoStreams(mute: boolean): number
  • Stops or resumes subscribing to the video streams of all remote users by default.

    deprecated

    This method is deprecated from v3.3.1.

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

    note

    If you need to resume subscribing to the video streams of remote users in the channel after calling setDefaultMuteAllRemoteVideoStreams(true), do the following:

    • If you need to resume subscribing to the video stream of a specified user, call muteRemoteVideoStream(false), and specify the user ID.
    • If you need to resume subscribing to the video streams of multiple remote users, call muteRemoteVideoStream(false) multiple times.

    Parameters

    • mute: boolean

      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.

    Returns number

    • 0: Success.
    • < 0: Failure.

setEffectPosition

  • setEffectPosition(soundId: number, pos: number): number
  • Sets the playback position of an audio effect file.

    since

    v3.4.2

    After a successful setting, the local audio effect file starts playing at the specified position.

    note

    Call this method after playEffect.

    Parameters

    • soundId: number

      Audio effect ID. Ensure that this parameter is set to the same value as in playEffect.

    • pos: number

      The playback position (ms) of the audio effect file.

    Returns number

    • 0: Success.
    • < 0: Failure.
      • -22: Cannot find the audio effect file. Please set a correct soundId.

setEffectsVolume

  • setEffectsVolume(volume: number): number
  • Sets the volume of the audio effects.

    Parameters

    • volume: number

      Sets the volume of the audio effects. The value ranges between 0 and 100 (default).

    Returns number

    • 0: Success.
    • < 0: Failure.

setEncryptionMode

  • setEncryptionMode(mode: string): number
  • Sets the built-in encryption mode.

    depercated

    This method is deprecated from v3.2.0. Use the enableEncryption method instead.

    The Agora SDK supports built-in encryption, which is set to aes-128-xts mode by default. Call this method to set the encryption mode to use other encryption modes. All users in the same channel must use the same encryption mode and password.

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

    Note: Call the setEncryptionSecret method before calling this method.

    Parameters

    • mode: string

      Sets the encryption mode:

      • "aes-128-xts": 128-bit AES encryption, XTS mode.
      • "aes-128-ecb": 128-bit AES encryption, ECB mode.
      • "aes-256-xts": 256-bit AES encryption, XTS mode.
      • "": When encryptionMode is set as null, the encryption is in “aes-128-xts” by default.

    Returns number

    • 0: Success.
    • < 0: Failure.

setEncryptionSecret

  • setEncryptionSecret(secret: string): number
  • deprecated

    This method is deprecated from v3.2.0. Use the enableEncryption method instead.

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

    All users in a channel must set the same encryption password. The encryption password is automatically cleared once a user has left the channel. If the encryption password is not specified or set to empty, the encryption function will be disabled.

    Note:

    • For optimal transmission, ensure that the encrypted data size does not exceed the original data size + 16 bytes. 16 bytes is the maximum padding size for AES encryption.
    • Do not use this method for Media Push.

    Parameters

    • secret: string

      Encryption Password

    Returns number

    • 0: Success.
    • < 0: Failure.

setHighQualityAudioParameters

  • setHighQualityAudioParameters(fullband: boolean, stereo: boolean, fullBitrate: boolean): number
  • deprecated

    This method is deprecated. Agora does not recommend using this method. Use setAudioProfile instead. Sets the high-quality audio preferences.

    Call this method and set all parameters before joining a channel.

    Parameters

    • fullband: boolean

      Sets whether to enable/disable full-band codec (48-kHz sample rate).

      • true: Enable full-band codec.
      • false: Disable full-band codec.
    • stereo: boolean

      Sets whether to enable/disable stereo codec.

      • true: Enable stereo codec.
      • false: Disable stereo codec.
    • fullBitrate: boolean

      Sets whether to enable/disable high-bitrate mode.

      • true: Enable high-bitrate mode.
      • false: Disable high-bitrate mode.

    Returns number

    • 0: Success.
    • < 0: Failure.

setLiveTranscoding

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

    The SDK triggers the otranscodingUpdated callback when you call the setLiveTranscoding method to update the LiveTranscoding class.

    note
    • Only the host in the Live-broadcast porfile can call this method.
    • Ensure that you enable the Media Push service before using this function. See Prerequisites in the Media Push guide.
    • If you call the setLiveTranscoding method to set the LiveTranscoding class for the first time, the SDK does not trigger the transcodingUpdated callback.

    Parameters

    Returns number

    • 0: Success.
    • < 0: Failure.

setLocalAccessPoint

setLocalPublishFallbackOption

  • setLocalPublishFallbackOption(option: 0 | 1 | 2): number
  • Sets the fallback option for the locally published video stream based on the network conditions.

    The default setting for option is STREAM_FALLBACK_OPTION_AUDIO_ONLY (2), where there is no fallback for the locally published video stream when the uplink network conditions are poor. If option is set to STREAM_FALLBACK_OPTION_AUDIO_ONLY (2), the SDK will:

    • Disable the upstream video but enable audio only when the network conditions worsen and cannot support both video and audio.
    • Re-enable the video when the network conditions improve. When the locally published stream falls back to audio only or when the audio stream switches back to the video, the localPublishFallbackToAudioOnly callback is triggered.
    note

    Agora does not recommend using this method for Media Push, because the CDN audience will have a noticeable lag when the locally publish stream falls back to audio-only.

    Parameters

    • option: 0 | 1 | 2

      Sets the fallback option for the locally published video stream.

      • STREAM_FALLBACK_OPTION_DISABLED (0): (Default) No fallback behavior for the local/remote video stream when the uplink/downlink network conditions are poor. The quality of the stream is not guaranteed.
      • STREAM_FALLBACK_OPTION_VIDEO_STREAM_LOW (1): (Default) The remote video stream falls back to the low-stream video when the downlink network condition worsens. This option works not for the setLocalPublishFallbackOption method.
      • STREAM_FALLBACK_OPTION_AUDIO_ONLY (2): Under poor uplink network conditions, the locally published video stream falls back to audio only.

    Returns number

    • 0: Success.
    • < 0: Failure.

setLocalVoiceChanger

setLocalVoiceEqualization

  • setLocalVoiceEqualization(bandFrequency: number, bandGain: number): number
  • Sets the local voice equalization effect.

    Parameters

    • bandFrequency: number

      Sets the index of the band center frequency. The value ranges between 0 and 9, representing the respective band center frequencies of the voice effects including 31, 62, 125, 500, 1k, 2k, 4k, 8k, and 16kHz.

    • bandGain: number

      Sets the gain (dB) of each band. The value ranges between -15 and 15. The default value is 0.

    Returns number

    • 0: Success.
    • < 0: Failure.

setLocalVoicePitch

  • setLocalVoicePitch(pitch: number): number
  • Changes the voice pitch of the local speaker.

    Parameters

    • pitch: number

      The value ranges between 0.5 and 2.0. The lower the value, the lower the voice pitch. The default value is 1.0 (no change to the local voice pitch).

    Returns number

    • 0: Success.
    • < 0: Failure.

setLocalVoiceReverb

  • setLocalVoiceReverb(reverbKey: number, value: number): number
  • Sets the local voice reverberation.

    Parameters

    • reverbKey: number

      Sets the audio reverberation key.

      • 0: Level (dB) of the dry signal. The value ranges between -20 and 10.
      • 1: Level (dB) of the early reflection signal (wet signal). The value ranges between -20 and 10.
      • 2: Room size of the reflection. A larger room size means a stronger reverbration. The value ranges between 0 and

      100.

      • 3: Length (ms) of the initial delay of the wet signal. The value ranges between 0 and 200.
      • 4: The reverberation strength. The value ranges between 0 and 100.
    • value: number

      Sets the effect of the reverberation key. See reverbKey for the value range.

    Returns number

    • 0: Success.
    • < 0: Failure.

setLocalVoiceReverbPreset

setLogFile

  • setLogFile(filepath: string): number
  • Specifies an SDK output log file.

    deprecated

    This method is deprecated from v3.3.1. Use logConfig in the initialize method instead.

    Parameters

    • filepath: string

      File path of the log file. The string of the log file is in UTF-8.

    Returns number

    • 0: Success.
    • < 0: Failure.

setLogFileSize

  • setLogFileSize(size: number): number
  • Sets the size of a log file that the SDK outputs.

    deprecated

    This method is deprecated from v3.3.1. Use logConfig in the initialize method instead.

    note

    If you want to set the log file size, ensure that you call this method before setLogFile, or the logs are cleared.

    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 create a new agorasdk.log to record latest logs.

    Related APIs:

    Parameters

    • size: number

      The size (KB) of a log file. The default value is 1024 KB. If you set size to 1024 KB, the SDK outputs at most 5 MB log files; if you set it to less than 1024 KB, the maximum size of a log file is still 1024 KB.

    Returns number

    • 0: Success.
    • < 0: Failure.

setLogFilter

  • setLogFilter(filter: number): number
  • Sets the output log level of the SDK.

    deprecated

    This method is deprecated from v3.3.1. Use logConfig in the initialize method instead.

    You can use one or a combination of the filters. The log level follows the sequence of OFF, CRITICAL, ERROR, WARNING, INFO, and DEBUG. Choose a level to see the logs preceding that level. For example, if you set the log level to WARNING, you see the logs within levels CRITICAL, ERROR, and WARNING.

    Parameters

    • filter: number

      Sets the filter level:

      • 0: Do not output any log.
      • 0x080f: Output all the API logs. Set your log filter as DEBUG if you want to get the most complete log file.
      • 0x000f: Output logs of the CRITICAL, ERROR, WARNING and INFO level. We recommend setting your log filter as this level.
      • 0x000e: Output logs of the CRITICAL, ERROR and WARNING level.
      • 0x000c: Output logs of the CRITICAL and ERROR level.
      • 0x0008: Output logs of the CRITICAL level.

    Returns number

    • 0: Success.
    • < 0: Failure.

setLowlightEnhanceOptions

  • Sets low-light enhancement.

    since

    v3.7.0

    The low-light enhancement feature can adaptively adjust the brightness value of the video captured in situations with low or uneven lighting, such as backlit, cloudy, or dark scenes. It restores or highlights the image details and improves the overall visual effect of the video.

    You can call this method to enable the low-light enhancement feature and set the options of the low-light enhancement effect.

    note
    • Before calling this method, ensure that you have integrated the following dynamic library into your project:
      • macOS: AgoraVideoSegmentationExtension.xcframework
      • Windows: libagora_segmentation_extension.dll
    • Call this method after enableVideo.
    • The low-light enhancement feature has certain performance requirements on devices. If your device overheats after you enable low-light enhancement, Agora recommends modifying the low-light enhancement options to a less performance-consuming level or disabling low-light enhancement entirely.

    Parameters

    Returns number

    • 0: Success.
    • < 0: Failure.

setMaxMetadataSize

  • setMaxMetadataSize(size: number): number
  • Sets the maximum size of the media metadata.

    After calling the registerMediaMetadataObserver method, you can call the setMaxMetadataSize method to set the maximum size.

    Parameters

    • size: number

      The maximum size of your metadata.

    Returns number

    • 0: Success.
    • < 0: Failure.

setParameters

  • setParameters(param: string): number
  • Provides technical preview functionalities or special customizations by configuring the SDK with JSON options.

    The JSON options are not public by default. Agora is working on making commonly used JSON options public in a standard way.

    Parameters

    • param: string

      The parameter as a JSON string in the specified format.

    Returns number

    • 0: Success.
    • < 0: Failure.

setPauseRenderer

  • setPauseRenderer(pause?: boolean): void
  • Parameters

    • Default value pause: boolean = false

    Returns void

setProcessDpiAwareness

  • setProcessDpiAwareness(): number
  • Returns number

setRecordingAudioFrameParameters

  • setRecordingAudioFrameParameters(sampleRate: number, channel: 1 | 2, mode: 0 | 1 | 2, samplesPerCall: number): number
  • Parameters

    • sampleRate: number
    • channel: 1 | 2
    • mode: 0 | 1 | 2
    • samplesPerCall: number

    Returns number

setRemoteDefaultVideoStreamType

  • setRemoteDefaultVideoStreamType(streamType: StreamType): number
  • Sets the default video-stream type of the remotely subscribed video stream when the remote user sends dual streams.

    Parameters

    • streamType: StreamType

      Sets the video stream type:

      • 0: High-stream video, the high-resolution, high-bitrate video.
      • 1: Low-stream video, the low-resolution, low-bitrate video.

    Returns number

    • 0: Success.
    • < 0: Failure.

setRemoteSubscribeFallbackOption

  • setRemoteSubscribeFallbackOption(option: 0 | 1 | 2): number
  • Sets the fallback option for the remote video stream based on the network conditions.

    If option is set as STREAM_FALLBACK_OPTION_VIDEO_STREAM_LOW (1) or STREAM_FALLBACK_OPTION_AUDIO_ONLY (2):

    • the SDK automatically switches the video from a high-stream to a low-stream, or disables the video when the downlink network condition cannot support both audio and video to guarantee the quality of the audio.
    • The SDK monitors the network quality and restores the video stream when the network conditions improve.

    When the remote video stream falls back to audio only or when the audio-only stream switches back to the video stream, the SDK triggers the remoteSubscribeFallbackToAudioOnly callback.

    Parameters

    • option: 0 | 1 | 2

      Sets the fallback option for the remote stream.

      • STREAM_FALLBACK_OPTION_DISABLED (0): No fallback behavior for the local/remote video stream when the uplink/downlink network conditions are poor. The quality of the stream is not guaranteed.
      • STREAM_FALLBACK_OPTION_VIDEO_STREAM_LOW (1): (Default) The remote video stream falls back to the low-stream video when the downlink network condition worsens. This option works only for this method and not for the setLocalPublishFallbackOption method.
      • STREAM_FALLBACK_OPTION_AUDIO_ONLY (2): Under poor downlink network conditions, the remote video stream first falls back to the low-stream video; and then to an audio-only stream if the network condition worsens.

    Returns number

    • 0: Success.
    • < 0: Failure.

setRemoteUserPriority

  • setRemoteUserPriority(uid: number, priority: Priority): number
  • Sets the priority of a remote user's media stream.

    Use this method with the setRemoteSubscribeFallbackOption method. If the fallback function is enabled for a subscribed stream, the SDK ensures the high-priority user gets the best possible stream quality.

    Note: The Agora SDK supports setting userPriority as high for one user only.

    Parameters

    • uid: number

      The ID of the remote user.

    • priority: Priority

      The priority of the remote user. See Priority.

    Returns number

    • 0: Success.
    • < 0: Failure.

setRemoteUserSpatialAudioParams

  • setRemoteUserSpatialAudioParams(uid: number, spatial_audio_params?: SpatialAudioParams): number

setRemoteVideoStreamType

  • setRemoteVideoStreamType(uid: number, streamType: StreamType): number
  • Sets the stream type of the remote video.

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

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

    The aspect ratio of the low-video stream is the same as the high-video stream. Once the resolution of the high-video stream is set, the system automatically sets the resolution, frame rate, and bitrate of the low-video stream. The SDK reports the result of calling this method in the apiCallExecuted callback.

    Parameters

    • uid: number

      ID of the remote user sending the video stream.

    • streamType: StreamType

      Sets the video stream type:

      • 0: High-stream video, the high-resolution, high-bitrate video.
      • 1: Low-stream video, the low-resolution, low-bitrate video.

    Returns number

    • 0: Success.
    • < 0: Failure.

setRemoteVoicePosition

  • setRemoteVoicePosition(uid: number, pan: number, gain: number): number
  • Sets the sound position and gain of a remote user.

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

    Note:

    • For this method to work, enable stereo panning for remote users by calling the enableSoundPositionIndication method before joining a channel.
    • This method requires hardware support. For the best sound positioning, we recommend using a stereo speaker.

    Parameters

    • uid: number

      The ID of the remote user.

    • pan: number

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

      • 0.0: The remote sound comes from the front.
      • -1.0: The remote sound comes from the left.
      • 1.0: The remote sound comes from the right.
    • gain: number

      Gain of the remote user. The value ranges from 0.0 to 100.0. The default value is 100.0 (the original gain of the remote user). The smaller the value, the less the gain.

    Returns number

    • 0: Success.
    • < 0: Failure.

setRenderMode

  • setRenderMode(mode?: 1 | 2 | 3 | 4): void
  • Decide whether to use webgl/software/custom rendering.

    Parameters

    • Default value mode: 1 | 2 | 3 | 4 = 1

    Returns void

setScreenCaptureContentHint

  • Sets the content hint for screen sharing.

    A content hint suggests the type of the content being shared, so that the SDK applies different optimization algorithm to different types of content.

    Parameters

    Returns number

    • 0: Success
    • < 0: Failure

setScreenCaptureScenario

  • Sets the screen sharing scenario.

    since

    v3.7.0

    When you start screen sharing or window sharing, you can call this method to set the screen sharing scenario. The SDK adjusts the video quality and experience of the sharing according to the scenario.

    Parameters

    Returns number

    • 0: Success.
    • < 0: Failure.

setVideoDenoiserOptions

  • Sets video noise reduction.

    since

    v3.7.0

    Underlit environments and low-end video capture devices can cause video images to contain significant noise, which affects video quality. In real-time interactive scenarios, video noise also consumes bitstream resources and reduces encoding efficiency during encoding.

    You can call this method to enable the video noise reduction feature and set the options of the video noise reduction effect.

    note
    • Before calling this method, ensure that you have integrated the following dynamic library into your project:
      • macOS: AgoraVideoSegmentationExtension.xcframework
      • Windows: libagora_segmentation_extension.dll
    • Call this method after enableVideo.
    • The video noise reduction feature has certain performance requirements on devices. If your device overheats after you enable video noise reduction, Agora recommends modifying the video noise reduction options to a less performance-consuming level or disabling video noise reduction entirely.

    Parameters

    Returns number

    • 0: Success.
    • < 0: Failure.

setVideoDevice

  • setVideoDevice(deviceId: string): number
  • Sets the video device using the device Id.

    Parameters

    • deviceId: string

      The device Id.

    Returns number

    • 0: Success.
    • < 0: Failure.

setVideoEncoderConfiguration

  • Sets the video encoder configuration.

    Each video encoder configuration corresponds to a set of video parameters, including the resolution, frame rate, bitrate, and video orientation. The parameters specified in this method are the maximum values under ideal network conditions. If the video engine cannot render the video using the specified parameters due to poor network conditions, the parameters further down the list are considered until a successful configuration is found.

    If you do not set the video encoder configuration after joining the channel, you can call this method before calling the enableVideo method to reduce the render time of the first video frame.

    Parameters

    Returns number

    • 0: Success.
    • < 0: Failure.

setVideoProfile

setVideoQualityParameters

  • setVideoQualityParameters(preferFrameRateOverImageQuality: boolean): number
  • deprecated

    This method is deprecated. Use setCameraCapturerConfiguration and setVideoEncoderConfiguration instead. Sets the preference option for the video quality (live streaming only).

    Parameters

    • preferFrameRateOverImageQuality: boolean

      Sets the video quality preference:

      • true: Frame rate over image quality.
      • false: (Default) Image quality over frame rate.

    Returns number

    • 0: Success.
    • < 0: Failure.

setVideoRenderDimension

  • setVideoRenderDimension(rendertype: number, uid: number, width: number, height: number): void
  • Sets the renderer dimension of video.

    This method ONLY affects size of data sent to js layer, while native video size is determined by setVideoEncoderConfiguration.

    Parameters

    • rendertype: number

      The renderer type:

      • 0: The local renderer.
      • 1: The remote renderer.
      • 2: The device test
      • 3: The video source.
    • uid: number

      The user ID of the targeted user.

    • width: number

      The target width.

    • height: number

      The target height.

    Returns void

setVideoRenderFPS

  • setVideoRenderFPS(fps: number): void
  • Sets the global renderer frame rate (fps).

    This method is mainly used to improve the performance of js rendering once set, the video data will be sent with this frame rate. This can reduce the CPU consumption of js rendering. This applies to ALL views except the ones added to the high frame rate stream.

    Parameters

    • fps: number

      The renderer frame rate (fps).

    Returns void

setVideoRenderHighFPS

  • setVideoRenderHighFPS(fps: number): void
  • Sets renderer frame rate for the high stream.

    The high stream here has nothing to do with the dual stream. It means the stream that is added to the high frame rate stream by calling the addVideoRenderToHighFPS method.

    This is often used when we want to set the low frame rate for most of views, but high frame rate for one or two special views, e.g. screen sharing.

    Parameters

    • fps: number

      The renderer high frame rate (fps).

    Returns void

setVoiceBeautifierParameters

  • Sets parameters for SDK preset voice beautifier effects.

    since

    v3.3.1

    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 setAudioProfile, and setting the scenario parameter as 3 and the profile parameter as 4 or 5.

    note

    Parameters

    • preset: VOICE_BEAUTIFIER_PRESET

      The options for SDK preset voice beautifier effects:

      • SINGING_BEAUTIFIER: Singing beautifier effect.
    • param1: number

      The gender characteristics options for the singing voice:

      • 1: A male-sounding voice.
      • 2: A female-sounding voice.
    • param2: number

      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.

    Returns number

    • 0: Success.
    • < 0: Failure.

setVoiceBeautifierPreset

setVoiceConversionPreset

  • Sets an SDK preset voice conversion effect.

    since

    v3.3.1

    Call this method to set an SDK preset voice conversion effect for the local user who sends an audio stream. After setting a voice conversion effect, all users in the channel can hear the effect.

    You can set different voice conversion effects for different scenarios. See Set the Voice Effect.

    To achieve better voice effect quality, Agora recommends calling setAudioProfile and setting the profile parameter to 4 or 5 and the scenario parameter to 3 before calling this method.

    Note:

    Parameters

    Returns number

    • 0: Success.
    • < 0: Failure.

setVolumeOfEffect

  • setVolumeOfEffect(soundId: number, volume: number): number
  • Sets the volume of a specified audio effect.

    Parameters

    • soundId: number

      ID of the audio effect. Each audio effect has a unique ID.

    • volume: number

      Sets the volume of the specified audio effect. The value ranges between 0.0 and 100.0 (default).

    Returns number

    • 0: Success.
    • < 0: Failure.

setupLocalVideo

  • Sets the local video view and the corresponding renderer.

    Parameters

    • view: Element

      The Dom element where you initialize your view.

    • Optional options: RendererOptions

    Returns number

    • 0: Success.
    • < 0: Failure.

setupLocalVideoSource

  • setupLocalVideoSource(view: Element): void
  • Sets the video renderer for video source.

    Parameters

    • view: Element

      The dom element where video source should be displayed.

    Returns void

setupRemoteVideo

  • setupRemoteVideo(uid: number, view?: Element, channel?: undefined | string, options?: RendererOptions): number
  • Sets the remote video view and the corresponding renderer.

    Parameters

    • uid: number

      The user ID

    • Optional view: Element

      The Dom element where the remote view is initialized.

    • Optional channel: undefined | string
    • Optional options: RendererOptions

    Returns number

    • 0: Success.
    • < 0: Failure.

setupViewContentMode

  • setupViewContentMode(uid: number | "local" | "videosource", mode: 0 | 1, channelId: string | undefined): number
  • Sets the view content mode.

    Parameters

    • uid: number | "local" | "videosource"

      The user ID for operating streams. When setting up the view content of the remote user's stream, make sure you have subscribed to that stream by calling the subscribe method.

    • mode: 0 | 1

      The view content mode:

      • 0: Cropped mode. Uniformly scale the video until it fills the visible boundaries (cropped). One dimension of the video may have clipped contents.
      • 1: Fit mode. Uniformly scale the video until one of its dimension fits the boundary (zoomed to fit). Areas that are not filled due to the disparity in the aspect ratio will be filled with black.
    • channelId: string | undefined

    Returns number

    • 0: Success.
    • -1: Failure.

startAudioDeviceLoopbackTest

  • startAudioDeviceLoopbackTest(interval: number): number
  • 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.

    Note: This method tests the local audio devices and does not report the network conditions.

    Parameters

    • interval: number

      The time interval (ms).

    Returns number

    • 0: Success.
    • < 0: Failure.

startAudioMixing

  • startAudioMixing(filepath: string, loopback: boolean, replace: boolean, cycle: number, startPos?: number): number
  • Starts playing and mixing the music file.

    This method supports mixing or replacing local or online music file and audio collected by a microphone. After successfully playing the music file, the SDK triggers the audioMixingStateChanged(710,720) callback. After completing playing the music file, the SDK triggers audioMixingStateChanged(713,723).

    note
    • If you need to call startAudioMixing multiple times, ensure that the call interval is longer than 500 ms.
    • If the local music file does not exist, or if the SDK does not support the file format or cannot access the music file URL, the SDK returns the warning code 701.

    Parameters

    • filepath: string

      The absolute path or URL address (including the filename extensions) of the music file. For example: C:\music\audio.mp4. Supported audio formats include MP3, AAC, M4A, MP4, WAV, and 3GP. For more information, see Supported Media Formats in Media Foundation. When you access a local file on Android, Agora recommends passing a URI address or the path starts with /assets/ in this parameter.

    • loopback: boolean

      Whether to only play the music file on the local client:

      • true: Only play the music file on the local client so that only the local user can hear the music.
      • false: Publish the music file to remote clients so that both the local user and remote users can hear the music.
    • replace: boolean

      Whether to replace the audio collected by the microphone with a music file:

      • true: Replace. Users can only hear music.
      • false: Do not replace. Users can hear both music and audio collected by the microphone.
    • cycle: number

      The number of times the music file plays.

      • ≥ 0: The number of playback times. For example, 0 means that the SDK does not play the music file, while 1 means that the SDK plays the music file once.
      • -1: Play the music in an indefinite loop.
    • Default value startPos: number = 0

      The playback position (ms) of the music file.

    Returns number

    • 0: Success.
    • < 0: Failure.

startAudioPlaybackDeviceTest

  • startAudioPlaybackDeviceTest(filepath: string): number
  • 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.

    Parameters

    • filepath: string

      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.

    Returns number

    • 0: Success, and you can hear the sound of the specified audio file.
    • < 0: Failure.

startAudioRecording

  • deprecated

    Deprecated from v3.4.2. Use startAudioRecordingWithConfig instead.

    Starts an audio recording on the client.

    The SDK allows recording during a call. After successfully calling this method, you can record the audio of all the users in the channel and get an audio recording file. Supported formats of the recording file are as follows:

    • .wav: Large file size with high fidelity.
    • .aac: Small file size with low fidelity.
    note
    • Ensure that the directory you use to save the recording file exists and is writable.
    • This method is usually called after joinChannel. The recording automatically stops when you call leaveChannel.
    • For better recording effects, set quality as MEDIUM or HIGH when sampleRate is 44.1 kHz or 48 kHz.

    Parameters

    • filePath: string

      The absolute file path of the recording file. The string of the file name is in UTF-8, such as c:/music/audio.aac for Windows and /var/mobile/Containers/Data/audio.aac for macOS.

    • Default value recordingSampleRate: number = 32000
    • recordingQuality: AUDIO_RECORDING_QUALITY_LOW
    • recordingPosition: AUDIO_RECORDING_POSITION_MIXED_RECORDING_AND_PLAYBACK
    • Default value recordingChannel: number = 1

    Returns number

    • 0: Success
    • < 0: Failure

startAudioRecordingDeviceTest

  • startAudioRecordingDeviceTest(indicateInterval: number): number
  • Starts the microphone test.

    This method checks whether the microphone works properly.

    Parameters

    • indicateInterval: number

      The interval period (ms).

    Returns number

    • 0: Success.
    • < 0: Failure.

startAudioRecordingWithConfig

  • Starts an audio recording on the client.

    since

    v3.4.2

    The SDK allows recording audio during a call. After successfully calling this method, you can record the audio of users in the channel and get an audio recording file. Supported file formats are as follows:

    • WAV: High-fidelity files with typically larger file sizes. For example, if the sample rate is 32,000 Hz, the file size for a 10-minute recording is approximately 73 MB.
    • AAC: Low-fidelity files with typically smaller file sizes. For example, if the sample rate is 32,000 Hz and the recording quality is AUDIO_RECORDING_QUALITY_MEDIUM, the file size for a 10-minute recording is approximately 2 MB.

    Once the user leaves the channel, the recording automatically stops.

    note

    Call this method after joining a channel.

    Parameters

    Returns number

    • 0: Success.
    • < 0: Failure.

startChannelMediaRelay

  • Starts to relay media streams across channels.

    After a successful method call, the SDK triggers the channelMediaRelayState and channelMediaRelayEvent callbacks, and these callbacks report the states and events of the media stream relay.

    • If the channelMediaRelayState callback reports the state code 1 and the error code 0, and the and the channelMediaRelayEvent callback reports the event code 4 in ChannelMediaRelayEvent, the SDK starts relaying media streams between the original and the destination channel.
    • If the channelMediaRelayState callback reports the state code 3 in ChannelMediaRelayState, an exception occurs during the media stream relay.
    note
    • Contact sales-us@agora.io before implementing this function.
    • Call this method after the joinChannel method.
    • This method takes effect only when you are a host in a Live-broadcast channel.
    • We do not support using string user accounts in this function.
    • After a successful method call, if you want to call this method again, ensure that you call the stopChannelMediaRelay method to quit the current relay.

    Parameters

    Returns number

    • 0: Success.
    • < 0: Failure.

startEchoTest

  • startEchoTest(): number
  • deprecated

    The method is deprecated. Use startEchoTestWithInterval instead. Starts an audio call test.

    This method launches an audio call test to determine whether the audio devices (for example, headset and speaker) and the network connection are working properly.

    To conduct the test, the user speaks, and the recording is played back within 10 seconds.

    If the user can hear the recording in 10 seconds, it indicates that the audio devices and network connection work properly.

    Note:

    • Call this method before the joinChannel method.
    • After calling this method, call the stopEchoTest method to end the test. Otherwise, the app cannot run the next echo test, nor can it call the joinChannel method to start a new call.
    • In the 1 (live streaming) profile, only hosts can call this method.

    Returns number

    • 0: Success.
    • < 0: Failure.

startEchoTestWithConfig

  • Starts an audio and video call loop test.

    since

    v3.6.1.4

    Before joining a channel, to test whether the user's local sending and receiving streams are normal, you can call this method to perform an audio and video call loop test, which tests whether the audio and video devices and the user's upstream and downstream networks are working properly.

    After starting the test, the user needs to make a sound or face the camera. The audio or video is output after about two seconds. If the audio playback is normal, the audio device and the user's upstream and downstream networks are working properly; if the video playback is normal, the video device and the user's upstream and downstream networks are working properly.

    note
    • Call this method before joining a channel.
    • After calling this method, call stopEchoTest to end the test; otherwise, the user cannot perform the next audio and video call loop test and cannot join the channel.
    • In the LIVE_BROADCASTING profile, only a host can call this method.

    Parameters

    • config: EchoTestConfiguration

      The configuration of the audio and video call loop test. See EchoTestConfiguration.

    Returns number

    • 0: Success.
    • < 0: Failure.

startEchoTestWithInterval

  • startEchoTestWithInterval(interval: number): number
  • Starts an audio call test.

    This method starts an audio call test to determine whether the audio devices (for example, headset and speaker) and the network connection are working properly.

    In the audio call test, you record your voice. If the recording plays back within the set time interval, the audio devices and the network connection are working properly.

    Note:

    • Call this method before the joinChannel method.
    • After calling this method, call the stopEchoTest method to end the test. Otherwise, the app cannot run the next echo test, nor can it call the joinChannel method to start a new call.
    • In the 1 (live streaming) profile, only hosts can call this method.

    Parameters

    • interval: number

      The time interval (s) between when you speak and when the recording plays back.

    Returns number

    • 0: Success.
    • < 0: Failure.

startLastmileProbeTest

  • 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 average round-trip time (RTT).

    Once this method is enabled, the SDK returns the following callbacks:

    • lastMileQuality: the SDK triggers this callback within two seconds depending on the network conditions. This callback rates the network conditions with a score and is more closely linked to the user experience.
    • lastmileProbeResult: the SDK triggers this callback within 30 seconds depending on the network conditions. This callback returns the real-time statistics of the network conditions and is more objective.

    Call this method to check the uplink network quality before users join a channel or before an audience switches to a host.

    note
    • This method consumes extra network traffic and may affect communication quality. We do not recommend calling this method together with enableLastmileTest.
    • Do not call other methods before receiving the lastMileQuality and lastmileProbeResult callbacks. Otherwise, the callbacks may be interrupted by other methods.
    • In the 1 (live streaming) profile, a host should not call this method after joining a channel.

    Parameters

    Returns number

startPreview

  • startPreview(): number
  • Starts the local video preview before joining a channel.

    Before starting the preview, always call setupLocalVideo to set up the preview window and configure the attributes, and also call the enableVideo method to enable video.

    If startPreview is called to start the local video preview before calling joinChannel to join a channel, the local preview remains after after you call leaveChannel to leave the channel. Call stopPreview to disable the local preview.

    Returns number

    • 0: Success.
    • < 0: Failure.

startRtmpStreamWithTranscoding

  • startRtmpStreamWithTranscoding(url: string, transcoding: TranscodingConfig): number
  • Starts pushing media streams to a CDN and sets the transcoding configuration.

    since

    v3.6.1.4

    You can call this method to push a live audio-and-video stream to the specified CDN address and set the transcoding configuration. This method can push media streams to only one CDN address at a time, so if you need to push streams to multiple addresses, call this method multiple times.

    After you call this method, the SDK triggers the rtmpStreamingStateChanged callback on the local client to report the state of the streaming.

    note
    • Ensure that you enable the Media Push service before using this function. See Prerequisites in Media Push.
    • Call this method after joining a channel.
    • Only hosts in the LIVE_BROADCASTING profile can call this method.
    • If you want to retry pushing streams after a failed push, make sure to call stopRtmpStream first, then call this method to retry pushing streams; otherwise, the SDK returns the same error code as the last failed push.
    • If you want to push media streams in the RTMPS protocol to CDN, call startRtmpStreamWithTranscoding instead of startRtmpStreamWithoutTranscoding.

    Parameters

    • url: string

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

    • transcoding: TranscodingConfig

      The transcoding configuration for Media Push. See LiveTranscoding.

    Returns number

    • 0: Success.
    • < 0: Failure.
      • ERR_INVALID_ARGUMENT(-2): url is null or the string length is 0.
      • ERR_NOT_INITIALIZED(-7): The SDK is not initialized before calling this method.

startRtmpStreamWithoutTranscoding

  • startRtmpStreamWithoutTranscoding(url: string): number
  • Starts pushing media streams to a CDN without transcoding.

    since

    v3.6.1.4

    You can call this method to push a live audio-and-video stream to the specified CDN address. This method can push media streams to only one CDN address at a time, so if you need to push streams to multiple addresses, call this method multiple times.

    After you call this method, the SDK triggers the rtmpStreamingStateChanged callback on the local client to report the state of the streaming.

    note
    • Ensure that you enable the Media Push service before using this function. See Prerequisites in Media Push.
    • Call this method after joining a channel.
    • Only hosts in the LIVE_BROADCASTING profile can call this method.
    • If you want to retry pushing streams after a failed push, make sure to call stopRtmpStream first, then call this method to retry pushing streams; otherwise, the SDK returns the same error code as the last failed push.
    • If you want to push media streams in the RTMPS protocol to CDN, call startRtmpStreamWithTranscoding instead of startRtmpStreamWithoutTranscoding.

    Parameters

    • url: string

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

    Returns number

    • 0: Success.
    • < 0: Failure.
      • ERR_INVALID_ARGUMENT(-2): url is null or the string length is 0.
      • ERR_NOT_INITIALIZED(-7): The SDK is not initialized before calling this method.

startScreenCapture

  • startScreenCapture(windowId: number, captureFreq: number, rect: object, bitrate: number): number
  • Starts the screen sharing.

    deprecated

    This method is deprecated. Use startScreenCaptureByWindow instead.

    Parameters

    • windowId: number
    • captureFreq: number

      (Mandatory) The captured frame rate. The value ranges between 1 fps and 15 fps.

    • rect: object

      Specifies the screen sharing region. rect is valid when wndid is set as 0. When rect is set as NULL, the whole screen is shared.

      • bottom: number
      • left: number
      • right: number
      • top: number
    • bitrate: number

      The captured bitrate.

    Returns number

    • 0: Success.
    • < 0: Failure.

startScreenCapture2

  • startScreenCapture2(windowId: number, captureFreq: number, rect: object, bitrate: number): number
  • deprecated

    This method is deprecated. Use videoSourceStartScreenCaptureByScreen or videoSourceStartScreenCaptureByWindow instead.

    Starts the video source.

    Parameters

    • windowId: number
    • captureFreq: number

      (Mandatory) The captured frame rate. The value ranges between 1 fps and 15 fps.

    • rect: object

      Specifies the video source region. rect is valid when wndid is set as 0. When rect is set as NULL, the whole screen is shared.

      • bottom: number
      • left: number
      • right: number
      • top: number
    • bitrate: number

      The captured bitrate.

    Returns number

    • 0: Success.
    • < 0: Failure.

startScreenCaptureByDisplayId

startScreenCaptureByScreen

  • Shares the whole or part of a screen by specifying the screen symbol.

    Parameters

    • screenSymbol: ScreenSymbol

      The screen symbol. See ScreenSymbol.

    • rect: CaptureRect

      (Optional) The relative location of the region to the screen. NULL means sharing the whole screen. See CaptureRect. 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: CaptureParam

      The screen sharing encoding parameters. See CaptureParam

    Returns number

    • 0: Success
    • < 0: Failure

startScreenCaptureByWindow

  • Shares the whole or part of a window by specifying the window symbol.

    Parameters

    • windowSymbol: number

      The symbol of the windows to be shared.

    • rect: CaptureRect

      (Optional) The relative location of the region to the window. NULL/NIL means sharing the whole window. See CaptureRect. 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: CaptureParam

      Window sharing encoding parameters. See CaptureParam

    Returns number

    • 0: Success
    • < 0: Failure

startScreenCapturePreview

  • startScreenCapturePreview(): number
  • Starts the local video preview when using the video source.

    Returns number

    • 0: Success
    • < 0: Failure

startVideoDeviceTest

  • startVideoDeviceTest(): number
  • Starts a video-capture device test.

    Note: This method tests whether the video-capture device works properly. Ensure that you call the enableVideo method before calling this method and that the HWND window handle of the incoming parameter is valid.

    Returns number

    • 0: Success.
    • < 0: Failure.

stopAllEffects

  • stopAllEffects(): number
  • Stops playing all audio effects.

    Returns number

    • 0: Success.
    • < 0: Failure.

stopAudioDeviceLoopbackTest

  • stopAudioDeviceLoopbackTest(): number
  • Stops the audio device loopback test.

    Note: Ensure that you call this method to stop the loopback test after calling the startAudioDeviceLoopbackTest method.

    Returns number

    • 0: Success.
    • < 0: Failure.

stopAudioMixing

  • stopAudioMixing(): number
  • Stops playing or mixing the music file.

    Call this API when you are in a channel.

    Returns number

    • 0: Success.
    • < 0: Failure.

stopAudioPlaybackDeviceTest

  • stopAudioPlaybackDeviceTest(): number
  • Stops the audio playback device test.

    This method stops testing the audio playback device. You must call this method to stop the test after calling the startAudioPlaybackDeviceTest method.

    Returns number

    • 0: Success.
    • < 0: Failure.

stopAudioRecording

  • stopAudioRecording(): number
  • Stops an audio recording on the client.

    You can call this method before calling the leaveChannel method else to stop the recording automatically.

    Returns number

    • 0: Success
    • < 0: Failure

stopAudioRecordingDeviceTest

  • stopAudioRecordingDeviceTest(): number
  • Stops the microphone test.

    Note: This method stops the microphone test. You must call this method to stop the test after calling the startAudioRecordingDeviceTest method.

    Returns number

    • 0: Success.
    • < 0: Failure.

stopChannelMediaRelay

  • stopChannelMediaRelay(): number
  • Stops the media stream relay.

    Once the relay stops, the host quits all the destination channels.

    After a successful method call, the SDK triggers the channelMediaRelayState callback. If the callback reports the state code 0 and the error code 1, the host successfully stops the relay.

    Note: If the method call fails, the SDK triggers the channelMediaRelayState callback with the error code 2 and 8 in ChannelMediaRelayError. You can leave the channel by calling the leaveChannel method, and the media stream relay automatically stops.

    Returns number

    • 0: Success
    • < 0: Failure

stopEchoTest

  • stopEchoTest(): number
  • Stops the audio call test.

    Returns number

    • 0: Success.
    • < 0: Failure.

stopEffect

  • stopEffect(soundId: number): number
  • Stops playing a specified audio effect.

    Parameters

    • soundId: number

      ID of the audio effect to stop playing. Each audio effect has a unique ID.

    Returns number

    • 0: Success.
    • < 0: Failure.

stopLastmileProbeTest

  • stopLastmileProbeTest(): number
  • Stops the last-mile network probe test.

    Returns number

    • 0: Success.
    • < 0: Failure.

stopPreview

  • stopPreview(): number
  • Stops the local video preview and closes the video.

    Returns number

    • 0: Success.
    • < 0: Failure.

stopRtmpStream

  • stopRtmpStream(url: string): number
  • Stops pushing media streams to a CDN.

    since

    v3.6.1.4

    You can call this method to stop the live stream on the specified CDN address. This method can stop pushing media streams to only one CDN address at a time, so if you need to stop pushing streams to multiple addresses, call this method multiple times.

    After you call this method, the SDK triggers the rtmpStreamingStateChanged callback on the local client to report the state of the streaming.

    Parameters

    • url: string

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

    Returns number

    • 0: Success.
    • < 0: Failure.

stopScreenCapture

  • stopScreenCapture(): number
  • Stops screen sharing.

    Returns number

    • 0: Success.
    • < 0: Failure.

stopScreenCapture2

  • stopScreenCapture2(): number
  • Stops the screen sharing when using the video source.

    Returns number

    • 0: Success.
    • < 0: Failure.

stopScreenCapturePreview

  • stopScreenCapturePreview(): number
  • Stops the local video preview when using the video source.

    Returns number

    • 0: Success.
    • < 0: Failure.

stopVideoDeviceTest

  • stopVideoDeviceTest(): number
  • Stops the video-capture device test.

    Note: This method stops testing the video-capture device. You must call this method to stop the test after calling the startVideoDeviceTest method.

    Returns number

    • 0: Success.
    • < 0: Failure.

subscribe

  • Subscribes to a remote user and initializes the corresponding renderer.

    Parameters

    • uid: number

      The user ID of the remote user.

    • view: Element

      The Dom where to initialize the renderer.

    • Optional options: RendererOptions

    Returns number

    • 0: Success.
    • < 0: Failure.

switchChannel

  • Switches to a different channel, and configures whether to automatically subscribe to audio or video streams in the target channel.

    This method allows the audience of a 1 (live streaming) channel to switch to a different channel.

    After the user successfully switches to another channel, the leaveChannel and joinChannelSuccess 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 1 (live streaming) channel only.

    Parameters

    • token: string

      The token generated at your server. For details, see Generate a token.

    • channel: string

      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: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
    • Optional options: ChannelMediaOptions

      The channel media options. See ChannelMediaOptions.

    Returns number

    • 0: Success.
    • < 0: Failure.
      • -1: A general error occurs (no specified reason).
      • -2: The parameter is invalid.
      • -5: The request is rejected, probably because the user is not an audience.
      • -7: The SDK is not initialized.
      • -102: The channel name is invalid.
      • -113: The user is not in the channel.

takeSnapshot

  • takeSnapshot(channel: string, uid: number, filePath: string): number
  • Takes a snapshot of a video stream.

    since

    v3.6.1.4

    This method takes a snapshot of a video stream from the specified user, generates a JPG image, and saves it to the specified path.

    The method is asynchronous, and the SDK has not taken the snapshot when the method call returns. After a successful method call, the SDK triggers the snapshotTaken callback to report whether the snapshot is successfully taken as well as the details of the snapshot taken.

    note
    • Call this method after joining a channel.
    • If the video of the specified user is pre-processed, for example, added with watermarks or image enhancement effects, the generated snapshot also includes the pre-processing effects.

    Parameters

    • channel: string

      The channel name.

    • uid: number

      The user ID of the user. Set uid as 0 if you want to take a snapshot of the local user's video.

    • filePath: string

      The local path (including the filename extensions) of the snapshot. For example, C:\Users\<user_name>\AppData\Local\Agora\<process_name>\example.jpg on Windows, /App Sandbox/Library/Caches/example.jpg on iOS, ~/Library/Logs/example.jpg on macOS, and /storage/emulated/0/Android/data/<package name>/files/example.jpg on Android. Ensure that the path you specify exists and is writable.

    Returns number

    • 0: Success.
    • < 0: Failure.

unRegisterMediaMetadataObserver

  • unRegisterMediaMetadataObserver(): number
  • Unregisters a media metadata observer.

    Returns number

    • 0: Success.
    • < 0: Failure.

unloadEffect

  • unloadEffect(soundId: number): number
  • Releases a specified preloaded audio effect from the memory.

    Parameters

    • soundId: number

      ID of the audio effect. Each audio effect has a unique ID.

    Returns number

    • 0: Success.
    • < 0: Failure.

updateChannelMediaRelay

updateRtmpTranscoding

  • Updates the transcoding configuration.

    since

    v3.6.1.4

    After you start pushing media streams to CDN with transcoding, you can dynamically update the transcoding configuration according to the scenario. The SDK triggers the transcodingUpdated callback after the transcoding configuration is updated.

    Parameters

    • transcoding: TranscodingConfig

      The transcoding configuration for Media Push. See LiveTranscoding.

    Returns number

    • 0: Success.
    • < 0: Failure.

updateScreenCaptureParameters

  • updateScreenCaptureParameters(param: CaptureParam): number
  • Updates the screen sharing parameters.

    Parameters

    Returns number

    • 0: Success
    • < 0: Failure

updateScreenCaptureRegion

  • updateScreenCaptureRegion(rect: object): number
  • Updates the screen capture region.

    Parameters

    • rect: object

      (relative distance from the left-top corner of the screen)

      • bottom: number
      • left: number
      • right: number
      • top: number

    Returns number

    • 0: Success.
    • < 0: Failure.

videoSourceAdjustLoopbackRecordingSignalVolume

  • videoSourceAdjustLoopbackRecordingSignalVolume(volume: number): number
  • Parameters

    • volume: number

    Returns number

videoSourceAdjustRecordingSignalVolume

  • videoSourceAdjustRecordingSignalVolume(volume: number): number
  • Parameters

    • volume: number

    Returns number

videoSourceDisableAudio

  • videoSourceDisableAudio(): number
  • meeting

    Returns number

videoSourceEnableAudio

  • videoSourceEnableAudio(): number
  • Enables the audio module.

    The audio module is disabled by default.

    Note:

    • This method affects the internal engine and can be called after calling the 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:

    Returns number

    • 0: Success.
    • < 0: Failure.

videoSourceEnableEncryption

  • videoSourceEnableEncryption(enabled: boolean, encryptionConfig: EncryptionConfig): number
  • Enables/Disables the built-in encryption.

    since

    v3.2.0

    In scenarios requiring high security, Agora recommends calling this method to enable the built-in encryption before joining a channel.

    All users in the same channel must use the same encryption mode and encryption key. 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 or RTMPS streaming function.
    • The SDK returns -4 when the encryption mode is incorrect or the SDK fails to load the external encryption library. Check the enumeration or reload the external encryption library.

    Parameters

    • enabled: boolean

      Whether to enable the built-in encryption:

      • true: Enable the built-in encryption.
      • false: Disable the built-in encryption.
    • encryptionConfig: EncryptionConfig

      Configurations of built-in encryption schemas.

    Returns number

    • 0: Success.
    • < 0: Failure.

videoSourceEnableLoopbackRecording

  • videoSourceEnableLoopbackRecording(enabled: boolean, deviceName?: string | null): number
  • Enables loopback audio capturing.

    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.

    Parameters

    • enabled: boolean
    • Default value deviceName: string | null = null

      The device name of the sound card. The default value is NULL (the default sound card). Note: 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.

    Returns number

    • 0: Success
    • < 0: Failure

videoSourceEnableWebSdkInteroperability

  • videoSourceEnableWebSdkInteroperability(enabled: boolean): number
  • deprecated

    This method is deprecated. As of v3.0.0, the Electron SDK automatically enables interoperability with the Web SDK, so you no longer need to call this method.

    Enables the web interoperability of the video source, if you set it to true.

    Note: You must call this method after calling the videoSourceInitialize method.

    Parameters

    • enabled: boolean

      Set whether or not to enable the web interoperability of the video source.

      • true: Enables the web interoperability.
      • false: Disables web interoperability.

    Returns number

    • 0: Success.
    • < 0: Failure.

videoSourceInitialize

  • videoSourceInitialize(appId: string, areaCode?: AREA_CODE, groupId?: undefined | string, bundleId?: undefined | string): number
  • Initializes agora real-time-communicating video source with the app Id.

    Parameters

    • appId: string

      The app ID issued to you by Agora.

    • Default value areaCode: AREA_CODE = 4294967295
    • Optional groupId: undefined | string

      optional groupId of your application, you will need to specify this field in order to start a process in MacOS Sandbox.

    • Optional bundleId: undefined | string

      optional bundleId of your application, you will need to specify this field in order to start a process in MacOS Sandbox

    Returns number

    • 0: Success.
    • < 0: Failure.
      • ERR_INVALID_APP_ID (101): The app ID is invalid. Check if it is in the correct format.

videoSourceJoin

  • videoSourceJoin(token: string, cname: string, info: string, uid: number, options?: ChannelMediaOptions): number
  • Allows a user to join a channel when using the video source.

    Parameters

    • token: string

      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 token.
      • For high-security requirements: Set it as the token generated at your server. For details, see Get a token.
    • cname: string

      (Required) The unique channel name for the Agora RTC session in the string format smaller than 64 bytes. Supported characters:

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

      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.

    • uid: number

      The User ID. The same user ID cannot appear in a channel. Ensure that the user ID of the videoSource here is different from the uid used by the user when calling the joinChannel method.

    • Optional options: ChannelMediaOptions

    Returns number

    • 0: Success.
    • < 0: Failure.

videoSourceLeave

  • videoSourceLeave(): number
  • Allows a user to leave a channe when using the video source.

    Note: You must call this method after calling the videoSourceJoin method.

    Returns number

    • 0: Success.
    • < 0: Failure.

videoSourceMuteAllRemoteAudioStreams

  • videoSourceMuteAllRemoteAudioStreams(mute: boolean): number
  • Parameters

    • mute: boolean

    Returns number

videoSourceMuteAllRemoteVideoStreams

  • videoSourceMuteAllRemoteVideoStreams(mute: boolean): number
  • Parameters

    • mute: boolean

    Returns number

videoSourceMuteRemoteAudioStream

  • videoSourceMuteRemoteAudioStream(uid: number, mute: boolean): number
  • Parameters

    • uid: number
    • mute: boolean

    Returns number

videoSourceMuteRemoteVideoStream

  • videoSourceMuteRemoteVideoStream(uid: number, mute: boolean): number
  • Parameters

    • uid: number
    • mute: boolean

    Returns number

videoSourceRelease

  • videoSourceRelease(): number
  • Releases the video source object.

    Returns number

    • 0: Success.
    • < 0: Failure.

videoSourceRenewToken

  • videoSourceRenewToken(token: string): number
  • Gets a new token for a user using the video source when the current token expires after a period of time.

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

    Parameters

    • token: string

      The new token.

    Returns number

    • 0: Success.
    • < 0: Failure.

videoSourceSetAddonLogFile

  • videoSourceSetAddonLogFile(filepath: string): number
  • Parameters

    • filepath: string

    Returns number

videoSourceSetChannelProfile

  • videoSourceSetChannelProfile(profile: number): number
  • Sets the channel profile when using the video source.

    Parameters

    • profile: number

      Sets the channel profile:

      • 0:(Default) Communication.
      • 1: Live streaming.
      • 2: Gaming.

    Returns number

    • 0: Success.
    • < 0: Failure.

videoSourceSetEncryptionMode

  • videoSourceSetEncryptionMode(mode: string): number
  • deprecated

    This method is deprecated from v3.2.0. Use the videoSourceEnableEncryption method instead.

    Sets the built-in encryption mode.

    Parameters

    • mode: string

    Returns number

    • 0: Success.
    • < 0: Failure.

videoSourceSetEncryptionSecret

  • videoSourceSetEncryptionSecret(secret: string): number
  • Enables built-in encryption with an encryption password before users join a channel.

    deprecated

    This method is deprecated from v3.2.0. Use the videoSourceEnableEncryption method instead.

    Parameters

    • secret: string

      The encryption password.

    Returns number

    • 0: Success.
    • < 0: Failure.

videoSourceSetLocalAccessPoint

videoSourceSetLogFile

  • videoSourceSetLogFile(filepath: string): number
  • Specifies an SDK output log file for the video source object.

    Note: Call this method after the videoSourceInitialize method.

    Parameters

    • filepath: string

      filepath of log. The string of the log file is in UTF-8.

    Returns number

    • 0: Success.
    • < 0: Failure.

videoSourceSetParameters

  • videoSourceSetParameters(parameter: string): number
  • Sets the video source parameters.

    Parameters

    • parameter: string

      Sets the video source encoding parameters.

    Returns number

    • 0: Success.
    • < 0: Failure.

videoSourceSetProcessDpiAwareness

  • videoSourceSetProcessDpiAwareness(): number
  • Returns number

videoSourceSetScreenCaptureContentHint

  • Updates the video source parameters.

    Parameters

    Returns number

    • 0: Success.
    • < 0: Failure.

videoSourceSetVideoProfile

  • videoSourceSetVideoProfile(profile: VIDEO_PROFILE_TYPE, swapWidthAndHeight?: boolean): number
  • Sets the video profile for the video captured by the camera device.

    Parameters

    Returns number

    • 0: Success.
    • < 0: Failure.

videoSourceStartScreenCaptureByDisplayId

videoSourceStartScreenCaptureByScreen

  • Shares the whole or part of a screen by specifying the screen rect.

    Parameters

    • screenSymbol: ScreenSymbol

      The display ID:

      • macOS: The display ID.
      • Windows: The screen rect.
    • rect: CaptureRect

      Sets the relative location of the region to the screen.

    • param: CaptureParam

      Sets the video source encoding parameters.

    Returns number

    • 0: Success.
    • < 0: Failure.

videoSourceStartScreenCaptureByWindow

  • Shares the whole or part of a window by specifying the window ID.

    Parameters

    • windowSymbol: number

      The ID of the window to be shared.

    • rect: CaptureRect

      The ID of the window to be shared.

    • param: CaptureParam

      Sets the video source encoding parameters.

    Returns number

    • 0: Success.
    • < 0: Failure.

videoSourceUpdateScreenCaptureParameters

  • videoSourceUpdateScreenCaptureParameters(param: CaptureParam): number
  • Updates the video source parameters.

    Parameters

    • param: CaptureParam

      Sets the video source encoding parameters.

    Returns number

    • 0: Success.
    • < 0: Failure.

videoSourceUpdateScreenCaptureRegion

  • videoSourceUpdateScreenCaptureRegion(rect: object): number
  • Updates the screen capture region for the video source.

    Parameters

    • rect: object

      (relative distance from the left-top corner of the screen)

      • bottom: number
      • left: number
      • right: number
      • top: number

    Returns number

    • 0: Success.
    • < 0: Failure.