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:

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.

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 error null 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 the feed 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.