Functional APIs

API List

API	Description
new WebRTC	Create a WebRTC object
init	Initialize
destroy	Destroy instance resources
isSupported	Check whether the browser supports Jocloud Web SDKs
getSupportedCodec	Get the supported code
isScreenShareSupported	Determine whether screen sharing is supported
VERSION	Version number
on	Add event bindings
off	Cancel event bindings
joinRoom	Join a room
leaveRoom	Exit a room
setArea	Set the user region
updateToken	Update a token
createStream	Create audio/video streams
closeStream	Complete audio/video streams
publish	Publish audio/video streams
unpublish	Stop publishing audio/video streams
setPublisherVolume	Set the microphone volume
setAudioMode	Set the local audio mode
setVideoEncoderConfig	Customize video encoding configuration
setVideoMode	Set local video stream brackets
changeDevice	Change input devices
subscribe	Subscribe to audio/video streams
unsubscribe	Unsubscribe to audio/video streams
play	Play the stream
stopPlay	Stop playing the stream
resume	Resume playing the stream
isPlaying	Determine whether the stream is playing
setAudioVolume	Set the playing volume
setAudioOutputDevice	Select the playing device
hasAudio	Determine whether there is an audio
hasVideo	Determine whether there is a video
enableAudio	Open an audio
disableAudio	Close an audio
enableVideo	Open a video
disableVideo	Close a video
addPublishOriginStreamUrl	Add the address of a source stream pushing to CDN
removePublishOriginStreamUrl	Remove the address of a source stream pushing to CDN
addPublishTranscodingStreamUrl	Add the address of a mixed stream pushing to CDN
removePublishTranscodingStreamUrl	Remove the address of a mixed stream pushing to CDN
setLiveTranscodingTask	Set a stream mixing task
removeLiveTranscodingTask	Remove a stream mixing task
addSubscribe	Subscribe across rooms
removeSubscribe	Cancel the cross-room subscription
createDualStream	Create dual-room video stream
changeRemoteVideoStreamType	Select high/low quality streams
startAudioMixing	Start audio mixing
stopAudioMixing	Stop audio mixing
pauseAudioMixing	Pause audio mixing
resumeAudioMixing	Resume audio mixing
setAudioMixingVolume	Set the audio mixing volume
getAudioMixingDuration	Get the total duration of audio mixing
getAudioMixingTime	Get the current audio mixing time
setAudioMixingTime	Set the audio mixing time
stopAllAudioMixing	Stop all audio mixing
pauseAllAudioMixing	Pause all audio mixing
resumeAllAudioMixing	Resume all audio mixing
getPublisherAudioLevel	Get the current output stream volume
getSubscriberAudioLevel	Get the current subscribed stream volume
enableAudioLevelReport	Enable audio volume reporting
disableAudioLevelReport	Disable audio volume reporting
getDevices	Get all audio/video devices
getAudioDevices	Get audio input devices such as microphones
getVideoDevices	Get video input devices such as cameras
getPlayoutDevices	Get playing devices
detectDevice	Check whether the device is available
getSystemStats	Get the system information
getSignalConnectionState	Get the connection status of the signaling room
getMediaConnectionState	Get the connection status of the media room
getSessionStats	Get the session-level connection statistics
getUplinkVideoStats	Get the uplink video stream statistics
getUplinkAudioStats	Get the uplink audio stream statistics
getDownlinkVideoStats	Get the downlink video stream statistics
getDownlinkAudioStats	Get the downlink audio stream statistics
getAudioTrack	Get the audio track in the stream
getVideoTrack	Get the video track in the stream
addTrack	Add an audio track to the local stream
removeTrack	Remove the audio/video track from the local stream
replaceTrack	Replace the audio/video track from the local stream
setLogLevel	Set the log level

Details

WebRTC

new WebRTC(config?: WebRTCConfig)

Create a WebRTC object and it will provide all the core APIs and features

Parameter

Parameter	Description
config	WebRTCConfig configuration object

WebRTCConfig

interface WebRTCConfig {
    codec?: 'H264' | 'VP8';
}

Profile	Description
codec	The code when configuring output streams (default: H264)

Return

Call all non-static functions through the WebRTC object.

init

init(appid: number): Err | null

This API initializes SDK.

Parameters

Parameter	Description
appid	Service application ID

Return

Return Value	Description
null	Succeeded
{error: "INVALID_APPID"}	Invalid application ID
{error: "ALREADY_INIT"}	Already initialized

destroy

destroy(): Err | null

Destory the SDK resource.

Return

Return Value	Description
null	Succeeded
{error: "HAS_NOT_INIT"}	Uninitialized

joinRoom

joinRoom(roomParam: RoomParam): Promise<Uid>

Calling this API allows users to join the communication room.

Users in the room can communicate with one another or engage in group chat. Applications using different application IDs cannot intercommunicate. Select either audio-only group mode or audio/video mode. The former supports audio-only intercommunication with other terminals’ thundersdk, while the latter supports audio/video intercommunication with other terminals’ thunderbolt sdk. Audio-only group mode only supports audio publishing. If you are already in the midst of communication, you must exit by calling leaveRoom() before you can join the next room.

Note:

For an audio-only group mode, it is recommended using 32-bit integer string uids (e.g. "123456" ). If you use a normal string, the registered user ID will be converted into a 32-bit integer string, which is obtainable through the Promise return.

Parameters

Parameter	Description
roomParam	Room information

RoomParam

interface RoomParam {
    uid: string;
    roomId: string;
    token?: string;
    mode?: number;
}

Profile	Description
uid	User ID [only supports a combination of the characters [A,Z],[a,z],[0,9],-,_, not to exceed 64 bytes in length]
roomId	Room ID (unique) [only supports a combination of the characters [A,Z],[a,z],[0,9],-,_, not to exceed 64 bytes in length]
token	See details in [User Authentication]
mode	0: audio-only group mode, 1: audio/video mode (default)

Return values

Promise, asynchronously returns local user ID. Its completion indicates the room joined.

Common Promise Error	Description
{error: "HAS_NOT_INIT"}	Not initialized
{error: "INVALID_PARAM"}	Invalid parameter type
{error: "INVALID_ROOM_ID"}	Invalid room ID
{error: "INVALID_UID"}	Invalid user ID
{error: "INVALID_MODE"}	Invalid mode
{error: "INVALID_TOKEN"}	Invalid token
{error: "ALREADY_JOINED"}	Room already joined
{error: "UNSUPPORTED_BROWSER"}	Unsupported browser
{error: "UNSAFE_ADDRESS"}	Unsafe address
{error: "UID_CONFLICT"}	User ID conflict

Note:

If the reject error shows “UNSAFE_ADDRESS”, check whether the application is deployed in the localhost or HTTPS domain.

isSupported

static isSupported(): boolean

Check whether the SDK is compatible with the running browser.

This is a static function. Currently, the SDK supports browsers with Chrome 70 or later and Safari 12.1 or later with localhost or https domain. See details in Browser Support

Return Values

true SDK is compatible with the browser
false SDK is incompatible with the browser

getSupportedCodec

static getSupportedCodec(): Promise<{ audio: string[], video: string[] }>

Return the audio/video codes supported by the browser.

Return Values

Promise, object members returned after successful asynchronous execution are as follows

Parameter	Description
audio	Arrays of the supported audio/video codes
video	Arrays of the supported video codes

isScreenShareSupported

static isScreenShareSupported(): boolean

Test whether the browser supports screen sharing

Screen sharing on Safari requires version 13 or above, and audio cannot be Shared.
Screen sharing on Chrome requires version 72 or above.
Audio sharing on Chrome requires version 74 or above; In Windows system, support to share system audio and tab audio; On macOS, only tab audio is supported.

Return Values

true screen sharing supported
false screen sharing not supported

getSystemStats

static getSystemStats(): Promise<{ system: string, browser: string, battery: number | undefined }>

Get the operating system version, browser version, and battery power.

Return Values

Promise, object members returned after successful asynchronous execution are as follows

Parameter	Description
system	System version
browser	Browser version
battery	Battery power; some browsers do not support the APIs of power; the value is undefined

VERSION

WebRTC.VERSION

Static string variable, indicates the SDK version number

on

on(event: string, listener: any)

Add event bindings, see details in callback event

Parameters

Parameter	Description
event	Event name
listener	Callback function

off

off(event: string, listener: any)

Cancel event bindings

Parameters

Parameter	Description
event	Name of the previously bound events
listener	Callback of the previously bound events

leaveRoom

leaveRoom(): Err | null

Leave the room, i.e. hanging up or exiting the conversation.

Return Values

Common Return Value	Description
null	Succeeded
{error: "HAS_NOT_JOIN"}	Room not joined

setArea

setArea(oversea: number): Err | null

Set the region.

To comply with differing laws and regulations at home and abroad, Jolcoud provides both domestic (default) and international central systems. If applications are mainly for use outside of China, call this API to set the region.

Note:

Users of the domestic and international central systems cannot intercommunicate. Make sure that the users in the same room are also in the same system.

Both systems are deployed globally, supporting worldwide access.

Parameters

Parameter	Description
oversea	0: default (domestic), 1: overseas

Return Values

Common Return Value	Description
null	Succeeded
{error: "INVALID_AREA"}	Invalid region parameter

updateToken

updateToken(token: string): Err | null

After calling this API, Jolcoud will update the user’s token immediately for authentication. See details in the Authentication Access Manual.

Authentication results are returned through sdk_auth_result.

Parameters

Parameter	Description
token	The token for update

Return Values

Common Return Value	Description
null	Succeeded
{error: "INVALID_TOKEN"}	Invalid token

createStream

createStream(param: MediaStreamParam): Promise<LocalStream>

Create audio/video streams locally.

You must join a room before calling. After creating a stream, call play to play local streams and publish to publish local streams.

Parameters

Parameter	Description
param	MediaStreamParam Create a parameter object of the local stream

MediaStreamParam

interface MediaStreamParam {
    audio?: {
        deviceId?: string;
        source?: MediaStreamTrack; // custom audio track
    } | boolean,
    video?: {
        deviceId?: string;
        videoMode?: number;
        source?: MediaStreamTrack; // custom video track
    },
    playType?: 1 | 2;
}

Profile	Description
audio	Enable the audio stream, which can be a Boolean value or built-in parameters; if not set, disable the audio stream; When playType is 1, audio means microphone; when playType is 2, audio means system sound
video	Enable the video stream, which can be a built-in parameter; if not entered, indicate that the video stream is not enabled.
playType	Optional parameters. In the audio/video mode, 1 (default) indicates that the camera and microphone are publishing the audio/video; 2 indicates screen sharing

Embedded Audio Parameters

Profile	Description
deviceId	Audio publishing device ID. If not entered, select default
source	Optional，audio track for creating the stream, the track's type is MediaStreamTrack, which can be obtained via the browser API

Embedded Video Parameters

Profile	Description
videoMode	Video bracket is required. See details in the Video Mode
deviceId	Video device ID. If not entered, select default
source	Optional，audio track for creating the stream, the track's type is MediaStreamTrack, which can be obtained via the browser API

Note:

The parameter videoMode in createStream has the same as the API setVideoMode and is used to set the video level.

Safari requires version 13 or above for and cannot share audio.

Screen sharing via Safari must be called related API from the User Gesture Handler.

Video Mode

The default video brackets are as follows. Add or adjust the brackets according to the services. Contact customer support for customized configurations.

videMode	Bracket	Resolution	Frame Rate	Bit Rate
1	Smooth	320 x 240	15	200 K
2	Standard definition	640 x 480	15	500 K
3	High definition	960 x 544	24	1000 K
4	Ultra-high definition	1280 x 720	24	1600 K
5	Blu-ray	1920 x 1080	24	4500 K

Note:

Due to camera and browser limitations, the actually published video resolution and frame rate may differ from the bracket set.

Custom frame rate is invalid in Safari and the video will be published at the default frame rate.

Return Values

Promise of LocalStream; successful asynchronous return indicates the local stream created

Common Promise Error	Description
{error: "HAS_NOT_JOIN"}	Room not joined
{error: "STREAM_ALREADY_CREATED"}	Stream already created
{error: "STREAM_IS_CREATING"}	Stream being created
{error: "INVALID_STREAM_PARAM"}	Invalid stream parameters
{error: "INVALID_PLAY_TYPE"}	Invalid publishing mode
{error: "INVALID_DEVICE_ID"}	Invalid device ID
{error: "INVALID_VIDEO_MODE"}	Invalid video bracket
{error: "PERMISSION_DENIED"}	The user rejected the request for media device
{error: "DEVICE_NOT_FOUND"}	No device
{error: "DEVICE_NOT_READABLE"}	Device unreadable
{error: "DEVICE_ERROR"}	Device error
{error: "INVALID_ACCESS_ERROR"}	Screen sharing via Safari must be called related API from the User Gesture Handler
{error: "SCREEN_CAPTURE_NOT_SUPPORTED"}	Screen sharing not supported

example

webRtc.createStream({
    audio: {},
    video: {videoMode: 3,
    },
    playType: 1,    
}.then((localStream)=>{ 
    webRtc.play(localStream.uid); // Locally available 
    webRtc.publish();   // Publish 
}))

closeStream

closeStream(): Err | null

Disable the local stream; the published local stream will stop likewise

Return Values

Common Return Value	Description
null	Succeeded
{error: "STREAM_HAS_NOT_BEEN_CREATED"}	Stream not created

publish

publish(): Promise<void>

This API pushes audio/video streams to the room for audio/video live streaming.

Before calling, you need to create the local stream: createStream

Return Values

Promise; successful asynchronous execution indicates the stream pushing published.

Common Promise Error	Description
{error: "STREAM_HAS_NOT_BEEN_CREATED"}	Stream not created
{error: "ALREADY_PUBLISH"}	Stream being published already
{error: "SET_REMOTE_SDP_FAIL"}	Protocol negotiation failed

unpublish

unpublish(): Err | null

This API can be used to stop pushing audio/video stream to the room, and should be called after the API publish.

Return Values

Common Return Value	Description
null	Succeeded
{error: "HAS_NOT_PUBLISH"}	Stream not published

setPublisherVolume

setPublisherVolume(volume: any): Err | null

Set the microphone volume.

Note:

Call after createStream

Parameters

Parameter	Description
volume	The microphone volume range [0-100]. 0: mute; 100 (default): maximum

Return Values

Common Return Value	Description
null	Succeeded
{error: "INVALID_VOLUME"}	Invalid volume
{error: "STREAM_HAS_NOT_BEEN_CREATED"}	Stream not created
{error: "AUDIO_TRACK_NOT_EXISTED"}	No audio track

setAudioMode

setAudioMode(audioMode: number): Err | null

Set the system audio mode.

Note:

-This API should be called beforecreateStream, and dynamic switching is not supported after a stream is created.

Parameter

Parameter	Description
audioMode	[Audio mode](#Audio Mode)

Audio Mode

audioMode	Mode	Track	Bitrate
1	Low quality	Mono	24 Kbps
2 (default)	Standard	Mono	40 Kbps
3	High quality	Mono	128 Kbps
4	High - quality stereo	stereo	192 Kbps

Note:

Playing stereo audio in Chrome doesn't have stereo effects, and Safari doesn't support stereo audio.

Audio mode 4 (high quality stereo) is only available for the scenario that publishing on Chrome and subscribing to on Native.

Return Values

Common Return Value	Description
null	Succeeded
{error: "INVALID_AUDIO_MODE"}	Invalid audio mode
{error: "INVALID_OPERATION_AFTER_STREAM_CREATED"}	This API should be called before creating streams

setVideoMode

setVideoMode(videoMode: number, layer = 0): Promise<LocalStream | void>

Set the video mode for local streams and the mode can be switched dynamically.

Note:

Call this API before createStream and after init.

Due to browser limitations, switching to a higher resolution during the publishing is not supporte.

The resolution of the low-quality stream should be smaller than that of the high-quality stream.

Dynamic switching may cause black bars to your video.

The effects of setVideoMode and setVideoEncoderConfig on video stream acquisition are mutually exclusive, and only the last called API takes effect.

Parameters

Parameter	Description
videoMode	Video brackets. See details in Video Mode
layer	optional, set stream type: 0 (default)-high-quality stream, 1- low-quality stream

Return Values

If a stream is created, return the Promise of LocalStream. Successful asynchronous execution indicates the video mode is switched. LocalStream contains the resolution parameters of the video after the switch.
If a stream is not created, return Promise. Successful asynchronous execution indicates the video mode is switched, and then createStream (#createStream) can be called to create a stream based on the set video mode.

Common Promise Error	Description
{error: "INVALID_VIDEO_MODE"}	Invalid video bracket
{error: "INVALID_LAYER"}	Invalid layer
{error: "SET_BITRATE_ERROR"}	Bit rate error

setVideoEncoderConfig

setVideoEncoderConfig(config: VideoEncoderConfig, layer = 0): Promise<LocalStream | void>

Set video encoding parameters of local streams and the parameter can be switched dynamically.

Note:

Call this API before createStream and after init.

The effects of setVideoMode and setVideoEncoderConfig on video stream acquisition are mutually exclusive, and only the last called API takes effect.

Parameters

Parameter	Description
config	Video encoding configuration, see details in VideoEncoderConfig
layer	optional, set stream type: 0 (default)-high-quality stream, 1- low-quality stream

VideoEncoderConfig

interface VideoEncoderConfig {
    width: number,
    height: number,
    frameRate: number,
    bitrate: number,
    minBitrate?: number,
}

Profile	Description
width	Video width, range: [2,4096]
height	Video height, range: [2,4096]
frameRate	Frame rate, range: [1,100], recommended value: [5,30]
bitrate	Bitrate, range:[1,10000], unit: Kbps Too small a bit rate may cause a decrease in video resolution and frame rate For bitrate setting, see details in Video Mode
minBitrate	Optional, the minimum bitrate, range:[1,10000], unit: Kbps

Note:

Due to browser limitations, switching to a higher resolution during the publishing is not supported.

The resolution of the low-quality stream should be smaller than that of the high-quality stream.

Dynamic switching may cause black bars to your video.

The effects of setVideoMode and setVideoEncoderConfig on video stream acquisition are mutually exclusive, and only the last called API takes effect.

The set encoding parameters may not be supported by the browser and will be adjusted according to the actual situation.

Return Values

If a stream is created, return the Promise of LocalStream. Successful asynchronous execution indicates the video mode is switched. LocalStream contains the resolution parameters of the video after the switch.
If a stream is not created, return Promise. Successful asynchronous execution indicates the video mode is switched, and then createStream (#createStream) can be called to create a stream based on the set video mode.

Common Promise Error	Description
{error: "INVALID_CONFIG"}	Invalid configuration
{error: "INVALID_BITRATE"}	Invalid bitrate
{error: "INVALID_MIN_BITRATE"}	Invalid minimum bitrate
{error: "INVALID_FRAME_RATE"}	Invalid frame rate
{error: "INVALID_WIDTH"}	Invalid width
{error: "INVALID_HEIGHT"}	Invalid height
{error: "INVALID_LAYER"}	Invalid layer

changeDevice

changeDevice(kind: 'audio' | 'video', deviceId: string): Promise<LocalStream>

Dynamically switch the audio/video input devices.

Note:

Call after createStream.

Screen recording publishing does not support calling this API.

Parameters

Parameter	Description
kind	Note: 'audio’ or 'video'; 'audio’ indicates switching the microphone device and 'video’ indicates switching the camera device.
deviceId	The target device ID

Return Values

Promise of LocalStream; successful asynchronous execution indicates successful video bracket switching. LocalStream contains parameter information for post-switch video.

Common Promise Error	Description
{error: "INVALID_DEVICE_KIND"}	Invalid device type
{error: "INVALID_DEVICE_ID"}	Invalid device ID
{error: "STREAM_HAS_NOT_BEEN_CREATED"}	Stream not created

subscribe(remoteStream: RemoteStream, option?: SubscribeOption): Promise<RemoteStream>

Subscribe to a remote media stream.

When the remote user publishs media streams, the callback remote_stream_add will be triggered on the local client . And then, the local user call this API to subscribe to a remote media and play it via play.

Note:

The default way of subscription configuredt via lowStream only take effect in the first video subscription; if the video stream is in subscription, you can switch low/high-quality streams by calling changeRemoteVideoStreamType.

Parameters

Parameter	Description
remoteStream	remote_stream_add The remote stream reported RemoteStream
option	Optional subscription parameters SubscribeOption

SubscribeOption

interface SubscribeOption {
    audio: boolean,
    video: boolean,
    lowStream?: boolean,
}

Profile	Description
audio	Boolean value, whether to subscribe to the audio
video	Boolean value, whether to subscribe to the video
lowStream	Optional, whether to subscribe to the low quality stream by default

Return Values

RemoteStream Promise. RemoteStream contains the subscribed stream information.

Common Promise Error	Description
{error: "INVALID_PARAM"}	Invalid parameter type
{error: "SUBSCRIBE_NONE"}	No audio or video subscription
{error: "REMOTE_USER_PUBLISH_H265"}	The remote stream has H265 encoding, which does not support subscription
{error: "STREAM_NOT_EXISTED"}	No streams
{error: "LOW_STREAM_NOT_EXISTED"}	No low quality stream subscribed
{error: "LOW_STREAM_MUST_HAVE_VIDEO"}	Subscribed to the low quality stream but not the video
{error: "INVALID_SUBSCRIBE"}	Invalid subscription
{error: "CANCEL"}	Operation canceled

example

webRtc.on("remote_stream_add", async function(evt, remoteStream) {
    await webRtc.subscribe(remoteStream);
    await webRtc.play(remoteStream.uid, divElement);
});

unsubscribe

unsubscribe(remoteStream: RemoteStream): Promise<void>

Unsubscribe to a remote video stream.

Parameters

Parameter	Description
remoteStream	The remote stream reported by remote_stream_add RemoteStream

Return Values

Promise; successful asynchronous execution indicates the subscription canceled.

Common Promise Error	Description
{error: "STREAM_NOT_EXISTED"}	No low quality stream subscribed
{error: "HAS_NOT_SUBSCRIBE"}	Not subscribed

play

play(uid: string, element: HTMLElement | string, option?: PlayOption): Promise<void>

Play the local stream or subscribed remote stream

Parameters

Parameter	Description
uid	The user ID of the local or subscribed stream
element	Select the HTMLElement or ID of playing
option	Optional playing parameters PlayOption

PlayOption

interface PlayOption {
    muted?: boolean,
    fit?: 'cover' | 'contain' | 'fill',
    mirror?: boolean,
    controls?: boolean,
}

Profile	Description
muted	Optional, whether to mute play; the local stream is muted by default
fit	Optional filling methods; refer to css object-fit. 'contain': maintain the length-width ratio, and there will be a black border; 'cover' (default): maintain the length-width ratio by cropping accordingly; 'fill': stretch the image.
mirror	Optional, whether to play in mirror
controls	Optional, whether to display the control bar of the video tag

Return Values

Promise; successful asynchronous execution indicates playing completed.

Common Promise Error	Description
{error: "INVALID_UID"}	Invalid user ID
{error: "INVALID_ELEMENT"}	Invalid ELEMENT parameter
{error: "INVALID_PLAY_OPTION"}	Invalid play option
{error: "STREAM_NOT_EXISTED"}	No streams
{error: "ALREADY_PLAY"}	Playing in progress
{error: "HAS_NOT_SUBSCRIBE"}	Not subscribed
{error: "CANCEL"}	Operation canceled
{error: "INTERNAL_PLAY_ERROR"}	Internal play error

Autoplay Policy

Due to Autoplay Policy, the browser cannot automatically play sound without the user interacting with the webpage. You can play the video without sound by the following methods：

Method 1: Guide the user to interact with the webpage and then call play to play the video with sound.

Method 2: Guide the user to interact with the webpage by llistening to the event mute_play. When the user is not interacting with the webpage, the SDK will mute the local or remote stream and trigger the mute_play event after calling play. When the SDK detects the interaction, it automatically resumes the audio playback and triggers the mute_play_resume event.

Method 3: Call play and set the paraeters muted and controls of PlayOption to "true", and then the user can click the audio icon on the webpage to umute the audio.

Method 4: Call play in the gesture callback to play audio directly.

Note:

Sites on the browser whitelist are not subject to the autoplay policy, and the whitelist is generated by the browser based on the times the user visits the site and cannot get via JS APIs. So, autoplay with sound is blocked unless the user has interacted with the webpage.

The method 1 is not supported by Safari.

stopPlay

stopPlay(uid: string): Err | null

Stop playing a local or remote stream.

Parameters

Parameter	Description
uid	The user ID of the local or subscribed stream

Return Values

Common Return Value	Description
null	Succeeded
{error: "INVALID_UID"}	Invalid user ID
{error: "STREAM_NOT_EXISTED"}	No streams
{error: "HAS_NOT_PLAY"}	Playing not started

resume

resume(uid: string): Promise<void>

Resume playing the local stream or remote stream. If it cannot be played or changes in its playing status are detected, call the API to try to resume playing.

Parameters

Parameter	Description
uid	The user ID of the local or subscribed stream

Return Values

Promise; successful asynchronous execution indicates playing resumed.

isPlaying

isPlaying(uid: string): boolean

Whether the local stream or subscribed stream is playing.

Parameters

Parameter	Description
uid	The user ID of the ocal or subscribed stream

Return Values

true the local or subscribed stream is playing
false the local or subscribed stream is not playing

setAudioVolume

setAudioVolume(uid: string, volume: number): Err | null

Set the local or remote stream’s playing volume.

Parameters

Parameter	Description
uid	The user ID of the local or subscribed stream
volume	Range: 0-100

Return Values

Common Return Value	Description
null	Succeeded
{error: "INVALID_UID"}	Invalid user ID
{error: "STREAM_NOT_EXISTED"}	No streams
{error: "AUDIO_TRACK_NOT_EXISTED"}	No audio track
{error: "INVALID_VOLUME"}	Invalid volume

setAudioOutputDevice

setAudioOutputDevice(uid: string, deviceId: string): Promise<void>

Select the audio output device; not recommended; the default audio output device is controlled by the system.

Note:

This API is not supported on Safari.

Parameters

Parameter	Description
uid	The user ID of the local or subscribed stream
deviceId	Audio output device ID

Return Values

Promise; successful asynchronous execution indicates calling succeeded.

Common Promise Error	Description
{error: "INVALID_UID"}	Invalid UID
{error: "INVALID_DEVICE_ID"}	Invalid device ID
{error: "STREAM_NOT_EXISTED"}	No streams
{error: "HAS_NOT_PLAY"}	Playing not started
{error: "NOT_SUPPORTED"}	Browser does not support calling the APIs

hasAudio

hasAudio(uid: string): boolean

Whether the user's stream has audio

Parameters

Parameter	Description
uid	The user ID of the local or subscribed stream

Return Values

true: audio available
false: no audio

hasVideo

hasVideo(uid: string): boolean

Whether the user's stream has video

Parameters

Parameter	Description
uid	The user ID of the local or subscribed stream

Return Values

true: audio available
false: no video

enableAudio

enableAudio(uid?: string): Err | null

For local streams, enable audio capture and send; for remote subscribed streams, receive audio data and play.

Parameters

Parameter	Description
uid	The user ID of the local or subscribed stream. If not entered, the local stream is operated by default.

Return Values

Common Return Value	Description
null	Succeeded
{error: "INVALID_UID"}	Invalid user ID
{error: "STREAM_NOT_EXISTED"}	No streams
{error: "INVALID_OPERATION"}	Invalid operation

disableAudio

disableAudio(uid?: string): Err | null

For local streams, send the muted audio; for remote subscribed streams, receive the audio data and mute playing.

Parameters

Parameter	Description
uid	The user ID of the local or subscribed stream. If not entered, the local stream is operated by default.

Return Values

Common Return Value	Description
null	Succeeded
{error: "INVALID_UID"}	Invalid user ID
{error: "STREAM_NOT_EXISTED"}	No streams
{error: "INVALID_OPERATION"}	Invalid operation

enableVideo

enableVideo(uid?: string): Err | null

For local streams, enable video capture and send; for remote subscribed streams, receive video data and play.

Parameters

Parameter	Description
uid	The user ID of the local or subscribed stream. If not entered, the local stream is operated by default.

Return Values

Common Return Value	Description
null	Succeeded
{error: "INVALID_UID"}	Invalid user ID
{error: "STREAM_NOT_EXISTED"}	No streams
{error: "INVALID_OPERATION"}	Invalid operation

disableVideo

disableVideo(uid?: string): Err | null

For local streams, send the blank screen video; for remote subscribed streams, receive the video data and play blank screen.

Parameters

Parameter	Description
uid	The user ID of the local or subscribed stream. If not entered, the local stream is operated by default.

Return Values

Common Return Value	Description
null	Succeeded
{error: "INVALID_UID"}	Invalid user ID
{error: "STREAM_NOT_EXISTED"}	No streams
{error: "INVALID_OPERATION"}	Invalid operation

addPublishOriginStreamUrl

addPublishOriginStreamUrl(url:string):Err | null

Calling this API to push the anchor's current audio/video stream to the specified CDN address.

It can only add one stream pushing address at a time. Call this API repeatedly to push multiple streams. A maximum of five stream pushing addresses is supported.

Add a CDN streaming URL to push the source stream.

You can call this API to push anchor's audio/video streams to the specific CDN URL. You should call removePublishOriginStreamUrl before update the CDN streaming URL.
Only one URL can be added each time this API is called. Up to 5 CDN streaming URLs is supported.
You shoud pubish at least one video before pushing the source stream to the specified URL, and exiting the room will clear the configuration.

Parameters

Parameter	Description
url	CDN streaming URL in RTMP format, which should not exceed 512 bytes

Return Values

Common Return Value	Description
null	Succeeded
{error: "HAS_NOT_JOIN"}	Not joined a room
{error: "INVALID_URL"}	Invalid URL
{error: "NOT_SUPPORTED_IN_GROUP_MODE"}	Invalid group mode
{error: "TOO_MUCH_URLS"}	The number of CDN streaming URLs exceed the upper limit
{error: "HAS_NOT_PUBLISH_VIDEO"}	No published video
{error: "HAS_ADD_URL"}	The CDN streaming URL exists

removePublishOriginStreamUrl

removePublishOriginStreamUrl(url:string) :Err | null

Remove the source stream address.

After calling this API, the audio/video stream will be stopped pushing to the specific CDN address.
Only one URL can be removed each time this API is called.
This API shoud be called after joining a room.

Parameters

Parameter	Description
url	CDN stream pushing addresses are in RTMP format. The characters cannot exceed 512 bytes in length

Return Values

Common Return Value	Description
null	Succeeded
{error: "HAS_NOT_JOIN"}	Not joined a room
{error: "INVALID_URL"}	Invalid URL
{error: "NOT_SUPPORTED_IN_GROUP_MODE"}	Group mode not supported
{error: "HAS_ADD_URL"}	The CDN streaming URL exists

addPublishTranscodingStreamUrl

addPublishTranscodingStreamUrl(taskId:string, url:string):Err | null

Add the CDN streaming URL to push transcoded streams.

This API shoud be called after the adding transcoding task by calling setLiveTranscodingTask.
The transcoded stream will be pushed to the specific CDN address after calling this API. You can add a new CDN streaming URL after removing the current one by calling removePublishTranscodingStreamUrl.
Only one URL can be added each time this API is called. Up to 5 CDN streaming URLs is supported.
You shoud pubish at least one video before pushing the source stream to the specified URL, and exiting the room will clear the configuration.

Parameters

Parameter	Description
taskId	Task ID [only supports a combination of the characters [A,Z],[a,z],[0,9], not to exceed 20 bytes in length]
url	CDN stream pushing addresses are in RTMP format. The characters cannot exceed 512 bytes in length

Return Values

Common Return Value	Description
null	Succeeded
{error: "HAS_NOT_JOIN"}	Not joined a room
{error: "INVALID_TASK_ID"}	Invalid task ID
{error: "INVALID_URL"}	Invalid URL
{error: "NOT_SUPPORTED_IN_GROUP_MODE"}	Group mode not supported
{error: "HAS_NOT_PUBLISH"}	Unpusblished
{error: "HAS_ADD_URL"}	The CDN streaming URL exists
{error: "TOO_MUCH_URLS"}	The number of CDN streaming URLs exceed the upper limit
{error: "TASKID_NOT_EXIST"}	The transcoding task does not exist

removePublishTranscodingStreamUrl

removePublishTranscodingStreamUrl(taskId:string, url:string):Err | null

Remove the CND streaming address of transcoded streams.

After calling this API, the mixed stream will be stopped pushing to the specific CDN address.
Only one URL can be removed each time this API is called.
This API shoud be called after joining a room.

Parameters

Parameter	Description
taskId	Task ID [only supports a combination of the characters [A,Z],[a,z],[0,9], not to exceed 20 bytes in length]
url	CDN stream pushing addresses are in RTMP format. The characters cannot exceed 512 bytes in length

Return Values

Common Return Value	Description
null	Succeeded
{error: "HAS_NOT_JOIN"}	Not joined a room
{error: "INVALID_TASK_ID"}	Invalid task ID
{error: "INVALID_URL"}	Invalid URL
{error: "NOT_SUPPORTED_IN_GROUP_MODE"}	Group mode not supported
{error: "TASKID_NOT_EXIST"}	The transcoding task does not exist
{error: "URL_NOT_EXIST"}	The CDN streaming URL exists

setLiveTranscodingTask

typescript
setLiveTranscodingTask(taskId:string, transcoding:LiveTranscoding):Err | null

Add/update the transcoding task.

The system will mix the pulled source streams after calling this API. Transcoding tasks are distinguished by the task ID.
You can call this API to update mixed-stream parameters. Multiple mixed-stream tasks can be added in a room.
This API should be called after joining a room, and the configuration willed be cleared after exiting the room.
Push-stream address can be added by call addPublishTranscodingStreamUrl, and When the mixed stream will be pushed to the specified address after the transcoding task is finished.

Parameters

Parameter	Description
taskId	Stream mixing task [only supports a combination of the characters [A,Z],[a,z],[0,9], not to exceed 20 bytes
transcoding	For information about stream mixing configuration, see LiveTranscoding

LiveTranscoding

LiveTranscoding :{ 
    transcodingMode:number; //Transcoding mode (refer to: definition of output mode of video mixing) 
	userList:TranscodingUser[]; 
	userList:TranscodingUser[];
	extConfig:ExtConfig[]; //Additional info, including background and watermark
};

TranscodingUser

TranscodingUser :{ 
            bStandard:boolean,        //standard stream user or not 
            layoutX:number,           //user's x-coordinate in video mixing canvas 
            layoutY:number,           //user's y-coordinate in video mixing canvas 
            layoutW:number,           //user's width in  video mixing canvas
            layoutH:number,           //user's height in video mixing canvas
            zOrder:number,            //user's live streaming video frame layer (0=bottom layer, 1=first layer up from the bottom, and so on) 
            bCrop:number,             //0: image is centered after zooming, with black borders on all sides; 1: image is centered after zooming, and any excess is cropped from all sides
            cropX:number,             //x-coordinate of cropping area. If not filled in, default will center
            cropY:number,             //y-coordinate of cropping area 
            cropW:number,             //width of cropping area
            cropH:number,             //height of cropping area
            alpha:number,             //user's live streaming video transparency. Value range: [0.0, 1.0]. 0.0 complete transparency; 1.0 complete opacity (default).
            audioChannel:number,      //not yet realized
            uid:string, 
            roomId:string      
};

ExtConfig

ExtConfig :{
            type:string,   //Type: background, watermark
            color?:string, //Background color, which is vliad when "type" is "background"
            image?:{       //Background image object, which is vliad when "type" is "background"
                url:string,     //Background image address
                scale:number    //Zoom/scale mode of the background image
            },
            timestamp?:{        //Timestamp watermark, which is vliad when "type" is "watermark"
                x:number,     //The x-coordinate of the watermark on the canvas
                y:number,     //The y-coordinate of the watermark on the canvas
                format:string,           //Timestamp format
                font:string,             //Font: NotoSansCJK
                size:number,             //Font size
                color:string,            //Font color
                backgroundColor:string,  //Font background color
                alpha:number             //Transparency
            },
            textList?:TextMark[],        //Text watermark list, which is vliad when "type" is "watermark"
            imageList?:ImageMark[]       //Image watermark list, which is vliad when "type" is "watermark"
};

TextMark

TextMark :{                         //Text watermark
                x:number,           //The x-coordinate of the watermark on the canvas
                y:number,           //The y-coordinate of the watermark on the canvas
                content:string,     //Text content
                font:string,             //Font: NotoSansCJK
                size:number,             //Font size
                color:string,            //Font color
                backgroundColor:string,  //Font background color
                alpha:number             //Transparency
};

ImageMark

ImageMark :{                        //Image watermark
                x:number,           //The x-coordinate of the watermark on the canvas
                y:number,           //The y-coordinate of the watermark on the canvas
                width:number,       //Image width
                heigth:number,      //Image height
                url:string,         //Image URL
                scale:number,       //Image zoom/crop mode
                alpha:number        //Transparency
};

Output modes are defined as below:

Bracket	Resolution	Bit Rate	Frame Rate
1	320 x 180	200 kbps	15 fps
2	320 x 240	200 kbps	15 fps
3	640 x 360	400 kbps	15 fps
4	640 x 480	600 kbps	15 fps
5	960 x 544	1000 kbps	24 fps
6	1280 x 720	1600 kbps	24 fps
7	1920 x 1080	4500 kbps	24 fps

Return Values

Common Return Value	Description
null	Succeeded
{error: "HAS_NOT_JOIN"}	Not joined a room
{error: "INVALID_TASK_ID"}	Invalid task ID
{error: "NOT_SUPPORTED_IN_GROUP_MODE"}	Group mode not supported
{error: "INVALID_LIVETRANSCODING"}	Invalid transcoding parameters

removeLiveTranscodingTask

removeLiveTranscodingTask(taskId:string):Err | null

Remove the transcoding task.

After calling this API, the transcoding task will stop and be deleted, but the URL added via addPublishTranscodingStreamUrl will not be deleted.

Parameters

Parameter	Description
taskId	Stream mixing task, only supports a combination of the characters [A,Z],[a,z],[0,9], not to exceed 20 bytes

Return Values

Common Return Value	Description
null	Succeeded
{error: "HAS_NOT_JOIN"}	Not joined a room
{error: "INVALID_TASK_ID"}	Invalid task ID
{error: "NOT_SUPPORTED_IN_GROUP_MODE"}	Group mode not supported
{error: "TASKID_NOT_EXIST"}	The transcoding task does not exist

addSubscribe

addSubscribe(roomId:string, uid:string): Err | null

Subscribe across channels.

After joining, call this API to subscribe to another room's audio/video streams. It will be cleared upon your leaving the room.

Parameters

Parameter	Description
roomId	Room ID [only supports a combination of the characters [A,Z],[a,z],[0,9],-,_, not to exceed 64 bytes in length]
uid	User ID [only supports a combination of the characters [A,Z],[a,z],[0,9],-,_, not to exceed 64 bytes in length]

Return Values

Common Return Value	Description
null	Succeeded
{error: "INVALID_UID"}	Invalid user ID
{error: "INVALID_ROOM_ID"}	Invalid room ID
{error: "NOT_SUPPORTED_IN_GROUP_MODE"}	Group mode not supported

removeSubscribe

removeSubscribe(roomId:string, uid:string): Err | null

Cancel a cross-room subscription.

Parameters

Parameter	Description
roomId	Room ID, only supports a combination of the characters [A,Z],[a,z],[0,9],-,_, not to exceed 64 bytes in length
uid	User ID, only supports a combination of the characters [A,Z],[a,z],[0,9],-,_, not to exceed 64 bytes in length

Return Values

Common Return Value	Description
null	Succeeded
{error: "INVALID_UID"}	Invalid user ID
{error: "INVALID_ROOM_ID"}	Invalid room ID
{error: "NOT_SUPPORTED_IN_GROUP_MODE"}	Group mode not supported
{error: "REMOVE_SAME_CHANNEL"}	Canceling the subscription across channels removed the same channels

createDualStream

createDualStream(param: DualStreamParam): Promise<LocalStream>

Create a local high/low quality video stream

The high quality video stream has high resolution and bit rate, while the low quality video stream has low resolution and bit rate. After calling, publish a high/low quality stream with publish. The subscriber may then choose to receive either the high quality or low quality stream.

Parameters

Parameter	Description
param	High/low quality stream parameter DualStreamParam

DualStreamParam

interface DualStreamParam {
    audio?: {
        deviceId?: string;
        source?: MediaStreamTrack; // custom audio track
    } | boolean;
    video: {
        highVideoMode?: number;
        lowVideoMode?: number;
        deviceId?: string;
    };
    playType?: 1 | 2;
}

Profile	Description
audio	Enable the audio stream, which can be a Boolean value or a built-in parameter; if not entered, indicate that the audio stream is not enabled.
video	Enable the video stream, which can be a built-in parameter; if not entered, indicate that the video stream is not enabled.
playType	Optional parameters: In audio/video mode, 1 (default) indicates that the camera and microphone are publishing the audio/video; 2 indicates screen sharing

Embedded Audio Parameters

Profile	Description
deviceId	Audio publishing device ID. If blank, select default
source	Optional，audio track for creating the stream, the track's type is MediaStreamTrack, which can be obtained via the browser API

Embedded Video Parameters

Profile	Description
highVideoMode	High-quality video stream mode, which is 3 (High Definition) by default. See details in the Video Mode
lowVideoMode	Low-quality video stream mode, which is 1 (Smooth) by default.,The low-quality stream has lower resolution. See details in the Video Mode
deviceId	Video publishing device ID. If not entered, select default

Return Values

LocalStream Promise; successful asynchronous return indicates the high/low-quality stream created.

Common Promise Error	Description
{error: "HAS_NOT_JOIN"}	Room not joined
{error: "STREAM_ALREADY_CREATED"}	Stream already created
{error: "STREAM_IS_CREATING"}	Stream being created
{error: "INVALID_STREAM_PARAM"}	Invalid stream parameter
{error: "INVALID_PLAY_TYPE"}	Invalid publishing mode
{error: "INVALID_DEVICE_ID"}	Invalid device ID
{error: "VIDEO_MODE_OUT_OF_ORDER"}	High/low quality stream mode sequencing error
{error: "INVALID_HIGH_VIDEO_MODE"}	Invalid high quality stream video bracket
{error: "INVALID_LOW_VIDEO_MODE"}	Invalid low quality stream video bracket
{error: "PERMISSION_DENIED"}	The user rejected the request for media device
{error: "DEVICE_NOT_FOUND"}	No device
{error: "DEVICE_NOT_READABLE"}	Device unreadable
{error: "DEVICE_ERROR"}	Device malfunction
{error: "SCREEN_CAPTURE_NOT_SUPPORTED"}	Screen sharing not supported

changeRemoteVideoStreamType

changeRemoteVideoStreamType(speakerUid: string, videoStreamType: number): Promise<RemoteStream>

When an anchor is publishing the high/low quality stream, audience can receive either the high or low quality stream through this API.

Note:

Upon calling this API, the return indicates that the local call was successful. There will be a certain delay as the server switches the streaming data.

Parameters

Parameter	Description
speakerUid	Anchor ID
videoStreamType	0: high quality stream (default), 1: low quality stream. Namely, videoStreamType is 0.

Return Values

Promise，successful asynchronous return indicates the high/low-quality stream created. LocalStream contains contains the local stream parameters after switching devices.

Common Promise Error	Description
{error: "STREAM_NOT_EXISTED"}	The high/-low quality stream does not exist
{error: "NO_SUBSCRIBE"}	Not subscribed
{error: "CANCEL"}	There is no stream
{error: "SAME_TARGET_STREAM"}	The target stream to switch is the same as the current stream

startAudioMixing

startAudioMixing(param: AudioMixingParam, id: number = 0): Promise<string>

Enable audio mixing of music files and the microphone. Call it after createStream.

Parameters

Parameter	Description
param	AudioMixingParam
id	Mixed audio ID (number). Set different IDs to mix multiple audio streams simultaneously. If not entered, the default value is 0. Value range: [0,10,000).

AudioMixingParam


interface AudioMixingParam {
    local?: boolean;
    url?: string;
    cycle?: number;
    loop?: boolean;
    playTime?: number;
    replace?: boolean;
    extraPlay?: boolean;
}

Profile	Description
local	Whether to select the local file.
url	Online background music URL, which is invalid when local is "true"
cycle	The number of times background music is played
loop	Whether to play the background music on loop. Conflicted with cycle.
playTime	The start time of playing music (ms).
replace	Whether to replace microphone input with music. When "true", the published stream contains only background music and not microphone input. To enable this option, the ID must be 0.
extraPlay	Whether to play background music on the anchor as well. "true" by default.

Return Values

Promise; successful asynchronous execution indicates playing of mixed audio started.

Common Promise Error	Description
{error: "INVALID_MIX_ID"}	Invalid mixed audio ID
{error: "STREAM_HAS_NOT_BEEN_CREATED"}	Stream not created
{error: "AUDIO_TRACK_NOT_EXISTED"}	No audio track
{error: "STREAM_IS_CREATING"}	Stream being created
{error: "SOURCE_LOAD_ERROR"}	Error loading mixed audio resource

stopAudioMixing

stopAudioMixing(id: number = 0): Err | null

Disable audio mixing of the background music and the microphone. Call after startAudioMixing.

Parameters

Profile	Description
id	Mixed audio ID; default=0

Return Values

Common Return Value	Description
null	Succeeded
{error: "INVALID_MIX_ID"}	Invalid mixed audio ID
{error: "MIX_AUDIO_NOT_EXISTED"}	No mixed audio

pauseAudioMixing

pauseAudioMixing(id: number = 0): Err | null

Pause audio mixing of the background music and microphone.

Parameters

Profile	Description
id	Mixed audio ID; default=0

Return Values

Common Return Value	Description
null	Succeeded
{error: "INVALID_MIX_ID"}	Invalid mixed audio ID
{error: "MIX_AUDIO_NOT_EXISTED"}	No mixed audio
{error: "ALREADY_PAUSE"}	Mixed audio already paused

resumeAudioMixing

resumeAudioMixing(id: number = 0): Err | null

Resume audio mixing of the background music and the microphone. Call after pauseAudioMixing.

Parameters

Profile	Description
id	Mixed audio ID; default=0

Return Values

Common Return Value	Description
null	Succeeded
{error: "INVALID_MIX_ID"}	Invalid mixed audio ID
{error: "MIX_AUDIO_NOT_EXISTED"}	No mixed audio
{error: "NOT_PAUSE"}	Mixed audio not paused

setAudioMixingVolume

setAudioMixingVolume(volume: number, id: number = 0): Err | null

Set the audio mixing volume.

Parameters

Parameter	Description
volume	Volume; value range [0,100]; default=100
id	Mixed audio ID; default=0

Return Values

Common Return Value	Description
null	Succeeded
{error: "INVALID_MIX_ID"}	Invalid mixed audio ID
{error: "MIX_AUDIO_NOT_EXISTED"}	No mixed audio
{error: "INVALID_VOLUME"}	Invalid volume

getAudioMixingDuration

getAudioMixingDuration(id: number = 0): number

Get the total duration of audio mixing.

Parameters

Profile	Description
id	Mixed audio ID; default=0

Return Values

The duration (s) of the mixed audio file

getAudioMixingTime

getAudioMixingTime(id: number = 0): number

Get the current audio mixing time (s).

Parameters

Profile	Description
id	Mixed audio ID; default=0

Return Values

The current playing time of the mixed audio

setAudioMixingTime

setAudioMixingTime(time: number, id: number = 0): Err | null

Set the audio mixing time.

Parameters

Parameter	Description
time	Playing time (s)
id	Mixed audio ID; default=0

Return Values

Common Return Value	Description
null	Succeeded
{error: "INVALID_MIX_ID"}	Invalid mixed audio ID
{error: "MIX_AUDIO_NOT_EXISTED"}	No mixed audio
{error: "INVALID_TIME"}	Invalid time parameter

stopAllAudioMixing

stopAllAudioMixing(): Err | null

Stop all audio mixing.

Return Values

Common Return Value	Description
null	Succeeded
{error: "HAS_NOT_INIT"}	Not initialized

pauseAllAudioMixing

Pause all audio mixing.

pauseAllAudioMixing(): Err | null

Return Values

Common Return Value	Description
null	Succeeded
{error: "HAS_NOT_INIT"}	Not initialized

resumeAllAudioMixing

resumeAllAudioMixing(): Err | null

Resume all audio mixing.

Return Values

Common Return Value	Description
null	Succeeded
{error: "HAS_NOT_INIT"}	Not initialized

getPublisherAudioLevel

getPublisherAudioLevel(): number

Get the current local stream volume.

Note:

Affected by the browser Autoplay Policy; call interaction with the page

Return Values

The local stream volume range [0,100].

getSubscriberAudioLevel

getSubscriberAudioLevel(uid: string):number

Get the current subscribed stream volume.

Note:

Affected by the browser Autoplay Policy; call after interaction with the page

Parameters

Parameter	Description
uid	Subscription stream ID [only supports a combination of the characters [A,Z],[a,z],[0,9],-,_, not to exceed 64 bytes in length]

Return Values

The subscribed stream volume range [0,100].

enableAudioLevelReport

enableAudioLevelReport(): Err | null

Enable audio volume reporting.

Repeated volume reporting at two-second intervals for the local stream and all subscribed streams. Monitor volume reporting by event audio_level_report.

Return Values

Common Return Value	Description
null	Succeeded
{error: "INVALID_OPERATION"}	Invalid operation

disableAudioLevelReport

disableAudioLevelReport(): Err | null

Disable audio volume reporting.

Return Values

Common Return Value	Description
null	Succeeded
{error: "INVALID_OPERATION"}	Invalid operation

getDevices

static getDevices(): Promise<MediaDeviceInfo[]>

A static function to obtain the information of the browser's audio input, video input, and audio output devices.

Return Values

Promise of the device information array MediaDeviceInfo.

Common Promise Error	Description
{error: "NOT_SUPPORTED"}	Browser does not support calling the APIs

getAudioDevices

static getAudioDevices(askPermission = false): Promise<MediaDeviceInfo[]>

A static function to obtain the information of the browser's audio input device.

Parameters

Profie

Description

askPermission

Whether to request user authorization when the device name cannot be obtained: true-yes, false (default)-no
The device name (Label) cannot be obtained without user authorization.
The device ID(deviceId) is unavailable on Chrome 81.
It is recommended to set it to true to ensure that the correct device information after calling this API, otherwise the label and deviceId in the MediaDeviceInfo returned may be empty strings.

Return Values

Promise of the audio input device information array MediaDeviceInfo.

Common Promise Error	Description
{error: "NOT_SUPPORTED"}	Browser does not support calling the APIs
{error: "PERMISSION_DENIED"}	The request for media device is rejected by the user
{error: "DEVICE_NOT_FOUND"}	No equipment found

getVideoDevices

static getVideoDevices(askPermission = false): Promise<MediaDeviceInfo[]>

A static function to obtain the informatio nfo the browser's video input device.

Parameters

Profile

Description

askPermission

Return Values

Promise of the video input device information array MediaDeviceInfo.

Common Promise Error	Description
{error: "NOT_SUPPORTED"}	Browser does not support calling APIs

getPlayoutDevices

static getPlayoutDevices(): Promise<MediaDeviceInfo[]>

A static function to obtain the information of the browser's audio output device.

Note：

This API is invalid on Safari.

Return Values

Promise of the audio output device information array MediaDeviceInfo.

Common Promise Error	Description
{error: "NOT_SUPPORTED"}	Browser does not support calling APIs
{error: "PERMISSION_DENIED"}	The request for media devices is rejected by the user
{error: "DEVICE_NOT_FOUND"}	No equipment found

detectDevice

static detectDevice(kind: 'audio' | 'video', deviceId?: string): Promise<void>

Dtecte whether the device is available.

Parameters

Profie	Description
kind	Things to be detected: audio-microphone, video-camera
deviceId	Optional, ID of the device to be detected

Return Values

Promise, asynchronous execution completion indicates that the device is available and can then be used to create a stream.

Common Promise Error	Description
{error: "PERMISSION_DENIED"}	The request for media devices is rejected by the user
{error: "DEVICE_NOT_FOUND"}	No equipment found
{error: "DEVICE_NOT_READABLE"}	The device is not readable
{error: "DEVICE_ERROR"}	Device error

getSignalConnectionState

getSignalConnectionState():string

Get the connection status of the signaling room. Call after init.

Return Values

The signaling room's connection status, e.g. "connected", "disconnected", or "connecting"

getMediaConnectionState

getMediaConnectionState(): MediaConnectionState

Get the connection status of the media room. Call after init.

Return Values

MediaConnectionState

MediaConnectionState

interface MediaConnectionState {
    result?: {
        uplinkStateMap: Map<string, string>,
        downlinkStateMap: Map<string, string>
    };
    err?: Err;
}

Profile	Description
result	Contain the map structures of uplinkStateMap and downlinkStateMap; key is [uid: string], value is [connection state:string]
err	Calling error

getSessionStats

getSessionStats(): SessionStats

Get the session-level connection statistics. Call after init.

Return Values

SessionStats

SessionStats

interface SessionStats {
    result?: {
        sendBitRate: number;
        sendBytes: number;
        recvBitRate: number;
        recvBytes: number;
    };
    err?: Err;
}

Profile	Description
result	See details in the table below
err	Calling error

result contents:

Profile	Description
sendBitRate	number; the total audio/video output bit rate (kpbs); an instantaneous value; calculated at one-second intervals
sendBytes	number; the total sent bytes, which is cleared when the WebRTC object is destroyed
recvBitRate	number; the total audio/video receiving bit rate (kpbs); an instantaneous value; calculated at one-second intervals
recvBytes	number; the total received bytes, which is cleared when the WebRTC object is destroyed

getUplinkVideoStats

getUplinkVideoStats(): VideoStats

Get the uplink video stream statistics. Call once video is published and the media room's status is "connected"

Return Values

VideoStats

VideoStats

interface VideoStats {
    result?: Map<string, VideoStatsItem>;
    err?: Err;
}

Profile	Description
result	Map structure; key is uid, value is VideoStatsItem
err	Calling error

VideoStatsItem

interface VideoStatsItem {
    time: string;
    rtt: string;
    networkScore: string;
    videoCodec: string;
    videoMuteState?: string;
    videoResolution: string;
    videoFrameRate: string;
    videoBitRate: string;
    videoLostRate: string;
}

Profile	Description
time	string; status capture's system timestamp
rtt	string; RTT (Round-Trip Time) from the SDK to the media server (ms)
networkScore	string; the network quality score. Refer to network_score for the definition
videoCodec	string; the video encoding/decoding type, "H264" or "VP8"
videoMuteState	string; whether the video transmission display is disabled; true=disabled, false=enabled
videoResolution	string; the video resolution (width x height), e.g. 640 x 480
videoFrameRate	string; the video frame rate (fps); an instantaneous value; calculated at one-second intervals
videoBitRate	string; the video bit rate (kpbs); an instantaneous value; calculated at one-second intervals
videoLostRate	string; the video packet loss rate (for reference only); an instantaneous value

getUplinkAudioStats

getUplinkAudioStats(): AudioStats

Get the uplink audio stream statistics. Call once the audio is published and the media room's status is "connected"

Return Values

AudioStats

AudioStats

interface UplinkAudioStats {
    result?: Map<string, AudioStatsItem>;
    err?: Err;
}

Profile	Description
result	Map structure; key is uid, value is AudioStats
err	Calling error

AudioStatsItem

interface AudioStatsItem {
    time: string;
    rtt: string;
    networkScore: string;
    audioCodec: string;
    audioMuteState?: string;
    audioLevel: string;
    audioBitRate: string;
    audioLostRate: string;
}

Profile	Description
time	string; status capture's system timestamp
rtt	string; RTT (Round-Trip Time) from the SDK to the media server (ms)
networkScore	string; the network quality score. Refer to network_score for the definition
audioCodec	string; the audio encoding/decoding type; currently only supports "opus"
audioMuteState	string; whether the audio is muted, true= muted, false=unmuted
audioLevel	string; the audio volume level, range[[0,100]]
audioBitRate	string; the audio bit rate (kpbs); an instantaneous value; calculated at one-second intervals
audioLostRate	string; the audio packet loss rate (for reference only); an instantaneous value

getDownlinkVideoStats

getDownlinkVideoStats(): VideoStats

Get the downlink video statistics. Call once you subscribed to a video stream and the media room's status is "connected”.

Return Values

VideoStats

getDownlinkAudioStats

Get the downlink audio statistics. Call once you subscribed to an audio stream and the media room's status is "connected".

getDownlinkAudioStats(): AudioStats

Return Values

AudioStats

getAudioTrack

getAudioTrack(uid?: string): MediaStreamTrack | undefined

Get the audio track of remote/local streams.

Parameters

Parameter	Description
uid	ID of user to which the local/remote streams belong; if it is not configured, get the audio track of local streams by default

Return Values

MediaStreamTrack
Return undefined when the audio track corresponding to UID does not exist.

getVideoTrack

getVideoTrack(uid?: string): MediaStreamTrack | undefined

Get the video track of remote/local streams.

Parameter

Parameter	Description
uid	ID of user to which the local/remote streams belong; if it is not configured, get the audio track of local streams by default

Return Values

MediaStreamTrack
Return undefined when the video track corresponding to UID does not exist.

addTrack

addTrack(track: MediaStreamTrack): Promise<void>

Add the audio.video track to the local stream.

Note:

This API should be called after createStream.

An achor can only have one video track at most.

Audio mixing will occur when multiple audio tracks are added.

The SDK will not play the audio track added by addTrack. You can create an Audio tag to play it.

Parameter

Profile	Description
track	Audio/ video track to be added of type MediaStreamTrack

Return Values

Promise，异步执行成功表示调用成功。

Common Promise Error	Description
{error: "INVALID_TRACK"}	Invalid track
{error: "STREAM_NOT_EXISTED"}	The stream does not exist
{error: "STREAM_IS_CREATING"}	The stream is being created
{error: "NOT_SUPPORT_WITH_DUAL_STREAM"}	This API is not supported in dual stream mode
{error: "SAME_KIND_TRACK_EXISTED"}	Cannot be added as a stream of the same type already exists
{error: "ALREADY_ADD"}	The track is added

removeTrack

removeTrack(track: MediaStreamTrack): Promise<void>

Remove the audio/video track from the local stream.

Note:

This API should be called after createStream.

Can not remove all tracks, at least keep one audio or video track.

Parameter

属性	Description
track	Audio/ video track to be added of type MediaStreamTrack, which can be obtainde by getAudioTrack or getVideoTrack

Return Values

Promise, asynchronous execution completion indicates success.

Common Promise Error	Description
{error: "INVALID_TRACK"}	Invalid track
{error: "STREAM_NOT_EXISTED"}	The stream does not exist
{error: "STREAM_IS_CREATING"}	The stream is being created
{error: "NOT_SUPPORT_WITH_DUAL_STREAM"}	This API is not supported in dual stream mode
{error: "NO_TRACK_LEFT"}	Cannot remove or tracks

replaceTrack

replaceTrack(track: MediaStreamTrack, oldSourceTrack?: MediaStreamTrack): Promise<void>

Replace the audio/video track in the local stream.

Note：

This API should be called after createStream.

Return Values

Promise, asynchronous execution completion indicates success.

Common Promise Error	Description
{error: "INVALID_TRACK"}	Invalid track
{error: "STREAM_NOT_EXISTED"}	The stream does not exist
{error: "STREAM_IS_CREATING"}	The stream is being created
{error: "NOT_SUPPORT_WITH_DUAL_STREAM"}	This API is not supported in dual stream mode

Parameter

属性	Description
track	New audio/ video track to be added of type MediaStreamTrack,
oldSourceTrack	Optional, audio/ video track to be replaced; if it is not configured, replace all audio/video tracks

setLogLevel

static setLogLevel(level: number): Err | null

Set the log level.

Parameters

Profile	Description
level	Log level. Possible values: WebRTC.DEBUG, WebRTC.INFO, WebRTC.WARN, WebRTC.ERROR, WebRTC.NONE

Return Values

Return null for success.
Return the Err object for failure.

Class Definitions

Err

interface Err {
    error: string;
}

Some APIs return the Err object for calling error. The error message displayed through err.error.

Parameter	Description
error	Error message

LocalStream

interface LocalStream {
    uid: string, roomId: string,
    stream?: MediaStream,
    audio?: StreamParam,
    video?: StreamParam,
}

The local stream information.

Profile	Description
uid	Anchor ID
roomId	ID of the room joined
stream	Raw audio/video data streams
audio	Audiostream parameter indicating that the local stream contains audio
video	Videostream parameter indicating that the local stream contains video

RemoteStream

interface RemoteStream {
    uid: string, roomId: string,
    stream?: MediaStream,
    audio?: StreamParam,
    video?: StreamParam,
    hasLowVideo?: boolean,
}

Profile	Description
uid	The user ID of the subscribed remote stream
roomId	The room ID of the remote stream
stream	Raw audio/video data streams
audio	Audio stream parameter indicating that the remote stream contains audio
video	Video stream parameter indicating that the remote stream contains video
hasLowVideo	Whether the remote stream has low quality streams

StreamParam

interface StreamParam {
    width?: number,
    height?: number,
    bitrate?: number,
    frameRate?: number,
    codec?: string,
    sampleRate?: number,
    room?: number,
}

Audio or video stream parameter information

Profile	Description
width	Video width
height	Video height
bitrate	Video bit rate
frameRate	Video frame rate
codec	Code
sampleRate	Audio sampling rate
room	Number of the audio channels

MediaDeviceInfo

interface MediaDeviceInfo {
    readonly deviceId: string;
    readonly groupId: string;
    readonly kind: MediaDeviceKind;
    readonly label: string;
}

Profile	Description
deviceId	Device ID
groupId	Group ID
kind	Device type
label	Device tag