dsh-musictheory 🎼
Deterministic music theory math for DeepSeek Harness (dsh) — zero runtime dependencies, pure 12-TET arithmetic.
中文简介:音乐理论数学工具箱——解析音名、频率与 MIDI 互转、26 种和弦与 17 种音阶的正确拼写(G# 大三和弦是 G# B# D# 而非 G# C D#)、音程构建与识别(C→F# 是增四度、C→Gb 是减五度)、音阶和声化(C 大调三和弦 I ii iii IV V vi vii°)、拼写感知移调(G# 上移大三度 = B#)、按音级集合识别和弦(E G C = Cmaj/E 第一转位;C E G A 同时是 C6 与 Am7/C)、由音反推音阶(C D E F G A B 是 C 大调,也是 A 自然小调与 D 多利亚;C# D# E# F# G# A# B# 是 C# 大调而非同音异名的 Db 大调)、调号与五度圈(三个降号是 Eb 大调 / C 小调,七升七降内给同音异名调)、和弦进行的罗马数字分析(C 大调里 Am F C G = vi IV I V;A# 是 #VI、Bb 是 bVII;C/E = I6、G7/F = V42)。零运行时依赖、纯确定计算,专治大模型手算音高/升降号/同音异名的高频错误。
Why
Agents get music theory wrong in predictable ways:
C4frequency? Often quoted wrong — it's exactly440 · 2^((60−69)/12) = 261.625565… Hz.G# majorchord? Frequently writtenG# C D#— the correct spelling is G# B# D# (a major third above G# is B#, the leading tone, not C).F# majorscale? Usually missing the E# (six sharps, not five).BbvsA#? Same key on the piano, different meaning on paper — the tools list all conventional enharmonic spellings.
These tools replace all of that with deterministic tables and a spelling engine.
Tools
| Tool | What it does |
|---|---|
note_info |
Parse a note name (C#4, Bb3, B#4, F##4, Gx4) → MIDI number, octave, pitch class, exact 12-TET frequency, and all conventional enharmonic spellings. |
freq_to_note |
Frequency in Hz → nearest note, MIDI number, cents deviation, enharmonics. |
chord_build |
Correctly spelled chords for 26 qualities — maj, min, dim, aug, sus2, sus4, 5, 6, m6, 7, maj7, m7, m7b5, dim7, aug7, 7sus4, add9, madd9, maj9, 9, m9, 11, m11, 13, maj13, 6/9 — with interval labels, MIDI numbers and frequencies. |
scale_generate |
Correctly spelled scales for 17 types — major, natural_minor, harmonic_minor, melodic_minor, dorian, phrygian, lydian, mixolydian, locrian, major_pentatonic, minor_pentatonic, blues, whole_tone, chromatic (plus aliases ionian, minor, aeolian) — with degrees, intervals and frequencies. |
interval_build |
Build the correctly spelled target note of an interval, up or down: C + M3 = E, G# + M3 = B# (not C!), C down a d5 = F#. 34 canonical names (M3, P5, m7, A4, d5, M9, P15 …) plus aliases (tritone, octave, semitone, whole_tone). |
interval_info |
Name the interval between two notes. The letter distance decides the number (C→F# = augmented 4th, C→Gb = diminished 5th), the semitone count decides the quality, direction and compound structure (C4→D5 = M9 = M2 + 1 octave) are reported separately. |
scale_harmonize |
Harmonize a 7-note scale: diatonic triads on every degree with roman numerals, qualities and correct spellings (C major → I ii iii IV V vi vii°, harmonic minor III is augmented). sevenths: true gives seventh chords (Imaj7 ii7 iii7 IVmaj7 V7 vi7 viiø7). |
transpose |
Transpose 1-16 notes by any interval, spelling-aware and in both directions: Bb3 G3 D4 up a M2 → C4 A3 E4, C#4 E#4 G#4 down a m3 → A#3 C##4 E#4, F#4 down a P4 → C#4. Canonical intervals (M3, P5, m7, M9, P15) plus aliases (tritone, octave, whole_tone). Use it for instrument transpositions (Bb trumpet +M2, Eb alto sax +M6) and key changes. |
chord_identify |
Identifies the chord behind 2-8 played notes: C E G → Cmaj; E G C (bass E) → Cmaj/E, first inversion; C E G A → both C6 and Am7/C; C Eb Gb Bbb → all four dim7 rotations; a chord written on B# stays on B#. Voicings that omit one or two chord tones are matched too (C E Bb D → C9 with missing: ["5"], exact: false). |
scale_identify |
Fits scales to 3-12 played notes — the inverse of scale_generate: C D E F G A B → C major, plus A natural minor, D dorian and the other modes of the same pitch classes; C D E G A → both C major pentatonic and A minor pentatonic; A B C D E F G# → A harmonic minor only. Spelling agreement wins: C# D# E# F# G# A# B# is C# major, not the enharmonic Db major. When nothing matches exactly, mode: "contains" returns scales that include every note with the missing degrees listed (C E G → C major pentatonic, missing D A). |
key_signature |
Look up a key signature instead of counting sharps: ask by key name (Eb, F# minor) or by circle-of-fifths position (fifths: -3 = three flats). Returns the accidentals in written order (Bb Eb Ab), the relative key (same signature), the parallel key (same tonic), the enharmonic spelling inside seven accidentals (C# major = Db major) and the spelled scale. Signatures beyond seven accidentals come back practical: false because they need double sharps — use enharmonic for everyday writing. |
roman_numeral |
Roman-numeral analysis of a progression: Am F C G in C major → vi IV I V. The degree comes from the written letter, not the pitch class — in C major A# is #VI and Bb is bVII (same key on the piano, two functions on paper). Each chord reports its degree, alteration, correctly spelled tones, whether every tone is in the key (inKey), whether it is the key's own chord of that size on that degree (diatonic), plus the key triad on that degree as a reference (degree 7 in major is vii°). Slash chords get figured bass: C/E → I6, G7/F → V42; a non-chord bass keeps the slash (C/D → I/D). Minor keys are analyzed with natural minor, so the raised leading tone shows up as #vii. |
Install
dsh plugin --profile <profile-name> add github:TYEclipse/dsh-musictheory
(Install from the npm-style git URL, or pin a release: add github:TYEclipse/dsh-musictheory#v0.5.0.)
Examples
note_info note="C#4" → MIDI 61, octave 4, pitch class 1, 277.18 Hz, also: Db4
freq_to_note frequencyHz=442 → A4 (MIDI 69), +7.85 cents
chord_build root="G#" quality="maj" → G#maj: G#4 B#4 D#5
chord_build root="C" quality="dim7" → Cdim7: C4 Eb4 Gb4 Bbb4
scale_generate root="F#" type="major" → F#4 G#4 A#4 B4 C#5 D#5 E#5
scale_generate root="C" type="blues" → C4 Eb4 F4 Gb4 G4 Bb4
interval_build root="C" interval="M3" → E4 (MIDI 64, 329.63 Hz)
interval_build root="C" interval="d5" direction="descending" → F#3 (a diminished fifth DOWN is lower than a perfect fifth)
interval_info note1="C4" note2="F#4" → A4, 6 semitones, ascending
interval_info note1="C4" note2="D5" → M9, 14 semitones (compound: M2 + 1 octave)
scale_harmonize root="C" type="major" → I ii iii IV V vi vii°
scale_harmonize root="A" type="harmonic_minor" → III+ = C5 E5 G#5 (augmented)
transpose notes=["Bb3","G3","D4"] interval="M2" → C4 A3 E4 (Bb instrument reading concert pitch)
transpose notes=["C#4","E#4","G#4"] interval="m3" direction="descending" → A#3 C##4 E#4
chord_identify notes=["E4","G4","C5"] → Cmaj/E (maj, inversion 1)
chord_identify notes=["C4","E4","G4","A4"] → C6, then "other readings: Am7/C"
chord_identify notes=["C4","E4","Bb4","D5"] → C9 (exact: false, missing ["5"])
scale_identify notes=["C4","D4","E4","F4","G4","A4","B4"] → C major (also A natural minor, D dorian, …)
scale_identify notes=["C4","D4","E4","G4","A4"] → C major pentatonic, then A minor pentatonic
scale_identify notes=["C#4","D#4","E#4","F#4","G#4","A#4","B#4"] → C# major (seven sharps, not Db major)
scale_identify notes=["C4","E4","G4"] → C major pentatonic, missing D A (mode: contains)
key_signature key="Eb" → 3 flats (Bb Eb Ab), relative C minor, parallel Eb minor
key_signature fifths=7 → C# major (seven sharps), enharmonic Db major
roman_numeral key="C major" chords=["Am","F","C","G"] → vi IV I V
roman_numeral key="C major" chords=["C/E","G7/F"] → I6 V42
roman_numeral key="A minor" chords=["Am","Dm","E"] → i iv V (the E major triad is inKey: false)
roman_numeral key="C major" chords=["A#","Bb"] → #VI bVII (same key, two functions)
How chord_identify ranks
Every reading of the played pitch classes is scored as
2 × inversion + quality weight + 3 × missing tones (a quality weight of 0 for
maj/min/dim/maj7/m7/7 up to 4 for the extended colours), then sorted
by root position, table order, root pitch class and inversion. Ties such as
C6 vs. Am7/C are returned in the order a musician would read them, best
first, and total reports how many readings exist before the 12-candidate cap.
How the spelling works
Every chord/scale is a table of letter steps + semitone offsets. A pitch is spelled by computing the accidental that makes the required letter sound at the target pitch class:
- Root
G#, major third = letterB, target pitch class 0 → B# (B's diatonic class is 11, +1 sharp). - Root
C, diminished seventh = letterB, target class 9 → Bbb (double flat). - Root
Cb, major =Cb Eb Gb— flats follow the root's flat spelling.
Accidentals are never chosen by "nearest black key"; they follow the letter name, which is exactly where hand-written music theory breaks down.
Tunings
All tools accept an optional a4Hz (and the plugin supports config.a4Hz) so you can work
in historical/alternative reference pitches: baroque 415, Verdi 432, modern
orchestra 442 Hz. Frequencies follow the 12-TET formula a4 · 2^((midi−69)/12).
Safety & design
- Zero runtime dependencies — pure arithmetic, no network, no shell, no filesystem access.
- Deterministic: same input always gives the same output; no approximation of note names.
- Inputs are validated (malformed notes / non-positive frequencies / unknown qualities return structured errors).
- 136 unit tests, anchored on an independent Python oracle committed with the source
(
test/oracle/anchors.py, printed values for every numeric expectation; re-check the public facts withpython3 test/oracle/anchors.py --check) and on public references (A4=440 Hz ISO 16, MIDI C4=60, C major diatonic triads, harmonic minor augmented III).
Roadmap
- Interval inversion & more compound intervals
- More chord qualities & scale types on request — open an issue!
License
MIT © 2026 TYEclipse
No comments yet. Be the first to write one.