Stream Validator for WaveCap-SDR

This skill helps validate WebSocket and HTTP streaming performance, measure metrics, and diagnose streaming issues.

When to Use This Skill

Use this skill when:

• Audio playback is stuttering or cutting out
• Spectrum display not updating smoothly
• WebSocket connections frequently disconnecting
• Need to measure streaming latency or throughput
• Debugging "no data" or buffering issues
• Performance testing under load
• Verifying stream quality after infrastructure changes

Stream Types in WaveCap-SDR

Audio Streams:

• HTTP: GET /api/v1/stream/channels/{chan_id}.pcm?format=pcm16
• WebSocket: ws://server/api/v1/stream/channels/{chan_id}
• Format: PCM16 (16-bit signed) or F32 (32-bit float)
• Rate: 48 kHz default (configurable)

Spectrum Streams:

• WebSocket: ws://server/api/v1/stream/captures/{capture_id}/spectrum
• Format: JSON messages with FFT bins
• Rate: Configurable FPS (typically 10-15)

IQ Streams:

• WebSocket: ws://server/api/v1/stream/captures/{capture_id}.iq
• Format: Complex IQ samples
• Rate: Full SDR sample rate (2+ MHz)

Usage Instructions

Step 1: Check Server Health

Before validating streams, check server health:

PYTHONPATH=backend backend/.venv/bin/python .claude/skills/stream-validator/validate_stream.py \
  --health-check \
  --port 8087

This shows:

• Server status (ok, degraded, error)
• Device count and status
• Capture count and status
• Channel count and status
• Streaming stats (subscriber count, zombie cleanup)

Step 2: Identify Stream to Validate

Determine the stream endpoint:

# List captures
curl http://127.0.0.1:8087/api/v1/captures | jq

# List channels for a capture
curl http://127.0.0.1:8087/api/v1/captures/{capture_id} | jq '.channels'

Step 3: Run Stream Validator

Validate HTTP audio stream:

PYTHONPATH=backend backend/.venv/bin/python .claude/skills/stream-validator/validate_stream.py \
  --type audio \
  --channel ch1 \
  --duration 10 \
  --port 8087

Validate WebSocket audio stream:

PYTHONPATH=backend backend/.venv/bin/python .claude/skills/stream-validator/validate_stream.py \
  --type audio_ws \
  --channel ch1 \
  --duration 10 \
  --port 8087

Validate spectrum stream:

PYTHONPATH=backend backend/.venv/bin/python .claude/skills/stream-validator/validate_stream.py \
  --type spectrum \
  --capture cap_abc123 \
  --duration 10 \
  --port 8087

Full validation with verbose audio analysis:

PYTHONPATH=backend backend/.venv/bin/python .claude/skills/stream-validator/validate_stream.py \
  --type audio \
  --channel ch1 \
  --duration 10 \
  --verbose \
  --health-check \
  --port 8087

Parameters

Step 4: Interpret Results

The validator outputs:

Connection Metrics:

• Connection time (time to establish WebSocket/HTTP)
• Connection success rate
• Reconnection attempts

Data Metrics:

• Throughput (bytes/sec, samples/sec, messages/sec)
• Latency (time from server to client)
• Packet loss or gaps
• Buffer underruns

Quality Metrics:

• Audio: RMS level, silence detection, clipping
• Spectrum: Update rate, FFT bin count
• IQ: Sample continuity, overflow detection

Health Status:

• HEALTHY: Stream working correctly (throughput >= 95%)
• DEGRADED: Issues detected but stream usable (throughput 80-95%)
• UNHEALTHY: Critical problems, stream unusable (throughput < 80%)

Example Output

============================================================
STREAM VALIDATION RESULTS: AUDIO
============================================================

Status: ✓ HEALTHY

Connection:
  Connect time: 12.3 ms
  Duration: 10.02s

Throughput:
  Bytes received: 960,384
  Throughput: 93.75 KB/s
  Expected: 93.75 KB/s
  Ratio: 100.0%

Audio Analysis:
  RMS level: -18.5 dB
  Peak level: -3.2 dB

============================================================

Common Issues and Solutions

Issue: Low Throughput

Expected throughput:

• Audio PCM16: 96 KB/s (48 kHz × 2 bytes)
• Spectrum: 1-10 KB/s (depends on FFT size and FPS)
• IQ: 4-16 MB/s (depends on sample rate)

Solutions:

• Check network bandwidth
• Reduce stream quality (lower sample rate, smaller FFT)
• Check server CPU usage
• Verify no other bandwidth-intensive processes

Issue: High Latency

Expected latency:

• Local network: <10 ms
• WiFi: 10-50 ms
• Remote: Varies by distance

Solutions:

• Use wired connection instead of WiFi
• Reduce buffering (if configurable)
• Check server processing time
• Verify network not congested

Issue: Packet Loss

Symptoms:

• Audio glitches or pops
• Spectrum gaps or freezes
• Counters show dropped packets

Solutions:

• Check WiFi signal strength
• Reduce stream bandwidth
• Verify no network congestion
• Check for server overload

Issue: Audio Appears Silent

Symptoms:

• RMS level < -50 dB
• Validator reports "Audio appears silent"

Solutions:

• Check channel is started and tuned correctly
• Verify frequency has active signal
• Check gain settings (may be too low)
• Use squelch threshold if monitoring quiet frequencies

Issue: Audio is Clipping

Symptoms:

• Peak level > -0.5 dB
• Validator reports "Audio is clipping"

Solutions:

• Reduce RF gain
• Enable AGC in channel settings
• Check for nearby strong signals causing overload

JSON Report Format

Use --report to get machine-readable output:

{
  "type": "audio",
  "channel": "ch1",
  "url": "http://127.0.0.1:8087/api/v1/stream/channels/ch1.pcm?format=pcm16",
  "success": true,
  "status": "HEALTHY",
  "connect_time_ms": 12.3,
  "duration_seconds": 10.02,
  "bytes_received": 960384,
  "throughput_kbps": 93.75,
  "expected_throughput_kbps": 93.75,
  "samples_received": 480192,
  "throughput_ratio": 1.0,
  "audio_analysis": {
    "rms_db": -18.5,
    "peak_db": -3.2,
    "is_silent": false,
    "is_clipping": false
  }
}

Files in This Skill

• SKILL.md: This file - instructions
• validate_stream.py: Stream validation and metrics script

Dependencies

The validator requires:

• requests - HTTP streaming (included in WaveCap-SDR deps)
• websockets - WebSocket streaming (included in WaveCap-SDR deps)
• numpy - Audio analysis (included in WaveCap-SDR deps)