Setting up a video call

This tutorial will walk you through the steps of setting up a basic client using the Between API.

Step 1: Import and initial the conference

The Conference object is initialized with two parameters. The first one is an optional customCallId which is used to idenitify calls, if it is not entered then a randon UUID is returned. The second parameter is customUserData, such as a user Id of the publisher, this will be used to identify participants later in the call.

import { Conference } from 'between'

let conf = new Conference(customCallId, customUserData)
conf.id // custom or auto generated callId

Step 2: Handling device permissions

Between handles all the difficult parts of the device permissions for the easiest call experience. The built-in method getPermissionState unifies permission handling across all browsers and it returns a DevicePermissionState object. To learn more about how devices are used in Between, visit the Adjusting Audio/Video section

// this will ask the user for media permissions
let status = await conf.getPermissionState()

// if the user denies permission, handle that
if (status.state === "denied" || status.state === "failed") {
    alert(status.error.rawStr)
    return
}

Step 3: Setting up session listeners

Between uses simple listeners to keep information up-to-date throughout the lifetime of the call. There are 3 main listeners to use when initializing a call, visit the Conference reference section to learn more about all of them.

// we will setup all the relevant events to listen for

let localParticipant;
let remoteParticpants = {}

conf.on("localParticipant", (lp) => {
    // returns a LocalParticipant object

    // we will use this to publish audio/video
    // also to change devices throughout the conference 
    
    localParticipant.on("videoCreated", (d) => {
        // we get a local video stream of the publishing user
    })
})

conf.on("participantJoined", (participant) => {
    // returns a Participant object 
    
    // called whenever someone has entered the call
    // we will use this to get information about other
    // participants in the call

    // NOTE: participant.id is customUserData that we initiated with

    participant.on('videoCreated', (video) => {
        // the remote user has created a video

        document.getElementById('remoteStreams').append(video)
    })

    // add this to our local array to use later
    // for volume, getting spatial data, etc..
    remoteParticpants[participant.id] = participant

})

conf.on("participantLeft", (id) => {
    // the participant has left the call

    delete remoteParticpants[id]
    document.getElementById(id).remove()
})

Step 4: Handling termination and starting the call

Starting a call is as easy as calling the startCall method. As for termination, Between dispatches a listener for when the conference ends through either user input or unexpectedly, visit the Conference reference section to learn more about handling errors.

// finally we will start the call
conf.startCall()

conf.on("sessionTerminated", () => {
    // the call has ended
    localParticipant = null
    remoteParticpants = {}
})