diff options
Diffstat (limited to 'tools/specplay_README.md')
| -rw-r--r-- | tools/specplay_README.md | 164 |
1 files changed, 164 insertions, 0 deletions
diff --git a/tools/specplay_README.md b/tools/specplay_README.md new file mode 100644 index 0000000..72d9ec1 --- /dev/null +++ b/tools/specplay_README.md @@ -0,0 +1,164 @@ +# 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 |