v0.4.0 — scale_identify

v0.4.0 — scale_identify: name the scale behind the notes

New tool: scale_identify (the inverse of scale_generate)

• Fits 3–12 played notes to the scale table and returns every reading, best first:
  C D E F G A B → C major, and also A natural minor, D dorian, E phrygian, …
• Spelling agreement decides ties: C# D# E# F# G# A# B# comes back as C# major (seven sharps), never the enharmonically identical Db major; Bb C D Eb F G A comes back as Bb major (two flats).
• Ambiguities are reported, not hidden: C D E G A is both C major pentatonic and A minor pentatonic; whole-tone collections list all six possible tonics; A B C D E F G# resolves to A harmonic minor alone.
• Nothing matches exactly → mode: "contains" returns scales that include every note and names the missing degrees (C E G → C major pentatonic, missing D A), so a melody fragment still resolves.
• Ranking: missing degrees → spelling agreement with the input → scale-type commonness → tonic-is-the-lowest-note → accidentals → root pitch class → table order. Scales that would need a triple accidental, or more than seven accidentals, are not reported.

Quality

• 123 → 136 tests; coverage 91.86 % (baseline ratchet).
• test/oracle/anchors.py extended with an independent Python implementation of the scale tables, the spelling of every degree and the ranking — every expectation in the new suite is printed by it, and --check now also verifies the structural invariants (exact readings carry exactly the played pitch classes, "contains" readings include all of them, relative keys share one pitch-class set).
• Oracle migration finished for this repo: every test file now carries the ORACLE: marker.
• Shared lossless-JSON guard (test/helpers/lossless-json.ts) wired into the new suite (undefined live keys, -0, NaN/±Infinity).

中文更新

• 新增工具 scale_identify（scale_generate 的逆运算）：由 3—12 个音反推音阶，给出全部读法并按「缺失音数 → 拼写一致度 → 调式常见度 → 主音是否最低音 → 变音数」排序。
• 拼写优先：C# D# E# F# G# A# B# 判为 C# 大调（七个升号），不会给同音异名的 Db 大调；Bb C D Eb F G A 判为 Bb 大调（两个降号）。
• 歧义如实给出：C D E G A 既是 C 大调五声也是 A 小调五声；全音阶列出六个可能主音。
• 没有音阶恰好吻合时退化为「包含」模式并列缺失音（C E G → C 大调五声，缺 D A）。
• 测试 123 → 136 条，覆盖率 91.86 %，oracle 自检覆盖结构性不变量。

安装：dsh plugin --profile <profile> add github:TYEclipse/dsh-musictheory#v0.4.0

v0.3.0 — transpose + chord_identify

v0.3.0 adds two new tools: spelling-aware transposition and chord identification.

New tools

• transpose — transpose 1–16 notes by any interval, in both directions, with
  correct spelling (the interval is applied through the letter ladder, not by semitone
  counting): 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, A4, M9, P15) plus
  aliases (tritone, octave, whole_tone). Every note comes back spelled, with MIDI
  number and exact 12-TET frequency — useful for instrument transpositions (Bb trumpet
  +M2, Eb alto sax +M6) and key changes.
• chord_identify — identify the chord behind 2–8 played notes by pitch-class set,
  including inversions, slash notation and enharmonic ambiguity: 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 as well (C E Bb D → C9,
  exact: false, missing: ["5"]). Candidates are ranked by
  2 × inversion + quality weight + 3 × missing tones, root position first, with total
  reporting every reading before the 12-candidate cap.

Quality

• Tests: 100 → 123 (23 new in test/music3.test.ts), coverage 90.0% → 91.82%
  (baseline ratcheted up).
• The expected values now come from an independent Python oracle committed with the
  source: test/oracle/anchors.py prints every numeric expectation used by the tests
  (transpose spellings/frequencies, chord rankings, and the legacy v0.1/v0.2 anchors).
  python3 test/oracle/anchors.py --check re-verifies the public facts (A4 = 440 Hz,
  MIDI C4 = 60, G# up a M3 = B#, the C6 ↔ Am7 ambiguity). The oracle caught two real
  defects while this release was being built: a hand-typed 415 Hz frequency and an
  inversion index computed against absolute pitch classes instead of root-relative ones.
• Zero runtime dependencies, no network, no shell — unchanged.

中文

v0.3.0 新增两个工具：拼写感知移调 与 和弦识别。

• transpose：按音程移调 1—16 个音（上/下行均可），走音名字母阶梯而非数半音：
  Bb3 G3 D4 上移 M2 → C4 A3 E4；C#4 E#4 G#4 下移 m3 → A#3 C##4 E#4；
  F#4 下移 P4 → C#4。支持规范音程（M3/P5/m7/M9/P15）与别名
  （tritone/octave/whole_tone）；每个音都返回正确拼写 + MIDI + 精确频率。
  适用降 B 小号（+M2）、降 E 中音萨克斯（+M6）等移调乐器与转调。
• chord_identify：由 2—8 个音按音级集合识别和弦，含转位、斜杠记号与同音异名歧义：
  C E G → Cmaj；E G C（低音 E）→ Cmaj/E 第一转位；C E G A 同时给出
  C6 与 Am7/C；C Eb Gb Bbb → 四个减七转位；写在 B# 上的和弦仍是 B#。
  省略音也匹配（C E Bb D → C9，exact: false、missing: ["5"]）。读法按
  2×转位 + 和弦常见度 + 3×省略音数 排序、根音在低音者优先，total 给出截断前全部读法数。

质量：测试 100 → 123，覆盖率 90.0% → 91.82%（基线棘轮上调）；数值锚点改由随源码
提交的独立 Python oracle（test/oracle/anchors.py）逐条打印 —— 本轮它抓出两处真问题
（手写的 415 Hz 频率、按绝对音级而非相对根音算的转位下标）。零运行时依赖不变。

Install / 安装

dsh plugin --profile <profile> add github:TYEclipse/dsh-musictheory#v0.3.0

v0.2.0 — interval engine + scale harmonization

v0.2.0 (2026-09-05)

新增 3 个工具 / New tools

• interval_build — build the correctly spelled target note of any interval, ascending or descending (C + M3 = E4, G# + M3 = B# not C, C down a d5 = F#3). 34 canonical interval names + aliases (tritone/octave/semitone/whole_tone), compound intervals supported (M9…P15).
• interval_info — name the interval between two notes from the letter distance and semitone count (C→F# = A4, C→Gb = d5), with direction and octave-reduced simple form for compound intervals (C4→D5 = M9 = M2 + 1 octave).
• scale_harmonize — harmonize any 7-note scale into diatonic triads (C major → I ii iii IV V vi vii°) or seventh chords (sevenths: true → Imaj7 ii7 iii7 IVmaj7 V7 vi7 viiø7), with roman numerals, qualities and correct spellings (harmonic minor III is augmented, G# major V = D# F## A#).

质量 / Quality

• 100 tests green (41 + 59 new), anchored on an independent closed-form oracle (anchors-music2.py) cross-checked against public music theory references.
• Zero runtime dependencies, pure 12-TET arithmetic. lint clean.

安装 / Install

dsh plugin --profile <profile-name> add github:TYEclipse/dsh-musictheory#v0.2.0

v0.1.0

v0.1.0 — first release 🎼

Deterministic music theory math for DeepSeek Harness, zero runtime dependencies.

Tools

• note_info — parse a note name (C#4/Bb3/B#4/F##4/Gx4) → MIDI, octave, pitch class, 12-TET frequency, enharmonic spellings
• freq_to_note — frequency in Hz → nearest note, MIDI, cents deviation
• chord_build — correctly spelled chords, 26 qualities (G# major = G# B# D#, Cdim7 = C Eb Gb Bbb)
• scale_generate — correctly spelled scales, 17 types (F# major = F# G# A# B C# D# E#)

Features

• Spelling engine: accidentals follow letter names, not nearest black keys
• Configurable A4 reference (415/432/440/442 Hz)
• 41 tests, anchors from an independent closed-form script + public references
• Zero runtime dependencies — pure arithmetic, no network/shell/filesystem

Install

dsh plugin --profile <profile-name> add github:TYEclipse/dsh-musictheory

---

v0.1.0 首发 🎼

确定性音乐理论数学插件，零运行时依赖。

工具

• note_info — 音名解析（C#4/Bb3/B#4/F##4/Gx4）→ MIDI、八度、音级、12-TET 频率、同音异名
• freq_to_note — 频率转最近音符、MIDI、音分偏差
• chord_build — 26 种和弦正确拼写（G# 大三和弦 = G# B# D#，C 减七和弦 = C Eb Gb Bbb）
• scale_generate — 17 种音阶正确拼写（F# 大调 = F# G# A# B C# D# E#）

特性

• 拼写引擎：变音记号跟随音名走，绝不按"最近黑键"选
• 可配置 A4 参考音高（415/432/440/442 Hz）
• 41 个测试，锚点由独立闭式脚本 + 公开标准交叉验证
• 零运行时依赖：纯算术，无网络/shell/文件访问

安装

dsh plugin --profile <profile-name> add github:TYEclipse/dsh-musictheory