zego express javascript apis for web

ZEGO Express Javascript APIs for Web

ZEGO Express SDKs provide rich APIs for you to quickly build audio/video calling and

live streaming capabilities into your applications based on ZEGO's cloud live streaming

platform. With a powerful audio/video processing engine and a global real-time network,

the platform is providing high-quality and reliable cloud audio/video streaming services

to businesses around the world.

ZEGO Express SDKs are available for all major platforms, including Android, iOS, Mac,

Windows, and Web.

1 SDK Initialization

1.1 Initialize the SDK

new ZegoExpressEngine(appID, server)

Parameter Description Type Mandatory?

appID The application ID assigned to

your project by ZEGO.

Numeric Yes

server ZEGO Server URL(s). String or Array

of Strings

Yes

1.2 Set up Logging Congurations

zegoExpressEngine.setLogConfig(config)

The config parameter has three properties:


config.logLevel Local log level;

0: debug;

1: info;

2: warn;

3: error;

Numeric No

98: report;

100: disable;

Defaults to 1.

config.remoteLogLevel Remote log level;

0: debug;

1: info;

2: warn;

3: error;

100: disable;

Defaults to 0.

Numeric No

(but recommended)

config.logURL Remote log server URL. String No

1.3 Set up Debugging Mode

zegoExpressEngine.setDebugVerbose(enable)

Whether to enable the verbose debugging mode. If enabled, critical errors will

be prompted in a pop-up window. Defaults to true in development environments.


enable Whether to enable verbose

debugging mode.

Boolean Yes

1.4 System Capability Check

zegoExpressEngine.checkSystemRequirements():Promise<CapabilityDetection>

The CapabilityDetection object has the following properties:

Parameter Description Type

webRTC Whether WebRTC is supported. Boolean

customCapture Whether customized stream publishing is

supported.

Boolean

camera Whether able to access the camera. Boolean

microphone Whether able to access the microphone. Boolean

setLogConfig is an optional method.

videoCodec The supported video codecs. Object

screenSharing Whether screen sharing is supported. Boolean

The videoCodec object has the following properties:


H264 Whether H.264 video encoding is supported. Boolean

VP8 Whether VP8 video encoding is supported. Boolean

1.5 Obtain Media Device Info

zegoExpressEngine.enumDevices(): Promise<DeviceInfo>

The deviceInfo object has the following properties:


microphones List of audio input devices. Array of Objects

speakers List of audio output devices. Array of Objects

cameras List of video input devices. Array of Objects

Each device object in the array has the following properties:


deviceName Device Name. String

deviceID Device ID. String

1.6 Register Event Listeners

Some browsers (e.g. Safari iOS) might get an empty Device Name at the first attempt,

try to call the API again in such cases.

The Device ID obtained by different browsers might not be the same.

This API must be invoked over https protocol.

Some browsers may not be able to obtain the device ID before accessing the camera.

zegoExpressEngine.on(event, callBack)


event The event name to be listend

for.

String Yes

callBack The callback function. Function Yes

1.7 Remove Event Listeners

zegoExpressEngine.off(event)


event Event Name. String Yes

1.8 Get the Current SDK Version

zegoExpressEngine.getVersion()

The retruned value is a string (e.g. "1.1.0")

2 Room

2.1 Log in to a Room

zegoExpressEngine.loginRoom(roomID, token, user, config): Promise<Boolean>


roomID Room ID, a string with a maximum

length of 128 bytes.

String Yes

token Login token. For the generation

and acquisition of token, please

refer to Room Login Security

String Yes

user The current user. Object Yes

Note: event handlers should be registered after the SDK is initialized and before the

API loginRoom is called.

https://doc-en.zego.im/1129.html#6

config Additional login parameters. Object No

The user object has the following properties:


userID User ID, a string with a maximum length of 128

bytes.

String

userName User name, a string with a maximum length of 128

bytes.

String

The config object has the following properties:


userUpdate Whether roomUserUpdate should fire callback;

defaults to false .

Boolean

maxMemberCount Maximum in-room user count; defaults to 0, which

means no limit.

Numeric

2.2 Log out of a Room

zegoExpressEngine.logoutRoom(roomID)

When this API is called, the client will send a logout signal to the ZEGO

server, reset the critical data related to the interaction between the user and

the ZEGO server, and then set null the websocket object.

2.3 Subscribe to Room Connection Status Updates

zegoExpressEngine.on('roomStateUpdate',callBack:

(roomID,state,errorCode,extendedData) => void)


roomID Room ID. String

state Current room connection status: String

Note: The userID must be globally unique within the entire scope of the same AppID.

Otherwise, if there is any new login with the same userID, the currently logged-in

user will be logged out automatically.

'DISCONNECTED'，'CONNECTING'，'CONNECTED'.

errorCode Error Code. Numeric

extendedData Extended data for room connection status update. String

2.4 Subscribe to Updates on Users in a Room

zegoExpressEngine.on('roomUserUpdate',callBack:(roomID, updateType, userList) =>

void)



updateType 'DELETE': users left the room;

'ADD': users entered the room.

String

userList List of users left or entered the room

(depending on updateType)

Array of

Objects

Each user object in the userList has the following properties



bytes.

String

userName User Name, a string with a maximum length of 128

bytes.

String

Please note that this callback will only be called if config.userUpdate is set to

true when logging in to the room.

3 Stream Publishing

3.1 Create a Stream

zegoExpressEngine.createStream(source): Promise<MediaStream>

The source parameter has three options:


camera Capture video from camera. Object No

screen Capture video from screen. Object or

Boolean

No

custom Capture video from third-party

source.

Object No

Notes: the stream source can only be camera , screen , or custom . If not

explicitly specified, camera (with video quality 2) will be used as default

value.

The camera object has the following properties:


audio Whether audio is required;

defaults to true.

Boolean No

audioInput Audio input device; If not

specified, the default device of

the system will be used.

String No

audioBitrate Audio bit rate; defaults to

48kbps.

Numeric No

video Whether video is required. Boolean No

videoInput Video input device; If not

specified, the default device of

the system will be used.

String No

videoQuality Video quality level; defaults to

2.

Numeric No

facingMode Front/Rear camera selection;

'user': front camera;

'environment': rear camera.

String No

horizontal Whether it is landscape video Boolean No

ANS Whether to enable Automatic

Noise Suppression.

Boolean No

AGC Whether to enable Automatic Gain

Control.

Boolean No

AEC Whether to enable Acoustic Echo Boolean No

Cancellation.

The screen object has the following properties:


audio Whether audio is required;

defaults to false .

Boolean No

videoQuality Video quality of screen sharing. Numeric No

Generally speaking, the choice of screen sharing video quality should be determined

according to the actual situation and scene. The videoQuality in screen provides three

preset values:

In addition to the above three preset values, videoQuality also provides a custom value

of 4, which can customize the Frame Rate and Bit Rate. The screen adds two attributes,

frameRate and bitrate . These two attributes need to be passed to the SDK when using a

custom value of 4.

Values of videoQuality of the screen object:

Value Frame Rate Bit Rate

1 20 800K

2 15 1500K

3 5 2000K

4 frameRate bitrate（k）

The custom object has the following properties:


source Third-party source. video object or Yes

1: The Frame Rate is larger, which is suitable for scenes with high fluency

requirements.

2: Suitable for scenes that strike a balance between fluency and clarity.

3: The Bit Rate is larger, which is suitable for scenes with high clarity

requirements.

audio object or

MediaStream object

bitrate Video bitrate. Numeric No

Values of the videoQuality property of the camera object:

Value Resolution Frame Rate Bit Rate

1 240 * 320 15 300K

2 480 * 640 15 800K

3 720 * 1280 20 1500K

4 width * height frameRate bitrate（k）

About the horizontal property：

3.2 Destroy a Stream

zegoExpressEngine.destroyStream(localStream): void


Rendering of a stream can be started by assigning the MediaStream object obtained by

calling the createStream function to the srcObject property of the local video or

audio object.

If audioInput and videoInput are not specified, the default device of the system will

be used.

By default ANS, AGC and AEC are enabled. We recommend keeping them enabled if no

special reason.

If a custom source is specified，it will be used for preview. Currently, this option

is only supported on Chrome 53 (or higher) and Firefox 47 (or higher).

If the videoQuality property of the camera object is 4, the camera object will have 4

more properties ( width , height , frameRate , bitrate ), which also need to be specified

when calling the API.

If the facingMode property is configured, the videoInput property will be ignored.

If the horizontal property is true , width and height will swap.

localStream The MediaStream object returned

by the createStream function.

MediaStream

Object

Yes

3.3 Start Publishing a Stream

zegoExpressEngine.startPublishingStream(streamID, localStream, publishOption):

boolean


streamID Stream ID of the stream to be

published.

String Yes



MediaStream

Object

Yes

publishOption Additonal stream publishing

parameters.

Object No

The publishOption object has the following properties:


streamParams Alternative stream publishing

parameters in the format:

' zg_expired=XX&zg_nonce=XX&zg_token=XX '

Only pass in this parameter when

authentication is required.

String No

extraInfo Addtional stream information. String No

videoCodec Video encoding format for stream

publishing;

Currently only VP8 and H.264 are

supported.

String No

3.4 Stop Publishing a Stream

zegoExpressEngine.stopPublishingStream(streamID): void


Destroying a stream object while the stream is being published will cause the stream

publishing to stop.

streamID Stream ID of the stream you want

to stop playing.

String Yes

If stream publishing is stopped, the video rendering will also stop. You will

need to destroy the local video object accordingly in your program.

3.5 Add a Target CDN URL

zegoExpressEngine.addPublishCdnUrl(streamID, signature, targetURL):

Promise<result>


streamID Stream ID of the stream to be

published to the CDN.

String Yes

signature Signature for authentication.

Signature generation method:

md5(appID + timestamp + secret).

String Yes

targetURL The target CDN url;

Supported formats: rtmp, flv,

hls.

String Yes

The result object has the following properties:


errorCode Error code. Numeric

3.6 Remove a CDN URL

zegoExpressEngine.removePublishCdnUrl(streamID, signature, targetURL):

Promise<result>


Call this API to publish the stream to the specified CDN URL when remote users need

to pull streams from the CDN.

The function for generating the signature need to be implemented separately by the

developers on their business backend; contact ZEGO support to get the secret ;

timestamp is a timestamp in second.

streamID Stream ID of the stream you want

to stop publishing to CDN.

String Yes

signature Signature for authentication.

Signature generation method:

md5(appID + timestamp + appsecret) .

String Yes

targetURL The CDN URL. to be removed;

Supported formats: rtmp, flv,

hls.

String Yes




3.7 Update Extra Information of a Stream

zegoExpressEngine.setStreamExtraInfo(streamID, extraInfo)


streamID Stream ID of the stream being

published.

String Yes

extraInfo Addtional information of the

stream.

String Yes

3.8 Subscribe to Stream Publishing Quality Updates

zegoExpressEngine.on('publishQualityUpdate', callBack:(streamID, stats) => void)


streamID Stream ID. String

stats Stream quality information. Object

Call this API to stop publishing a stream to the specified CDN URL.

The function for generating the signature need to be implemented separately by the

developers on their business backend; contact ZEGO support to get the secret ;

timestamp is a timestamp in second.

The stats object has the following properties:：


video Video quality. Object

audio Audio quality. Object

3.9 Turn On/Off Video

zegoExpressEngine.mutePublishStreamVideo(localStream, mute)


localStream The stream object returned by

the createStream function.

MediaStream

Object

Yes

mute Whether to stop publishing the

local video stream;

true : DO NOT publish the local

video stream;

false : Publish the local video

stream;

Defaults to false .

Boolean Yes

3.10 Turn On/Off Audio

zegoExpressEngine.mutePublishStreamAudio(localStream, mute)




MediaStream

Object

Yes

mute Whether to stop publishing the

local audio stream；

true : DO NOT publish the local

audio stream;

false : Publish the local audio

stream；

Defaults to false .

Boolean Yes

3.11 Use Specified Video Capture Device

zegoExpressEngine.useVideoDevice(localStream, deviceID):Promise




MediaStream

Object

Yes

deviceID Device ID of the video capture

device to be used.

String Yes

3.12 Use Specified Audio Capture Device

zegoExpressEngine.useAudioDevice(localStream, deviceID):Promise




MediaStream

Object

Yes

deviceID Device ID of the audio capture

device to be used.

String Yes

3.13 Subscribe to Stream Publishing Status Updates

zegoExpressEngine.on('publisherStateUpdate', callBack:(result) => void)




state 'NO_PUBLISH'：Stream publishing not yet started;

'PUBLISH_REQUESTING'：Stream publishing being

requested;

'PUBLISHING'：Stream publishing in progress.

Numeric


Changing the video capture device during streaming publishing is supported.

Changing the audio capture device during streaming publishing is supported.

extendedData Extended data for stream publishing status

update.

String

3.14 Subscribe to Screen Sharing Ending Request

zegoExpressEngine.on('screenSharingEnded', callBack:() => void)

3.15 Start Audio Mixing

zegoExpressEngine.startMixingAudio(streamID, mediaList): boolean


streamID The streamID of the stream for

which audio mixing is to be

carried out.

String Yes

mediaList The list of local <audio> or

<video> objects.

Array Yes

3.16 Stop Audio Mixing

zegoExpressEngine.stopMixingAudio(streamID, mediaList): boolean


streamID The streamID of the stream that

is on audio mixing.

String Yes

mediaList The list of <audio> or <video>

objects for which audio mixing

is being carried out.

Array No

When users click to stop screen sharing, an ending request will be triggered.

The operations on the sound effect is done by operating on the <audio> or <video>

object.

Currently not supported by safari.

If no value is passed to mediaList , then audio mixing will be stopped for all media of

the stream.

4 Stream Playing

4.1 Subscribe to Updates on Streams in a Room

zegoExpressEngine.on('roomStreamUpdate', callBack:(roomID，type，streamList) =>

void)



updateType 'DELETE'：stream deleted;

'ADD'：stream added.

String

streamList List of streams deleted or added (depending on

updateType)

Array of

Objects

Each stream in the streamList has the following properties:



user The user associated with the stream. user Object

extraInfo Additional information of the stream. String

urlsFLV FLV playback URL. Array of Strings

urlsRTMP RTMP playback URL. Array of Strings

urlsHLS HLS playback URL. Array of Strings

urlsHttpsFLV HTTPS-FLV playback URL. Array of Strings

urlsHttpsHLS HTTPS-HLS playback URL. Array of Strings

user object has the following properties:


userID User ID of the user who published the stream, a

string with a maximum length of 128 bytes.

String

userName User Name of the user who published the stream,

a string with a maximum length of 128 bytes.

String

4.2 Play a Remote Stream

zegoExpressEngine.startPlayingStream(streamID, playOption):Promise<MediaStream>


streamID Stream ID. String Yes

playOption Stream playing options. Object No

playOption object has the following properties:


video Whether video stream is

required; defaults to true .

Boolean No

audio Whether audio stream is

required; defaults to true .

Boolean No

streamParams Additional stream playing

options in the following format:

' zg_expired=XX&zg_nonce=XX&zg_token=XX '

Only pass in this parameter when

authentication is required;

String No

videoCodec The video codec to be used for

stream playing;

Values: 'VP8' or 'H264';

Defaults to 'H264'.

String No

4.3 Subscribe to Stream Playing Quality Updates

zegoExpressEngine.on('playQualityUpdate', callBack:(streamID，stats) => void)



In live audio/video broadcasting, if there are only one host publishing streamings,

the audience needs to pull the streams from CDN.

It is recommended NOT to explicitly specify the value for the parameters video and

audio . The SDK will determine whether to pull the video or audio stream based on the

related device status.

stats Stream quality. Object

The stats object has the following properties:


video Video quality. Object

audio Audio quality. Object

4.4 Stop Playing a Stream

zegoExpressEngine.stopPlayingStream(streamID): void


streamID Stream ID. String Yes

4.5 Subscribe to Stream Extra Information Updates

zegoExpressEngine.on('streamExtraInfoUpdate', callBack:(roomID，streamList) =>

void)



streamList List of streams with updates. Array of Objects

Each stream in the streamList has the following properties：



user The user who is publishing the stream. user Object

extraInfo Additional information of the stream. String

The user object has the following properties:


userID User ID of the user who published the stream, a String

string with a maximum length of 128 bytes.

userName User Name of the user who published the stream,

a string with a maximum length of 128 bytes.

String

4.6 Subscribe to Steam Playing Status Updates

zegoExpressEngine.on('playerStateUpdate', callBack:(result) => void)




state 'NO_PLAY'：stream playing not yet started

'PLAY_REQUESTING'：requesting to start stream

playing

'PLAYING'：stream playing in progress

Numeric

errorCode Error Code. Numeric

extendedData Extended data for stream playing status update. String

4.7 Subscribe to Remote Camera's Status Updates

zegoExpressEngine.on('remoteCameraStatusUpdate', callBack:(streamID, status) =>

void)



status 'OPEN': the camra on the remote side is on;

'MUTE': the camera on the remote side is off.

String

4.8 Subscribe to Remote Microphone's Status Updates

zegoExpressEngine.on('remoteMicStatusUpdate', callBack:(streamID, status) =>

void)



status 'OPEN': the microphone on the remote side is on;

'MUTE': the microphone on the remote side is

off.

String

4.9 Set up the Sound Level Update Callback

ZegoClient.setSoundLevelDelegate(boolean, interval)


boolean Wheter to enable the sound level

update callback.

Boolean Yes

interval The interval of the sound level

update callback (if enabled).

Defaults to 1000ms.

Numeric No

4.10 Subscribe to Sound Level Updates

zegoExpressEngine.on('soundLevelUpdate', callBack:(soundLevelList) => void)


soundLevelList List of sound level values Array of Objects

Each object in the soundLevelList has the following properties:



soundLevel Sound level value: [0-100] Numeric

type Streaming type: 'push' or 'pull'. String

5 Stream Mixing

The value of Sound Level can be obtained from the callback soundLevelUpdate when it is

enabled.

Currently, this API is not supported by safari.

5.1 Start Stream Mixing

zegoExpressEngine.startMixerTask(mixStreamConfig):Promise<result>

The mixStramConfig object has the following properties:


taskID Stream mixing task Id, which should be defined

by user and must be unique for each task.

String

inputList List of input streams; cannot be empty. Arrary

outputList List of output streams; Each element in the

outputList can be a String (stream ID or stream

url) or an target Object.

Array

outputConfig Output stream configurations. Object

Each stream in the inputList has the following properties:


streamID Stream ID of the input stream. String

contentType Stream mixing content type;

'VIDEO': video and audio;

'AUDIO': pure audio;

Defaults to 'VIDEO'.

String

layout Output stream layout. Object

The layout object has the following properties:：


top The top coordinate of the target position. Numeric >=0

left The left coordinate of the target position. Numeric >= 0

bottom The bottom coordinate of the target position. Numeric >= 0

right The right coordinate of the target position. Numeric >= 0

top , left , bottom , and right must be integers

Each output stream object in the outputList has the following properties:


target Stream ID or url of the output stream. String

The outputConfig object has the following properties:


outputBitrate Bitrate of the output

stream (kbps); must > 0.

Numeric Yes

outputFPS Frame rate of the output

stream (fps); must > 0.

Numeric Yes

outputWidth Width of the output stream;

must > 0.

Numeric Yes

outputHeight Height of the output

stream; must > 0.

Numeric Yes

outputAudioCodecID Audio codec of the output

stream;

0：HE_AAC;

1：AAC_LC;

2：MP3;

Defaults to 0.

Numeric No

outputAudioBitrate Audio bitrate of the output

stream (kbps).

Numeric No

outputAudioChannels Number of audio channels of

the output stream.

Numeric No




extendedData Extended data for stream mixing. String

5.2 Advanced Stream Mixing Configurations

zegoExpressEngine.setMixerTaskConfig(config):void

The config object has the following properties:


backgroundColor Background color of the output

stream, an hex value of RGB

colors in the format 0xRRGGBBxx .

Numeric No

backgroundImage Background image of the output

stream;

The corresponding imageID must

be preconfigured in ZEGO

backend in the format: preset-

id://xxx .

String No

videoCodec Video codec of the output

stream ;

Values: 'vp8' or ' h264';

Defaults to 'h264'.

String No

5.3 Stop Stream Mixing

zegoExpressEngine.stopMixerTask(taskID):Promise<result>


taskID Stream mixing task ID, which is

user-defined and must be unique

for each task.

String Yes




6 Instant Messaging

This is an optional method. To take effect, it needs to be called before calling

startMixerTask .

6.1 Send Broadcast Messages to a Room

zegoExpressEngine.sendBroadcastMessage(roomID, message):Promise<result>


message Message content，a string with a

maximum length of 1024 bytes.

String Yes




messageID Message content. Numeric

6.2 Subscribe to In-Room Broadcast Messages

zegoExpressEngine.on('IMRecvBroadcastMessage', (roomID, ZegoMessageInfo[]) =>

void)



ZegoMessageInfo Message Object. Object

The ZegoMessageInfo object has the following properties:


fromUser Message sender. user Object

message Message content. String

sendTime Time message sent. Numeric

messageID Message ID. Numeric

The fromUser object has the following properties:


userID User ID, a string with a maximum length of 128 String

bytes.


bytes.

String

6.3 Send In-room Barrage Messages (Bullet Screen)

zegoExpressEngine.sendBarrageMessage(roomID, message):Promise<result>


message Message content，a string with a

maximum length of 1024 bytes.

String Yes




messageID Message content. Numeric

6.4 Subscribe to In-room Barrage Messages (Bullet Screen)

zegoExpressEngine.on('IMRecvBarrageMessage', (roomID, ZegoMessageInfo[]) =>

void)



ZegoMessageInfo Message object. Object

The ZegoMessageInfo object has the following properties:



message Message content. String

sendTime Time message sent. Numeric

messageID Message ID. String




bytes.

String


bytes.

String

6.5 Send In-Room Custom Signaling Messages

zegoExpressEngine.sendCustomCommand(roomID, command,

toUserIDList):Promise<result>


roomID Room ID. String Yes

command Message content, a string with a

maximum length of 1024 bytes, or

an object with a maximum size of

1024 bytes.

String or

object

Yes

toUserIDList List of message recipients; If

the message is for all users in

the room, set the array to be

empty.

Array of

Strings

Yes




6.6 Subscribe to Custom Signaling Messages

zg.on('IMRecvCustomCommand', (roomID,fromUser,command) => void)




command Message content. String




bytes.

String


bytes.

String

zego express javascript apis for web

Documents