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°）。零运行时依赖、纯确定计算，专治大模型手算音高/升降号/同音异名的高频错误。
Why
Agents get music theory wrong in predictable ways:
C4 frequency? Often quoted wrong — it's exactly 440 · 2^((60−69)/12) = 261.625565… Hz.G# major chord? Frequently written G# C D# — the correct spelling is G# B# D# (a major third above G# is B#, the leading tone, not C).F# major scale? Usually missing the E# (six sharps, not five).Bb vs A#? 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). |
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.2.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)
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 = letter B, target pitch class 0 → B# (B's diatonic class is 11, +1 sharp).
- Root
C, diminished seventh = letter B, 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).
- 100 unit tests, anchored on independently computed 12-TET values (
~/.hermes/scripts/anchors-music.py and anchors-music2.py) and public references (A4=440 Hz ISO 16, MIDI C4=60, C major diatonic triads, harmonic minor augmented III).
Roadmap
transpose — spelling-aware transposition by interval/key (coming in a future release)- Interval inversion & more compound intervals
- More chord qualities & scale types on request — open an issue!
License
MIT © 2026 TYEclipse
