Audio Quality Checker for WaveCap-SDR

This skill helps analyze the audio stream from WaveCap-SDR channels to determine if they are properly tuned and producing usable audio.

When to Use This Skill

Use this skill when:

• User asks to check if an SDR channel is "well tuned" or working properly
• User wants to verify audio quality or detect issues
• User asks if they're getting "real sound" vs "just noise" vs "nothing"
• Debugging why audio playback isn't working as expected
• Validating SDR configuration changes

How It Works

The skill captures a sample of the audio stream and analyzes it to detect:

1. Silence - No signal, near-zero amplitude (broken/stopped channel)
2. Noise - Random signal with no structure (poor tuning, no carrier)
3. Proper Audio - Structured signal with meaningful content (well-tuned FM station)
4. Clipping/Distortion - Signal hitting limits (gain too high, overmodulation)

Usage Instructions

Step 1: Identify the Server and Channel

First, determine:

• Server port (default: 8087, check backend/config/wavecapsdr.yaml or environment variables)
• Channel ID to test (e.g., "ch1", "ch2", etc.)
• Server bind address (default: 127.0.0.1)

You can find active channels by checking:

curl http://127.0.0.1:8087/api/v1/captures | jq '.[] | .channels'

Step 2: Capture Audio Sample

Use the provided analyze_audio_stream.py script to capture and analyze:

PYTHONPATH=backend backend/.venv/bin/python .claude/skills/audio-quality-checker/analyze_audio_stream.py \
  --port 8087 \
  --channel ch1 \
  --duration 3

Parameters:

• --port: Server port (default: 8087)
• --channel: Channel ID to test (default: ch1)
• --duration: Seconds of audio to capture (default: 3)
• --host: Server host (default: 127.0.0.1)
• --format: Audio format, pcm16 or f32 (default: pcm16)

Step 3: Interpret Results

The script outputs a detailed analysis including:

Signal Level Metrics:

• RMS Level (dB): Overall signal strength (-inf = silence, -20 to 0 dB = good)
• Peak Level (dB): Maximum amplitude (near 0 dB may indicate clipping)
• Crest Factor: Peak-to-RMS ratio (high = dynamic, low = compressed/noise)

Spectral Analysis:

• Spectral Flatness: How "flat" the spectrum is (high = noise-like, low = tonal)
• Spectral Centroid: "Center of mass" of the spectrum in Hz
• Zero Crossing Rate: How often signal crosses zero (higher for noise/high-freq content)

Signal Classification: The script will classify the signal as:

• SILENCE: RMS < -60 dB
• NOISE: High spectral flatness (> 0.7) and low RMS
• CLIPPED: Peak level > -0.5 dB
• GOOD AUDIO: Structured signal with moderate levels

Step 4: Recommendations

Based on the results:

If SILENCE detected:

• Check if channel is started: curl -X POST http://127.0.0.1:8087/api/v1/channels/{chan_id}/start
• Verify capture is running
• Check SDR device connection

If NOISE detected:

• Adjust channel frequency (offset_hz) - may not be tuned to a station
• Check antenna connection
• Try different frequencies known to have active broadcasts
• Verify modulation mode matches the signal (wbfm, nbfm, am, ssb, p25, dmr supported)

If CLIPPED detected:

• Reduce SDR gain settings
• Check for overmodulation from the broadcaster
• Adjust RF gain in device configuration

If GOOD AUDIO:

• Channel is properly tuned and working correctly
• Can fine-tune squelch_db if needed to reduce noise during silent periods

Example Workflow

# 1. Check what channels exist
curl http://127.0.0.1:8087/api/v1/captures | jq

# 2. Start a channel if needed
curl -X POST http://127.0.0.1:8087/api/v1/channels/ch1/start

# 3. Analyze the audio quality
PYTHONPATH=backend backend/.venv/bin/python .claude/skills/audio-quality-checker/analyze_audio_stream.py \
  --channel ch1 --duration 3

# 4. If noise detected, try adjusting frequency
# (Update channel configuration and restart)

Technical Details

Audio Stream Format:

• Endpoint: GET /api/v1/stream/channels/{chan_id}.pcm?format=pcm16
• Sample Rate: 48000 Hz (default, configurable)
• Channels: Mono (1 channel)
• Format: 16-bit signed little-endian PCM
• Streaming: Continuous, no headers

Analysis Metrics:

1. RMS Level: 20 * log10(sqrt(mean(signal^2)))

   • Measures average signal power
   • Typical good audio: -20 to -6 dB

2. Spectral Flatness: Geometric mean / Arithmetic mean of power spectrum

   • Near 1.0 = white noise (flat spectrum)
   • Near 0.0 = tonal (structured frequencies)

3. Zero Crossing Rate: Count of sign changes / total samples

   • High ZCR = noisy or high-frequency content
   • Low ZCR = low-frequency or tonal content

4. Crest Factor: Peak / RMS

   • High (>4) = dynamic audio (speech, music)
   • Low (<3) = compressed or noise-like

Files in This Skill

• SKILL.md: This file - instructions for using the skill
• analyze_audio_stream.py: Python script to capture and analyze audio
• requirements.txt: Python dependencies (numpy, scipy, requests)

Notes

• The skill uses the Python environment at backend/.venv
• Ensure the WaveCap-SDR server is running before analysis
• For best results, capture at least 2-3 seconds of audio
• The analysis is statistical and works best with steady signals
• Some transient issues may not be detected in short samples