From 2dcc4216faa359482f3f782931bfd1a2bbaf407b Mon Sep 17 00:00:00 2001
From: skal <pascal.massimino@gmail.com>
Date: Fri, 6 Feb 2026 18:10:47 +0100
Subject: docs: Document specplay tool and add future enhancement roadmap

- Created tools/specplay_README.md with comprehensive documentation
- Added Task #64 to TODO.md for future specplay enhancements
- Updated HOWTO.md with specplay usage examples and use cases
- Outlined 5 priority levels of potential features (20+ ideas)

Key enhancements planned:
- Priority 1: Spectral visualization, waveform display, frequency analysis
- Priority 2: Diff mode, batch analysis, CSV reports
- Priority 3: WAV export, normalization
- Priority 4: Advanced spectral analysis (harmonics, onsets)
- Priority 5: Interactive mode (seek, loop, volume control)

The tool is production-ready and actively used for debugging.
---
 doc/HOWTO.md | 43 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)

(limited to 'doc')

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.
-- 
cgit v1.2.3