@zigbang/rtc-sdk NPM

Zigbang RTC SDK

The Zigbang RTC SDK is a Software Development Kit designed for utilizing Zigbang's WebRTC-based real-time video call solution. This SDK provides an interface for communication with the Zigbang WebRTC signaling server, enabling developers to effortlessly integrate video calling features into their applications.

Install

yarn add @zigbang/rtc-sdk

Usage

RTC

The RTC class is the gateway to the WebRTC-based real-time video communication solution. Designed to provide a straightforward and easy-to-use interface for working with WebRTC, it conveniently abstracts the low-level details for developers.

Features

Wait for and initiate calls by joining a waiting session.
Engage in video calls with peers by entering a room.
Easily create a media stream for video calls.

To start using the RTC class, you need to first create an instance of the class and provide the Zigbang JWT token.

import { RTC } from "@zigbang/rtc-sdk"

const accessToken = "<accessToken>" // ...from somewhere
const rtc = new RTC({ accessToken, from })
rtc.on("initialized", (peerId: string) => {
    // Actions to take when RTC is ready.
})

Call Iniviation

To wait for a call invitation, hosts should remain in the waiting session. The waitingId must be unique. When the RTC is ready to receive a call invitation, it will send a hostStarted event. Once the waiting process is successful, the host can receive a hostInvited event.

// Host side
rtc.hostStart(waitingId)

rtc.on("hostStarted", (roomId: string) => {
    // When the call invitation waiting starts
})

rtc.on("hostInvited", (roomId: string) => {
    // When someone initiates a call
})

To initiate a call, a guest needs to know the waitingId of the hosts they want to contact. By inviting them, participants in the waiting session will receive a hostInvited event, including the guest. The hostInvited event delivers the roomId of the room to join.

// Guest side
rtc.guestInvite(waitingId)

rtc.on("hostInvited", (roomId: string) => {
    // When you initiate a call
})

Hosts can answer the call invitation and choose to accept or decline the call. If hosts answer the call, the participants, including the hosts, will receive a hostAnswered event or hostBusy event. This allows hosts to be aware of whether the other host accepted or declined the invitation.

On the guest's side, they can cancel the calling process before it's responded to by the hosts. If the calling process is (forcibly) terminated unsuccessfully, the participants will receive a callTerminated event with a reason (e.g., cancel).

// Guest side
rtc.on("hostAnswered", (roomId: string) => {
    // When answered by the host
})

rtc.on("callTerminated", (roomId: string, answer: "canceled") => {
    // When the call progress is forcibly terminated
    // Other reasons are not implemented
})

await rtc.guestHangUp(roomId)

// Host side
rtc.on("hostAnswered", (roomId: string) => {
    // When answered by the host
})

rtc.on("callTerminated", (roomId: string, answer: "canceled") => {
    // When the call progress is forcibly terminated
})

await rtc.guestAnswer(roomId, answer)

Joining Room

For actual P2P video calls with peers, you must set your local stream using the myStream attribute. Here's how you can do it:

rtc.myStream = await navigator.mediaDevices.getUserMedia({ video: true, audio: true })

Once the event handlers are in place and the "initialized" event has been triggered, you are all set to dive into video calls!

rtc.join("<roomId>") // To join a room indetified "roomId"
rtc.leave("<roomId>") // To exit the room you've joined

Apart from initialized, the SDK offers other events to keep you in sync:

rtc.on("userJoined", (peerId: string) => {
    // When a new peer joins the room you are in
})
rtc.on("userLeft", (peerId: string) => {
    // When a peer with peerId exits the room you are in
})
rtc.on("joined", (roomId: string) => {
    // When you join a room
})
rtc.on("left", (roomId: string) => {
    // When you exit a room
})

When the userJoined or userLeft events are triggered, updates are reflected in the peers attribute of the RTC object. For accessing individual user streams of each peer, follow the example below:

// key = peerId
// value = PeerJS's MediaConnection (https://peerjs.com/docs/#mediaconnection)
{
    rtc.peers.entries().map(([key, value]) => (
        <div key={key}>
            <VideoPlayer mediaStream={value.remoteStream} key={key} />
        </div>
    ))
}

MyStream

The MyStream class is a helper class for working with MediaStream objects in a more convenient way. The MyStream class allows you to dynamically change the properties of a MediaStream, such as the device used for video and audio, and to easily control features like background blur.

The MyStream class is useful for building applications that require video conferencing, such as Zoom or Google Meet. It can be used to control the video and audio devices used by the application, and to add features like background blur to the video stream.

Features

Dynamically switch video/audio devices.
Toggle the audio/video of the current device.
Toggle background blur for the current video stream.

To create an instance of the MyStream class, you can specify the options you want to use, such as the mode (camera or screen), and any additional options for the camera or screen. For example, the following code creates an instance of the MyStream class that uses the camera device and enables background blur:

const mystream = new MyStream({ mode: "camera", camera: { blur: true } })
await mystream.start()

Once the start() method has completed, the MyStream instance will have two properties: myVideo and myVideoAudio.

`myVideo` property

myVideo contains only the Video track of the MediaStream. Typically used in local applications for users to preview their own stream. When developing applications like 직방밋 or Google Meet, using a stream that includes audio in a VIDEO element can cause echoes. Hence, audio tests are conducted differently, and only video checks are needed. This is where the audio-excluded myVideo comes in handy.

`myVideoAudio` property

myVideoAudio includes both the Video and Audio tracks in the MediaStream. Ideally, this would be used with the myStream attribute of the previously mentioned RTC class since P2P video calls inherently transmit both video and audio.

`audio`, `video`, `blur` properties

Just as their names suggest, these properties control the toggling of audio, video, and background blur respectively. Change the boolean values, and watch them get reflected in real-time.