agora-rtc-sdk-ng
Version:
Agora WebRTC SDK for JavaScript
1,241 lines (1,228 loc) • 154 kB
TypeScript
import { IRemoteAudioTrack, IRemoteVideoTrack, IRemoteDataChannel, RemoteAudioTrack, RemoteVideoTrack, RemoteDataChannel, ILocalTrack, ILocalDataChannel, IDataChannelConfig, IRemoteTrack, LowStreamParameter, RemoteStreamType, RemoteStreamFallbackType, AgoraRTCStats, LocalAudioTrackStats, RemoteAudioTrackStats, LocalVideoTrackStats, RemoteVideoTrackStats, LocalTrack, LocalDataChannel, RemoteTrack, AudioMetadata, LocalVideoTrack, LocalAudioTrack, CustomAudioTrackInitConfig, ILocalAudioTrack, MicrophoneAudioTrackInitConfig, IMicrophoneAudioTrack, BufferSourceAudioTrackInitConfig, IBufferSourceAudioTrack, CustomVideoTrackInitConfig, ILocalVideoTrack, CameraVideoTrackInitConfig, ICameraVideoTrack, ScreenVideoTrackInitConfig, ScreenAudioTrackInitConfig, ScreenSourceType, DeviceInfo } from '@agora-js/media';
export { AgoraRTCStats, AudioEncoderConfiguration, AudioEncoderConfigurationPreset, AudioSourceOptions, AudioSourceState, BeautyEffectOptions, BufferSourceAudioTrackInitConfig, CameraVideoTrackInitConfig, ConstrainLong, CustomAudioTrackInitConfig, CustomVideoTrackInitConfig, DeviceInfo, DeviceState, IBufferSourceAudioTrack, ICameraVideoTrack, IDataChannel, IDataChannelConfig, ILocalAudioTrack, ILocalDataChannel, ILocalTrack, ILocalVideoTrack, IMicrophoneAudioTrack, IRemoteAudioTrack, IRemoteDataChannel, IRemoteTrack, IRemoteVideoTrack, ITrack, ImageTypedData, LocalAudioTrackStats, LocalVideoTrackStats, LowStreamParameter, MicrophoneAudioTrackInitConfig, RemoteAudioTrackStats, RemoteStreamFallbackType, RemoteStreamType, RemoteVideoTrackStats, SVCConfiguration, SVCConfigurationPreset, ScreenEncoderConfigurationPreset, ScreenSourceType, ScreenVideoTrackInitConfig, VideoEncoderConfiguration, VideoEncoderConfigurationPreset, VideoPlayerConfig, __TRACK_LIST__, audioContextState, audioElementPlayCenter, createBufferSourceAudioTrack, createCameraVideoTrack, createCustomAudioTrack, createCustomVideoTrack, createMicrophoneAndCameraTracks, createMicrophoneAudioTrack, createScreenVideoTrack, getElectronScreenSources } from '@agora-js/media';
import { UID, MutableParamsConfig, EventEmitter, ConnectionState, SDK_MODE, ClientRole, SIMULCAST_STREAM_MODE, ClientRoleOptions, TurnServerConfig, RTMConfiguration, EncryptionMode, NetworkQuality, LocalAccessPointConfig, ConnectionDisconnectedReason, ClientConfig, KeyMetrics, P2PTransportType, JoinChannelServiceRecord, ElectronDesktopCapturerSource, RetryConfiguration, setParameter as setParameter$1 } from '@agora-js/shared';
export { AgoraRTCErrorCode, AudienceLatencyLevelType, BUILD, ClientConfig, ClientRole, ClientRoleOptions, ConnectionDisconnectedReason, ConnectionState, ElectronDesktopCapturerSource, EncryptionMode, IAgoraRTCError, LocalAccessPointConfig, NetworkQuality, SDK_AUDIO_CODEC, SDK_CODEC, SDK_MODE, TurnServerConfig, UID, VERSION, getParameter } from '@agora-js/shared';
import { AgoraRTCError, EventCustomReportParams } from '@agora-js/report';
export { EventCustomReportParams } from '@agora-js/report';
import { IExtension } from 'agora-rte-extension';
import { CancelToken } from 'axios';
/**
* Configurations for the watermark and background images to put on top of the video in [LiveStreamingTranscodingConfig]{@link LiveStreamingTranscodingConfig}.
*/
interface LiveStreamingTranscodingImage {
/**
* The HTTP/HTTPS URL address of the image on the video.
*
* Supports online PNG only.
*/
url: string;
/**
* The horizontal distance (pixel) between the image's top-left corner and the video's top-left corner.
*
* The default value is `0`.
*/
x?: number;
/**
* The vertical distance (pixel) between the image's top-left corner and the video's top-left corner.
*
* The default value is `0`.
*/
y?: number;
/**
* The width (pixel) of the image.
*
* The default value is `160`.
*/
width?: number;
/**
* The height (pixel) of the image.
*
* The default value is `160`.
*/
height?: number;
/**
* The transparency level of the image.
*
* The value range is [0.0,1.0]:
* - 0.0: Completely transparent.
* - 1.0: (Default) Opaque.
*/
alpha?: number;
}
/**
* The configurations for CDN live stream transcoding. To be used when you call [setLiveTranscoding]{@link IAgoraRTCClient.setLiveTranscoding}.
*/
interface LiveStreamingTranscodingConfig {
/**
* The audio bitrate (Kbps) of the CDN live stream.
*
* A positive integer. The default value is 48, and the highest value is 128.
*/
audioBitrate?: number;
/**
* The number of audio channels for the CDN live stream.
*
* Agora recommends choosing 1 (mono), or 2 (stereo) audio channels. Special players are required if you choose 3, 4, or 5.
*
* - 1: (Default) Mono
* - 2: Stereo
* - 3: Three audio channels
* - 4: Four audio channels
* - 5: Five audio channels
*/
audioChannels?: 1 | 2 | 3 | 4 | 5;
/**
* The audio sampling rate:
*
* - 32000: 32 kHz
* - 44100: 44.1 kHz
* - 48000: (Default) 48 kHz
*/
audioSampleRate?: 32000 | 44100 | 48000;
/**
* The background color in RGB hex.
*
* Value only. Do not include a preceding #. The default value is 0x000000.
*/
backgroundColor?: number;
/**
* The height of the video in pixels.
*
* A positive integer, the default value is 360.
*
* - When pushing video streams to the CDN, ensure that `height` is at least 64; otherwise, the Agora server adjusts the value to 64.
* - When pushing audio streams to the CDN, set `width` and `height` as 0.
*/
height?: number;
/**
* The width of the video in pixels.
*
* A positive integer, the default value is 640.
*
* - When pushing video streams to the CDN, ensure that `width` is at least 64; otherwise, the Agora server adjusts the value to 64.
* - When pushing audio streams to the CDN, set `width` and `height` as 0.
*/
width?: number;
/**
* @ignore
*/
lowLatency?: boolean;
/**
* The bitrate (Kbps) of the output video stream.
*
* The default value is 400.
*/
videoBitrate?: number;
/**
* The video codec profile type.
*
* Set it as `66`, `77`, or `100` (default). If you set this parameter to any other value, the Agora server adjusts it to the default value `100`.
*
* - `66`: Baseline video codec profile. Generally used for video calls on mobile phones.
* - `77`: Main video codec profile. Generally used for mainstream electronic devices, such as MP4 players, portable video players, PSP, and iPads.
* - `100`: (Default) High video codec profile. Generally used for high-resolution broadcasts or television.
*/
videoCodecProfile?: 66 | 77 | 100;
/**
* The video frame rate (fps) of the CDN live stream.
*
* The default value is 15. The Agora server adjusts any value over 30 to 30.
*/
videoFrameRate?: number;
/**
* The video GOP in frames.
*
* The default value is 30.
*/
videoGop?: number;
/**
* @deprecated
*
* Watermark images for the CDN live stream.
*/
images?: LiveStreamingTranscodingImage[];
/**
* Watermark image for the CDN live stream.
*/
watermark?: LiveStreamingTranscodingImage;
/**
* Background image for the CDN live stream.
*/
backgroundImage?: LiveStreamingTranscodingImage;
/**
* Manages the user layout configuration in the CDN live streaming.
*
* Agora supports a maximum of 17 transcoding users in a CDN streaming channel.
*/
transcodingUsers?: LiveStreamingTranscodingUser[];
userConfigExtraInfo?: string;
}
/**
* Manages the user layout configuration in [LiveStreamingTranscodingConfig]{@link LiveStreamingTranscodingConfig}.
*/
interface LiveStreamingTranscodingUser {
/**
* The transparency level of the user's video.
*
* The value ranges between 0.0 and 1.0:
*
* - 0.0: Completely transparent.
* - 1.0: (Default) Opaque.
*/
alpha?: number;
/**
* The height of the video.
*
* The default value is 640.
*/
height?: number;
/**
* The user ID of the CDN live host.
*/
uid: UID;
/**
* The width of the video.
*
* The default value is 360.
*/
width?: number;
/**
* The position of the top-left corner of the video on the horizontal axis.
*
* The default value is 0.
*/
x?: number;
/**
* The position of the top-left corner of the video on the vertical axis.
*
* The default value is 0.
*/
y?: number;
/**
* The layer index of the video frame.
*
* An integer. The value range is [0,100].
*
* - 0: (Default) Bottom layer.
* - 100: Top layer.
*/
zOrder?: number;
/**
* The audio channel ranging between 0 and 5. The default value is 0.
* - 0: (default) Supports dual channels. Depends on the upstream of the broadcaster.
* - 1: The audio stream of the broadcaster uses the FL audio channel. If the broadcaster’s upstream uses multiple audio channels, these channels are mixed into mono first.
* - 2: The audio stream of the broadcaster uses the FC audio channel. If the broadcaster’s upstream uses multiple audio channels, these channels are mixed into mono first.
* - 3: The audio stream of the broadcaster uses the FR audio channel. If the broadcaster’s upstream uses multiple audio channels, these channels are mixed into mono first.
* - 4: The audio stream of the broadcaster uses the BL audio channel. If the broadcaster’s upstream uses multiple audio channels, these channels are mixed into mono first.
* - 5: The audio stream of the broadcaster uses the BR audio channel. If the broadcaster’s upstream uses multiple audio channels, these channels are mixed into mono first.
*/
audioChannel?: number;
}
/**
* Channel information in the media relay, used in [ChannelMediaRelayConfiguration]{@link IChannelMediaRelayConfiguration}.
*/
interface ChannelMediaRelayInfo {
/**
* The channel name.
*/
channelName: string;
/**
* The token generated with the `channelName` and `uid`. Do not set this parameter if you have not enabled token.
* The token for authentication. Do not set this parameter if you have not enabled token authentication.
*
* - When you set the information of the source channel, the token is generated with 0 and the source channel name.
* - When you set the information of the destination channel, the token is generated with `uid` and the destination channel name.
*/
token?: string;
/**
* The unique ID to identify the relay stream.
*
* A 32-bit unsigned integer with a value ranging from 0 to (2<sup>32</sup>-1). If you set it as `0`, the server assigns a random one.
*
* When used for the source channel, it is the ID to identify the relay stream in the source channel.
*
* When used for the destination channel, it is the ID to identify the relay stream in the destination channel. To avoid UID conflicts, this value must be different from any other user IDs in the destination channel.
* - When you set the information of the source channel, set `uid` as the ID of the host whose stream is relayed.
* - When you set the information of the destination channel, you can set `uid` as `0` (the server assigns a random one) or a 32-bit unsigned integer with a value ranging from 0 to (2<sup>32</sup>-1). To avoid UID conflicts, this value must be different from any other user IDs in the destination channel.
*/
uid: number;
}
/**
* Events during the media stream relay. You can get the event through [AgoraRTCClient.on("channel-media-relay-event")]{@link IAgoraRTCClient.event_channel_media_relay_event}.
*/
declare enum ChannelMediaRelayEvent {
/**
* The user disconnects from the server due to a poor network connection.
*/
NETWORK_DISCONNECTED = "NETWORK_DISCONNECTED",
/**
* The user is connected to the server.
*/
NETWORK_CONNECTED = "NETWORK_CONNECTED",
/**
* The user joins the source channel.
*/
PACKET_JOINED_SRC_CHANNEL = "PACKET_JOINED_SRC_CHANNEL",
/**
* The user joins the destination channel.
*/
PACKET_JOINED_DEST_CHANNEL = "PACKET_JOINED_DEST_CHANNEL",
/**
* The SDK starts relaying the media stream to the destination channel.
*/
PACKET_SENT_TO_DEST_CHANNEL = "PACKET_SENT_TO_DEST_CHANNEL",
/**
* The server receives the video stream from the source channel.
*/
PACKET_RECEIVED_VIDEO_FROM_SRC = "PACKET_RECEIVED_VIDEO_FROM_SRC",
/**
* The server receives the audio stream from the source channel.
*/
PACKET_RECEIVED_AUDIO_FROM_SRC = "PACKET_RECEIVED_AUDIO_FROM_SRC",
/**
* The destination channel is updated.
*/
PACKET_UPDATE_DEST_CHANNEL = "PACKET_UPDATE_DEST_CHANNEL",
/**
* Fails to update the destination channel due to an internal error.
*/
PACKET_UPDATE_DEST_CHANNEL_REFUSED = "PACKET_UPDATE_DEST_CHANNEL_REFUSED",
/**
* The destination channel is not updated.
*/
PACKET_UPDATE_DEST_CHANNEL_NOT_CHANGE = "PACKET_UPDATE_DEST_CHANNEL_NOT_CHANGE"
}
/**
* The state code of the media stream relay. You can get the code through [AgoraRTCClient.on("channel-media-relay-state")]{@link IAgoraRTCClient.event_channel_media_relay_state}.
*/
declare enum ChannelMediaRelayState {
/**
* The SDK is initialized, but has not started the media stream relay service.
*/
RELAY_STATE_IDLE = "RELAY_STATE_IDLE",
/**
* The SDK is connecting to the media stream relay service.
*/
RELAY_STATE_CONNECTING = "RELAY_STATE_CONNECTING",
/**
* The SDK successfully relays the media stream to the destination channel.
*/
RELAY_STATE_RUNNING = "RELAY_STATE_RUNNING",
/**
* An error occurs in the media stream relay. See {@link ChannelMediaRelayError} for the error code.
*/
RELAY_STATE_FAILURE = "RELAY_STATE_FAILURE"
}
/**
* The error code of the media stream relay. You can get the code through [AgoraRTCClient.on("channel-media-relay-state")]{@link IAgoraRTCClient.event_channel_media_relay_state}.
*/
declare enum ChannelMediaRelayError {
/**
* No error.
*/
RELAY_OK = "RELAY_OK",
/**
* The SDK disconnects from the relay service.
*/
SERVER_CONNECTION_LOST = "SERVER_CONNECTION_LOST",
/**
* The token of the source channel has expired.
*/
SRC_TOKEN_EXPIRED = "SRC_TOKEN_EXPIRED",
/**
* The token of the destination channel has expired.
*/
DEST_TOKEN_EXPIRED = "DEST_TOKEN_EXPIRED"
}
/**
* Regions for the connection. Used for calling [AgoraRTC.setArea]{@link IAgoraRTC.setArea}.
*/
declare enum AREAS {
/**
* China.
*/
CHINA = "CHINA",
/**
* Asia, excluding Mainland China.
*/
ASIA = "ASIA",
/**
* North America.
*/
NORTH_AMERICA = "NORTH_AMERICA",
/**
* Europe.
*/
EUROPE = "EUROPE",
/**
* Japan.
*/
JAPAN = "JAPAN",
/**
* India.
*/
INDIA = "INDIA",
/**
* @ignore
*/
KOREA = "KOREA",
/**
* @ignore
*/
HKMC = "HKMC",
/**
* @ignore
*/
US = "US",
/**
* @ignore
*/
OCEANIA = "OCEANIA",
/**
* @ignore
*/
SOUTH_AMERICA = "SOUTH_AMERICA",
/**
* @ignore
*/
AFRICA = "AFRICA",
/**
* @ignore
*/
OVERSEA = "OVERSEA",
/**
* Global.
*/
GLOBAL = "GLOBAL",
/**
* @ignore
*/
EXTENSIONS = "EXTENSIONS"
}
interface ConfigDistributeConfigs {
[key: string]: {
tag: string;
value: MutableParamsConfig;
};
}
/**
* Information about a remote user. You can get this through [AgoraRTCClient.remoteUsers]{@link IAgoraRTCClient.remoteUsers}.
*/
interface IAgoraRTCRemoteUser {
/**
* The ID of the remote user.
*/
uid: UID;
/**
* The subscribed audio track.
*/
audioTrack?: IRemoteAudioTrack;
/**
* The subscribed video track.
*/
videoTrack?: IRemoteVideoTrack;
/**
* Whether the remote user is sending an audio track.
* - `true`: The remote user is sending an audio track.
* - `false`: The remote user is not sending an audio track.
*/
hasAudio: boolean;
/**
* Whether the remote user is sending a video track.
* - `true`: The remote user is sending an audio track.
* - `false`: The remote user is not sending an audio track.
*/
hasVideo: boolean;
/**
* @ignore
*/
dataChannels?: IRemoteDataChannel[];
}
declare class AgoraRTCRemoteUser implements IAgoraRTCRemoteUser {
uid: UID;
_uintid: number;
_trust_audio_enabled_state_: boolean;
_trust_video_enabled_state_: boolean;
_trust_audio_mute_state_: boolean;
_trust_video_mute_state_: boolean;
_audio_muted_: boolean;
_video_muted_: boolean;
_audio_enabled_: boolean;
_video_enabled_: boolean;
_audio_added_: boolean;
_video_added_: boolean;
_is_pre_created: boolean;
_video_pre_subscribed: boolean;
_audio_pre_subscribed: boolean;
_trust_video_stream_added_state_: boolean;
_trust_audio_stream_added_state_: boolean;
get hasVideo(): boolean;
get hasAudio(): boolean;
get audioTrack(): undefined | RemoteAudioTrack;
get videoTrack(): undefined | RemoteVideoTrack;
get dataChannels(): RemoteDataChannel[];
constructor(uid: UID, uintid: number);
}
/**
* @ignore
*/
declare enum InspectState {
CONNECTING = "CONNECTING",
RECONNECTING = "RECONNECTING",
CONNECTED = "CONNECTED",
CLOSED = "CLOSED"
}
/**
* @ignore
*/
interface InspectConfiguration {
interval: number;
ossFilePrefix?: string;
extraInfo?: string;
inspectType?: ("supervise" | "moderation")[];
}
declare enum AppType {
APP_TYPE_INVALID_VALUE = -1,
APP_TYPE_NATIVE = 0,
APP_TYPE_NATIVE_COCOS = 1,
APP_TYPE_NATIVE_UNITY = 2,
APP_TYPE_NATIVE_ELECTRON = 3,
APP_TYPE_NATIVE_FLUTTER = 4,
APP_TYPE_NATIVE_UNREAL = 5,
APP_TYPE_NATIVE_XAMARIN = 6,
APP_TYPE_NATIVE_API_CLOUD = 7,
APP_TYPE_NATIVE_REACT_NATIVE = 8,
APP_TYPE_NATIVE_PYTHON = 9,
APP_TYPE_NATIVE_COCOS_CREATOR = 10,
APP_TYPE_NATIVE_RUST = 11,
APP_TYPE_NATIVE_C_SHARP = 12,
APP_TYPE_NATIVE_CEF = 13,
APP_TYPE_NATIVE_UNI_APP = 14,
APP_TYPE_WEBRTC = 1000,
APP_TYPE_WEBRTC_REACT = 1001,
APP_TYPE_WEBRTC_VUE = 1002,
APP_TYPE_WEBRTC_ANGULAR = 1003
}
/**
* Connection state between the SDK and the third-party video moderation service.
*/
declare enum ImageModerationConnectionState {
/**
* The SDK is connecting to the third-party service.
*/
CONNECTING = "CONNECTING",
/**
* The SDK is reconnecting to the third-party service.
*/
RECONNECTING = "RECONNECTING",
/**
* The SDK is connected to the third-party service.
*/
CONNECTED = "CONNECTED",
/**
* The SDK has disconnected from the third-party service.
*/
CLOSED = "CLOSED"
}
/**
* Configuration for the video moderation service. Used in the {@link setImageModeration} method.
*/
interface ImageModerationConfiguration {
/**
* Interval for taking video screenshots (ms), with a minimum value of `1000`.
*/
interval: number;
/**
* Additional information, with a maximum length of 1024 bytes.
*
* The SDK sends the screenshots and additional information on the video content to the Agora server. Once the video screenshot and upload process is completed, the Agora server sends the additional information and the callback notification to your server.
*/
extraInfo?: string;
/**
* @ignore
*/
vendor?: string;
}
/**u
* Pre-call network quality probe result, which reflects the overall quality of uplink and downlink networks.
* @since
* <br>   *4.24.1*</br>
*/
interface LastmileProbeResult {
/**
* Network quality probe status:
* - `complete`: Indicates that the network quality probe is complete.
* - `unavailable`: Indicates that the network quality probe is unavailable. A possible reason is a network disconnection.
*/
state: "complete" | "unavailable";
/**
* Round-trip time (ms).
*/
rtt?: number;
/**
* Packet loss rate.
*/
packetLossRate?: number;
/**
* Network jitter (ms).
*/
jitter?: number;
/**
* Network quality:
* - 1: Excellent.
* - 2: Average.
* - 3: Poor.
* - 4: Very poor.
*/
networkQuality?: number;
}
/**
* Configurations of the media stream relay.
*
* Use this interface to set the media stream relay when calling [startChannelMediaRelay]{@link IAgoraRTCClient.startChannelMediaRelay} or [updateChannelMediaRelay]{@link IAgoraRTCClient.updateChannelMediaRelay}.
*
* ```javascript
* const configuration = AgoraRTC.createChannelMediaRelayConfiguration();
* configuration.setSrcChannelInfo({ channelName: "test", token: "xxx", uid: 12345 });
* configuration.addDestChannelInfo({ channelName: "test2", token: "xxx", uid: 23456 });
* ```
*/
interface IChannelMediaRelayConfiguration {
/**
* Sets the information of the source channel.
*
* ```javascript
* const config = AgoraRTC.createChannelMediaRelayConfiguration();
* config.setSrcChannelInfo({ channelName: "test", token: "xxx", uid: 123456 });
* ```
* @param info The information of the source channel.
*/
setSrcChannelInfo(info: ChannelMediaRelayInfo): void;
/**
* Adds a destination channel.
*
* To relay a media stream across multiple channels, call this method as many times (to a maximum of four).
*
* ```javascript
* const config = AgoraRTC.createChannelMediaRelayConfiguration();
* config.addDestChannelInfo({ channelName: "test2", token: "xxx", uid: 23456 });
* config.addDestChannelInfo({ channelName: "test3", token: "xxx", uid: 23457 });
* ```
*
* @param info The information of the destination channel.
*/
addDestChannelInfo(info: ChannelMediaRelayInfo): void;
/**
* Removes the destination channel added through {@link addDestChannelInfo}.
* @param channelName The name of the destination channel to be removed.
*/
removeDestChannelInfo(channelName: string): void;
}
declare class ChannelMediaRelayConfiguration implements IChannelMediaRelayConfiguration {
private destChannelMediaInfos;
private srcChannelMediaInfo?;
setSrcChannelInfo(info: ChannelMediaRelayInfo): void;
addDestChannelInfo(info: ChannelMediaRelayInfo): void;
removeDestChannelInfo(channelName: string): void;
}
/**
* Occurs when the state of the connection between the SDK and the server changes.
* @param curState The current connection state.
* @param revState The previous connection state.
* @param reason The reason of disconnection if `curState` is `"DISCONNECTED"`.
* @asMemberOf IAgoraRTCClient
* @event
*/
declare function event_connection_state_change(curState: ConnectionState, revState: ConnectionState, reason?: ConnectionDisconnectedReason): void;
/**
* @since
* <br>   *4.23.0*
*
* Reports the connection state of the local media with PeerConnection.
* @param curState The current connection state. For details, see [RTCPeerConnectionState](https://developer.mozilla.org/en-US/docs/Web/API/RTCPeerConnection/connectionstatechange_event).
* @param revState The previous connection state. For details, see [RTCPeerConnectionState](https://developer.mozilla.org/en-US/docs/Web/API/RTCPeerConnection/connectionstatechange_event).
* @asMemberOf IAgoraRTCClient
* @event
*/
declare function event_peerconnection_state_change(curState: RTCPeerConnectionState, revState: RTCPeerConnectionState): void;
/**
* Occurs when a remote user or host joins the channel.
*
* - In a communication channel, this callback indicates that another user joins the channel and reports the ID of that user. The SDK also triggers this callback to report the existing users in the channel when a user joins the channel.
* - In a live-broadcast channel, this callback indicates that a host joins the channel. The SDK also triggers this callback to report the existing hosts in the channel when a user joins the channel. Ensure that you have no more than 32 hosts in a channel.
*
* The SDK triggers this callback when one of the following situations occurs:
* - A remote user or host joins the channel by calling {@link join}.
* - A remote audience switches the user role to host by calling {@link setClientRole} after joining the channel.
* - A remote user or host rejoins the channel after a network interruption.
* @param user Information of the remote user.
* @asMemberOf IAgoraRTCClient
* @event
*/
declare function event_user_joined(user: IAgoraRTCRemoteUser): void;
/**
* Occurs when a remote user becomes offline.
*
* The SDK triggers this callback when one of the following situations occurs:
* - A remote user calls {@link leave} and leaves the channel.
* - A remote user has dropped offline. If no data packet of the user or host is received for 20 seconds, the SDK assumes that the user has dropped offline. A poor network connection may cause a false positive.
* - A remote user switches the client role from host to audience.
*
* > In live-broadcast channels, the SDK triggers this callback only when a host goes offline.
* @param user Information of the user who is offline.
* @param reason Reason why the user has gone offline.
* - `"Quit"`: The user calls {@link leave} and leaves the channel.
* - `"ServerTimeOut"`: The user has dropped offline.
* - `"BecomeAudience"`: The client role is switched from host to audience.
* @asMemberOf IAgoraRTCClient
* @event
*/
declare function event_user_left(user: IAgoraRTCRemoteUser, reason: string): void;
/**
* Occurs when a remote user publishes an audio or video track.
*
* You can subscribe to and play the audio or video track in this callback. See {@link subscribe} and [RemoteTrack.play]{@link IRemoteTrack.play}.
*
* > The SDK also triggers this callback to report the existing tracks in the channel when a user joins the channel.
*
* ```javascript
* client.on("user-published", async (user, mediaType) => {
* await client.subscribe(user, mediaType);
* if (mediaType === "video") {
* console.log("subscribe video success");
* user.videoTrack.play("xxx");
* }
* if (mediaType === "audio") {
* console.log("subscribe audio success");
* user.audioTrack.play();
* }
* })
* ```
* @param user Information of the remote user.
* @param mediaType Type of the track.
* - `"audio"`: The remote user publishes an audio track.
* - `"video"`: The remote user publishes a video track.
* - `"datachannel"`: Reserved for future use.
* @param config Reserved for future use.
* @asMemberOf IAgoraRTCClient
* @event
*/
declare function event_user_published(user: IAgoraRTCRemoteUser, mediaType: "audio" | "video" | "datachannel", config?: IDataChannelConfig): void;
/**
* Occurs when a remote user unpublishes an audio or video track.
* @param user Information of the remote user.
* @param mediaType Type of the track.
* - `"audio"`: The remote user unpublishes an audio track.
* - `"video"`: The remote user unpublishes a video track.
* @asMemberOf IAgoraRTCClient
* @event
*/
declare function event_user_unpublished(user: IAgoraRTCRemoteUser, mediaType: "audio" | "video" | "datachannel", config?: IDataChannelConfig): void;
/**
* Reports the state change of users.
*
* In most cases, you only need to listen for [user-published]{@link IAgoraRTCClient.event_user_published} and [user-unpublished]{@link IAgoraRTCClient.event_user_unpublished} events for operations including subscribing, unsubscribing, and displaying whether the remote user turns on the camera and microphone. You do not need to pay special attention to user states since the SDK automatically handles user states.
*
* > This event indicating the media stream of a remote user is active does not necessarily mean that the local user can subscribe to this remote user. The local user can subscribe to a remote user only when receiving the [user-published]{@link IAgoraRTCClient.event_user_published} event.
*
* @param uid The ID of the remote user.
* @param msg The current user state. Note that the `"enable-local-video"` and `"disable-local-video"` states are only for synchronizing states with the clients that integrate the RTC Native SDK.
* @asMemberOf IAgoraRTCClient
* @event
*/
declare function event_user_info_updated(uid: UID, msg: "mute-audio" | "mute-video" | "enable-local-video" | "unmute-audio" | "unmute-video" | "disable-local-video"): void;
/**
* Occurs when the SDK starts to reestablish the media connection for publishing and subscribing.
* @param uid The ID of the user who reestablishes the connection. If it is the local `uid`, the connection is for publishing; if it is a remote `uid`, the connection is for subscribing.
* @asMemberOf IAgoraRTCClient
* @event
*/
declare function event_media_reconnect_start(uid: UID): void;
/**
* Occurs when the SDK ends reestablishing the media connection for publishing and subscribing.
* @param uid The ID of the user who reestablishes the connection. If it is the local `uid`, the connection is for publishing; if it is a remote `uid`, the connection is for subscribing.
* @asMemberOf IAgoraRTCClient
* @event
*/
declare function event_media_reconnect_end(uid: UID): void;
/**
* Occurs when the type of a remote video stream changes.
*
* The SDK triggers this callback when a high-quality video stream changes to a low-quality video stream, or vice versa.
* @param uid The ID of the remote user.
* @param streamType The new stream type:
* - 0: High-bitrate, high-resolution video stream.
* - 1: Low-bitrate, low-resolution video stream.
* @asMemberOf IAgoraRTCClient
* @event
*/
declare function event_stream_type_changed(uid: UID, streamType: RemoteStreamType): void;
/**
* Occurs when a remote video stream falls back to an audio stream due to unreliable network conditions or switches back to video after the network conditions improve.
* @param uid The ID of the remote user.
* @param isFallbackOrRecover Whether the remote media stream falls back or recovers:
* - `"fallback"`: The remote media stream falls back to audio-only due to unreliable network conditions.
* - `"recover"`: The remote media stream switches back to the video stream after the network conditions improve.
* @asMemberOf IAgoraRTCClient
* @event
*/
declare function event_stream_fallback(uid: UID, isFallbackOrRecover: "fallback" | "recover"): void;
/**
* Occurs when the state of the media stream relay changes.
*
* The SDK reports the state and error code of the current media relay with this callback.
*
* If the media relay is in an abnormal state, you can find the error code in {@link ChannelMediaRelayError} (for example if the token has expired, or repeated reconnection attempts fail.)
* @param state The state of the media relay.
* @param code The error code.
* @asMemberOf IAgoraRTCClient
* @event
*/
declare function event_channel_media_relay_state(state: ChannelMediaRelayState, code: ChannelMediaRelayError): void;
/**
* Reports events during a media stream relay.
*
* @param event The event code for a media stream relay.
* @asMemberOf IAgoraRTCClient
* @event
*/
declare function event_channel_media_relay_event(event: ChannelMediaRelayEvent): void;
/**
* Reports all the speaking local and remote users and their volumes.
*
* It is disabled by default. You can enable this callback by calling {@link enableAudioVolumeIndicator}.
* If enabled, it reports the users' volumes every two seconds regardless of whether there are users speaking.
*
* The volume is an integer ranging from 0 to 100. Usually a user with volume above 60 is a speaking user.
*
* ``` javascript
* client.on("volume-indicator", function(result){
* result.forEach(function(volume, index){
* console.log(`${index} UID ${volume.uid} Level ${volume.level}`);
* });
* });
* ```
*
* @param result An object consisting of the following properties:
* - level: The volume of the speaking user, ranging from 0 to 100.
* - uid: The ID of the speaking user.
*
* @asMemberOf IAgoraRTCClient
* @event
*/
declare function event_volume_indicator(result: {
/**
* The volume of the speaking user, ranging from 0 to 100.
*/
level: number;
/**
* The ID of the speaking user.
*/
uid: UID;
}[]): void;
/**
* Occurs when decryption fails.
*
* The SDK triggers this callback when the decryption fails during the process of subscribing to a stream. The failure is usually caused by incorrect encryption settings. See {@link setEncryptionConfig} for details.
* @asMemberOf IAgoraRTCClient
* @event
*/
declare function event_crypt_error(): void;
/**
* Occurs 30 seconds before a token expires.
*
* You must request a new token from your server and call {@link renewToken} to pass a new token as soon as possible.
*
* ``` javascript
* client.on("token-privilege-will-expire", async function(){
* // After requesting a new token
* await client.renewToken(token);
* });
* ```
* @asMemberOf IAgoraRTCClient
* @event
*/
declare function event_token_privilege_will_expire(): void;
/**
* Occurs when the token expires.
*
* You must request a new token from your server and call {@link join} to use the new token to join the channel.
*
* ``` javascript
* client.on("token-privilege-did-expire", async () => {
* // After requesting a new token
* await client.join(<APPID>, <CHANNEL NAME>, <NEW TOKEN>);
* });
* ```
*
* @asMemberOf IAgoraRTCClient
* @event
*/
declare function event_token_privilege_did_expire(): void;
/**
* Reports the network quality of the local user.
*
* After the local user joins the channel, the SDK triggers this callback to report the uplink and downlink network conditions of the local user once every two second.
*
* > Agora recommends listening for this event and displaying the network quality.
*
* @param stats The network quality of the local user.
* @asMemberOf IAgoraRTCClient
* @event
*/
declare function event_network_quality(stats: NetworkQuality): void;
/**
* Occurs when an error occurs in CDN live streaming.
*
* After the method call of {@link startLiveStreaming} succeeds, the SDK triggers this callback when errors occur during CDN live streaming.
*
* You can visit `err.code` to get the error code. The errors that you may encounter include:
* - `LIVE_STREAMING_INVALID_ARGUMENT`: Invalid argument.
* - `LIVE_STREAMING_INTERNAL_SERVER_ERROR`: An error occurs in Agora's streaming server.
* - `LIVE_STREAMING_PUBLISH_STREAM_NOT_AUTHORIZED`: The URL is occupied.
* - `LIVE_STREAMING_TRANSCODING_NOT_SUPPORTED`: Sets the transcoding parameters when the transcoding is not enabled.
* - `LIVE_STREAMING_CDN_ERROR`: An error occurs in the CDN.
* - `LIVE_STREAMING_INVALID_RAW_STREAM`: Timeout for the CDN live streaming. Please check your media stream.
*
* @param url The URL of the CDN live streaming that has errors.
* @param err The error details.
* @asMemberOf IAgoraRTCClient
* @event
*/
declare function event_live_streaming_error(url: string, err: AgoraRTCError): void;
/**
* Occurs when a warning occurs in CDN live streaming.
*
* After the method call of {@link startLiveStreaming} succeeds, the SDK triggers this callback when warnings occur during CDN live streaming.
*
* You can visit `err.code` to get the warning code. The warnings that you may encounter include:
* - `LIVE_STREAMING_WARN_STREAM_NUM_REACH_LIMIT`: Pushes stremas to more than 10 URLs.
* - `LIVE_STREAMING_WARN_FAILED_LOAD_IMAGE`: Fails to load the background image or watermark image.
* - `LIVE_STREAMING_WARN_FREQUENT_REQUEST`: Pushes stremas to the CDN too frequently.
*
* @param url The URL of the CDN live streaming that has warnings.
* @param warning The warning details.
* @asMemberOf IAgoraRTCClient
* @event
*/
declare function event_live_streaming_warning(url: string, warning: AgoraRTCError): void;
/**
* @since
* <br>   *4.4.0*
*
* The SDK triggers this callback to indicate whether the media stream is forwarded by the Agora cloud proxy service.
* - Earlier than v4.10.0: The callback is triggered after the method call of [[publish]] succeeds.
* - v4.10.0 and later: The callback is triggered after the method call of [[join]] succeeds.
*
* @param isUsingProxy Whether the media stream is forwarded by the Agora cloud proxy service.
* - `true`: Forwarded by the Agora cloud proxy service.
* - `false`: Not forwarded by the Agora cloud proxy service.
* @asMemberOf IAgoraRTCClient
* @event
*/
declare function event_is_using_cloud_proxy(isUsingProxy: boolean): void;
/**
* @deprecated from v4.19.0. This callback will not be triggered because the SDK stops using proxy to ensure connectivity.
*
* Occurs when the SDK automatically switches to TCP/TLS 443.
*
* As of v4.11.0, if the SDK fails in the attempt to directly connect to Agora SD-RTN™ after you call [[join]],
* the SDK automatically switches to TCP/TLS 443 in order to ensure connectivity.
*
* @param proxyServer The server address used after the switch.
* @asMemberOf IAgoraRTCClient
* @event
*/
declare function event_join_fallback_to_proxy(proxyServer: string): void;
/**
* @since
* <br>   *4.11.0*
*
* If you enable support for 128 hosts in a channel, this callback is triggered when [[join]] is called.
* The callback reports remote users who publish audio and/or video tracks in the channel.
*
* > Note:
* > - For the `published-user-list` to be triggered, every user in the channel must use a number as their user ID (`uid`).
* > - `published-user-list` has the following impacts on [AgoraRTCClient.on("user-joined")]{@link event_user_joined} and [AgoraRTCClient.on("user-published")]{@link event_user_published}:
* > - If you listen for the `published-user-list` event, users reported by the `published-user-list` callback are not reported by `user-joined` and `user-published`.
* > - If you do not listen for the `published-user-list` event, the `user-joined` and `user-published` callbacks are not affected.
*
* @param users The remote user.
*
* @asMemberOf IAgoraRTCClient
* @event
*/
declare function event_published_user_list(users: IAgoraRTCRemoteUser[]): void;
declare function event_content_inspect_connection_state_change(preState: InspectState, newState: InspectState): void;
declare function event_content_inspect_error(error?: AgoraRTCError): void;
declare function event_image_moderation_connection_state_change(newState: ImageModerationConnectionState, preState: ImageModerationConnectionState): void;
/**
* Callback for receiving the DataStream message.
*
* ```javascript
* client.on("stream-message", (uid, payload) => {
* console.info(`received data stream message from ${uid}: `, payload);
* });
* ```
*
* @param uid UID of the message sender.
* @param payload Message content.
*
* @asMemberOf IAgoraRTCClient
* @event
*/
declare function event_stream_message(uid: UID, payload: Uint8Array): void;
/**
* Reports exceptions in the channel.
*
* Exceptions are not errors, but usually reflect quality issues.
*
* This callback also reports recovery from an exception.
*
* Each exception corresponds to a recovery event.
*
* **Exception**
*
* | Code | Message | Exception |
* | :----- | :------------------------- | :--------------- |
* | 1001 | FRAMERATE_INPUT_TOO_LOW | Captured video frame rate is too low |
* | 1002 | FRAMERATE_SENT_TOO_LOW | Sent video frame rate is too low |
* | 1003 | SEND_VIDEO_BITRATE_TOO_LOW | Sent video bitrate is too low |
* | 1005 | RECV_VIDEO_DECODE_FAILED | Decoding received video fails |
* | 2001 | AUDIO_INPUT_LEVEL_TOO_LOW | Sent audio volume is too low |
* | 2002 | AUDIO_OUTPUT_LEVEL_TOO_LOW | Received audio volume is too low |
* | 2003 | SEND_AUDIO_BITRATE_TOO_LOW | Sent audio bitrate is too low |
* | 2005 | RECV_AUDIO_DECODE_FAILED | Decoding received audio fails |
*
* **Recoveries**
*
* | Code | Message | Recovery |
* | :----- | :------------------------- | :--------------- |
* |3001 | FRAMERATE_INPUT_TOO_LOW_RECOVER | Captured video frame rate recovers |
* |3002 | FRAMERATE_SENT_TOO_LOW_RECOVER | Sent video frame rate recovers |
* |3003 | SEND_VIDEO_BITRATE_TOO_LOW_RECOVER | Sent video bitrate recovers |
* |3005 | RECV_VIDEO_DECODE_FAILED_RECOVER | Decoding received video recovers |
* |4001 | AUDIO_INPUT_LEVEL_TOO_LOW_RECOVER | Sent audio volume recovers |
* |4002 | AUDIO_OUTPUT_LEVEL_TOO_LOW_RECOVER | Received audio volume recovers |
* |4003 | SEND_AUDIO_BITRATE_TOO_LOW_RECOVER | Sent audio bitrate recovers |
* |4005 | RECV_AUDIO_DECODE_FAILED_RECOVER | Decoding received audio recovers |
*
* @asMemberOf IAgoraRTCClient
* @event
*/
declare function event_exception(event: {
/**
* The event code.
*/
code: number;
/**
* The event message.
*/
msg: string;
/**
* The ID of the user who has experienced the exception or recovery event.
*/
uid: UID;
}): void;
/**
* An interface providing the local client with basic functions for a voice or video call, such as joining a channel, publishing tracks, or subscribing to tracks.
*
* An `AgoraRTCClient` object is created by the [[createClient]] method.
* @public
*/
interface IAgoraRTCClient extends EventEmitter {
/**
* Connection state between the SDK and the Agora server.
*/
readonly connectionState: ConnectionState;
/**
* A list of the remote users in the channel, each of which includes the user ID and the corresponding track information.
*
* The list is empty if the local user has not joined a channel.
*/
readonly remoteUsers: IAgoraRTCRemoteUser[];
/**
* @since
* <br>   *4.0.0*
*
* The list of the local tracks that the local user is publishing.
*
* - After a success method call of [[publish]], the published track object is added to this list automatically.
* - After a success method call of [[unpublish]], the unpublished track object is removed from this list automatically.
*/
readonly localTracks: ILocalTrack[];
/**
* The ID of the local user.
*
* The value is `undefined` if the local user has not joined a channel.
*/
readonly uid?: UID;
/**
* The current channel name.
*
* The value is `undefined` if the local user has not joined a channel.
*/
readonly channelName?: string;
/**
* @ignore
*/
readonly localDataChannels: ILocalDataChannel[];
/**
* @ignore
* @since
* <br>   *4.18.1*
*
* The current channel profile.
*/
readonly mode: SDK_MODE;
/**
* @ignore
* @since
* <br>   *4.18.1*
*
* The current user role.
*/
readonly role: ClientRole;
/**
* @since
* <br>   *4.23.0*
*
* Occurs when the connection state to PeerConnection changes.
*
* @param event The event name.
* @param listener See [peerconnection-state-change]{@link event_peerconnection_state_change}.
*/
on(event: "peerconnection-state-change", listener: typeof event_peerconnection_state_change): void;
/**
* Occurs when the connection state between the SDK and server changes.
* @param event The event name.
* @param listener See [connection-state-change]{@link event_connection_state_change}.
*/
on(event: "connection-state-change", listener: typeof event_connection_state_change): void;
/**
* Occurs when a remote user or broadcaster joins the channel.
* @param event The event name.
* @param listener See [user-joined]{@link event_user_joined}.
*/
on(event: "user-joined", listener: typeof event_user_joined): void;
/**
* Occurs when a remote user or broadcaster leaves the channel.
*
* @param event The event name.
* @param listener See [user-left]{@link event_user_left}.
*/
on(event: "user-left", listener: typeof event_user_left): void;
/**
*
* Occurs when a remote user publishes a new audio or video track.
*
* @param event The event name.
* @param listener See [user-published]{@link event_user_published}.
*/
on(event: "user-published", listener: typeof event_user_published): void;
/**
* Occurs when a remote user stops publishing the audio or video track.
* @param event The event name.
* @param listener See [user-unpublished]{@link event_user_unpublished}.
*/
on(event: "user-unpublished", listener: typeof event_user_unpublished): void;
/**
* Occurs when the user info changes.
* @param event The event name.
* @param listener See [user-info-updated]{@link event_user_info_updated}.
*/
on(event: "user-info-updated", listener: typeof event_user_info_updated): void;
/**
* Occurs when the SDK starts establishing media connection (for publishing and subscribing to media).
*
* @param event The event name.
* @param listener See [media-reconnect-start]{@link event_media_reconnect_start}.
*/
on(event: "media-reconnect-start", listener: typeof event_media_reconnect_start): void;
/**
* Occurs when the SDK stops establishing media connection (for publishing and subscribing to media).
* @param event The event name.
* @param listener See [media-reconnect-end]{@link event_media_reconnect_end}.
*/
on(event: "media-reconnect-end", listener: typeof event_media_reconnect_end): void;
/**
* Occurs when the subscribed video stream type changes.
* @param event The event name.
* @param listener See [stream-type-changed]{@link event_stream_type_changed}.
*/
on(event: "stream-type-changed", listener: typeof event_stream_type_changed): void;
/**
* Occurs when the subscribed audio and video stream falls back to audio stream, or resumes from audio stream to audio and video stream.
*
* @param event The event name.
* @param listener See [stream-fallback]{@link event_stream_fallback}.
*/
on(event: "stream-fallback", listener: typeof event_stream_fallback): void;
/**
* Occurs when the media relay state changes.
*
* @param event The event name.
* @param listener See [channel-media-relay-state]{@link event_channel_media_relay_state}.
*/
on(event: "channel-media-relay-state", listener: typeof event_channel_media_relay_state): void;
/**
* Reports media relay events.
* @param event The event name.
* @param listener See [channel-media-relay-event]{@link event_channel_media_relay_event}.
*/
on(event: "channel-media-relay-event", listener: typeof event_channel_media_relay_event): void;
/**
* Reports the local user and remote users that are talking at the moment, together with their voice volumes.
*
* @param event The event name.
* @param listener See [volume-indicator]{@link event_volume_indicator}.
*/
on(event: "volume-indicator", listener: typeof event_volume_indicator): void;
/**
* Reports when a decryption error occurs.
* @param event The event name.
* @param listener See [crypt-error]{@link event_crypt_error}.
*/
on(event: "crypt-error", listener: typeof event_crypt_error): void;
/**
* Occurs when the token is about to expire in 30 seconds.
*
* @param event The event name.
* @param listener See [token-privilege-will-expire]{@link event_token_privilege_will_expire}.
*/
on(event: "token-privilege-will-expire", listener: typeof event_token_privilege_will_expire): void;
/**
* Occurs when the token has expired.
*
* @param event The event name.
* @param listener See [token-privilege-did-expire]{@link event_token_privilege_did_expire}.
*/
on(event: "token-privilege-did-expire", listener: typeof event_token_privilege_did_expire): void;
/**
* Reports the uplink and downlink netowrk quality.
* @param event The event name.
* @param listener See [network-quality]{@link event_network_quality}.
*/
on(event: "network-quality", listener: typeof event_network_quality): void;
/**
* Occurs when a streaming error occurs.
* @param event The event name.
* @param listener See [live-streaming-error]{@link event_live_streaming_error}.
*/
on(event: "live-streaming-error", listener: typeof event_live_streaming_error): void;
/**
* Occurs when a streaming warning occurs.
* @param event The event name.
* @param listener See [live-streaming-warning]{@link event_live_streaming_warning}.
*/
on(event: "live-streaming-warning", listener: typeof event_live_streaming_warning): void;
/**
* Occurs when the SDK detects an exception.
*
* @param event The event name.
* @param listener See [exception]{@link event_exception}.
*/
on(event: "exception", listener: typeof event_exception): void;
/**
* Reports whether the current media stream is using cloud proxy for transmission.
* @param event The e