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`