EEN Two-way Audio Web SDK

Copyright (C) 2023 Eagle Eye Network B.V. - [email protected] This software can not be copied and/or distributed without the express permission of Eagle Eye Networks.

The EEN Two-way Audio Web SDK is a wrapper for the communication between a client (ie. Web Browser) and the EEN Two-way Audio Signaling Services using WebRTC. Developers can use the exposed methods to easily establish and disconnect sessions.

Quick start

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.

Preparation

To establish a Two-way Audio session by using the SDK, you need to prepare the following variables:

1. <audio />: an Audio HTML element, which will be the displaying media for talkdown.HTML/DOM element
2. talkdown_feed: a JavaScript object which contains the necessary variables for establishing talkdown connection. More info

Declaration

Since EEN Two-way Audio Web SDK is built in UMD format, you have to import it based on the framework which you are using. For example, if you are using Vue, you should import it in the main.js as below:

import {createApp} from 'vue'
import App from './App.vue'
import EENWebRTC from '@een/two-way-audio-web-sdk';

const app = createApp(App)
app.use(EENWebRTC);
app.mount('#app')

Once you finished import, you can declare the instance as following:

const audioElement = document.getElementById("two-way-audio");

// Instantiate a new Two-way Audio client with settings
const client = new EENWebRTC({audioDom: audioElement});

You have to pass the audioDom(HTML/DOM audio element) when creating the client.

Register status callbacks

The EENWebRTC extends from EventEmitter3, all connection status are exposed by emitter.emit() function. The status are like below:

| Status Name | Description | Param | | -- | -- | -- | | 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 | Once the connection is established, the client will be in this status. | None | | disconnected | Any connection error happens or the end user closes the call, the client will be in this status until the user makes the next call. More details. | reason: the reason of why disconnected: USER or ERROR, error(optional): It will be null if the user disconnects talkdown. Otherwise, it is a standard Javascript Error object. |

End-user can register the status callback to listen the client status. For example:

client.on('connecting', function () {
    // Update UI icon to be connecting stage.
    this.updateSpeakerIcon('connecting');
});

client.on('connected', function () {
    // Update UI icon to be connected stage.
    this.updateSpeakerIcon('connected');
});

client.on('disconnected', function (reason, error) {
    // Update UI icon to be disconnected stage.
    this.updateSpeakerIcon('disconnected');

    if (error) {
        // Handle the error.
        console.error('WebRTCError reason: ', reason);
        console.error(error);
    }

    if (reason !== 'USER') {
        // If error type is not USER, then it means connection error happens, so here you can popup some notification view.
        if (error.message === 'Speaker is busy') {
            this.speakerMessageNotification('device is busy');
        } else {
            this.speakerMessageNotification('disconnect error');
        }
    } else {
        // If error type is USER, it means disconnection is caused by end user. So here you can popup some dissconnected message on the page.
        this.speakerMessageNotification('disconnected');
    }
});

If a disconnect happens, the EENWebRTC client will close the websocket connection by itself.

connect(): Start A Two-way Audio Session

Use the connect(feed) method to start a Two-way Audio session.

// 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"
}

client.connect(feed);

close(): Disconnect

// Disconnect the call
client.close();

The Authorization

The WebRTC SDK requires EEN authentication and access_token. Please refer to https://developerv3.eagleeyenetworks.com/docs/login-public-client .

The feed object

You can get the feed object from API V3 / feeds. The feed object must have: deviceId, webRtcUrl, type, and mediaType.

| Variable name | Type | Description | Example | | :-- | :--: | :-- | :-- | | sourceId | String | The ESN of doing talkdown device(Camera/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 service type of web RTC, here the value is always talkdown. | “talkdown“ | | mediaType | String | The media type string of talkdown, here only support fullDuplex and halfDuplex | “halfDuplex” |

Errors

The EENWebRTC client can catch all errors and throws Error by the disconnected status callback, like 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 error null to the callback.
• ERROR: Any connection errors, including websocket error, signal connection error, auth error etc., will use this reason.

The ClientError’s cause could be one of following:

• busy
• invalidRequest
• clientMediaError
• serviceUnavailable
• authorizationFailed
• permissionDenied
• resourceNotFound
• invalidParameters
• alreadyConnected

There are several ERRORs as below:

• ClientError(message: 'The audioElement can not be null', cause: 'invalidParameters'): When a user does not pass any audioElement to EENWebRTC constructor method, this error will show.
• ClientError(message: 'The webRtcUrl can not be null', cause: 'invalidParameters'): When a user passes a null value or no value of webRtcUrl to EENWebRTC constructor method, this error will show.
• ClientError(message: 'The deviceId can not be null', cause: 'invalidParameters'): When a user passes a null value or no value of deviceId to EENWebRTC constructor method, this error will show.
• ClientError(message: 'Already connected', cause: 'alreadyConnected'): If the EENWebRTC client has established one talkdown connection, the following connection will be rejected and get this error.
• ClientError(message: 'Connection to Signaling Services lost', cause: 'serviceUnavailable'): If signal disconnects by any connection error, the end user will get this error.
• ClientError(message: 'One or more transports has terminated in an error', cause: 'serviceUnavailable'): If PeerRTCConnection's connectionState failed, the client will throw this error to the end user.
• ClientError: (message: 'Failed to get stream', cause: 'clientMediaError'): If client can't get audio stream from peer connection, end user will get this error.
• ClientError: (message: 'Connection closed during initialization', cause: 'serviceUnavailable'): If websocket is closed during establishing a talkdown connection, the end user will see this error.
• Your token not valide: This error is from the signal server when token doesn't pass authorization in the signal server.
• Device is busy: This error is from the signal server. If the device is in another talkdown session, the user will get this error when trying to establish the talkdown connection.
• WebSocket errors.

Methods of client

The client object only has below methods:

• connect(talkdown_feed: object): establish the Two-way Audio connection.
• getStatus(): get current WebRTC client connection status.
• close(): disconnect the Two-way Audio.