@maruaudio/dsp/math/scale snaps a fractional MIDI pitch to the nearest note of a key and scale. Fourteen scales are static 12-bit interval masks (chromatic, major, the three minors, two pentatonics, blues, the four other church modes and whole tone) mirroring @maruaudio/music-theory. A key rotates the mask to absolute pitch classes, an absolute enable mask removes notes, and a reference A sets the Hz conversion 69 + 12 × log2(hz / ref). The stateful quantizer holds its note with midpoint hysteresis; an empty allowed set passes the pitch through.

Parameters

configureScaleQuantizer(state, key, scale, enableMask, referenceHz, hysteresisCents) sets all five at once, at control rate.

Lifecycle

initScaleQuantizer() → configureScaleQuantizer → quantizeScaleMidi or quantizeScaleHz, normally once per detector hop → resetScaleQuantizer, which forgets the held note. Stateless helpers (scaleIntervalMask, scalePitchClassMask, nearestAllowedMidi, hzToMidi, midiToHz, isNoteAllowed, pitchClassOf) need no state.

When to use it

Pitch correction and automatic carriers, where a detected voice pitch should land on a scale note without flickering between two neighbours. @maru/modulation-retune, @maru/voices-chord-voicing, @maru/voices-chord-colour and @maru/math-ring-stack build on it (pitch and harmony).

Limits

• A held note stays until another allowed note is closer by more than twice the hysteresis; a held note the new mask disallows is dropped on the next call.
• A negative or NaN MIDI pitch, or 0 Hz or less, is unvoiced: it releases the held note and returns −1 (or 0 Hz).
• nearestAllowedMidi searches ±6 semitones from the rounded pitch; a tie goes to the rounded note when allowed, otherwise downward.
• Unknown ids passed to scaleIntervalMask return the chromatic mask.