Options
All
  • Public
  • Public/Protected
  • All
Menu

Namespace agora

Index

Enumerations

Classes

Interfaces

Events

Variables

Functions

Events

on

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    • type: "error"
    • callback: typeof onError

    Returns void

  • Listens for the events during the Agora engine runtime.

    deprecated

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    deprecated

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    deprecated

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    deprecated

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    deprecated

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    deprecated

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    deprecated

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    deprecated

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    deprecated

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    deprecated

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    deprecated

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    deprecated

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    deprecated

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    deprecated

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    deprecated

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    deprecated

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    deprecated

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    deprecated

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    deprecated

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    deprecated

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    deprecated

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    deprecated

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    deprecated

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    deprecated

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    deprecated

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    deprecated

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    deprecated

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

  • Listens for the events during the Agora engine runtime.

    Parameters

    Returns void

Variables

Const COMPATIBLE_BITRATE

COMPATIBLE_BITRATE: -1 = -1

The compatible bitrate set in the setVideoEncoderConfiguration method. The bitrate remains the same regardless of the channel profile. If you choose this mode in the LIVE_BROADCASTING profile, the video frame rate may be lower than the set value.

Const DEFAULT_MIN_BITRATE

DEFAULT_MIN_BITRATE: -1 = -1

Use the default minimum bitrate.

Const STANDARD_BITRATE

STANDARD_BITRATE: 0 = 0

(Recommended) The standard bitrate set in the setVideoEncoderConfiguration method.

In this mode, the bitrates differ between the live interactive streaming and communication profiles:

  • COMMUNICATION profile: The video bitrate is the same as the base bitrate.
  • LIVE_BROADCASTING profile: The video bitrate is twice the base bitrate.

Functions

addInjectStreamUrl

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

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

    The addInjectStreamUrl method call triggers the following callbacks:

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

    Note

    • Ensure that you enable the RTMP Converter service before using this function.
    • This method applies to the SDK of v3.1.2 and later.
    • This method applies to the LIVE_BROADCASTING profile only.
    • You can inject only one media stream into the channel at the same time.

    Parameters

    • url: string

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

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

      agora.InjectStreamConfig contains the configuration of the added voice or video stream.

    Returns number

    • 0: Success.
    • < 0: Failure.
      • -2(ERR_INVALID_ARGUMENT): The injected URL does not exist. Call this method again to inject the stream and ensure that the URL is valid.
      • -3(ERR_NOT_READY): The user is not in the channel.
      • -4(ERR_NOT_SUPPORTED): The channel profile is not LIVE_BROADCASTING. Call the setChannelProfile method and set the channel profile to LIVE_BROADCASTING before calling this method.
      • -7(ERR_NOT_INITIALIZED): The SDK is not initialized. Ensure that the Agora engine is initialized before calling this method.

addPublishStreamUrl

  • addPublishStreamUrl(url: string, transcodingEnabled: boolean): number
  • 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 onStreamPublished callback.

    The addPublishStreamUrl method call triggers the onRtmpStreamingStateChanged callback on the local client to report the state of adding a local stream to the CDN.

    Note

    • Ensure that the user joins the channel before calling this method.
    • Ensure that you enable the RTMP Converter service before using this function.
    • This method adds only one stream RTMP URL address each time it is called.
    • This method applies to LIVE_BROADCASTING only.

    Parameters

    • url: string

      The CDN streaming URL in the RTMP format. The maximum length of this parameter is 1024 bytes. The RTMP URL address must not contain special characters, such as Chinese language characters.

    • transcodingEnabled: boolean

      Sets whether transcoding is enabled/disabled:

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

    Returns number

    • 0: Success.
    • < 0: Failure.
      • -2(ERR_INVALID_ARGUMENT): The RTMP URL address is null or has a string length of 0.
      • -7(ERR_NOT_INITIALIZED): You have not initialized the Agora engine when publishing the stream.

addVideoWatermark

  • Adds a watermark image to the local video.

    This method adds a PNG watermark image to the local video in the live streaming. Once the watermark image is added, all the audience in the channel (CDN audience included), and the recording device can see and capture it. Agora supports adding only one watermark image onto the local video, and the newly watermark image replaces the previous one.

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

    Note

    • Ensure that you have called the enableVideo method to enable the video module before calling this method.
    • If you only want to add a watermark image to the local video for the audience in the CDN live streaming channel to see and capture, you can call this method or the setLiveTranscoding method.
    • This method supports adding a watermark image in the PNG file format only. Supported pixel formats of the PNG image are RGBA, RGB, Palette, Gray, and Alpha_gray.
    • If the dimensions of the PNG image differ from your settings in this method, the image will be cropped or zoomed to conform to your settings.
    • If you have enabled the local video preview by calling the startPreview method, you can use the visibleInPreview member in the WatermarkOptions class to set whether or not the watermark is visible in preview.
    • If you have enabled the mirror mode for the local video, the watermark on the local video is also mirrored. To avoid mirroring the watermark, Agora recommends that you do not use the mirror and watermark functions for the local video at the same time. You can implement the watermark function in your application layer.

    Parameters

    • watermarkUrl: string

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

    • options: WatermarkOptions

      The watermark's options to be added. See WatermarkOptions.

    Returns number

    • 0: Success.
    • < 0: Failure.

adjustAudioMixingPlayoutVolume

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

    note

    Call this method when you are in a channel.

    Parameters

    • volume: number

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

    Returns number

    • 0: Success.
    • < 0: Failure.

adjustAudioMixingPublishVolume

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

    note

    Call this method when you are in a channel.

    Parameters

    • volume: number

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

    Returns number

    • 0: Success.
    • < 0: Failure.

adjustAudioMixingVolume

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

    Call this method when you are in a channel.

    note

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

    Parameters

    • volume: number

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

    Returns number

    • 0: Success.
    • < 0: Failure.

adjustPlaybackSignalVolume

  • adjustPlaybackSignalVolume(volume: number): number
  • Adjusts the playback volume of all remote users.

    Note

    • This method adjusts the playback volume that is the mixed volume of all remote users.
    • (Since v3.1.2) To mute the local audio playback, call both the adjustPlaybackSignalVolume and adjustAudioMixingVolume methods and set the volume as 0.

    Parameters

    • volume: number

      The playback volume of all remote users. To avoid echoes and improve call quality, Agora recommends setting the value of volume between 0 and 100. If you need to set the value higher than 100, contact support@agora.io first.

      • 0: Mute.
      • 100: Original volume.

    Returns number

    • 0: Success.
    • < 0: Failure.

adjustRecordingSignalVolume

  • adjustRecordingSignalVolume(volume: number): number
  • Adjusts the recording volume.

    Parameters

    • volume: number

      Recording volume. To avoid echoes and improve call quality, Agora recommends setting the value of volume between 0 and 100. If you need to set the value higher than 100, contact support@agora.io first.

      • 0: Mute.
      • 100: Original volume.

    Returns number

    • 0: Success.
    • < 0: Failure.

adjustUserPlaybackSignalVolume

  • adjustUserPlaybackSignalVolume(uid: number, volume: number): number
  • Adjusts the playback volume of a specified remote user.

    You can call this method as many times as necessary to adjust the playback volume of different remote users, or to repeatedly adjust the playback volume of the same remote user.

    Note

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

    Parameters

    • uid: number

      The ID of the remote user.

    • volume: number

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

      • 0: Mute.
      • 100: Original volume.

    Returns number

    • 0: Success.
    • < 0: Failure.

clearVideoWatermarks

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

    Returns number

    • 0: Success.
    • < 0: Failure.

complain

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

    Parameters

    • callId: string

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

    • description: string

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

    Returns number

    • 0: Success.
    • < 0: Failure.

createDataStream

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

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

    note

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

    Parameters

    • streamId: number

      The ID of the created data stream.

    • reliable: boolean

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

      • true: The recipients receive the data stream from the sender within five seconds. If the recipient does not receive the data stream within five seconds, an error is reported to the application.
      • false: There is no guarantee that the recipients receive the data stream within five seconds and no error message is reported for any delay or missing data stream.
    • 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

    • 0: Success.
    • < 0: Failure.

disableAudio

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

    Note

    • This method affects the internal engine and can be called after 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 enableLocalAudio and muteLocalAudioStream methods to capture, process, and send the local audio streams.

    Returns number

    • 0: Success.
    • < 0: Failure.

disableLastmileTest

  • disableLastmileTest(): number
  • Disables the network connection quality test.

    Returns number

    • 0: Success.
    • < 0: Failure.

disableVideo

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

    This method can be called before joining a channel or during a call. If this method is called before joining a channel, the call starts in audio mode. If this method is called during a video call, the video mode switches to the audio mode. To enable the video module, call the enableVideo method.

    A successful disableVideo method call triggers the onUserEnableVideo (false) callback on the remote client.

    Note

    • This method affects the internal engine and can be called after the leaveChannel method.
    • This method resets the internal engine and takes some time to take effect. We recommend using the following API methods to control the video engine modules separately:

    Returns number

    • 0: Success.
    • < 0: Failure.

enableAudio

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

    The audio mode is enabled by default.

    Note

    • This method affects the internal engine and can be called after the leaveChannel method. You can call this method either before or after joining a channel.
    • This method resets the internal engine and takes some time to take effect. We recommend using the following API methods to control the audio engine modules separately:

    Returns number

    • 0: Success.
    • < 0: Failure.

enableAudioVolumeIndication

  • enableAudioVolumeIndication(interval: number, smooth: number, report_vad: boolean): number
  • Enables the onAudioVolumeIndication 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 onAudioVolumeIndication callback at the set time interval, whether or not 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. Do not set interval < 10 ms, or the onAudioVolumeIndication callback will not be triggered.
    • smooth: number

      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.

    • report_vad: boolean

      true: Enable the voice activity detection of the local user. Once it is enabled, the vad parameter of the onAudioVolumeIndication callback reports the voice activity status of the local user.

      • false: (Default) Disable the voice activity detection of the local user. Once it is disabled, the vad parameter of the onAudioVolumeIndication callback does not report the voice activity status of the local user, except for the scenario where the engine automatically detects the voice activity of the local user.

    Returns number

    • 0: Success.
    • < 0: Failure.

enableDualStreamMode

  • enableDualStreamMode(enabled: boolean): number
  • Sets the stream mode to the single-stream (default) or dual-stream mode. (LIVE_BROADCASTING only.)

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

    Parameters

    • enabled: boolean

      Sets the stream mode:

      • true: Dual-stream mode.
      • false: Single-stream mode.

    Returns number

enableEncryption

  • Enables/Disables the built-in encryption.

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

    All users in the same channel must use the same encryption mode and encryption key. Once all users leave the channel, the encryption key of this channel is automatically cleared.

    Note

    • If you enable the built-in encryption, you cannot use the RTMP streaming function.
    • Agora supports four encryption modes. If you choose an encryption mode (excepting SM4_128_ECB mode), you need to add an external encryption library when integrating the Android or iOS SDK.

    Parameters

    • enabled: boolean

      Whether to enable the built-in encryption:

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

      Configurations of built-in encryption schemas. See EncryptionConfig.

    Returns number

    • 0: Success.
    • < 0: Failure.
    • -2(ERR_INVALID_ARGUMENT): An invalid parameter is used. Set the parameter with a valid value.
    • -4(ERR_NOT_SUPPORTED): The encryption mode is incorrect or the SDK fails to load the external encryption library. Check the enumeration or reload the external encryption library.
    • -7(ERR_NOT_INITIALIZED): The SDK is not initialized. Initialize the Agora engine before calling this method.

enableFaceDetection

  • enableFaceDetection(enabled: boolean): number
  • Enables/Disables face detection for the local user.

    Once face detection is enabled, the SDK triggers the onFacePositionChanged callback to report the face information of the local user, which includes the following aspects:

    • The width and height of the local video.
    • The position of the human face in the local video.
    • The distance between the human face and the device screen.

    Parameters

    • enabled: boolean

      Determines whether to enable the face detection function for the local user:

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

    Returns number

    • 0: Success.
    • < 0: Failure.

enableInEarMonitoring

  • enableInEarMonitoring(enabled: boolean): number
  • Enables in-ear monitoring.

    Parameters

    • enabled: boolean

      Determines whether to enable in-ear monitoring.

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

    Returns number

    • 0: Success.
    • < 0: Failure.

enableLastmileTest

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

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

    Before a user joins 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, and hence may affect communication quality.

    Call the disableLastmileTest method to disable this test after receiving the onLastmileQuality callback, and before joining a channel.

    Note

    • Do not call any other methods before receiving the onLastmileQuality callback. Otherwise, the callback may be interrupted by other methods, and hence may not be triggered.
    • A host should not call this method after joining a channel (when in a call).
    • If you call this method to test the last-mile quality, the SDK consumes the bandwidth of a video stream, whose bitrate corresponds to the bitrate you set in the setVideoEncoderConfiguration method. After you join the channel, whether you have called the disableLastmileTest method or not, the SDK automatically stops consuming the bandwidth.

    Returns number

    • 0: Success.
    • < 0: Failure.

enableLocalAudio

  • enableLocalAudio(enabled: boolean): number
  • Disables/Re-enables the local audio function.

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

    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.

    Once the local audio function is disabled or re-enabled, the SDK triggers the onLocalAudioStateChanged callback, which reports LOCAL_AUDIO_STREAM_STATE_STOPPED(0) or LOCAL_AUDIO_STREAM_STATE_RECORDING(1).

    Note

    This method is different from the muteLocalAudioStream method:

    • enableLocalAudio: Disables/Re-enables the local audio capturing and processing. If you disable or re-enable local audio recording using the enableLocalAudio` method, the local user may hear a pause in the remote audio playback.
    • muteLocalAudioStream: Sends/Stops sending the local audio streams.

    Parameters

    • enabled: boolean

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

      • true: (Default) Re-enable the local audio function, that is, to start the local audio capturing device (for example, the microphone).
      • false: Disable the local audio function, that is, to stop local audio capturing.

    Returns number

    • 0: Success.
    • < 0: Failure.

enableLocalVideo

  • enableLocalVideo(enabled: boolean): number
  • Enables/Disables the local video capture.

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

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

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

    note

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

    Parameters

    • enabled: 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 the other remote users.

    Returns number

    • 0: Success.
    • < 0: Failure.

enableSoundPositionIndication

  • enableSoundPositionIndication(enabled: boolean): number
  • Enables/Disables stereo panning for remote users.

    Ensure that you call this method before joinChannel to enable stereo panning for remote users so that the local user can track the position of a remote user by calling setRemoteVoicePosition.

    Parameters

    • enabled: 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
  • Enables the video module.

    Call this method either before joining a channel or during a call. If this method is called before joining a channel, the call starts in the video mode. If this method is called during an audio call, the audio mode switches to the video mode. To disable the video module, call the disableVideo method.

    A successful enableVideo method call triggers the onUserEnableVideo(true) callback on the remote client.

    Note

    • This method affects the internal engine and can be called after the leaveChannel method.
    • 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(enabled: boolean): number
  • Enables interoperability with the Agora Web SDK.

    deprecated

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

    Note

    • This method applies only to the LIVE_BROADCASTING profile. In the COMMUNICATION profile, interoperability with the Agora Web SDK is enabled by default.
    • If the channel has Web SDK users, ensure that you call this method, or the video of the Native user will be a black screen for the Web user.

    Parameters

    • enabled: 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
  • Retrieves the playback position (ms) of the music file.

    Call this method 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
  • Retrieves the duration (ms) of the music file.

    Call this method when you are in a channel.

    Returns number

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

getAudioMixingPlayoutVolume

  • getAudioMixingPlayoutVolume(): number
  • Retrieves the audio mixing volume for local playback.

    This method helps troubleshoot audio volume related issues.

    note

    Call this method when you are in a channel.

    Returns number

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

getAudioMixingPublishVolume

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

    This method helps troubleshoot audio volume related issues.

    note

    Call this method 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.

getCallId

  • getCallId(): string | null
  • 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 | null

    The current call ID.

getConnectionState

getEffectsVolume

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

    The value ranges between 0.0 and 100.0.

    Returns number

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

getErrorDescription

  • getErrorDescription(code: number): string | null

getUserInfoByUid

  • getUserInfoByUid(uid: number): UserInfo | null
  • 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 UserInfo, and triggers the onUserInfoUpdated callback on the local client.

    After receiving the onUserInfoUpdated callback, you can call this method to get the user account of the remote user from the UserInfo interface by passing in the user ID.

    Parameters

    • uid: number

      The user ID of the remote user. Ensure that you set this parameter.

    Returns UserInfo | null

    A UserInfo interface that identifies the user.

getUserInfoByUserAccount

  • getUserInfoByUserAccount(userAccount: string): UserInfo | null
  • 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 UserInfo, and triggers the onUserInfoUpdated callback on the local client.

    After receiving the onUserInfoUpdated callback, you can call this method to get the user ID of the remote user from the UserInfo interface by passing in the user account.

    Parameters

    • userAccount: string

      The user account of the user. Ensure that you set this parameter.

    Returns UserInfo | null

    A UserInfo interface that identifies the user.

getVersion

  • getVersion(): string
  • Retrieves the SDK version number.

    Returns string

    The version of the current SDK in the string format. For example, "3.1.2".

init

  • init(appId: string): number
  • Initializes the Agora engine.

    Unless otherwise specified, all the methods provided by the Agora engine are executed asynchronously. Agora recommends calling these methods in the same thread.

    Note

    • You must initializes the Agora engine before calling any other method.
    • You can initializes the Agora engine either by calling this method or by calling initWithAreaCode. The difference between initWithAreaCode and this method is that initWithAreaCode enables you to specify the region for connection.

    Parameters

    • appId: string

      The App ID issued to you by Agora. See How to get the App ID. Only users in apps with the same App ID can join the same channel and communicate with each other. To change your App ID, call release to release the current Agora engine, and after release returns 0, call init to initializes the Agora engine with a new App ID.

    Returns number

    • The Agora engine, if the method call succeeds.
    • < 0, if the method call fails.
      • ERR_INVALID_APP_ID(101): The app ID is invalid. Check if it is in the correct format.

initWithAreaCode

  • initWithAreaCode(appId: string, areaCode: AREA_CODE): number
  • Initializes the Agora engine.

    Unless otherwise specified, all the methods provided by the Agora engine are executed asynchronously. Agora recommends calling these methods in the same thread.

    Note

    • You must initializes the Agora engine before calling any other method.
    • You can initializes the Agora engine either by calling this method or by calling init. The difference between init and this method is that this method enables you to specify the region for connection.
    • The SDK supports initializing only one Agora engine for an app for now.
    note

    The SDK supports specifying only one region.

    Parameters

    • appId: string

      The App ID issued to you by Agora. See How to get the App ID. Only users in apps with the same App ID can join the same channel and communicate with each other. Use an App ID to initialize only one Agora engine. To change your App ID, call release to release the current Agora engine, and after release returns 0, call initWithAreaCode to initializes the Agora engine with a new App ID.

    • areaCode: AREA_CODE

      The region for connection. This advanced feature applies to scenarios that have regional restrictions.

      For the regions that Agora supports, see AREA_CODE. After specifying the region, the SDK connects to the Agora servers within that region.

    Returns number

    • The Agora engine, if the method call succeeds.
    • < 0, if the method call fails.
      • ERR_INVALID_APP_ID(101): The app ID is invalid. Check if it is in the correct format.

isSpeakerphoneEnabled

  • isSpeakerphoneEnabled(): boolean
  • Checks whether the speakerphone is enabled.

    Returns boolean

    • true: The speakerphone is enabled, and the audio plays from the speakerphone.
    • false: The speakerphone is not enabled, and the audio plays from devices other than the speakerphone. For example, the headset or earpiece.

joinChannel

  • joinChannel(token: string, channelId: string, info?: string, uid?: number): number
  • Joins a channel with the user ID.

    Users in the same channel can talk to each other, and multiple users in the same channel can start a group chat. Users with different App IDs cannot call each other.

    You must call the leaveChannel method to exit the current call before entering another channel.

    A successful joinChannel method call triggers the following callbacks:

    • The local client: onJoinChannelSuccess
    • The remote client: onUserJoined , if the user joining the channel is in the COMMUNICATION profile, or is a host in the LIVE_BROADCASTING profile.

    When the connection between the client and Agora 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 onRejoinChannelSuccess callback on the local client.

    note

    A channel does not accept duplicate uids, such as two users with the same uid. If you set uid as 0, the system automatically assigns a uid. If you want to join a channel from different devices, ensure that each device has a different uid.

    warning

    Ensure that the App ID used for creating the token is the same App ID used by the init method for initializing the Agora engine. Otherwise, the CDN live streaming may fail.

    Parameters

    • token: string

      The token for authentication:

      • In situations not requiring high security: You can use the temporary token generated at Console. For details, see Get a temporary token.
      • In situations requiring high security: Set it as the token generated at your server. For details, see Get a token.
    • channelId: string

      The unique channel name for the Agora RTC session in the string format smaller than 64 bytes. Supported characters:

      • All lowercase English letters: a to z.
      • All uppercase English letters: A to Z.
      • All numeric characters: 0 to 9.
      • The space character.
      • Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
    • Default value info: string = ""

      (Optional) The 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.

    • Default value uid: number = 0

      (Optional) 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 and returns a uid in the onJoinChannelSuccess callback. Your application must record and maintain the returned uid since the SDK does not do so.

    Returns number

    • 0(ERR_OK): Success.
    • < 0: Failure.
      • -2(ERR_INVALID_ARGUMENT): The parameter is invalid.
      • -3(ERR_NOT_READY): The SDK fails to be initialized. You can try re-initializing the SDK.

joinChannelWithUserAccount

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

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

    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 for authentication:

      • In situations not requiring high security: You can use the temporary token generated at Console. For details, see Get a temporary token.
      • In situations requiring high security: Set it as the token generated at your server. For details, see Get a token.
    • channelId: string

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

      • All lowercase English letters: a to z.
      • All uppercase English letters: A to Z.
      • All numeric characters: 0 to 9.
      • The space character.
      • Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
    • userAccount: string

      The user account. The maximum length of this parameter is 255 bytes. Ensure that you set this parameter and do not set it as null. Supported character scopes are:

      • All lowercase English letters: a to z.
      • All uppercase English letters: A to Z.
      • All numeric characters: 0 to 9.
      • The space character.
      • Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".

    Returns number

    • 0: Success.
    • < 0: Failure.
      • -2(ERR_INVALID_ARGUMENT)
      • -3(ERR_NOT_READY)
      • -5(ERR_REFUSED)

leaveChannel

  • leaveChannel(): number
  • Allows a user to leave a channel, such as hanging up or exiting a call.

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

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

    This method call is asynchronous, and the user has not left the channel when the method call returns. Once the user leaves the channel, the SDK triggers the onLeaveChannel callback. A successful leaveChannel method call triggers the following callbacks:

    • The local client: onLeaveChannel.
    • The remote client: onUserOffline, if the user leaving the channel is in the COMMUNICATION channel, or is a host in the LIVE_BROADCASTING profile.

    Note

    • If you call the release method immediately after the leaveChannel method, the leaveChannel process interrupts, and the onLeaveChannel callback is not triggered.
    • If you call the leaveChannel method during a CDN live streaming, the SDK triggers the removePublishStreamUrl method.

    Returns number

    • 0(ERR_OK): Success.
    • < 0: Failure.
      • -1(ERR_FAILED): A general error occurs (no specified reason).
      • -2(ERR_INVALID_ARGUMENT): The parameter is invalid.
      • -7(ERR_NOT_INITIALIZED): The SDK is not initialized.

muteAllRemoteAudioStreams

  • muteAllRemoteAudioStreams(mute: boolean): number
  • Stops/Resumes receiving all remote users' audio streams.

    Parameters

    • mute: boolean

      Sets whether to receive or stop receiving all remote users' audio streams.

      • true: Stops receiving all remote users' audio streams.
      • false: (Default) Receives all remote users' audio streams.

    Returns number

    • 0: Success.
    • < 0: Failure.

muteAllRemoteVideoStreams

  • muteAllRemoteVideoStreams(mute: boolean): number
  • Stops/Resumes receiving all video stream from a specified remote user.

    Parameters

    • mute: boolean

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

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

    Returns number

    • 0: Success.
    • < 0: Failure.

muteLocalAudioStream

  • muteLocalAudioStream(mute: boolean): number
  • Stops/Resumes sending the local audio stream.

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

    Note

    • When mute is set as true, this method does not disable the microphone, which does not affect any ongoing recording.
    • If you call setChannelProfile after this method, the SDK resets whether or not to mute the local audio according to the channel profile and user role. Therefore, we recommend calling this method after the setChannelProfile method.

    Parameters

    • mute: boolean

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

      • true: Stops sending the local audio stream.
      • false: (Default) Sends the local audio stream.

    Returns number

    • 0: Success.
    • < 0: Failure.

muteLocalVideoStream

  • muteLocalVideoStream(mute: boolean): number
  • Stops/Resumes sending the local video stream.

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

    Note

    • When set to true, this method does not disable the camera which does not affect the retrieval of the local video streams. This method executes faster than the enableLocalVideo method which controls the sending of the local video stream.
    • If you call setChannelProfile after this method, the SDK resets whether or not to mute the local video according to the channel profile and user role. Therefore, we recommend calling this method after the setChannelProfile method.

    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(userId: number, mute: boolean): number
  • Stops/Resumes receiving a specified remote user's audio stream.

    note

    If you called the muteAllRemoteAudioStreams method and set mute as true to stop receiving all remote users' audio streams, call the muteAllRemoteAudioStreams method and set mute as false before calling this method. The muteAllRemoteAudioStreams method sets all remote audio streams, while the muteAllRemoteAudioStreams method sets a specified remote audio stream.

    Parameters

    • userId: number

      User ID of the specified remote user sending the audio.

    • mute: boolean

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

      • true: Stops receiving the specified remote user's audio stream.
      • false: (Default) Receives the specified remote user's audio stream.

    Returns number

    • 0: Success.
    • < 0: Failure.

muteRemoteVideoStream

  • muteRemoteVideoStream(userId: number, mute: boolean): number
  • Stops/Resumes receiving the video stream from a specified remote user.

    note

    If you called the muteAllRemoteVideoStreams method and set mute as true to stop receiving all remote video streams, call the muteAllRemoteVideoStreams method and set mute as false before calling this method.

    Parameters

    • userId: number

      User ID of the specified remote user.

    • mute: boolean

      Sets whether to stop/resume receiving the video stream from a specified remote user:

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

    Returns number

    • 0: Success.
    • < 0: Failure.

off

  • off(type: string, callback?: Function, target?: any): void
  • Stops monitoring the events during the Agora engine runtime.

    Parameters

    • type: string
    • Optional callback: Function
    • Optional target: any

    Returns void

pauseAllEffects

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

    Returns number

    • 0: Success.
    • < 0: Failure.

pauseAudioMixing

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

    Call this method when you are in a channel.

    Returns number

    • 0: Success.
    • < 0: Failure.

pauseEffect

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

    Parameters

    • soundId: number

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

    Returns number

    • 0: Success.
    • < 0: Failure.

playEffect

  • playEffect(soundId: number, filePath: string, loopCount: number, pitch: number, pan: number, gain: number, publish: Boolean): number
  • 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.

    note

    If the audio effect is preloaded into the memory through the preloadEffect method, the value of soundID must be the same as that in the preloadEffect method.

    Parameters

    • soundId: number

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

    • filePath: string

      Specifies the absolute path (including the suffixes of the filename) to the local audio effect file or the URL of the online audio effect file, for example, c:/music/audio.mp4. Supported audio formats: mp3, mp4, m4a, aac, 3gp, mkv and wav.

    • 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 stopAllEffects 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 and 100 (default). The lower the value, the lower the volume of the audio effect.

    • publish: Boolean

      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
  • 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, description?: undefined | string): number
  • Allows a user to rate a call after the call ends.

    Parameters

    • callId: string

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

    • rating: number

      Rating of the call. The value is between 1 (lowest score) and 5 (highest score). If you set a value out of this range, the ERR_INVALID_ARGUMENT(-2) error returns.

    • Optional description: undefined | string

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

    Returns number

    • 0: Success.
    • < 0: Failure.

registerLocalUserAccount

  • registerLocalUserAccount(appId: string, userAccount: string): number
  • Registers a user account.

    Once registered, the user account can be used to identify the local user when the user joins the channel. After the user successfully registers a user account, the SDK triggers the onLocalUserRegistered callback on the local client, reporting the user ID and user account of the local user.

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

    • Call the registerLocalUserAccount method to create a user account, and then the joinChannelWithUserAccount method to join the channel.
    • Call the joinChannelWithUserAccount method to join the channel.

    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.

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

    • 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. Supported character scopes are:

      • All lowercase English letters: a to z.
      • All uppercase English letters: A to Z.
      • All numeric characters: 0 to 9.
      • The space character.
      • Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".

    Returns number

    • 0: Success.
    • < 0: Failure.

registerMediaMetadataObserver

  • Registers the metadata observer.

    You need to specify the metadata type in this method.

    This method enables you to add synchronized metadata in the video stream for more diversified live interactive streaming, such as sending shopping links, digital coupons, and online quizzes.

    Note

    • Call this method before the joinChannel method.
    • This method applies to the LIVE_BROADCASTING channel profile.

    Parameters

    Returns number

    • 0: Success.
    • < 0: Failure.

registerPacketObserver

  • registerPacketObserver(observer: any): number
  • Registers a packet observer.

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

    Note

    • The size of the packet sent to the network after processing should not exceed 1200 bytes, otherwise, the packet may fail to be sent.
    • Ensure that both receivers and senders call this method, otherwise, you may meetĀ undefined behaviors such as no voice and black screen.
    • When you use CDN live streaming, recording or storage functions, Agora doesn't recommend calling this method.

    Parameters

    • observer: any

      The registered packet observer.

    Returns number

    • 0: Success.
    • < 0: Failure.

release

  • release(): void
  • Releases all resources of the Agora engine.

    Use this method for apps in which users occasionally make voice or video calls. When users do not make calls, you can free up resources for other operations. Once you call release to release the Agora engine, you cannot use any method or callback in the SDK any more.

    If you want to use the real-time communication functions again, you must call init to initialize a new Agora engine.

    note

    If you want to reinitialize the Agora engine after releasing the current one, ensure that you wait till the release method completes executing.

    Returns void

removeInjectStreamUrl

  • removeInjectStreamUrl(url: string): number
  • Removes the voice or video stream URL address from the live streaming.

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

    note

    If this method is called successfully, the SDK triggers the onUserOffline callback and returns a stream uid of 666.

    Parameters

    • url: string

      The URL address of the injected stream to be removed.

    Returns number

    • 0: Success.
    • < 0: Failure.

removePublishStreamUrl

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

    This method removes the RTMP URL address (added by the addPublishStreamUrl method) from a CDN live stream. The SDK returns the result of this method call in the onStreamUnpublished callback.

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

    Note

    • This method removes only one RTMP URL address each time it is called.
    • The RTMP URL address must not contain special characters, such as Chinese language characters.
    • This method applies to LIVE_BROADCASTING 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.

renewToken

  • renewToken(token: string): number
  • Gets a new token when the current token expires after a period of time.

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

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

    Parameters

    • token: string

      The new token.

    Returns number

    • 0(ERR_OK): Success.
    • < 0: Failure.
      • -1(ERR_FAILED): A general error occurs (no specified reason).
      • -2(ERR_INVALID_ARGUMENT): The parameter is invalid.
      • -7(ERR_NOT_INITIALIZED): The SDK is not initialized.

resumeAllEffects

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

    Returns number

    • 0: Success.
    • < 0: Failure.

resumeAudioMixing

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

    Call this method when you are in a channel.

    Returns number

    • 0: Success.
    • < 0: Failure.

resumeEffect

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

    Parameters

    • soundId: number

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

    Returns number

    • 0: Success.
    • < 0: Failure.

sendCustomReportMessage

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

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

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

    Parameters

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

    Returns number

sendMetadata

  • sendMetadata(__namedParameters: { buffer: Uint8Array; size: number; timeStampMs: number; uid: number }): number
  • Sends the metadata.

    Note

    Parameters

    • __namedParameters: { buffer: Uint8Array; size: number; timeStampMs: number; uid: number }
      • buffer: Uint8Array

        The sent metadata.

      • size: number

        The size of the sent metadata.

      • timeStampMs: number

        The timestamp (ms) of the metadata.

      • uid: number

        ID of the user who sends the metadata.

    Returns number

    • 0: Success.
    • < 0: Failure.

sendStreamMessage

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

    The SDK has the following restrictions on this method:

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

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

    note

    This method applies only to the COMMUNICATION profile or to the hosts in the LIVE_BROADCASTING profile. If an audience in the LIVE_BROADCASTING profile calls this method, the audience may be switched to a host.

    Parameters

    • streamId: number

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

    • data: Uint8Array

      The sent data.

    • length: number

      Length of the sent data.

    Returns number

    • 0: Success.
    • < 0: Failure.

setAudioMixingPitch

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

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

    note

    Call this method after calling startAudioMixing.

    Parameters

    • pitch: number

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

    Returns number

    • 0: Success.
    • < 0: Failure.

setAudioMixingPosition

  • setAudioMixingPosition(pos: number): number
  • Sets the playback position of the music file to a different starting position (the default plays from the beginning).

    Parameters

    • pos: number

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

    Returns number

    • 0: Success.
    • < 0: Failure.

setAudioProfile

  • Sets the audio parameters and application scenarios.

    Note

    • The setAudioProfile method must be called before the joinChannel method.
    • In the COMMUNICATION and LIVE_BROADCASTING profiles, the bitrate may be different from your settings due to network self-adaptation.
    • In scenarios requiring high-quality audio, for example, a music teaching scenario, we recommend setting profile as AUDIO_PROFILE_MUSIC_HIGH_QUALITY(4) and scenario as AUDIO_SCENARIO_GAME_STREAMING(3).

    Parameters

    Returns number

    • 0: Success.
    • < 0: Failure.

setBeautyEffectOptions

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

    Note

    • Call this method after calling the enableVideo method.
    • Currently this method does not apply for macOS.

    Parameters

    • enabled: boolean

      Sets whether or not to enable image enhancement:

      • true: enables image enhancement.
      • false: disables image enhancement.
    • options: BeautyOptions

      Sets the image enhancement option. See BeautyOptions.

    Returns number

    • 0: Success.
    • < 0: Failure.

setCameraCapturerConfiguration

  • Sets the camera capture configuration.

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

    • 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

  • Sets the channel profile of the Agora engine.

    The Agora engine differentiates channel profiles and applies optimization algorithms accordingly. For example, it prioritizes smoothness and low latency for a video call, and prioritizes video quality for the live interactive video streaming.

    warning
    • To ensure the quality of real-time communication, we recommend that all users in a channel use the same channel profile.
    • Call this method before calling joinChannel . You cannot set the channel profile once you have joined the channel.
    • The default audio route and video encoding bitrate are different in different channel profiles. For details, see setDefaultAudioRouteToSpeakerphone and setVideoEncoderConfiguration.

    Parameters

    Returns number

    • 0(ERR_OK): Success.
    • < 0: Failure.
    • -2(ERR_INVALID_ARGUMENT): The parameter is invalid.
    • -7(ERR_NOT_INITIALIZED): The SDK is not initialized.

setClientRole

  • Sets the role of the user, such as a host or an audience (default), before joining a channel in the live interactive streaming.

    This method can be used to switch the user role in the live interactive streaming after the user joins a channel.

    In the LIVE_BROADCASTING profile, when a user switches user roles after joining a channel, a successful setClientRole method call triggers the following callbacks:

    note

    This method applies only to the LIVE_BROADCASTING profile.

    Parameters

    Returns number

    • 0(ERR_OK): Success.
    • < 0: Failure.
    • -1(ERR_FAILED): A general error occurs (no specified reason).
    • -2(ERR_INVALID_ARGUMENT): The parameter is invalid.
    • -7(ERR_NOT_INITIALIZED): The SDK is not initialized.

setDefaultAudioRouteToSpeakerphone

  • setDefaultAudioRouteToSpeakerphone(defaultToSpeaker: boolean): number
  • Sets the default audio playback route.

    This method sets whether the received audio is routed to the earpiece or speakerphone by default before joining a channel.

    If a user does not call this method, the audio is routed to the earpiece by default. If you need to change the default audio route after joining a channel, call the setEnableSpeakerphone method.

    The default setting for each profile:

    • COMMUNICATION: In a voice call, the default audio route is the earpiece. In a video call, the default audio route is the speakerphone. If a user who is in the COMMUNICATION profile calls the disableVideo method or if the user calls the muteLocalVideoStream and muteAllRemoteVideoStreams methods, the default audio route switches back to the earpiece automatically.
    • LIVE_BROADCASTING: Speakerphone.

    Note

    • This method is applicable only to the COMMUNICATION profile.
    • For iOS, this method only works in a voice call.
    • Call this method before calling the joinChannel method.

    Parameters

    • defaultToSpeaker: boolean

      Sets the default audio route:

      • true: Route the audio to the speakerphone. If the playback device connects to the earpiece or Bluetooth, the audio cannot be routed to the speakerphone.
      • false: (Default) Route the audio to the earpiece. If a headset is plugged in, the audio is routed to the headset.

    Returns number

    • 0: Success.
    • < 0: Failure.

setDefaultMuteAllRemoteAudioStreams

  • setDefaultMuteAllRemoteAudioStreams(mute: boolean): number
  • Stops/Resumes receiving all remote users' audio streams by default.

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

    note

    If you want to resume receiving the audio stream, call muteRemoteAudioStream(false), and specify the ID of the remote user whose audio stream you want to receive. To receive the audio streams of multiple remote users, call muteRemoteAudioStream(false) as many times. Calling setDefaultMuteAllRemoteAudioStreams (false) resumes receiving the audio streams of subsequent users only.

    Parameters

    • mute: boolean

      Sets whether to receive/stop receiving all remote users' audio streams by default:

      • true: Stops receiving all remote users' audio streams by default.
      • false: (Default) Receives all remote users' audio streams by default.

    Returns number

    • 0: Success.
    • < 0: Failure.

setDefaultMuteAllRemoteVideoStreams

  • setDefaultMuteAllRemoteVideoStreams(mute: boolean): number
  • Stops/Resumes receiving all remote users' video streams by default.

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

    note

    If you want to resume receiving the video stream, call muteRemoteVideoStream(false), and specify the ID of the remote user whose video stream you want to receive. To receive the video streams of multiple remote users, call muteRemoteVideoStream(false) as many times. Calling setDefaultMuteAllRemoteVideoStreams(false) resumes receiving the video streams of subsequent users only.

    Parameters

    • mute: boolean

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

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

    Returns number

    • 0: Success.
    • < 0: Failure.

setEffectsVolume

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

    Parameters

    • volume: number

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

    Returns number

    • 0: Success.
    • < 0: Failure.

setEnableSpeakerphone

  • setEnableSpeakerphone(speakerOn: boolean): number
  • Enables/Disables the audio playback route to the speakerphone.

    This method sets whether the audio is routed to the speakerphone or earpiece.

    See the default audio route explanation in the setDefaultAudioRouteToSpeakerphone method and check whether it is necessary to call this method.

    Note

    • Ensure that you have successfully called the joinChannel method before calling this method.
    • After calling this method, the SDK returns the onAudioRouteChanged callback to indicate the changes.
    • This method does not take effect if a headset is used.

    Parameters

    • speakerOn: boolean

      Sets whether to route the audio to the speakerphone or earpiece:

      • true: Route the audio to the speakerphone. If the playback device connects to the earpiece or Bluetooth, the audio cannot be routed to the speakerphone.
      • false: Route the audio to the earpiece. If a headset is plugged in, the audio is routed to the headset.

    Returns number

    • 0: Success.
    • < 0: Failure.

setEncryptionMode

  • setEncryptionMode(encryptionMode: "aes-128-xts" | "aes-128-ecb" | "aes-256-xts"): number
  • Sets the built-in encryption mode.

    deprecated

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

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

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

    note

    Call the setEncryptionSecret method to enable the built-in encryption function before calling this method.

    Parameters

    • encryptionMode: "aes-128-xts" | "aes-128-ecb" | "aes-256-xts"

      The set encryption mode:

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

    Returns number

    • 0: Success.
    • < 0: Failure.

setEncryptionSecret

  • setEncryptionSecret(secret: string): number
  • Enables built-in encryption with an encryption password before users join a channel.

    deprecated

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

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

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

    Note

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

    Parameters

    • secret: string

      The encryption password.

    Returns number

    • 0: Success.
    • < 0: Failure.

setHighQualityAudioParameters

  • setHighQualityAudioParameters(fullband: boolean, stereo: boolean, fullBitrate: boolean): number
  • Sets the high-quality audio preferences.

    deprecated

    This callback is deprecated.

    Call this method and set all parameters before joining a channel. Do not call this method again after joining a channel.

    Parameters

    • fullband: boolean

      Sets whether to enable/disable full-band codec (48-kHz sample rate). Not compatible with SDK versions before v1.7.4:

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

      Sets whether to enable/disable stereo codec. Not compatible with SDK versions before v1.7.4:

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

      Sets whether to enable/disable high-bitrate mode. Recommended in voice-only mode:

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

    Returns number

    • 0: Success.
    • < 0: Failure.

setInEarMonitoringVolume

  • setInEarMonitoringVolume(volume: number): number
  • 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

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

    The SDK triggers the onTranscodingUpdated callback when you call the setLiveTranscoding method to update the transcoding setting.

    Note

    • This method applies to LIVE_BROADCASTING only.
    • Ensure that you enable the RTMP Converter service before using this function.
    • If you call the setLiveTranscoding method to update the transcoding setting for the first time, the SDK does not trigger the onTranscodingUpdated callback.

    Parameters

    Returns number

    • 0: Success.
    • < 0: Failure.

setLocalPublishFallbackOption

  • Sets the fallback option for the published video stream based on the network conditions.

    If option is set as STREAM_FALLBACK_OPTION_AUDIO_ONLY(2), the SDK will:

    • Disable the upstream video but enable audio only when the network conditions deteriorate and cannot support both video and audio.
    • Re-enable the video when the network conditions improve.

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

    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 published video stream falls back to audio only.

    Parameters

    Returns number

    • 0: Success.
    • < 0: Failure.

setLocalVoiceChanger

  • Sets the local voice changer option.

    This method can be used to set the local voice effect for users in a COMMUNICATION channel or hosts in a LIVE_BROADCASTING channel.

    Voice changer options include the following voice effects:

    • VOICE_CHANGER_XXX: Changes the local voice to an old man, a little boy, or the Hulk. Applies to the voice talk scenario.
    • VOICE_BEAUTY_XXX: Beautifies the local voice by making it sound more vigorous, resounding, or adding spacial resonance. Applies to the voice talk and singing scenario.
    • GENERAL_VOICE_BEAUTY_XXX: Adds gender-based beautification effect to the local voice. Applies to the voice talk scenario.
      • For a male-sounding voice: Adds magnetism to the voice.
      • For a female-sounding voice: Adds freshness or vitality to the voice.

    Note

    • To achieve better voice effect quality, Agora recommends setting the profile parameter in setAudioProfile as AUDIO_PROFILE_MUSIC_HIGH_QUALITY(4) or AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5).
    • This method works best with the human voice, and Agora does not recommend using it for audio containing music and a human voice.
    • Do not use this method with setLocalVoiceReverbPreset, because the method called later overrides the one called earlier.

    Parameters

    • voiceChanger: VOICE_CHANGER_PRESET

      Sets the local voice changer option. The default value is VOICE_CHANGER_OFF, which means the original voice. See details in VOICE_CHANGER_PRESET. Gender-based beatification effect works best only when assigned a proper gender:

      • For a male-sounding voice: GENERAL_BEAUTY_VOICE_MALE_MAGNETIC.
      • For a female-sounding voice: GENERAL_BEAUTY_VOICE_FEMALE_FRESH or GENERAL_BEAUTY_VOICE_FEMALE_VITALITY.

      Failure to do so can lead to voice distortion.

    Returns number

    • 0: Success.
    • < 0: Failure. Check if the enumeration is properly set.

setLocalVoiceEqualization

  • Sets the local voice equalization effect.

    Parameters

    • bandFrequency: AUDIO_EQUALIZATION_BAND_FREQUENCY

      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, 250, 500, 1k, 2k, 4k, 8k, and 16k Hz. See AUDIO_EQUALIZATION_BAND_FREQUENCY.

    • 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
  • Changes the voice pitch of the local speaker.

    Parameters

    • pitch: number

      Sets the voice pitch. 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

  • Sets the local voice reverberation.

    You can also use setLocalVoiceReverbPreset to use the preset reverberation effect, such as pop music, R&B or rock music effects.

    Parameters

    Returns number

    • 0: Success.
    • < 0: Failure.

setLocalVoiceReverbPreset

  • Sets the local voice reverberation option, including the virtual stereo.

    This method sets the local voice reverberation for users in a COMMUNICATION channel or hosts in a LIVE_BROADCASTING channel. After successfully calling this method, all users in the channel can hear the voice with reverberation.

    Note

    • When calling this method with enumerations that begin with AUDIO_REVERB_FX, ensure that you set profile in setAudioProfile as AUDIO_PROFILE_MUSIC_HIGH_QUALITY(4) or AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5); otherwise, this methods cannot set the corresponding voice reverberation option.
    • When calling this method with AUDIO_VIRTUAL_STEREO, Agora recommends setting the profile parameter in setAudioProfile as AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5).
    • This method works best with the human voice, and Agora does not recommend using it for audio containing music and a human voice.
    • Do not use this method with setLocalVoiceChanger, because the method called later overrides the one called earlier.

    Parameters

    • reverbPreset: AUDIO_REVERB_PRESET

      The local voice reverberation option. The default value is AUDIO_REVERB_OFF, which means the original voice. See AUDIO_REVERB_PRESET. To achieve better voice effects, Agora recommends the enumeration whose name begins with AUDIO_REVERB_FX.

    Returns number

    • 0: Success.
    • < 0: Failure.

setLogFile

  • setLogFile(filePath: string): number
  • Sets the log files that the SDK outputs.

    By default, the SDK outputs five log files, agorasdk.log, agorasdk_1.log, agorasdk_2.log, agorasdk_3.log, agorasdk_4.log, each with a default size of 1024 KB.

    These log files are encoded in UTF-8. The SDK writes the latest logs in agorasdk.log. When agorasdk.log is full, the SDK deletes the log file with the earliest modification time among the other four, renames agorasdk.log to the name of the deleted log file, and create a new agorasdk.log to record latest logs.

    note

    Ensure that you call this method immediately after calling init, otherwise the output logs may not be complete.

    Parameters

    • filePath: string

      The absolute path of log files. The default file path is as follows:

      • Android: /storage/emulated/0/Android/data/<package name>/files/agorasdk.log
      • iOS: App Sandbox/Library/caches/agorasdk.log

      Ensure that the directory for the log files exists and is writable. You can use this parameter to rename the log files.

    Returns number

    • 0: Success.
    • < 0: Failure.

setLogFileSize

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

    By default, the SDK outputs five log files, agorasdk.log, agorasdk_1.log, agorasdk_2.log, agorasdk_3.log, agorasdk_4.log, each with a default size of 1024 KB.

    These log files are encoded in UTF-8. The SDK writes the latest logs in agorasdk.log. When agorasdk.log is full, the SDK deletes the log file with the earliest modification time among the other four, renames agorasdk.log to the name of the deleted log file, and create a new agorasdk.log to record latest logs.

    Parameters

    • fileSizeInKBytes: number

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

    Returns number

    • 0: Success.
    • < 0: Failure.

setLogFilter

  • Sets the output log level of the SDK.

    You can use one or a combination of the log filter levels. The log level follows the sequence of OFF, CRITICAL, ERROR, WARNING, INFO, and DEBUG. Choose a level to see the logs preceding that level.

    If you set the log level to WARNING, you see the logs within levels CRITICAL, ERROR, and WARNING.

    Parameters

    Returns number

    • 0: Success.
    • < 0: Failure.

setMaxMetadataSize

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

    The metadata includes the following parameters:

    • uid: ID of the user who sends the metadata.
    • size: The size of the sent or received metadata.
    • buffer: The sent or received metadata.
    • timeStampMs: The timestamp (ms) of the metadata.
    note

    Call this method after registerMediaMetadataObserver.

    Parameters

    • size: number

      The maximum size of the buffer of the metadata that you want to use. The highest value is 1024 bytes.

    Returns number

    • 0: Success.
    • < 0: Failure.

setParameters

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

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

    Parameters

    • parameters: string

      Sets the parameter as a JSON string in the specified format.

    Returns number

    • 0: Success.
    • < 0: Failure.

setRemoteDefaultVideoStreamType

  • Sets the default stream type of remote videos.

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

    By default, users receive the high-quality video stream. Call this method if you want to switch to the low-video stream.

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

    The method result returns in the onApiCallExecuted callback.

    Parameters

    Returns number

    • 0: Success.
    • < 0: Failure.

setRemoteSubscribeFallbackOption

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

    The default setting for option is STREAM_FALLBACK_OPTION_VIDEO_STREAM_LOW(1), where the remotely subscribed video stream falls back to the low-stream video (low resolution and low bitrate) under poor downlink network conditions.

    If option is set as 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 conditions 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 onRemoteSubscribeFallbackToAudioOnly callback.

    Parameters

    Returns number

    • 0: Success.
    • < 0: Failure.

setRemoteUserPriority

  • setRemoteUserPriority(uid: number, userPriority: PRIORITY_TYPE): number
  • Prioritizes a remote user's 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 PRIORITY_HIGH for one user only.

    Parameters

    Returns number

    • 0: Success.
    • < 0: Failure.

setRemoteVideoStreamType

  • Sets the stream type of the remote video.

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

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

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

    The method result returns in the onApiCallExecuted callback.

    Parameters

    Returns number

    • 0: Success.
    • < 0: Failure.

setRemoteVoicePosition

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

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

    Note

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

    Parameters

    • uid: number

      The ID of the remote user.

    • pan: number

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

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

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

    Returns number

    • 0: Success.
    • < 0: Failure.

setVideoEncoderConfiguration

  • Sets the video encoder configuration.

    Each video encoder configuration corresponds to a set of video parameters, including the resolution, frame rate, bitrate, and video orientation.

    The parameters specified in this method are the maximum values under ideal network conditions. If the video engine cannot render the video using the specified parameters due to poor network conditions, the parameters further down the list are considered until a successful configuration is found.

    note

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

    Parameters

    Returns number

    • 0: Success.
    • < 0: Failure.

setVideoProfile

  • Sets the video profile.

    deprecated

    This method is deprecated. Use the setVideoEncoderConfiguration method instead.

    Each video profile includes a set of parameters, such as the resolution, frame rate, and bitrate. If the camera device does not support the specified resolution, the SDK automatically chooses a suitable camera resolution, keeping the encoder resolution specified by the setVideoProfile method.

    Note

    • If you do not need to set the video profile after joining the channel, call this method before the enableVideo method to reduce the render time of the first video frame.
    • Always set the video profile before calling the joinChannel or startPreview method.
    note

    Since the landscape or portrait mode of the output video can be decided directly by the video profile, We recommend setting swapWidthAndHeight to false (default).

    Parameters

    • profile: VIDEO_PROFILE_TYPE

      Sets the video profile. See VIDEO_PROFILE_TYPE.

    • swapWidthAndHeight: boolean

      Sets whether to swap the width and height of the video stream:

      • true: Swap the width and height.
      • false: (Default) Do not swap the width and height. The width and height of the output video are consistent with the set video profile.

    Returns number

    • 0: Success.
    • < 0: Failure.

setVolumeOfEffect

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

    Parameters

    • soundId: number

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

    • volume: number

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

    Returns number

    • 0: Success.
    • < 0: Failure.

startAudioMixing

  • startAudioMixing(filePath: string, loopback: boolean, replace: boolean, cycle: number): number
  • 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 playback loops. This method also supports online music playback.

    When the audio mixing file playback finishes after calling this method, the SDK triggers the onAudioMixingFinished callback.

    A successful startAudioMixing method call triggers the onAudioMixingStateChanged(PLAY) callback on the local client.

    When the audio mixing file playback finishes, the SDK triggers the onAudioMixingStateChanged(STOPPED) callback on the local client.

    Note

    • Call this method after joining a channel, otherwise issues may occur.
    • 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 WARN_AUDIO_MIXING_OPEN_ERROR(-701).
    • If you want to play an online music file, ensure that the time interval between calling this method is more than 100 ms, or the AUDIO_MIXING_ERROR_TOO_FREQUENT_CALL(702) error code occurs.

    Parameters

    • filePath: string

      The absolute path (including the suffixes of the filename) of the local or online audio file to mix, for example, c:\music\audio.mp4. Supported audio formats: 3GP, ASF, ADTS, AVI, MP3, MP4, MPEG-4, SAMI, and WAVE. For more information, see Supported Media Formats in Media Foundation.

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

startAudioRecording

  • Starts an audio recording on the client.

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

    Supported formats of the recording file are as follows:

    • .wav: Large file size with high fidelity.
    • .aac: Small file size with low fidelity.

    Note

    • Ensure that the directory you use to save the recording file exists and is writable.
    • This method is usually called after the joinChannel method. The recording automatically stops when you call the leaveChannel method.
    • For better recording effects, set quality as AUDIO_RECORDING_QUALITY_MEDIUM or AUDIO_RECORDING_QUALITY_HIGH when sampleRate is 44.1 kHz or 48 kHz.

    Parameters

    • filePath: string

      The absolute file path of the recording file. The string of the file name is in UTF-8, such as /dir1/dir2/dir3/audio.aac.

    • quality: AUDIO_RECORDING_QUALITY_TYPE

      Sets the audio recording quality. See AUDIO_RECORDING_QUALITY_TYPE.

    • Optional sampleRate: undefined | number

      Sample rate (Hz) of the recording file. Supported values are as follows:

      • 16000
      • (Default) 32000
      • 44100
      • 48000

    Returns number

    • 0: Success.
    • < 0: Failure.

startChannelMediaRelay

startEchoTest

  • startEchoTest(intervalInSeconds?: undefined | number): number
  • Starts an audio call test.

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

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

    Note

    • Call this method before joining a channel.
    • After calling this method, call the stopEchoTest method to end the test. Otherwise, the app cannot run the next echo test, or call the joinChannel method.
    • In the LIVE_BROADCASTING profile, only a host can call this method.

    Parameters

    • Optional intervalInSeconds: undefined | number

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

    Returns number

    • 0: Success.
    • < 0: Failure.

startLastmileProbeTest

  • Starts the last-mile network probe test.

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

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

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

    • onLastmileQuality: the SDK triggers this callback within two seconds depending on the network conditions. This callback rates the network conditions and is more closely linked to the user experience.
    • onLastmileProbeResult: 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.

    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 onLastmileQuality and onLastmileProbeResult callbacks. Otherwise, the callbacks may be interrupted.
    • In the LIVE_BROADCASTING profile, a host should not call this method after joining a channel.

    Parameters

    Returns number

    • 0: Success.
    • < 0: Failure.

startPreview

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

    Before calling this method, you must call the enableVideo method to enable video.

    note

    Once the startPreview method is called to start the local video preview, if you leave the channel by calling the leaveChannel method, the local video preview remains until you call the stopPreview method to disable it.

    Returns number

    • 0: Success.
    • < 0: Failure.

stopAllEffects

  • stopAllEffects(): number
  • Stops playing all audio effects.

    Returns number

    • 0: Success.
    • < 0: Failure.

stopAudioMixing

  • stopAudioMixing(): number
  • Stops playing and mixing the music file.

    Call this method when you are in a channel.

    Returns number

    • 0: Success.
    • < 0: Failure.

stopAudioRecording

  • stopAudioRecording(): number
  • Stops an audio recording on the client.

    You can call this method before calling the leaveChannel method else, the recording automatically stops when the leaveChannel method is called.

    Returns number

    • 0: Success
    • < 0: Failure.

stopChannelMediaRelay

  • stopChannelMediaRelay(): number

stopEchoTest

  • stopEchoTest(): number
  • Stops the audio call test.

    Returns number

    • 0: Success.
    • < 0: Failure.

stopEffect

  • stopEffect(soundId: number): number
  • Stops playing a specified audio effect.

    Parameters

    • soundId: number

      ID of the audio effect to stop playing. Each audio effect has a unique ID.

    Returns number

    • 0: Success.
    • < 0: Failure.

stopLastmileProbeTest

  • stopLastmileProbeTest(): number
  • Stops the last-mile network probe test.

    Returns number

    • 0: Success.
    • < 0: Failure.

stopPreview

  • stopPreview(): number
  • Stops the local video preview and disables video.

    Returns number

    • 0: Success.
    • < 0: Failure.

switchCamera

switchChannel

  • switchChannel(token: string, channelId: string): number
  • Switches to a different channel.

    This method allows the audience of a LIVE_BROADCASTING channel to switch to a different channel.

    After the user successfully switches to another channel, the onLeaveChannel and onJoinChannelSuccess callbacks are triggered to indicate that the user has left the original channel and joined a new one.

    note

    This method applies to the audience role in a LIVE_BROADCASTING channel only.

    Parameters

    • token: string

      The token for authentication:

      • In situations not requiring high security: You can use the temporary token generated at Console. For details, see Get a temporary token.
      • In situations requiring high security: Set it as the token generated at your server. For details, see Get a token.
    • channelId: string

      The unique channel name for the Agora RTC session in the string format smaller than 64 bytes. Supported characters:

      • All lowercase English letters: a to z.
      • All uppercase English letters: A to Z.
      • All numeric characters: 0 to 9.
      • The space character.
      • Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".

    Returns number

    • 0(ERR_OK): Success.
    • < 0: Failure.
    • -1(ERR_FAILED): A general error occurs (no specified reason).
    • -2(ERR_INVALID_ARGUMENT): The parameter is invalid.
    • -5(ERR_REFUSED): The request is rejected, probably because the user is not an audience.
    • -7(ERR_NOT_INITIALIZED): The SDK is not initialized.
    • -102(ERR_INVALID_CHANNEL_NAME): The channel name is invalid.
    • -113(ERR_NOT_IN_CHANNEL): The user is not in the channel.

unloadEffect

  • unloadEffect(soundId: number): number
  • Releases a specified preloaded audio effect from the memory.

    Parameters

    • soundId: number

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

    Returns number

    • 0: Success.
    • < 0: Failure.

updateChannelMediaRelay

Generated using TypeDoc