2-Way Audio SDK for Web
Introduction
Eagle Eye Networks 2-Way Audio enables communications between a client and a far end camera or cameras with associated audio devices such as speakers and microphones. 2-Way Audio uses WebRTC to deliver peer-to-peer communications.
This guide describes how to implement 2-Way Audio using a Node.js based SDK.
Prerequisites
You will need the following to use and verify a 2-Way Audio integration:
- You should be logged in and have an OAuth JWT access token
- The account should have a camera that is associated with the speaker
- The bridge version should be 3.8.0 or higher
Installation
You can use following command to install @een/two-way-audio-web-sdk:
npm i @een/two-way-audio-web-sdk
If successful, the een-two-way-audio-web-sdk
should appear in the project's dependencies in package.json
.
Declaration
To establish a WebRTC session, you will need an <audio autoplay />
HTML/DOM element to instantiate the client. Additionally, you will need to provide a JWT access token.
import EENWebRTC from 'een-two-way-audio-web-sdk';
const audioElement = document.getElementById("webrtc-audio");
// Instantiate a new Two-way Audio client with audio DOM element
const webRtcClient = new EENWebRTC({ audioDom: audioElement, token: accessToken });
Events
The EENWebRTC extends from EventEmitter3, all connection status are exposed by emitter.emit() function. The status fiels are listed below:
Event Name | Description | Event Parameters |
---|---|---|
connecting | Once the end user makes a call, the client will be in this status, and it will last until connection is established | None |
connected | Occurs once the connection is established and the call has started | None |
disconnected | Occurs when any connection error happens, or the end user ends the call. The client will be in this status until the user makes the next call. See below for details regarding errors. | reason : the reason of why disconnected, either USER or ERROR error : It will be null if the user initiated a disconnect. Otherwise, it is a Javascript Error object |
End users can register the status callback to listen for client status changes. For example:
webRtcClient.on('connecting', function() {
// Update UI icon to be connecting stage.
this.updateSpeakerIcon('connecting');
});
webRtcClient.on('connected', function() {
// Update UI icon to be connected stage.
this.updateSpeakerIcon('connected');
});
webRtcClient.on('disconnected', function(reason, error) {
// Update UI icon to be disconnected stage.
this.updateSpeakerIcon('disconnected');
if (error) {
// It possible to distinguish between a BUSY error or something else
if (error.cause === 'busy') {
console.error('Device is busy. Try again later');
} else {
// Handle the error.
console.error('WebRTCError reason: ', reason);
console.error(error);
}
}
if (reason !== 'USER') {
// If error type is not USER type, then it means connection error happens, so here you can popup some notification view.
this.speakerMessageNotification('disconnected');
}
});
In the case of a disconnects (including errors), the EENWebRTC client will close the Web Socket and WebRTC connections.
Methods
connect()
: Start WebRTC Session
Use the connect(feed)
method to start a WebRTC session. The feed object provides the necessary information to connect to the right bridge and devices. It comes from the API V3 /feeds
endpoints. More information about the feed object is below.
// Note: feed object is provided by the /feeds API.
// This is just an example.
let feed = {
"sourceId": "100abcde",
"webRtcUrl": "wss://edge.c000.eagleeyenetworks.com",
"type": "talkdown",
"id": "100abcde-talkdown",
"mediaType": "halfDuplex"
}
webRtcClient.connect(feed);
close()
: Disconnect
Tell the EENWebRTC client to close the Web Socket and WebRTC connections to terminate the call.
// Disconnect the call
webRtcClient.close();
getStatus()
Returns the current WebRTC client connection status as a string.
The Feed Object
You can get the <<glossary:feed>>
object from API V3 /feeds
.
The feed
object will have some important properties: deviceId
, webRtcUrl
, type
, and mediaType
. When calling connect(feed)
, pass the feed object as the first and only parameter.
Property | Type | Description | Example |
---|---|---|---|
sourceId | string | ESN of the target camera or speaker | “100abcde“ |
webRtcUrl | string | The websocket URL of edge service. The url is composed according to the wss://edge.<speaker_account_cluster>.eagleeyenetworks.com pattern | “wss: //edge.c000.eagleeyenetworks.com“ |
type | string | The type of service that is being called, here the value is talkdown | “talkdown“ |
mediaType | string | The media type being requested, either fullDuplex or halfDuplex | “halfDuplex” |
Errors
The EENWebRTC client catches and throws all Error
using the disconnected
status callback with the pattern webRtcClient.emit(Events.DISCONNECTED, Reasons, Error);
. There are two Reasons
:
USER
: If the user disconnects the call, then the client will throw this reason with errornull
to the callback.ERROR
: Any connection errors, including websocket error, signal connection error, auth error etc, will use this reason.
There are several possible ERRORs listed below:
ClientError: The audioElement can not be null.
: When a user does not pass any audioElement to EENWebRTC constructor method.ClientError: The webRtcUrl can not be null.
: When a user passes a null value or no value of webRtcUrl (in thefeed
object) to EENWebRTC constructor method.ClientError: The deviceId can not be null.
: When a user passes a null value or no value of deviceId to EENWebRTC constructor method.ClientError: Already connected
: If the EENWebRTC client is already connected and a new connection is attempted, the attempt will be rejected.ClientError: Connection to Signaling Services lost
: If signal disconnects by error.ClientError: One or more transports has terminated in an error
: If PeerRTCConnection's connectionState failed.ClientError: Failed to get stream
: If client can't get audio stream from peer connection.ClientError: Connection closed during initialization
: Connection attempt failed.Your token not valid
: Auth_key was not accepted during authorization.
Additionally, the client will throw all standard Web Socket and WebRTC errors if they occur.
Updated about 1 year ago