Client | NERTC V4.4.0

The Client interface provides the core functions of audio and video calls, such as joining a room, publishing, and subscribing to audio and video streams.

You can use NERTC.createClient to create a Client object. The Client object points to a local or remote user during a call, and provides the core functions of YunXin NERTC SDK.

Hierarchy

Client

Methods

addTasks

addTasks(options: { rtmpTasks: RTMPTask[] }): Promise<undefined>

Adds a streaming task in a room.

After you call the method, the current user can receive the notification about the status of live streaming by calling Client.on("rtmp-state").
- The method is applicable to only live streaming.
- You can call the method when you are in a room. The method is valid for calls.
- Only one URL for the relayed stream can be added in each call. You need to call the method multiple times if you wan to push many streams. An RTC room with the same channelid can create three different streaming tasks.
Parameters
- options: { rtmpTasks: RTMPTask[] }
  - rtmpTasks: RTMPTask[]
    
    Information about a streaming task.
Returns Promise<undefined>

deleteTasks

deleteTasks(options: { taskIds: string[] }): Promise<void>

Deletes a push task.
- The method is applicable to only live streaming.
- You can call the method when you are in a room. The method is valid for calls.
Parameters
- options: { taskIds: string[] }
  - taskIds: string[]
    
    Specifies the ID of a streaming task.
Returns Promise<void>

destroy

destroy(): void

Destroys the Client object.

Returns void

getChannelInfo

getChannelInfo(): any

Gets current call information.

Returns any

getConnectionState

getConnectionState(): ConnectionState

Obtains the status of network connection.

The method can be used in the following scenarios:
- When the app restarts due to exceptions, you can call this method to actively obtain the current connection status between the client and the server. This allows the client to sync the connection status with the server.
- In RTC scenarios， such as real-time audio and video calls, The method actively obtains the connection status of the room to support the business requirements.
The connection between the SDK and the server has the following states: -DISCONNECTED: The client is disconnected. This state indicates that the SDK:
- gets initialized by calling Client.join before the client joins the room.
- leaves the room by calling Client.leave.
- CONNECTING: The network connection is being established. This state indicates that the SDK:
- is getting connected with the specified room by calling Client.join.
- reconnects to the server after the client is disconnected during a call.
- CONNECTED: The client is connected. This state indicates that the user has successfully joined the room and can publish or subscribe to media streams in the room.
- DISCONNECTING: The client is disconnecting.
- The connection show this state when the SDK calls Client.leave to leave the room.
Returns ConnectionState

getLocalAudioStats

getLocalAudioStats(): Promise<any>

Gets the audio stats of the local publishing stream.

Returns Promise<any>

getLocalVideoStats

getLocalVideoStats(mediaType?: "audio" | "video" | "screen"): Promise<any>

Gets the video stats of the local publishing stream.

Parameters
- Optional mediaType: "audio" | "video" | "screen"
  
  The media stream type.
Returns Promise<any>

getRemoteAudioStats

getRemoteAudioStats(): Promise<any>

Gets the audio stats of the subscribed remote stream.

Returns Promise<any>

getRemoteVideoStats

getRemoteVideoStats(mediaType?: "audio" | "video" | "screen"): Promise<any>

Gets the video stats of the subscribed remote stream.

Parameters
- Optional mediaType: "audio" | "video" | "screen"
  
  The media stream type.
Returns Promise<any>

getSessionStats

getSessionStats(): Promise<any>

Gets the stats of the connection to the sessions.

note

You must join a room before you can call the method.

Returns Promise<any>

getSystemStats

getSystemStats(): Promise<any>

Gets the information about system power.

Returns Promise<any>

getTransportStats

getTransportStats(): Promise<any>

Gets the stats of the connection to the gateways.

Returns Promise<any>

getUid

getUid(): null | number

Gets the local user ID.

If uid is specified in the join method, the specified ID is returned. If uid is not specified, the ID will automatically be assigned by YunXin server.

since

V4.4.0

Returns null | number

join

join(options: JoinOptions): Promise<any>

Joins the room.

If the specified room does not exist when you join the room, a room with the specified name is automatically created in the server provided by YunXin.

When you call this method to join a room, the Client.on("connection-state-change") callback will be triggered on the local client. After the user in the communication and the host in the live streaming join the room, the Client.on(" peer-online") callback will be triggered on the remote client.

Parameters

options: JoinOptions

Room settings.

Returns Promise<any>

Error codes:

Error code	Reason	Description
403	netcall.g2 unsafe mode is closed, please contact business!	Token is not set in safe mode. You can get the NERTC Token by calling getToken, and use the token when you join the room. If your app is still in testing, you can switch the application to debug mode in the console. Token is not required when you join a room in debug mode.
414	check checksum error	Authentication fails. In most cases, the error occurs because an invalid token is used.

leave

leave(): Promise<void>

Leaves a room.

When you call this method to leave a room, the Client.on("connection-state-change") callback will be triggered on the local client. After the user in the communication and the host in the live streaming leave the room, the Client.on(" peer-leave") callback will be triggered on the remote client.

Returns Promise<void>

on

on(event: "client-role-changed", callback: (evt: { role: "host" | "audience" }) => void): void
on(event: "stream-added", callback: (evt: { stream: Stream }) => void): void
on(event: "stream-subscribed", callback: (evt: { mediaType: MediaType; stream: Stream }) => void): void
on(event: "stream-removed", callback: (evt: { stream: Stream }) => void): void
on(event: "active-speaker", callback: (evt: { uid: number }) => void): void
on(event: "volume-indicator", callback: (evt: { level: number; uid: number }) => void): void
on(event: "peer-online", callback: (evt: { uid: number }) => void): void
on(event: "peer-leave", callback: (evt: { uid: number }) => void): void
on(event: "mute-audio", callback: (evt: { uid: number }) => void): void
on(event: "unmute-audio", callback: (evt: { uid: number }) => void): void
on(event: "mute-video", callback: (evt: { uid: number }) => void): void
on(event: "unmute-video", callback: (evt: { uid: number }) => void): void
on(event: "mute-screen", callback: (evt: { uid: number }) => void): void
on(event: "unmute-screen", callback: (evt: { uid: number }) => void): void
on(event: "client-banned", callback: (evt: { uid: number }) => void): void
on(event: "channel-closed", callback: () => void): void
on(event: "stopScreenSharing", callback: (evt: {}) => void): void
on(event: "connection-state-change", callback: (evt: { curState: ConnectionState; prevState: ConnectionState }) => void): void
on(event: "error", callback: (errorName: string) => void): void
on(event: "warning", callback: (evt: { code: number; reason: string }) => void): void
on(event: "audioTrackEnded"): void
on(event: "videoTrackEnded"): void
on(event: "rtmp-state", callback: (state: RTMPTaskState) => void): void
on(event: "network-quality", callback: (netStatus: NetStatusItem[]) => void): void
on(event: "exception", callback: (exceptionEvent: ClientExceptionEvt) => void): void
on(event: "crypt-error", callback: (evt: { cryptType: EncryptionMode }) => void): void

Occurs when the role of the local user changes.

In live streaming, this callback will be triggered when the user role is switched, from host to audience, or from audience to host.

Parameters
- event: "client-role-changed"
- callback: (evt: { role: "host" | "audience" }) => void
  - - (evt: { role: "host" | "audience" }): void
    - Parameters
      - evt: { role: "host" | "audience" }
        
        role: "host" | "audience"
        
        The role after the change.
      Returns void
Returns void
A remote user publishes audio and video streams.

Parameters
- event: "stream-added"
- callback: (evt: { stream: Stream }) => void
  - - (evt: { stream: Stream }): void
    - Parameters
      - evt: { stream: Stream }
        
        stream: Stream
        
        A new remote stream.
      Returns void
Returns void
Occurs when the app has received remote audio and video streams.

This callback will be triggered after an audio and video stream published by a remote user is subscribed.

Parameters
- event: "stream-subscribed"
- callback: (evt: { mediaType: MediaType; stream: Stream }) => void
  - - (evt: { mediaType: MediaType; stream: Stream }): void
    - Parameters
      - evt: { mediaType: MediaType; stream: Stream }
        
        mediaType: MediaType
        
        The type of the audio and video stream.
        
        stream: Stream
        
        The received remote stream.
      Returns void
Returns void
Occurs when the app has deleted the remote audio and video stream.

After the remote user calls the Client.unpublish method, this callback will be triggered.

Parameters
- event: "stream-removed"
- callback: (evt: { stream: Stream }) => void
  - - (evt: { stream: Stream }): void
    - Parameters
      - evt: { stream: Stream }
        
        stream: Stream
        
        The remote stream.
      Returns void
Returns void
This event will return the uid of the user with the highest volume in the current room.

Parameters
- event: "active-speaker"
- callback: (evt: { uid: number }) => void
  - - (evt: { uid: number }): void
    - Parameters
      - evt: { uid: number }
        
        uid: number
        
        The uid of the user with the highest volume.
      Returns void
Returns void
This event returns the current user and volume in the room.

Parameters
- event: "volume-indicator"
- callback: (evt: { level: number; uid: number }) => void
  - - (evt: { level: number; uid: number }): void
    - Parameters
      - evt: { level: number; uid: number }
        
        level: number
        
        The user volume.
        
        uid: number
        
        User ID.
      Returns void
Returns void
This event indicates that a remote user or host has joined the room.
- In communication, this callback prompts that a remote user has joined the room, and returns the ID of the user who has joined the room.
- In live streaming, the callback prompts that the host has joined the room, and returns the user ID of the host.
The callback will be triggered in the following scenarios:
- In communication, the remote user or the remote host in live streaming calls the Client.join method to join the room.
- In live streaming, the remote audience joins the room, call Client.setClientRole to change the user's role as the host.
- In communication, a remote user rejoins the room after the client is disconnected.
Parameters
- event: "peer-online"
- callback: (evt: { uid: number }) => void
  - - (evt: { uid: number }): void
    - Parameters
      - evt: { uid: number }
        
        uid: number
        
        The user ID of the remote user or the host.
      Returns void
Returns void
This event indicates that the remote user or the host leaves the room.

The callback will be triggered in the following scenarios:
- A remote user leaves the room.
- A user changes the role from host to audience.
note

In live streaming, only the user whose role is the host can trigger this callback.
Parameters
- event: "peer-leave"
- callback: (evt: { uid: number }) => void
  - - (evt: { uid: number }): void
    - Parameters
      - evt: { uid: number }
        
        uid: number
        
        The user ID of the remote user or the host.
      Returns void
Returns void
This event indicates that the remote user mutes the audio.

Parameters
- event: "mute-audio"
- callback: (evt: { uid: number }) => void
  - - (evt: { uid: number }): void
    - Parameters
      - evt: { uid: number }
        
        uid: number
        
        The remote user ID.
      Returns void
Returns void
This event indicates that the remote user unmutes the audio.

Parameters
- event: "unmute-audio"
- callback: (evt: { uid: number }) => void
  - - (evt: { uid: number }): void
    - Parameters
      - evt: { uid: number }
        
        uid: number
        
        The remote user ID.
      Returns void
Returns void
This event indicates that the remote user has turned off the video during a video call.

Parameters
- event: "mute-video"
- callback: (evt: { uid: number }) => void
  - - (evt: { uid: number }): void
    - Parameters
      - evt: { uid: number }
        
        uid: number
        
        The remote user ID.
      Returns void
Returns void
This event indicates that the remote user turns on the video during a video call.

Parameters
- event: "unmute-video"
- callback: (evt: { uid: number }) => void
  - - (evt: { uid: number }): void
    - Parameters
      - evt: { uid: number }
        
        uid: number
        
        The remote user ID.
      Returns void
Returns void
This event indicates that the remote user has paused screen sharing.

Parameters
- event: "mute-screen"
- callback: (evt: { uid: number }) => void
  - - (evt: { uid: number }): void
    - Parameters
      - evt: { uid: number }
        
        uid: number
        
        The remote user ID.
      Returns void
Returns void
This event indicates that the remote user resumes screen sharing.

Parameters
- event: "unmute-screen"
- callback: (evt: { uid: number }) => void
  - - (evt: { uid: number }): void
    - Parameters
      - evt: { uid: number }
        
        uid: number
        
        The remote user ID.
      Returns void
Returns void
This event indicates that the local user is removed from the room.

note

Only users who are removed from the room receive this callback.

Parameters
- event: "client-banned"
- callback: (evt: { uid: number }) => void
  - - (evt: { uid: number }): void
    - Parameters
      - evt: { uid: number }
        
        uid: number
        
        The remote user ID.
      Returns void
Returns void
This event indicates that the room is closed.

Parameters
- event: "channel-closed"
- callback: () => void
  - - (): void
    - Returns void
Returns void
This event indicates that the local user stops screen sharing.

Parameters
- event: "stopScreenSharing"
- callback: (evt: {}) => void
  - - (evt: {}): void
    - Parameters
      - evt: {}
      Returns void
Returns void
This event indicates the connection between the SDK and server changes"

Parameters
- event: "connection-state-change"
- callback: (evt: { curState: ConnectionState; prevState: ConnectionState }) => void
  - - (evt: { curState: ConnectionState; prevState: ConnectionState }): void
    - Parameters
      - evt: { curState: ConnectionState; prevState: ConnectionState }
        
        curState: ConnectionState
        
        The status after the change.
        
        prevState: ConnectionState
        
        The status before the change.
      Returns void
Returns void
An error occurs on the client. Error types include:
- SOCKET_ERROR: Connection error.
- RELOGIN_ERROR: Reconnection failure.
Parameters
- event: "error"
- callback: (errorName: string) => void
  - - (errorName: string): void
    - Parameters
      - errorName: string
      Returns void
Returns void
A warning is delivered on the client. Warnings:
- 406: ability not support. The video encoding capability of the current client device does not match the encoding support of the room. For example, the device does not support encoding types such as VP8. In this room, video streams cannot be encoded and decoded. In this case, the local client may not be able to display some remote videos, and the remote client may be unable to display videos from the local client.
Parameters
- event: "warning"
- callback: (evt: { code: number; reason: string }) => void
  - - (evt: { code: number; reason: string }): void
    - Parameters
      - evt: { code: number; reason: string }
        
        code: number
        
        Warning code.
        
        reason: string
        
        Reasons.
      Returns void
Returns void
The audio stream ends. The possible reason is that the device is unplugged.

Parameters
- event: "audioTrackEnded"
Returns void
The video stream ends. The possible reason is that the device is unplugged.

Parameters
- event: "videoTrackEnded"
Returns void
This event indicates that the streaming status has changed.

Parameters
- event: "rtmp-state"
- callback: (state: RTMPTaskState) => void
  - - (state: RTMPTaskState): void
    - Parameters
      - state: RTMPTaskState
      Returns void
Returns void
This event shows the uplink and downlink network quality of all members in the room.

Parameters
- event: "network-quality"
- callback: (netStatus: NetStatusItem[]) => void
  - - (netStatus: NetStatusItem[]): void
    - Parameters
      - netStatus: NetStatusItem[]
      Returns void
Returns void
This event shows the current exception events in the room.

Exception events are not errors. However, the events may cause quality problems for calls.

Parameters
- event: "exception"
- callback: (exceptionEvent: ClientExceptionEvt) => void
  - - (exceptionEvent: ClientExceptionEvt): void
    - Parameters
      - exceptionEvent: ClientExceptionEvt
      Returns void
Returns void
Fails to join the room because the specified media stream encryption key is inconsistent with the key specified by one or more members who join the room.

Reset the encryption key by calling Client.setEncryptionSecret.

Parameters
- event: "crypt-error"
- callback: (evt: { cryptType: EncryptionMode }) => void
  - - (evt: { cryptType: EncryptionMode }): void
    - Parameters
      - evt: { cryptType: EncryptionMode }
        
        cryptType: EncryptionMode
      Returns void
Returns void

publish

publish(stream: Stream): Promise<undefined>

Publishes local audio and video streams.

After you publish the audio and video stream, the Client.on("stream-added") callback is triggered on the remote client.

Parameters
- stream: Stream
  
  The stream that you want to publish.
Returns Promise<undefined>

setChannelProfile

setChannelProfile(options: { mode: "rtc" | "live" }): void

Sets a room scene.

You can set a room scene for a call or live event. Different QoS policies are applied to different scenes.

note

You must call the method before you join a room. If you have joined a room, you cannot set the room scene.

Parameters
- options: { mode: "rtc" | "live" }
  - mode: "rtc" | "live"
    Sets a room scene.
    
    Valid values:
    - rtc (default) communications: In this scenario, all users in the room can publish and receive audio and video streams. The setting is suitable for scenarios such as audio calls and group video calls.
    - live: Live streaming. This scenario has two user roles: host and audience, which can be set using setClientRole. The host can publish and receive audio and video streams, and the audience can receive the streams. The setting is suitable for scenarios such as chat rooms, live streaming, and interactive remote learning for large classes.
Returns void

setClientRole

setClientRole(role: "host" | "audience"): Promise<undefined>

Sets the user role. By default, a user joins a room as a host.

Before a user joins a room, the user can call this method to change the client role to audience. After a user joins a room, the user can call this method to switch the client role.

You can set the role to host or audience. The permissions of a host and an audience are different.
- The host: The host has the permissions to open or close audio and video devices such as a camera, publish streams, and configure streaming tasks in Interactive Live Streaming. The status of the host is visible to the users in the room when the host joins or leaves the room.
- The audience: The audience can only receive audio and video streams, but cannot operate audio and video devices, configure streaming tasks in interactive live streaming. The status of an audience is invisible to the users in the room when the audience joins or leaves the room.
note
You can configure the setting before or after you join the room.

Callbacks:

If you join a room and call this method to change roles, the following callbacks are triggered.
- If the role changes from host to audience, the Client.on(client-role-changed) callback is triggered on the client, and the Client.on(peer-leave) callback is triggered on a remote client.
- If the role changes from audience to host, the onClientRoleChange callback is triggered on the client, and the onUserJoined callback is remotely triggered on a remote client.
Parameters
- role: "host" | "audience"
  The user role. Valid values:
  - host: The host in live streaming can publish and receive audio and video streams. If the user has published audio or video as before, the audio or video stream will be automatically resumed when the role is switched to host.
  - audience: The audience in live streaming can only receive audio and video streams. If the user role changes from host to audience, the client will automatically stop publishing audio and video streams.
Returns Promise<undefined>

setEncryptionMode

setEncryptionMode(encryptionMode: EncryptionMode): void

Sets Media stream encryption mode.

In scenarios with high security requirements such as finance, you can use this method to set the media stream encryption mode before you join the room.

-This method is used together with Client.setEncryptionSecret. Before you join the room, you must call Client.setEncryptionMode to set the media stream encryption scheme, and then call Client.setEncryptionSecret to set the secret. If the key is not specified, the media stream encryption cannot be enabled.
- After you leave the room, the SDK will automatically disable encryption. If you need to turn on encryption again, you need to call the previous two methods before you join the room again.
since

V4.4.0

note
- You must call this method before you join the room, the encryption mode and key cannot be modified after you join the room.
- For security, we recommend that you replace the new key every time the media stream encryption is enabled.
- All users in a room who enable media stream encryption must use the same encryption mode and key. Otherwise, Client.on("crypt-error") is triggered.
Parameters
- encryptionMode: EncryptionMode
Returns void

setEncryptionSecret

setEncryptionSecret(encryptionSecret: string): void

Sets media stream encryption key.

-This method is used together with Client.setEncryptionMode. Before you join the room, you must call Client.setEncryptionMode to set the media stream encryption scheme, and then call Client.setEncryptionSecret to set the secret. If the key is not specified, the media stream encryption cannot be enabled.
- After you leave the room, the SDK will automatically disable encryption. If you need to turn on encryption again, you need to call the previous two methods before you join the room again.
since

V4.4.0

note
- You must call this method before you join the room, the encryption mode and key cannot be modified after you join the room.
- For security, we recommend that you replace the new key every time the media stream encryption is enabled.
- All users in a room who enable media stream encryption must use the same encryption mode and key. Otherwise, Client.on("crypt-error") is triggered.
Parameters
- encryptionSecret: string
  
  The encryption key of media streams. The key must be of STRING type and must be 1 to 128 characters in length. We recommend that you set the key to a string that contains only letters.
Returns void

setLocalMediaPriority

setLocalMediaPriority(options: MediaPriorityOptions): void

Sets the priority of media streams from a local user.

If a user has a high priority, the media stream from the user also has a high priority. In unreliable network connections, the SDK guarantees the quality of the media stream from users with a high priority.
note
- You must call the method before you join a room.
- An RTC room has only one user that has a high priority. We recommend that only one user in a room call the setLocalMediaPriority method to set the local media stream a high priority. Otherwise, you need to enable the preempt mode to ensure the high priority of the local media stream.
Parameters
- options: MediaPriorityOptions
  
  Priority settings.
Returns void

setRemoteVideoStreamType

setRemoteVideoStreamType(stream: Stream, highOrLow: number): Promise<void>

Sets to low streams or high streams.

If the publishing client enables the dual-stream mode, the client subscribes to the high-resolution video stream by default. You can also choose the high-resolution stream or low-resolution stream at the client that subscribes to the streams.

note

You can configure the setting before or after you join the room.

Parameters
- stream: Stream
  
  The specified audio and video stream to which you want to subscribe.
- highOrLow: number
  
  The stream type. A value of 0 indicates the low-resolution stream. A value of 1 indicates the high-resolution stream.
Returns Promise<void>

subscribe(stream: Stream): Promise<void>

Subscribes to remote audio and video streams.

After you subscribe to the remote audio and video stream, the Client.on("stream-subscribed") callback will be triggered on the local client.

Parameters
- stream: Stream
  
  The source audio and video stream to which you want to subscribe.
Returns Promise<void>

unpublish

unpublish(stream: Stream, type?: null): Promise<undefined>

Stops publishing local audio and video streams to the room.

After you stop publishing the audio and video stream, the Client.on("stream-removed") callback is triggered on the remote client.

Parameters
- stream: Stream
  
  Stream that you want to stop publishing.
- Optional type: null
  
  The stream type.
Returns Promise<undefined>

unsubscribe

unsubscribe(stream: Stream): Promise<void>

Unsubscribe from remote audio and video streams.

After you unsubscribe from remote audio and video streams, the SDK will not receive remote audio and video streams.

Parameters
- stream: Stream
  
  The audio and video stream from which you want to unsubscribe.
Returns Promise<void>

updateTasks

updateTasks(options: { rtmpTasks: RTMPTask[] }): Promise<void>

Updates a streaming task.
- The method is applicable to only live streaming.
- You can call the method when you are in a room. The method is valid for calls.
Parameters
- options: { rtmpTasks: RTMPTask[] }
  - rtmpTasks: RTMPTask[]
    
    Information about a streaming task.
Returns Promise<void>

Hierarchy

Index

Methods

Methods

addTasks

Parameters

options: { rtmpTasks: RTMPTask[] }

rtmpTasks: RTMPTask[]

Returns Promise<undefined>

deleteTasks

Parameters

options: { taskIds: string[] }

taskIds: string[]

Returns Promise<void>

destroy

Returns void

getChannelInfo

Returns any

getConnectionState

Returns ConnectionState

getLocalAudioStats

Returns Promise<any>

getLocalVideoStats

Parameters

Optional mediaType: "audio" | "video" | "screen"

Returns Promise<any>

getRemoteAudioStats

Returns Promise<any>

getRemoteVideoStats

Parameters

Optional mediaType: "audio" | "video" | "screen"

Returns Promise<any>

getSessionStats

Returns Promise<any>

getSystemStats

Returns Promise<any>

getTransportStats

Returns Promise<any>

getUid

Returns null | number

join

Parameters

options: JoinOptions

Returns Promise<any>

leave

Returns Promise<void>

on

Parameters

event: "client-role-changed"

callback: (evt: { role: "host" | "audience" }) => void

Parameters

evt: { role: "host" | "audience" }

role: "host" | "audience"

Returns void

Returns void

Parameters

event: "stream-added"

callback: (evt: { stream: Stream }) => void

Parameters

evt: { stream: Stream }

stream: Stream

Returns void

Returns void

Parameters

event: "stream-subscribed"

callback: (evt: { mediaType: MediaType; stream: Stream }) => void

Parameters

evt: { mediaType: MediaType; stream: Stream }

mediaType: MediaType

stream: Stream

Returns void

Returns void

Parameters

event: "stream-removed"

callback: (evt: { stream: Stream }) => void

Parameters

evt: { stream: Stream }

stream: Stream

Returns void

Returns void