Skip to main content

README

@auvious/rtc / Exports

Auvious RTC API

This library simplifies the creation of calls and conferences on your web app, utilizing the Auvious RTC backend for signalling and media routing.

Install using NPM

Setup @auvious package registry

npm config set @auvious:registry=https://nexus.auvious.com/repository/npm-auvious

Login to @auvious package registry. Contact info@auvious.com if you don't have the credentials.

npm login --registry=https://nexus.auvious.com/repository/npm-auvious

Usage

In order to use the services of this module, you first need to create an AuviousClient instance (@auvious/common module), and then login. Afterwards you create an Auvious instance (provided in this module) and call Auvious.register() method. The register method takes an IRegisterOptions object where you must supply at least the auviousCommonClient attribute which must be an AuviousClient object. User registration creates a unique user endpoint which can also be thought as something like a user "session". This user endpoint is thoroughly used for event routing, and for the system to be able to distinguish between different devices that a user has registered from. For example, when a call is created, all user endpoints will receive the related event, but only one can answer. When he answers all other endpoints receive the answered event, and from the user endpoint id the other devices can detect that the user has answered the call, in order to stop ringing for example.

If you want to create simple one-to-one calls check the Simple (one-to-one) Call Guide and Call Examples.

If need communication between more than 2 people then you should look at Conference Call Guide and Conference Examples. This is the API that is used by the Auvious Video Counselor Application

Simple (one-to-one) Call Guide

  • A user can initiate a new call using Auvious.call method. This method takes two arguments, username and options of type ICallOptions. The username is the call target, and it should either be a valid username or a sip address in case a sip gateway has been configured. The options parameters should be used to provide event handlers and media constraints.

    • ringing event handler will be called when the remote party device signals that it started ringing.
    • accepted event handler will called when the call is answered by the remote party.
    • streamAdded event handler will be called when the local or remote stream is available. An IStream object will be passed as an argument on the event handler. IStream.originator will contain the local or remote endpoint details, through which the developer can distinguish between local and remote streams.
    • streamRemoved event handler will be called when the local or remote stream is removed, when the call is ended, or failed for some reason.
    • failed event handler is called when the call has fatally failed, error is given
    • ended event handler is called when the call is ended, or cancelled
  • A user can accept an incoming call using ISession.answer. An incoming call can be detected by providing the Auvious instance the newSession event handler, either when registering with Auvious.register() or with Auvious.on() method at any either point in time.

  • With ISession.terminate() an user can reject a call, when received first time, hangup when established or cancel outgoing call before being established

Call Examples

Using @auvious/common login

const auviousClientArgs: AuviousClientArgs = {
serverUrl: CONFIG.SERVER_URL,
mqttUrl: CONFIG.MQTT_URL,
mqttUsername: CONFIG.MQTT_USERNAME,
mqttPassword: CONFIG.MQTT_PASSWORD,
saveAuthTokenState: false,
subscribeToUserTopic: false,
useStandardOAuth2: !CONFIG.AUVIOUS_AUTH,
};

const auviousCommonClient = new AuviousClient(auviousClientArgs);

auviousCommonClient
.login(username, password)
.then((token) => resolve(this.auviousCommonClient))
.catch((error) => reject(error));

Create Auvious client from this library and register

const eventHandlers = {
connecting?: (event?: any) => void,
connected?: (event?: any) => void,
disconnected?: (event?: any) => void,
connectionFailed?: (event?: any) => void,
registered?: (event?: any) => void,
unregistered?: (event?: any) => void,
registrationFailed?: (event?: any) => void,
warning?: (event?: any) => void,
newSession?: (event?: any) => void,
newConferenceSession?: (event?: any) => void,
conferenceCreated?: (event?: any) => void,
createConferenceFailed?: (event?: any) => void,
newMessage?: (event?: any) => void
};

client = new Auvious();
const options: IRegisterOptions = {
auviousCommonClient: auviousCommonClient,
eventHandlers: eventHandlers
};

await client.register(options);

When registered, caller can make a call to other registered user

const eventHandlers: ISessionEventHandlers = {
connecting?: (event?: any) => void,
ringing?: (event?: any) => void,
accepted?: (event?: any) => void,
streamAdded?: (event?: any) => void,
streamRemoved?: (event?: any) => void,
ended?: (event?: any) => void,
failed?: (event?: any) => void
};

const options: ICallOptions = {
mediaConstraints: {
audio: sendConstraints.audio,
video: sendConstraints.video
},
receiveMediaConstraints: {
audio: receiveConstraints.audio,
video: receiveConstraints.video
},
eventHandlers: eventHandlers
};

client.call(contact, options);

Callee will receive an ISession class from newSession event handler, he can answer

// options is IAnswerOptions, similar to ICallOptions, look above example
call.answer(options);

Then caller will receive accepted event and call is considered established. Then at any point anyone can terminate the call, which is also possible in any state the call may be.

The Audio/Video streams will be received/removed by the streamAdded/streamRemoved event handlers. The mediaStream object from that event should be attached to audio/video renders, like HTML5's video/audio element.

Conference Call Guide

Besides simple one to one calls, Auvious RTC system allows you to create multi-party calls aka conferences.

A user or a system first has to create a conference. Then the conference id must somehow be communicated to all the users that want to join the conference. The users then join the conference and usually publish one or more streams so that other users can view them. To create a conference using this library use Auvious.createConference(). To join a conference use Auvious.joinConference(). In order to join a conference, it must exist prior to joining. Auvious.joinConference() returns a IConferenceSession instance. Use IConferenceSession.publish() to publish a stream, and you receive other user streams through IConferenceSessionEventHandlers.streamPublished event handler. For more info check [[Auvious]], IConferenceSession and IConferenceSessionEventHandlers objects.

Conference Examples

// first create and register two users, alice and bob
let aliceClient = new AuviousClient(AUVIOUS_CLIENT_ARGS);
let bobClient = new AuviousClient(AUVIOUS_CLIENT_ARGS);

alice = new Auvious();
bob = new Auvious();

await aliceClient.login(aliceUsername, alicePassword);
await bobClient.login(bobUsername, bobPassword);

await alice.register({
auviousCommonClient: aliceClient,
eventHandlers: aliceUAEventHandlers,
});
await bob.register({
auviousCommonClient: bobClient,
eventHandlers: bobUAEventHandlers,
});

// alice creates conference
const conference = await alice.createConference();

// alice joins conference
const aliceSession = await alice.joinConference({
eventHandlers: aliceConferenceEventHandlers,
id: conference.name,
});

// bob joins conference
const bobSession = await bob.joinConference({
eventHandlers: bobConferenceEventHandlers,
id: conference.name,
});

// alice publishes camera
const alicePublishedCam = await aliceSession.publish(cameraStreamOptions);

// bob publishes mic
const bobPublishedMic = await bobSession.publish(micStreamOptions);

// ...

// bob leaves
bobSession.leave();

// alice closes camera
aliceSession.unpublish(alicePublishedCam);

// alice terminates conference
aliceSession.terminate();

Code Style

We use mainly prettier with default settings, .editorconfig to enforce some basics (which prettier also uses), and check/enforce style with eslint.

Use prettier vscode extension, and automatic formatting should take care of format