liforma docs

Quick Start

Add an intelligent animated avatar to your app in minutes.

What you'll build

A live avatar that listens, thinks, speaks, and animates inside your app — with a single component. No backend required for public experiences.

1. Install

Choose Svelte or the framework-agnostic web component.

Svelte

npm install @liforma/client

Any framework (CDN)

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

2. Embed

This is the entire integration for a public experience:

Svelte

App.svelte
<script>
  import { LiformaExperience } from '@liforma/client/svelte';
<\/script>

<LiformaExperience experienceId="exp_01DEMO1SPANISHCAFE" />

Web component

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

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

3. Run

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

Try a live demo: www.liforma.ai/meet or the hosted player. See the Spanish Tutor example for a multi-lesson app.

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 — POST /v1/public-sessions with your experienceId
  • Fetches the Session Manifest — runtime configuration for this launch
  • Selects transport — connection strategy is declared in the manifest, hidden from you
  • Requests microphone access — when speech input is enabled
  • Runs speech recognition — browser STT in the client
  • Runs the AI response loop — language model, tools, and state updates
  • Synthesises speech — natural TTS with viseme timing
  • Renders the avatar — lip-sync, expressions, and animation
  • Manages lifecycle — listening, speaking, close, and teardown

4. Listen to events

Subscribe to conversation and mode changes when you need UI hooks:

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

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

experience.on('message', ({ role, text, final }) => {
  console.log(role, text, final);
});

experience.on('modeChange', ({ mode }) => {
  console.log('mode:', mode); // listening | speaking | thinking
});

await experience.attach({ container: '#avatar' });

See Listen to Events for the full event model.

5. Authenticated sessions (when you need them)

Public embeds are the default hello world. For private experiences, billing control, or user-specific sessions, your backend mints a manifest with an API key:

<LiformaExperience
  experienceId="exp_01DEMO1SPANISHCAFE"
  sessionEndpoint="/api/liforma-session"
/>

See Authenticated Experiences and the authenticated guide.