tonnetz

Neo-Riemannian music theory for JavaScript and TypeScript: the P, L, R transformations, hexatonic and octatonic cycles, the Tonnetz lattice, and shortest transformation paths between triads. Typed, zero runtime dependencies, runs in the browser and in Node.

Install

npm install tonnetz

30-second example

import { triad, p, l, r, transform, hexatonicPole, pathBetween, triadName } from "tonnetz";

const c = triad(0, "major");        // C major

p(c);                                // { root: 0, quality: "minor" }   C minor
l(c);                                // { root: 4, quality: "minor" }   E minor
r(c);                                // { root: 9, quality: "minor" }   A minor

triadName(hexatonicPole(c));         // "G# minor"  (no common tones)
triadName(transform(c, "LPR"));      // "C# minor"  (apply L, then P, then R)

pathBetween(c, triad(5, "minor"));   // "PLR"  shortest route to F minor

Chord symbol parsing (v0.3.0)

import { parseChord, chordCandidates } from "tonnetz";

parseChord("C");       // { root: 0, quality: "major",    pitchClasses: [0, 4, 7] }
parseChord("Cm7");     // { root: 0, quality: "minor7",   pitchClasses: [0, 3, 7, 10] }
parseChord("F#maj7");  // { root: 6, quality: "major7",   pitchClasses: [1, 6, 10, 11] }
parseChord("Bbdim7");  // { root: 10, quality: "diminished7", pitchClasses: [0, 3, 6, 10] }
parseChord("Csus4");   // { root: 0, quality: "sus4",     pitchClasses: [0, 5, 7] }
parseChord("xyz");     // null

// Identify all chords that contain the pitch classes 0, 4, 7 (C major triad).
chordCandidates([0, 4, 7]);
// [{ root: 0, quality: "major", symbol: "C" }, ...]

Triads are { root, quality } with root a pitch class (0..11, C = 0). All functions are pure.

Why this exists

Neo-Riemannian theory (the PLR transformations and the Tonnetz) is standard in modern music theory, but there is no JavaScript or TypeScript library for it. tonal covers tonal harmony but not transformational theory; Tone.js is for audio; music21 is a large Python framework that does not run in a browser. tonnetz fills that gap with a small, correct, dependency-free engine, well suited to interactive teaching tools and analysis.

Comparison

Capability	tonnetz	tonal	music21
P, L, R transformations	yes	no	yes
Compound transformations	yes	no	yes
Hexatonic / octatonic cycles	yes	no	partial
Shortest PLR path	yes	no	no
Tonnetz lattice coordinates	yes	no	no
Common chord symbol parsing	yes	yes	yes
Zero runtime dependencies	yes	yes	no
Runs in the browser	yes	yes	no
Language	TS	JS/TS	Python

API

Triads

• triad(root, quality) constructs a triad, reducing the root modulo 12.
• triadToPitchClasses(t) returns the three pitch classes.
• isConsonantTriad(pcs) identifies a pitch-class set as a major or minor triad, or null.
• triadName(t) returns a readable name such as "C major".
• allTriads() returns all 24 consonant triads.
• triadsEqual(a, b) compares root and quality.

Transformations

• p(t), l(t), r(t) are the Parallel, Leittonwechsel, and Relative transformations.
• n(t) (Nebenverwandt) and s(t) (Slide) are the named compound transformations.
• transform(t, "LPR") applies a sequence of operations, left to right.
• hexatonicPole(t) returns the maximally distant triad (LPL).

Cycles and paths

• hexatonicCycle(t) returns the six triads of the hexatonic cycle.
• octatonicCycle(t) returns the eight triads of the octatonic cycle.
• pathBetween(from, to) returns the shortest P, L, R sequence mapping one triad to another.

Geometry and relations

• commonTones(a, b) counts shared pitch classes.
• pitchAtLattice(fifths, majorThirds) maps a Tonnetz lattice coordinate to a pitch class.

Chord symbol parsing

• parseChord(symbol) parses a standard chord symbol string (e.g. "Cm7", "F#maj7", "Bbdim7", "Csus4", "CmM7") into { root, quality, pitchClasses }. Root is a pitch class (C = 0, C# = 1, ..., B = 11). Accepts all 12 roots with sharps and flats. Returns null for unrecognized input.
• chordCandidates(pcs) is the inverse: given a pitch-class array, returns all recognized chord symbols whose pitch-class content exactly matches, sorted deterministically by root then quality.
• ChordQuality is the type for the quality field, a union of string literals.

Supported quality labels and the spellings accepted for each:

Quality label	Accepted suffixes	Example
major	(none), maj, M	C, Cmaj
minor	m, min, -	Cm, Cmin
diminished	dim, o	Cdim, Co
augmented	aug, +	Caug, C+
dominant7	7	C7
major7	maj7, M7	Cmaj7
minor7	m7, min7, -7	Cm7
halfDiminished7	m7b5, ø7, ø	Cm7b5
diminished7	dim7, o7	Cdim7
sus2	sus2	Csus2
sus4	sus4	Csus4
minorMajor7	mM7, m(maj7), min(maj7)	CmM7

The transformations

• P (Parallel) swaps quality on the same root: C major to C minor.
• L (Leittonwechsel): C major to E minor, A minor to F major.
• R (Relative): C major to A minor, A minor to C major.

Each preserves exactly two common tones, and each is its own inverse. Together they generate the dihedral group of order 24 acting on the 24 consonant triads, which is why a path always exists between any two triads. These properties are tested.

Roadmap

• Seventh-chord transformations (Childs/Gollin neo-Riemannian operations on seventh chords).
• Tonnetz triangle coordinates for rendering.

Examples

npm run example

Testing

npm test

Tests cover the exact textbook transformations and group-theoretic invariants (involutions, the two-common-tone property, and that every shortest path actually maps its source onto its target across all 24 triads).

Contributing

Issues and pull requests are welcome. See CONTRIBUTING.md.

License

MIT. See LICENSE.