DingRTCClient
DingRTCClient provides core audio and video calling capabilities, including joining a channel, publishing local audio or video tracks, and subscribing to remote audio or video tracks. Create a client instance by calling createClient(). Each client instance represents a local client.
Properties
Property | Type | Description | Minimum supported version |
channelName | string | The channel name. If the local user has not joined a channel, this property is undefined. | 3.0.0 |
connectionState | The connection state between the SDK instance and the server. | 3.0.0 | |
localTracks | A list of local track objects currently being published. After you successfully call publish, the published track is automatically added to this list. After you successfully call unpublish, the unpublished track is automatically removed from this list. | 3.0.0 | |
remoteUsers
| A list of remote user information. This includes each remote user's ID and track information in the channel. If the local user has not joined a channel, this list is empty. | 3.0.0 | |
userId | string | The local user's ID. If the local user has not joined a channel, this property is undefined. | 3.0.0 |
groups | Group[] | A list of audio group information for the current channel. | 3.4.0 |
Methods
Interface | Description | Minimum supported version |
Get local audio statistics. | 3.0.0 | |
You can retrieve information about the local video. | 3.0.0 | |
Get video statistics for a remote user. | 3.3.0 | |
Get network quality scores for a remote user. | ||
Join a channel. Users in the same channel can communicate with each other. When you call this method, the local client triggers the "connection-state-change" callback. After the local client joins the channel, remote clients trigger the "user-joined" callback. | 3.0.0 | |
Leave a channel. This ends or exits the call. When you call this method, the local client triggers the "connection-state-change" callback. Remote clients trigger the "user-left" callback. | 3.0.0 | |
Publish a local audio or video track to the channel. After publishing an audio or video track, remote clients trigger the "user-published" callback. | 3.0.0 | |
Stop publishing a local audio or video track. After stopping publication of an audio or video track, remote clients trigger the "user-unpublished" callback. | 3.0.0 | |
Set the default video stream type for all remote users. If a remote user enables dual-stream mode, the local client subscribes to the stream type specified by the streamType parameter when you call subscribe. If you do not set this, the default is the high-resolution stream. | 3.0.0 | |
Set the video stream type for a specific remote user. | 3.0.0 | |
Subscribe to a remote user's audio or video track. | 3.0.0 | |
Unsubscribe from a remote user's audio or video track. | 3.0.0 | |
Subscribe to multiple remote users' audio and video tracks at once. | 3.1.0 | |
Unsubscribe from multiple remote users' audio and video tracks at once. | 3.1.0 | |
Remove a listener callback for a specified event. | 3.0.0 | |
Add a listener callback for a specified event. | 3.0.0 | |
Add a listener callback for a specified event. The callback runs only once and is then removed. | 3.0.0 | |
Remove all listener callbacks for a specified event or for all events. | 3.0.0 | |
Join a specified audio group. | 3.4.0 | |
Leave a specified audio group. | 3.4.0 | |
Dismiss a specified audio group. | 3.4.0 | |
Subscribe to a specified audio group. | 3.4.0 | |
Unsubscribe from a specified audio group. | 3.4.0 | |
Mix or unmix a specified audio track into a group or the main channel. | 3.4.0 | |
Set the group name. | 3.5.0 |
Events
Event | Parameters | Description | Minimum supported version |
(curState:ConnectionState, prevState:ConnectionState, reason?:DisconnectedReason) => void | Triggered when the SDK's connection state with the server changes. | 3.0.0 | |
(uid: string) => void | Triggered when the SDK finishes re-establishing media connections for publishing and subscribing. | 3.0.0 | |
(uid: string) => void | Triggered when the SDK starts trying to re-establish media connections for publishing and subscribing. | 3.0.0 | |
(uid: string, streamType:RemoteStreamType) => void | Triggered when the subscribed video stream type changes. A change means switching between the high-resolution stream (high bitrate, high resolution) and the low-resolution stream (low bitrate, low resolution). | 3.0.0 | |
(uid: string, msg: 'mute-audio' | 'mute-video' | 'unmute-audio' | 'unmute-video') => void | Notifies you of a user status change. In most cases, listen for "user-published" and "user-unpublished" to handle subscription, unsubscription, and display whether remote users have turned on their cameras or microphones. You do not need to monitor actual user status changes. The SDK handles them automatically. | 3.0.0 | |
"user-mic-audio-muted" | (uid: string, muted: boolean) => void | Indicates whether the user's microphone audio is muted. | |
"user-screencast-audio-mixed" | (uid: string, mixed: boolean) => void | Indicates whether the user's screen-sharing audio is mixed into the published audio stream. | |
(user:RemoteUser) => void | Triggered when a remote user or streamer joins the channel. | 3.0.0 | |
(user:RemoteUser) => void | Triggered when a remote user or streamer leaves the channel. | 3.0.0 | |
(user:RemoteUser, mediaType:TrackMediaType, auxiliary?: boolean) => void | Notifies you that a remote user has published a new audio or video track. Subscribe to and play the remote user's audio or video track in this callback. | 3.0.0 | |
(user:RemoteUser, mediaType:TrackMediaType, auxiliary?: boolean) => void | Notifies you that a remote user has stopped publishing an audio or video track. | 3.0.0 | |
(uids: string[]) => void | Lists remote users who are speaking in the channel. This event activates automatically when three or more users are in the channel. uids lists the UIDs of speaking users. The first UID is the user with the highest volume. An empty list means no one is speaking. | 3.0.0 | |
(uplinkNetworkQuality:NetworkQuality, downlinkNetworkQuality:NetworkQuality) => void | Reports the client-side network quality. This event triggers every two seconds after joining a channel. Use it as a reference only. | 3.0.0 | |
(group: Group) => void; | Triggered when a group is added. | 3.4.0 | |
(group: Group) => void; | Group Removal Event | 3.4.0 | |
(groupId: string, groupUser: GroupUser) => void; | Triggered when a member joins a group. | 3.4.0 | |
(groupId: string, groupUser: GroupUser) => void; | Triggered when a member leaves a group. | 3.4.0 | |
'group-info-updated': ( groupId: string, updateType: GroupPropertyUpdateTypes, value?: string, ) => void; | Triggered when a group property changes. | 3.5.0 |
API Details
getLocalAudioStats()
Retrieve local audio statistics.
Type Signature
getLocalAudioStats(): LocalAudioStates;
Returns
getLocalVideoStats()
Retrieve local video statistics.
Signature
getLocalVideoStats(): LocalVideoStatesMap;
Returns
getRemoteVideoStats()
Retrieve video statistics for a remote user.
Type Signature
getRemoteVideoStats(): RemoteVideoStatesMap;
Back
getRemoteNetworkQuality()
Retrieve network quality statistics for a remote user. Remote users must use version 3.3.0 or later to provide this data.
Signature
getRemoteNetworkQuality(): {
[uid: string]: {
downlinkNetworkQuality: NetworkQuality,
uplinkNetworkQuality: NetworkQuality,
}
};
Back
{
[uid: string]: {
downlinkNetworkQuality: NetworkQuality,
uplinkNetworkQuality: NetworkQuality,
}
};
join()
Join a channel. Users in the same channel can communicate with each other.
You can call this method to join a channel. When you do, the local client triggers the connection-state-change event.
After the local client joins the channel, remote clients trigger the user-joined event.
Signature
join(joinInfo: JoinParam): Promise<{
remoteUsers: RemoteUser[];
timeLeft: number;
}>;
Parameters:
Parameter | Type | Description |
joinInfo | Parameters required to join the channel. |
Returns:
Parameter | Type | Description | Version |
remoteUsers | RemoteUser[]; | A list of remote users. | 3.0.0 |
timeLeft | number | Remaining time for the channel. | 3.1.0 |
Back
Promise<{ remoteUsers: RemoteUser[]; timeLeft: number }>
leave()
Leave a channel. This ends or exits the call.
You can call this method to leave a channel. When you do, the local client triggers the connection-state-change event.
Remote clients trigger the user-left event.
Type Signature
leave(): void;
Back
void
publish()
Publish a local audio or video track to the channel.
After publishing an audio or video track, remote clients trigger the user-published event.
Type Signature
publish(tracks: LocalTrack | LocalTrack[]): Promise<void>;
Parameter | Type | Description |
tracks | A local track object created using DingRTC.createMicrophoneAudioTrack, DingRTC.createCameraTrack, or another method. |
Returns
Promise<void>
setRemoteDefaultVideoStreamType()
Set the default video stream type for all remote users.
If a remote user enables dual-stream mode, the local client subscribes to the stream type specified by the streamType parameter when you call subscribe(). If you do not set this, the default is the high-resolution stream.
Signature
setRemoteDefaultVideoStreamType(streamType: RemoteStreamType): void;
Parameter | Type | Description |
streamType | The video stream type to subscribe to. "high" means the high-resolution stream. "low" means the low-resolution stream. |
Back
void
setRemoteVideoStreamType()
Set the video stream type for a specific remote user.
Type signature
setRemoteVideoStreamType(uid: string, streamType: RemoteStreamType): Promise<void>;
Parameter | Type | Description |
uid | string | The remote user's ID. |
streamType | The video stream type to subscribe to. "high" means the high-resolution stream. "low" means the low-resolution stream. |
Returns
Promise<void>
subscribe()
Subscribe to a remote user's audio or video track.
Type signature
subscribe(uid: string, mediaType: TrackMediaType, auxiliary?: boolean): Promise<RemoteAudioTrack | RemoteVideoTrack>;
Parameter | Type | Description |
uid | string | The remote user's ID. |
mediaType | The media type of the track to subscribe to. | |
auxiliary | boolean | (Optional) If subscribing to a video track, indicates whether to subscribe to the desktop sharing video stream. |
Back
Promise<RemoteAudioTrack|RemoteVideoTrack>
batchSubscribe()
Subscribe to multiple remote users' audio and video tracks at once.
Type signature
batchSubscribe(batchSubscribeParam: SubscribeParam[]): Promise<SubscribeResult[]>;
Parameter | Type | Description |
batchSubscribeParam | Parameters for subscribing to remote audio and video tracks. |
Returns
Promise<SubscribeResult[]>
Subscribing to individual audio streams is not yet supported. To subscribe to audio, set userId to the string "mcu". This subscribes to the merged audio stream from all remote users in the channel. You only need to subscribe to the MCU audio stream once. When new remote users publish audio, their streams are automatically mixed into your existing MCU audio subscription.
unpublish()
Stop publishing a local audio or video track.
After stopping publication of an audio or video track, remote clients trigger the user-unpublished event.
Signature
unpublish(tracks?: LocalTrack | LocalTrack[]): Promise<void>;
Parameter | Type | Description |
tracks | (Optional) The track or tracks to stop publishing. If omitted, all published audio and video tracks are stopped. |
Back
Promise<void>
unsubscribe()
Unsubscribe from a remote user's audio or video track.
Signature
unsubscribe(uid: string, mediaType?: TrackMediaType, auxiliary?: boolean): Promise<void>;
Parameter | Type | Description |
uid | string | The remote user's ID. |
mediaType | (Optional) The media type of the track to unsubscribe from. | |
auxiliary | boolean | (Optional) Indicates whether the video track subscription is for a desktop sharing video stream. |
Back
Promise<void>
batchUnsubscribe()
You can batch subscribe to audio and video tracks of remote users.
Type signature
batchUnsubscribe(batchUnsubscribeParam: UnsubscribeParam[]): Promise<void>;
Parameter | Type | Description |
batchUnsubscribeParam | Parameters for unsubscribing from remote audio and video tracks. |
Returns
Promise<void>
Unsubscribing from individual audio streams is not yet supported. To unsubscribe from audio, set userId to the string "mcu". This unsubscribes from the merged audio stream from all remote users in the channel. You only need to unsubscribe from the MCU audio stream once. Support for unsubscribing from individual audio streams will be available soon.
on()
Add a listener callback for a specified event.
Type Signature
on(event: string, fn: Function): void;
Parameters
Parameter | Type | Description |
event | string | The event to listen for. |
fn | Function | The callback function to run when the event triggers. |
Back
void
off()
Remove a listener callback for a specified event.
Type Signature
off(event: string, fn: Function): void;
Parameters
Parameter | Type | Description |
event | string | The event to listen for. |
fn | Function | The callback function to run when the event triggers. |
Back
void
once()
Add a listener callback for a specified event. The callback runs only once and is then removed.
Signature
once(event: string, fn: Function): void;
Parameters
Parameter | Type | Description |
event | string | The event to listen for. |
fn | Function | The callback function to run when the event triggers. |
Back
void
removeAllListeners()
Remove all listener callbacks for a specified event or for all events.
Type Signature
removeAllListeners(event?: string): void;
Parameters
Parameter | Type | Description |
event | string | (Optional) If you specify an event, only its listeners are removed. If you omit this parameter, all listeners for all events are removed. |
Back
void
joinGroup()
Join a specified audio group.
Signature
joinGroup(config?: JoinGroupConfig): Promise<void>;
Parameters
Parameter | Type | Description |
config | Configuration options for joining an audio group. |
Back
Promise<void>
leaveGroup()
Leave a specified audio group.
Type Signature
leaveGroup(groupId: string): Promise<void>;
Parameters
Parameter | Type | Description |
groupId | string | The audio group ID. |
Returns
Promise<void>
dismissGroup()
Dismiss a specified audio group.
Type signature
dismissGroup(groupId: string): Promise<void>;
Parameters
Parameter | Type | Description |
groupId | string | The audio group ID. |
Returns
Promise<void>
subscribeGroup()
Subscribe to a specified audio group.
Signature
subscribeGroup(groupId: string): Promise<RemoteAudioTrack>;
Parameters
Parameter | Type | Description |
groupId | string | The audio group ID. |
You cannot subscribe to an audio group if you are already subscribed to the MCU audio stream. First unsubscribe from the MCU audio stream.
You can only subscribe to audio groups you have joined.
You can subscribe to only one audio group at a time.
Back
Promise<RemoteAudioTrack>
unsubscribeGroup()
Unsubscribe from a specified audio group.
Signature
unsubscribeGroup(groupId: string): Promise<void>;
Parameters
Parameter | Type | Description |
groupId | string | The audio group ID. |
Back
Promise<void>
mixAudioToGroup()
Mix or unmix a specified audio track into a group or the main channel.
Signature
mixAudioToGroup(track: LocalAudioTrack, mixed: boolean, groupId?: string): Promise<void>;
Parameters
Parameter | Type | Description |
track | A local audio track. | |
mixed | boolean | Set to true to mix audio. Set to false to cancel mixing. |
groupId | string | The audio group ID to publish to. |
If you omit the audio group ID, the audio track publishes to the main channel.
You can publish an audio track to the main channel and multiple groups at the same time.
Back
Promise<void>
setGroupName()
Set the group name. The system then triggers the "group-info-updated" event.
Type signature
setGroupName(grupId: string, name: string): Promise<void>;Parameters
Parameter | Type | Description |
groupId | string | The audio group ID. |
name | string | The group name. Must be UTF-8 encoded and no longer than 64 bytes. |
Back
Promise<void>
Event details
"connection-state-change"
Triggered when the SDK's connection state with the server changes.
Type Signature
'connection-state-change': (curState: ConnectionState, prevState: ConnectionState, reason?: DisconnectedReason) => void;"media-reconnect-end"
Triggered when the SDK finishes re-establishing media connections for publishing and subscribing.
Type Signature
'media-reconnect-end': (uid: string) => void;
"media-reconnect-start"
Triggered when the SDK starts trying to re-establish media connections for publishing and subscribing.
Type signature
'media-reconnect-start': (uid: string) => void;
"stream-type-changed"
Triggered when the subscribed video stream type changes. A change means switching between the high-resolution stream (high bitrate, high resolution) and the low-resolution stream (low bitrate, low resolution).
Signature
'stream-type-changed': (uid: string, streamType: RemoteStreamType) => void;
"user-info-updated"
Notifies you of a user status change.
In most cases, listen for user-published and user-unpublished to handle subscription, unsubscription, and display whether remote users have turned on their cameras or microphones. You do not need to monitor actual user status changes. The SDK handles them automatically.
Signature
'user-info-updated': (uid: string, msg: 'mute-audio' | 'mute-video' | 'unmute-audio' | 'unmute-video') => void;"user-joined"
Triggered when a remote user joins the channel.
Signature
'user-joined': (user: RemoteUser) => void;
"user-left"
Triggered when a remote user leaves the channel.
Type signature
'user-left': (user: RemoteUser) => void;
"user-published"
Notifies you that a remote user has published a new audio or video track.
Subscribe to and play the remote user's audio or video track in this callback.
Type signature
'user-published': (user: RemoteUser, mediaType: TrackMediaType, auxiliary?: boolean) => void;
"user-unpublished"
Notifies you that a remote user has stopped publishing an audio or video track.
Type Signature
'user-unpublished': (user: RemoteUser, mediaType: TrackMediaType, auxiliary?: boolean) => void;
"volume-indicator"
Lists remote users who are speaking in the channel. This event activates automatically when three or more users are in the channel.
The uids array lists the UIDs of speaking users. The first UID is the user with the highest volume. An empty list means no one is speaking.
Signature
'volume-indicator': (uids: string[]) => void;
"network-quality"
Reports the client-side network quality. This event triggers every two seconds after joining a channel. Use it as a reference only.
Type signature
'network-quality': (uplinkNetworkQuality: NetworkQuality, downlinkNetworkQuality: NetworkQuality) => void;"group-add"
Add an event to a group
Type Signature
Group'group-add': (group: <a baseurl="t2584364_v1_0_6.xdita" data-node="4688872" data-root="16740" data-tag="xref" href="t2584362.xdita#1b0c579aac71h" id="65e105bd1amn3">Group</a>) => void;"group-remove"
Group removal event
Type signature
Group'group-remove': (group: <a baseurl="t2584364_v1_0_6.xdita" data-node="4688872" data-root="16740" data-tag="xref" href="t2584362.xdita#1b0c579aac71h" id="d5ebb883ca5tl">Group</a>) => void;"group-user-join"
Triggered when a member joins a group.
Type signature
GroupUser'group-user-join': (groupId: string, groupUser: <a baseurl="t2584364_v1_0_6.xdita" data-node="4688872" data-root="16740" data-tag="xref" href="t2584362.xdita#16c1078b3d39c" id="20c2f2d10231m">GroupUser</a>) => void;"group-user-leave"
Group member departure (event)
Type signature
GroupUser'group-user-leave': (groupId: string, groupUser: <a baseurl="t2584364_v1_0_6.xdita" data-node="4688872" data-root="16740" data-tag="xref" href="t2584362.xdita#16c1078b3d39c" id="2942c29af5h57">GroupUser</a>) => void;"group-info-updated"
Triggered when a group property changes.
Type signature
GroupPropertyUpdateTypes 'group-info-updated': (groupId: string, updateType: <a baseurl="t2584364_v1_0_9.xdita" data-node="4688872" data-root="16740" data-tag="xref" href="t2584362.xdita#84e1106d45xq7" id="0db4780e42che">GroupPropertyUpdateTypes</a>, value?: string) => void;