@liforma/client

Browser SDK for Liforma — embed real-time AI avatar experiences in web apps.

Experience (exp_…) → Session Manifest → @liforma/client

Docs: docs.liforma.ai · Quick start · llms.txt
Examples: examples.liforma.ai
Portal (API keys & origins): app.liforma.ai

Install

npm install @liforma/client

Optional peers: svelte ^5 for the Svelte entry; react / react-dom ^18 or ^19 for React / Next; @elevenlabs/client for /elevenlabs; livekit-client for /livekit. /openai, /deepgram, and /google use the browser WebSocket API (no extra peer). Shared BYO primitives live in @liforma/client/byo (used by the vendor helpers; rarely imported directly).

Hello world

Svelte

<script>
  import { Experience } from '@liforma/client/svelte';
</script>

<Experience experienceId="exp_01EXAMPLES_COFFEE_BARISTA" />

Gallery cards — use the light thumbnail entry so landing pages do not load the session SDK:

<script>
  import { ExperienceThumbnail } from '@liforma/client/svelte/thumbnail';
</script>

import { ExperienceThumbnail } from '@liforma/client/react/thumbnail';
// or: import { ExperienceThumbnail } from '@liforma/client/next/thumbnail';

<script src="https://cdn.liforma.ai/sdk/v2/thumbnail.js" defer></script>
<liforma-experience-thumbnail experience-id="exp_…" alt="…"></liforma-experience-thumbnail>

React

import { Experience } from '@liforma/client/react';

export function Demo() {
  return <Experience experienceId="exp_01EXAMPLES_COFFEE_BARISTA" />;
}

Next.js (App Router session route)

import { createLiformaSessionRouteHandler } from '@liforma/client/next';

export const POST = createLiformaSessionRouteHandler({
  // Production: supply authorize() that checks your app session.
  allowUnauthenticated: true // demos only
});

'use client';

import { Experience } from '@liforma/client/next';

export function Demo() {
  return (
    <Experience
      experienceId="exp_01EXAMPLES_COFFEE_BARISTA"
      sessionEndpoint="/api/liforma-session"
    />
  );
}

Vanilla (CDN)

<script src="https://cdn.liforma.ai/sdk/v2/client.js" defer></script>
<liforma-experience experience-id="exp_01EXAMPLES_COFFEE_BARISTA"></liforma-experience>

Package entry points

| Import | Surface | |--------|---------| | @liforma/client | JS API (Experience.startSession, types) | | @liforma/client/svelte | <Experience />, <ExperienceThumbnail />, <ExperienceWidget /> | | @liforma/client/svelte/thumbnail | <ExperienceThumbnail /> only (prefer for galleries) | | @liforma/client/thumbnail | Shared thumbnail helpers (no session player) | | @liforma/client/react | React components | | @liforma/client/react/thumbnail | <ExperienceThumbnail /> only (prefer for galleries) | | @liforma/client/next | Next helpers + client components | | @liforma/client/next/thumbnail | <ExperienceThumbnail /> only (prefer for galleries) | | @liforma/client/byo | Shared BYO primitives (PCM/mic/turn helpers) | | @liforma/client/elevenlabs | connectElevenLabsAgent (BYO ElevenLabs Agents → avatar) | | @liforma/client/openai | connectOpenAiRealtime / connectOpenAiRealtimeWebRtc (BYO OpenAI Realtime → avatar) | | @liforma/client/deepgram | connectDeepgramAgent (BYO Deepgram Voice Agent → avatar) | | @liforma/client/google | connectGeminiLive (BYO Gemini Live → avatar) | | @liforma/client/livekit | connectLiveKitAgent (BYO LiveKit remote track → avatar) | | CDN sdk/v2/client.js | Web components + window.Liforma | | CDN sdk/v2/thumbnail.js | <liforma-experience-thumbnail> only |

Session minting

| Situation | Path | |-----------|------| | You have a backend | Mint with API key via POST /v1/sessions; pass a same-origin sessionEndpoint to the component | | Client-only / public demos | Allowlist your origin in the developer portal; the SDK mints via POST /v1/public-sessions |

Never put API keys in browser code. Details: Server sessions, Browser embeds.

Speech API

import { Experience } from '@liforma/client';

const experience = await Experience.startSession({ experienceId: 'exp_…' });
await experience.attach({ container: '#avatar' });

experience.on('started', async () => {
  // Liforma TTS
  await experience.speech.speak({ text: 'Hello from Liforma.' });

  // Bring-your-own: PCM, encoded bytes, URL, or MediaStreamTrack
  await experience.speech.play({
    audio: { url: 'https://cdn.example.com/line.mp3' },
    queue: 'append'
  });

  // Vendor BYO helpers (install optional peers as needed):
  // import { connectElevenLabsAgent } from '@liforma/client/elevenlabs';
  // import { connectOpenAiRealtime } from '@liforma/client/openai';
  // import { connectDeepgramAgent } from '@liforma/client/deepgram';
  // import { connectGeminiLive } from '@liforma/client/google';
  // import { connectLiveKitAgent } from '@liforma/client/livekit';
});

| Capability | Methods | |------------|---------| | textSpeech | speech.speak | | externalSpeechAudio | speech.play, speech.createUtterance, speech.interrupt |

Streaming vendors: open one utterance per agent turn, write PCM chunks, close on turn end — see Bring your own voice.

More components

• ExperienceThumbnail — gallery cards (no session)
• ExperienceWidget — corner launcher
• Experience API — speech.*, listen, events

License

MIT