Web API - WebRTC Beta

The Agora Web SDK(WebRTC for short) library includes the following classes:

AgoraRTC Use the AgoraRTC object to create Client(s) and Stream objects.
Client Represents the web client object that provides access to core AgoraRTC functionality.
Stream Represents the local/remote media streams in a session.

AgoraRTC Methods

Use the AgoraRTC object to create Client(s) and Stream objects.

Create Client Object (createClient)

createClient()

This method creates and returns a client object for web-only or interop mode(interoperability with Agora Native SDKs). Call it only once per session.

Note

When you set the mode as interop:

  • Communication: the interoperability with Agora Native SDKs is enabled automatically
  • Live Broadcast: the users who use the Agora Native SDK must call enableWebSdkInteroperability to enable the interoperability

For the web-only mode, see the following sample code:

AgoraRTC.createClient();

For the interop mode, see the following sample code:

AgoraRTC.createClient({mode: 'interop'});

Enumerate Platform Devices (getDevices)

getDevices(callback)

This method enumerates platform camera/microphone devices.

Parameter Name Type Description
callback Function

The callback function to retrieve the devices information.

For ex. callback(devices):

devices[0].deviceId: device ID

devices[0].label: device name in string

devices[0].kind: ‘audioinput’, ‘videoinput’

Sample code:

AgoraRTC.getDevices (function(devices) {
var dev_count = devices.length;

var id = devices[0].deviceId;
});

Create Stream Object (createStream)

createStream(spec)

This method creates and returns a Stream object.

Parameter Name Type Description
spec Object

This object contains the following properties:

  • streamID: represents the stream ID, normally set to uid which can be retrieved from the client.join callback.
  • audio: (flag) true/false, marks whether this stream contains an audio track.
  • video: (flag) true/false, marks whether this stream contains a video track.
  • screen: (flag) true/false, marks whether this stream contains a screen sharing track. It should be set to false in the current version.
  • attributes: (optional) including the following attributes:
    • resolution: The resolution, which can be set as one of ‘sif’, ‘vga’, ‘hd720p’
    • minFrameRate: The minimum framerate
    • maxFrameRate: The maximum framerate
  • (optional) cameraId: the camera device ID retrieved from the getDevices method.
  • (optional) microphoneId: the microphone device ID retrieved from the getDevices method.

Sample code:

var stream = AgoraRTC.createStream({streamID: uid, audio:true, video:true, screen:false});

Client Methods and Callbacks

Represent the web client object that provides access to core AgoraRTC functionality.

Method

Initialize Client Object (init)

init(appId, onSuccess, onFailure)

This method initializes the Client object.

Parameter Name Type Description
appId String The App ID for your project. For how to get it, refer to Agora Keys User Guide
onSuccess Function (optional) the function to be called when the method succeeds.
onFailure Function (optional) the function to be called when the method fails.

Sample code:

client.init(appId, function() {
    log("client initialized");
    //join channel
    //……
}, function(err) {
    log("client init failed ", err);
    //error handling
});

Join AgoraRTC Channel (join)

join(channelKey, channel, uid, onSuccess, onFailure)

This method allows the user to join an AgoraRTC channel.

Parameter Name Type Description
channelKey String
  • Low Security Requirement: pass null as the parameter value
  • High Security Requirement: pass the string of the Channel Key as the parameter value

For how to get a Channel Key, refer to Agora Keys User Guide

channel String A string providing the unique channel name for the AgoraRTC session.
uid Integer The user ID: a 32-bit unsigned integer ranges from 1 to (2^32-1). It must be unique. If set to null, the server will allocate one and returns it in onSuccess callback.
onSuccess function (optional) The function to be called when the method succeeds, will return the uid which represents the identity of the user.
onFailure function (optional) the function to be called when the method fails.

Sample code:

client.join('channelKey', '1024', 'null', function(uid) {
    log("client" + uid + "joined channel");
    //create local stream
    //……
}, function(err) {
    log("client join failed ", err);
    //error handling
});

Renew Channel Key(renewChannelKey)

renewChannelKey(channelKey, onSuccess, onFailure)

This method updates the Channel Key.

The key expires after a certain period of time once the Channel Key schema is enabled. When the onFailure callback reports the error DYNAMIC_KET_TIMEOUT, the application should retrieve a new key and then call this method to renew it. Failure to do so will result in SDK disconnecting with the server.

Name Description
channelKey Specifies the Channel key to be renewed.
Return Value
  • 0: Method call succeeded
  • <0: Method call failed

Set Video Stream Type(setRemoteVideoStreamType)

setRemoteVideoStreamType(stream, streamType)

This method specifies the video stream type of the remote user to be received by the local when the remote user sends dual streams. This method allows the application to adjust the corresponding video stream type according to the size of the video windows to save bandwidth and calculation resources. Agora SDK receives the high video stream by default. If needed, users can switch to the low video stream using this method.

Note

This API is applicable to the interop scenario when you set the scenario as interop when calling Create Client Object (createClient) .

Sample code:

client.on('stream-added', function (evt) {
 var stream = evt.stream;
 client.setRemoteVideoStreamType(stream, client.remoteVideoStreamTypes.REMOTE_VIDEO_STREAM_LOW);
 client.subscribe(stream, function (err) {
   console.log("Subscribe stream failed", err);
 });
});

Leave AgoraRTC Channel (leave)

leave(onSuccess, onFailure)

This method allows the user to leave an AgoraRTC channel.

Parameter Name Type Description
onSuccess function (optional) The function to be called when the method succeeds.
onFailure function (optional) The function to be called when the method fails.

Sample code:

client.leave(function() {
    log("client leaves channel");
    //……
}, function(err) {
    log("client leave failed ", err);
    //error handling
});

Publish Local Stream (publish)

publish(stream, onFailure)

This method publishes a local stream to the server.

Note

In the live broadcast scenario, the user who calls this API is considered as host.

Parameter Name Type Description
stream object Stream object, which represents the local stream.
onFailure function (optional) The function to be called when the method fails.

Sample code:

client.publish(stream, function(err) {
    log("stream published");
    //……
})

Unpublish Local Stream (unpublish)

unpublish(stream, onFailure)

This method unpublishes the local stream.

Parameter Name Type Description
stream object Stream object, which represents the local stream.
onFailure function (optional) The function to be called when the method fails.

Sample code:

client.unpublish(stream, function(err) {
    log.("stream unpublished");
    //……
})

Subscribe Remote Stream(subscribe)

subscribe(stream, onFailure)

This method subscribes remote stream from the server.

Parameter Name Type Description
stream object Stream object, which represents the remote stream.
onFailure function (optional) The function to be called when the method fails.

Sample code:

client.subscribe(stream, function(err) {
    log.("stream unpublished");
    //……
})

Unsubscribe Remote Stream (unsubscribe)

unsubscribe (stream, onFailure)

This method unsubscribes the remote stream.

Parameter Name Type Description
stream object Stream object, which represents the remote stream.
onFailure function (optional) The function to be called when the method fails.

Sample code:

client.unsubscribe(stream, function(err) {
    log("stream unpublished");
    //……
})

Callback Events

Local Stream Published Event (stream-published)

Notify the application that the local stream has been published.

Sample code:

client.on('stream-published', function(evt) {
    log("local stream published");
    //……
})

Remote Stream Added Event (stream-added)

Notify the application that the remote stream has been added.

Sample code:

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

Remote Stream Removed Event (stream-removed)

Notify the application that the remote stream has been removed, (i.e., a peer user called unpublish stream).

Sample code:

client.on('stream-removed', function(evt) {
    var stream = evt.stream;
    log("remote stream was removed", stream.getId());
    //……
})

Remote Stream Subscribed Event (stream-subscribed)

Notify the application that the remote stream has been subscribed.

Sample code:

client.on('stream-subscribed', function(evt) {
    var stream = evt.stream;
    log("new stream subscribed ", stream.getId());
    //play the stream
    //……
})

Peer User Left Channel Event (peer-leave)

Notify the application that the peer user has left the room, (i.e., peer user called client.leave())

Sample code:

client.on('peer-leave', function(evt) {
    var uid = evt.uid;
    log("remote user left ", uid);
    //……
})

Audio Volume Indication Event (active-speaker)

Notify the application who is speaker in the channel now.

Sample code:

client.on(‘active-speaker’, function(evt) {
     var uid = evt.uid;
     log("update active speaker: client" + uid);
  });

Error Messages Reported(onFailure)

Notify the application that an error message is reported and requires error handling.

For details, refer to Error Messages.

Stream Methods

Initialize Stream Object (init)

init(onSuccess, onFailure)

This method initializes the Stream object.

Parameter Name Type Description
onSuccess function (optional) The function to be called when the method succeeds.
onFailure function (optional) The function to be called when the method fails.

Sample code:

stream.init(function() {
    log("local stream initialized");
    // publish the stream
    //……
}, function(err) {
    log("local stream init failed ", err);
    //error handling
});

Retrieve Stream ID (getId)

getId()

This method retrieves the stream id.

Retrieve Stream Attributes(getAttributes)

getAttributes()

This method retrieves the stream attributes.

Retrieve Video Flag (hasVideo)

hasVideo()

This method retrieves video flag.

Retrieve Audio Flag (hasAudio)

hasAudio()

This method retrieves the audio flag.

Enable Video (enableVideo)

enableVideo()

This method enables video track in the stream; it only works when video flag was set to true in stream.create and acts like video resume.

Disable Video (disableVideo)

disableVideo()

This method disables video track in the stream, only works when video flag was set to true in stream.create and acts like video pause.

Enable Audio(enableAudio)

enableAudio()

This method enables audio track in the stream and acts like audio resume.

Disable Audio (disableAudio)

disableAudio()

This method disables audio track in the stream and acts like audio pause.

Set Video Profile (setVideoProfile)

setVideoProfile(profile)

This method sets the video profile. It is optional and only works before calling stream.init(). The default value is 480p_1 .

Parameter Name Type Description
profile String The video profile. See the table below for its definition.

Video Profile Definition:

Video Profile Enum Value Resolution (width x height) Frame Rate (fps) Bitrate(kbps)
120P 0 160x120 15 65
120P_3 2 120x120 15 50
180P 10 320x180 15 140
180P_3 12 180x180 15 100
180P_4 13 240x180 15 120
240P 20 320x240 15 200
240P_3 22 240x240 15 140
240P_4 24 424x240 15 220
360P 30 640x360 15 400
360P_3 32 360x360 15 260
360P_4 33 640x360 30 600
360P_6 35 360x360 30 400
360P_7 36 480x360 15 320
360P_8 37 480x360 30 490
360P_9 38 640x360 15 800
360P_10 39 640x360 24 800
360P_11 100 640x360 24 1000
480P 40 640x480 15 500
480P_3 42 480x480 15 400
480P_4 43 640x480 30 750
480P_6 45 480x480 30 600
480P_8 47 848x480 15 610
480P_9 48 848x480 30 930
720P 50 1280x720 * 15 1130
720P_3 52 1280x720 * 30 1710
720P_5 54 960x720 * 15 910
720P_6 55 960x720 * 30 1380
1080P 60 1920x1080 * [1] 15 2080
1080P_3 62 1920x1080 * [1] 30 3150
1080P_5 64 1920x1080 * [1] 60 4780

Footnotes

[1](1, 2, 3) Achieving 1080P resolution depends on the performance and capabilities of the device and may not currently be possible on lower performance devices. If a device has inadequate performance then low frame rates may be experienced when using 1080P. Agora.io is continuing to optimize video for lower-end devices in future releases – contact support@agora.io to discuss particular device needs.

Sample code:

stream.setVideoProfile('480p_1');

Play Video/Audio Stream (play)

play(elementID, assetsURL)

This method plays the video/audio stream.

Parameter Name Type Description
elementID String Represents the html element id.
assetsURL String (optional) The URL of the resource file. By default the files are located under /assets/ folder.

Sample code:

stream.play('div_id', '/res'); // stream will be played in div_id element, resource files under /res/assets/

Stop Video/Audio Stream(stop)

stop()

This method destroys the player created in play() and clears the display DOM tree under elementID (specified in the play method).

Close Video/Audio Stream (close)

close()

This method closes the video/audio stream. The camera and microphone authorization will be cancelled after calling this method.