diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/HOWTO.md | 43 |
1 files changed, 43 insertions, 0 deletions
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. |