tonus

tonus is a medieval music and cosmology library. It covers:

• pitch, tuning, hexachords, and the eight church modes
• the liturgical calendar, the feast of the day, and mass selection
• the chant repertoire in GABC: propers, ordinary, office, and psalm tones
• chant rhythm and performance shaping, rendered to MIDI or MusicXML
• planetary positions voiced as tuned pitch across the classical theorists' "harmony of the spheres"

tonus is implemented in TypeScript and its API is a single namespace of methods. Every result is deterministic: the same query returns the same answer, computed locally from data that ships with the package, with no network calls.

Install

npm install tonus

ESM only. Node ≥ 20; works in the browser through a bundler. No runtime dependencies. Roughly 5,500 chants and the full 642-entry calendar ship in the package — 6.5 MB unpacked, 1.5 MB packed.

Documentation

One page per engine, in dependency order. Each page states its rules, then its theory and historical context, then its sources.

• Index — Table of contents and conventions.
• Tuning — temperamentum. The medieval pitch system: temperaments, Guidonian gamut and hand, hexachordal solmization and mutations, eight modes, and psalm tones. Depends on nothing else in the library.
• Calendar — festum, pascha. The Tridentine liturgical calendar resolved against dual-computus Easter: feasts with their authentic ranks, grades, and seasons, and the movable anchors of any year.
• Chant — cantus, proprium, ordinarium, officium, psalmus. The Solesmes books in GABC: Mass propers, the Kyriale, the Office hours, the psalter.
• Score — notatio. GABC into tuned notes: phrases, syllables, Solesmes arsis/thesis rhythm, prosody, the analytic imprint.
• Heavens — caelum, harmonia. An ephemeris computed from JPL orbital elements, voiced through the planetary doctrines of Boethius, Nicomachus, Pliny, and Ptolemy.

These pages are the middle of a three-level ladder: the API docs here link down into the code, where the full theory, provenance, and editorial reasoning live in comments beside what they explain. Read as deep as you care to. Sources for concepts, scholarship, and data are listed in BIBLIOGRAPHY.md; where sources disagree or run out, tonus makes an editorial call, recorded in the code and glossed in the page's Theory & Context section.

The tuning engine

The tuning engine is self-contained; every other engine resolves its pitches through it.

import tonus from "tonus";

const t = tonus.temperamentum({ mode: 1 }); // Pythagorean, mode 1

t.nota("D4");
// 293.33 Hz — the final of mode 1, tuned through pure fifths

t.gradus("D4");
// Delasolre: RE of the natural hexachord, role "finalis",
// middle finger, base joint, on the Guidonian hand

t.intervallum("D4", "A4");
// Quinta (alias Diapente), perfect — final to tenor

t.tonus();
// psalm tone 1, differentia 1g:
// intonatio F3–A3–C4, mediatio C4–A3–G3–A3, terminatio C4–A3–G3–A3–G3

The liturgical stack

The remaining engines compose:

const [feast] = tonus.festum({ date: new Date("2026-12-25") });
// nomen: "In Nativitate Domini", ritus: "Duplex I classis",
// grade: "duplex-i", tempus: "Tempus Nativitatis"

const [introit] = tonus.proprium({ feast, office: "in" });
// "Puer natus est", mode 7, GABC from the Liber Usualis

const score = tonus.notatio(introit, { temperamentum: t });
// phrases, syllables, tuned pitches, arsis/thesis rhythm, prosody, imprint

const harmony = tonus.harmonia(tonus.caelum({ date: feast.date }));
// each visible planet voiced as pitch and Greek vowel, after Boethius

Development

npm test          # builds and runs the suite (node --test)

The data files in src/data/ are generated by a separate extraction pipeline (tonus-corpus). Edits happen there, not here.

License

MIT. Chant and liturgical data derive from GregoBase and Divinum Officium; see BIBLIOGRAPHY.md for full attribution.