# 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 power-law colormap (gamma=0.3)
  - [x] Horizontal zoom (shift+mousewheel) and scroll (mousewheel)
  - [x] Axis ticks and labels
  - [x] Mouse tooltip (time/frequency/dB intensity)
  - [x] Improved partial tracking (frequency-dependent threshold, candidate system)
  - [x] Original WAV playback with animated playhead
  - [x] Keyboard shortcuts ('2' for playback)
- [ ] 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`