Crate harmonia 

harmonia

Instrument-agnostic music theory primitives.

This crate is being grown out of the JavaScript theory layer in fretboard-explorer. The design separates abstract theory (pitch classes, intervals, scales, chords, keys) from any instrument-specific layout (frets, keys, valves).

Quick tour

use harmonia::{Chord, ChordQuality, Key, PitchClass, Scale, ScaleKind};

// Pitch-class arithmetic.
let g = PitchClass::G;
let v_chord = Chord::new(g, ChordQuality::Dominant7);
assert_eq!(v_chord.to_string(), "G7");

// Roman-numeral analysis in a key.
let c_major = Key::new(PitchClass::C);
let roman = c_major.roman_for(v_chord).unwrap();
assert_eq!(roman.to_string(), "V7");

// Diatonic spelling.
let g_major: Scale = "G Ionian".parse().unwrap();
let spelled = g_major.spelled().unwrap();
let labels: Vec<String> = spelled.iter().map(|n| n.to_string()).collect();
assert_eq!(labels, vec!["G", "A", "B", "C", "D", "E", "F♯"]);

// Parse chord progressions and analyse them.
let progression: Vec<Chord> = ["C", "Am", "F", "G7"]
    .iter()
    .map(|s| s.parse().unwrap())
    .collect();
let detected = harmonia::detect_key(&progression);
assert_eq!(detected[0].key, Key::new(PitchClass::C));

Foundation layer

• PitchClass — one of the twelve octave-equivalent tones (0..12).
• Interval — a non-negative number of semitones, with named constants.
• Note — a Letter plus an Accidental; carries enharmonic spelling on top of a pitch class.
• spell_heptatonic — assigns natural letters A–G across a seven- note scale so each appears exactly once.

Catalogue

• ScaleKind — the 16 scales from theory.js (modes, pentatonics, harmonic/melodic minor, symmetric scales).
• Scale — a ScaleKind anchored at a root PitchClass.
• ChordQuality — 12 chord qualities (6 triads + 6 sevenths).
• Chord — a ChordQuality anchored at a root PitchClass.

Analysis

• Key — a (currently always major) key. Provides diatonic chord templates and Roman-numeral labels via Key::roman_for.
• detect_key — score a chord progression against every major key, returning candidates ranked by fit.
• suggest_scales_for_bracket — rank scales that fit a lead-line gap between two chords.
• suggest_next_chords — context-aware chord recommender with diatonic, resolution, borrowed, secondary, relative, and chromatic categories.

Crate features

• serde (off by default) — derives Serialize and Deserialize on every public data type. PitchClass and Interval serialize as integers; SuggestionCategory as a lowercase string; everything else uses the default serde representation.

Re-exports

pub use analysis::detect_key;

pub use analysis::suggest_next_chords;

pub use analysis::suggest_scales_for_bracket;

pub use analysis::ChordSuggestion;

pub use analysis::ChordSuggestionResult;

pub use analysis::KeyMatch;

pub use analysis::ScaleSuggestion;

pub use analysis::SuggestionCategory;

pub use chord::Chord;

pub use chord::ChordQuality;

pub use interval::Interval;

pub use key::DiatonicChord;

pub use key::Key;

pub use note::Accidental;

pub use note::Letter;

pub use note::Note;

pub use parse::ParseError;

pub use pitch::PitchClass;

pub use roman::Alteration;

pub use roman::RomanNumeral;

pub use scale::Scale;

pub use scale::ScaleGroup;

pub use scale::ScaleKind;

pub use spelling::spell_heptatonic;

Modules

analysis

Higher-level inference functions over chords, scales, and keys.

chord

Chords: 12 qualities and a Chord (kind + root) with pitch-class access.

interval

Intervals measured in semitones.

key

Keys and Roman-numeral analysis.

note

Named notes: a letter A–G plus an accidental.

parse

Parser error type shared by every FromStr implementation in the crate.

pitch

Pitch classes — the twelve octave-equivalent tones of equal temperament.

roman

Typed Roman numerals for harmonic analysis.

scale

Scales: a catalogue of 16 scale types and a Scale (kind + root) for working with concrete pitch-class sets.

spelling

Enharmonic spelling for diatonic scales.