Skip to main content

Initialising Video API Overview

Push Video API abstract away connection and encryption methods to enable seamless video calls between wallets.

Prerequisites​

  • You need to initialize use and setup video stream before initializing video.
  • You also need to declare data, setData which are essentially a state/variable to hold video call-related data with a callback function to react to changes in video state.

Initialize video API​

// state to handle current video call data
const [data, setData] = useState(CONSTANTS.VIDEO.INITIAL_DATA);

// userAlice.video.initialize(onChange, {options?});
const aliceVideoCall = await userAlice.video.initialize(setData, {
  stream: stream, // pass the stream object, refer Stream Video
  config: {
    video: true, // to enable video on start, for frontend use
    audio: true, // to enable audio on start, for frontend use
  },
  media?: MediaStream, // to pass your existing media stream(for backend use)
});

Initialize video parameters​

ParamTypeSub-TypeDefaultRemarks
onChangeconstant--Function to update the video call data, takes a function as an argument which receives the latest state of data as a param and should return the modified/new state of data
optionsVideoInitializeOptions--configuration properties for initializing the video.
-options.streamPushStream-Option to configure to enable listening to only certain chats or notifications.
-options.config.videoboolean-pass trueto enable video on start, else pass false.
-options.config.audioboolean-pass trueto enable audio on start, else pass false.
-options.mediaMediaStream-Local stream. For backend use. Defaults to null.

Note: Parameters in this style are mandatory.

Understanding Video Lifecycle​

data variable​

  • The data variable is an object that is used to store all of the video call-related data.
  • It is of type TYPES.VIDEO.DATA and should be initialized with CONSTANTS.VIDEO.INITIAL_DATA.
  • For React-based projects, this would basically be a React state, and for vanilla JS projects, it will be a simple JS variable.

The type TYPES.VIDEO.DATA is described below:

// IMediaStream is a custom type that represents a media stream object or null
type IMediaStream = MediaStream | null;

// VideoCallStatus is an enum that represents different statuses of a video call
// These values are used to indicate the current status of a video call
enum VideoCallStatus {
  // call hasn't been started yet
  UNINITIALIZED,

  // call has been started by the initiator but not received by the receiver
  INITIALIZED,

  // call has been received by the receiver but not connected yet
  RECEIVED,

  // call has been connected, and both users can interact now
  // MediaStream (includes both audio and video) exchange is now possible
  CONNECTED,

  // when the call request is denied by the peer (receiver)
  DISCONNECTED,

  // call has been ended by one of the users
  ENDED

  // retrying to establish the call from the INITIALIZED state
  RETRY_INITIALIZED,

  // retrying to establish the call from the RECEIVED state
  RETRY_RECEIVED,
}

type VideoCallData = {
  meta: {
    // contains meta info of the video call
    chatId: string; // unique identifier for every push chat
    initiator: {
      address: string; // address of the initiator of the call
      signal: any; // signal data from the initiator
    };
    broadcast?: {
      // will be used in Push Spaces
      livepeerInfo: any;
      hostAddress: string;
      coHostAddress: string;
    };
  };
  // This property is used to store the info of the local peer/user
  local: {
    stream: IMediaStream; // the stream object
    audio: boolean | null; // whether local audio is on or not
    video: boolean | null; // whether local video is on or not
    address: string; // address of the local peer/user
  };
  incoming: [
    // This property is used to store the info of an incoming peer/user
    {
      stream: IMediaStream; // the stream object
      audio: boolean | null; // whether incoming audio is on or not
      video: boolean | null; // whether incoming video is on or not
      address: string; // address of the incoming peer/user
      status: VideoCallStatus; // video call status with a particular incoming peer
      retryCount: number; // no. of retries required in establishing the call
    },
  ];
};

The CONSTANTS.VIDEO.INITIAL_DATA looks like the following:

// As mentioned earlier, this should be used to initialize the data variable.
{
  meta: {
    chatId: "",
    initiator: {
      address: "",
      signal: null,
    },
  },
  local: {
    stream: null,
    audio: null,
    video: null,
    address: "",
  },
  incoming: [
    {
      stream: null,
      audio: null,
      video: null,
      address: "",
      status: CONSTANTS.VIDEO.STATUS.UNINITIALIZED, // call is at the UNINITIALIZED status
      retryCount: 0,
    },
  ],
};

Creating and initializing the data variable is shown below:

import { TYPES, CONSTANTS } from '@pushprotocol/restapi';

// 1. For a vanilla JS project
let data: TYPES.VIDEO.DATA = CONSTANTS.VIDEO.INITIAL_DATA;

// 2. For a React project
import { useState } from 'react';
const [data, setData] = useState<TYPES.VIDEO.DATA>(
  CONSTANTS.VIDEO.INITIAL_DATA
);

setData function​

  • setData is a function to update the video call data i.e., the data variable.
  • It is of type (fn: (data: TYPES.VIDEO.DATA) => TYPES.VIDEO.DATA) => void and is described below:
/*
- fn function is supplied by the caller of setData()
- fn is a function that accepts current 'data' as input and returns updated 'data'
*/
const setData = (fn: (data: TYPES.VIDEO.DATA) => TYPES.VIDEO.DATA): void => {
  /*
    - Here, we are passing the current value of 'data' to fn
    - The return value of fn() i.e., the updated value of 'data' is assigned back to 'data'
  */
  data = fn(data);
};