# Chords, Roman numerals, and inversions

## Choose the right bracket

| Purpose | Spelling | Meaning |
| --- | --- | --- |
| Specify sounding notes | `4[C4 E G]` | Plays the three written pitches together |
| Print a harmony symbol | `@C` before music | Labels the harmony; adds no sounding pitches |
| Generate a sounding chord | `4[CMm7:4]` | C4 E4 G4 Bb4 together |
| Generate a key-relative chord | `4[V65:4]` in C major | B4 D5 F5 G5 together |
| Print boxed measure-number landmarks | `RH {5, 9, 13}` | Recommended rehearsal default; no sounding notes |

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.

| Triad | Example | Tones |
| --- | --- | --- |
| Major | `[CM]` | C E G |
| Minor | `[Cm]` | C Eb G |
| Diminished | `[Cd]` | C Eb Gb |
| Augmented | `[C+]` | C E G# |

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](https://www.usu.edu/ycpiano/files/Level9.pdf).

| Spelling | Triad quality | Seventh quality | Spelled tones |
| --- | --- | --- | --- |
| `[CMM7]` | Major | Major | C E G B |
| `[CMm7]` | Major | Minor | C E G Bb |
| `[CmM7]` | Minor | Major | C Eb G B |
| `[Cmm7]` | Minor | Minor | C Eb G Bb |
| `[Cdm7]` | Diminished | Minor | C Eb Gb Bb |
| `[Cdd7]` | Diminished | Diminished | C Eb Gb Bbb |
| `[CdM7]` | Diminished | Major | C Eb Gb B |
| `[C+M7]` | Augmented | Major | C E G# B |
| `[C+m7]` | Augmented | Minor | C E G# Bb |

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.

```scorescript
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.

```scorescript
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`.

| Figure | Bass | Named chord | Roman example |
| --- | --- | --- | --- |
| None | Triad root | `[CM]` | `[I]` |
| `6` | Triad third | `[CM6]` | `[I6]` |
| `64` | Triad fifth | `[CM64]` | `[I64]` |
| `7` | Seventh-chord root | `[CMm7]` | `[V7]` |
| `65` | Seventh-chord third | `[CMm65]` | `[V65]` |
| `43` | Seventh-chord fifth | `[CMm43]` | `[V43]` |
| `42` | Seventh-chord seventh | `[CMm42]` | `[V42]` |

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.

```scorescript
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](https://viva.pressbooks.pub/openmusictheory/chapter/figured-bass/).

## 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
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]
    }
  }
}
```

| Key | Formula | Tones, in root order |
| --- | --- | --- |
| C | `[I]` | C E G |
| G | `[I]` | G B D |
| Am | `[i]` | A C E |
| Am | `[v]` | E G B |
| Am | `[V]` | E G# B |
| Am | `[VII]` | G B D |
| Am | `[viio7]` | G# B D F |
| Am | `[viiø7]` | G# B D F# |

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](https://viva.pressbooks.pub/openmusictheory/chapter/roman-numerals/)
uses contextual sevenths, while [Puget Sound](https://musictheory.pugetsound.edu/mt21c/RomanNumeralsOfDiatonicSeventhChords.html)
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.

```scorescript
[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.

| Formula | Included tones, root order |
| --- | --- |
| `[CMM9]` | C E G B D |
| `[Cmm11]` | C Eb G Bb D F |
| `[CMm13]` | C E G Bb D F A |
| `[CMm13b9#11b13]` | C E G Bb Db F# Ab |

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#.

```scorescript
[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.

```scorescript
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](pitch.md).

## 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.

| Quality | Preferred symbol | Other accepted spellings |
| --- | --- | --- |
| Major triad | `@F` | `@FM`, `@Fmaj`, `@Fmajor`, `@FMaj` |
| Minor triad | `@Fm` | `@Fmin`, `@Fminor`, `@F-` |
| Diminished triad | `@Fd` | `@Fdim`, `@Fo` |
| Augmented triad | `@F+` | `@Faug` |
| Major–minor seventh (dominant) | `@F7` | `@Fdom7`, `@FMm7` |
| Major–major seventh | `@Fmaj7` | `@FM7`, `@FMM7`, `@Fmajor7`, `@FMaj7` |
| Minor–minor seventh | `@Fm7` | `@Fmm7`, `@Fmin7`, `@F-7` |
| Minor–major seventh | `@FmMaj7` | `@FmM7`, `@Fmmaj7`, `@Fminmaj7` |
| Diminished–diminished seventh | `@Fdd7` | `@Fdim7`, `@Fo7` |
| Diminished–minor seventh (half-diminished) | `@Fdm7` | `@Fm7b5`, `@Fm7-5`, `@Fmin7b5`, `@Fhalfdim7` |
| Diminished–major seventh | `@FdM7` | `@FdMaj7`, `@Fdmaj7`; rare-quality warning |
| Augmented–major seventh | `@F+M7` | `@F+maj7`, `@Faugmaj7`, `@F+Maj7` |
| Augmented–minor seventh | `@F+m7` | `@Faug7`, `@F+7`, `@F7#5` |

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.

```scorescript
@C 1[C4 E G] | @DMm7 [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](lyrics.md), [marks](marks.md), [normalization](normalization.md).

## Formatting, reuse, export, and current boundaries

| Operation | Formula behavior |
| --- | --- |
| Ordinary formatting | Keeps quality, numeral, inversion, and sounding spelling; normalizes root register |
| Grid/part arrangement | Retains the formula and its music |
| Change the written key | Roman formulas intentionally follow the new key; named formulas keep their root spelling |
| Sound-preserving key normalization | Explicitly refuses Roman formulas rather than reinterpreting them |
| Shared reader register | Anchors the formula's root, not its inverted bass |
| Shared reader interval | Supported for spellable named roots; Roman interval readings explicitly refuse for now |
| Consolidation | Uses the existing musical equivalence check; a root/bass register mismatch can refuse consolidation |
| MIDI, rendering, MusicXML | Consume the generated notes; a formula does not add a printed harmony label |
| Edit one generated member | Refused as an individual written-pitch edit; author a literal voicing to edit its members independently |

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.