DingRTCClient
DingRTCClient provides the core features for audio and video calls, such as joining channels, and publishing and subscribing to audio and video tracks. You can create a Client object by calling `DingRTC.createClient`. A Client object represents a local client.
Properties
Property | Type | Description | Minimum supported version |
localTracks | A list of local track objects that are currently published. After a successful call to `publish`, the published track object is automatically added to this list. After a successful call to `unpublish`, the track object is automatically removed from this list. | 1.0.0 | |
userId | string | The user ID of the local user. If the local user has not joined a channel, this property is `undefined`. | 1.0.0 |
API List
Interface | Description | Minimum supported version |
Gets the network quality information of remote users. | ||
Joins a channel. Users in the same channel can communicate with each other. Calling this method triggers the "connection-state-change" callback locally. After the local client successfully joins the channel, remote clients trigger the "user-joined" callback. | 1.0.0 | |
Leaves the channel and ends the call. Calling this method triggers the "connection-state-change" callback on the local client. Remote clients trigger the "user-left" callback. | 1.0.0 | |
Publishes local audio and video tracks to the channel. After the tracks are published, remote clients trigger the "user-published" callback. | 1.0.0 | |
Unpublishes local audio and video tracks. After the tracks are unpublished, remote clients trigger the "user-unpublished" callback. | 1.0.0 | |
Sets the video stream type for subscriptions to all remote users. If a remote user has dual-stream mode enabled, the local client subscribes to the stream type specified by the `streamType` parameter after calling `subscribe`. If not set, the high-quality stream is subscribed to by default. | 1.0.0 | |
Sets the video stream type for a subscription to a specific remote user. | 1.0.0 | |
Subscribes to the audio and video tracks of a remote user. | 1.0.0 | |
Unsubscribes from the audio and video tracks of a remote user. | 1.0.0 | |
Subscribes to the audio and video tracks of multiple remote users in a batch. | 1.0.0 | |
Unsubscribes from the audio and video tracks of multiple remote users in a batch. | 1.0.0 | |
Removes the callback function for a specific event listener. | 1.0.0 | |
Adds a listener and sets a callback function for a specific event. | 1.0.0 | |
Adds a one-time listener for a specific event. The listener is removed after the callback function is triggered. | 1.0.0 | |
Removes the listeners for a specific event or for all events on this object. | 1.0.0 |
Events
Event | Event parameter | Description | Minimum supported version |
(curState:ConnectionState, prevState:ConnectionState, reason?:DisconnectedReason) => void | A callback that is triggered when the connection state between the SDK and the server changes. | 1.0.0 | |
(uid: string) => void | A callback that is triggered when the SDK finishes re-establishing the media connection for publishing and subscribing. | 1.0.0 | |
(uid: string) => void | A callback that is triggered when the SDK starts to re-establish the media connection for publishing and subscribing. | 1.0.0 | |
(uid: string, streamType:RemoteStreamType) => void | A callback that is triggered when the subscribed video stream type changes. A stream type change can be from a high-quality stream (high bitrate and high resolution) to a low-quality stream (low bitrate and low resolution), or from a low-quality stream to a high-quality stream. | 1.0.0 | |
(uid: string, msg: 'mute-audio' | 'mute-video' | 'unmute-audio' | 'unmute-video') => void | This callback notifies you of a change in a user's status. In most cases, you only need to listen for the `user-published` and `user-unpublished` events to manage subscriptions and to show whether a remote user's camera and microphone are on. The SDK handles user status changes automatically. | 1.0.0 | |
(user:RemoteUser) => void | A callback that is triggered when a remote user or streamer joins the channel. | 1.0.0 | |
(user:RemoteUser) => void | A callback that is triggered when a remote user or streamer leaves the channel. | 1.0.0 | |
(user:RemoteUser, mediaType:TrackMediaType, auxiliary?: boolean) => void | This callback notifies you that a remote user has published a new audio or video track. You can subscribe to and play the remote user's audio and video tracks in this callback. | 1.0.0 | |
(user:RemoteUser, mediaType:TrackMediaType, auxiliary?: boolean) => void | This callback notifies you that a remote user has unpublished an audio or video track. | 1.0.0 | |
(uids: string[]) => void | Indicates the list of remote users who are currently speaking in the channel. This feature is automatically enabled when three or more users are in the channel. The `uids` parameter is a list of the speakers' user IDs. The first user ID in the list belongs to the loudest speaker. An empty list means that no one is speaking. | 1.0.0 | |
(uplinkNetworkQuality:NetworkQuality, downlinkNetworkQuality:NetworkQuality) => void | A callback that reports the network quality on the client side. It is triggered every 2 seconds after joining a channel and is for reference only. | 1.0.0 |
Interface details
getRemoteNetworkQuality()
Retrieves the network statistics of remote users. To retrieve this information, the remote users must also be using version 1.0.0 or later.
Type signature
getRemoteNetworkQuality(): {
[uid: string]: {
downlinkNetworkQuality: NetworkQuality,
uplinkNetworkQuality: NetworkQuality,
}
};
Returns
{
[uid: string]: {
downlinkNetworkQuality: NetworkQuality,
uplinkNetworkQuality: NetworkQuality,
}
};
join()
Joins a channel. Users in the same channel can communicate with each other.
Calling this method triggers the "connection-state-change" callback locally.
After the local client successfully joins the channel, remote clients trigger the "user-joined" callback.
Type signature
join(joinInfo: JoinParam): Promise<{
remoteUsers: RemoteUser[];
timeLeft: number;
}>;
Parameters:
Parameter | Type | Description |
joinInfo | The parameters required to join a channel. |
Returns:
Parameter | Type | Description | Version |
remoteUsers | RemoteUser[]; | A list of remote users. | 1.0.0 |
timeLeft | number | The remaining duration of the channel. | 1.0.0 |
Returns
Promise<{ remoteUsers: RemoteUser[]; timeLeft: number }>
leave()
Leaves the channel and ends the call.
Calling this method triggers the "connection-state-change" callback on the local client.
Remote clients trigger the "user-left" callback.
Type signature
leave(): void;
Returns
void
publish()
Publishes local audio and video tracks to the channel.
After the tracks are published, remote clients trigger the "user-published" callback.
Type signature
publish(tracks: LocalTrack | LocalTrack[]): Promise<void>;
Parameter | Type | Description |
tracks | The local Track object created by `DingRTC.createMicrophoneAudioTrack`, `DingRTC.createCameraTrack`, or other methods. |
Returns
Promise<void>
setRemoteDefaultVideoStreamType()
Sets the video stream type for subscriptions to all remote users.
If a remote user has dual-stream mode enabled, calling `subscribe` subscribes the local client to the stream type specified by the `streamType` parameter. If you do not call this method, the high-quality stream is subscribed to by default.
Type signature
setRemoteDefaultVideoStreamType(streamType: RemoteStreamType): void;
Parameter | Type | Description |
streamType | The video stream type to subscribe to. `high` represents the high-quality stream, and `low` represents the low-quality stream. |
Returns
void
setRemoteVideoStreamType()
Sets the video stream type for a subscription to a specific remote user.
Type signature
setRemoteVideoStreamType(uid: string, streamType: RemoteStreamType): Promise<void>;
Parameter | Type | Description |
uid | string | The ID of the remote user. |
streamType | The video stream type to subscribe to. `high` represents the high-quality stream, and `low` represents the low-quality stream. |
Returns
Promise<void>
subscribe()
Subscribes to the audio and video tracks of a remote user.
Type signature
subscribe(uid: string, mediaType: TrackMediaType, auxiliary?: boolean): Promise<RemoteAudioTrack | RemoteVideoTrack>;
Parameter | Type | Description |
uid | string | The ID of the remote user. |
mediaType | The media type of the track to subscribe to. | |
auxiliary | boolean | (Optional) If you are subscribing to a video track, this specifies whether to subscribe to the screen sharing video stream. |
Returns
Promise<RemoteAudioTrack|RemoteVideoTrack>
batchSubscribe()
Subscribes to the audio and video tracks of multiple remote users in a batch.
Type signature
batchSubscribe(batchSubscribeParam: SubscribeParam[]): Promise<SubscribeResult[]>;
Parameter | Type | Description |
batchSubscribeParam | The parameters for subscribing to remote audio and video tracks. |
Returns
Promise<SubscribeResult[]>
Subscribing to the audio of a specific user is not yet supported. To subscribe to audio, set `userId` to the string 'mcu'. This subscribes to the mixed audio stream of all remote users in the channel. You only need to subscribe to the mixed audio stream once. When a new remote user publishes an audio stream, it is automatically added to the subscribed MCU audio stream.
unpublish()
Unpublishes local audio and video tracks.
After the tracks are unpublished, remote clients trigger the "user-unpublished" callback.
Type signature
unpublish(tracks?: LocalTrack | LocalTrack[]): Promise<void>;
Parameter | Type | Description |
tracks | (Optional) The track or tracks to unpublish. If this is left empty, all published audio and video tracks are unpublished. |
Returns
Promise<void>
unsubscribe()
Unsubscribes from the audio and video tracks of a remote user.
Type signature
unsubscribe(uid: string, mediaType?: TrackMediaType, auxiliary?: boolean): Promise<void>;
Parameter | Type | Description |
uid | string | The ID of the remote user. |
mediaType | (Optional) The media type of the track to unsubscribe from. | |
auxiliary | boolean | (Optional) Specifies whether the video track to be subscribed is a desktop sharing video stream. |
Returns
Promise<void>
batchUnsubscribe()
You can batch subscribe to the audio and video tracks of remote users.
Type signature
batchSubscribe(batchUnsubscribeParam: UnsubscribeParam[]): Promise<void>;
Parameter | Type | Description |
batchUnsubscribeParam | The parameters for unsubscribing from remote audio and video tracks. |
Returns
Promise<void>
Unsubscribing from the audio of a specific user is not yet supported. To unsubscribe from audio, set `userId` to the string 'mcu'. This unsubscribes from the mixed audio stream of all remote users in the channel. You only need to unsubscribe from the mixed audio stream once. Support for unsubscribing from the audio of a specific user will be available soon.
on()
Adds a listener and sets a callback function for a specific event.
Type signature
on(event: string, fn: Function): void;
Parameters
Parameter | Type | Description |
event | string | The specific event to listen for. |
fn | Function | The callback function that is triggered when the event occurs. |
Returns
void
off()
Removes the callback function for a specific event listener.
Type signature
off(event: string, fn: Function): void;
Parameters
Parameter | Type | Description |
event | string | The specific event to listen for. |
fn | Function | The callback function that is triggered when the event occurs. |
Returns
void
once()
Adds a one-time listener for a specific event. The listener is removed after the callback function is triggered.
Type signature
once(event: string, fn: Function): void;
Parameters
Parameter | Type | Description |
event | string | The specific event to listen for. |
fn | Function | The callback function that is triggered when the event occurs. |
Returns
void
removeAllListeners()
Removes the listeners for a specific event or for all events on this object.
Type signature
removeAllListeners(event?: string): void;
Parameters
Parameter | Type | Description |
event | string | (Optional) The event for which to remove listeners. If you specify an event, all its listeners are removed. If you omit this parameter, all listeners for all events on the object are removed. |
Returns
void
Event List
"connection-state-change"
A callback that is triggered when the connection state between the SDK and the server changes.
Type signature
'connection-state-change': (curState: ConnectionState, prevState: ConnectionState, reason?: DisconnectedReason) => void;"media-reconnect-end"
A callback that is triggered when the SDK finishes re-establishing the media connection for publishing and subscribing.
Type signature
'media-reconnect-end': (uid: string) => void;
"media-reconnect-start"
A callback that is triggered when the SDK starts to re-establish the media connection for publishing and subscribing.
Type signature
'media-reconnect-start': (uid: string) => void;
"stream-type-changed"
A callback that is triggered when the subscribed video stream type changes. The stream type can change from a high-quality stream (high bitrate and high resolution) to a low-quality stream (low bitrate and low resolution), or vice versa.
Type signature
'stream-type-changed': (uid: string, streamType: RemoteStreamType) => void;
"user-info-updated"
This callback notifies you of a change in a user's status.
In most cases, you only need to listen for the `user-published` and `user-unpublished` events to manage subscriptions and to determine whether a remote user's camera and microphone are on. The SDK handles user status changes automatically.
Type signature
'user-info-updated': (uid: string, msg: 'mute-audio' | 'mute-video' | 'unmute-audio' | 'unmute-video') => void;"user-joined"
A callback that is triggered when a remote user or streamer joins the channel.
Type signature
'user-joined': (user: RemoteUser) => void;
"user-left"
A callback that is triggered when a remote user or streamer leaves the channel.
Type signature
'user-left': (user: RemoteUser) => void;
"user-published"
This callback notifies you that a remote user has published a new audio or video track.
You can subscribe to and play the remote user's audio and video tracks in this callback.
Type signature
'user-published': (user: RemoteUser, mediaType: TrackMediaType, auxiliary?: boolean) => void;
"user-unpublished"
This callback notifies you that a remote user has unpublished an audio or video track.
Type signature
'user-unpublished': (user: RemoteUser, mediaType: TrackMediaType, auxiliary?: boolean) => void;
"volume-indicator"
Reports the list of remote users who are currently speaking in the channel. This feature is automatically enabled when three or more users are in the channel.
The `uids` parameter is a list of the speakers' user IDs. The first user ID in the list belongs to the loudest speaker. An empty list means that no one is speaking.
Type signature
'volume-indicator': (uids: string[]) => void;
"network-quality"
A callback that reports the network quality of the local client. It is triggered every 2 seconds after you join a channel and is for reference only.
Type signature
'network-quality': (uplinkNetworkQuality: NetworkQuality, downlinkNetworkQuality: NetworkQuality) => void;"group-add"
Adding events by group
Type signature
Group'group-add': (group: <a baseurl="t3055468_v1_0_0.xdita" data-node="4688872" data-root="16740" data-tag="xref" href="t2584362.xdita#1b0c579aac71h" id="78046aef3en14">Group</a>) => void;"group-remove"
Group Removed Event
Type signature
Group'group-remove': (group: <a baseurl="t3055468_v1_0_0.xdita" data-node="4688872" data-root="16740" data-tag="xref" href="t2584362.xdita#1b0c579aac71h" id="fc9a31ab83z26">Group</a>) => void;"group-user-join"
Triggered when a member joins a group.
Type signature
GroupUser'group-user-join': (groupId: string, groupUser: <a baseurl="t3055468_v1_0_0.xdita" data-node="4688872" data-root="16740" data-tag="xref" href="t2584362.xdita#16c1078b3d39c" id="07d3eb7a14syw">GroupUser</a>) => void;"group-user-leave"
Management event for a member leaving a group
Type signature
GroupUser'group-user-leave': (groupId: string, groupUser: <a baseurl="t3055468_v1_0_0.xdita" data-node="4688872" data-root="16740" data-tag="xref" href="t2584362.xdita#16c1078b3d39c" id="6407a15e91vnr">GroupUser</a>) => void;"group-info-updated"
Triggered when a group property changes.
Type signature
GroupPropertyUpdateTypes 'group-info-updated': (groupId: string, updateType: <a baseurl="t3055468_v1_0_0.xdita" data-node="4688872" data-root="16740" data-tag="xref" href="t2584362.xdita#84e1106d45xq7" id="277b91b59fk30">GroupPropertyUpdateTypes</a>, value?: string) => void;