tonus 0.1.8 → 0.5.0

package/docs/api/tuning.md

@@ -0,0 +1,619 @@
+# Tuning
+
+`tonus.temperamentum` is the library's model of medieval pitch. It builds
+a tuning context (temperament, mode, A4) and returns helper functions to tune and analyze pitch content. The engine depends on nothing
+else in the library and may be used alone; every pitch elsewhere in tonus
+is resolved through one of these contexts. The default tuning is
+Pythagorean, as in the treatises.
+
+- [Tuning](#tuning)
+  - [The context — `temperamentum`](#the-context--temperamentum)
+  - [Pitch input](#pitch-input)
+  - [Pitches — `nota`](#pitches--nota)
+  - [Steps — `gradus`](#steps--gradus)
+  - [Intervals — `intervallum`](#intervals--intervallum)
+  - [Neumes — `neuma`](#neumes--neuma)
+  - [Ratios — `ratio`](#ratios--ratio)
+  - [The gamut — `gamut`](#the-gamut--gamut)
+  - [Modes — `modus`](#modes--modus)
+    - [Cadence figures](#cadence-figures)
+    - [The corpus catalogue — `CADENTIAE`](#the-corpus-catalogue--cadentiae)
+      - [Lift — how mode-bound a close is](#lift--how-mode-bound-a-close-is)
+  - [Psalm tones — `tonus`](#psalm-tones--tonus)
+  - [Theory \& Context](#theory--context)
+    - [The presets](#the-presets)
+
+## The context — `temperamentum`
+
+`temperamentum(input?)` returns a `Temperamentum`. The input is a tuning
+name, an options object, or nothing; with nothing, the context is
+Pythagorean, mode `"auto"`, A4 = 440 Hz. Invalid input throws.
+
+```js
+tonus.temperamentum(); // pythagorean, mode auto, A4=440
+tonus.temperamentum("pythagorean"); // string shorthand
+tonus.temperamentum({ tuning: "meantone", comma: "1/4" });
+tonus.temperamentum({ tuning: "ptolemy-intense" }); // just intonation
+tonus.temperamentum({ tuning: "equal", mode: 3, a4: 415 });
+tonus.temperamentum({ scale: ["1/1", "9/8", "5/4" /* … */] }); // custom array
+tonus.temperamentum({ scale: "! meanquar.scl\n…" }); // Scala file
+```
+
+**`TemperamentumOpts`**
+
+| Field       | Type                 | Default         | Description                                                                                                               |
+| ----------- | -------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `tuning`    | `Tuning`             | `"pythagorean"` | Base temperament                                                                                                          |
+| `mode`      | `number \| "auto"`   | `"auto"`        | Gregorian mode (1–8); `"auto"` resolves from chant, falls back to mode 1 (final D)                                        |
+| `a4`        | `number`             | `440`           | A4 reference frequency in Hz                                                                                              |
+| `root`      | `number`             | mode finalis    | Root pitch class override (0–11)                                                                                          |
+| `transpose` | `number`             | `0`             | Output semitone transposition                                                                                             |
+| `comma`     | `number \| string`   | —               | Meantone comma (`0.25`, `"1/4"`, `"1/3"`); ignored for other tunings                                                      |
+| `scale`     | `string \| string[]` | —               | Scala `.scl` file string or array of 7/12 ratio/cent values, beginning at `1/1` (degree list) or ending at `2/1` (Scala convention); implies custom tuning, name from the Scala description |
+
+The tuning presets:
+
+| Name                | Description                                                                                  |
+| ------------------- | -------------------------------------------------------------------------------------------- |
+| `"pythagorean"`     | Pure fifths (3/2), no tempering. Default                                                     |
+| `"meantone"`        | Tempered fifths; `comma` controls the amount (default 1/4)                                   |
+| `"equal"`           | 12-tone equal temperament                                                                    |
+| `"ptolemy-intense"` | Ptolemy's intense diatonic (_syntonon_) — classical just intonation, pure major thirds (5/4) |
+| `"ptolemy-soft"`    | Ptolemy's soft diatonic (_malakon_) — septimal tuning, 8/7 whole tone                        |
+| `"ptolemy-equable"` | Ptolemy's equable diatonic (_homalon_) — undecimal tuning, neutral 12/11 seconds             |
+
+What each preset is, and when to choose it, is treated in
+[Theory & Context](#theory--context). Any other string is accepted as a
+custom tuning name (for instance, from a Scala file description).
+
+```ts
+interface Temperamentum {
+  // resolved
+  tuning: Tuning;
+  mode: number | "auto";
+  a4: number;
+  root: number;
+  transpose: number;
+  comma: number;
+
+  // computed
+  ratios: number[]; // frequency ratios relative to root, one per pitch class
+  cents: number[]; // cent values per pitch class, relative to root
+
+  // methods
+  nota(input: PitchInput): Pitch;
+  gradus(input: PitchInput): Step;
+  intervallum(a: PitchInput, b: PitchInput): Interval;
+  ratio(input: string): RatioResult & { step: Step | null };
+  neuma(inputs: PitchInput[]): Neume;
+  gamut(opts?: GamutOptions): Pitch[];
+  modus(mode: number): Modus;
+  tonus(opts?: TonusOpts): Tonus;
+}
+```
+
+## Pitch input
+
+Every method that takes a pitch accepts the same forms. A number is a MIDI
+note (a non-integer or a value past 127 reads as a frequency in Hz); a
+string is scientific pitch notation or a GABC letter; an object addresses
+one system explicitly (`{ hz: 293.33 }` for an exact frequency). All inputs resolve to a pitch
+first; `transpose` is applied last as a uniform output shift.
+
+```js
+t.nota(62); // MIDI
+t.nota("D4"); // scientific pitch notation
+t.nota(293.33); // frequency (any non-integer, or > 127)
+t.nota({ gabc: "d", clef: "c4" }); // GABC letter under a clef
+t.nota({ solmization: "RE", hexachord: "naturale" }); // hexachordal address
+```
+
+```ts
+type PitchInput = number | string | PitchObject;
+
+interface PitchObject {
+  midi?: number;
+  spn?: string;
+  hz?: number;
+  gabc?: string;
+  clef?: string; // default "c4", only with gabc
+  solfege?: string; // modern fixed-do: "DO" | "RE" | "MI" | "FA" | "SOL" | "LA" | "SI"
+  solmization?: string; // medieval: "UT" | "RE" | "MI" | "FA" | "SOL" | "LA"
+  hexachord?: "durum" | "naturale" | "molle"; // default "naturale", only with solmization
+}
+```
+
+## Pitches — `nota`
+
+`nota` resolves any pitch input to a tuned `Pitch`. The frequency comes
+through the scale; the same note name lands on a different frequency in a
+different tuning.
+
+```js
+const t = tonus.temperamentum({ mode: 1 }); // pythagorean
+
+t.nota("D4");
+// { midi: 62, pc: 2, oct: 4, acc: 0, spn: "D4",
+//   hz: 293.33, offset: -1.96, bend: 8112, ratio: 1 }
+
+tonus.temperamentum({ root: 0 }).nota("C4").hz; // 260.74  pythagorean
+tonus.temperamentum({ tuning: "meantone", root: 0 }).nota("C4").hz; // 263.18  quarter-comma
+tonus.temperamentum({ tuning: "equal", root: 0 }).nota("C4").hz; // 261.63  equal
+```
+
+`offset` is the distance in cents from the equal-tempered pitch of the same
+MIDI number; `bend` is the corresponding 14-bit MIDI pitch bend. `Pitch` is
+the tuned identity type used everywhere in tonus: in `Neume.pitches`, as
+`note.pitch` in the score engine, and on `Attractor.pitch` in the imprint.
+
+```ts
+interface Pitch {
+  midi: number;
+  pc: number; // pitch class 0–11
+  oct: number;
+  acc: -1 | 0 | 1; // flat, natural, sharp
+  spn: string; // scientific pitch name, e.g. "D4"
+  hz: number; // frequency in Hz (through the scale)
+  offset: number; // cents from 12-TET
+  bend: number; // 14-bit MIDI pitch bend, 8192 = center
+  ratio: number; // scale ratio for this pc
+}
+```
+
+## Steps — `gradus`
+
+`gradus` returns the modal and Guidonian identity of a pitch class: its
+letter, its compound name, its hexachord and solmization syllable, the
+mutations available to it, its position on the Guidonian hand, and its
+degree and role in the current mode. `Step` carries no tuning data; that is
+`Pitch`'s office.
+
+```js
+const t = tonus.temperamentum({ mode: 1 });
+
+t.gradus("D4");
+// { pc: 2, name: "d", nomen: "Delasolre",
+//   hexachord: "naturale", solmization: "RE",
+//   variants: [ { hexachord: "durum",    solmization: "SOL" },
+//               { hexachord: "naturale", solmization: "RE"  },
+//               { hexachord: "molle",    solmization: "LA"  } ],
+//   hand: { finger: "middle", region: "tip" },
+//   degree: 1, role: "finalis" }
+```
+
+The `variants` array lists the step's solmization in every hexachord that
+contains it; these are the mutations a medieval singer had available at
+that step. `degree` and `role` read against the resolved mode (`"auto"`
+falls back to mode 1); for a chromatic pitch outside the mode's scale they
+are `null`.
+
+The hand position names the joint a singer would point to. The loci follow the
+canonical counter-clockwise spiral (Γ ut at the thumb tip, across the finger
+bases, up the little finger, back across the tips, in), not a linear fill:
+
+| `hand` field | values                              |
+| ------------ | ----------------------------------- |
+| `finger`     | thumb, index, middle, ring, pinky   |
+| `region`     | base, mid, top, tip, super          |
+
+```ts
+interface StepVariant {
+  hexachord: "durum" | "naturale" | "molle";
+  solmization: string;
+}
+
+interface Step {
+  pc: number; // pitch class 0–11
+  name: string; // "d" (Guidonian) or SPN letter fallback
+  nomen: string | null; // "Delasolre"; null out of gamut
+  hexachord: "durum" | "naturale" | "molle" | null;
+  solmization: string | null; // null out of gamut
+  variants: StepVariant[]; // available mutations across hexachords
+  hand: { finger: string; region: string } | null; // Guidonian hand position
+  degree: number | null; // 1–7 diatonic degree in mode
+  role: "finalis" | "tenor" | "other" | null;
+}
+```
+
+## Intervals — `intervallum`
+
+`intervallum` classifies the interval between two pitches: its Latin name,
+its Greek alias where one exists, its quality, class, direction, and
+consonance grade.
+
+```js
+t.intervallum("D4", "A4");
+// { nomen: "Quinta", alias: "Diapente", quality: "perfect",
+//   class: "P5", direction: "up", semitones: 7, cents: 700,
+//   consonance: "perfect" }
+```
+
+`semitones` and `cents` describe the interval class in nominal
+(equal-tempered) terms. The tuned distance between two particular pitches
+is the ratio of their frequencies; take it from `nota`.
+
+| field        | values                                                           |
+| ------------ | ---------------------------------------------------------------- |
+| `class`      | `P1` `m2` `M2` `m3` `M3` `P4` `TT` `P5` `m6` `M6` `m7` `M7` `P8` |
+| `quality`    | perfect, major, minor, augmented                                 |
+| `direction`  | up, down, unison                                                 |
+| `consonance` | perfect, imperfect, dissonant                                    |
+
+```ts
+interface Interval {
+  nomen: string; // e.g. "Quinta", "Semitonium"
+  alias?: string; // e.g. "Diapente", "Diatessaron"
+  quality: string;
+  class: string;
+  direction: string;
+  semitones: number;
+  cents: number; // nominal class value
+  consonance: string;
+}
+```
+
+## Neumes — `neuma`
+
+The neume is chant's unit of notation: a group of notes written as one
+figure and sung on one syllable. `neuma` classifies a sequence of pitches
+as a neume shape, under the Solesmes nomenclature, and returns the tuned
+pitches with the intervals between them.
+
+```js
+t.neuma(["D4", "F4", "E4"]);
+// shape: "torculus" — up, then down
+// intervals: Tertia minor, Semitonium
+```
+
+Shapes that match no simple figure classify as `"compound"`.
+
+| `shape`     | figure             | `shape`              | figure                      |
+| ----------- | ------------------ | -------------------- | --------------------------- |
+| `punctum`   | a single note      | `torculus resupinus` | torculus, then rising       |
+| `pes`       | two notes, rising  | `porrectus flexus`   | porrectus, then falling     |
+| `clivis`    | two notes, falling | `scandicus flexus`   | scandicus, then falling     |
+| `torculus`  | three: up, down    | `climacus resupinus` | climacus, then rising       |
+| `porrectus` | three: down, up    | `pes subpunctis`     | pes, then descending points |
+| `scandicus` | three, rising      | `compound`           | any figure not above        |
+| `climacus`  | three, falling     |                      |                             |
+
+```ts
+interface Neume {
+  pitches: Pitch[];
+  intervals: Interval[];
+  shape: string; // a value from the table above
+}
+```
+
+## Ratios — `ratio`
+
+`ratio` converts between cents, decimal ratios, and colon display
+notation, following the Scala conventions: a period means cents
+(`"701.955"`); a slash, colon, or bare integer means a ratio (`"3/2"`,
+`"3:2"`, `"2"`). When the ratio corresponds to a degree of the current
+scale, the matching `Step` is returned with it.
+
+```js
+t.ratio("3/2");
+// { ratio: 1.5, cents: 701.96, display: "3:2",
+//   step: { nomen: "Alamire", degree: 5, role: "tenor", … } }
+```
+
+In mode 1 the pure fifth lands on the tenor; the step field says so.
+
+```ts
+interface RatioResult {
+  ratio: number; // decimal frequency ratio
+  cents: number; // interval in cents
+  display: string; // colon notation, e.g. "3:2"
+}
+```
+
+## The gamut — `gamut`
+
+The gamut is the medieval note-space: the ordered range of singable
+pitches Guido's system named from Gammaut upward. `gamut` returns the
+tuned pitches of the scale across a span. With a mode set, the default
+span is the mode's ambitus; mode 1 yields twelve diatonic pitches from D3
+to A4. The `chromatic` option adds the chromatic degrees; `span` sets
+explicit MIDI bounds.
+
+```js
+const g = t.gamut(); // 12 pitches, D3 … A4 (mode 1 ambitus)
+t.gamut({ span: [48, 72], chromatic: true });
+```
+
+```ts
+interface GamutOptions {
+  span?: [number, number]; // [lowest, highest] MIDI
+  chromatic?: boolean; // include chromatic pitches, default false
+}
+```
+
+## Modes — `modus`
+
+`modus` returns the full profile of one of the eight modes, as the
+medieval tonaries describe them:
+
+- its identity — Latin name, modern alias, _maneria_ (the family: Protus,
+  Deuterus, Tritus, Tetrardus), and authentic or plagal type;
+- its structure — finalis, tenor, scale degrees, ambitus, and the species
+  of fifth and fourth that build it;
+- its practice — hexachords in rank order, melodic profile, its cadence
+  figures, and permitted modulations.
+
+Each mode also carries its traditional **ethos** (the character medieval theory
+ascribed to it) as both a Latin epithet (`gravis`, `tristis`, …) and an English
+gloss. The full set and its source are at the data, in
+[`temper/data/modes.ts`](https://github.com/jeffreypierce/tonus/blob/main/src/engines/temper/data/modes.ts).
+
+The `modulations` fields (`regular`, `conceded`, and `initials`) are the
+mode's tonal centres and valid openings, each list **ordered by importance**
+(after Rockstro's Grove table [`rockstro-grove`](https://github.com/jeffreypierce/tonus/blob/main/BIBLIOGRAPHY.md)). The
+modal-affinity scorer reads that order; the reasoning is documented at the
+data, in [`temper/data/modes.ts`](https://github.com/jeffreypierce/tonus/blob/main/src/engines/temper/data/modes.ts).
+
+`modus` resolves the mode's structural pitches through its own
+temperamentum: the **finalis** and **reciting** tone as tuned notes (pitch +
+Guidonian step), and **ambitusNotes**, the mode's diatonic range walked out
+note by note. The raw `ModeData` fields (`final`, `tenor`, `cadences`, …)
+remain alongside — `Modus` extends `ModeData`.
+
+```js
+t.modus(1);
+// { mode: 1, nomen: "Protus Authenticus", alias: "dorian",
+//   maneria: "Protus", type: "authentic",
+//   final: 2, tenor: 9,
+//   finalis: { pitch: <D4 293.33 Hz>, step: { … role: "finalis" } },
+//   reciting: { pitch: <A4>, step: { … role: "tenor" } },
+//   ambitusNotes: [ <D4>, <E4>, <F4>, … ],
+//   profile: { mood: "serious", ethos: "gravis", … }, … }
+```
+
+```ts
+interface ModeProfile {
+  mood: string; // English gloss of the ethos, e.g. "serious"
+  ethos: string; // traditional Latin epithet, e.g. "gravis"
+  phrasing: "recitative" | "lyrical" | "hymnic" | "solemn";
+  melodic: "rising" | "falling" | "arch" | "neutral";
+  tendency: "melismatic" | "neumatic" | "syllabic" | "neutral";
+}
+
+interface CadenceFigure {
+  id: string; // solmization, e.g. "sol-fa-re"
+  steps: number[]; // diatonic steps relative to the final; resolution (0) last
+}
+
+interface ModeData {
+  mode: number;
+  nomen: string; // "Protus Authenticus"
+  alias: string; // "dorian" (modern name)
+  maneria: string; // "Protus" — the mode family
+  type: "authentic" | "plagal";
+  final: number; // finalis pitch class (C=0)
+  tenor: number; // reciting tone pitch class
+  recitingNotes: { pc: number; rank: string; label: string }[]; // tenor + secondary reciting pitches
+  scalePcs: number[]; // 7 diatonic pitch classes
+  hexachords: ("durum" | "naturale" | "molle")[]; // rank-ordered
+  profile: ModeProfile;
+  cadences: CadenceFigure[]; // characteristic cadence figures
+  modulations: {
+    regular: number[];
+    conceded: number[];
+    initials: number[];
+  };
+  ambitus: {
+    lowest: number;
+    highest: number;
+    span: number;
+  };
+  species: {
+    fifth: [number, number];
+    fourth: [number, number];
+  };
+}
+
+interface TunedNote {
+  pitch: Pitch; // tuned through the temperamentum
+  step: Step; // Guidonian annotation
+}
+
+interface Modus extends ModeData {
+  finalis: TunedNote; // the final, tuned
+  reciting: TunedNote; // the tenor / reciting tone, tuned
+  ambitusNotes: TunedNote[]; // every diatonic step across the mode's range
+}
+```
+
+### Cadence figures
+
+Each mode carries the melodic figures its phrases characteristically close
+on, in `modus(n).cadences` — the shapes by which a chant comes to rest, stored
+as diatonic steps relative to the final. The score engine reads them to name a
+phrase's cadence ([score.md](score.md#cadences)).
+
+| Maneria (final) | Figures (solmization → final)     |
+| --------------- | --------------------------------- |
+| Protus (Re)     | mi-re, ut-re, sol-fa-re, mi-fa-re |
+| Deuterus (Mi)   | fa-mi, re-mi, sol-fa-mi           |
+| Tritus (Fa)     | mi-fa, fa-mi-fa, la-sol-fa        |
+| Tetrardus (Sol) | la-sol, fa-sol, ut-sol, ut-ti-sol |
+
+The catalogue is an editorial synthesis covering the final cadences; its step
+encoding, sources, and known gaps (medial cadences are not yet included) are
+documented at the data — see `CadenceFigure` in
+[`temper/data/modes.ts`](https://github.com/jeffreypierce/tonus/blob/main/src/engines/temper/data/modes.ts).
+
+This is the **tradita** half — what the treatises say. Its counterpart is the
+corpus tally below, and they are not interchangeable: see [one spine, two
+annotations](score.md#one-spine-two-annotations).
+
+### The corpus catalogue — `CADENTIAE`
+
+Where the figures above are received, [`CADENTIAE`](index.md#the-appendix) is
+**mined**: every phrase-end in the sung corpus, grouped into families by what
+the melody actually did. A family is a **shape** — the closing tail's
+successive semitone intervals — and an **arrival**, where it landed relative
+to the chant's own closing note. Together they are the key, `"2,0,-2 @0"`, and
+the key is the family's whole name.
+
+About 110 families clear the floor of 50 occurrences, covering about 57% of all
+phrase-ends. The rest of the tail is real but too thin to characterise.
+
+```ts
+interface CadentiaFamilia {
+  key: string;       // "shape @arrival" — the name, and the join
+  shape: number[];   // successive semitone intervals of the closing tail
+  arrival: number;   // SIGNED semitones from the chant's own closing note
+  n: number;         // corpus occurrences
+  share: number;     // n over ALL phrase-ends (CADENTIAE_POPULATION.ends)
+  finality: number;  // share of those occurrences at a final close
+  modes: Record<string, number>; // occurrences by mode digit ("?" = mode-less)
+}
+```
+
+`share` is taken against **every** phrase-end, not against the ~57% that
+cleared the floor. The denominator ships beside the table:
+
+```ts
+CADENTIAE_POPULATION.ends;   // 26787 — all phrase-ends, sung corpus
+CADENTIAE_POPULATION.byMode; // the same total per mode digit
+```
+
+#### Lift — how mode-bound a close is
+
+`modes` and `byMode` share a denominator, so a family's **lift** in a given
+mode is one division: how much more (or less) that mode reaches for this close
+than the corpus at large.
+
+```js
+import { CADENTIAE, CADENTIAE_POPULATION as POP } from "tonus";
+
+const fam = CADENTIAE.find((f) => f.key === "2,0,-2 @0");
+const lift = (f, mode) =>
+  (f.modes[String(mode)] / POP.byMode[String(mode)]) / f.share;
+
+lift(fam, 6); // 2.15
+lift(fam, 4); // 0.07
+```
+
+The commonest family in the corpus — about 1,100 occurrences, about 4% of all
+phrase-ends, closing a little under half the time — is not reached for evenly.
+Mode 6 reaches for this close more than twice as often as the corpus does;
+mode 4 almost never. That is the figure the tonarium prints under a cadence
+([score.md](score.md#the-analysis-tracks)).
+
+**The ratio is not baked.** The table exports the vocabulary — counts and
+their denominators — and leaves the arithmetic to the caller. Two cautions when
+you take it: below roughly ten in-mode occurrences the ratio is one or two
+chants deciding a number that reads like a measurement, and a mode-less chant
+(`"?"`) has no denominator at all. In both cases fall back to `share`.
+
+## Psalm tones — `tonus`
+
+`tonus` returns the recitation formula of the context's mode as tuned
+pitches: the **intonatio** (the opening rise), the **mediatio** (the
+cadence at the verse's colon), and the **terminatio** (the closing
+cadence). The termination varies by **differentia**, the cadential variant
+chosen to lead back into the antiphon; the mode's default differentia is
+used when none is given. The mode must be set explicitly — with mode
+`"auto"`, `tonus()` throws.
+
+```js
+const t = tonus.temperamentum({ mode: 1 });
+
+t.tonus();
+// { mode: 1, differentia: "1g",
+//   intonatio:  [F3, A3, C4],
+//   mediatio:   [C4, A3, G3, A3],
+//   terminatio: [C4, A3, G3, A3, G3] }   // each entry a tuned Pitch
+
+t.tonus({ differentia: "1f" });
+```
+
+To sing psalm texts to these formulas, use
+[`tonus.psalmus`](chant.md#psalms--psalmus), which returns
+GABC-encoded verses pointed to the tone.
+
+```ts
+interface TonusOpts {
+  differentia?: string; // e.g. "6F", "4e"; mode comes from Temperamentum, throws if "auto"
+}
+
+interface Tonus {
+  mode: number;
+  differentia: string;
+  intonatio: Pitch[]; // opening intonation formula
+  mediatio: Pitch[]; // mediant cadence at the verse colon
+  terminatio: Pitch[]; // termination cadence (per differentia)
+}
+```
+
+## Theory & Context
+
+`temperamentum` represents a tuning as a table of twelve frequency ratios,
+one per pitch class, relative to the context's root and anchored at the
+reference A4. The presets fill that table from history: the Pythagorean
+division the treatises teach, the meantone compromise of the Renaissance,
+Ptolemy's three diatonic shades, and the modern equal division.
+
+### The presets
+
+Six ways to fill the table, five historical and one modern. Each has a
+character; the interval arithmetic, the commas that drive it, and the
+editorial choices behind it are documented at the builder, in
+[`temper/scale.ts`](https://github.com/jeffreypierce/tonus/blob/main/src/engines/temper/scale.ts).
+
+- **`"pythagorean"`** — the medieval default. All intervals from the pure
+  fifth and the octave: perfect melodic fifths and fourths, a narrow keen
+  semitone, a wide third that never has to be a consonance. Correct for
+  unaccompanied chant, and the tuning the treatises teach.
+
+  ```js
+  tonus.temperamentum(); // pythagorean, A4 = 440
+  ```
+
+- **`"meantone"`** — the Renaissance compromise. Narrows each fifth to buy
+  purer thirds; `comma` sets how far (`"1/4"`, the default, gives pure major
+  thirds and the 16th-century sound; `"1/3"` pure minor thirds; `"1/6"` leans
+  baroque). One fifth is left over as the _wolf_.
+
+  ```js
+  tonus.temperamentum({ tuning: "meantone", comma: "1/4" });
+  ```
+
+- **The three Ptolemaic diatonics** — antiquity's just intonations, Ptolemy's
+  three "shades" of the diatonic. `"ptolemy-intense"` is classical just
+  intonation (pure thirds; coherent with the Ptolemy doctrina in
+  [`harmonia`](heavens.md)); `"ptolemy-soft"` is septimal and dark;
+  `"ptolemy-equable"` has neutral, near-equal steps outside the Latin tradition.
+  Each tunes one fixed scale, so pairing one with a non-default mode can surface
+  unexpected intervals, including a wolf.
+
+  ```js
+  tonus.temperamentum({ tuning: "ptolemy-intense" });
+  ```
+
+- **`"equal"`** — twelve identical semitones; nothing pure, nothing unusable.
+  Anachronistic for chant by some seven centuries, included as a reference point.
+
+  ```js
+  tonus.temperamentum({ tuning: "equal", a4: 415 }); // equal at baroque pitch
+  ```
+
+Any 7- or 12-step scale can also be supplied directly as ratios or cents, or as
+a [Scala `.scl`](https://www.huygens-fokker.org/scala/scl_format.html) file:
+
+```js
+tonus.temperamentum({
+  scale: ["1/1", "9/8", "5/4", "4/3", "3/2", "5/3", "15/8"],
+});
+tonus.temperamentum({ scale: sclFileString }); // name taken from the file
+```
+
+## Sources
+
+Sources for this page are in the central [bibliography](https://github.com/jeffreypierce/tonus/blob/main/BIBLIOGRAPHY.md):
+`boethius-institutione`, `ptolemy-harmonics`, `schulter-harmony`,
+`rockstro-grove`, `niedermeyer-ortigue`, `bragers-treatise`,
+`sunol-textbook`, `saulnier-modes`, `liber-usualis`, `scala-format`.

package/package.json

@@ -1,11 +1,10 @@
 {
   "name": "tonus",
-  "version": "0.1.8",
-  "private": false,
+  "version": "0.5.0",
   "type": "module",
   "description": "Medieval music analysis and performance: GABC plainchant exports, liturgical calendar, tuning systems, ephemeris, and the harmony of the spheres",
   "author": "Jeffrey Pierce <jeffrey@jeffreypierce.net>",
-  "license": "MIT",
+  "license": "PolyForm-Noncommercial-1.0.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/jeffreypierce/tonus.git"
@@ -39,6 +38,7 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
+    "docs/api",
     "!dist/**/*.js.map",
     "!dist/**/*.d.ts.map",
     "LICENSE",
@@ -46,10 +46,16 @@
     "BIBLIOGRAPHY.md"
   ],
   "scripts": {
-    "build": "tsc && cp src/data/psalms.json dist/data/psalms.json",
+    "build": "tsc && cp src/data/psalms.json dist/data/psalms.json && cp src/data/smufl-glyphs.json dist/data/smufl-glyphs.json && cp src/data/office-ferial.json dist/data/office-ferial.json && cp src/data/commune-office.json dist/data/commune-office.json && cp src/data/seasonal-respbreve.json dist/data/seasonal-respbreve.json && cp src/data/attestation.json dist/data/attestation.json && node scripts/bake-data.mjs",
     "clean": "rm -rf dist",
     "test": "npm run build && node --test --test-reporter=spec tests/*.test.mjs",
-    "prepublishOnly": "npm run clean && npm run build"
+    "prepublishOnly": "npm run clean && npm run build",
+    "check:links": "node scripts/check-doc-links.mjs",
+    "site": "npm run build && node scripts/vendor-ink.mjs && rm -rf docs/dist && cp -R dist docs/dist",
+    "serve": "npm run site && node scripts/serve.mjs",
+    "diagrams": "npm run site && node scripts/diagram-lab.mjs",
+    "lab": "npm run build && node scripts/render-lab.mjs",
+    "stress": "npm run build && node scripts/render-stress.mjs"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/dist/data/office-matins-roman.d.ts

@@ -1,19 +0,0 @@
-export interface MatinsChant {
-    id: string;
-    type: string;
-    pos: string;
-}
-export interface MatinsNocturn {
-    n: number;
-    chants: MatinsChant[];
-}
-export interface MatinsDay {
-    id: string;
-    tonusFeastId: string | null;
-    name: string;
-    rank: string;
-    nocturns: MatinsNocturn[];
-    redirectedFrom: string | null;
-}
-export declare const MATINS_ROMAN: MatinsDay[];
-//# sourceMappingURL=office-matins-roman.d.ts.map