Introduction

When developing DeepSeek Harness-based agents, handling music theory can often lead to nondeterministic errors, such as incorrect note spelling (writing a G# major triad as G# C D#), inaccurate frequency calculations, and inconsistent handling of sharps and flats. dsh-musictheory is a deterministic music theory toolkit for DeepSeek Harness. It uses pure 12-TET (equal temperament) arithmetic with zero runtime dependencies, aiming to provide precise and reliable mathematical support for model reasoning.

Core Capabilities

The plugin provides the following core functions:

  1. Note-name parsing and frequency/MIDI conversion: supports parsing note names such as C#4, Bb3, outputs the MIDI number, octave, pitch class, and precise 12-TET frequency, and lists all conventional enharmonic spellings.
  2. Chord construction: supports correct spelling for 26 chord qualities (such as maj, min, dim, sus2, sus4, 7, maj7, m7b5, dim7, aug7, 7sus4, add9, madd9, maj9, 9, m9, 11, m11, 13, maj13, 6/9, etc.).
  3. Scale generation: supports correct spelling for 17 scale types (such as major, natural_minor, harmonic_minor, melodic_minor, dorian, phrygian, lydian, mixolydian, locrian, major_pentatonic, minor_pentatonic, blues, whole_tone, chromatic, etc.).
  4. Interval construction and recognition: supports constructing and recognizing 34 standard interval names, and handles enharmonic issues.
  5. Scale harmonization: harmonizes 7-note scales and outputs diatonic triads and seventh chords with Roman numeral labels.
  6. Spelling-aware transposition: supports transposing 1–16 notes by any interval, with spellings strictly following letter and sharp/flat rules.
  7. Chord identification: supports identifying chords made up of 2–8 notes, including inversion recognition (such as Cmaj/E), and can handle enharmonic cases (such as C6 and Am7/C coexisting).

Installation

To install this plugin, use the DeepSeek Harness plugin command.

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

Typical Usage

Below are examples of the main commands for this plugin:

Note-name and frequency info

note_info  note="C#4"

Output: MIDI 61, octave 4, pitch class 1, 277.18 Hz, also: Db4

Frequency to note name

freq_to_note  frequencyHz=442

Output: A4 (MIDI 69), +7.85 cents

Build a chord

chord_build  root="G#" quality="maj"

Output: G#maj: G#4 B#4 D#5

Generate a scale

scale_generate  root="C" type="blues"

Output: C4 Eb4 F4 Gb4 G4 Bb4

Transpose notes

transpose  notes=["Bb3","G3","D4"] interval="M2"

Output: C4 A3 E4

Identify a chord

chord_identify  notes=["C4","E4","G4","A4"]

Output: C6, then “other readings: Am7/C”

Features and Design

  • Zero runtime dependencies: pure mathematical calculations, with no network requests, shell calls, or filesystem access.
  • Deterministic computation: the same input always produces the same output, without relying on LLM randomness.
  • Configurable standard pitch: supports adjusting the reference pitch frequency via config.a4Hz (for example, Baroque 415 Hz, Verdi 432 Hz, modern 442 Hz).
  • Input validation: returns structured errors for invalid note names, frequencies, or unknown chord qualities.
  • License: MIT License.

Ecosystem Context

The core philosophy of DeepSeek Harness is “everything is a plugin.” dsh-musictheory is one of the community-contributed plugins, aimed at extending DSH capability boundaries through standardized tools. The plugin was developed by maintainer TYEclipse, and more information can be found in the community directory.

Summary

dsh-musictheory addresses common spelling errors and nondeterminism issues in music theory calculations. For agent applications that need to handle pitches, chords, scales, and frequency conversion, it provides a deterministic, pure-math solution. The current version of this plugin is 0.3.0, and it is easy to install with no external dependencies.