@maruaudio/dsp/voices/chord-colour proposes up to two added tones (colours) for a chord, given as a 12-bit pitch-class mask and its root, from the key's scale. Candidates are scale tones outside the chord. A candidate a semitone above a chord tone is an avoid note, except the flat ninth and flat 13th over a dominant seventh, and two colours are never a semitone apart; the rule follows Nettles & Graf and Levine as the source header cites. Survivors are ranked by mean interval-class consonance with the sounding tones. A decaying histogram of the pitch classes played can boost degrees the output has under-used against a flat or Krumhansl–Kessler key profile (pitch and harmony).
Parameters
| Setter | Range as coded | Default |
|---|---|---|
configureChordColourKey(state, tonic, scaleMask, profile) | Tonic rounded, mod 12; mask & 4095; profile rounded, 0 flat, 1 key (major or minor by the third above the tonic), 2 KK major, 3 KK minor; returns false and changes nothing for an empty mask or unknown profile | C major (mask 2741), profile 1 |
configureChordColourBalance(state, balance, halfLife) | Balance 0 to 1 (NaN gives 0); half-life 1 to 256 chords (NaN gives 1) | Balance 0, half-life 8 |
chordColourPick(state, chordMask, rootPc, amount, out) | Amount rounded, 0 to 2; returns how many were picked | — |
A candidate whose observed share is below the profile's expected share gains balance × 0.25 × deficit, the deficit relative to the expected share (0..1).
Lifecycle
createChordColour() allocates two 12-bin Float32Arrays (expected, histogram) → configure the key and balance at control rate (the balance setter calls Math.pow once) → on each chord change chordColourPick, then chordColourObserve(state, soundingMask) with what is finally played (every bin decays by 0.5^(1/halfLife), then each sounding class gains 1 / count) → resetChordColourHistory forgets the history. Changing the key keeps the history.
When to use it
Adding ninths, sixths and other tensions to generated chords so that the additions stay in key, avoid the classic clashes, and vary over a progression instead of repeating one colour.
Limits
- Pitch classes only; voicing the colours is the caller's job.
- Deterministic argmax: ties within 1e-9 go to higher consonance, then the pitch class closer to the root, then the smaller interval above the root.
- An empty history adds no boost, so a fresh state picks by consonance alone.
- The 13th over a Dorian minor seventh is deliberately not an avoid note.