Troubleshooting

Common issues, error scenarios, and recommended fixes when working with the real-time transcription WebSocket API.

Connection Problems

Error message

WebSocket connection failed

Solutions

• Verify endpoint:wss://tl.shunyalabs.ai/
• Check network connectivity and firewall rules
• Ensure WebSocket support in your runtime
• Test with a basic WebSocket client

Reconnection logic

function connectWithRetry(retries = 5, delay = 1000) {
  const ws = new WebSocket('wss://tl.shunyalabs.ai/');

  ws.onerror = () => {
    if (retries > 0) {
      setTimeout(() => {
        connectWithRetry(retries - 1, delay * 2);
      }, delay);
    }
  };

  return ws;
}

Audio Quality Issues

Problem: Poor transcription accuracy

• Audio must be Float32, 16kHz, mono
• Avoid clipping or very low volume
• Reduce background noise
• Use chunk sizes of 200–300ms
• Set correctlanguage

Problem: Distorted audio

• Confirm Float32 little-endian encoding
• Ensure Base64 encoding is correct
• Verify sample rate is 16000 Hz
• Ensure mono channel audio

Performance Issues

Problem: High latency

• Send smaller audio chunks (200–300ms)
• Check network latency to the API
• Avoid buffering excessive audio
• Monitor frame sequence gaps

Problem: Transcription lags behind speech

• Reduce chunk size and send more frequently
• Monitor CPU and memory usage
• Check WebSocket buffer sizes

Message Format Errors

Problem: Messages rejected

• Every message must include"action": "send"
• Verify JSON structure
• Ensureframe_seqincrements sequentially
• Confirm Base64 encoding

Problem: No transcription results

• Sendinitmessage before audio frames
• Ensure audio contains actual speech
• Check WebSocket onmessage handler

WebSocket Status Codes

Debugging Tips

Enable detailed logging

ws.onopen = () => console.log('Connected');
ws.onclose = (e) => console.log('Closed:', e.code, e.reason);
ws.onerror = (e) => console.error('Error:', e);
ws.onmessage = (e) => console.log('Received:', e.data);

Validate audio format

def check_audio_format(sample_rate, channels, dtype):
    if sample_rate != 16000:
        print("Warning: Invalid sample rate")
    if channels != 1:
        print("Warning: Audio must be mono")
    if dtype != np.float32:
        print("Warning: Expected float32")