ClientEvent

Client event list

Listen to the specified event through client.on('eventName'). You can use these events to manage the room user list, manage the user's flow status, and perceive network status. The following is a detailed introduction to the events.

Notice：

  • Events need to be listened before the event is triggered. It is recommended to complete the event listening before the client enters the room, so as to ensure that the event notification will not be missed.

Members

(static) STREAM_ADDED

Default Value:
  • 'stream-added'

A remote stream was added. This event will be fired when a stream published by remote user. When you receive this notification, you can subscribe to the specified remote stream. Full subscription playback process reference document Quick Start Call.

Example
client.on('stream-added', event => {
  const remoteStream = event.stream;
});

(static) STREAM_REMOVED

Default Value:
  • 'stream-removed'

A remote stream was removed. This event will be fired when a stream unpublished by remote user. With this event you can know which remote stream was removed. SDK will automatically unsubscribe when it receives this notification, you do not need to unsubscribe.

Example
client.on('stream-removed', event => {
  const remoteStream = event.stream;
});

(static) STREAM_UPDATED

Default Value:
  • 'stream-updated'

A remote stream was updated. This event will be fired when a remote user adds, removes, or replaces an audio/video track.

Example
client.on('stream-updated', event => {
  const remoteStream = event.stream;
});
// For example, if the remote adds a video stream, you can change from only subscribing to audio to subscribing to both audio and video
client.on('stream-updated', event => {
  const remoteStream = event.stream;
  if(remoteStream.hasVideo()) {
     client.subscribe(remoteStream, { audio: true, video: true }).catch(error => {
       console.error('failed to subscribe remoteStream');
     });
  }
});

(static) STREAM_SUBSCRIBED

Default Value:
  • 'stream-subscribed'

A remote stream was successfully subscribed. This event will be fired after subscribe() is successfully called. Full subscription playback process reference document Quick Start Call.

Example
client.on('stream-subscribed', event => {
  const remoteStream = event.stream;
});

(static) CONNECTION_STATE_CHANGED

Default Value:
  • 'connection-state-changed'

The connection status between the SDK and Tencent Cloud changed. You can use this event to listen for the connection status of the SDK and Tencent Cloud in general.
If you want to listen for the connection status of each stream, listen for StreamEvent.CONNECTION_STATE_CHANGED.

  • ‘DISCONNECTED’: disconnected
  • ‘CONNECTING’: connecting
  • ‘RECONNECTING’: automatically reconnecting
  • ‘CONNECTED’: connected
Example
client.on('connection-state-changed', event => {
  const prevState = event.prevState;
  const curState = event.state;
});

(static) PEER_JOIN

Default Value:
  • 'peer-join'

This event will be fired when a remote user has joined room.

**Note: **

  • In live mode, this event will not be fired if a audience remote user joined room.
Example
client.on('peer-join', event => {
  const userId = event.userId;
});

(static) PEER_LEAVE

Default Value:
  • 'peer-leave'

This event will be fired when a remote user has leaved room.

Notes:

  • In live mode, this event will not be fired if a audience remote user leaved room.
Example
client.on('peer-leave', event => {
  const userId = event.userId;
});

(static) MUTE_AUDIO

Default Value:
  • 'mute-audio'

A remote user mute audio.

Example
client.on('mute-audio', event => {
  const userId = event.userId;
});

(static) MUTE_VIDEO

Default Value:
  • 'mute-video'

A remote user mute video.

Example
client.on('mute-video', event => {
  const userId = event.userId;
});

(static) UNMUTE_AUDIO

Default Value:
  • 'unmute-audio'

A remote user unmute audio.

Example
client.on('unmute-audio', event => {
  const userId = event.userId;
});

(static) UNMUTE_VIDEO

Default Value:
  • 'unmute-video'

A remote user unmute video.

Example
client.on('unmute-video', event => {
  const userId = event.userId;
});

(static) CLIENT_BANNED

Default Value:
  • 'client-banned'

Passive exit room event. Since v4.14.0 the event callback returns the reason for checking out (reason) and the corresponding reason description (message). The enumeration values of reason and their meanings are as follows:

Value Meaning
kick A user with the same userId has already joined room. The user who joined later kicks the user who joined the room first; or the user who published the stream first kicks the user who did not publish the stream.
banned The user was kicked out of the room by the account admin(by Server API
room_disband the room was disband by the account admin(by Server API
Tip:
  • The users with the same userId are not allowed to join same room at the same time, which may cause abnormal audio/video calls between the two parties.
  • In live mode, only anchor users will kick each other. Audience will not kick each other.
Example
// since v4.14.0
client.on('client-banned', event => {
  console.log(`reason: ${event.reason}, message: ${event.message}`);
});
// before v4.14.0
client.on('client-banned', error => {
  console.error('client-banned observed: ' + error);
});

(static) NETWORK_QUALITY

Since:
  • v4.6.0
Default Value:
  • 'network-quality'

Network quality statistics were collected. Network quality statistics collection starts when a user enters a room and is triggered every 2 seconds. The statistics include upstream and downstream network quality statistics:

  • Upstream network quality (uplinkNetworkQuality): network quality of the upstream connection from SDK to Tencent Cloud
  • Downstream network quality (downlinkNetworkQuality): average network quality of all downstream connections from Tencent Cloud to SDK Enumerated values and their meanings are as follows:
    Value Meaning
    0 Unknown network status: no upstream or downstream connection has been established for the current client instance
    1 Excellent network condition
    2 Good network connection
    3 Average network connection
    4 Poor network connection
    5 Extremely poor network connection
    6 Disconnected
    Note: for downstream network quality, this value indicates that all downstream connections are disconnected.

Starting from v4.10.3, upstream and downstream RTTs and packet loss rates can be obtained.

  • uplinkRTT and uplinkLoss indicate the upstream RTT (ms) and upstream packet loss rate respectively.
  • downlinkRTT and downlinkLoss` indicate the average RTT (ms) and average packet loss rate of all downstream connections respectively.
Example
client.on('network-quality', event => {
   console.log(`network-quality, uplinkNetworkQuality:${event.uplinkNetworkQuality}, downlinkNetworkQuality: ${event.downlinkNetworkQuality}`)
   // Starting from v4.10.3, upstream and downstream RTTs and packet loss rates can be obtained
   console.log(`uplink rtt:${event.uplinkRTT} loss:${event.uplinkLoss}`)
   console.log(`downlink rtt:${event.downlinkRTT} loss:${event.downlinkLoss}`)
})

(static) AUDIO_VOLUME

Since:
  • v4.9.0
Default Value:
  • 'audio-volume'

Volume event
After you call the enableAudioVolumeEvaluation API to enable volume callback, the SDK regularly throws this event to notify each user (userId) of the volume.
Note

  • The callback contains the volume of the pushed local stream and subscribed remote stream. It will be triggered regardless of whether there is someone speaking.
  • The value of audioVolume is an integer ranging from 0 to 100. If the value is greater than 10, it is generally considered that the user is speaking.
Example
client.on('audio-volume', event => {
    event.result.forEach(({ userId, audioVolume, stream }) => {
        if (audioVolume > 10) {
           console.log(`user: ${userId} is speaking, audioVolume: ${audioVolume}`);
        }
    })
})
// Enable volume callback and set the SDK to trigger the volume callback event at an interval of 1000 ms
client.enableAudioVolumeEvaluation(1000);

(static) SEI_MESSAGE

Since:
  • v4.14.1
Default Value:
  • 'sei-message'

receive SEI message

Example
client.on('sei-message', event => {
   console.log(`receive sei message: ${event.data} from ${event.userId}`)
   // since v4.15.11+
   console.log(`is the SEI received from the auxiliary stream: ${event.isFromAuxiliary}`)
})

(static) ERROR

Default Value:
  • 'error'

Error event. This event is thrown when an unrecoverable error occurs.

Example
client.on('error', error => {
  console.error('client error observed: ' + error);
  const errorCode = error.getCode();
  // View the error types in the error code list (https://cloud.tencent.com/document/product/647/34342)
  // When a client error occurs, call `Client.leave()` to leave the room and try to call `Client.join()` to enter the room again to resume the call
});
stream.on('error', error => {
  const errorCode = error.getCode();
  if (errorCode === 0x4043) {
    // Autoplay restrictions. Display a window for users to click to trigger the callback function and call the `stream.resume` API in the callback function to resume audio/video playback
    // Reference: https://web.sdk.qcloud.com/trtc/webrtc/doc/en/module-ErrorCode.html#.PLAY_NOT_ALLOWED
  } else if (errorCode === 0x4044) {
    // Failed to automatically resume after the media device is unplugged. Reference: https://web.sdk.qcloud.com/trtc/webrtc/doc/en/module-ErrorCode.html#.DEVICE_AUTO_RECOVER_FAILED
  }
});