Class Chord

An immutable chord: a root pitch class, quality, interval template, and optional slash bass, optionally carrying a Key context. Analysis methods (roman, function, analyze, ...) use an explicitly passed key first and fall back to the carried context.

Example

import { Chord } from '@libraz/libcantus';
Chord.parse('Cmaj7').invert(1).symbol(); // 'Cmaj7/E' (third in the bass)

Index

Constructors

constructor

Accessors

rootPc quality intervals bassPc data key

Constructors

constructor

new Chord(data: ChordData, key?: Key): Chord
Wrap a plain chord object.
Parameters
- data: ChordData
  The chord; it is copied, never retained or mutated.
- Optionalkey: Key
  Optional key context for analysis methods.
Returns Chord
- Defined in model/chord.ts:87

Accessors

rootPc

get rootPc(): number
The root pitch class (0..11).

Returns number
- Defined in model/chord.ts:159

quality

get quality(): ChordQuality
The chord quality.

Returns ChordQuality
- Defined in model/chord.ts:164

intervals

get intervals(): number[]
A copy of the semitone offsets above the root.

Returns number[]
- Defined in model/chord.ts:169

bassPc

get bassPc(): number | undefined
The slash-chord bass pitch class, or undefined in root position.

Returns number | undefined
- Defined in model/chord.ts:174

data

get data(): ChordData
A copy of the underlying plain chord object.

Returns ChordData
- Defined in model/chord.ts:179

key

get key(): Key | undefined
The carried key context, if any.

Returns Key | undefined
- Defined in model/chord.ts:184

Methods

`Static`of

of(root: string | number, quality: ChordQuality, bass?: number): Chord
Build a chord from a root and quality.
Parameters
- root: string | number
  Root as a note name (e.g. 'Eb') or a pitch class.
- quality: ChordQuality
  The chord quality.
- Optionalbass: number
  Optional slash-chord bass pitch class.
Returns Chord
The chord (without key context).
- Defined in model/chord.ts:104

`Static`from

from(data: ChordData): Chord
Wrap an existing plain chord object.
Parameters
- data: ChordData
  The plain chord.
Returns Chord
The wrapped chord (without key context).
- Defined in model/chord.ts:120

`Static`parse

parse(symbol: string): Chord
Parse a lead-sheet chord symbol (e.g. 'Cmaj7', 'F#m7b5', 'C/G').
Parameters
- symbol: string
  The chord symbol.
Returns Chord
The chord (without key context).

Throws
If the root or quality is not recognized.
- Defined in model/chord.ts:131

`Static`detect

detect(pitches: number[], opts?: DetectChordOptions): Chord[]
Identify the chords matching a set of pitches, best interpretation first.
Parameters
- pitches: number[]
  MIDI pitches or bare pitch classes.
- Optionalopts: DetectChordOptions
Returns Chord[]
Ranked chord interpretations (may be empty).
- Defined in model/chord.ts:141

`Static`detectBest

detectBest(pitches: number[], opts?: DetectChordOptions): Chord | null
The single best chord interpretation of a pitch set.
Parameters
- pitches: number[]
  MIDI pitches or bare pitch classes.
- Optionalopts: DetectChordOptions
Returns Chord | null
The top-ranked chord, or null when nothing matches.
- Defined in model/chord.ts:153

withKey

withKey(key: Key): Chord
A copy of this chord carrying the given key context.
Parameters
- key: Key
  The key context to attach.
Returns Chord
The new chord.
- Defined in model/chord.ts:194

pitchClasses

pitchClasses(): number[]
The chord's sorted, deduplicated pitch classes.

Returns number[]
Pitch classes ascending in [0, 11].
- Defined in model/chord.ts:203

roman

roman(key?: Key): string
The chord's Roman numeral in a key.
Parameters
- Optionalkey: Key
  Key to analyze in; falls back to the carried context.
Returns string
The Roman numeral string.

Throws
If no key is given and none is carried.
- Defined in model/chord.ts:214

function

function(key?: Key): HarmonicFunction
The chord's harmonic function (tonic / subdominant / dominant) in a key.
Parameters
- Optionalkey: Key
  Key to analyze in; falls back to the carried context.
Returns HarmonicFunction
The harmonic function.

Throws
If no key is given and none is carried.
- Defined in model/chord.ts:225

analyze

analyze(key?: Key): ChordAnalysis
Full functional analysis: function, borrowing, and Roman numeral.
Parameters
- Optionalkey: Key
  Key to analyze in; falls back to the carried context.
Returns ChordAnalysis
The chord analysis.

Throws
If no key is given and none is carried.
- Defined in model/chord.ts:236

isBorrowed

isBorrowed(key?: Key): boolean
Whether the chord is borrowed from the parallel mode (modal interchange).
Parameters
- Optionalkey: Key
  Key to analyze in; falls back to the carried context.
Returns boolean
True if the chord is borrowed.

Throws
If no key is given and none is carried.
- Defined in model/chord.ts:247

borrowedSource

borrowedSource(key?: Key): BorrowedSource
The origin of a non-diatonic chord (parallel mode or Neapolitan), or null.
Parameters
- Optionalkey: Key
  Key to analyze in; falls back to the carried context.
Returns BorrowedSource
The borrowing source, or null.

Throws
If no key is given and none is carried.
- Defined in model/chord.ts:258

symbol

symbol(opts?: { flats?: boolean }): string
The chord rendered as a lead-sheet symbol (e.g. 'Cmaj7', 'F#m7', 'C/G').
Parameters
- Optionalopts: { flats?: boolean }
  Set flats: true to spell the root/bass with flats.
Returns string
The chord symbol.
- Defined in model/chord.ts:268

voice

voice(opts?: VoicingOptions): number[]
Realize the chord as one MIDI pitch per voice, ascending.
Parameters
- Optionalopts: VoicingOptions
  Voicing options; defaults to four SATB voices.
Returns number[]
MIDI pitches, ascending, one per voice.

Throws
If no voicing fits the given ranges.
- Defined in model/chord.ts:279

styledVoicing

styledVoicing(opts?: StyledVoicingOptions): number[]
Realize the chord as a single styled voicing (close, drop2, drop3, shell, or rootless), optionally constraining the top voice.
Parameters
- Optionalopts: StyledVoicingOptions
  Styled-voicing options; defaults to a close-position voicing.
Returns number[]
MIDI pitches, ascending.
- Defined in model/chord.ts:290

negativeHarmony

negativeHarmony(key?: Key): Chord
The negative-harmony mirror of the chord about the key's tonic–dominant axis (major becomes minor and vice versa).
Parameters
- Optionalkey: Key
  Key providing the reflection axis; falls back to the carried context.
Returns Chord
The mirrored chord, keeping any key context.

Throws
If no key is given and none is carried.
- Defined in model/chord.ts:303

invert

invert(n: number): Chord
The n-th inversion: a copy whose bass is the chord tone n steps above the root in the interval template (invert(1) puts the third in the bass). n wraps around the template length; negative values count backwards.

invert(0) (and any n that wraps to it) is root position, so it carries no slash bass and equals the original chord.
Parameters
- n: number
  The inversion number.
Returns Chord
The inverted chord, keeping any key context.

Throws
If the chord has no intervals.
- Defined in model/chord.ts:322

scales

scales(): ChordScaleMatch[]
The named scales that fit over this chord, best fit first, rooted on the chord root.

Returns ChordScaleMatch[]
The matching scales.
- Defined in model/chord.ts:354

tensions

tensions(scaleName: string): number[]
The available tensions (usable non-chord, non-avoid scale tones) of a scale over this chord.
Parameters
- scaleName: string
  A named scale, rooted on the chord root.
Returns number[]
Tension pitch classes, ascending in [0, 11].
- Defined in model/chord.ts:365

avoidNotes

avoidNotes(scaleName: string): number[]
The avoid notes (scale tones a semitone above a chord tone) of a scale over this chord.
Parameters
- scaleName: string
  A named scale, rooted on the chord root.
Returns number[]
Avoid-note pitch classes, ascending in [0, 11].
- Defined in model/chord.ts:376

spell

spell(key?: Key): Note[]
Spell the chord tones with letter names, root first, in the key's spelling.
Parameters
- Optionalkey: Key
  Key providing the spelled tonic; falls back to the carried context.
Returns Note[]
Spelled octave-less notes in the chord's own (tertian) order.

Throws
If no key is given and none is carried.
- Defined in model/chord.ts:388

progressionTo

progressionTo(...others: Chord[]): Progression
Start a progression with this chord followed by others, carrying this chord's key context (if any).
Parameters
- ...others: Chord[]
  The chords following this one.
Returns Progression
The progression.
- Defined in model/chord.ts:402

equals

equals(other: Chord): boolean
Whether another chord has the same root, quality, intervals, and bass. Key context is not compared.
Parameters
- other: Chord
  The chord to compare.
Returns boolean
True if the chord data is identical.
- Defined in model/chord.ts:413

toJSON

toJSON(): ChordData
The plain chord data, for JSON serialization.

Returns ChordData
A copy of the underlying plain chord object.
- Defined in model/chord.ts:430

Class Chord

Example

Index

Constructors

Accessors

Methods

Constructors

constructor

Parameters

Returns Chord

Accessors

rootPc

Returns number

quality

Returns ChordQuality

intervals

Returns number[]

bassPc

Returns number | undefined

data

Returns ChordData

key

Returns Key | undefined

Methods

Staticof

Parameters

Returns Chord

Staticfrom

Parameters

Returns Chord

Staticparse

Parameters

Returns Chord

Throws

Staticdetect

Parameters

Returns Chord[]

StaticdetectBest

Parameters

Returns Chord | null

withKey

Parameters

Returns Chord

pitchClasses

Returns number[]

roman

Parameters

Returns string

Throws

function

Parameters

Returns HarmonicFunction

Throws

analyze

Parameters

Returns ChordAnalysis

Throws

isBorrowed

Parameters

Returns boolean

Throws

borrowedSource

Parameters

Returns BorrowedSource

Throws

symbol

Parameters

Returns string

voice

Parameters

Returns number[]

Throws

styledVoicing

Parameters

Returns number[]

negativeHarmony

Parameters

Returns Chord

Throws

invert

`Static`of

`Static`from

`Static`parse

`Static`detect

`Static`detectBest