Skip to main content

Read aloud

Archived SDK documentation

This page preserves the previous SDK documentation and its existing URL. The generated API reference was produced from SDK 0.1.5, source commit 4db9fbe925bf07a4b95e936a5bb172d6ab5820bb. Handbook behavior and compatibility claims below are historical descriptions, not a newly verified support guarantee. For the reviewed version-specific reference, see the SDK 0.1.5 overview.

The highest-level use of the SDK: send a string, hear the AI speak it. The SDK opens an audio_playback session, streams the TTS audio over the channel WebSocket, plays it via new Audio(), and resolves a promise when the audio finishes.

This mirrors the ReadAloudDemo.tsx example in the SDK's React examples app.

Prerequisites​

Minimum viable example​

import {DelphiClient} from '@ki-kombinat/delphi-client-js-sdk';

const delphi = new DelphiClient({
  apiDomain: 'api.delphi.ki-kombinat.com',
  apiKey: 'sk_live_…',
});

await delphi.readAloud('Hello, world!', {
  endpointId: '24599c70-1e79-4e52-9819-e2d97acf45a5',
});

That's it. The server picks the right read-aloud browser action; you only supply the text. Repeated calls reuse the same session and conversation thread.

Interruptible playback

A new read-aloud (or audio browser-action) request immediately stops whatever is currently playing and resets the SDK playback queue so the fresh response starts without waiting. Wait on audioDone() when you need sequential playback. From SDK 0.1.4, SessionState.audioRequestPending / audioPlaying and onAudioPlaybackStart / onAudioPlaybackEnd expose the browser playback lifecycle for spinners and UI state.

When the server splits TTS into sentence-level MP3 segments, the SDK queues them as one logical response — audioDone() still resolves once for the full reply.

Options​

await delphi.readAloud('Some text', {
  endpointId: '24599c70-1e79-4e52-9819-e2d97acf45a5',

  metadata: {from: 'highlight'},

  // Disambiguate when an endpoint has multiple read-aloud BOAs.
  capabilityId: 'cap_123',
  identifier: 'tts-fast',

  // Override the BOA message-type if your runtime uses a custom one.
  messageType: 'browser.action.readAloudFast',

  // Cancel mid-flight.
  signal: abortController.signal,

  // Skip the SDK's built-in audio playback (handle audio yourself).
  disableAutoPlay: true,
  onAudio: (event) => myAudioPlayer.play(event.dataUrl),
});

Inspect the audio​

The promise resolves with the assembled BrowserAudioEvent:

const audio = await delphi.readAloud('Welcome back!', {endpointId});

console.log(audio.dataUrl); // data: URL ready to feed into <audio>
console.log(audio.mimeType); // e.g. 'audio/wav'
console.log(audio.metadata); // BOA metadata from the server

Closing the session​

// Close just audio playback for this endpoint.
await delphi.endSession(endpointId, 'audio_playback');

// Or close every mode for this endpoint at once.
await delphi.endSession(endpointId);

Power-user variant​

If you want explicit control over the session lifecycle and the ability to push browser context the AI can reference:

const session = await delphi.openSession({
  endpointId,
  mode: 'audio_playback',
});

session.setBrowserContext({
  text: document.querySelector('article')?.innerText ?? '',
  source: 'page',
  url: window.location.href,
});

session.sendBrowserAction({
  messageType: 'browser.action.readAloud',
});
await session.audioDone();

session.sendBrowserAction({
  messageType: 'browser.action.transformAndRead',
  text: 'Summarise the article.',
});
await session.audioDone();

await session.close();

To drive a spinner from request send until browser playback starts/ends:

session.updateOptions({
  onAudioPlaybackStart: () => hideSpinner(),
  onAudioPlaybackEnd: () => hideSpinner(),
});

// session.getState() also exposes audioRequestPending / audioPlaying

Next step​

Try the voice call quick start, or jump straight to the React guide for useDelphiSession.