Best Practices

​

Error handling

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

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

​

Timing

• Use audioContext.currentTime for audio and viseme 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();
    visemeTimeline = [];
  }
});

​

Latency

• Denoising steps: the current voice model runs a fixed 4 on every endpoint; steps is accepted and has no effect
• Keep connection open: WebSocket handshake adds 200-500ms. Reuse it.
• Streaming playback: Play chunks as they arrive — don’t wait for the full response
• Track TTFB: client.synthesize({ text, onTTFB: (ms) => ... })

​

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

• Never hardcode API keys — use environment variables
• Validate key presence before creating the client