TruGen.AI JavaScript SDK

Official JavaScript/TypeScript client library for integrating TruGen.ai low-latency, real-time conversational video avatars into web applications.

Installation

npm install @trugen/js-sdk

Local Development

The quickest way to start testing the SDK is to use your API key directly with our SDK. To use the SDK, initialize a session using the createClientWithDevApiKey method:

import { createClientWithDevApiKey, TruGenEvent } from '@trugen/js-sdk';

const session = await createClientWithDevApiKey('your-api-key', {
  agentId: 'your-agent-id'
});

// Wire up track events to attach to a DOM video element
session.on(TruGenEvent.VIDEO_STREAM_STARTED, (track) => {
  const videoElement = document.getElementById('video-element-id');
  track.attach(videoElement);
});

await session.connect();

[!WARNING] The method createClientWithDevApiKey is unsafe for production use cases because it exposes your secret API key to the client. For production deployments, follow the instructions in the Usage in Production section below.

To stop a session, use the disconnect method:

await session.disconnect();

Features & Core Capabilities

The TruGenSession class exposes detailed primitives for advanced media control, real-time computer vision, and custom audio input.

Quick Example Snippets

Here are focused, copy-pasteable snippets for common SDK integrations.

1. Getting Started

Initialize and connect to the avatar using a backend-generated session JWT token:

import { createClient } from '@trugen/js-sdk';

const session = await createClient({
  token: 'YOUR_JWT_TOKEN'
});

await session.connect();

2. Media Track Access

Access WebRTC remote media tracks directly, or listen to when they go active:

// Get current active tracks
const videoTrack = session.getVideoTrack(); // RemoteVideoTrack | null
const audioTrack = session.getAudioTrack(); // RemoteAudioTrack | null

// Register callbacks for track activation
session.onVideoTrack((track) => {
  track.attach(document.getElementById('video-element-id'));
});

session.onAudioTrack((track) => {
  // Attach to audio element or WebAudio context
});

3. Video Frame Processing

Process remote decoded video frames in real-time. The SDK automatically handles WebCodecs (VideoFrame) and Canvas fallbacks (ImageData):

session.onVideoFrame((frame) => {
  if (frame instanceof ImageData) {
    // Canvas Fallback - raw pixel data
    const data = frame.data;
  } else {
    // WebCodecs VideoFrame - hardware decoded
    const width = frame.displayWidth;
    // Remember to close the frame to release GPU/memory!
    frame.close();
  }
});

4. Microphone Controls

Manage local hardware microphone publishing states:

// Toggle microphone manually
await session.stopMic();  // Deactivates & unpublishes mic
await session.startMic(); // Re-enables & publishes mic

// Get current state
const { isMuted, permissionState } = session.getInputAudioState();

5. Audio File & Stream Upload

Decodes a local file or raw audio stream on the client side and feeds it into the avatar conversation:

// Stream a pre-recorded audio file (e.g. WAV/MP3)
await session.uploadAudio(audioFile);

// Stream raw audio blob
await session.sendAudio(audioBlob);

Usage in Production

When deploying to production, exchange your API key for a short-lived session token (JWT) on your backend server.

1. Retrieve a Session Token (Server-side)

Your backend should handle authentication and return a single JWT token containing the required connection fields (rtcServerUrl, accessToken, agentId).

const response = await fetch('https://api.trugen.ai/v1/auth/conversation', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': apiKey,
  },
  body: JSON.stringify({
    agentId: 'your-agent-id'
  }),
});
const data = await response.json();
const sessionToken = data.token; // Single short-lived JWT token

2. Initialize the Session (Client-side)

import { createClient, TruGenEvent } from '@trugen/js-sdk';

// Under the hood, createClient decodes the JWT and returns a ready session instance
const session = await createClient({
  token: sessionToken
});

session.on(TruGenEvent.VIDEO_STREAM_STARTED, (track) => {
  const videoElement = document.getElementById('video-element-id');
  track.attach(videoElement);
});

await session.connect();