build in-app video and audio chat with cyxth calls §

intergrating calls to your application is easy and straight forward with the @cyxth/calls npm package.

introduction §

first make sure you have created a cyxth account and created a cyxth instance, and make sure to check out authorization and concepts.

next download @cyxth/core and @cyxth/calls packages from npm

bashnpm install @cyxth/core @cyxth/calls

This guide gives a high level overview and cyxth calls concepts, feel free to check the calls api reference and colab examples after this guide. for a deeper understanding of various topics.

initialization §

calls is a cyxth core plugin and is instantiated like the other plugins to get started with calls use calls() function from cyxth core module.

tsimport Cyxth from '@cyxth/core';
import Calls from '@cyxth/calls';

const APP_URL = "my-app.apps.cyxth.com"
let USER_TOKEN = "user_token_from_backend";

const cyxth = await new Cyxth(APP_URL, [Calls]).connect(USER_TOKEN);
const caller : Calls = cyxth.calls();

the user has to be connected to cyxth or else cyxth.calls() will fail.

call flow §

at a glance implementing calls to your application with cyxth calls follows these three simple steps

• create or join - create a call on a new channel or join an existing one
• call events - listen and respond to new tracks, user joining and leaving etc.
• call controls - once established add buttons to activate mic, video , mute users moderate etc.

let’s go over each of this steps with an example.

create or join §

first a user creates a call or joins one

tsconst caller : Calls = cyxth.calls();
await caller.create('channelId');

caller.on("call:new", async ({channelId}) => {
    await caller.join(channelId)
})

call events §

next we listen for call and channel events to know when a user joins, adds a video or audio track, removes a track, is muted, is speaking, etc and update the local application state to reflect the same

tscaller.on("track:add",(data) => {
    // ... update user tracks and show in ui
})

caller.on("user:left",({userId}) => {
    // ... remove user from view
})

// .. listen for more events

calls controls §

these are your typical call control buttons at the bottom of the screen mute, video, audio, etc plus if a user is a call admin controls for other users like mute others, disable publishing and receiving certain tracks by various users in call etc.

tsconst enableMic = () => {
    const media = await navigator.mediaDevices.getUserMedia({audio:true})
    const tracks = {
        "mic_0": media.getAudioTracks[0],
    };
    await caller.addTracks(tracks);
}

//.. more call controls + actions

// add trigger to your call, for example
micOnBtn.addEventListener("click", enableMic);

with these three steps, you are able to integrate the full call experience to your application and customize it to your specific needs or use it in your framework of choice. check out the demos on various implementation examples, PS they all take these three steps.

concepts overview §

tracks §

cyxth calls works primarily on MediaStreamTracks rather than media streams. developers are required to provide labelled tracks sourced from streams i.e camera and mic with getUserMedia, screen capture with the screen capture API or canvas capture anything that can be turned to a MediaStreamTrack is supported.

for example to get user camera feed and mic

tsconst media = await navigator.mediaDevices.getUserMedia({audio:true, video: true})

const tracks = {
    "aliceMic": media.getAudioTracks[0],
    "aliceCam": media.getVideoTracks[0],
};

// use to create call
await myCall.create('channelId', tracks)

// or add to existing call
// await myCall.addTracks(tracks);

the track labels have to be unique and are used to control the specific tracks i.e muteTracks, removeTracks, getUsers on the call instance, labelled tracks also used on various call events such as track:add, track:mute.

the choosen media tracks are affected by the application codecs and call quality setting on the cyxth console and the call configuration. i.e if HD video is not enabled adding tracks with high video quality will fail so always match the constraints with what is set in the console.

call channels §

calls implements the channel interface, the common channel operations such as create, join, leave, work with calls and emit the usual channel events. all this is covered an overview of channel concepts,

user moderation enables you to build various call presets by limiting what a user can send or receive in a call, i.e a group call (many to many) where all users can send and receive media , a stream(few to many) where a few users are allowed to send media and many users can receive. one to one private calls and anything in between specific to your use case.

for all controls and actions on call channel check out Calls.

call configuration §

application wide call configuration is done at the cyxth console. call quality, supported codecs, maximum number of users per call instance, max tracks etc. check the call configuration page for all these settings.

application users can also create local configuration for a specific call instance like the allowed MediaKinds, maximum number of users, default permissions and join requests. Check CallConfig for all the configuration options available.

events §

use the on method to listen to various call events, here is an overview of the events, for a great user experience it is recommended that you listen to all this events and update the user view accordingly. for example if a user leaves the call make sure you remove their container or view as they will stay frozen contributing to bad ux, this goes for mute, track:add, track:del, cnl:del (call ended) and more.

-- ✌🏾