diff options
| -rw-r--r-- | TODO.md | 10 | ||||
| -rw-r--r-- | doc/HOWTO.md | 43 | ||||
| -rw-r--r-- | tools/specplay_README.md | 164 |
3 files changed, 217 insertions, 0 deletions
@@ -286,6 +286,16 @@ This file tracks prioritized tasks with detailed attack plans. ## Future Goals & Ideas (Untriaged) +### Audio Tools +- [ ] **Task #64: specplay Enhancements**: Extend audio analysis tool with new features + - **Priority 1**: Spectral visualization (ASCII art), waveform display, frequency analysis, dynamic range + - **Priority 2**: Diff mode (compare .wav vs .spec), batch mode (CSV report, find clipping) + - **Priority 3**: WAV export (.spec → .wav), normalization + - **Priority 4**: Spectral envelope, harmonic analysis, onset detection + - **Priority 5**: Interactive mode (seek, loop, volume control) + - See `tools/specplay_README.md` for detailed feature list + +### Visual Effects - [ ] **Task #52: Procedural SDF Font**: Minimal bezier/spline set for [A-Z, 0-9] and SDF rendering. - [x] **Task #53: Particles Shader Polish**: Improve visual quality of particles. (Completed February 6, 2026) - Implemented transparent circular particles with smooth distance-based falloff diff --git a/doc/HOWTO.md b/doc/HOWTO.md index ef1f1ed..36216fa 100644 --- a/doc/HOWTO.md +++ b/doc/HOWTO.md @@ -306,6 +306,49 @@ The executable will be located at `build/specview`. ./build/specview path/to/input.spec ``` +### Audio Analysis & Playback Tool (`specplay`) + +A diagnostic tool for analyzing and playing .spec spectrogram files and .wav audio files. Useful for debugging audio issues, detecting clipping, and comparing spectrograms to source audio. + +#### Building the Tool + +`specplay` is built along with other tools when enabling `DEMO_BUILD_TOOLS`. + +```bash +cmake -S . -B build -DDEMO_BUILD_TOOLS=ON +cmake --build build +``` +The executable will be located at `build/specplay`. + +#### Usage + +**Play and analyze a .spec file:** +```bash +./build/specplay path/to/input.spec +``` + +**Play and analyze a .wav file:** +```bash +./build/specplay path/to/input.wav +``` + +#### Output Example +``` +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. +[CLIP at sample 1234: 1.523] # Only shown if clipping detected +Playback complete. +``` + +#### Use Cases +- **Detect clipping**: Peak > 1.0 indicates samples will clip +- **Compare loudness**: RMS shows average energy (loudness) +- **Verify spectrograms**: Ensure .spec matches source .wav +- **Debug distortion**: Quickly test individual samples + +See `tools/specplay_README.md` for detailed documentation and future enhancement ideas. + ### Asset Management System This system allows embedding binary assets directly into the demo executable. 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 |