Scales & Keys

Scales, keys, chords, and interval helpers.

Key

A Key — a Scale rooted at a note, for scale-relative composition. All rooted operations (degrees, diatonic chords, quantize) live here. Construct with Key(root, name) or Key(root, scale).

Example:

Key(D4, "dorian") or Key(D4, Scale(#[0, 2, 3.5, 5, 7, 8.5, 10])). Access the underlying Scale with k.scale, the root with k.root, and the scale name with k.name.

Constructor

fn Key(root: Note or Number, name: String or Scale) -> Key

Creates a Key value for scale-relative composition.

Example:

Key(D4, "dorian") or Key(D4, Scale(#[0, 2, 3, 5, 7, 9, 10])). Methods: degree(n), chord(deg), chord7(deg), notes(), quantize(note), transpose(semitones).

Parameters:

• root (Note | Number) — root note (e.g. D4 or a MIDI number)
• name (String | Scale) — scale name (see scale_names()) or a Scale value

Returns: Key — the constructed key

degree

fn degree(n: Number) -> Note

Returns the Note at the given scale degree. Degrees are 1-indexed; degrees > scale length wrap up an octave. Non-positive degrees go below the root: 0 = one step below, -1 = two below.

Parameters:

• n (Number) — scale degree (1 = root, 5 = fifth, 8 = root + octave, etc.)

Returns: Note — the note at that scale degree

chord

fn chord(deg: Number, quality: String or Number, inv: Number) -> Array

Returns a chord (array of Notes) built on the given scale degree. With only deg: the diatonic triad. The optional second argument is either a chord-quality String (e.g. “min7”) or an inversion Number. A third argument adds an inversion to an explicit quality.

Example:

k.chord(1), k.chord(1, 1), k.chord(1, "min7").

Parameters:

• deg (Number) — scale degree (1-indexed, >= 1)
• quality (String | Number) — chord quality String, OR an inversion Number (optional)
• inv (Number) — inversion to apply when quality is given (optional)

Returns: Array — the chord as an array of Notes

chord7

fn chord7(deg: Number, inv: Number) -> Array

Returns a diatonic 7th chord (4 Notes) on the given scale degree.

Parameters:

• deg (Number) — scale degree (1-indexed, >= 1)
• inv (Number) — inversion to apply (optional)

Returns: Array — the 7th chord as an array of four Notes

notes

fn notes() -> Array

Returns one octave of the key’s scale as an array of Notes (rooted).

Returns: Array — one octave of the scale as rooted Notes

quantize

fn quantize(note: Note or Number) -> Note

Snaps a note to the nearest tone in this key’s scale.

Parameters:

• note (Note | Number) — the note (or MIDI number) to quantize

Returns: Note — the nearest in-scale note

transpose

fn transpose(semitones: Number) -> Key

Returns a new Key with the root shifted by the given semitones.

Parameters:

• semitones (Number) — semitones to shift (positive or negative)

Returns: Key — a new key with the shifted root

Scale

A musical scale — a rootless, ordered set of pitch intervals. Construct with Scale("name") for built-in scales, or Scale(#[0, 2, 4, 5, 7, 9, 11]) from a semitone array. Microtonal scales use fractional semitones: Scale(#[0, 1.5, 3.5, 5, 7, 8.5, 10]). Pass a Scale to Key(root, scale) or track.key(scale, root) to play it.

Constructor

fn Scale(arg: String or Array) -> Scale

Creates a Scale value.

Example:

Scale("minor") or Scale(#[0, 2, 3, 5, 7, 8, 10]).

Parameters:

• arg (String | Array) — scale name (e.g. “major”, “dorian”) or an array of semitone intervals (must start with 0 and be strictly ascending, e.g. #[0, 2, 4, 5, 7, 9, 11])

Returns: Scale — the constructed scale

name

fn name() -> String

Returns the scale’s name.

Returns: String — the scale name

intervals

fn intervals() -> Array

Returns the interval array (semitones from root).

Returns: Array — the semitone intervals from the root

period

fn period() -> Number

Returns the period in semitones (12 for a standard octave).

Returns: Number — the period in semitones

length

fn length() -> Number

Returns the number of scale degrees.

Returns: Number — the number of degrees in the scale

mode

fn mode(n: Number) -> Scale

Returns a new Scale rotated to the nth mode (1-indexed).

Example:

Scale("major").mode(2) returns the dorian mode.

Parameters:

• n (Number) — mode index (1-indexed)

Returns: Scale — the scale rotated to the nth mode

contains

fn contains(semitones: Number) -> Boolean

Returns true if the scale contains the given interval (in semitones).

Parameters:

• semitones (Number) — interval from the root, in semitones

Returns: Boolean — true if the interval is in the scale

chord

fn chord(root: Note or Number, name: String) -> Array

Returns an array of Notes forming a chord.

Example:

chord(C4, "min7") returns [C4, Eb4, G4, Bb4]

Parameters:

• root (Note | Number) — root note (e.g. C4 or a MIDI number)
• name (String) — chord name: “major”, “minor”, “dim”, “aug”, “7”, “maj7”, “min7”, “dim7”, “aug7”, “sus2”, “sus4”, “6”, “min6”, “9”, “maj9”, “min9”, “add9”, “power”

Returns: Array — the chord as an array of Notes

chord_names

fn chord_names() -> Array

Returns an array of all available chord names.

Returns: Array — the built-in chord names as Strings

interval

fn interval(note: Note or Number, name: String) -> Note

Returns a single Note at the given interval above the input note.

Example:

interval(C4, "P5") returns G4

Parameters:

• note (Note | Number) — starting note (e.g. C4 or a MIDI number)
• name (String) — interval name: “m2”, “M2”, “m3”, “M3”, “P4”, “tritone” (“TT”), “P5”, “m6”, “M6”, “m7”, “M7”, “P8” (“oct”)

Returns: Note — the note that interval above note

load_scala

fn load_scala(name: String) -> Scale

Load a Scala (.scl) tuning file and return a Scale value. Searches: relative to source file, ~/.resonon/scales/, bundled scales. The .scl extension is optional.

Example:

load_scala("maqam/rast"), load_scala("my_scale.scl")

Parameters:

• name (String) — Scala file name or path (.scl extension optional)

Returns: Scale — the scale loaded from the tuning file

scale_names

fn scale_names() -> Array

Returns an array of all available scale names.

Returns: Array — the built-in scale names as Strings