Chords, Roman numerals, and inversions

Choose the right bracket

Sounding formulas are implemented in the native engine accompanying this reference. Older installed builds may not recognize them. Compile with the matching build before relying on a host's editor highlighting.

[C] is one pitch, not C major. [C7] is one C in octave 7, not a dominant seventh. Use [CM] and [CMm7] for those harmonies. Boxed rehearsal marks use RH {5, 9, 13} by default, or inline [[5]] at measure 5. Custom letters are optional; replace an older boxed [A] with [[A]].

Triads and seventh qualities

Named roots are uppercase A–G, optionally followed by b, bb, #, ##, or n. Their spelling is absolute even under spell key: [FM] always starts on F-natural. [F#M] starts on F-sharp.

The first quality describes the triad; the second describes the seventh above the root, not the third stacked above the fifth. This is established academic notation, explicitly documented in the UMTA skills syllabus, page 7.

The formatter preserves the quality pair instead of replacing it with another tradition's shorter label. The square brackets and plain-text encoding are ScoreScript's choices; the chord classification is established music theory, not a new naming system.

[CM7], [Cm7], and [DMm] are not abbreviations in this grammar. State both seventh qualities and a figure: [CMM7], [Cmm7], [DMm7]. Case matters. The d in dd7 means diminished, so C's seventh is Bbb, not an enharmonically respelled A.

4[CMM7:4] [CMm7] [Cmm7] [Cdd7]

Generated notation

Canonical spelling

4[CMM7:4] [CMm7] [Cmm7] [Cdd7]

Duration and register are separate fields

Put duration before the bracket: 4[CMm7] or q[CMm7]. Both are a quarter-note chord. Duration continues across later chords, ordinary notes, and barlines within the same row/continuation; separately addressed rows have their own duration start. Digits inside a formula are chord structure, not duration.

Put an explicit root octave after a colon inside the bracket: [CMm7:4]. It anchors C4, not whichever member an inversion puts in the bass. This avoids confusing a seventh or inversion figure with an octave. Formula register accepts :-10 through :10; the instrument's playable range is a separate check. Prefer a useful musical register.

Without :octave, the root follows the ordinary nearest-note rule. A final apostrophe or comma inside a formula shifts that root up or down: [CMm7'], [CMm7,]. Do not put spaces inside a formula. Formatter output anchors the first sounding root of a section, then uses relative register. The next event follows the formula's root, including after inversions.

4C4 [DMm7] [EMm7'] [FMm7,]

Generated notation

Canonical spelling

4C4 [DMm7] [EMm7'] [FMm7,]

Inversions: figured-bass placement

Figures select the bass member. The conventional printed figures are often stacked; ScoreScript writes them consecutively. The inversion figure replaces 7; do not write a suffix such as 765 or 742.

With C4 as the root anchor, [CMm65:4] produces E4 G4 Bb4 C5; [CMm43:4] produces G4 Bb4 C5 E5; [CMm42:4] produces Bb4 C5 E5 G5. The engine starts with the root-position stack and raises the members below the requested bass by an octave. This is ScoreScript's deterministic voicing policy—not a claim that figured bass requires that spacing.

4[CMm7:4] [CMm65] [CMm43] [CMm42]

Generated notation

Canonical spelling

4[CMm7:4] [CMm65] [CMm43] [CMm42]

6 means inversion here, not an added sixth. Full figures 53, 63, 753, the abbreviated seventh inversion 2, and arbitrary figures above a separately written bass are not accepted in this constructor grammar. See the figured-bass reference.

Roman numerals: the active key supplies the root

Uppercase I–VII specifies a major triad; lowercase i–vii specifies a minor triad. The numeral selects a scale degree of the active major or minor tonic. A minor therefore starts on A, not its relative-major C. Append o (or °) for diminished, + for augmented, and ø for a diminished triad with a minor seventh. ø needs a seventh figure or extension.

scorescript 0.3
score "Key-relative harmony" {
  meter 4/4
  key {C, 2:G, 3:Am}
  piano {
    m1-3 {
      4[I:4] [vi] [ii6] [V7] |
      [I] [vi] [ii6] [V7] |
      [i] [iv6] [V7] [i]
    }
  }
}

Generated notation

Canonical spelling

scorescript 0.3
score "Key-relative harmony" {
  meter 4/4

  key {C, 2:G, 3:Am}

  part piano

  piano {
    m1-3 {
      4[I:4] [vi] [ii6] [V7] | [I] [vi] [ii6] [V7] | [i] [iv6] [V7] [i]
    }
  }
}

In minor, diminished vii raises the unstated seventh-degree root to the leading tone; uppercase VII remains the natural-minor subtonic. This does not turn every other chord into a harmonic-minor stack.

An initial b, bb, #, or ## alters the root relative to the active key's scale degree. In C major, [bII6] is Db major in first inversion. In A minor, [VI] already starts on F; [bVI] starts on Fb. An explicit prefix replaces the implicit leading-tone adjustment on diminished vii.

key open has no tonic and rejects Roman formulas. An omitted key uses the engine's C-major default; state the key explicitly when authoring reusable Roman-numeral material.

Roman sevenths and explicit quality

Plain 7, 65, 43, and 42 take the seventh from the local key, except where o or ø explicitly selects its quality. Thus [I7] in C major is C E G B, while [V7] is G B D F. In A minor, [i7] is A C E G.

Use M or m before the figure to state the seventh independently: [IM7] is major–major; [Im7] is major–minor; [iM7] is minor–major; [im7] is minor–minor. The numeral's case already supplies the triad quality. [viio7] selects a diminished seventh; [viiø7] selects a minor seventh. Do not append another quality to ø.

This key-diatonic default follows one established academic practice, not a universal spelling rule: Open Music Theory uses contextual sevenths, while Puget Sound uses an explicit M7 convention. Explicit quality avoids that ambiguity.

Applied chords: slash means “of,” not “over”

[V7/V] means the dominant seventh of V. In C major it produces D F# A C. [V7/ii] produces A C# E G; [viio7/ii] produces C# E G Bb. The target's case determines its local major/minor key. Add inversion before the slash and register last: [V65/V:4] produces F#4 A4 C5 D5.

[key C] 4[I:4] [V65/V] [V7] [I]

Generated notation

Canonical spelling

[key C] 4[I:4] [V65/V] [V7] [I]

Only one target numeral is accepted, optionally with a root accidental. Nested chains, a figured target, and diminished-key targets are not supported. [V7/V] is unrelated to repetition and to an @F7/A printed slash-bass label.

Ninths, elevenths, thirteenths, and alterations

Replace the root-position 7 with 9, 11, or 13. The two named quality letters retain their meanings: the second still describes the seventh. Every intervening third is included. These are complete stacks, not automatically thinned performance voicings.

Named formulas use a major ninth, perfect eleventh, and major thirteenth above the root before alterations. Roman formulas instead take extension tones from the local key: A-minor [V9] has F-natural; named [EMm9] has F#.

[key Am] 2[V9:4] [EMm9]

Generated notation

Canonical spelling

[key Am] 2[V9:4] [EMm9]

Append b or # plus 5, 9, 11, or 13 to alter a member already present. The alteration is relative to that formula's unaltered member. [CMm9b9] is valid; [CMm7b9] is not, because a seventh stack has no ninth. Repeated alterations of the same degree are rejected. add, sus, no5, slash-bass named constructors, and combined extension/inversion digits are not part of the sounding-formula grammar. Write a literal chord for custom omissions, suspensions, spacing, doublings, or extended-chord inversions.

Explicit sounding chords

Put the duration before the whole bracket. Within the same musical row or continuation, it carries to later chords and notes until another duration changes it. Separately addressed rows can reset it. Anchor the opening register, then use relative pitches where they express the intended voicing.

4[C4 E G] [D F# A C] [E G C] [F A C]

Generated notation

Canonical spelling

4[C4 E G] [D F# A C] [E G C] [F A C]

Member order controls relative octave reading. The next event follows the first written member, so sorting members is not a harmless formatting change. Inside brackets a comma separates members; it is not the downward-octave operator. Use an explicit octave when a member needs that lower register. Key-aware letters and solfège are pitch spellings here too; they use the same modes described under notes and pitch.

Chord-symbol qualities

The following table describes the @ annotation vocabulary, which is separate from sounding formulas. Every entry needs @ when used in music. The preferred column names the resolved quality; aliases are accepted input.

In quality pairs, the first component describes the triad and the second the seventh. An accepted annotation alias does not automatically become an accepted sounding-formula spelling.

@C 1[C4 E G] | @DMm7 [D F# A C] | @G7 [G B D F] | @C [C E G]

Generated notation

Canonical spelling

@C 1[C4 E G] | @D7 [D F# A C] | @G7 [G B D F] | @C [C E G]

@DMm7 labels the explicitly written D seventh chord; the bracket supplies its notes. Bare D7, without @ or brackets, means the pitch D in octave 7.

Case, accidentals, and omissions

Roots accept b, bb, #, and ##. Prefer uppercase roots with explicit qualities. Lowercase @f means F minor and @f7 means F minor seventh. Lowercase roots with explicit major or augmented quality, such as @fmaj7, raise chord.quality-case-mismatch errors. @FdM7 instead raises the non-fatal chord.rare-quality warning.

Append no5 to omit the fifth in the symbol description: @Fm7no5. The alias ^5 is accepted and formatted to no5. A symbol omission does not delete any notes you separately wrote in a sounding chord.

Extensions, slash bass, and validation limits

Compact suffixes such as sus2, sus4, 7sus4, add9, 6, 9, 11, 13, m9b5, and 9#5 are accepted as symbol text. Extended suffixes are not comprehensively checked: even an unknown word can survive checking. Acceptance is not proof of a recognized chord formula or automatic voicing.

@F7/A prints a slash suffix. The current implementation does not resolve it as a validated bass field or export a structured MusicXML bass. Keep the slash and bass adjacent to the symbol, and write the sounding bass explicitly. Do not use slash-symbol acceptance as proof that the bass spelling is valid.

Parenthesized alterations such as @F7(b9) do not form one chord symbol: the parenthesis is read separately and can produce notation.unknown. @Fø7, @FΔ7, and @"Cmaj7" are not accepted alternatives. Use the tested ASCII quality spellings above. Quoted text marks can print arbitrary text, but do not acquire chord semantics.

Formatting is not complete quality normalization

The source formatter rewrites selected spellings, including @FMm7 → @F7, @FMM7 → @Fmaj7, @FmM7 → @FmMaj7, and ^5 → no5. It does not rewrite every accepted alias into the table's preferred spelling.

Known defect: avoid lowercase @fdom7. Formatting currently changes it to @Fdom7, changing the resolved harmony from minor seventh to dominant. Use explicit @Fm7 or @F7. Checking MIDI alone cannot detect a changed annotation because symbols do not generate notes.

Related: lyrics, marks, normalization.

Formatting, reuse, export, and current boundaries

Use @ separately if a printed chord label is wanted. MusicXML transports the resolved notes, not the compact authored formula; importing it is not a promise to recover the original Roman numeral or quality-pair source.

General figured-bass realization, SATB voice-leading, and host gestures for expanding/editing formula members are later work. They are not implied by correct chord construction. Unsupported formulas report an error; a suffix being accepted as loose @ label text is not validation of sounding harmony.