1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
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
|
