Functional APIs

API List

API	Description
new WebRTC	Create a WebRTC object
init	Initialize
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 channel
leaveRoom	Leave a channel
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
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-channel 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
getSystemStats	Get the system information
getSignalConnectionState	Get the connection status of the signaling channel
getMediaConnectionState	Get the connection status of the media channel
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
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

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

joinRoom

joinRoom(roomParam: RoomParam): Promise<Uid>

Calling this API allows users to join the communication channel.

Users in the channel 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 channel.

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 [Authentication Access Manual]
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 version or later, and requires localhost or https domain.

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

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 channel, 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 channel 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 channel 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;
    } | boolean,
    video?: {
        deviceId?: string;
        videoMode: number;
    },
    playType?: 1 | 2;
}

Profile	Description
audio	Enable the audio stream, which can be a Boolean value or built-in parameters; 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 the audio/video mode, 1 (default) indicates that the camera and microphone are publishing the audio/video; 2 indicates screen sharing

The built-in parameters of audio

Profile	Description
deviceId	Audio publishing device ID. If not entered, select default

The built-in parameters of video

Profile	Description
videoMode	Video bracket is required. See details in the Video Bracket Information Table
deviceId	Video device ID. If not entered, select default

Video Bracket Information Table

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.

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: "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 channel 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

unpublish

unpublish(): Err | null

This API cancels audio/video stream pushing to the channel. You may call it at any point during the publishing.

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

setVideoMode

setVideoMode(videoMode: number): Promise<LocalStream>

Dynamically switch the video brackets of the streams created.

Note:

• setVideoModeonly only sets high quality stream in the case of the high/low quality stream
• Due to browser limitations, screen recording publishing does not support switching to higher resolutions during the publishing.

Parameters

Parameter	Description
videoMode	Video brackets. See details in Video Bracket Information Table.

Return Values

• Promise of LocalStream; successful asynchronous execution indicates the video bracket switched. LocalStream contains the resolution parameters of the video after switching.

Common Promise Error	Description
{error: "INVALID_VIDEO_MODE"}	Invalid video bracket
{error: "STREAM_HAS_NOT_BEEN_CREATED"}	Stream not created
{error: "SET_BITRATE_ERROR"}	Bit rate error

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

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

Subscribe to a remote media stream.

Calling this API will issue remote media stream notifications to you after you join the channel; upon notification arrival, “remote_stream_add” will be triggered. Call this API to subscribe and call play to play the remote stream after subscription.

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 its Autoplay Policy, the browser cannot automatically play sound without the user interacting with the page.

If the user has not interacted with the page, calling play will mute playing. The SDK will resume the unmuted audio playing upon detecting interaction with the page. No need to process it.

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.

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.

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: "INVALID_URL"}	Invalid URL
{error: "NOT_SUPPORTED_IN_GROUP_MODE"}	Group mode not supported

removePublishOriginStreamUrl

removePublishOriginStreamUrl(url:string) :Err | null

Call this API to stop pushing the anchor's current audio/video stream to the specified CDN address.

Parameters

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

Return Values

Common Return Value	Description
null	Succeeded
{error: "INVALID_URL"}	Invalid URL
{error: "NOT_SUPPORTED_IN_GROUP_MODE"}	Group mode not supported

addPublishTranscodingStreamUrl

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

Parameters

Parameter	Description
taskId	Task ID [only supports a combination of the characters [A,Z],[a,z],[0,9],-,_, not to exceed 64 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: "INVALID_TASK_ID"}	Invalid task ID
{error: "INVALID_URL"}	Invalid URL
{error: "NOT_SUPPORTED_IN_GROUP_MODE"}	Group mode not supported

removePublishTranscodingStreamUrl

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

Call this API to stop pushing the specified mixed stream to the specified CDN address.

Parameters

Parameter	Description
taskId	Task ID [only supports a combination of the characters [A,Z],[a,z],[0,9],-,_, not to exceed 64 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: "INVALID_TASK_ID"}	Invalid task ID
{error: "INVALID_URL"}	Invalid URL
{error: "NOT_SUPPORTED_IN_GROUP_MODE"}	Group mode not supported

setLiveTranscodingTask

setLiveTranscodingTask(taskId:number, transcodingCfg:LiveTranscoding):Err | null

Call this API and Jolcoud‘s background will begin the stream mixing task, pulling all source streams for audio and video mixing.

The application needs to specify the stream mixing IDs to differentiate stream mixing tasks. Call this API repeatedly throughout the mixing to update stream mixing parameters. You can set multiple stream mixing tasks in the same channel.

Parameters

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

LiveTranscoding is defined as below:

LiveTranscoding :{ 
    transcodingMode:number; //Transcoding mode (refer to: definition of output mode of video mixing) 
	userCount:number; 
	userList:TranscodingUser[]; 
};

TranscodingUser is defined as below:

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      
};

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	Successful
{error: "INVALID_TASK_ID"}	Invalid task ID
{error: "NOT_SUPPORTED_IN_GROUP_MODE"}	Group mode not supported

removeLiveTranscodingTask

removeLiveTranscodingTask(taskId:string):Err | null

Call this API and Jolcoud's background will terminate and delete the stream mixing task.

Parameters

Parameter	Description
taskId	Stream mixing task ID is generated by the application. It must be unique in the entire domain

Return Values

Common Return Value	Description
null	Successful
{error: "INVALID_TASK_ID"}	Invalid task ID
{error: "NOT_SUPPORTED_IN_GROUP_MODE"}	Group mode not supported

addSubscribe

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

Subscribe across channels.

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

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	Successful
{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-channel 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	Successful
{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;
    } | 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

The built-in parameters of audio

Profile	Description
deviceId	audio publishing device ID. If blank, select default

The built-in parameters of video

Profile	Description
highVideoMode	The high quality video bracket is required. See details in the Video Bracket Information Table
lowVideoMode	The low quality video mode is required. The low quality video has lower resolution. See details in the Video Bracket Information Table
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 execution indicates calling succeeded.

startAudioMixing

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

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	Background music playing times
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	Successful
{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	Successful
{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	Successful
{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	Successful
{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	Successful
{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	Successful
{error: "HAS_NOT_INIT"}	Not initialized

pauseAllAudioMixing

Pause all audio mixing.

pauseAllAudioMixing(): Err | null

Return Values

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

resumeAllAudioMixing

resumeAllAudioMixing(): Err | null

Resume all audio mixing.

Return Values

Common Return Value	Description
null	Successful
{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	Successful
{error: "INVALID_OPERATION"}	Invalid operation

disableAudioLevelReport

disableAudioLevelReport(): Err | null

Disable audio volume reporting.

Return Values

Common Return Value	Description
null	Successful
{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(): Promise<MediaDeviceInfo[]>

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

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

getVideoDevices

static getVideoDevices(): Promise<MediaDeviceInfo[]>

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

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.

Return Values

• Promise of the audio output device information array MediaDeviceInfo.

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

getSignalConnectionState

getSignalConnectionState():string

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

Return Values

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

getMediaConnectionState

getMediaConnectionState(): MediaConnectionState

Get the connection status of the media channel. 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 byte output; an accumulated value
recvBitRate	number; the total audio/video receiving bit rate (kpbs); an instantaneous value; calculated at one-second intervals
recvBytes	number; the total byte input; an accumulated value

getUplinkVideoStats

getUplinkVideoStats(): VideoStats

Get the uplink video stream statistics. Call once video is published and the media channel'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 channel'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 channel's status is "connected”.

Return Values

• VideoStats

getDownlinkAudioStats

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

getDownlinkAudioStats(): AudioStats

Return Values

• AudioStats

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 string

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,
    channel?: 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
channel	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