Browser Setup - Lokutor

Constraints

Constraint	Solution
Microphone and AudioContext need a user gesture	Call `startManaged()` inside a button click handler
AudioContext starts in `suspended` state	Call `audioContext.resume()` after the user gesture
No filesystem access for saving audio	Use `Blob` and `URL.createObjectURL`
Anything in the page is public	Never ship an API key: pass a short-lived ticket from your backend

Quick setup (Vite)

npm create vite@latest my-app -- --template vanilla-ts
cd my-app
npm install @lokutor/sdk

Do not put your API key in a .env file the bundler reads (VITE_* variables are inlined into the page). Instead, add a backend route that returns a ticket from POST /ws-ticket; Secure browser setup has a complete one.

Audio pipeline

The SDK’s BrowserAudioManager handles everything:

Capture mic at hardware rate
Resample to 16 kHz Int16 PCM
Send over WebSocket
Receive 44.1 kHz Int16 PCM
Convert to Float32 and schedule via Web Audio API

Start on button click

import { VoiceAgentClient } from '@lokutor/sdk';

const client = new VoiceAgentClient({
  // Called before every connect and reconnect; your backend returns { ticket }.
  auth: async () => (await fetch('/api/lokutor-ticket', { method: 'POST' }).then((r) => r.json())).ticket,
  prompt: 'You are a helpful assistant.',
});

startButton.addEventListener('click', async () => {
  await client.startManaged();
});

On phones, ask for the microphone inside the tap itself with requestMicrophone() and pass it to BrowserAudioManager; see Starting a call on a phone.

VU meter

setInterval(() => {
  meter.style.width = `${client.getAmplitude() * 100}%`;
}, 50);

Pitfalls

Calling startManaged() on page load: browsers block microphone access without a user gesture
Putting an API key in the page, including through bundler environment variables
Not handling interrupted status: if you play audio yourself, clear your queue on interruption