DSH HUB
HomePlugin StorePlugin PacksCommunityRankingsResourcesPublish Guide
Plugin source
Back to catalog

TYEclipse /

TYEclipse/dsh-musictheory

Verified

Music theory math toolbox for DeepSeek Harness (dsh): note parsing, frequency/MIDI conversion, correctly spelled chords (26 qualities) and scales (17 types) — zero runtime dependencies

★ 1 Stars0 Forks13 IssuesN/A Community rating0 Confirmed installs
View on GitHub
READMESource: main@3d4e3c21

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:

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

—/ 5

No ratings yet

Verified DSH bundle

Commit 3d4e3c2179eb

Community comments

No comments yet. Be the first to write one.

DSH HUB

A community index for DSH plugins. Not an official GitHub or DeepSeek AI product.

CommunityResourcesAPIAbout