Tencent RTC SDK - TRTC - Documentation

TRTC is the main entry to the TRTC SDK for web. You can use TRTC APIs to create a client object (Client) and local audio/video stream object (Stream) for real-time communication, check a browser's compatibility and whether it supports screen sharing, as well as set the log output level and enable/disable log upload.

Namespaces

Logger

Members

(static) VERSION :string

Version number of the TRTC SDK for web

Type:

string

Methods

(async) checkSystemRequirements() → {Promise.<object>}

Check whether the TRTC SDK for web is compatible with the browser.
If not, recommend a browser supported by the SDK according to the user’s device.
Breaking Change:

In versions earlier than v4.7.0, a Boolean value is returned from the promise, which indicates whether the SDK is compatible with the browser.
In v4.7.0 and later versions, an object is returned from the promise. For details, see “Returns” below.
In v4.9.0 and later versions, isH264Supported in checkResult.detail is replaced by isH264EncodeSupported, isVp8EncodeSupported, isH264DecodeSupported, and isVp8DecodeSupported.

Example

// Versions earlier than v4.7.0
TRTC.checkSystemRequirements().then((result) => {
  if(!result) {
     console('Your browser is not compatible with TRTC');
     // The SDK is not compatible with the browser. Ask the user to use the latest version of Chrome.
  }
});
// v4.7.0 and later versions
TRTC.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.
  }
});

Returns:

Results returned from the promise

Property	Type	Description
checkResult.result	boolean	Compatibility check results
checkResult.detail.isBrowserSupported	boolean	Whether the browser is supported by the SDK
checkResult.detail.isWebRTCSupported	boolean	Whether the browser supports WebRTC
checkResult.detail.isMediaDevicesSupported	boolean	Whether the browser supports getting media devices and media streams
checkResult.detail.isH264EncodeSupported	boolean	Whether the browser supports H.264 encoding
checkResult.detail.isH264DecodeSupported	boolean	Whether the browser supports H.264 decoding
checkResult.detail.isVp8EncodeSupported	boolean	Whether the browser supports VP8 encoding
checkResult.detail.isVp8DecodeSupported	boolean	Whether the browser supports VP8 decoding

Type: Promise.<object>

isScreenShareSupported() → {boolean}

Check whether the browser supports screen sharing
Call this API before creating a screen sharing stream.

Example

if (TRTC.isSmallStreamSupported()) {
  console.log('The current browser supports the dual-channel mode.');
} else {
  console.log('The current browser does not supports the dual-channel mode.');
}

Returns:

Type: boolean

isSmallStreamSupported() → {boolean}

Check whether the browser supports the dual-channel mode
Call this API before enabling the dual-channel mode.

Example

if (TRTC.isScreenShareSupported()) {
  console.log('The current browser supports screen sharing.');
} else {
  console.log('The current browser does not support screen sharing.');
}

Returns:

Type: boolean

(async) getDevices() → {Promise.<Array.<MediaDeviceInfo>>}

Get the list of media input and output devices
Note

This API cannot be used on HTTP websites. Please use HTTPS to deploy your website. For more information, please see Privacy and security.
For security reasons, before users grant camera and mic access, label and deviceId may be left empty. We recommend that you call this API again after the access is granted. For example, you may call this API again to get the device list after initialize().

Example

TRTC.getDevices()
  .then(deviceList => {
    deviceList.forEach(item => {
      console.log('device: ' + item.kind + ' ' + item.label + ' ' + item.deviceId);
    });
  })
  .catch(error => console.error('getDevices error observed ' + error));

Returns:

The MediaDeviceInfo array is returned from the promise.

Type: Promise.<Array.<MediaDeviceInfo>>

(async) getCameras() → {Promise.<Array.<MediaDeviceInfo>>}

Get the camera list
Note

This API cannot be used on HTTP websites. Please use HTTPS to deploy your website. For more information, please see Privacy and security.
For security reasons, before users grant camera and mic access, label and deviceId may be left empty. We recommend that you call this API again after the access is granted. For example, you may call this API again to get the device list after LocalStream.initialize().
Version v4.14.2+ supports getCapabilities browser native interface. From this interface you can get basic capabilities of the camera, such as maximum resolution supported, maximum frame rate, differentiation between front or rear camera in mobile devices, etc. This interface supports Chrome 67+, Edge 79+, Opera 54+ browsers.

Example

TRTC.getCameras()
  .then(cameraList => {
    cameraList.forEach(item => {
      console.log('camera: ' + item.kind + ' ' + item.label + ' ' + item.deviceId);
    });
  })
  .catch(error => console.error('getCameras error observed ' + error));

Returns:

The MediaDeviceInfo array is returned from the promise.

Type: Promise.<Array.<MediaDeviceInfo>>

(async) getMicrophones() → {Promise.<Array.<MediaDeviceInfo>>}

Get the mic list
Note

This API cannot be used on HTTP websites. Please use HTTPS to deploy your website. For more information, please see Privacy and security.
For security reasons, before users grant camera and mic access, label and deviceId may be left empty. We recommend that you call this API again after the access is granted. For example, you may call this API again to get the device list after LocalStream.initialize().
In order to avoid possible silent problems, the API in version 4.11.9+ no longer returns microphones with deviceId of 'communications'. For more information, please refer to Chrome case 8 in WebRTC known issues.
The v4.14.2+ version supports calling the getCapabilities native interface, from which you can get the microphone's You can get the basic parameters of the microphone from this interface, such as the maximum number of supported channels. This interface supports Chrome 67+, Edge 79+, Opera 54+ browsers.

Example

TRTC.getMicrophones()
  .then(microphoneList => {
    microphoneList.forEach(item => {
      console.log('microphone: ' + item.kind + ' ' + item.label + ' ' + item.deviceId);
    });
  })
  .catch(error => console.error('getMicrophones error observed ' + error));

Returns:

The MediaDeviceInfo array is returned from the promise.

Type: Promise.<Array.<MediaDeviceInfo>>

(async) getSpeakers() → {Promise.<Array.<MediaDeviceInfo>>}

Get the speaker list

For security reasons, before users grant camera and mic access, label and deviceId may be left empty. We recommend that you call this API again after the access is granted. For example, you may call this API again to get the device list after initialize().
No support for mobile devices.

Example

TRTC.getSpeakers()
  .then(speakerList => {
    speakerList.forEach(item => {
      console.log('speaker: ' + item.kind + ' ' + item.label + ' ' + item.deviceId);
    });
  })
  .catch(error => console.error('getSpeakers error observed ' + error));

Returns:

The MediaDeviceInfo array is returned from the promise.

Type: Promise.<Array.<MediaDeviceInfo>>

createClient(clientConfig) → {Client}

Create a client object for real-time audio/video calls. This API needs to be called only once for each call.
A client is usually bound to a user ID (userId). There can be multiple client objects on a webpage, each bound to a different user ID.
For example, you can use a client object to publish the local audio/video stream and receive remote streams and another client object to publish the screen sharing stream (this client does not receive remote streams).

Examples

// Create client objects in real-time call mode
const client = TRTC.createClient({
  sdkAppId: 0,   // Fill in the sdkAppId of your application
  userId: '',    // Fill in the userId
  userSig: '',   // Fill in the userSig
  mode: 'rtc'
});

// Create client objects in interactive live mode
const client = TRTC.createClient({
  sdkAppId: 0,   // Fill in the sdkAppId of your application
  userId: '',    // Fill in the userId
  userSig: '',   // Fill in the userSig
  mode: 'live'
});

Parameters:

Name Type Description

clientConfig

object

Client-side settings

Properties

Name	Type	Attributes	Default	Description
`sdkAppId`	number			sdkAppId In the TRTC console, click Application Management > Create Application. Then, you can get the sdkAppId information in the Application Info .
`userId`	string			User ID Up to 32 bytes; supports letters (a-z and A-Z), digits (0-9), underscores, and hyphens.
`userSig`	string			User signature For the calculation of userSig, please refer to UserSig.
`mode`	string			Application scenario, which can be: 'rtc': real-time call 'live': interactive live streaming
`useStringRoomId`	boolean	<optional>	`false`	Whether to use string-type `roomId`, supported on v4.3.0+
`autoSubscribe`	boolean	<optional>	`true`	Whether to receive remote streams automatically, supported on v4.8.0+ By default, the SDK automatically starts receiving and decoding the audio/video data of a remote stream right after the `stream-added` callback is received. You can disable the automatic receiving of remote streams for screen sharing clients, which publish but do not receive data.
`enableAutoPlayDialog`	boolean	<optional>	`true`	enable autoplay dialog, since v4.11.9. It is enabled by default. When autoplay fails, SDK will show a dialog to guide the user to click on the page to resume playback. Set false to disable，ref: Suggested Solutions for Autoplay Restrictions
`pureAudioPushMode`	number	<optional>		Audio-only publishing mode. Include this parameter if you need to enable relayed live streaming and record the audio. `1`: Only audio data is published, which does not need to be recorded into an MP3 file. `2`: Only audio data is published, which needs to be recorded into an MP3 file.

Returns:

Client object

Type: Client

createStream(streamConfig) → {Stream}

Create a local stream object, which can use the publish() API to publish local audio/video.
Note: A stream can contain at most one audio track and one video track.
The source of a local audio/video stream can be:

The camera and mic. This is the case in common audio/video calls.
A screen sharing source. This is the case for screen sharing.
The MediaStreamTrack you specify via audioSource/videoSource. If this is the case, your business layer can process the audio and video data before publishing, for example, mix the audio or apply beauty filters to the video. You can also use this method to publish to remote users an audio/video file the local user is playing.

Examples

// Capture audio and video from the camera and mic
const localStream = TRTC.createStream({ userId, audio: true, video: true });
localStream.initialize().then(() => {
  console.log('initialize localStream success');
  // The local stream object was initialized successfully and can use `Client.publish(localStream)` to publish an audio/video stream.
.catch(error => {
  console.error('failed initialize localStream ' + error);
});

// Capture from a screen sharing source
// Capture the screen sharing stream only
const localStream = TRTC.createStream({ userId, audio: false, screen: true });
// Capture audio from the mic and the screen sharing stream
// const localStream = TRTC.createStream({ userId, audio: true, screen: true });
// Capture system audio and the screen sharing stream
// const localStream = TRTC.createStream({ userId, screenAudio: true, screen: true });
localStream.initialize().then(() => {
  console.log('initialize localStream success');
  // The local stream object was initialized successfully and can use `Client.publish(localStream)` to publish an audio/video stream.
.catch(error => {
  console.error('failed initialize localStream ' + error);
});

// Capture from an audio/video source specified by an external application
navigator.mediaDevices.getUserMedia({ audio: true, video: true }).then(stream => {
  const audioTrack = stream.getAudioTracks()[0];
  const videoTrack = stream.getVideoTracks()[0];
  // After processing the audio and video tracks
  const localStream = TRTC.createStream({ userId, audioSource: audioTrack, videoSource: videoTrack });
  localStream.initialize().then(() => {
    console.log('initialize localStream success');
    // The local stream object was initialized successfully and can use `Client.publish(localStream)` to publish an audio/video stream.
  .catch(error => {
    console.error('failed initialize localStream ' + error);
  });
}
);

Parameters:

Name Type Description

streamConfig

object

Properties

Name	Type	Attributes	Description
`userId`	string		User ID
`audio`	boolean		Whether to capture audio from the mic
`microphoneId`	string	<optional>	Device ID of the mic, which can be obtained via getMicrophones()
`video`	boolean		Whether to capture video from the camera
`cameraId`	string	<optional>	Device ID of the camera, which can be obtained via getCameras()
`facingMode`	string	<optional>	Whether to use the front or rear camera for video capturing. You can use this parameter to specify whether to use the front or rear camera on mobile devices. 'user': front camera 'environment': rear cameraNote Do not use both `cameraId` and `facingMode`.
`screen`	boolean	<optional>	Whether to capture the screen sharing stream
`screenAudio`	boolean		Whether to capture system audio Note Do not set both `audio` and `screenAudio` to true. System audio capturing is supported on Chrome M74+ only. On Chrome for Windows and Chrome OS, you can capture the audio of the entire system, while on Chrome for Linux and macOS, you can capture only the audio of Chrome tabs. Other Chrome versions, OS, and browsers do not support system audio capturing. For detailed directions on screen sharing, see Screen Sharing.
`audioSource`	MediaStreamTrack		Audio source
`videoSource`	MediaStreamTrack		Video source
`mirror`	boolean	<optional>	Whether to mirror the video. Default value: `true`. We recommend that you enable the mirror mode when using the front camera and disable it when using the rear camera. Screen sharing does not support mirroring. This parameter is deprecated from v4.12.1. To set the local video mirror preview please refer to localStream.play().

Throws:

RtcError

Returns:

Local audio/video stream object

Type: Stream