summaryrefslogtreecommitdiff
path: root/tools/mq_editor/README.md
diff options
context:
space:
mode:
authorskal <pascal.massimino@gmail.com>2026-02-17 16:12:21 +0100
committerskal <pascal.massimino@gmail.com>2026-02-17 16:12:21 +0100
commit03579c4a33ab3955ff9924a6dcd882fe91dd9aaa (patch)
treebe458d2ac4bc0d7160be8a18526b4e9157af33a5 /tools/mq_editor/README.md
parente3f0b002c0998c8553e782273b254869107ffc0f (diff)
feat(mq_editor): Phase 1 - MQ extraction and visualization (SPECTRAL_BRUSH_2)
Implement McAulay-Quatieri sinusoidal analysis tool for audio compression. New files: - doc/SPECTRAL_BRUSH_2.md: Complete design doc (MQ algorithm, data format, synthesis, roadmap) - tools/mq_editor/index.html: Web UI (file loader, params, canvas) - tools/mq_editor/fft.js: Radix-2 Cooley-Tukey FFT (from spectral_editor) - tools/mq_editor/mq_extract.js: MQ algorithm (peak detection, tracking, bezier fitting) - tools/mq_editor/viewer.js: Visualization (spectrogram, partials, zoom, axes) - tools/mq_editor/README.md: Usage and implementation status Features: - Load WAV → extract sinusoidal partials → fit cubic bezier curves - Time-frequency spectrogram with hot colormap (0-16 kHz) - Horizontal zoom (mousewheel) around mouse position - Axis ticks with labels (time: seconds, freq: Hz/kHz) - Mouse tooltip showing time/frequency coordinates - Real-time adjustable MQ parameters (FFT size, hop, threshold) Algorithm: - STFT with Hann windows (2048 FFT, 512 hop) - Peak detection with parabolic interpolation - Birth/death/continuation tracking (50 Hz tolerance) - Cubic bezier fitting (4 control points per trajectory) Next: Phase 2 (JS synthesizer for audio preview) handoff(Claude): MQ editor Phase 1 complete. Ready for synthesis implementation.
Diffstat (limited to 'tools/mq_editor/README.md')
-rw-r--r--tools/mq_editor/README.md55
1 files changed, 55 insertions, 0 deletions
diff --git a/tools/mq_editor/README.md b/tools/mq_editor/README.md
new file mode 100644
index 0000000..89449c3
--- /dev/null
+++ b/tools/mq_editor/README.md
@@ -0,0 +1,55 @@
+# MQ Spectral Editor
+
+McAulay-Quatieri sinusoidal analysis and synthesis tool.
+
+## Usage
+
+```bash
+open tools/mq_editor/index.html
+```
+
+1. Load WAV file
+2. Adjust MQ parameters (FFT size, hop, threshold)
+3. Click "Extract Partials"
+4. View extracted sinusoidal trajectories with bezier curve fits
+
+## Features (Phase 1)
+
+- **MQ Extraction:** FFT → peak detection → trajectory tracking → bezier fitting
+- **Visualization:** Time-frequency plot with raw trajectories and bezier overlays
+- **Real-time:** Adjustable extraction parameters
+
+## Parameters
+
+- **FFT Size:** 1024-4096 (default 2048)
+- **Hop Size:** 64-2048 samples (default 512, 75% overlap)
+- **Threshold:** -80 to -20 dB (default -60 dB)
+
+## Architecture
+
+- `index.html` - UI and integration
+- `fft.js` - Fast Fourier Transform (Cooley-Tukey radix-2)
+- `mq_extract.js` - MQ algorithm (peak detection, tracking, bezier fitting)
+- `viewer.js` - Visualization (spectrogram, partials, zoom, mouse interaction)
+
+## Implementation Status
+
+- [x] Phase 1: MQ extraction + visualization
+ - [x] Spectrogram rendering with hot colormap
+ - [x] Horizontal zoom (mousewheel)
+ - [x] Axis ticks and labels
+ - [x] Mouse tooltip (time/frequency)
+- [ ] Phase 2: JS synthesizer (preview playback)
+- [ ] Phase 3: Editing UI (drag control points, replicas)
+- [ ] Phase 4: Export (.txt + C++ code generation)
+
+## Algorithm
+
+1. **STFT:** Overlapping Hann windows, radix-2 Cooley-Tukey FFT (from spectral_editor/dct.js)
+2. **Peak Detection:** Local maxima above threshold, parabolic interpolation
+3. **Tracking:** Birth/death/continuation (50 Hz tolerance, 2-frame persistence)
+4. **Bezier Fitting:** Cubic curves (4 control points), fixed endpoints
+
+## See Also
+
+- Design doc: `doc/SPECTRAL_BRUSH_2.md`