name: audio-quality-checker description: Analyze the WaveCap-SDR audio stream to assess tuning quality, detect silence, noise, proper audio, or distortion. Use when checking if SDR channels are properly configured or debugging audio issues.

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