Skip to content
learn
Global menu

Music theory for Guitar Alchemist — Mission

Why I’m learning this

Section titled “Why I’m learning this”

Guitar Alchemist (GA) is a large C# and F# code base about music: notes, intervals, scales, modes, chords, voicings, set classes, and tools that let an AI assistant reason about them. I can read the code. What I can’t do is tell whether ModalFamily, PrimeForm or GetSymbolSuffix compute what a musician means by those words. This course learns the theory from serious sources, then reads GA’s types with that theory in hand, and writes down every place where the two disagree.

Who this course is for

Section titled “Who this course is for”

You write C# or Java. You play a little guitar: a few open chords, maybe a pentatonic scale. You don’t read music, and you don’t need to: every concept comes in three steps.

  1. The idea, in words and on the fretboard.
  2. The notation musicians and theorists write it in.
  3. In GA: the types and methods that represent it, with links to the exact lines.

The programming side stays familiar: value objects, records, bit fields, switch expressions, LINQ.

By the end of this course, I will be able to

Section titled “By the end of this course, I will be able to”
  • convert between note names, pitch classes, MIDI numbers and fretboard positions;
  • name and spell intervals, and fold them into interval classes;
  • build scales and modes from step patterns, read them as 12-bit numbers and draw them as bracelets;
  • read chord symbols, spell chords, recognise inversions and name guitar voicings;
  • compute interval-class vectors, prime forms and Forte numbers, and explain the Z-relation;
  • read key signatures, walk the circle of fifths and find relative, parallel and closely related keys;
  • build the chords of a key, label them with Roman numerals and functions, and analyse cadences and progressions;
  • explain voice leading, substitutions, modal mixture, symmetric scales, extended chords and guitar voicing techniques;
  • find each of these in GA’s code, and say where GA agrees with the theory and where it doesn’t.

Outline

Section titled “Outline”

The course follows the concepts that GA’s code, configuration files and MCP tools use, from the single note to the neo-Riemannian transformations. Lessons 1 to 16 are written; the others are the plan, and their GA column names the types, files and tools each one will read.

# Lesson Theory In GA If you write C#
1 Notes, pitch classes and the fretboard pitch, pitch class, accidentals, intervals, tuning PitchClass, Note, Interval, Tuning, Fretboard value objects, closed record hierarchies
2 Scales, modes and 12-bit scale ids major and minor scales, modes, transposition, bracelets PitchClassSetId, Scale, MajorScaleMode, ModalFamily [Flags], bit rotation, PopCount
3 Chords, symbols, inversions and voicings triads, seventh chords, chord symbols, inversions Chord, ChordFormula, CanonicalChordPatternCatalog, Voicing parsers, switch expressions
4 Set classes, interval vectors and the Z-relation T/I equivalence, interval-class vectors, prime forms, Forte numbers SetClass, IntervalClassVector, ForteCatalog, MCP tools canonical forms, equivalence classes
5 Keys, key signatures and the circle of fifths key signatures, relative and parallel keys, closely related keys Key, KeySignature, MCP key tools range value objects, lookup tables
6 The chords of a key diatonic triads and seventh chords, Roman numerals, scale-degree names, functions HarmonicFunction, Key.Notes, PitchClassSet.GetCompatibleKeys, ga_diatonic_chords enums, subset tests on bit masks
7 Cadences, ii–V–I and the key of a progression cadences, plagal and deceptive motion, ii–V–I, resolving V⁷, finding the key Cadences.yaml, PitchClassSet.ClosestDiatonicKey, ga_analyze_progression, ga_key_from_progression scoring and tie-breaking
8 The ukulele and the bass re-entrant tunings, tunings in fourths, string numbering Tuning.Ukulele, Tuning.Bass, Str, Fretboard, Instruments.yaml guessing from data, and when not to
9 Voice leading and common tones common tones, smooth voice leading, voice-leading distance, parallel fifths and octaves, OPTIC distances VoiceLeadingSpace, SetClassOpticIndex, ProgressionVoiceLeadingAnalyzer, VoiceLeadingSkill, ga_common_tones, ga_voice_leading_pair distance metrics
10 Substitutions and modal mixture relative and tritone substitution, borrowed chords ChordSubstitutionSkill, ModalInterchange.yaml, get_borrowed_chords, ga_chord_substitutions, GrothendieckDelta ranking candidates
11 Modes in depth modes of melodic and harmonic minor, brightness, modal families MelodicMinorMode, HarmonicMinorMode, IScaleDegreeNaming, PitchClassSet.StepBrightness, UnifiedModeService, Modes.yaml, get_mode_info generics over scale degrees
12 Symmetry and modes of limited transposition modes of limited transposition, Messiaen’s modes, the tritone scale, mirror axes SymmetricScaleMode, WholeToneScaleMode, DiminishedScaleMode, AugmentedScaleMode, UnifiedModeService, AtonalModalFamilies.yaml, TranspositionClass invariants under rotation
13 Extended and altered chords ninths, elevenths, thirteenths, alterations, upper structures, polychords Chord.FromSymbol, ChordSymbolParser, BasicChordExtensionsService, ChordAlterationService, ChordTemplateFactory, ExtendedChords.yaml, ga_polychord parsers with optional parts
14 Guitar voicings: shells, drop 2 and drop 3 shell voicings, close and drop voicings, guide tones VoicingGenerator, VoicingHarmonicAnalyzer, VoicingAnalyzer, VoicingFilters, ChordClassificationEngine, ChordProgressions.yaml combinatorial generation
15 The fretboard: CAGED, fingering and playability CAGED shapes, fretboard geometry, reach and effort, open tunings FretboardGeometry, PhysicalFretboardCalculator, PhysicalCostService, VoicingPhysicalAnalyzer, BiomechanicalAnalyzer, PlayerProfile, Tunings.toml, ga_easier_voicings cost functions
16 Arpeggios, chord–scale theory and improvisation arpeggios, chord–scale pairs, outside notes ga_arpeggio_suggestions, ImprovisationSkill, OutsideNotesSkill, ImprovisationConcepts.yaml mapping tables
17 The Tonnetz and neo-Riemannian transformations P, L and R, the Tonnetz, chromatic mediants NeoRiemannian.yaml, NeoRiemannianConfig.fs graphs of transformations
A Every instrument in Guitar Alchemist tunings, courses, re-entrant strings Instruments.yaml, InstrumentsConfig, Tuning configuration that nothing reads
B The OPTIC hierarchy octave, permutation, transposition, inversion, cardinality PitchClassSet, TranspositionClass, SetClass, GA’s OPTIC-K schema equivalence, quotient by quotient
C Every divergence, and whose bug it is the 40 DIFF rows of lessons 1 to 7 the 19 defects they come from reading a comparison honestly
— Journal

Prerequisites

Section titled “Prerequisites”
  • The .NET 10 SDK and Git. On Windows, run the course scripts from Git Bash.
  • About 35 MB of disk for GA’s partial clone and the build output: the script fetches only the files of the three projects the program builds against, and a few files of four others.
  • A guitar helps: every example can be played.
Section titled “Related modules on this site”

The Streeling modules, generated from GuitarAlchemist/Demerzel, cover some of the same ground from the musician’s side. Each lesson links the relevant ones:

Resources

Section titled “Resources”