calls

introduction

intergrating calls to cyxth is easy with the@cyxth/calls npm package. calls can utilize the existing channel or create a new temporary call channel shared in the same parent channel or any other means.

cyxth supports private calls (one to one), group calls(many to many), broadcast (few to many), streams (one to many) and every thing in between, you can start in any of the call types and upgrade or downgrade to another.

calls are fully customizable with the cyxth REST API or cyxth console ui. You can set your application to use only voice calls, video calls, customize video and audio codecs and qualities or even disable calls in given channels.

a simple example

before attempting to make calls ensure you’ve enabled calling on cyxth initialization

import Calls from '@cyxth/calls';

const APP_URL = 'your_init_app_url_from_cyxth_console';

const cyxth = new Cyxth(APP_URL, {
	calls: Calls,
	offline: true
});

making calls in cyxth is a simple 3 step process. here is a simple web conferencing snippet from advanced chat tutorial.

/**@type {import('@cyxth/calls').default} */
let call;

// start call in a channel
const newCall = async () => {
	call = await cyxth.startCall('channel_id', {
		video: true,
		audio: true
	});

	handleCall(call);
};

// others in same channnel receive event and accept|reject
cyxth.on('call', async (data) => {
	// show a notification | ring on `data.channel`
	//add logic to accept or reject the call

	call = await data.request.accept({
		video: true,
		audio: true
	});

	handleCall(call);
});

// handle call events
const handleCall = async (call) => {
	call.on('join', (data) => {
		// update element
	});

	// more events
};

start a call

starting a call takes 3 method signatures, the simplest is using media constraint and let cyxth handle streams and tracks for you

startCall(channelId: string, {
    video: bool,
    audio: bool
})

or you can provide a media stream instead, it is recommended you use this method to allow users to setup and their camera and mic before joining a call or meeting.

startCall(channelId:string, mediastream: MediaStream)

to add multiple streams for example share screen while using camera, or stream from another device use labels with media streams as shown below.

startCall('channelId', {
	cam0: MediaStream,
	share: MediaStream,
	cam2: MediaStream
});

the number of streams and tracks can be adjusted in cyxth console or for a specific channel.

joining a call

users join calls by listening on call event or using joinCall() function.

cyxth.on('call', (request: OnCall) => {
	// accept or decline call
});

// on call
interface OnCall {
	channel: string;
	request: CallRequest;
}

// call request
declare class CallRequest {
	/**
	 * accept a call
	 * @returns a call promise
	 */
	accept(callOptions: CallOptions): Promise<Call>;
	/**
	 * reject a call
	 */
	reject(): void;
}

call events

events emitted in call can be listened for using on in the call object

call.on('event'(ev) => { ...handle event})

call events include

connected

event emitted when the call is connected and ready to be used
returns

{
    src: MediaStream,
    audio: number,
    video: number
}

join

event emitted when a new user joined the call
returns

{
    userId: string,
    src: MediaStream,
    audio: number,
    video: number,
    label?: string
}

leave

event emitted when a user left the call
returns

{
	userId: number;
}

update

event emitted when users update their streams by muting, togging a track on or off among other actions. returns

{
    kind: "audio" | "video",
    action: "mute" | "unmute" | "on" | "off",
    userId: string,
    src?: MediaStream,
    label?: string
}

error

event emitted when there is an error in the active call for example slow or no internet connection.
returns

{
    // error reference code
    code: string,
    // error message
    message: string,
    // data
    data: any
}

call methods

you can also control a given call

1. mute() mute mic, mic is on but not sending audio packets
2. unmute() unmute mic
3. endCall() end a call if one started it
4. micOn turn mic on
5. micOff turn mic off completely
6. cameraOn() enable camera
7. cameraOff() disable camera
8. leave() leave call
9. moderate() moderate users in call

method summary

summary of call method signatures

startCall(channelId: string, options: CallOptions): Promise<Call>

// on call
interface OnCall{
    channel:string
    request:CallRequest
    data: any
}

// call request
declare class CallRequest {
    /**
     * accept a call
     * @returns a call promise
     */
    accept(callOptions: CallOptions): Promise<Call>;
    /**
     * reject a call
     */
    reject(): void;
}

/** enable mic */
micOn: () => Promise<void>;

/** disable mic*/
micOff: () => Promise<void>;

/** turn camera on*/
cameraOn: () => Promise<void>;

/** turn camera off completely */
cameraOff: () => Promise<void>;

/** mute mic, note that the mic stays **on** but is not sending audio to other peers, use micOff to completely stop */
mute: () => Promise<void>;

/** unmute mic */
unmute: () => Promise<void>;

/** leave call */
leave(): void;

/*** end call (only call initiator or channel admin can do this) */
endCall(): void;

/** moderate users in call*/
moderate(): void;

/*** listenfor  call events*/
on(event: string, callback: Function): void;