timmerse v1.2.17

Overview

Currently, the Timmerse Web SDK can be used on Chrome M58+ and Safari. Make sure you use HTTPS or localhost to deploy your web app or a "navigator.mediaDevices not present" error will occur.

You can use the Timmerse Web SDK to implement features including co-anchoring, message sending/receiving, room creation and closing, user muting and removal, as well as beauty filters.

Integration

Before you integrate the Timmerse Web SDK into your project, contact us at colleenyu@tencent.com for a developer ID and key. You need to verify login at your backend and return the application ID and key. At the development stage, it’s OK to use the application ID and key directly at the frontend. The figure below describes the integration process:

Sample code:

import Timmerse, { EVENT } from 'timmerse';

const config = {
  apaasAppId: '*',
  apaasSecret: '*',
  userId: '*',
  avatar: '*',
  name: '*'
};
// Initialization parameters. Pass in the config object the first time you get a singleton.
const rtcClient = await Timmerse.getInstance(config);
// Listen for events
rtcClient.on(EVENT.PEER_JOIN, event => {
  // Callback for the entry of a remote user
});
// Enter a room
rtcClient
  .enterRoom('12345', 'anchor')
  .then(() => {
    // Logic after room entry
  })
  .catch(err => {
    // In case of failure to enter a room
  });
// Terminate the room
rtcClient.destroyRoom();

Timmerse Web SDK Overview

Basic SDK APIs

Device APIs

User information APIs

Room APIs

Audio/Video APIs

Screen sharing APIs

Beauty filter APIs

Message sending APIs

Remote stream APIs

Listen for the rtcClient.on('STREAM_ADDED') callback to be notified when there is a new remote stream.

Events

Timmerse Web SDK Details

Basic SDK APIs

getInstance

This API is used to get a singleton.

Parameters: | Parameter | Type | Description | Required | |-----|-----|-----|-----| | config | Config | Initialization parameters. Pass in the config object the first time you get a singleton. | No |

config: | Parameter | Type | Description | Required | |-----|-----|-----|-----| | requestId | String | The UUID of a request, which is needed for locating issues and troubleshooting | No | | apaasAppId | String | The application ID assigned by Timmerse, which identifies a customer | Yes | | apaasSecret | String | The key assigned by Timmerse, which is used for authentication | Yes | | userId | String | The user ID, which is managed by your system | Yes | | avatar | String | Profile photo URL | Yes | | nickName | String | Username | No |

Sample code:

const rtcClient = await Timmerse.getInstance(config);

destroyInstance

This API is used to terminate a singleton.

Parameters: | Parameter | Type | Description | Required | |-----|-----|-----|-----| | timInstance | Timmerse | The singleton to terminate. | No |

Sample code:

Timmerse.destroyInstance();

on

This API is used to listen for events dispatched by the component. For details about the events, see "Event Details" below.

Parameters: | Parameter | Type | Description | Required | |-----|-----|-----|-----| | EventCode | String | Event code | Yes | | handler | Function | Listener function | Yes | | context | Object | Context | No |

Sample code:

rtcClient.on(EVENT.PEER_JOIN, onPeerJoin);

off

This API is used to stop listening for events.

Parameters: | Parameter | Type | Description | Required | |-----|-----|-----|-----| | EventCode | String | The event code. | Yes | | handler | Function | The named listener function to remove. | Yes |

Sample code:

rtcClient.off(EVENT.PEER_JOIN, onPeerJoin);

Device APIs

getVersion

This API is used to get the version number of the Timmerse Web SDK.

Parameters: None

Return: Version number

Sample code:

Timmerse.getVersion();

checkSystemRequirements

This API is used to check whether the Timmerse Web SDK supports the current browser.

If not, recommend a browser supported by the SDK according to the user’s device.

Parameters: None

Return: A promise that contains the test results. For details, see checkSystemRequirements.

Sample code:

Timmerse.checkSystemRequirements().then(checkResult => {
  if (!checkResult.result) {
    console.log('checkResult', checkResult.result, 'checkDetail', checkResult.detail);
    // The SDK is not compatible with the browser. Recommend a browser supported by the SDK based on the user’s device.
  }
});

isScreenShareSupported

This API is used to check whether the browser supports screen sharing.

Call this API before creating a screen sharing stream.

Parameters: None

Return: A Boolean value. true: supported; false: not supported.

Sample code:

const isScreen = Timmerse.isScreenShareSupported();

getCameras

This API is used to get the camera list.

For security reasons, before users grant camera and mic access, label and deviceId might be empty. We recommend that you call this API again after the access is granted. For example, call this API after openLocalCamera.

Parameters: None

Return: A promise that contains an array of MediaDeviceInfo.

Sample code:

const cameras = await Timmerse.getCameras();

getMicrophones

This API is used to get the mic list.

For security reasons, before users grant camera and mic access, label and deviceId might be empty. We recommend that you call this API again after the access is granted. For example, call this API after openLocalCamera.

Parameters: None

Return: A promise that contains an array of MediaDeviceInfo.

Sample code:

const microphones = await Timmerse.getMicrophones();

getSpeakers

This API is used to get the speaker list.

For security reasons, before users grant camera and mic access, label and deviceId might be empty. We recommend that you call this API again after the access is granted. For example, call this API after openLocalCamera.

Parameters: None

Return: A promise that contains an array of MediaDeviceInfo.

Sample code:

const speakers = await Timmerse.getSpeakers();

getDevices

This API is used to get a list of the media input and output devices.

For security reasons, before users grant camera and mic access, label and deviceId might be empty. We recommend that you call this API again after the access is granted. For example, call this API after openLocalCamera.

Parameters: None

Return: A promise that contains an array of MediaDeviceInfo.

Sample code:

const devices = await Timmerse.getDevices();

getMediaPermission

This API is used to ask for audio and video access.

Parameters: | Parameter | Type | Description | Required | |-----|-----|-----|-----| | audio | boolean | Whether to ask for audio access | Yes | | video | boolean | Whether to ask for video access | Yes |

Return: A promise object | Error | Description | Suggested Solution | |-----|-----|-----| | NotFoundError | The media (audio, video, or screen sharing) specified by the request parameter were not found. This error occurs if, for example, the PC has no cameras, but the browser is asked to obtain a video stream. | Remind users to check their cameras and mics before making a call. If a user does not have a camera and wants to make an audio call, use the rtcClient.openLocalVideo({ audio: true, video: false }) API to make the SDK capture audio only. | | NotAllowedError| The user rejected the request of the current browser instance to access the camera/mic or share the screen.| Remind the user that audio/video calls are not possible without camera/mic access. | | NotReadableError | The user has granted access to the requested device, but it is still inaccessible due to a hardware, browser, or webpage error. | Handle the error according to the error message returned, and send this message to the user: “The camera/mic cannot be accessed. Please make sure it is not being used by another application and try again.”| | AbortError| The device cannot be accessed due to an unknown reason. | |

Sample code:

Timmerse.getMediaPermission({ audio: true, video: true })
  .then(() => {})
  .catch(error => {
    // Failed to initialize the local stream
    switch (error.name) {
      case 'NotReadableError':
        // Send this message to the user: "The camera/mic cannot be accessed. Please make sure it is not being used by another application and try again."
        break;
      default:
        console.error(error);
        break;
    }
  });

User information APIs

queryUser

This API is used to get the information of a user.

Parameters: None

Return: A promise object | Parameter Name | Type | Description | |-----|-----|-----| | userId | String | User ID | | name | String | Username | | avatar | String | Profile photo URL |

Sample code:

const userInfo = await rtcClient.queryUser();

updateUser

This API is used to modify the information of a user.

Parameters: | Parameter | Type | Description | Required | |-----|-----|-----|-----| | userInfo | UserInfo | User information | Yes |

userInfo: | Parameter | Type | Description | Required | |-----|-----|-----|-----| | name | String | Username | Yes | | avatar | String | Profile photo URL | No |

Return: A promise object

Sample code:

await rtcClient.updateUser({ name, avatar });

Room APIs

enterRoom

This API is used to enter a room (the room ID is generated by your project and must be unique).

Parameters: | Parameter | Type | Description | Required | |-----|-----|-----|-----| | roomId | String | Room ID | Yes | | role | String | User role. anchor: room owner; guest: participant. | Yes |

Return: A promise object

Sample code:

rtcClient
  .enterRoom('12345', 'anchor')
  .then(() => {
    // Logic after room entry
  })
  .catch(err => {
    // In case of failure to enter a room
  });

leaveRoom

This API is used to leave a room (called by participant).

Parameters: | Parameter | Type | Description | Required | |-----|-----|-----|-----| | roomId | String | Room ID | No |

Return: A promise object

Sample code:

rtcClient
  .leaveRoom()
  .then(() => {
    // Logic after room exit
  })
  .catch(err => {
    // Handle exceptions
  });

destroyRoom

This API is used to terminate a room (called by room owner).

Parameters: None

Return: A promise object

Sample code:

rtcClient
  .destroyRoom()
  .then(() => {
    // Logic after room termination
  })
  .catch(err => {
    // Handle exceptions
  });

getRoomList

This API is used to get the room list.

Parameters: | Parameter | Type | Description | Required | |-----|-----|-----|-----| | offset | int | The number of rows to skip before returning records, 0 by default. | No | | limit | int | The maximum number of records to return per query. Default: 10; maximum: 100. | No | | startUtc | String | Start time | No | | endUtc | String | End time | No |

Return: A promise object | Parameter Name | Type | Description | |-----|-----|-----| | roomId | String | Room ID | | title | String | Room name |

代码示例：

const roomList = await rtcClient.getRoomList({
  offset: 0,
  limit: 10,
  startUtc: '2021-09-14 16:00:00',
  endUtc: '2021-09-16 16:00:00'
});

getRoomDetail

This API is used to get room details.

Parameters: | Parameter | Type | Description | Required | |-----|-----|-----|-----| | roomId | String | Room ID | Yes |

Return: A promise object | Parameter Name | Type | Description | |-----|-----|-----| | roomId | String | Room ID | | title | String | Room name | | createUtc | String | Creation time | | updateUtc | String | Updated time | | nnUsers | String | Number of users in the room |

Sample code:

const roomDetail = await rtcClient.getRoomDetail('12345');

getRoomUserList

This API is used to get the users in a room.

Parameters: | Parameter | Type | Description | Required | |-----|-----|-----|-----| | limit | int | The maximum number of records to return per query. Default: 50; maximum: 100. | No |

Return: A promise object | Parameter Name | Type | Description | |-----|-----|-----| | userId | String | User ID | | name | String | Username | | avatar | String | Profile photo URL | | role | String | User role. anchor: room owner; guest: participant. |

Sample code:

const userList = await rtcClient.getRoomUserList(50);

Audio/Video APIs

openLocalVideo

This API is used to turn the local camera and mic on.

This API creates an tag and a tag and plays audio and video on them. The tags will be added to the div container whose name is element on the webpage.

Parameters: | Parameter | Type | Description | Required | |-----|-----|-----|-----| | isAudio | boolean | Whether to capture audio from the mic. | Yes | | isVideo | boolean | Whether to capture video from the camera. | Yes | | element | String/HTMLDivElement | The container that the created audio and video tags are added to. | Yes | | profile | Profile | Custom video parameters, including resolution, frame rate, and bitrate. | No |

profile: | Parameter | Type | Description | Required | |-----|-----|-----|-----| | width | number | Resolution (width) | No | | height | number | Resolution (height) | No | | frameRate | number | Frame rate | No | | bitrate | number | Bitrate | No |

Return: A promise object

Sample code:

html: <div id="testContainer"></div>;
js: await rtcClient.openLocalVideo(true, true, 'testContainer', {
  width: 640,
  height: 480,
  frameRate: 15,
  bitrate: 900
});

closeLocalVideo

This API is used to close the audio/video stream and remove the audio and video tags created from the HTML page.

Parameters: None

Return: None

Sample code:

rtcClient.closeLocalVideo();

muteLocalAudio

This API is used to disable/enable the audio of the local user.

Parameters: | Parameter | Type | Description | Required | |-----|-----|-----|-----| | mute | boolean | true: disable; false: enable | Yes |

Return: None

Sample code:

rtcClient.muteLocalAudio(true);

muteLocalVideo

This API is used to disable/enable the video of the local user.

Parameters: | Parameter | Type | Description | Required | |-----|-----|-----|-----| | mute | boolean | true: disable; false: enable | Yes |

Return: None

Sample code:

await rtcClient.muteLocalVideo(true);

publish

This API is used to publish the local stream.

For this API to work, you must call it after room entry. A user can publish only one local stream in an audio/video call. To publish a different local stream, call unPublish() to stop publishing the current stream first.

After the local user publishes a stream, remote users will receive the STREAM_ADDED callback.

Parameters: None

Return: A promise object

Sample code:

await rtcClient.publish();

unPublish

This API is used to stop publishing the local stream.

After the local user stops publishing his or her stream, remote users will receive the STREAM_REMOVED callback.

Stop publishing the local stream before leaving the room.

Parameters: None

Return: A promise object

Sample code:

await rtcClient.unPublish();

getAudioLevel

This API is used to get the current audio volume.

This API works only if the local stream or a remote stream contains audio. Therefore, before calling this API, you need to play the stream first.

Parameters: None

Return: Audio volume Value range: 0.0-1.0. Generally, a user is considered to be speaking if the value is greater than 0.1.

Sample code:

setInterval(() => {
  const level = rtcClient.getAudioLevel();
  if (level >= 0.1) {
    console.log(`user ${stream.getUserId()} is speaking`);
  }
}, 200);

switchDevice

This API is used to switch media input devices.

You can call this API to change the media input device for the local stream:

• Audio input device, such as a mic
• Video input device, such as a camera

Do not call this API before publish or an error will occur.

Parameters: | Parameter | Type | Description | Required | |-----|-----|-----|-----| | type | String | The media type. Valid values: audio; video. | Yes | | deviceId | String | The device ID. You can call getCameras() to get the ID of a camera. On mobile devices, to switch between the front and rear cameras, set deviceId to user or environment. You can call getMicrophones() to get the ID of a mic. | Yes |

Return: A promise object

Sample code:

await rtcClient.publish();
const cameras = await rtcClient.getCameras();
await rtcClient.switchDevice('video', cameras[0].deviceId);

enableAudioVolumeEvaluation

This API is used to enable/disable the volume callback.

After the volume callback is enabled, the SDK will return the volume of each user in the room regularly via the EVENT.AUDIO_VOLUME callback, regardless of whether someone is speaking.

Parameters: | Parameter | Type | Description | Required | |-----|-----|-----|-----| | interval | number | The interval (ms) to return the volume callback. Default: 2000; minimum: 16. If you set it to 0 or a negative number, the callback will be disabled. | Yes |

Return: None

Sample code:

rtcClient.on('AUDIO_VOLUME', event => {
  event.result.forEach(({ userId, audioVolume, stream }) => {
    console.log(`userId: ${userId}, audioVolume: ${audioVolume}`);
  });
});
// Enable the volume callback and set the callback interval to 1000 ms
rtcClient.enableAudioVolumeEvaluation(1000);
// To disable the volume callback, set interval to 0 or a negative number
rtcClient.enableAudioVolumeEvaluation(-1);

subscribe

This API is used to subscribe to a remote stream.

By default, after you receive the EVENT.STREAM_ADDED callback, the SDK will immediately start receiving and decoding the audio and video data of the remote stream.

You can use this API to specify what data (audio, video, or both) of a remote stream you want to receive. If you do not want to receive any data, call unSubscribe() to unsubscribe from the stream.

Parameters: | Parameter | Type | Description | Required | |-----|-----|-----|-----| | stream | Stream | The remote stream, which can be found in the STREAM_ADDED callback. | Yes | | isAudio | boolean | Whether to receive audio. true: receive audio; false: do not receive audio. | Yes | | isVideo | boolean | Whether to receive video. true: receive video; false: do not receive video. | Yes |

Return: None

Sample code:

// Listen for the STREAM_SUBSCRIBED callback
rtcClient.on('STREAM_SUBSCRIBED', event => {
  const remoteStream = event.stream;
  const userId = event.userId;
  // Play the remote stream after successful subscription
  remoteStream.play('remote_stream');
});
// Listen for the STREAM_ADDED callback
rtcClient.on('STREAM_ADDED', event => {
  const remoteStream = event.stream;
  // Subscribe to the remote audio/video stream
  rtcClient.subscribe(remoteStream, { audio: true, video: true }).catch(e => {
    console.error('failed to subscribe remoteStream');
  });
});

unSubscribe

This API is used to unsubscribe from a remote stream.

Parameters: | Parameter | Type | Description | Required | |-----|-----|-----|-----| | stream | Stream | The remote stream, which can be found in the STREAM_ADDED callback. | Yes |

Return: None

Sample code:

// Listen for the STREAM_ADDED callback
rtcClient.on('STREAM_ADDED', event => {
  const remoteStream = event.stream;
  // Unsubscribe from the remote audio/video stream
  rtcClient.unSubscribe(remoteStream, { audio: true, video: true }).catch(e => {
    console.error('failed to subscribe remoteStream');
  });
});

Screen sharing APIs

openShareScreen

This API is used to start screen sharing.

WebRTC screen sharing is supported on Chrome M72+ and Safari 13.

Parameters: | Parameter | Type | Description | Required | |-----|-----|-----|-----| | profile | Profile | Custom screen sharing parameters, including resolution, frame rate, and bitrate. | No |

profile: | Parameter | Type | Description | Required | |-----|-----|-----|-----| | width | number | Resolution (width) | No | | height | number | Resolution (height) | No | | frameRate | number | Frame rate | No | | bitrate | number | Bitrate | No |

Return: None

Sample code:

await rtcClient.openShareScreen({ width: 1920, height: 1080, frameRate: 30, bitrate: 4000 });

closeShareScreen

This API is used to stop screen sharing.

Parameters: None

Return: None

Sample code:

await rtcClient.closeShareScreen();

Beauty filter APIs

enableBeauty

This API is used to enable/disable beauty filters.

Parameters: | Parameter | Type | Description | Required | |-----|-----|-----|-----| | enable | boolean | true: enable; false: disable | Yes |

Return: None

Sample code:

rtcClient.enableBeauty(true);

setBeautyParam

This API is used to adjust the strength of filters (beauty, brightness, and blush).

Parameters: | Parameter | Type | Description | Required | |-----|-----|-----|-----| | beauty | number | Strength of the beauty filter. Value range: 0-1; default: 0.5. | Yes | | brightness | number | Strength of the skin brightening filter. Value range: 0-1; default: 0.5. | Yes | | ruddy | number | Strength of the blush filter. Value range: 0-1; default: 0.5. | Yes |

Return: None

Sample code:

rtcClient.setBeautyParam({ beauty: 0.5, brightness: 0.5, ruddy: 0.5 });

Message sending APIs

sendRoomMsg

This API is used to broadcast a chat message in a room and is usually used for text chat.

Parameters: | Parameter | Type | Description | Required | |-----|-----|-----|-----| | text | String | The content of the chat message. | Yes |

Return: None

Sample code:

rtcClient.sendRoomMsg('Hello');

sendRoomCustomMsg

This API is used to send a custom message.

Parameters: | Parameter | Type | Description | Required | |-----|-----|-----|-----| | cmd | String | Custom command | Yes | | data | String | Data of the custom message | Yes | | extension | String | Additional field | No |

Return: None

Sample code:

rtcClient.sendRoomCustomMsg('networkQuality', data);

Event details

CONNECTION_STATE_CHANGED

The connection status between the SDK and Tencent Cloud changed. This callback keeps you updated on the connection status between the SDK and Tencent Cloud.

• DISCONNECTED: Disconnected
• CONNECTING: Connecting
• RECONNECTING: Reconnecting
• CONNECTED: Connected

Sample code:

rtcClient.on('CONNECTION_STATE_CHANGED', event => {
  const prevState = event.prevState;
  const curState = event.state;
});

PEER_JOIN

A remote user entered the room.

Sample code:

rtcClient.on('PEER_JOIN', event => {
  const userId = event.userId;
});

PEER_LEAVE

A remote user left the room.

Sample code:

rtcClient.on('PEER_LEAVE', event => {
  const userId = event.userId;
});

CLIENT_BANNED

A user was removed from the room, for example, due to repeated login.

Sample code:

rtcClient.on('CLIENT_BANNED', error => {
  console.error('CLIENT_BANNED observed:', error);
  // The room exit page
});

NETWORK_QUALITY

Statistics on upstream and downstream network quality. This callback is triggered every two seconds after room entry.

• Upstream network quality (uplinkNetworkQuality): Quality of upstream data transfer from the SDK to Tencent Cloud
• Downstream network quality (downlinkNetworkQuality): Average quality of downstream data transfer from Tencent Cloud to the SDK. For the valid values and their meanings, see the table below:

Sample code:

rtcClient.on('NETWORK_QUALITY', event => {
  console.log(
    `network-quality, uplinkNetworkQuality:${event.uplinkNetworkQuality}, downlinkNetworkQuality: ${event.downlinkNetworkQuality}`
  );
});

AUDIO_VOLUME

Audio volume

After you call the enableAudioVolumeEvaluation API to enable this callback, the SDK will return the volume of each user in the room at a regular interval.

• The callback contains the volume of the published local stream and subscribed remote streams and is triggered regularly regardless of whether someone is speaking.
• The value of audioVolume is an integer from 0 to 100. A user is generally considered to be speaking if the value is greater than 10.

Sample code:

rtcClient.on('AUDIO_VOLUME', event => {
  event.result.forEach(({ userId, audioVolume, stream }) => {
    if (audioVolume > 10) {
      console.log(`user: ${userId} is speaking, audioVolume: ${audioVolume}`);
    }
  });
});
// Enable the volume callback and set the callback interval to 1000 ms
rtcClient.enableAudioVolumeEvaluation(1000);

MUTE_AUDIO

A remote user disabled his or her audio.

Sample code:

rtcClient.on('MUTE_AUDIO', event => {
  const userId = event.userId;
  const mute = event.mute; // true: audio disabled; false: audio enabled
});

MUTE_VIDEO

A remote user disabled his or her video.

Sample code:

rtcClient.on('MUTE_VIDEO', event => {
  const userId = event.userId;
  const mute = event.mute; // true: video disabled; false: video enabled
});

STREAM_ADDED

There is a new remote stream. This callback is triggered after a remote user publishes his or her stream.

Sample code:

rtcClient.on('STREAM_ADDED', event => {
  const remoteStream = event.stream;
});

STREAM_REMOVED

A remote stream was removed. This callback is triggered after a remote user stops publishing his or her stream.

Sample code:

rtcClient.on('STREAM_ADDED', event => {
  const remoteStream = event.stream;
});

STREAM_UPDATED

A remote stream was updated. This callback is triggered after a remote user adds an audio/video track to their stream or deletes or replaces the audio/video track of their stream.

Sample code:

rtcClient.on('STREAM_UPDATED', event => {
  const remoteStream = event.stream;
});

STREAM_SUBSCRIBED

A remote stream was subscribed to. This callback is triggered after you call subscribe() to successfully subscribe to a remote stream.

Sample code:

rtcClient.on('STREAM_SUBSCRIBED', event => {
  const remoteStream = event.stream;
});

ROOM_DESTROY

The room was terminated.

Sample code:

rtcClient.on('ROOM_DESTROY', event => {
  // Leave the room
});

MSG_NOT_READY

The messaging system is not ready, in which case you cannot use the SDK to send messages.

Sample code:

rtcClient.on('MSG_NOT_READY', event => {
  console.log('message not ready:', event.isReady);
});

MSG_READY

The messaging system is ready. After receiving this callback, you can call the SDK’s APIs to send messages and perform other actions.

Sample code:

rtcClient.on('MSG_READY', event => {
  console.log('message ready:', event.isReady);
});

RECV_ROOM_MSG

A chat message was received (chat with participants).

Sample code:

rtcClient.on('RECV_ROOM_MSG', event => {
  console.log('message received:', event[0]);
});

RECV_ROOM_CUSTOM_MSG

A custom message was received.

Sample code:

rtcClient.on('RECV_ROOM_CUSTOM_MSG', event => {
  console.log('custom message received:', event[0]);
});

ERROR

Error. The SDK returns this callback when it encounters an unrecoverable error.

Sample code:

rtcClient.on('ERROR', error => {
  console.error('error observed:', error);
});

STREAM_RECOVER_FAILED

The SDK failed to resume capturing data from the camera or mic.

Sample code:

rtcClient.on('STREAM_RECOVER_FAILED', event => {
  const { recoverAudioFail, recoverVideoFail, error } = event;
  if (recoverAudioFail) console.error('Audio recover failed');
  if (recoverVideoFail) console.error('Video recover failed');
  console.error('error observed:', error);
});