Quick Start

What you'll build

A live avatar that listens, thinks, speaks, and animates inside your app — with a single component. This hello world uses a browser embed (origin allowlist); no backend required. If you have a server, prefer API-key minting.

1. Install

Install the SDK once, then import the entry for your framework. The CDN script works in any framework.

npm

npm install @liforma/client

Any framework (CDN)

<script src="https://cdn.liforma.ai/sdk/v2/client.js"><\/script>

2. Embed

This is the entire client-side integration (browser mint via allowed origins):

Svelte

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

<Experience experienceId="exp_T0I7ACMQLBMPG6K" />

React

Use @liforma/client/react. In Next.js App Router, put this in a client component ('use client').

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

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

Web component

<script src="https://cdn.liforma.ai/sdk/v2/client.js"><\/script>

<liforma-experience experience-id="exp_T0I7ACMQLBMPG6K"></liforma-experience>

Full walkthroughs: Svelte, React, Next.js.

3. Run

Open your app. The SDK mints a Session Launch and starts the runtime. Allowlist your production origin in the developer portal (app.liforma.ai → your project → Origins) so browser embeds work on your domain.

Try a live demo: www.liforma.ai/meet or the hosted player. See the examples gallery and Spanish Tutor live demo for full sample apps.

Run examples locally

Clone the examples.liforma.ai repository to explore runnable integrations:

git clone https://github.com/LiformaLtd/examples.liforma.ai.git
cd examples.liforma.ai
npm install
./start

That opens the gallery on http://localhost:4000 and runnable demos on 4001–4010. See the examples gallery for the current list. Framework modes share those ports:

• ./start or ./start vanilla — HTML examples
• ./start sveltekit — SvelteKit variants
• ./start nextjs — guided-practice Next.js on :4003
• ./start react-vite — guided-practice React (Vite) on :4003

Examples call production Liforma APIs — no local API or player required.

Developer portal (create your own experience)

To ship your own exp_… id instead of a demo experience:

1. Sign in at app.liforma.ai
2. Create or open a project → Experience Studio → publish
3. Add your site origin under Origins
4. Copy the experience id from the Integrate tab
5. Paste the id into your embed (same code as step 2 above)

What Liforma handles for you

You do not wire transport, tokens, or media pipelines. Liforma automatically:

• Creates the session — browser mint via POST /v1/browser-sessions with your experienceId
• Receives a Session Launch — public session plus opaque launch
• Starts the player — transport and pipeline stay inside launch, hidden from you
• Requests microphone access — when speech input is enabled
• Runs speech recognition — when speech input is enabled
• Runs the AI response loop — language model, tools, and state updates
• Synthesises speech — natural TTS
• Renders the avatar — lip-sync, expressions, and animation
• Manages lifecycle — listening, speaking, close, and teardown

4. Listen to events

Subscribe to conversation and activity updates when you need UI hooks. Events arrive as envelopes ({ id, type, sessionId, timestamp, data }); use activityChange for idle / listening / thinking / speaking, and onPlayerStatusChange on attach() for player chrome status. You never need to inspect launch.

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

const experience = await Experience.startSession({
  experienceId: 'exp_T0I7ACMQLBMPG6K'
});

experience.on('message', (evt) => {
  // ExperienceEventEnvelope<data: ConversationMessage>
  console.log(evt.data.role, evt.data.text, evt.data.status);
});

experience.on('activityChange', (evt) => {
  // evt.data: 'idle' | 'listening' | 'thinking' | 'speaking'
  console.log('activity:', evt.data);
});

const player = await experience.attach({
  container: '#avatar',
  onPlayerStatusChange: (status) => console.log('Player status', status)
});

player.on('close', ({ reason }) => {
  console.log('Player closed', reason);
});

See Listen to Events for the full event model.

5. Server sessions (preferred when you have a backend)

Browser embeds are the simplest hello world. When you have a server, mint with an API key so the key never reaches the browser — and so you can pass per-user context.

Svelte

<Experience
  experienceId="exp_T0I7ACMQLBMPG6K"
  sessionEndpoint="/api/liforma-session"
/>

React / Next.js

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

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

In Next.js, pair that with createLiformaSessionRouteHandler() from @liforma/client/next on app/api/liforma-session/route.ts. See Experience (Next.js), Server sessions, and the server-session guide.