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

renderMode

renderMode: 1 | 2 | 3

rtcEngine

rtcEngine: NodeRtcEngine

streams

streams: Map<string, IRenderer>

Methods

addInjectStreamUrl

  • description

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

    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.

    Parameters

    • url: string

      The HTTP/HTTPS URL address to be added to the ongoing live broadcast. 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.

addPublishStreamUrl

  • addPublishStreamUrl(url: string, transcodingEnabled: boolean): number
  • description

    Publishes the local stream to a specified CDN live RTMP address. (CDN live only)

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

    • Ensure that the user joins the channel before calling this method.
    • This method adds only one stream RTMP URL address each time it is called.
    • The RTMP URL address must not contain special characters, such as Chinese language characters.
    • This method applies to Live Broadcast only.

    Parameters

    • url: string

      The CDN streaming URL in the RTMP format. The maximum length of this parameter is 1024 bytes.

    • 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.
      • false: Disable transcoding.

    Returns number

    • 0: Success.
    • < 0: Failure.

addVideoRenderToHighFPS

  • addVideoRenderToHighFPS(uid: number): void
  • description

    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

adjustAudioMixingPlayoutVolume

  • adjustAudioMixingPlayoutVolume(volume: number): number
  • description

    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
  • description

    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
  • description

    Adjusts the volume of audio mixing.

    Call this API when you are in a channel.

    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.

adjustPlaybackSignalVolume

  • adjustPlaybackSignalVolume(volume: number): number
  • description

    Adjusts the playback volume.

    Parameters

    • volume: number

      Playback volume. The value ranges between 0 and 400:

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

    Returns number

    • 0: Success.
    • < 0: Failure.

adjustRecordingSignalVolume

  • adjustRecordingSignalVolume(volume: number): number
  • description

    Adjusts the recording volume.

    Parameters

    • volume: number

      Recording volume. The value ranges between 0 and 400:

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

    Returns number

    • 0: Success.
    • < 0: Failure.

complain

  • complain(callId: string, desc: string): number
  • description

    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) Pointer to the description of the complaint, with a string length of less than 800 bytes.

    Returns number

    • 0: Success.
    • < 0: Failure.

createDataStream

  • createDataStream(reliable: boolean, ordered: boolean): number
  • description

    Creates a data stream.

    Each user can have up to five simultaneous data streams in a channel.

    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.

destroyRender

  • destroyRender(key: "local" | "videosource" | number, onFailure?: undefined | function): void
  • description

    Destroys the renderer.

    Parameters

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

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

    • Optional onFailure: undefined | function

      The error callback for the destroyRenderer method.

    Returns void

disableAudio

  • disableAudio(): number
  • description

    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
  • description

    This method disables the network connection quality test.

    Returns number

    • 0: Success.
    • < 0: Failure.

disableVideo

  • disableVideo(): number
  • description

    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
  • description

    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): number
  • description

    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.

    Returns number

    • 0: Success.
    • < 0: Failure.

enableDualStreamMode

  • enableDualStreamMode(enable: boolean): number
  • description

    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.

enableLastmileTest

  • enableLastmileTest(): number
  • description

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

    Returns number

    • 0: Success.
    • < 0: Failure.

enableLocalAudio

  • enableLocalAudio(enable: boolean): number
  • description

    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.

    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
  • description

    Disables/Re-enables the local video capture.

    The local video is enabled by default. This method enables/disables the local video, which is only applicable to the scenario when the user only wants to watch the remote video without sending any video stream to the other user.

    A successful enableLocalVideo method call triggers the userEnableLocalVideo callback on the remote client.

    Note: This method affects the internal engine and can be called after calling the leaveChannel method.

    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.

enableLoopbackRecording

  • enableLoopbackRecording(enable?: boolean, deviceName?: string | null): number
  • description

    Enables the loopback recording. Once enabled, the SDK collects all local sounds.

    Parameters

    • Default value enable: boolean = false
    • Default value deviceName: string | null = null

    Returns number

    • 0: Success.
    • < 0: Failure.

enableSoundPositionIndication

  • enableSoundPositionIndication(enable: boolean): number
  • description

    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.

enableVideo

  • enableVideo(): number
  • description

    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.

enableWebSdkInteroperability

  • enableWebSdkInteroperability(enable: boolean): number
  • description

    Enables interoperability with the Agora Web SDK (Live Broadcast only).

    Use this method when the channel profile is Live Broadcast. Interoperability with the Agora Web SDK is enabled by default when the channel profile is Communication.

    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.

getAudioMixingCurrentPosition

  • getAudioMixingCurrentPosition(): number
  • description

    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
  • description

    Gets the duration (ms) of the music file.

    Call this API when you are in a channel.

    Returns number

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

getAudioMixingPlayoutVolume

  • getAudioMixingPlayoutVolume(): number
  • description

    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
  • description

    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
  • description

    check whether selected audio playback device is muted

    Returns boolean

    muted/unmuted

getAudioPlaybackDevices

  • getAudioPlaybackDevices(): Array<Object>
  • description

    Retrieves the audio playback device associated with the device ID.

    Returns Array<Object>

    The array of the audio playback device.

getAudioPlaybackVolume

  • getAudioPlaybackVolume(): number
  • description

    Retrieves the volume of the audio playback device.

    Returns number

    The audio playback device volume.

getAudioRecordingDeviceMute

  • getAudioRecordingDeviceMute(): boolean
  • description

    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>
  • description

    Retrieves the audio recording device associated with the device ID.

    Returns Array<Object>

    The array of the audio recording device.

getAudioRecordingVolume

  • getAudioRecordingVolume(): number
  • description

    Retrieves the volume of the microphone.

    Returns number

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

getCallId

  • getCallId(): string
  • description

    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.

getConnectionState

getCurrentAudioPlaybackDevice

  • getCurrentAudioPlaybackDevice(): Object
  • description

    Gets the current audio playback device.

    Returns Object

    The current audio playback device.

getCurrentAudioRecordingDevice

  • getCurrentAudioRecordingDevice(): Object
  • description

    Gets the current audio recording device.

    Returns Object

    The audio recording device.

getCurrentVideoDevice

  • getCurrentVideoDevice(): Object
  • description

    Gets the current video device.

    Returns Object

    The video device.

getEffectsVolume

  • getEffectsVolume(): number
  • description

    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
  • description

    Retrieves the error description.

    Parameters

    • errorCode: number

      The error code.

    Returns string

    The error description.

getPlaybackDeviceInfo

  • getPlaybackDeviceInfo(deviceId: string, deviceName: string): number
  • description

    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.

getRecordingDeviceInfo

  • getRecordingDeviceInfo(deviceId: string, deviceName: string): number
  • description

    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.

getScreenDisplaysInfo

  • getScreenDisplaysInfo(): Array<Object>
  • description

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

    Returns Array<Object>

    The array list of the display ID and relevant information.

getScreenWindowsInfo

  • getScreenWindowsInfo(): Array<Object>
  • description

    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.

    Returns Array<Object>

    The array list of the window ID and relevant information.

getUserInfoByUid

  • getUserInfoByUid(uid: number): object
  • description

    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

    • 0: Success.
    • < 0: Failure.
    • errCode: number

      Error code.

    • userInfo: UserInfo

      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
  • description

    Gets the user information by passing in the user account.

    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 ID of the remote user from the UserInfo object by passing in the user account.

    Parameters

    • userAccount: string

      The user account. Ensure that you set this parameter.

    Returns object

    • 0: Success.
    • < 0: Failure.
    • errCode: number

      Error code.

    • userInfo: UserInfo

      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.

getVersion

  • getVersion(): string
  • description

    Returns the version and the build information of the current SDK.

    Returns string

    The version of the current SDK.

getVideoDevices

  • getVideoDevices(): Array<Object>
  • description

    Gets the list of the video devices.

    Returns Array<Object>

    The array of the video devices.

initRender

  • initRender(key: "local" | "videosource" | number, view: Element): void
  • description

    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.

    Returns void

initialize

  • initialize(appid: string): number
  • description

    Initializes the agora real-time-communicating engine with your App ID.

    Parameters

    • appid: string

      The App ID issued to you by Agora.

    Returns number

    • 0: Success.
    • < 0: Failure.

joinChannel

  • joinChannel(token: string, channel: string, info: string, uid: number): number
  • description

    Allows a user to join a channel.

    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.

    This method call triggers the following callbacks:

    • The local client: joinedChannel
    • The remote client: userJoined, if the user joining the channel is in the Communication profile, or is a BROADCASTER in the Live Broadcast profile.

    When the connection between the client and Agora's server is interrupted due to poor network conditions, the SDK tries reconnecting to the server. When the local client successfully rejoins the channel, the SDK triggers the rejoinedChannel callback on the local client.

    Parameters

    • token: string

      token The token generated at your server:

      • For low-security requirements: You can use the temporary token generated at Dashboard. 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.
    • channel: string

      (Required) Pointer to 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

      (Optional) Pointer to additional information about the channel. This parameter can be set to NULL or contain channel related information. Other users in the channel will not receive this message.

    • uid: number

      The User ID. A 32-bit unsigned integer with a value ranging from 1 to 232-1. The uid must be unique. If a uid is not assigned (or set to 0), the SDK assigns a uid.

    Returns number

    • 0: Success.
    • < 0: Failure.

joinChannelWithUserAccount

  • joinChannelWithUserAccount(token: string, channel: string, userAccount: string): number
  • description

    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 profile, or is a BROADCASTER in the Live Broadcast 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 low-security requirements: You can use the temporary token generated at Dashboard. 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.
    • 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:

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

    Returns number

    • 0: Success.
    • < 0: Failure.

leaveChannel

  • leaveChannel(): number
  • description

    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 BROADCASTER in the Live Broadcast profile.

    Returns number

    • 0: Success.
    • < 0: Failure.

muteAllRemoteAudioStreams

  • muteAllRemoteAudioStreams(mute: boolean): number
  • description

    Stops/Resumes receiving all remote audio streams.

    Parameters

    • mute: boolean

      Sets whether to receive/stop receiving all remote audio streams:

      • true: Stop receiving all remote audio streams.
      • false: (Default) Receive all remote audio streams.

    Returns number

    • 0: Success.
    • < 0: Failure.

muteAllRemoteVideoStreams

  • muteAllRemoteVideoStreams(mute: boolean): number
  • description

    Stops/Resumes receiving all remote video streams.

    Parameters

    • mute: boolean

      Sets whether to receive/stop receiving all remote video streams:

      • true: Stop receiving all remote video streams.
      • false: (Default) Receive all remote video streams.

    Returns number

    • 0: Success.
    • < 0: Failure.

muteLocalAudioStream

  • muteLocalAudioStream(mute: boolean): number
  • description

    Stops/Resumes sending the local audio stream.

    A successful muteLocalAudioStream method call triggers the userMuteAudio callback on the remote client.

    Note: muteLocalAudioStream(true) does not disable the microphone and thus does not affect any ongoing recording.

    Parameters

    • mute: boolean

      Sets whether to send/stop sending the local audio stream:

      • true: Stop sending the local audio stream.
      • false: (Default) Send the local audio stream.

    Returns number

    • 0: Success.
    • < 0: Failure.

muteLocalVideoStream

  • muteLocalVideoStream(mute: boolean): number
  • description

    Stops/Resumes sending the local video stream.

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

    Note: muteLocalVideoStream(true) does not disable the camera and thus does not affect the retrieval of the local video streams.

    Parameters

    • mute: boolean

      Sets whether to send/stop sending the local video stream:

      • true: Stop sending the local video stream.
      • false: (Default) Send the local video stream.

    Returns number

    • 0: Success.
    • < 0: Failure.

muteRemoteAudioStream

  • muteRemoteAudioStream(uid: number, mute: boolean): number
  • description

    Stops/Resumes receiving a specified audio stream.

    Parameters

    • uid: number

      ID of the specified remote user.

    • mute: boolean

      Sets whether to receive/stop receiving the specified remote user's audio stream:

      • true: Stop receiving the specified remote user’s audio stream.
      • false: (Default) Receive the specified remote user’s audio stream.

    Returns number

    • 0: Success.
    • < 0: Failure.

muteRemoteVideoStream

  • muteRemoteVideoStream(uid: number, mute: boolean): number
  • description

    Stops/Resumes receiving a specified remote user's video stream.

    Parameters

    • uid: number

      User ID of the specified remote user.

    • mute: boolean

      Sets whether to receive/stop receiving a specified remote user's video stream:

      • true: Stop receiving a specified remote user’s video stream.
      • false: (Default) Receive a specified remote user’s video stream.

    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: "remoteVideoStats", cb: function): this
  • on(evt: "remoteAudioStats", cb: function): this
  • on(evt: "remoteVideoTransportStats", cb: function): this
  • on(evt: "remoteAudioTransportStats", 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: "userJoined", cb: function): this
  • on(evt: "removeStream", 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: "fristLocalAudioFrame", 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: "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: "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: "localUserRegistered", cb: function): this
  • on(evt: "userInfoUpdated", cb: function): this
  • on(evt: "localVideoStateChanged", 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.

    • warn: Warning code.
    • msg: Pointer to the warning message.

    Parameters

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

          • warn: number
          • msg: string

          Returns void

    Returns this

  • Reports an error during SDK runtime.

    • err: Error code.
    • msg: Pointer to the error message.

    Parameters

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

          • err: number
          • msg: string

          Returns void

    Returns this

  • Occurs when a user joins a specified channel.

    • channel: Pointer to the channel name.
    • uid: User ID of the user joining the channel.
    • elapsed: Time elapsed (ms) from the user calling the joinChannel method until the SDK triggers this callback.

    Parameters

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

          • channel: string
          • uid: number
          • elapsed: number

          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.

    • channel: Pointer to the channel name.
    • uid: User ID of the user joining the channel.
    • elapsed: Time elapsed (ms) from the user calling the joinChannel method until the SDK triggers this callback.

    Parameters

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

          • channel: string
          • uid: number
          • elapsed: number

          Returns void

    Returns this

  • 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 and the speakers' volume.

    • speakers: A struct containing each speaker's user ID and volume information.
      • uid: User ID of the speaker. The uid of the local user is 0.
      • volume: The volume of the speaker.
    • speakerNumber: Total number of speakers.
    • volume: Total volume after audio mixing. The value ranges between 0 (lowest volume) and 255 (highest volume).

    Parameters

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

          • speakers: object[]
          • speakerNumber: number
          • totalVolume: number

          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
        • (): void
        • Returns void

    Returns this

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

    • stats: Agora RTC engine statistics, see RtcStats.

    Parameters

    • evt: "rtcStats"
    • cb: function

    Returns this

  • Reports the statistics of the local video streams.

    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

  • 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

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

    • stats: The transport-layer statistics. See {@link remoteAudioTransportStats}.

    Parameters

    Returns this

  • Occurs when the audio device state changes.

    • deviceId: Pointer to the device ID.
    • deviceType: Device type. See MediaDeviceType.
    • deviceState: Device state:
    • 1: The device is active
    • 2: The device is disabled.
    • 4: The device is not present.
    • 8: The device is unplugged.

    Parameters

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

          • deviceId: string
          • deviceType: number
          • deviceState: number

          Returns void

    Returns this

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

    • state: The state code.
      • 710: The audio mixing file is playing.
      • 711: The audio mixing file pauses playing.
      • 713: The audio mixing file stops playing.
      • 714: An exception occurs when playing the audio mixing file.
    • err: The error code.
      • 701: The SDK cannot open the audio mixing file.
      • 702: The SDK opens the audio mixing file too frequently.
      • 703: The audio mixing file playback is interrupted.

    Parameters

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

          • state: number
          • err: number

          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.

    • deviceId: Pointer to the device ID.
    • deviceType: Device type. See MediaDeviceType.
    • deviceState: Device state:
    • 1: The device is active.
    • 2: The device is disabled.
    • 4: The device is not present.
    • 8: The device is unplugged.

    Parameters

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

          • deviceId: string
          • deviceType: number
          • deviceState: number

          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.

    • uid: User ID. The network quality of the user with this uid is reported. If uid is 0, the local network quality is reported.
    • txquality: 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: Downlink network quality rating of the user in terms of the packet loss rate, average RTT, and jitter of the downlink network. See AgoraNetworkQuality.

    Parameters

    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 engine receives and renders the first local video frame on the video window.

    • width: Width (pixels) of the first local video frame.
    • height: Height (pixels) 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

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

    • uid: User ID of the remote user or local user (0) whose video size or rotation changes.
    • width: New width (pixels) of the video.
    • height: New height (pixels) of the video.
    • roation: New height (pixels) of the video.

    Parameters

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

          • uid: number
          • width: number
          • height: number
          • rotation: number

          Returns void

    Returns this

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

    • 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: "firstRemoteVideoFrame"
    • 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.

    • uid: User ID of the user or host joining the channel.
    • elapsed: Time delay (ms) from the local user calling the joinChannel method until the SDK triggers this callback.

    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 Live-broadcast 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
          • elapsed: number

          Returns void

    Returns this

  • 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 profile, and more for the Live-broadcast 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'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

  • 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

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

    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.

    • uid: User ID of the remote user sending the message.
    • streamId: Stream ID.
    • msg: Pointer to the data received bt the local user.
    • len: Length of the data in bytes.

    Parameters

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

          • uid: number
          • streamId: number
          • msg: string
          • len: number

          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.

    • uid: User ID of the remote user sending the message.
    • streamId: Stream ID.
    • err: Error code.
    • missed: Number of the lost messages.
    • cached: Number of incoming cached messages when the data stream is interrupted.

    Parameters

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

          • uid: number
          • streamId: number
          • code: number
          • missed: number
          • cached: number

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

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

    Parameters

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

          • elapsed: number

          Returns void

    Returns this

  • 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

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

    • uid: User ID of the remote user sending the audio stream.
    • elapsed: The time elapsed (ms) from the local user calling the joinChannel method until the SDK triggers this callback.

    Parameters

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

          • uid: number
          • elapsed: number

          Returns void

    Returns this

  • Reports which user is the loudest speaker.

    • uid: User ID of the active speaker. A uid of 0 represents the local user. 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.

    Note:

    • To receive this callback, you need to call the enableAudioVolumeIndication method.
    • This callback returns the user ID of the user with the highest voice volume during a period of time, instead of at the moment.

    Parameters

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

          • uid: number

          Returns void

    Returns this

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

    • oldRole: Role that the user switches from ClientRoleType.
    • newRole: Role that the user switches to ClientRoleType.

    Parameters

    Returns this

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

    • deviceType: Device type. See {@link AgoraRtcEngine.MediaDeviceType MediaDeviceType}.
    • volume: Volume of the device. The value ranges between 0 and 255.
    • muted:
      • true: Volume of the device. The value ranges between 0 and 255.
      • false: The audio device is not muted.

    Parameters

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

          Returns void

    Returns this

  • Occurs when the user for sharing screen joined the channel.

    • uid: The User ID.

    Parameters

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

          • uid: number

          Returns void

    Returns this

  • Occurs when the token expires.

    Parameters

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

    Returns this

  • Occurs when the user for sharing screen leaved the channel.

    • uid: The User ID.

    Parameters

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

    Returns this

  • Occurs when the remote video state changes.

    • uid: ID of the user whose video state changes.
    • state: State of the remote video: Playing normally or frozen. See {@link AgoraRtcEngine.RemoteVideoState RemoteVideoState}.

    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.

    • token: Pointer to the token that expires in 30 seconds.

    Parameters

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

          • token: string

          Returns void

    Returns this

  • Reports the result of CDN live streaming.

    • 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

  • 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 publisher's transcoding is updated.

    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.

    • url: Pointer to 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 remotely subscribed media stream falls back to audio-only due to poor network conditions or switches back to the video 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.

    • uid: ID of the remote user sending the stream.
    • isFallbackOrRecover: Whether the remotely subscribed media stream falls back to audio-only or switches back to the video:
      • true: The remotely subscribed media stream falls back to audio-only due to poor network conditions.
      • false: The remotely subscribed media stream switches back to the video stream after the network conditions improved.

    Parameters

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

          • uid: number
          • isFallbackOrRecover: boolean

          Returns void

    Returns this

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

    • localVideoState: The local video state:
      • 0: The local video is in the initial state.
      • 1: The local video capturer starts successfully.
      • 2: The local video capturer starts successfully.
      • 3: The local video fails to start.
    • error: The detailed error information of the local video:
      • 0: The local video is normal.
      • 1: No specified reason for the local video failure.
      • 2: No permission to use the local video device.
      • 3: The local video capturer is in use.
      • 4: The local video capture fails. Check whether the capturer is working properly.
      • 5: The local video encoding fails.

    Parameters

    • evt: "localVideoStateChanged"
    • cb: function
        • (localVideoState: number, error: number): void
        • Parameters

          • localVideoState: number
          • error: number

          Returns void

    Returns this

  • Parameters

    • evt: string
    • listener: Function

    Returns this

pauseAllEffects

  • pauseAllEffects(): number
  • description

    Pauses all the audio effects.

    Returns number

    • 0: Success.
    • < 0: Failure.

pauseAudio

  • pauseAudio(): number
  • deprecated

    This method is deprecated. Use disableAudio instead.

    description

    Disables the audio function in the channel.

    Returns number

    • 0: Success.
    • < 0: Failure.

pauseAudioMixing

  • pauseAudioMixing(): number
  • description

    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
  • description

    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: number): number
  • description

    Plays a specified local or online audio effect file.

    This method allows you to set the loop count, pitch, pan, and gain of the audio effect file, as well as whether the remote user can hear the audio effect.

    To play multiple audio effect files simultaneously, call this method multiple times with different soundIds and filePaths. We recommend playing no more than three audio effect files at the same time.

    When the audio effect file playback finishes, the SDK returns the audioEffectFinished callback.

    Parameters

    • soundId: number

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

    • filePath: string

      The absolute path to the local audio effect file or the URL of the online audio effect file.

    • loopcount: number

      Sets the number of times the audio effect loops:

      • 0: Play the audio effect once.
      • 1: Play the audio effect twice.
      • -1: Play the audio effect in an indefinite loop until the stopEffect or stopEffect method is called.
    • pitch: number

      Sets the pitch of the audio effect. The value ranges between 0.5 and 2. The default value is 1 (no change to the pitch). The lower the value, the lower the pitch.

    • pan: number

      Sets the spatial position of the audio effect. The value ranges between -1.0 and 1.0:

      • 0.0: The audio effect displays ahead.
      • 1.0: The audio effect displays to the right.
      • -1.0: The audio effect displays to the left.
    • gain: number

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

    • publish: number

      Sets whether or not to publish the specified audio effect to the remote stream:

      • true: The locally played audio effect is published to the Agora Cloud and the remote users can hear it.
      • false: The locally played audio effect is not published to the Agora Cloud and the remote users cannot hear it.

    Returns number

    • 0: Success.
    • < 0: Failure.

preloadEffect

  • preloadEffect(soundId: number, filePath: string): number
  • description

    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
  • description

    Allows a user to rate a call after the call ends.

    Parameters

    • callId: string

      Pointer to 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) Pointer to 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
  • description

    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:

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

    Returns number

    • 0: Success.
    • < 0: Failure.

release

  • release(): number
  • description

    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.

    Returns number

    • 0: Success.
    • < 0: Failure.

removeInjectStreamUrl

  • removeInjectStreamUrl(url: string): number
  • description

    Removes the injected online media stream from a live broadcast.

    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
  • description

    Removes an RTMP stream from the CDN. (CDN live only) Note:

    • This method removes only one RTMP URL address each time it is called.
    • The RTMP URL address must not contain special characters, such as Chinese language characters.
    • This method applies to Live Broadcast only.

    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
  • description

    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
  • description

    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): void
  • description

    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.

    Returns void

resumeAllEffects

  • resumeAllEffects(): number
  • description

    Resumes playing all audio effects.

    Returns number

    • 0: Success.
    • < 0: Failure.

resumeAudio

  • resumeAudio(): number
  • deprecated

    This method is deprecated. Use enableAudio instead.

    description

    Resumes the audio function in the channel.

    Returns number

    • 0: Success.
    • < 0: Failure.

resumeAudioMixing

  • resumeAudioMixing(): number
  • description

    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
  • description

    Resumes playing a specified audio effect.

    Parameters

    • soundId: number

      sound id

    Returns number

    • 0: Success.
    • < 0: Failure.

sendStreamMessage

  • sendStreamMessage(streamId: number, msg: string): number
  • description

    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 profile or to the hosts in the Live-broadcast profile. If an audience in the Live-broadcast 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.

setAudioMixingPosition

  • setAudioMixingPosition(position: number): number
  • description

    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.

    Parameters

    • position: number

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

    Returns number

    • 0: Success.
    • < 0: Failure.

setAudioPlaybackDevice

  • setAudioPlaybackDevice(deviceId: string): number
  • description

    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
  • description

    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
  • description

    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): number
  • description

    Sets audio parameters and application scenarios.

    Parameters

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

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

      • 0: Default. In the Communication profile, the default value is 1: Speech standard; in the Live Broadcast profile, the default value is 2: Music standard.
      • 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.
    • scenario: 0 | 1 | 2 | 3 | 4 | 5

      Sets the audio application scenarios:

      • 0: Default.
      • 1: Chatroom entertainment. The entertainment scenario, supporting voice during gameplay.
      • 2: Education. The education scenario, prioritizing fluency and stability.
      • 3: Game streaming. The live gaming scenario, enabling the gaming audio effects in the speaker mode in a live broadcast scenario. Choose this scenario for high-fidelity music playback.
      • 4: Showroom. The showroom scenario, optimizing the audio quality with external professional equipment.
      • 5: Chatroom gaming. The game chatting scenario.

    Returns number

    • 0: Success.
    • < 0: Failure.

setAudioRecordingDevice

  • setAudioRecordingDevice(deviceId: string): number
  • description

    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
  • description

    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
  • description

    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: object): number
  • description

    Enables/Disables image enhancement and sets the options

    Parameters

    • enable: boolean

      Sets whether or not to enable image enhancement:

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

      The image enhancement options. It contains the following parameters:

      • lighteningContrastLevel: 0 | 1 | 2

        The lightening contrast level: 0 for low, 1 (default) for normal, and 2 for high.

      • lighteningLevel: number

        The brightness level. The value ranges from 0.0 (original) to 1.0.

      • rednessLevel: number

        The redness level. The value ranges between 0 (original) and 1. This parameter adjusts the red saturation level.

      • smoothnessLevel: number

        The sharpness level. The value ranges between 0 (original) and 1. This parameter is usually used to remove blemishes.

    Returns number

    • 0: Success.
    • < 0: Failure.

setCameraCapturerConfiguration

  • description

    Sets the camera capturer configuration.

    For a video call or live broadcast, 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. 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
  • description

    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 broadcasting
      • 2: for in-game

    Returns number

    • 0: Success.
    • < 0: Failure.

setClientRole

  • description

    Sets the role of a user (Live Broadcast 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 Live Broadcast 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

    • role: ClientRoleType

      The client role:

      • 1: The broadcaster
      • 2: The audience

    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
  • description

    Sets whether to receive all remote audio streams by default.

    You can call this method either before or after joining a channel. If you call this method after joining a channel, the remote audio streams of all subsequent users are not received.

    Parameters

    • mute: boolean

      Sets whether or not to receive/stop receiving all remote audio streams by default:

      • true: Stop receiving all remote audio streams by default.
      • false: (Default) Receive all remote audio streams by default.

    Returns number

    • 0: Success.
    • < 0: Failure.

setDefaultMuteAllRemoteVideoStreams

  • setDefaultMuteAllRemoteVideoStreams(mute: boolean): number
  • description

    Sets whether to receive all remote video streams by default.

    Parameters

    • mute: boolean

      Sets whether to receive/stop receiving all remote video streams by default:

      • true: Stop receiving all remote video streams by default.
      • false: (Default) Receive all remote video streams by default.

    Returns number

    • 0: Success.
    • < 0: Failure.

setEffectsVolume

  • setEffectsVolume(volume: number): number
  • description

    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
  • description

    Sets the built-in encryption mode.

    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
  • description

    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 CDN live streaming.

    Parameters

    • secret: string

      Encryption Password

    Returns number

    • 0: Success.
    • < 0: Failure.

setExternalAudioSource

  • setExternalAudioSource(enabled: boolean, samplerate: number, channels: number): number
  • description

    Sets the external audio source.

    Parameters

    • enabled: boolean

      Sets whether to enable/disable the external audio sink:

      • true: Enable the external audio source.
      • false: (Default) Disable the external audio source.
    • samplerate: number

      Sets the sample rate of the external audio source, which can be set as 8000, 16000, 32000, 44100, or 48000 Hz.

    • channels: number

      Sets the number of external audio source channels (two channels maximum).

    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.

    description

    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.

setInEarMonitoringVolume

  • setInEarMonitoringVolume(volume: number): number
  • description

    Sets the volume of the in-ear monitor.

    Parameters

    • volume: number

      Sets the volume of the in-ear monitor. The value ranges between 0 and 100 (default).

    Returns number

    • 0: Success.
    • < 0: Failure.

setLiveTranscoding

  • description

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

    Parameters

    Returns number

    • 0: Success.
    • < 0: Failure.

setLocalPublishFallbackOption

  • setLocalPublishFallbackOption(option: 0 | 1 | 2): number
  • description

    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, where there is no fallback for the locally published video stream when the uplink network conditions are poor. If option is set toSTREAM_FALLBACK_OPTION_AUDIO_ONLY, 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 CDN live streaming, because the remote CDN live user 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_AUDIO_ONLY = 2: Under poor uplink network conditions, the locally published video stream falls back to audio only.

    Returns number

    • 0: Success.
    • < 0: Failure.

setLocalVideoMirrorMode

  • setLocalVideoMirrorMode(mirrortype: 0 | 1 | 2): number
  • description

    Sets the local video mirror mode.

    Use this method before startPreview, or it does not take effect until you re-enable startPreview.

    Parameters

    • mirrortype: 0 | 1 | 2

      Sets the local video mirror mode:

      • 0: The default mirror mode, that is, the mode set by the SDK
      • 1: Enable the mirror mode
      • 2: Disable the mirror mode

    Returns number

    • 0: Success.
    • < 0: Failure.

setLocalVoiceChanger

setLocalVoiceEqualization

  • setLocalVoiceEqualization(bandFrequency: number, bandGain: number): number
  • description

    Sets the local voice equalization effect.

    Parameters

    • bandFrequency: number

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

    • bandGain: number

      Sets the gain of each band in dB. The value ranges between -15 and 15.

    Returns number

    • 0: Success.
    • < 0: Failure.

setLocalVoicePitch

  • setLocalVoicePitch(pitch: number): number
  • description

    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
  • description

    Sets the local voice reverberation.

    Parameters

    • reverbKey: number

      Sets the audio reverberation key.

      • AUDIO_REVERB_DRY_LEVEL = 0: Level of the dry signal (-20 to 10 dB).
      • AUDIO_REVERB_WET_LEVEL = 1: Level of the early reflection signal (wet signal) (-20 to 10 dB).
      • AUDIO_REVERB_ROOM_SIZE = 2: Room size of the reflection (0 to 100 dB).
      • AUDIO_REVERB_WET_DELAY = 3: Length of the initial delay of the wet signal (0 to 200 ms).
      • AUDIO_REVERB_STRENGTH = 4: Strength of the late reverberation (0 to 100).
    • value: number

      Sets the value of the reverberation key.

    Returns number

    • 0: Success.
    • < 0: Failure.

setLocalVoiceReverbPreset

setLogFile

  • setLogFile(filepath: string): number
  • description

    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.

setLogFileSize

  • setLogFileSize(size: number): number
  • description

    Sets the log file size (KB).

    The Agora SDK has two log files, each with a default size of 512 KB. If you set size as 1024 KB, the SDK outputs log files with a total maximum size of 2 MB. If the total size of the log files exceed the set value, the new output log files overwrite the old output log files.

    Parameters

    • size: number

      The SDK log file size (KB).

    Returns number

    • 0: Success.
    • < 0: Failure.

setLogFilter

  • setLogFilter(filter: number): number
  • description

    Sets the output log level of the SDK.

    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:

      • LOG_FILTER_OFF = 0: Do not output any log.
      • LOG_FILTER_DEBUG = 0x80f: Output all the API logs. Set your log filter as DEBUG if you want to get the most complete log file.
      • LOG_FILTER_INFO = 0x0f: Output logs of the CRITICAL, ERROR, WARNING and INFO level. We recommend setting your log filter as this level.
      • LOG_FILTER_WARNING = 0x0e: Output logs of the CRITICAL, ERROR and WARNING level.
      • LOG_FILTER_ERROR = 0x0c: Output logs of the CRITICAL and ERROR level.
      • LOG_FILTER_CRITICAL = 0x08: Output logs of the CRITICAL level.

    Returns number

    • 0: Success.
    • < 0: Failure.

setMixedAudioFrameParameters

  • setMixedAudioFrameParameters(sampleRate: number, samplesPerCall: number): number
  • description

    Sets the mixed audio format.

    Parameters

    • sampleRate: number

      Sets the sample rate (samplesPerSec) returned, which can be set as 8000, 16000, 32000, 44100, or 48000 Hz.

    • samplesPerCall: number

      Sets the sample points (samples) returned. samplesPerCall is usually set as 1024 for stream pushing. samplesPerCall = (int)(samplesPerSec × sampleInterval × numChannels), where sampleInterval ≥ 0.01 in seconds.

    Returns number

    • 0: Success.
    • < 0: Failure.

setPlaybackAudioFrameParameters

  • setPlaybackAudioFrameParameters(sampleRate: number, channel: 1 | 2, mode: 0 | 1 | 2, samplesPerCall: number): number
  • description

    Sets the audio playback format.

    Parameters

    • sampleRate: number

      Sets the sample rate (samplesPerSec) returned, which can be set as 8000, 16000, 32000, 44100, or 48000 Hz.

    • channel: 1 | 2

      Sets the number of audio channels (channels) returned:

      • 1: Mono
      • 2: Stereo
    • mode: 0 | 1 | 2

      Sets the use mode:

      • 0: Read-only mode: Users only read the AudioFrame data without modifying anything. For example, when users acquire the data with the Agora SDK then push the RTMP streams.
      • 1: Write-only mode: Users replace the AudioFrame data with their own data and pass the data to the SDK for encoding. For example, when users acquire the data.
      • 2: Read and write mode: Users read the data from AudioFrame, modify it, and then play it. For example, when users have their own sound-effect processing module and perform some voice pre-processing, such as a voice change.
    • samplesPerCall: number

      Sets the sample points (samples) returned. samplesPerCall is usually set as 1024 for stream pushing. samplesPerCall = (int)(samplesPerSec × sampleInterval × numChannels), where sampleInterval ≥ 0.01 in seconds.

    Returns number

    • 0: Success.
    • < 0: Failure.

setRecordingAudioFrameParameters

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

    Sets the audio recording format.

    Parameters

    • sampleRate: number

      Sets the sample rate (samplesPerSec) returned, which can set be as 8000, 16000, 32000, 44100 or 48000 Hz.

    • channel: 1 | 2

      Sets the number of audio channels (channels) returned:

      • 1: Mono
      • 2: Stereo
    • mode: 0 | 1 | 2

      Sets the use mode:

      • 0: Read-only mode: Users only read the AudioFrame data without modifying anything. For example, when users acquire the data with the Agora SDK then push the RTMP streams.
      • 1: Write-only mode: Users replace the AudioFrame data with their own data and pass the data to the SDK for encoding. For example, when users acquire the data.
      • 2: Read and write mode: Users read the data from AudioFrame, modify it, and then play it. For example, when users have their own sound-effect processing module and perform some voice pre-processing, such as a voice change.
    • samplesPerCall: number

      Sets the sample points (samples) returned. samplesPerCall is usually set as 1024 for stream pushing. samplesPerCall = (int)(samplesPerSec × sampleInterval × numChannels), where sampleInterval ≥ 0.01 in seconds.

    Returns number

    • 0: Success.
    • < 0: Failure.

setRemoteDefaultVideoStreamType

  • setRemoteDefaultVideoStreamType(streamType: StreamType): number
  • description

    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
  • description

    Sets the fallback option for the remotely subscribed video stream based on the network conditions.

    If option is set as STREAM_FALLBACK_OPTION_VIDEO_STREAM_LOW 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 remotely subscribed 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 remotely subscribed 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 remotely subscribed 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 remotely subscribed 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
  • description

    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.

setRemoteVideoStreamType

  • setRemoteVideoStreamType(uid: number, streamType: StreamType): number
  • description

    Sets the video stream type of the remotely subscribed video stream when the remote user sends dual streams.

    If the dual-stream mode is enabled by calling enableDualStreamMode, you will receive the high-video stream by default. This method allows the application to adjust the corresponding video-stream type according to the size of the video windows to save the bandwidth and calculation resources.

    If the dual-stream mode is not enabled, you will receive the high-video stream by default. The result after calling this method will be returned in onApiCallExecuted. The Agora SDK receives the high-video stream by default to save the bandwidth. If needed, users can switch to the low-video stream using this method.

    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
  • description

    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): void
  • Decide whether to use webgl/software/custom rendering.

    Parameters

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

    Returns void

setVideoDevice

  • setVideoDevice(deviceId: string): number
  • description

    Sets the video device using the device Id.

    Parameters

    • deviceId: string

      The device Id.

    Returns number

    • 0: Success.
    • < 0: Failure.

setVideoEncoderConfiguration

  • description

    Sets the video encoder configuration.

    description

    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.

    description

    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.

    description

    Sets the preference option for the video quality (Live Broadcast 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
  • description

    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
  • description

    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
  • description

    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

setVolumeOfEffect

  • setVolumeOfEffect(soundId: number, volume: number): number
  • description

    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

  • setupLocalVideo(view: Element): number
  • description

    Sets the local video view and the corresponding renderer.

    Parameters

    • view: Element

      The Dom element where you initialize your view.

    Returns number

    • 0: Success.
    • < 0: Failure.

setupLocalVideoSource

  • setupLocalVideoSource(view: Element): void
  • description

    Sets the video renderer for video source.

    Parameters

    • view: Element

      The dom element where video source should be displayed.

    Returns void

setupViewContentMode

  • setupViewContentMode(uid: number | "local" | "videosource", mode: 0 | 1): number
  • description

    Sets the view content mode.

    Parameters

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

      The user ID for operating streams.

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

    Returns number

    • 0: Success.
    • < 0: Failure.

startAudioDeviceLoopbackTest

  • startAudioDeviceLoopbackTest(interval: number): number
  • description

    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): number
  • description

    Starts playing and mixing the music file.

    This method mixes the specified local audio file with the audio stream from the microphone, or replaces the microphone’s audio stream with the specified local audio file. You can choose whether the other user can hear the local audio playback and specify the number of loop playbacks. This API also supports online music playback.

    The SDK returns the state of the audio mixing file playback in the audioMixingStateChanged callback.

    Note:

    • Call this method when you are in the channel, otherwise it may cause issues.
    • If the local audio mixing 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

      Specifies the absolute path of the local or online audio file to be mixed. Supported audio formats: mp3, aac, m4a, 3gp, and wav.

    • loopback: boolean

      Sets which user can hear the audio mixing:

      • true: Only the local user can hear the audio mixing.
      • false: Both users can hear the audio mixing.
    • replace: boolean

      Sets the audio mixing content:

      • true: Only publish the specified audio file; the audio stream from the microphone is not published.
      • false: The local audio file is mixed with the audio stream from the microphone.
    • cycle: number

      Sets the number of playback loops:

      • Positive integer: Number of playback loops.
      • -1: Infinite playback loops.

    Returns number

    • 0: Success.
    • < 0: Failure.

startAudioPlaybackDeviceTest

  • startAudioPlaybackDeviceTest(filepath: string): number
  • description

    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.

startAudioRecordingDeviceTest

  • startAudioRecordingDeviceTest(indicateInterval: number): number
  • description

    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.

startEchoTest

  • startEchoTest(): number
  • deprecated

    The method is deprecated. Use startEchoTestWithInterval instead.

    description

    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 Live Broadcast profile, only hosts can call this method.

    Returns number

    • 0: Success.
    • < 0: Failure.

startEchoTestWithInterval

  • startEchoTestWithInterval(interval: number): number
  • description

    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 Live Broadcast 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

  • description

    Starts the last-mile network probe test before joining a channel to get the uplink and downlink last-mile network statistics, including the bandwidth, packet loss, jitter, and round-trip time (RTT).

    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 Live Broadcast profile, a host should not call this method after joining a channel.

    Parameters

    Returns number

startPreview

  • startPreview(): number
  • description

    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.

startScreenCapture

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

    This method is deprecated. Use videoSourceStartScreenCaptureByScreen or videoSourceStartScreenCaptureByWindow instead.

    description

    Starts the screen sharing.

    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.

    description

    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.

startScreenCapturePreview

  • startScreenCapturePreview(): number
  • description

    Starts the video source preview.

    Returns number

    • 0: Success.
    • < 0: Failure.

startVideoDeviceTest

  • startVideoDeviceTest(): number
  • description

    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
  • description

    Stops playing all audio effects.

    Returns number

    • 0: Success.
    • < 0: Failure.

stopAudioDeviceLoopbackTest

  • stopAudioDeviceLoopbackTest(): number
  • description

    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
  • description

    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
  • description

    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.

stopAudioRecordingDeviceTest

  • stopAudioRecordingDeviceTest(): number
  • description

    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.

stopEchoTest

  • stopEchoTest(): number
  • description

    Stops the audio call test.

    Returns number

    • 0: Success.
    • < 0: Failure.

stopEffect

  • stopEffect(soundId: number): number
  • description

    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
  • description

    Stops the last-mile network probe test.

    Returns number

    • 0: Success.
    • < 0: Failure.

stopPreview

  • stopPreview(): number
  • description

    Stops the local video preview and closes the video.

    Returns number

    • 0: Success.
    • < 0: Failure.

stopScreenCapture

  • stopScreenCapture(): number
  • description

    Stops screen sharing.

    Returns number

    • 0: Success.
    • < 0: Failure.

stopScreenCapture2

  • stopScreenCapture2(): number
  • description

    Stop the video source.

    Returns number

    • 0: Success.
    • < 0: Failure.

stopScreenCapturePreview

  • stopScreenCapturePreview(): number
  • description

    Stops the video source preview.

    Returns number

    • 0: Success.
    • < 0: Failure.

stopVideoDeviceTest

  • stopVideoDeviceTest(): number
  • description

    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

  • subscribe(uid: number, view: Element): number
  • description

    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.

    Returns number

    • 0: Success.
    • < 0: Failure.

unloadEffect

  • unloadEffect(soundId: number): number
  • description

    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.

updateScreenCaptureRegion

  • updateScreenCaptureRegion(rect: object): number
  • description

    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.

videoSourceEnableDualStreamMode

  • videoSourceEnableDualStreamMode(enable: boolean): number
  • description

    Enables the dual-stream mode for the video source.

    Parameters

    • enable: boolean

      Whether or not to enable the dual-stream mode:

      • true: Enables the dual-stream mode.
      • false: Disables the dual-stream mode.

    Returns number

    • 0: Success.
    • < 0: Failure.

videoSourceEnableWebSdkInteroperability

  • videoSourceEnableWebSdkInteroperability(enabled: boolean): number
  • description

    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): number
  • description

    Initializes agora real-time-communicating video source with the app Id.

    Parameters

    • appId: string

      The app ID issued to you by Agora.

    Returns number

    • 0: Success.
    • < 0: Failure.

videoSourceJoin

  • videoSourceJoin(token: string, cname: string, info: string, uid: number): number
  • description

    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 Dashboard. 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) Pointer to 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

      Pointer to additional information about the channel. This parameter can be set to NULL or contain channel related information. Other users in the channel will not receive this message.

    • uid: number

      The User ID.

    Returns number

    • 0: Success.
    • < 0: Failure.

videoSourceLeave

  • videoSourceLeave(): number
  • description

    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.

videoSourceRelease

  • videoSourceRelease(): number
  • description

    Releases the video source object.

    Returns number

    • 0: Success.
    • < 0: Failure.

videoSourceRenewToken

  • videoSourceRenewToken(token: string): number
  • description

    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.

videoSourceSetChannelProfile

  • videoSourceSetChannelProfile(profile: number): number
  • description

    Sets the channel profile when using the video source.

    Parameters

    • profile: number

      Sets the channel profile:

      • 0:(Default) Communication.
      • 1: Live Broadcast.
      • 2: Gaming.

    Returns number

    • 0: Success.
    • < 0: Failure.

videoSourceSetLogFile

  • videoSourceSetLogFile(filepath: string): number
  • description

    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
  • description

    Sets the video source parameters.

    Parameters

    • parameter: string

      Sets the video source encoding parameters.

    Returns number

    • 0: Success.
    • < 0: Failure.

videoSourceSetScreenCaptureContentHint

  • description

    Updates the video source parameters.

    Parameters

    Returns number

    • 0: Success.
    • < 0: Failure.

videoSourceSetVideoProfile

  • videoSourceSetVideoProfile(profile: VIDEO_PROFILE_TYPE, swapWidthAndHeight?: boolean): number
  • description

    Sets the video profile when using the video source.

    Parameters

    Returns number

    • 0: Success.
    • < 0: Failure.

videoSourceStartScreenCaptureByScreen

  • description

    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

  • description

    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
  • description

    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
  • description

    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.