Best Practices

​

Error handling

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

client.on('error', (error) => {
  if (error.code.startsWith('billing.')) {
    showTopUpPrompt();
    return;
  }
  if (!isRetryable(error)) {
    showFatalError(error.message);
    return;
  }
  console.warn('Transient error:', error.code);
});

​

Timing

• Use audioContext.currentTime for audio timing (not Date.now())
• Use performance.now() for UI timestamps
• Schedule audio with 10-50ms lead time to avoid glitches

​

Interruptions

client.on('status', (status) => {
  if (status === 'interrupted') {
    audioQueue.clear();
  }
});

​

Latency

• Stream and play chunks as they arrive; do not wait for the full response.
• Reuse connections where you can: each new WebSocket costs a handshake.
• Leave speculative replies on for voice agents unless token cost matters more than about 255 ms per reply.
• steps cannot be tuned: the current model always runs 4.

​

Reconnection

client.on('status', (status) => {
  if (status === 'reconnecting') showSpinner();
  if (status === 'disconnected') showReconnectButton();
});

​

Audio

• Pre-warm AudioContext inside a user gesture (button click), not when the first chunk arrives
• Guard against odd-length PCM buffers: trim the last byte if length % 2 !== 0
• Limit transcript history to avoid memory leaks

​

Security

• Keep API keys on your server, in environment variables. Never put one in browser or mobile code.
• Give browsers short-lived tickets with the SDK’s auth option (Secure browser setup).
• Put your ticket route behind your own login.