Skip to main content

Basic Usage

Learn the fundamentals of using the Kaltura Avatar Client SDK to display and control avatars.

Creating an SDK Instance​

First, create a KalturaAvatarSession instance:

import { KalturaAvatarSession } from '@unisphere/models-sdk-js';

// Option 1: With apiKey (SDK creates session)
const session = new KalturaAvatarSession('your-kaltura-session', {
  baseUrl: 'https://api.avatar.us.kaltura.ai/v1/avatar-session',
});

// Option 2: Without apiKey (backend creates session)
const session = new KalturaAvatarSession(undefined, {
  baseUrl: 'https://api.avatar.us.kaltura.ai/v1/avatar-session',
});

Constructor Parameters​

ParameterTypeRequiredDescription
apiKeystringOptionalYour Kaltura Session (KS) - only needed if SDK creates the session. Omit if backend creates it.
configobjectNoOptional configuration
apiKey Parameter
  • Pass it for FE-only control where the SDK creates sessions
  • Omit it (use undefined) for BE/FE split where backend creates sessions (recommended for production)

Configuration Options​

{
  baseUrl: string;              // Backend API URL (required for non-default endpoints)
  logLevel?: 'debug' | 'info' | 'warn' | 'error';  // Default: 'info'
}

Two Usage Patterns​

The SDK supports two patterns for displaying avatars:

The SDK automatically creates and attaches a video element:

await session.createSession({
  avatarId: 'avatar-123',
  voiceId: 'voice-456',
  videoContainerId: 'avatar-container', // SDK creates video element here
});

HTML:

<div id="avatar-container" style="width: 512px; height: 512px;"></div>

The SDK will:

  1. Create a <video> element
  2. Insert it into #avatar-container
  3. Set up WebRTC streaming
  4. Start playing automatically

Pattern 2: Manual Attach​

Create the session first, then attach the video manually:

// Step 1: Create session
await session.createSession({
  avatarId: 'avatar-123',
  voiceId: 'voice-456',
});

// Step 2: Manually attach video
session.attachAvatar('avatar-container');

When to use:

  • You need control over when the video appears
  • You want to add UI elements before showing the avatar
  • You need to perform checks before displaying

Complete Example: Auto-Attach​

import { KalturaAvatarSession } from '@unisphere/models-sdk-js';

async function initAvatar() {
  // Create SDK instance
  const session = new KalturaAvatarSession('your-api-key', {
    baseUrl: 'https://api.avatar.us.kaltura.ai/v1/avatar-session',
    logLevel: 'info',
  });

  // Setup event listeners
  session.on('stateChange', (state) => {
    console.log('Session state:', state);
  });

  session.on('error', (error) => {
    console.error('Error:', error.message);
  });

  try {
    // Create session with auto-attach
    await session.createSession({
      avatarId: 'avatar-123',
      voiceId: 'voice-456',
      videoContainerId: 'avatar-container',
    });

    console.log('Avatar ready! Session ID:', session.getSessionId());

    // Make avatar speak
    await session.sayText('Hello! I am your Kaltura Avatar.');
  } catch (error) {
    console.error('Failed to initialize avatar:', error);
  }
}

// Call when DOM is ready
initAvatar();

Complete Example: Manual Attach​

import { KalturaAvatarSession } from '@unisphere/models-sdk-js';

async function initAvatar() {
  const session = new KalturaAvatarSession('your-api-key', {
    baseUrl: 'https://api.avatar.us.kaltura.ai/v1/avatar-session',
  });

  try {
    // Step 1: Create session (no video yet)
    await session.createSession({
      avatarId: 'avatar-123',
      voiceId: 'voice-456',
    });

    console.log('Session created:', session.getSessionId());

    // Step 2: Show loading UI
    document.getElementById('loading').style.display = 'block';

    // Step 3: Attach video when ready
    session.attachAvatar('avatar-container');

    // Step 4: Hide loading UI
    document.getElementById('loading').style.display = 'none';

    // Step 5: Make avatar speak
    await session.sayText('Hello! I am ready.');
  } catch (error) {
    console.error('Failed to initialize avatar:', error);
  }
}

initAvatar();

Making the Avatar Speak​

Text-to-Speech​

await session.sayText('Hello, how are you doing today?');

Text is automatically chunked into 3-word segments for optimal processing:

  • Input: "Hello, how are you doing today?"
  • Chunks: ["Hello, how are", "you doing today"]

Audio File​

Audio must be MP3 at 44.1 kHz. Provide the duration and a unique turnId:

const arrayBuffer = await audioBlob.arrayBuffer();
const audioCtx = new AudioContext();
const decoded = await audioCtx.decodeAudioData(arrayBuffer);
await audioCtx.close();
const duration = decoded.duration;

const audioFile = new File([audioBlob], 'speech.mp3', { type: 'audio/mpeg' });
const turnId = `turn-${Date.now()}`;
await session.sayAudio(audioFile, turnId, duration);

Controlling the Avatar​

Interrupt Speech​

Stop the avatar mid-speech:

await session.interrupt();

End Session​

Clean up and end the session:

await session.endSession();

This will:

  • Stop keep-alive
  • Disconnect WebRTC
  • End the backend session
  • Clean up all resources

Keep-Alive​

The SDK automatically sends keep-alive signals every 10 seconds once a session is created. This ensures:

  • Session remains active
  • Backend doesn't terminate the session
  • Resources are properly maintained
Automatic Management

You don't need to manage keep-alive manually. It starts automatically when the session is ready and stops when you call endSession().

Video Element Details​

When the SDK creates a video element, it has:

  • autoplay and playsinline attributes
  • Width and height set to 100%
  • Appropriate styling for fullscreen display within the container

Generated HTML:

<div id="avatar-container">
  <video autoplay playsinline style="width: 100%; height: 100%; object-fit: cover;"></video>
</div>

Common Patterns​

Initialize on Button Click​

BY using this pattern, you provide a better UX by allowing users to control when the avatar initializes. This is also good for browsers autoplay policies that require user interaction.

document.getElementById('start-btn').addEventListener('click', async () => {
  const session = new KalturaAvatarSession('your-api-key', {
    baseUrl: 'https://api.avatar.us.kaltura.ai/v1/avatar-session',
  });

  await session.createSession({
    avatarId: 'avatar-123',
    videoContainerId: 'avatar-container',
  });

  await session.sayText('Hello! You clicked the start button.');
});

Next Steps​