Functional APIs

API List

APIDescription
new WebRTCCreate a WebRTC object
initInitialize
isSupportedCheck whether the browser supports Jocloud Web SDKs
getSupportedCodecGet the supported code
isScreenShareSupportedDetermine whether screen sharing is supported
VERSIONVersion number
onAdd event bindings
offCancel event bindings
joinRoomJoin a channel
leaveRoomLeave a channel
setAreaSet the user region
updateTokenUpdate a token
createStreamCreate audio/video streams
closeStreamComplete audio/video streams
publishPublish audio/video streams
unpublishStop publishing audio/video streams
setPublisherVolumeSet the microphone volume
setVideoModeSet local video stream brackets
changeDeviceChange input devices
subscribeSubscribe to audio/video streams
unsubscribeUnsubscribe to audio/video streams
playPlay the stream
stopPlayStop playing the stream
resumeResume playing the stream
isPlayingDetermine whether the stream is playing
setAudioVolumeSet the playing volume
setAudioOutputDeviceSelect the playing device
hasAudioDetermine whether there is an audio
hasVideoDetermine whether there is a video
enableAudioOpen an audio
disableAudioClose an audio
enableVideoOpen a video
disableVideoClose a video
addPublishOriginStreamUrlAdd the address of a source stream pushing to CDN
removePublishOriginStreamUrlRemove the address of a source stream pushing to CDN
addPublishTranscodingStreamUrlAdd the address of a mixed stream pushing to CDN
removePublishTranscodingStreamUrlRemove the address of a mixed stream pushing to CDN
setLiveTranscodingTaskSet a stream mixing task
removeLiveTranscodingTaskRemove a stream mixing task
addSubscribeSubscribe across rooms
removeSubscribeCancel the cross-room subscription
createDualStreamCreate dual-channel video stream
changeRemoteVideoStreamTypeSelect high/low quality streams
startAudioMixingStart audio mixing
stopAudioMixingStop audio mixing
pauseAudioMixingPause audio mixing
resumeAudioMixingResume audio mixing
setAudioMixingVolumeSet the audio mixing volume
getAudioMixingDurationGet the total duration of audio mixing
getAudioMixingTimeGet the current audio mixing time
setAudioMixingTimeSet the audio mixing time
stopAllAudioMixingStop all audio mixing
pauseAllAudioMixingPause all audio mixing
resumeAllAudioMixingResume all audio mixing
getPublisherAudioLevelGet the current output stream volume
getSubscriberAudioLevelGet the current subscribed stream volume
enableAudioLevelReportEnable audio volume reporting
disableAudioLevelReportDisable audio volume reporting
getDevicesGet all audio/video devices
getAudioDevicesGet audio input devices such as microphones
getVideoDevicesGet video input devices such as cameras
getPlayoutDevicesGet playing devices
getSystemStatsGet the system information
getSignalConnectionStateGet the connection status of the signaling channel
getMediaConnectionStateGet the connection status of the media channel
getSessionStatsGet the session-level connection statistics
getUplinkVideoStatsGet the uplink video stream statistics
getUplinkAudioStatsGet the uplink audio stream statistics
getDownlinkVideoStatsGet the downlink video stream statistics
getDownlinkAudioStatsGet the downlink audio stream statistics
setLogLevelSet the log level

Details

WebRTC

new WebRTC(config?: WebRTCConfig)

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

Parameter

ParameterDescription
configWebRTCConfig configuration object
WebRTCConfig
interface WebRTCConfig {
    codec?: 'H264' | 'VP8';
}
ProfileDescription
codecThe 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

ParameterDescription
appidService application ID

Return

Common Return ValueDescription
nullSuccessful
{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

ParameterDescription
roomParamRoom information
RoomParam
interface RoomParam {
    uid: string;
    roomId: string;
    token?: string;
    mode?: number;
}
ProfileDescription
uidUser ID [only supports a combination of the characters [A,Z],[a,z],[0,9],-,_, not to exceed 64 bytes in length]
roomIdRoom ID (unique) [only supports a combination of the characters [A,Z],[a,z],[0,9],-,_, not to exceed 64 bytes in length]
tokenSee details in [Authentication Access Manual]
mode0: 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 ErrorDescription
{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
ParameterDescription
audioArrays of the supported audio/video codes
videoArrays 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
ParameterDescription
systemSystem version
browserBrowser version
batteryBattery 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

ParameterDescription
eventEvent name
listenerCallback function

off

off(event: string, listener: any)

Cancel event bindings

Parameters

ParameterDescription
eventName of the previously bound events
listenerCallback of the previously bound events

leaveRoom

leaveRoom(): Err | null

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

Return Values

Common Return ValueDescription
nullSucceeded
{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

ParameterDescription
oversea0: default (domestic), 1: overseas

Return Values

Common Return ValueDescription
nullSucceeded
{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

ParameterDescription
tokenThe token for update

Return Values

Common Return ValueDescription
nullSucceeded
{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

ParameterDescription
paramMediaStreamParam Create a parameter object of the local stream
MediaStreamParam
interface MediaStreamParam {
    audio?: {
        deviceId?: string;
    } | boolean,
    video?: {
        deviceId?: string;
        videoMode: number;
    },
    playType?: 1 | 2;
}
ProfileDescription
audioEnable the audio stream, which can be a Boolean value or built-in parameters; if not entered, indicate that the audio stream is not enabled.
videoEnable the video stream, which can be a built-in parameter; if not entered, indicate that the video stream is not enabled.
playTypeOptional 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

ProfileDescription
deviceIdAudio publishing device ID. If not entered, select default

The built-in parameters of video

ProfileDescription
videoModeVideo bracket is required. See details in the Video Bracket Information Table
deviceIdVideo 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.

videModeBracketResolutionFrame RateBit Rate
1Smooth320 x 24015200 K
2Standard definition640 x 48015500 K
3High definition960 x 544241000 K
4Ultra-high definition1280 x 720241600 K
5Blu-ray1920 x 1080244500 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 ErrorDescription
{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 ValueDescription
nullSucceeded
{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 ErrorDescription
{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 ValueDescription
nullSucceeded
{error: "HAS_NOT_PUBLISH"}Stream not published

setPublisherVolume

setPublisherVolume(volume: any): Err | null

Set the microphone volume.

Note:

Parameters

ParameterDescription
volumeThe microphone volume range [0-100]. 0: mute; 100 (default): maximum

Return Values

Common Return ValueDescription
nullSucceeded
{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

ParameterDescription
videoModeVideo 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 ErrorDescription
{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

ParameterDescription
kindNote: 'audio’ or 'video'; 'audio’ indicates switching the microphone device and 'video’ indicates switching the camera device.
deviceIdThe 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 ErrorDescription
{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

ParameterDescription
remoteStreamremote_stream_add The remote stream reported RemoteStream
optionOptional subscription parameters SubscribeOption
SubscribeOption
interface SubscribeOption {
    audio: boolean,
    video: boolean,
    lowStream?: boolean,
}
ProfileDescription
audioBoolean value, whether to subscribe to the audio
videoBoolean value, whether to subscribe to the video
lowStreamOptional, whether to subscribe to the low quality stream by default

Return Values

Common Promise ErrorDescription
{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

ParameterDescription
remoteStreamThe remote stream reported by remote_stream_add RemoteStream

Return Values

  • Promise; successful asynchronous execution indicates the subscription canceled.
Common Promise ErrorDescription
{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

ParameterDescription
uidThe user ID of the local or subscribed stream
elementSelect the HTMLElement or ID of playing
optionOptional playing parameters PlayOption
PlayOption
interface PlayOption {
    muted?: boolean,
    fit?: 'cover' | 'contain' | 'fill',
    mirror?: boolean,
    controls?: boolean,
}
ProfileDescription
mutedOptional, whether to mute play; the local stream is muted by default
fitOptional 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.
mirrorOptional, whether to play in mirror
controlsOptional, whether to display the control bar of the video tag

Return Values

  • Promise; successful asynchronous execution indicates playing completed.
Common Promise ErrorDescription
{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

ParameterDescription
uidThe user ID of the local or subscribed stream

Return Values

Common Return ValueDescription
nullSucceeded
{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

ParameterDescription
uidThe 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

ParameterDescription
uidThe 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

ParameterDescription
uidThe user ID of the local or subscribed stream
volumeRange: 0-100

Return Values

Common Return ValueDescription
nullSucceeded
{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

ParameterDescription
uidThe user ID of the local or subscribed stream
deviceIdAudio output device ID

Return Values

  • Promise; successful asynchronous execution indicates calling succeeded.
Common Promise ErrorDescription
{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

ParameterDescription
uidThe 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

ParameterDescription
uidThe 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

ParameterDescription
uidThe user ID of the local or subscribed stream. If not entered, the local stream is operated by default.

Return Values

Common Return ValueDescription
nullSucceeded
{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

ParameterDescription
uidThe user ID of the local or subscribed stream. If not entered, the local stream is operated by default.

Return Values

Common Return ValueDescription
nullSucceeded
{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

ParameterDescription
uidThe user ID of the local or subscribed stream. If not entered, the local stream is operated by default.

Return Values

Common Return ValueDescription
nullSucceeded
{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

ParameterDescription
uidThe user ID of the local or subscribed stream. If not entered, the local stream is operated by default.

Return Values

Common Return ValueDescription
nullSucceeded
{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

ParameterDescription
urlCDN stream pushing addresses are in RTMP format. The characters cannot exceed 512 bytes in length

Return Values

Common Return ValueDescription
nullSucceeded
{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

ParameterDescription
urlCDN stream pushing addresses are in a RTMP format. The characters cannot exceed 512 bytes in length

Return Values

Common Return ValueDescription
nullSucceeded
{error: "INVALID_URL"}Invalid URL
{error: "NOT_SUPPORTED_IN_GROUP_MODE"}Group mode not supported

addPublishTranscodingStreamUrl

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

Parameters

ParameterDescription
taskIdTask ID [only supports a combination of the characters [A,Z],[a,z],[0,9],-,_, not to exceed 64 bytes in length]
urlCDN stream pushing addresses are in RTMP format. The characters cannot exceed 512 bytes in length

Return Values

Common Return ValueDescription
nullSucceeded
{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

ParameterDescription
taskIdTask ID [only supports a combination of the characters [A,Z],[a,z],[0,9],-,_, not to exceed 64 bytes in length]
urlCDN stream pushing addresses are in RTMP format. The characters cannot exceed 512 bytes in length

Return Values

Common Return ValueDescription
nullSucceeded
{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

ParameterDescription
taskIdStream mixing task [only supports a combination of the characters [A,Z],[a,z],[0,9],-,_, not to exceed 64 bytes in length]
transcodingFor 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:

BracketResolutionBit RateFrame Rate
1320 x 180200 kbps15 fps
2320 x 240200 kbps15 fps
3640 x 360400 kbps15 fps
4640 x 480600 kbps15 fps
5960 x 5441000 kbps24 fps
61280 x 7201600 kbps24 fps
71920 x 10804500 kbps24 fps

Return Values

Common Return ValueDescription
nullSuccessful
{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

ParameterDescription
taskIdStream mixing task ID is generated by the application. It must be unique in the entire domain

Return Values

Common Return ValueDescription
nullSuccessful
{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

ParameterDescription
roomIdRoom ID [only supports a combination of the characters [A,Z],[a,z],[0,9],-,_, not to exceed 64 bytes in length]
uidUser 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 ValueDescription
nullSuccessful
{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

ParameterDescription
roomIdRoom ID [only supports a combination of the characters [A,Z],[a,z],[0,9],-,_, not to exceed 64 bytes in length]
uidUser 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 ValueDescription
nullSuccessful
{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

ParameterDescription
paramHigh/low quality stream parameter DualStreamParam
DualStreamParam
interface DualStreamParam {
    audio?: {
        deviceId?: string;
    } | boolean;
    video: {
        highVideoMode: number;
        lowVideoMode: number;
        deviceId?: string;
    };
    playType?: 1 | 2;
}
ProfileDescription
audioEnable 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.
videoEnable the video stream, which can be a built-in parameter; if not entered, indicate that the video stream is not enabled.
playTypeOptional 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

ProfileDescription
deviceIdaudio publishing device ID. If blank, select default

The built-in parameters of video

ProfileDescription
highVideoModeThe high quality video bracket is required. See details in the Video Bracket Information Table
lowVideoModeThe low quality video mode is required. The low quality video has lower resolution. See details in the Video Bracket Information Table
deviceIdVideo publishing device ID. If not entered, select default

Return Values

  • LocalStream Promise; successful asynchronous return indicates the high/low quality stream created.
Common Promise ErrorDescription
{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

ParameterDescription
speakerUidAnchor ID
videoStreamType0: 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

ParameterDescription
paramAudioMixingParam
idMixed 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;
}
ProfileDescription
localWhether to select the local file.
urlBackground music playing times
loopWhether to play the background music on loop. Conflicted with cycle.
playTimeThe start time of playing music (ms).
replaceWhether 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.
extraPlayWhether 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 ErrorDescription
{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

ProfileDescription
idMixed audio ID; default=0

Return Values

Common Return ValueDescription
nullSuccessful
{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

ProfileDescription
idMixed audio ID; default=0

Return Values

Common Return ValueDescription
nullSuccessful
{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

ProfileDescription
idMixed audio ID; default=0

Return Values

Common Return ValueDescription
nullSuccessful
{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

ParameterDescription
volumeVolume; value range [0,100]; default=100
idMixed audio ID; default=0

Return Values

Common Return ValueDescription
nullSuccessful
{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

ProfileDescription
idMixed 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

ProfileDescription
idMixed 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

ParameterDescription
timePlaying time (s)
idMixed audio ID; default=0

Return Values

Common Return ValueDescription
nullSuccessful
{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 ValueDescription
nullSuccessful
{error: "HAS_NOT_INIT"}Not initialized

pauseAllAudioMixing

Pause all audio mixing.

pauseAllAudioMixing(): Err | null

Return Values

Common Return ValueDescription
nullSuccessful
{error: "HAS_NOT_INIT"}Not initialized

resumeAllAudioMixing

resumeAllAudioMixing(): Err | null

Resume all audio mixing.

Return Values

Common Return ValueDescription
nullSuccessful
{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

ParameterDescription
uidSubscription 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 ValueDescription
nullSuccessful
{error: "INVALID_OPERATION"}Invalid operation

disableAudioLevelReport

disableAudioLevelReport(): Err | null

Disable audio volume reporting.

Return Values

Common Return ValueDescription
nullSuccessful
{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

Common Promise ErrorDescription
{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

Common Promise ErrorDescription
{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

Common Promise ErrorDescription
{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

Common Promise ErrorDescription
{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
interface MediaConnectionState {
    result?: {
        uplinkStateMap: Map<string, string>,
        downlinkStateMap: Map<string, string>
    };
    err?: Err;
}
ProfileDescription
resultContain the map structures of uplinkStateMap and downlinkStateMap; key is [uid: string], value is [connection state:string]
errCalling error

getSessionStats

getSessionStats(): SessionStats

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

Return Values

SessionStats
interface SessionStats {
    result?: {
        sendBitRate: number;
        sendBytes: number;
        recvBitRate: number;
        recvBytes: number;
    };
    err?: Err;
}
ProfileDescription
resultSee details in the table below
errCalling error

result contents:

ProfileDescription
sendBitRatenumber; the total audio/video output bit rate (kpbs); an instantaneous value; calculated at one-second intervals
sendBytesnumber; the total byte output; an accumulated value
recvBitRatenumber; the total audio/video receiving bit rate (kpbs); an instantaneous value; calculated at one-second intervals
recvBytesnumber; 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
interface VideoStats {
    result?: Map<string, VideoStatsItem>;
    err?: Err;
}
ProfileDescription
resultMap structure; key is uid, value is VideoStatsItem
errCalling error
VideoStatsItem
interface VideoStatsItem {
    time: string;
    rtt: string;
    networkScore: string;
    videoCodec: string;
    videoMuteState?: string;
    videoResolution: string;
    videoFrameRate: string;
    videoBitRate: string;
    videoLostRate: string;
}
ProfileDescription
timestring; status capture's system timestamp
rttstring; RTT (Round-Trip Time) from the SDK to the media server (ms)
networkScorestring; the network quality score. Refer to network_score for the definition
videoCodecstring; the video encoding/decoding type, "H264" or "VP8"
videoMuteStatestring; whether the video transmission display is disabled; true=disabled, false=enabled
videoResolutionstring; the video resolution (width x height), e.g. 640 x 480
videoFrameRatestring; the video frame rate (fps); an instantaneous value; calculated at one-second intervals
videoBitRatestring; the video bit rate (kpbs); an instantaneous value; calculated at one-second intervals
videoLostRatestring; 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
interface UplinkAudioStats {
    result?: Map<string, AudioStatsItem>;
    err?: Err;
}
ProfileDescription
resultMap structure; key is uid, value is AudioStats
errCalling error
AudioStatsItem
interface AudioStatsItem {
    time: string;
    rtt: string;
    networkScore: string;
    audioCodec: string;
    audioMuteState?: string;
    audioLevel: string;
    audioBitRate: string;
    audioLostRate: string;
}
ProfileDescription
timestring; status capture's system timestamp
rttstring; RTT (Round-Trip Time) from the SDK to the media server (ms)
networkScorestring; the network quality score. Refer to network_score for the definition
audioCodecstring; the audio encoding/decoding type; currently only supports "opus"
audioMuteStatestring; whether the audio is muted, true= muted, false=unmuted
audioLevelstring; the audio volume level, range[[0,100]]
audioBitRatestring; the audio bit rate (kpbs); an instantaneous value; calculated at one-second intervals
audioLostRatestring; 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

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

setLogLevel

static setLogLevel(level: number): Err | null

Set the log level.

Parameters

ProfileDescription
levelLog 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.

ParameterDescription
errorError message string

LocalStream

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

The local stream information.

ProfileDescription
uidAnchor ID
roomIdID of the room joined
streamRaw audio/video data streams
audioAudiostream parameter indicating that the local stream contains audio
videoVideostream parameter indicating that the local stream contains video

RemoteStream

interface RemoteStream {
    uid: string, roomId: string,
    stream?: MediaStream,
    audio?: StreamParam,
    video?: StreamParam,
    hasLowVideo?: boolean,
}
ProfileDescription
uidThe user ID of the subscribed remote stream
roomIdThe room ID of the remote stream
streamRaw audio/video data streams
audioAudio stream parameter indicating that the remote stream contains audio
videoVideo stream parameter indicating that the remote stream contains video
hasLowVideoWhether 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

ProfileDescription
widthVideo width
heightVideo height
bitrateVideo bit rate
frameRateVideo frame rate
codecCode
sampleRateAudio sampling rate
channelNumber of the audio channels

MediaDeviceInfo

interface MediaDeviceInfo {
    readonly deviceId: string;
    readonly groupId: string;
    readonly kind: MediaDeviceKind;
    readonly label: string;
}
ProfileDescription
deviceIdDevice ID
groupIdGroup ID
kindDevice type
labelDevice tag

Was this page helpful?

Helpful Not helpful
Submitted! Your feedback would help us improve the website.
Feedback
Top
<