JavaScript SDK · Liforma Docs

Install

npm install @liforma/client

Or load from CDN (v2 speak API):

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

Primary API

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

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

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

Exports

Export	Description
`Experience`	Session lifecycle, speech API, events, and conversation getters
`LiformaExperience`	Svelte component (from `@liforma/client/svelte`)

Lifecycle

await experience.attach({ container });
experience.pause();
experience.resume();
await experience.end();

attach() mounts the player iframe. ready fires when visuals are mounted; started fires after the player start button unlocks audio — required before speech APIs. See Events.

Speech API

Presenter sessions, manual listening, automatic capture, and custom processors. Requires attach() and the started event. Full reference: Experience API.

Method	Returns	Purpose
`speak(options)`	`Promise<SpeechResult>`	Animated character speech (`text`, optional `characterId`, `behavior`)
`startListening()`	`Promise<void>`	Open manual listening gate (`speechInputMode: 'manual'`)
`stopListening()`	`Promise<UtteranceResult>`	Close gate and finalize utterance
`listenOnce(options?)`	`Promise<UtteranceResult>`	One automatic end-of-speech capture (`speechInputMode: 'auto'`)
`getConversation()`	`readonly ConversationMessage[]`	Flat ordered session history snapshot
`getLastTurn()`	`readonly ConversationMessage[]`	Messages in the latest turn

Session options

Pass conversationProcessor and onUserTranscript on Experience.startSession(). See Custom Conversation Processor.

Presenter + manual listening

const experience = await Experience.startSession({
  experienceId: 'exp_01DEMO1SPANISHCAFE',
  mode: 'presenter',
  speechInputMode: 'manual'
});

experience.on('started', async () => {
  await experience.speak({ text: 'Welcome to the lesson.' });
});

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

`speak()`

const result = await experience.speak({
  text: 'Repeat after me: Buenos días.',
  characterId: 'char_…', // optional — defaults to activeCharacterId
  behavior: 'enqueue' // optional — enqueue (default) or interrupt
});

console.log(result.turnId, result.durationMs);

Manual listening

await experience.startListening();
// Learner speaks; pauses do not end the utterance in manual mode.
const utterance = await experience.stopListening();
console.log(utterance.utteranceId, utterance.text);

`listenOnce()`

const experience = await Experience.startSession({
  experienceId: 'exp_01DEMO1SPANISHCAFE',
  mode: 'presenter',
  speechInputMode: 'auto'
});

experience.on('started', async () => {
  await experience.speak({ text: 'What is your party size?' });
  const answer = await experience.listenOnce({ timeoutMs: 15_000 });
  console.log(answer.utteranceId, answer.text);
});

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

Conversation getters

const history = experience.getConversation();
const lastTurn = experience.getLastTurn();

experience.on('conversationUpdate', (conversation) => {
  console.log('History length', conversation.length);
});

Events

Register handlers with experience.on(event, handler). Speech-related events include ready, started, userTranscript, userSpeechStarted, userSpeechEnded, characterSpeechStarted, characterSpeechEnded, conversationUpdate, conversationProcessorError, and listeningState. See the full list on Events.

Patterns: Guided Scripted Practice, Listen Once Capture, Custom Conversation Processor.