dsh-musictheory

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 大调）。零运行时依赖、纯确定计算，专治大模型手算音高/升降号/同音异名的高频错误。

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

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.4.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)

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 = 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).
• 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 with python3 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