Web SDK

TgoRTC Web (JavaScript/React) SDK for real-time audio/video communication based on LiveKit.

Installation

npm install tgortc-js-sdk
# or
yarn add tgortc-js-sdk
# or
pnpm add tgortc-js-sdk

Peer Dependencies

npm install react react-dom

Quick Start

1. Initialize SDK

import { TgoRTC } from 'tgortc-js-sdk';

// Initialize with options
TgoRTC.instance.init({
  debug: true,   // Enable debug logging
  mirror: false, // Enable video mirroring
});

2. Create Room Info and Join

import { RoomInfo, RTCType } from 'tgortc-js-sdk';

// Create room info
const roomInfo = new RoomInfo(
  'room-name',           // Room name
  'your-token',          // LiveKit Token
  'wss://your-server',   // LiveKit server URL
  'local-user-id',       // Current user ID
  'creator-user-id'      // Room creator ID
);

// Optional: Configure room settings
roomInfo.maxParticipants = 4;
roomInfo.rtcType = RTCType.Video;
roomInfo.timeout = 30; // Participant join timeout in seconds

// Join room
await TgoRTC.instance.roomManager.joinRoom(roomInfo, {
  micEnabled: true,
  cameraEnabled: true,
  screenShareEnabled: false,
});

3. Listen to Connection Status

import { ConnectStatus } from 'tgortc-js-sdk';

const handleConnectStatus = (
  roomName: string,
  status: ConnectStatus,
  reason: string
) => {
  console.log(`Room ${roomName}: ${status} - ${reason}`);
  
  switch (status) {
    case ConnectStatus.Connected:
      console.log('Connected to room');
      break;
    case ConnectStatus.Disconnected:
      console.log('Disconnected from room');
      break;
    case ConnectStatus.Reconnecting:
      console.log('Reconnecting...');
      break;
  }
};

// Add listener
TgoRTC.instance.roomManager.addConnectListener(handleConnectStatus);

// Remove listener
TgoRTC.instance.roomManager.removeConnectListener(handleConnectStatus);

4. Get Participants

// Get local participant
const localParticipant = TgoRTC.instance.participantManager.getLocalParticipant();

// Get all remote participants
const remoteParticipants = TgoRTC.instance.participantManager.getRemoteParticipants();

// Get all participants (local + remote)
const allParticipants = TgoRTC.instance.participantManager.getAllParticipants();

// Listen for new participants
TgoRTC.instance.participantManager.addNewParticipantListener((participant) => {
  console.log('New participant joined:', participant.uid);
});

5. Media Control and Events

Media control is only available for local participants.

const participant = TgoRTC.instance.participantManager.getLocalParticipant();

if (participant) {
  // ========== Media Control ==========
  
  // Toggle microphone (local participant only)
  await participant.setMicrophoneEnabled(true);
  
  // Toggle camera (local participant only)
  await participant.setCameraEnabled(true);
  
  // Toggle screen share (local participant only)
  await participant.setScreenShareEnabled(true);
  
  // Switch camera front/back (local participant only)
  await participant.switchCamera();
  
  // Toggle speakerphone (local participant only)
  await participant.toggleSpeakerphone();

  // Check media status
  const micEnabled = participant.getMicrophoneEnabled();
  const cameraEnabled = participant.getCameraEnabled();
  const speakerEnabled = participant.getSpeakerEnabled();

  // ========== Event Listeners ==========

  // Microphone status change
  participant.addMicrophoneStatusListener((enabled) => {
    console.log('Microphone:', enabled ? 'on' : 'off');
  });

  // Camera status change
  participant.addCameraStatusListener((enabled) => {
    console.log('Camera:', enabled ? 'on' : 'off');
  });

  // Speaker status change
  participant.addSpeakerStatusListener((enabled) => {
    console.log('Speaker:', enabled ? 'on' : 'off');
  });

  // Speaking status change
  participant.addSpeakingListener((isSpeaking) => {
    console.log('Speaking:', isSpeaking);
  });

  // Connection quality change (good / poor / unknown)
  participant.addConnQualityListener((quality) => {
    console.log('Connection quality:', quality);
  });

  // Participant joined room
  participant.addJoinedListener(() => {
    console.log('Participant joined');
  });

  // Participant left room
  participant.addLeaveListener(() => {
    console.log('Participant left');
  });

  // Participant timeout (did not join within specified time)
  participant.addTimeoutListener(() => {
    console.log('Participant timeout');
  });

  // Video info change (resolution, bitrate, etc.)
  participant.addVideoInfoListener((info) => {
    console.log('Video info:', info.width, 'x', info.height, info.frameRate, 'fps');
  });

  // ========== Remove Listeners ==========

  // Always remove listeners when page is disposed to avoid memory leaks
  participant.removeMicrophoneStatusListener(listener);
  participant.removeCameraStatusListener(listener);
  participant.removeSpeakerStatusListener(listener);
  participant.removeConnQualityListener(listener);
  participant.removeJoinedListener(listener);
  participant.removeLeaveListener(listener);
  participant.removeTimeoutListener(listener);
  participant.removeVideoInfoListener(listener);
}

6. Render Video Track (React Component)

import { useRef, useState, useEffect } from 'react';
import { 
  TgoTrackRenderer, 
  TgoTrackRendererHandle,
  TgoParticipant,
  TgoRTC 
} from 'tgortc-js-sdk';
import { Track } from 'livekit-client';

function VideoView() {
  const rendererRef = useRef<TgoTrackRendererHandle>(null);
  const [participant, setParticipant] = useState<TgoParticipant | null>(null);

  useEffect(() => {
    const local = TgoRTC.instance.participantManager.getLocalParticipant();
    setParticipant(local);
  }, []);

  return (
    <TgoTrackRenderer
      ref={rendererRef}
      participant={participant}
      source={Track.Source.Camera}
      fit="cover"
      mirror={true}
      placeholder={<div>Waiting for video...</div>}
      onTrackChange={(hasTrack) => {
        console.log('Track available:', hasTrack);
      }}
    />
  );
}

7. Audio Device Management

// Get audio devices
const inputDevices = await TgoRTC.instance.audioManager.getAudioInputDevices();
const outputDevices = await TgoRTC.instance.audioManager.getAudioOutputDevices();

// Listen to device changes
TgoRTC.instance.audioManager.addDeviceChangeListener((devices) => {
  console.log('Devices changed:', devices);
});

// Toggle speakerphone
await TgoRTC.instance.audioManager.toggleSpeakerphone();

8. Leave Room

await TgoRTC.instance.roomManager.leaveRoom();

API Reference

TgoRTC

Main SDK entry point (singleton).

Property	Type	Description
instance	TgoRTC	Singleton instance
options	Options	SDK configuration
roomManager	TgoRoomManager	Room management
participantManager	TgoParticipantManager	Participant management
audioManager	TgoAudioManager	Audio device management

TgoRoomManager

Method	Description
joinRoom(roomInfo, options?)	Join a room
leaveRoom()	Leave current room
addConnectListener(listener)	Add connection status listener
removeConnectListener(listener)	Remove connection status listener

TgoParticipantManager

Method	Description
getLocalParticipant()	Get local participant
getRemoteParticipants(includeTimeout?)	Get remote participants
getAllParticipants(includeTimeout?)	Get all participants
inviteParticipant(uids)	Invite participants by UID
addNewParticipantListener(listener)	Listen for new participants

TgoParticipant

Media Control Methods

Method	Description
setMicrophoneEnabled(enabled)	Enable/disable microphone
setCameraEnabled(enabled)	Enable/disable camera
setScreenShareEnabled(enabled)	Enable/disable screen share
switchCamera()	Switch front/back camera
toggleSpeakerphone()	Toggle speakerphone

Status Methods

Method	Description
getMicrophoneEnabled()	Get microphone status
getCameraEnabled()	Get camera status
getScreenShareEnabled()	Get screen share status
getSpeakerEnabled()	Get speakerphone status
getVideoTrack(source?)	Get video track
getAudioLevel()	Get audio level (0-1)
getIsSpeaking()	Check if speaking

Event Listener Methods

Method	Description
addMicrophoneStatusListener(listener)	Listen for microphone changes
addCameraStatusListener(listener)	Listen for camera changes
addSpeakerStatusListener(listener)	Listen for speaker changes
addSpeakingListener(listener)	Listen for speaking status
addConnQualityListener(listener)	Listen for connection quality
addJoinedListener(listener)	Listen for participant join
addLeaveListener(listener)	Listen for participant leave
addTimeoutListener(listener)	Listen for participant timeout
addVideoInfoListener(listener)	Listen for video info changes
remove...Listener(listener)	Remove corresponding listener

Properties

Property	Type	Description
uid	string	Participant ID
isLocal	boolean	Is local participant
hasJoined	boolean	Has joined room
isTimeout	boolean	Has timed out
currentVideoInfo	VideoInfo	Current video info

TgoTrackRenderer (React Component)

Prop	Type	Default	Description
participant	TgoParticipant | null	-	Participant to render
source	Track.Source	Camera	Track source type
fit	'cover' | 'contain' | 'fill'	'cover'	Video fit mode
mirror	boolean	SDK option	Mirror video
placeholder	ReactNode	-	Placeholder when no video
onTrackChange	(hasTrack: boolean) => void	-	Track change callback

Ref Method	Description
refresh()	Manually refresh video track
setParticipant(participant)	Update participant

Enums

ConnectStatus

enum ConnectStatus {
  Connecting = 'connecting',     // Connecting
  Connected = 'connected',       // Connected
  Reconnecting = 'reconnecting', // Reconnecting
  Reconnected = 'reconnected',   // Reconnected
  Disconnected = 'disconnected', // Disconnected
}

RTCType

enum RTCType {
  Audio = 'audio',  // Audio only
  Video = 'video',  // Audio + Video
}

TgoConnectionQuality

enum TgoConnectionQuality {
  Unknown = 'unknown',     // Unknown
  Excellent = 'excellent', // Excellent
  Good = 'good',           // Good
  Poor = 'poor',           // Poor
  Lost = 'lost',           // Lost
}

TgoCameraPosition

enum TgoCameraPosition {
  Front = 'front',  // Front camera
  Back = 'back',    // Back camera
}

RoomInfo Class

Room information class for configuring room connections.

class RoomInfo {
  roomName: string;        // Room name
  token: string;           // LiveKit Token
  url: string;             // LiveKit server URL
  loginUID: string;        // Current user ID
  creatorUID: string;      // Room creator ID
  maxParticipants: number; // Max participants (default 2)
  rtcType: RTCType;        // Call type (default Audio)
  isP2P: boolean;          // Is P2P (default true)
  uidList: string[];       // Participant list
  timeout: number;         // Timeout in seconds (default 30)
  
  // Methods
  getP2PToUID(): string;   // Get P2P target user
  isCreator(): boolean;    // Check if creator
}

Configuration Options

interface Options {
  mirror: boolean;  // Video mirroring (default false)
  debug: boolean;   // Debug mode (default true)
}

Best Practices

Use useRef to Store Participant Reference

In React, use useRef to store participant reference to avoid stale closures in event listeners:

import { useRef, useEffect, useCallback } from 'react';
import { TgoRTC, TgoParticipant } from 'tgortc-js-sdk';

function CallPage({ roomInfo }) {
  const localParticipantRef = useRef<TgoParticipant | null>(null);
  const cleanupRef = useRef<(() => void) | null>(null);

  useEffect(() => {
    const joinRoom = async () => {
      await TgoRTC.instance.roomManager.joinRoom(roomInfo, {
        micEnabled: true,
        cameraEnabled: true,
      });

      // Store participant reference
      const participant = TgoRTC.instance.participantManager.getLocalParticipant();
      localParticipantRef.current = participant;

      // Add listeners and save cleanup function
      if (participant) {
        const onMicChange = (enabled: boolean) => console.log('Mic:', enabled);
        const onCameraChange = (enabled: boolean) => console.log('Camera:', enabled);
        
        participant.addMicrophoneStatusListener(onMicChange);
        participant.addCameraStatusListener(onCameraChange);

        cleanupRef.current = () => {
          participant.removeMicrophoneStatusListener(onMicChange);
          participant.removeCameraStatusListener(onCameraChange);
        };
      }
    };

    joinRoom();

    return () => {
      // Cleanup listeners
      cleanupRef.current?.();
      // Leave room
      TgoRTC.instance.roomManager.leaveRoom();
    };
  }, [roomInfo]);

  const handleMicToggle = useCallback(async () => {
    const participant = localParticipantRef.current;
    if (participant) {
      const current = participant.getMicrophoneEnabled();
      await participant.setMicrophoneEnabled(!current);
    }
  }, []);

  return <button onClick={handleMicToggle}>Toggle Mic</button>;
}

Listen for Remote Participants

Use addNewParticipantListener to listen for new participants and add event listeners:

const participantManager = TgoRTC.instance.participantManager;

// Listen for new participants
participantManager.addNewParticipantListener((participant) => {
  console.log('New participant:', participant.uid);

  // Listen to remote participant events
  participant.addJoinedListener(() => {
    console.log(`${participant.uid} joined`);
  });

  participant.addLeaveListener(() => {
    console.log(`${participant.uid} left`);
  });

  participant.addCameraStatusListener((enabled) => {
    console.log(`${participant.uid} camera:`, enabled);
  });
});

Handle Timeout

Use addTimeoutListener to handle participant timeout (did not join within specified time):

// Listen for remote participant timeout
remoteParticipant.addTimeoutListener(() => {
  console.log('Remote user did not answer, ending call');
  handleHangup();
});

// Listen for local timeout (room connection timeout)
localParticipant.addTimeoutListener(() => {
  console.log('Connection timeout');
  handleHangup();
});