Speak Debug Bundle
Overview
Collect diagnostic information for Speak API issues: auth verification, audio format validation, session inspection, and network testing.
Prerequisites
- Completed
speak-install-auth setup
- Valid API credentials configured
- ffmpeg installed for audio processing
Instructions
Current State
!node --version 2>/dev/null || echo 'N/A'
!ffmpeg -version 2>/dev/null | head -1 || echo 'ffmpeg not installed'
Step 1: Auth Diagnostic
#!/bin/bash
set -euo pipefail
echo "=== Speak Debug Bundle ==="
echo "Time: $(date -u)"
echo -e "\n--- Auth Check ---"
STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
-H "Authorization: Bearer $SPEAK_API_KEY" \
https://api.speak.com/v1/languages)
echo "API Key Status: HTTP $STATUS"
[ "$STATUS" = "200" ] && echo " Auth: OK" || echo " Auth: FAILED"
echo -e "\n--- Environment ---"
echo "SPEAK_API_KEY set: $([ -n \"${SPEAK_API_KEY:-}\" ] && echo 'yes' || echo 'no')"
echo "SPEAK_APP_ID set: $([ -n \"${SPEAK_APP_ID:-}\" ] && echo 'yes' || echo 'no')"
Step 2: Audio Format Validator
import { execSync } from 'child_process';
function validateAudio(filePath: string): { valid: boolean; issues: string[] } {
const issues: string[] = [];
try {
const info = JSON.parse(execSync(
`ffprobe -v quiet -print_format json -show_streams "${filePath}"`,
{ encoding: 'utf-8' }
));
const stream = info.streams[0];
if (stream.codec_name !== 'pcm_s16le') issues.push(`Codec: ${stream.codec_name} (need pcm_s16le)`);
if (parseInt(stream.sample_rate) !== 16000) issues.push(`Sample rate: ${stream.sample_rate} (need 16000)`);
if (stream.channels !== 1) issues.push(`Channels: ${stream.channels} (need 1/mono)`);
const size = parseInt(execSync(`stat -f%z "${filePath}"`, { encoding: 'utf-8' }));
if (size > 25 * 1024 * 1024) issues.push(`File too large: ${(size/1024/1024).toFixed(1)}MB (max 25MB)`);
if (size < 1000) issues.push('File too small — may be empty or corrupt');
} catch (e) {
issues.push(`Cannot read file: ${e}`);
}
return { valid: issues.length === 0, issues };
}
Step 3: Network Connectivity
echo -e "\n--- Network ---"
curl -s -o /dev/null -w "API: HTTP %{http_code} in %{time_total}s\n" \
-H "Authorization: Bearer $SPEAK_API_KEY" \
https://api.speak.com/v1/health
curl -s -o /dev/null -w "OpenAI: HTTP %{http_code} in %{time_total}s\n" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
https://api.openai.com/v1/models
Output
- Bundle implementation complete
- Speak API integration verified
- Production-ready patterns applied
Error Handling
| Error | Cause | Solution |
|---|
| 401 Unauthorized | Invalid API key | Verify SPEAK_API_KEY environment variable |
| 429 Rate Limited | Too many requests | Wait Retry-After seconds, use backoff |
| Audio format error | Wrong codec/sample rate | Convert to WAV 16kHz mono with ffmpeg |
| Session expired | Timeout after 30 min | Start a new conversation session |
Resources
Next Steps
See speak-prod-checklist for production readiness.
Examples
Basic: Apply debug bundle with default configuration for a standard Speak integration.
Advanced: Customize for production with error recovery, monitoring, and team-specific requirements.
