# specplay - Audio Analysis & Playback Tool

Standalone diagnostic tool for analyzing and playing .spec spectrogram files and .wav audio files.

## Usage

```bash
./build/specplay <file.spec|file.wav>
```

## Features

### Current (v1.0)
- ✅ Plays .spec files via IDCT synthesis (matches demo playback exactly)
- ✅ Plays .wav files for comparison
- ✅ Reports PCM statistics:
  - **Peak level**: Maximum absolute sample value (detects clipping if > 1.0)
  - **RMS level**: Root-mean-square energy (loudness measure)
- ✅ Real-time clipping detection during playback with sample position
- ✅ Validates .spec file format (magic bytes, version, DCT size)

### Example Output
```
Loading .spec: version=1, dct_size=512, frames=68
PCM stats: Peak=0.403, RMS=0.058
Playing 1.09 seconds... Press Ctrl+C to stop.
Playback complete.
```

## Use Cases

1. **Debugging Audio Issues**
   - Quickly identify which samples have clipping (Peak > 1.0)
   - Compare .wav source vs .spec output to detect analysis artifacts
   - Verify spectrogram regeneration after DCT changes

2. **Quality Assurance**
   - Batch test all .spec files for clipping before committing
   - Measure loudness consistency across samples (RMS levels)
   - Validate spectrograms match expected characteristics

3. **Development Workflow**
   - Test individual samples without running full demo
   - A/B compare different spectrogram generation parameters
   - Verify procedural note generation output

## Technical Details

- **Sample Rate**: 32kHz (matches demo audio engine)
- **Format**: Mono (duplicated to stereo for playback)
- **IDCT**: Uses same `idct_512()` function as demo (bit-exact)
- **Clamping**: Clipping detected but samples clamped to [-1, 1] for playback

## Future Enhancement Ideas

### Priority 1: Analysis Features
- [ ] **Spectral visualization**: ASCII art frequency plot
- [ ] **Waveform display**: Time-domain amplitude graph
- [ ] **Frequency analysis**: Dominant frequency, spectral centroid
- [ ] **Dynamic range**: Measure headroom, suggest normalization
- [ ] **Duration info**: Show seconds, samples, frames

### Priority 2: Comparison Tools
- [ ] **Diff mode**: `specplay --compare file.wav file.spec`
  - Side-by-side PCM stats
  - RMS error, peak difference
  - Correlation coefficient
- [ ] **Batch mode**: `specplay --batch assets/final/*.spec`
  - Generate CSV report of all stats
  - Sort by peak level (find clipping candidates)
  - Find outliers (unusually loud/quiet samples)

### Priority 3: Export Features
- [ ] **WAV export**: `specplay file.spec --export output.wav`
  - Convert .spec → .wav for external analysis
  - Useful for importing into audio editors
- [ ] **Normalization**: `specplay file.spec --normalize --export normalized.wav`
  - Auto-scale to target peak/RMS
  - Preserve transients

### Priority 4: Advanced Analysis
- [ ] **Spectral envelope**: Extract formants, resonances
- [ ] **Harmonic analysis**: Detect fundamental frequency, harmonics
- [ ] **Onset detection**: Find transient attacks (kick/snare hits)
- [ ] **Spectral flux**: Measure frequency content change over time

### Priority 5: Interactive Mode
- [ ] **Seek controls**: Play from specific time offset
- [ ] **Loop mode**: Repeat playback indefinitely
- [ ] **Volume control**: Adjust playback gain
- [ ] **Real-time waveform**: Live visualization during playback

## Integration with Build System

Built automatically when `DEMO_BUILD_TOOLS=ON`:
```bash
cmake -S . -B build -DDEMO_BUILD_TOOLS=ON
cmake --build build --target specplay
```

Or with all options:
```bash
cmake -S . -B build -DDEMO_ALL_OPTIONS=ON
cmake --build build
```

## Code Architecture

- **Minimal dependencies**: Only uses audio subsystem + miniaudio
- **Self-contained**: No GPU, no platform layer (pure audio)
- **Size**: ~250 lines (easy to extend)
- **Format support**:
  - `.spec` via SpecHeader parser
  - `.wav` via miniaudio decoder (also handles .aif, .mp3)

## Related Tools

- **spectool**: Analyzes .wav → generates .spec (batch processing)
- **specview**: ASCII visualization of .spec frequency content
- **specplay**: This tool (playback + analysis)

## Troubleshooting

**"Failed to read SpecHeader"**
- File is not a valid .spec file
- Try with spectool to regenerate: `./build/spectool analyze input.wav output.spec`

**"Peak exceeds 1.0! Will clip during playback."**
- Spectrogram has too much energy
- Likely needs regeneration after DCT changes
- Or source .wav is already clipping

**No audio output**
- Check system audio device
- Ensure 32kHz sample rate is supported
- Try with a different .spec file (may be empty/silent)

## Examples

### Find all clipping samples
```bash
for f in assets/final/*.spec; do
  ./build/specplay "$f" | grep "WARNING" && echo "$f"
done
```

### Compare wav source to spec output
```bash
./build/specplay assets/originals/kick.wav
./build/specplay assets/final/KICK.spec
# Compare Peak/RMS values
```

### Quick loudness check
```bash
./build/specplay assets/final/KICK_606.spec | grep "RMS"
# RMS > 0.3: loud, RMS < 0.1: quiet
```

---

**Last Updated**: February 6, 2026
**Author**: Claude (AI assistant)
**Status**: Production-ready, actively used for debugging