Troubleshooting

​

Connection Issues

​

Cannot Establish WebSocket Connection

• Invalid API key
• Network/firewall blocking WebSocket connections
• Incorrect WebSocket URL

1. Verify API Key:
   Copy

   // Ensure Authorization header is correct
   headers: {
     Authorization: `Bearer ${API_KEY}` // Not "Token" or "Key"
   }
   
2. Check WebSocket URL:
   Copy

   // Correct URL format
   const url = new URL("wss://waves-api.smallest.ai/api/v1/lightning/get_text");
   // Not "ws://" or "https://"
   
3. Test Network Connectivity:
   Copy

   # Test WebSocket endpoint
   curl -i -N -H "Connection: Upgrade" \
        -H "Upgrade: websocket" \
        -H "Sec-WebSocket-Version: 13" \
        -H "Sec-WebSocket-Key: test" \
        https://waves-api.smallest.ai/api/v1/lightning/get_text
   

​

Connection Drops Unexpectedly

• Network instability
• Server timeout
• Invalid audio data

1. Implement Reconnection Logic:
   Copy

   let ws;
   let reconnectAttempts = 0;
   
   function connect() {
     ws = new WebSocket(url.toString(), { headers });
     
     ws.onclose = (event) => {
       if (event.code !== 1000 && reconnectAttempts < 5) {
         setTimeout(connect, 1000 * Math.pow(2, reconnectAttempts++));
       }
     };
   }
   
2. Monitor Connection State:
   Copy

   setInterval(() => {
     if (ws.readyState !== WebSocket.OPEN) {
       console.warn("Connection not open, state:", ws.readyState);
     }
   }, 5000);
   

​

Audio Encoding Problems

​

No Transcription Received

• Incorrect audio encoding
• Mismatched sample rate
• Invalid audio format

1. Verify Encoding Parameters:
   Copy

   // Ensure encoding matches your audio format
   url.searchParams.append("encoding", "linear16"); // or linear32, alaw, mulaw, opus, ogg_opus
   url.searchParams.append("sample_rate", "16000"); // Must match audio
   
2. Check Audio Format:
   Copy

   import soundfile as sf
   
   audio, sample_rate = sf.read("audio.wav")
   print(f"Sample rate: {sample_rate}")
   print(f"Channels: {audio.shape}")
   print(f"Format: {audio.dtype}")
   # Should be: 16000 Hz, mono, int16
   
3. Validate Chunk Format:
   Copy

   // Ensure chunks are binary (not base64 or text)
   ws.send(audioChunk); // Uint8Array or ArrayBuffer
   // Not: ws.send(JSON.stringify(audioChunk))
   

​

Poor Transcription Quality

• Wrong sample rate
• Incorrect encoding
• Audio quality issues

1. Match Sample Rate:
   Copy

   // Audio must match sample_rate parameter
   const audioContext = new AudioContext({ sampleRate: 16000 });
   url.searchParams.append("sample_rate", "16000");
   
2. Use Recommended Encoding:
   Copy

   // Use linear16 for best quality
   url.searchParams.append("encoding", "linear16");
   
3. Preprocess Audio:
   Copy

   # Normalize and clean audio before streaming
   audio = audio / np.abs(audio).max() * 0.95  # Normalize
   audio = audio.astype(np.int16)  # Convert to int16
   

​

Response Handling Issues

​

Partial Transcripts Not Updating

• Not checking is_final field
• Filtering out partial messages

1. Handle Both Types:
   Copy

   ws.onmessage = (event) => {
     const message = JSON.parse(event.data);
     
     if (!message.is_final) {
       // Show partial transcript
       displayPartial(message.transcript);
     } else {
       // Show final transcript
       displayFinal(message.full_transcript);
     }
   };
   

​

Performance Issues

​

High Latency

• Chunk size too large
• Streaming rate too slow
• Network latency

1. Optimize Chunk Size:
   Copy

   // Use recommended 4096 bytes
   const chunkSize = 4096;
   
2. Increase Streaming Rate:
   Copy

   // Send chunks every 50ms
   setTimeout(sendChunk, 50); // Not 200ms or longer
   
3. Check Network:
   Copy

   # Test latency to API
   ping waves-api.smallest.ai
   

​

Memory Issues

• Buffering too much audio
• Not cleaning up resources

1. Stream Directly:
   Copy

   // Stream chunks immediately, don't buffer entire file
   const stream = fs.createReadStream("audio.wav", { highWaterMark: 4096 });
   stream.on("data", (chunk) => ws.send(chunk));
   
2. Clean Up Resources:
   Copy

   ws.onclose = () => {
     // Clean up audio resources
     if (audioContext) audioContext.close();
     if (stream) stream.destroy();
   };
   

​

Browser-Specific Issues

​

CORS Errors

1. Use WSS (Secure WebSocket):
   Copy

   // Always use wss:// in browsers
   const url = new URL("wss://waves-api.smallest.ai/api/v1/lightning/get_text");
   
2. Handle Authentication:
   Copy

   // Note: Browsers may not support custom headers in WebSocket
   // Consider using query parameter for API key (if supported)
   // Or use a proxy server for authentication
   

​

Microphone Access Denied

1. Request Permissions:
   Copy

   navigator.mediaDevices.getUserMedia({ audio: true })
     .then(stream => {
       // Use stream
     })
     .catch(error => {
       console.error("Microphone access denied:", error);
       // Show user instructions
     });
   
2. Handle HTTPS Requirement:
   • Microphone access requires HTTPS (or localhost)
   • Ensure your page is served over HTTPS

​

Debugging Tips

​

Enable Verbose Logging

ws.onopen = () => console.log("✓ Connected");
ws.onmessage = (event) => {
  console.log("📨 Received:", JSON.parse(event.data));
};
ws.onerror = (error) => console.error("✗ Error:", error);
ws.onclose = (event) => console.log("✗ Closed:", event.code, event.reason);

​

Validate Audio Before Sending

function validateAudioChunk(chunk) {
  if (!(chunk instanceof ArrayBuffer || chunk instanceof Uint8Array)) {
    throw new Error("Audio chunk must be ArrayBuffer or Uint8Array");
  }
  if (chunk.byteLength === 0) {
    throw new Error("Audio chunk cannot be empty");
  }
  if (chunk.byteLength > 8192) {
    console.warn("Chunk size exceeds recommended 4096 bytes");
  }
  return true;
}

​

Monitor Session State

let sessionStats = {
  chunksSent: 0,
  messagesReceived: 0,
  partialCount: 0,
  finalCount: 0
};

ws.onmessage = (event) => {
  sessionStats.messagesReceived++;
  const message = JSON.parse(event.data);
  if (message.is_final) {
    sessionStats.finalCount++;
  } else {
    sessionStats.partialCount++;
  }
  console.log("Session stats:", sessionStats);
};

​

Getting Help

1. Check API Status: Verify the API is operational
2. Review Documentation: Ensure you’re following the correct API version
3. Test with Sample Code: Use the provided examples as a baseline
4. Note down: Reach out with:
   • Session ID (if available)
   • Error messages
   • Code snippets (sanitized of API keys)
   • Network conditions (if applicable)
5. Reach out to us:
   • Email: [email protected]
   • Discord: Join our community