Client | Agora Web SDK API Reference v2.4.1

The Client object returned by the createClient method provides access to much of the core AgoraRTC functionality.

Hierarchy

Client

Methods

configPublisher

configPublisher(width: number, height: number, framerate: number, bitrate: number, publisherUrl: string): void

Configure the CDN Live Streaming

DEPRECATED

Agora recommends using the following methods instead:
This method configures the CDN live streaming before joining a channel.

Note:
- To use the functions of Live Broadcast 1.0, use the configPublisher method before Client.join.
- To use the functions of Live Broadcast 2.0, use the startLiveStreaming and setLiveTranscoding methods after createStream. For details, see Advanced: Pushing Streams to the CDN.
example
Sample Code
```
client.configPublisher({
  width: 360,
  height: 640,
  framerate: 30,
  bitrate: 500,
  publishUrl: "rtmp://xxx/xxx/"
});
```
Parameters
- width: number
  
  Width of the output data stream set for CDN Live, 360 is the default value.
- height: number
  
  Height of the output data stream set for CDN Live, 640 is the default value.
- framerate: number
  
  Frame rate of the output data stream set for CDN Live, 15 fps is the default value.
- bitrate: number
  
  Bitrate of the output data stream set for CDN Live, 500 kbps is the default value.
- publisherUrl: string
  
  The push-stream address for the picture-in-picture layouts, null is the default value.
Returns void

disableDualStream

disableDualStream(onSuccess: function, onFailure: function): void

Disable Dual Streams

This method disables dual streams.
example
Sample Code
```
client.disableDualStream(function() {
  console.log("Disable dual stream success!")
}, function(err) {
  console.log(err)
})
```
Parameters
- onSuccess: function
  
  The callback when the method succeeds.
  - - (): void
    - Returns void
- onFailure: function
  
  The callback when the method fails.
  - - (err: any): void
    - Parameters
      - err: any
      Returns void
Returns void

enableAudioVolumeIndicator

enableAudioVolumeIndicator(): void

Enable Volume Indicator

This method enables the SDK to report the active speakers and their volume regularly.

If this method is enabled, the SDK will return the volumes every two seconds, regardless of whether there are active speakers.

Note:
- Agora recommends enabling DTX at the same time, see StreamSpec.audioProcessing.
- If you have mutiple web pages running the Web SDK, this function might not work.
example
Sample Code
```
client.enableAudioVolumeIndicator(); // Triggers the "volume-indicator" callback event every two seconds.
client.on("volume-indicator", function(evt){
    evt.attr.forEach(function(volume, index){
            console.log(#{index} UID ${volume.uid} Level ${volume.level});
    });
});
```
Returns void

enableDualStream

enableDualStream(onSuccess: function, onFailure: function): void

Enable Dual Stream

This method enables the dual-stream mode on the publisher side.

Dual streams are a hybrid of a high-video stream and a low-video stream:
- High-video stream: high bitrate, high resolution
- Low-video stream: low bitrate, low resolution
example
Sample Code
```
client.enableDualStream(function() {
  console.log("Enable dual stream success!")
}, function(err) {
  console,log(err)
})
```
Note:

This method does not apply to the following scenarios:
- Audio-only mode (audio: true, video: false)
- Safari browsers
- Screen-sharing scenario
Parameters
- onSuccess: function
  
  The callback when the method succeeds.
  - - (): void
    - Returns void
- onFailure: function
  
  The callback when the method fails.
  - - (err: any): void
    - Parameters
      - err: any
      Returns void
Returns void

init

init(appId: string, onSuccess: function, onFailure: function): void

Initialize a Client Object

This method initializes the client object.
example
Sample Code
```
client.init(appId, function() {
    console.log("client initialized");
    // Join a channel
    //……
}, function(err) {
    console.log("client init failed ", err);
    // Error handling
});
```
Parameters
- appId: string
  
  Pass in the App ID for your project. To get your App ID, see Get an App ID.
- onSuccess: function
  
  The callback when the method succeeds.
  - - (): void
    - Returns void
- onFailure: function
  
  The callback when the method fails.
  - - (err: string): void
    - Parameters
      - err: string
      Returns void
Returns void

join

join(tokenOrKey: string, channel: string, uid: number, onSuccess: function, onFailure: function): void

Join an AgoraRTC Channel

This method joins an AgoraRTC channel.
example
Sample Code
```
client.join(<token>, "1024", null, function(uid) {
    console.log("client" + uid + "joined channel");
    // Create a local stream
    //……
}, function(err) {
    console.error("client join failed ", err);
    // Error handling
});
```
Parameters
- tokenOrKey: string
  - Low security requirements: Pass null as the parameter value.
  - High security requirements: Pass the string of the Token or Channel Key as the parameter value. See Security Keys for details.
- channel: string
  
  A string that provides a unique channel name for the Agora session. The length must be within 64 bytes. The supported characters: a-z,A-Z,0-9,space,! #$%&,()+, -,:;<=.#$%&,()+,-,:;<=.,>?@[],^_,{|},~
- uid: number
  
  The user ID. Ensure that this integer is unique. If you set the uid to null, the server assigns one and returns it in the onSuccess callback.
- onSuccess: function
  
  The callback when the method succeeds. The server returns the uid which represents the identity of the user.
  - - (uid: number): void
    - Parameters
      - uid: number
      Returns void
- onFailure: function
  
  The callback when the method fails.
  - - (err: any): void
    - Parameters
      - err: any
      Returns void
Returns void

leave

leave(onSuccess: function, onFailure: function): void

Leave an AgoraRTC Channel

This method enables a user to leave a channel.
example
Sample Code
```
client.leave(function() {
    console.log("client leaves channel");
    //……
}, function(err) {
    console.log("client leave failed ", err);
    //error handling
});
```
Parameters
- onSuccess: function
  
  The callback when the method succeeds.
  - - (): void
    - Returns void
- onFailure: function
  
  The callback when the method fails.
  - - (err: any): void
    - Parameters
      - err: any
      Returns void
Returns void

on

on(event: "stream-published", callback: function): void
on(event: "stream-added", callback: function): void
on(event: "stream-removed", callback: function): void
on(event: "stream-subscribed", callback: function): void
on(event: "peer-leave", callback: function): void
on(event: "mute-audio", callback: function): void
on(event: "unmute-audio", callback: function): void
on(event: "mute-video", callback: function): void
on(event: "unmute-video", callback: function): void
on(event: "client-banned", callback: function): void
on(event: "active-speaker", callback: function): void
on(event: "volume-indicator", callback: function): void
on(event: "liveStreamingStarted", callback: function): void
on(event: "liveStreamingFailed", callback: function): void
on(event: "lliveStreamingStopped", callback: function): void
on(event: "liveTranscodingUpdated", callback: function): void
on(event: "onTokenPrivilegeWillExpire", callback: function): void
on(event: "onTokenPrivilegeDidExpire", callback: function): void
on(event: "error", callback: function): void

This callback notifies the application that the local stream has been published.
example
Sample Code
```
client.on("stream-published", function(evt) {
    console.log("local stream published");
    //……
})
```
Parameters
- event: "stream-published"
- callback: function
  - - (evt: any): void
    - Parameters
      - evt: any
      Returns void
Returns void

This callback notifies the application that the remote stream has been added.

example

Sample Code

client.on("stream-added", function(evt) {
    var stream = evt.stream;
    console.log("new stream added ", stream.getId());
    // Subscribe the stream.
    //……
})

Parameters

event: "stream-added"
callback: function
- - (evt: any): void
  - Parameters
    - evt: any
    Returns void

Returns void

This callback notifies the application that the remote stream has been removed; for example, a peer user has called Client.unpublish.
example
Sample Code
```
client.on("stream-removed", function(evt) {
    var stream = evt.stream;
    console.log("remote stream was removed", stream.getId());
    //……
});
```
Parameters
- event: "stream-removed"
- callback: function
  - - (evt: any): void
    - Parameters
      - evt: any
      Returns void
Returns void
This callback notifies the application that a user has subscribed to a remote stream.
example
Sample Code
```
client.on("stream-subscribed", function(evt) {
    var stream = evt.stream;
    console.log("new stream subscribed ", stream.getId());
    // Play the stream.
    //……
})
```
Parameters
- event: "stream-subscribed"
- callback: function
  - - (evt: any): void
    - Parameters
      - evt: any
      Returns void
Returns void
This callback notifies the application that the peer user has left the channel; for example, the peer user has called Client.leave.
example
Sample Code
```
client.on("peer-leave", function(evt) {
    var uid = evt.uid;
    console.log("remote user left ", uid);
    //……
});
```
Parameters
- event: "peer-leave"
- callback: function
  - - (evt: any): void
    - Parameters
      - evt: any
      Returns void
Returns void
This callback notifies the application that the peer user has muted the audio.
example
Sample Code
```
client.on("mute-audio", function(evt) {
  var uid = evt.uid;
  console.log("mute audio:" + uid);
  //alert("mute audio:" + uid);
});
```
Parameters
- event: "mute-audio"
- callback: function
  - - (evt: any): void
    - Parameters
      - evt: any
      Returns void
Returns void
This callback notifies the application that the peer user has unmuted the audio.
example
Sample Code
```
client.on("unmute-audio", function (evt) {
  var uid = evt.uid;
  console.log("unmute audio:" + uid);
});
```
Parameters
- event: "unmute-audio"
- callback: function
  - - (evt: any): void
    - Parameters
      - evt: any
      Returns void
Returns void
This callback notifies the application that the peer user has turned off the video.
example
Sample Code
```
client.on("mute-video", function (evt) {
  var uid = evt.uid;
  console.log("mute video" + uid);
  //alert("mute video:" + uid);
})
```
Parameters
- event: "mute-video"
- callback: function
  - - (evt: any): void
    - Parameters
      - evt: any
      Returns void
Returns void
This callback notifies the application that the peer user has turned on the video.
example
Sample Code
```
client.on("unmute-video", function (evt) {
  var uid = evt.uid;
  console.log("unmute video:" + uid);
})
```
Parameters
- event: "unmute-video"
- callback: function
  - - (evt: any): void
    - Parameters
      - evt: any
      Returns void
Returns void
This callback notifies the peer user that he/she has been banned from the channel. Only the banned users receive this callback.
example
Sample Code
```
client.on("client-banned", function (evt) {
   var uid = evt.uid;
   var attr = evt.attr;
   console.log(" user banned:" + uid + ", banntype:" + attr);
   alert(" user banned:" + uid + ", banntype:" + attr);
});
```
Parameters
- event: "client-banned"
- callback: function
  - - (evt: any): void
    - Parameters
      - evt: any
      Returns void
Returns void
This callback notifies the application who is the active speaker in the channel.
example
Sample Code
```
client.on("active-speaker", function(evt) {
     var uid = evt.uid;
     console.log("update active speaker: client " + uid);
  });
```
Parameters
- event: "active-speaker"
- callback: function
  - - (evt: any): void
    - Parameters
      - evt: any
      Returns void
Returns void
This callback notifies the application of all the speaking users and their volumes.

It is disabled by default. You can enable this event by calling enableAudioVolumeIndicator. If enabled, it reports the volumes every two seconds regardless of whether there are users speaking.

The volume is an integer ranging from 0 to 100. Usually a user with volume above five will be counted as a speaking user.
example
Sample Code
```
client.on("volume-indicator", function(evt){
    evt.attr.forEach(function(volume, index){
    console.log(`#{index} UID ${volume.uid} Level ${volume.level}`);
  });
});
```
Parameters
- event: "volume-indicator"
- callback: function
  - - (evt: any): void
    - Parameters
      - evt: any
      Returns void
Returns void
This callback notifies the application that the live streaming has started.

Parameters
- event: "liveStreamingStarted"
- callback: function
  - - (evt: any): void
    - Parameters
      - evt: any
      Returns void
Returns void
This callback notifies the application that the live streaming has failed.

Parameters
- event: "liveStreamingFailed"
- callback: function
  - - (evt: any): void
    - Parameters
      - evt: any
      Returns void
Returns void
This callback notifies the application that the live streaming has stopped.

Parameters
- event: "lliveStreamingStopped"
- callback: function
  - - (evt: any): void
    - Parameters
      - evt: any
      Returns void
Returns void
This callback notifies the application that the live transcoding setting has been updated.

Parameters
- event: "liveTranscodingUpdated"
- callback: function
  - - (evt: any): void
    - Parameters
      - evt: any
      Returns void
Returns void
This callback notifies the application that the Token will expire in 30 seconds.

You should request a new Token from your server and call Client.renewToken.
example
Sample Code
```
client.on("onTokenPrivilegeWillExpire", function(){
  //After requesting a new token
  client.renewToken(token);
});
```
Parameters
- event: "onTokenPrivilegeWillExpire"
- callback: function
  - - (evt: any): void
    - Parameters
      - evt: any
      Returns void
Returns void
This callback notifies the application that the Token has expired.

You should request a new Token from your server and call Client.renewToken.
example
Sample Code
```
client.on("onTokenPrivilegeDidExpire", function(){
  //After requesting a new token
  client.renewToken(token);
});
```
Parameters
- event: "onTokenPrivilegeDidExpire"
- callback: function
  - - (evt: any): void
    - Parameters
      - evt: any
      Returns void
Returns void
This callback notifies the application that an error message is reported and requires error handling.
example
Sample Code
```
client.on("error", function(err) {
    console.log("Got error msg:", err.reason);
  });
```
For details, see Error Codes and Warning Codes.
Parameters
- event: "error"
- callback: function
  - - (evt: any): void
    - Parameters
      - evt: any
      Returns void
Returns void

publish

publish(stream: Stream, onFailure: function): void

Publish a Local Stream

This method publishes a local stream to the SD-RTN.

Note:

In a live broadcast, whoever calls this API is the host.
example
Sample Code
```
client.publish(stream, function(err) {
    console.log(err);
    //……
})
```
Parameters
- stream: Stream
  
  Stream object, which represents the local stream.
- onFailure: function
  
  The callback when the method fails.
  - - (err: any): void
    - Parameters
      - err: any
      Returns void
Returns void

renewChannelKey

renewChannelKey(key: string, onSuccess: function, onFailure: function): void

Renew the Channel Key

This method renews your channel key.

Once the Channel Key schema is enabled, the key expires after a certain period of time. When the onFailure callback reports the error DYNAMIC_KEY_TIMEOUT, the application should renew the Channel Key by calling this method. Not doing so will result in SDK disconnecting with the server.

Parameters
- key: string
  
  Specifies the renewed Channel Key.
- onSuccess: function
  
  The callback when the method succeeds.
  - - (): void
    - Returns void
- onFailure: function
  
  The callback when the method fails.
  - - (err: any): void
    - Parameters
      - err: any
      Returns void
Returns void

renewToken

renewToken(token: string): void

Renew the Token

This method renews your token.

Once the Token schema is enabled, the token expires after a certain period of time. In case of the onTokenPrivilegeWillExpire or onTokenPrivilegeDidExpire callback events, the application should renew the Token by calling this method. Not doing so will result in SDK disconnecting with the server.

Parameters
- token: string
  
  Specifies the renewed Token.
Returns void

setEncryptionMode

setEncryptionMode(encryptionMode: "aes-128-xts" | "aes-256-xts" | "aes-128-ecb"): void

Set the Encryption Mode

This method sets the encryption mode.

Note:

Ensure that you call this API before Client.join.

example

client.setEncryptionMode(encryptionMode);

Parameters
- encryptionMode: "aes-128-xts" | "aes-256-xts" | "aes-128-ecb"
  The encryption mode:
  - aes-128-xts: Sets the encrption mode as AES128XTS.
  - aes-256-xts: Sets the encrption mode as AES256XTS.
  - aes-128-ecb: Sets the encrption mode as AES128ECB.
Returns void

setEncryptionSecret

setEncryptionSecret(password: string): void

Enable Built-in Encryption

This method enables the built-in encryption.

Note:

Ensure that you call this API before Client.join.

example

client.setEncryptionSecret(password)

Parameters
- password: string
  
  The encryption password.
Returns void

setLiveTranscoding

setLiveTranscoding(coding: LiveTranscoding): void

Set Live Transcoding

This method sets the video layout and audio for CDN live.

Parameters
- coding: LiveTranscoding
  
  Transcoding settings, see LiveTranscoding for details.
Returns void

setLowStreamParameter

setLowStreamParameter(param: object): void

Set the Low-video Stream Parameter

If you enabled the dual-stream mode by calling Client.enableDualStream, use this method to set the low-video stream profile.

If you do not set the low-video stream profile, the SDK will assign default values based on your stream video profile.

Note:
- As different web browsers have different restrictions on the video profile, the parameters you set may fail to take effect. The Firefox browser has a fixed frame rate of 30 fps, therefore the frame rate settings do not work on the Firefox browser.
- Due to limitations of some devices and browsers, the resolution you set may fail to take effect and get adjusted by the browser. In this case, billings will be calculated based on the actual resolution.
- Call Client.join before using this method.
- Screen sharing supports the high-video stream only.
Parameters
- param: object
  
  Sets the video profile of the low-video stream.
  - birate: number
    
    Bitrate of the low-video stream frame in Kbps.
  - framerate: number
    
    Frame rate of the low-video stream frame in fps.
  - height: number
    
    Height of the low-video stream frame. The width and height parameters are bound together, and take effect only when both are set. Otherwise, the SDK will assign default values.
  - width: number
    
    Width of the low-video stream frame. The width and height parameters are bound together, and take effect only when both are set. Otherwise, the SDK will assign default values.
Returns void

setProxyServer

setProxyServer(proxyServer: string): void

Deploy the Nginx Server

Use this method to deploy the Nginx server.

Note:
- Ensure that you call this API before Client.join.
- Proxy services by different service providers may result in slow performance if you are using the Firefox browser. Therefore, Agora recommends using the same service provider for the proxy services. If you use different service providers, Agora recommends not using the Firefox browser.
example

client.setProxyServer(proxyServer);
Parameters
- proxyServer: string
  
  Your Nginx server domain name.
Returns void

setRemoteVideoStreamType

setRemoteVideoStreamType(stream: Stream, streamType: 0 | 1): void

Set the Remote Video-stream Type

When a remote user sends dual streams, this method decides on which stream to receive on the subscriber side. If this method is not used, the subscriber receives the high-video stream.

example

Sample Code

switchStream = function (){
  if (highOrLow === 0) {
    highOrLow = 1
    console.log("Set to low");
  }
  else {
    highOrLow = 0
    console.log("Set to high");
  }

  client.setRemoteVideoStreamType(stream, hightOrLow);
}

Note:

As not all web browsers are compatible with dual streams, Agora does not recommend developers setting the resolution of the low-video stream.

Some web browsers may not be fully compatible with dual streams:

Browser	Possible problem
Safari on MacOS	A high-video stream and a low-video stream share the same frame rate and resolution.
Firefox	A low-video stream has a fixed frame rate of 30 fps.
Safari on iOS	Safari 11 does not support switching between the two video streams.

Parameters

stream: Stream

The remote video stream object.
streamType: 0 | 1
Sets the remote video stream type. The following lists the video-stream types:
- 0: High-bitrate, high-resolution video stream.
- 1: Low-bitrate, low-resolution video stream.

Returns void

setStreamFallbackOption

setStreamFallbackOption(stream: Stream, fallbackType: 0 | 1 | 2): void

Set Stream Fallback Option

Use this method to set stream fallback option on the receiver.

Under poor network conditions, the SDK can choose to subscribe to the low-video stream or only the audio stream.

Note:

This method can only be used when the publisher has enabled the dual-stream mode by enableDualStream.

Parameters
- stream: Stream
  
  The remote stream object.
- fallbackType: 0 | 1 | 2
  The fallback option:
  - 0: (Default) Disable the fallback.
  - 1: Automatically subscribe to the low-video stream under poor network.
  - 2: Under poor network, the SDK may subscribe to the low-video stream (of lower resolution and lower bitrate) first, but if the network still does not allow displaying the video, the SDK will receive audio only.
Returns void

setTurnServer

setTurnServer(turnServer: object): void

Deploy the TURN Server

Use this method to deploy the TURN server.

Note:

Ensure that you call this API before Client.join.

example

client.setTurnServer(config);

Parameters
- turnServer: object
  
  The TURN server settings.
  - forceturn: boolean
    Sets whether to force data transfer by TURN Server:
    
    true: Force data transfer.
    
    false: (default) Not to force data transfer.
  - password: string
    
    Your TURN Server password.
  - Optional tcpport?: string
    
    The TCP port(s) you want add to TURN Server.
  - turnServerURL: string
    
    Your TURN Server URL address.
  - Optional udpport?: string
    
    The UDP port(s) you want to add to TURN Server.
  - username: string
    
    Your TURN Server username.
Returns void

startLiveStreaming

startLiveStreaming(url: string, enableTranscoding?: boolean): void

Start a Live Stream

This method starts a live stream.
example
Sample Code
```
client.setLiveTranscoding(<coding>);
client.startLiveStreaming(<url>, true)
```
Parameters
- url: string
  
  URL address for the live stream.
- Optional enableTranscoding: boolean
  
  Marks whether to enable live transcoding. If set as true, setLiveTranscoding must be called before this method.
Returns void

stopLiveStreaming

stopLiveStreaming(url: string): void

Stop Live Streaming

This method stops and deletes the live streaming.

Parameters
- url: string
  
  URL address of the live streaming.
Returns void

subscribe(stream: Stream, onFailure: function): void

Subscribe to a Remote Stream

This method enables a user to subscribe to a remote stream.
example
Sample Code
```
client.subscribe(stream, function(err) {
    console.error("stream subscribe failed", err);
    //……
})
```
Parameters
- stream: Stream
  
  Stream object, which represents the remote stream.
- onFailure: function
  
  The callback when the method fails.
  - - (err: any): void
    - Parameters
      - err: any
      Returns void
Returns void

unpublish

unpublish(stream: Stream, onFailure: function): void

Unpublish the Local Stream

This method unpublishes the local stream.
example
Sample Code
```
client.unpublish(stream, function(err) {
    console.log(err);
    //……
})
```
Parameters
- stream: Stream
  
  Stream object, which represents the local stream.
- onFailure: function
  
  The callback when the method fails.
  - - (err: any): void
    - Parameters
      - err: any
      Returns void
Returns void

unsubscribe

unsubscribe(stream: Stream, onFailure: function): void

Unsubscribe from the Remote Stream

This method enables the user to unsubscribe from the remote stream.
example
Sample Code
```
client.unsubscribe(stream, function(err) {
    console.log(err);
    //……
})
```
Parameters
- stream: Stream
  
  Stream object, which represents the remote stream.
- onFailure: function
  
  The callback when the method fails.
  - - (err: any): void
    - Parameters
      - err: any
      Returns void
Returns void

Agora Web SDK API Reference

Hierarchy

Index

Methods

Methods

configPublisher

Parameters

width: number

height: number

framerate: number

bitrate: number

publisherUrl: string

Returns void

disableDualStream

Parameters

onSuccess: function

Returns void

onFailure: function

Parameters

err: any

Returns void

Returns void

enableAudioVolumeIndicator

Returns void

enableDualStream

Parameters

onSuccess: function

Returns void

onFailure: function

Parameters

err: any

Returns void

Returns void

init

Parameters

appId: string

onSuccess: function

Returns void

onFailure: function

Parameters

err: string

Returns void

Returns void

join

Parameters

tokenOrKey: string

channel: string

uid: number

onSuccess: function

Parameters

uid: number

Returns void

onFailure: function

Parameters

err: any

Returns void

Returns void

leave

Parameters

onSuccess: function

Returns void

onFailure: function

Parameters

err: any

Returns void

Returns void

on

Parameters

event: "stream-published"

callback: function

Parameters

evt: any

Returns void

Returns void

Parameters

event: "stream-added"

callback: function

Parameters

evt: any

Returns void