tonus 0.1.3 → 0.1.4

package/dist/engines/imprint.d.ts

@@ -1,7 +1,9 @@
 import type { Phrase } from "./score/types.js";
 import type { Pitch } from "./temper/pitch.js";
 import type { Scale } from "./temper/scale.js";
+import { type ModalAffinity } from "./temper/modality.js";
 import type { VoicedBody } from "./harmonia/voice.js";
+export type { ModalAffinity };
 export interface Attractor {
     pc: number;
     weight: number;
@@ -12,19 +14,18 @@ export interface VowelAttractor {
     weight: number;
     pitch: Pitch;
 }
-export interface ModalAffinity {
-    mode: number;
-    alias: string;
-    score: number;
-}
 export interface Imprint {
     pcDistribution: Record<number, number>;
     attractors: Attractor[];
     vowelAttractors: VowelAttractor[];
     modalAffinity: ModalAffinity[];
 }
-/** Build an Imprint from chant phrases (unweighted pc counts). */
-export declare function computeImprint(phrases: Phrase[], scale: Scale): Imprint;
+export interface ImprintOptions {
+    /** Positions "phrase:syllable:note" of cadence resolution notes, weighted up. */
+    cadenceNotes?: Set<string>;
+}
+/** Build an Imprint from chant phrases, weighting structural notes more. */
+export declare function computeImprint(phrases: Phrase[], scale: Scale, opts?: ImprintOptions): Imprint;
 /** Build an Imprint from voiced planetary bodies (presence-weighted pc counts). */
 export declare function computeImprintFromBodies(bodies: VoicedBody[], scale: Scale): Imprint;
 //# sourceMappingURL=imprint.d.ts.map

package/dist/engines/imprint.js

@@ -1,5 +1,5 @@
 import { toPitch } from "./temper/pitch.js";
-import { MODES } from "./temper/modes.js";
+import { computeModalAffinity } from "./temper/modality.js";
 const DEFAULT_TOP = 5;
 const DEFAULT_MIDI_OCTAVE = 4;
 const VOWELS = ["a", "e", "i", "o", "u"];
@@ -22,24 +22,6 @@ function computeAttractors(pcDistribution, scale, topN = DEFAULT_TOP) {
         pitch: pitchForPc(pc, scale),
     }));
 }
-function computeModalAffinity(pcDistribution) {
-    const results = [];
-    for (let m = 1; m <= 8; m++) {
-        const data = MODES.get(m);
-        if (!data)
-            continue;
-        const structural = new Set([
-            data.final,
-            data.tenor,
-            ...data.modulations.regular,
-        ]);
-        let score = 0;
-        for (const pc of structural)
-            score += pcDistribution[pc] ?? 0;
-        results.push({ mode: m, alias: data.alias, score });
-    }
-    return results.sort((a, b) => b.score - a.score);
-}
 function computeVowelAttractors(phrases, scale) {
     const vowelPcMap = new Map();
     for (const v of VOWELS)
@@ -85,15 +67,30 @@ function computeVowelAttractors(phrases, scale) {
     }
     return results.sort((a, b) => b.weight - a.weight);
 }
-/** Build an Imprint from chant phrases (unweighted pc counts). */
-export function computeImprint(phrases, scale) {
+// A note's contribution to the pc-distribution is raised where it carries more
+// structural weight: on an ictus (the rhythmic footfall) and, above all, when it
+// is a cadence's resolution. Cadence notes are passed in — the imprint sits below
+// the score engine, so it cannot detect them itself.
+const ICTUS_WEIGHT = 1.5;
+const CADENCE_WEIGHT = 2;
+/** Build an Imprint from chant phrases, weighting structural notes more. */
+export function computeImprint(phrases, scale, opts = {}) {
+    const cadenceNotes = opts.cadenceNotes;
     const pcCounts = new Array(12).fill(0);
     let total = 0;
-    for (const phrase of phrases) {
-        for (const syl of phrase.syllables) {
-            for (const note of syl.notes) {
-                pcCounts[note.pitch.pc]++;
-                total++;
+    for (let pi = 0; pi < phrases.length; pi++) {
+        const phrase = phrases[pi];
+        for (let si = 0; si < phrase.syllables.length; si++) {
+            const notes = phrase.syllables[si].notes;
+            for (let ni = 0; ni < notes.length; ni++) {
+                const note = notes[ni];
+                let w = 1;
+                if (note.context.ictus)
+                    w *= ICTUS_WEIGHT;
+                if (cadenceNotes?.has(`${pi}:${si}:${ni}`))
+                    w *= CADENCE_WEIGHT;
+                pcCounts[note.pitch.pc] += w;
+                total += w;
             }
         }
     }
@@ -101,11 +98,12 @@ export function computeImprint(phrases, scale) {
     for (let pc = 0; pc < 12; pc++) {
         pcDistribution[pc] = total > 0 ? pcCounts[pc] / total : 0;
     }
+    const firstNotePc = phrases[0]?.syllables[0]?.notes[0]?.pitch.pc;
     return {
         pcDistribution,
         attractors: computeAttractors(pcDistribution, scale),
         vowelAttractors: computeVowelAttractors(phrases, scale),
-        modalAffinity: computeModalAffinity(pcDistribution),
+        modalAffinity: computeModalAffinity(pcDistribution, firstNotePc),
     };
 }
 /** Build an Imprint from voiced planetary bodies (presence-weighted pc counts). */

package/dist/engines/score/api.d.ts

@@ -1,6 +1,7 @@
 import { type Imprint } from "../imprint.js";
 import { type Prosody } from "./prosody.js";
 import { type Cadence } from "./cadence.js";
+import { type Modulation } from "./modulation.js";
 import { type ChantTabulaRow } from "./tabula.js";
 import { type MidiOpts, type MidiEmitResult } from "./emitters/midi.js";
 import { type MusicXmlOpts, type MusicXmlEmitResult } from "./emitters/musicxml.js";
@@ -32,6 +33,8 @@ export interface Score {
     prosody: Prosody;
     /** Mode-specific cadence at each phrase-ending divisio. */
     cadences: Cadence[];
+    /** Passages where the tonal centre leans away from the home mode. */
+    modulations: Modulation[];
     imprint: Imprint;
     /**
      * Emit a Standard MIDI File from the score's tabula. Returns the file bytes
@@ -53,6 +56,7 @@ export interface Score {
 export declare function buildScore(chant: Chant, opts?: ScoreOpts): Score;
 export type { ParseError };
 export type { Cadence, CadenceTarget, CadenceApproach } from "./cadence.js";
+export type { Modulation } from "./modulation.js";
 export type { MidiOpts, MidiEmitResult, MidiJsonResult, MidiJsonEvent } from "./emitters/midi.js";
 export type { MusicXmlOpts, MusicXmlEmitResult } from "./emitters/musicxml.js";
 //# sourceMappingURL=api.d.ts.map

package/dist/engines/score/api.js

@@ -8,6 +8,7 @@ import { computeMeta } from "./meta.js";
 import { computeImprint } from "../imprint.js";
 import { computeProsody } from "./prosody.js";
 import { detectCadences } from "./cadence.js";
+import { detectModulations } from "./modulation.js";
 import { computeTabula } from "./tabula.js";
 import { MODES } from "../temper/modes.js";
 import { toMidi } from "./emitters/midi.js";
@@ -61,6 +62,8 @@ export function buildScore(chant, opts) {
     // Cadence detection runs here, where the resolved mode (and its cadence
     // figures) is in hand. Pure data — mirrors the arsis/thesis pass in ir.ts.
     const cadences = detectCadences(ir.phrases, meta.mode != null ? MODES.get(meta.mode) : undefined);
+    // Modulation: where the tonal centre leans away from the home mode.
+    const modulations = detectModulations(ir.phrases, meta.mode ?? undefined);
     const tabula = computeTabula(ir, {
         mode: meta.mode ?? undefined,
         a4Hz: opts?.temperamentum?.a4,
@@ -82,7 +85,14 @@ export function buildScore(chant, opts) {
         tabula,
         prosody: computeProsody(ir.phrases),
         cadences,
-        imprint: computeImprint(ir.phrases, scale),
+        modulations,
+        imprint: computeImprint(ir.phrases, scale, {
+            // Each cadence's resolution note (its last) is the strongest modal anchor.
+            cadenceNotes: new Set(cadences.map((c) => {
+                const [pi, si, ni] = c.notes[c.notes.length - 1];
+                return `${pi}:${si}:${ni}`;
+            })),
+        }),
         midi(emitOpts) {
             return toMidi(tabula, emitOpts);
         },

package/dist/engines/score/modulation.d.ts

@@ -0,0 +1,20 @@
+import type { Phrase } from "./types.js";
+export interface Modulation {
+    /** Phrase index where the modulation begins (inclusive). */
+    startPhrase: number;
+    /** Phrase index where it ends (inclusive). */
+    endPhrase: number;
+    /** The mode the passage leans toward (1–8). */
+    toMode: number;
+    /** 0–1: how strongly the foreign mode outscored the home mode, averaged. */
+    confidence: number;
+}
+/**
+ * Detect tonal-centre shifts. For each phrase, score it against every mode; a
+ * phrase whose top mode is not the home mode, and beats the home mode by MARGIN,
+ * "leans" toward that foreign mode. Consecutive phrases leaning to the same mode
+ * merge into one modulation span. `homeMode` is the chant's own mode (1–8); with
+ * no mode, nothing is detected.
+ */
+export declare function detectModulations(phrases: Phrase[], homeMode: number | undefined): Modulation[];
+//# sourceMappingURL=modulation.d.ts.map

package/dist/engines/score/modulation.js

@@ -0,0 +1,74 @@
+import { computeModalAffinity } from "../temper/modality.js";
+// How much a foreign mode must outscore the home mode (in normalised affinity)
+// before a phrase counts as leaning away. Calibrated against Suñol's worked
+// examples: at 0.25 the modulations he names in Christus resurgens (to mode 3)
+// register, while incidental modal colouring below that does not.
+const MARGIN = 0.25;
+/** The pitch-class distribution of one phrase's notes (fractions summing to 1). */
+function phrasePcDistribution(phrase) {
+    const counts = new Array(12).fill(0);
+    let total = 0;
+    for (const syl of phrase.syllables) {
+        for (const note of syl.notes) {
+            counts[note.pitch.pc]++;
+            total++;
+        }
+    }
+    const dist = {};
+    for (let pc = 0; pc < 12; pc++)
+        dist[pc] = total > 0 ? counts[pc] / total : 0;
+    return dist;
+}
+/**
+ * Detect tonal-centre shifts. For each phrase, score it against every mode; a
+ * phrase whose top mode is not the home mode, and beats the home mode by MARGIN,
+ * "leans" toward that foreign mode. Consecutive phrases leaning to the same mode
+ * merge into one modulation span. `homeMode` is the chant's own mode (1–8); with
+ * no mode, nothing is detected.
+ */
+export function detectModulations(phrases, homeMode) {
+    if (homeMode == null)
+        return [];
+    // Per-phrase lean: the foreign mode a phrase favours, with its margin over
+    // the home mode — or null if the phrase stays home.
+    const leans = phrases.map((phrase) => {
+        if (phrase.syllables.every((s) => s.notes.length === 0))
+            return null;
+        const affinity = computeModalAffinity(phrasePcDistribution(phrase));
+        const top = affinity[0];
+        if (!top || top.mode === homeMode)
+            return null;
+        const home = affinity.find((a) => a.mode === homeMode);
+        const margin = top.score - (home?.score ?? 0);
+        return margin >= MARGIN ? { mode: top.mode, margin } : null;
+    });
+    // Merge consecutive phrases leaning to the same foreign mode into spans.
+    const modulations = [];
+    let run = null;
+    const flush = () => {
+        if (!run)
+            return;
+        const avg = run.margins.reduce((s, m) => s + m, 0) / run.margins.length;
+        modulations.push({
+            startPhrase: run.start,
+            endPhrase: run.start + run.margins.length - 1,
+            toMode: run.mode,
+            confidence: Math.min(1, Math.round(avg * 100) / 100),
+        });
+        run = null;
+    };
+    for (let i = 0; i < leans.length; i++) {
+        const lean = leans[i];
+        if (lean && run && lean.mode === run.mode) {
+            run.margins.push(lean.margin);
+        }
+        else {
+            flush();
+            if (lean)
+                run = { mode: lean.mode, start: i, margins: [lean.margin] };
+        }
+    }
+    flush();
+    return modulations;
+}
+//# sourceMappingURL=modulation.js.map

package/dist/engines/temper/api.d.ts

@@ -28,6 +28,22 @@ export interface Tonus {
     mediatio: Pitch[];
     terminatio: Pitch[];
 }
+/** A pitch resolved through the tuning, with its Guidonian annotation. */
+export interface TunedNote {
+    pitch: Pitch;
+    step: Step;
+}
+/**
+ * A mode's reference data (ModeData), enriched with its structural pitches
+ * tuned through the temperamentum that returned it. `modus()`. Cadence figures
+ * stay in their diatonic-step form on `cadences` — they are transposition-
+ * relative by design.
+ */
+export interface Modus extends ModeData {
+    finalis: TunedNote;
+    reciting: TunedNote;
+    ambitusNotes: TunedNote[];
+}
 export interface Temperamentum {
     tuning: Tuning;
     mode: number | "auto";
@@ -45,7 +61,7 @@ export interface Temperamentum {
         step: Step | null;
     };
     gamut(opts?: GamutOptions): Pitch[];
-    modus(mode: number): ModeData;
+    modus(mode: number): Modus;
     tonus(opts?: TonusOpts): Tonus;
 }
 /**

package/dist/engines/temper/api.js

@@ -110,7 +110,25 @@ export function buildTemper(input) {
             return buildGamut(scala, gamutOpts);
         },
         modus(mode) {
-            return getMode(mode);
+            const data = getMode(mode);
+            // The mode's degrees are stored as semitone offsets from C (pc 0), with
+            // values past 12 in the upper octave. Anchor them at C4 (MIDI 60).
+            const tuned = (offset) => ({
+                pitch: toPitch(60 + offset, scala),
+                step: toStep(60 + offset, scala),
+            });
+            const scaleSet = new Set(data.scalePcs);
+            const ambitusNotes = [];
+            for (let off = data.ambitus.lowest; off <= data.ambitus.highest; off++) {
+                if (scaleSet.has(((off % 12) + 12) % 12))
+                    ambitusNotes.push(tuned(off));
+            }
+            return {
+                ...data,
+                finalis: tuned(data.final),
+                reciting: tuned(data.tenor),
+                ambitusNotes,
+            };
         },
         tonus(tonusOpts) {
             if (modeVal === "auto")

package/dist/engines/temper/modality.d.ts

@@ -0,0 +1,11 @@
+export interface ModalAffinity {
+    mode: number;
+    alias: string;
+    score: number;
+}
+/**
+ * Rank a pitch-class distribution against the eight modes, best fit first.
+ * `firstNotePc`, when given, applies the rank-weighted initials bonus.
+ */
+export declare function computeModalAffinity(pcDistribution: Record<number, number>, firstNotePc?: number): ModalAffinity[];
+//# sourceMappingURL=modality.d.ts.map

package/dist/engines/temper/modality.js

@@ -0,0 +1,57 @@
+// ---------------------------------------------------------------------------
+// engines/temper/modality — how well pitch content fits each church mode
+// ---------------------------------------------------------------------------
+// Modal theory, not tied to any one caller: the imprint uses it to fingerprint a
+// whole chant, modulation detection to read each phrase. A pure function of a
+// pitch-class distribution (and, optionally, the chant's opening note).
+import { MODES } from "./modes.js";
+// A mode's structural degrees are not equal: the finalis defines it, the tenor
+// anchors its recitation, and modulation degrees are only secondary colour. Time
+// spent on each pitch counts toward the mode in that proportion.
+const FINALIS_WEIGHT = 3;
+const TENOR_WEIGHT = 2;
+const REGULAR_MOD_WEIGHT = 1;
+const CONCEDED_MOD_WEIGHT = 0.5;
+// A chant's opening note is a modal signal: each mode lists its valid initials
+// in rank order (the first is the most characteristic). Opening on a mode's
+// primary initial boosts it more than opening on a lower-ranked one — which is
+// what separates an authentic mode from its plagal partner, since the two share
+// a finalis but rank the same opening pitch differently.
+const INITIAL_BONUS = 0.3;
+/**
+ * Rank a pitch-class distribution against the eight modes, best fit first.
+ * `firstNotePc`, when given, applies the rank-weighted initials bonus.
+ */
+export function computeModalAffinity(pcDistribution, firstNotePc) {
+    const results = [];
+    for (let m = 1; m <= 8; m++) {
+        const data = MODES.get(m);
+        if (!data)
+            continue;
+        // Weight each degree by its modal role; a pc that fills more than one role
+        // (e.g. a modulation degree that is also the tenor) takes the strongest.
+        const degreeWeight = new Map();
+        const set = (pc, w) => {
+            degreeWeight.set(pc, Math.max(degreeWeight.get(pc) ?? 0, w));
+        };
+        for (const pc of data.modulations.conceded)
+            set(pc % 12, CONCEDED_MOD_WEIGHT);
+        for (const pc of data.modulations.regular)
+            set(pc % 12, REGULAR_MOD_WEIGHT);
+        set(data.tenor, TENOR_WEIGHT);
+        set(data.final, FINALIS_WEIGHT);
+        let score = 0;
+        for (const [pc, w] of degreeWeight)
+            score += (pcDistribution[pc] ?? 0) * w;
+        // Initials bonus, scaled by how highly the mode ranks the opening pitch.
+        if (firstNotePc != null) {
+            const initials = data.modulations.initials;
+            const rank = initials.findIndex((pc) => pc % 12 === firstNotePc);
+            if (rank !== -1)
+                score += (INITIAL_BONUS * (initials.length - rank)) / initials.length;
+        }
+        results.push({ mode: m, alias: data.alias, score });
+    }
+    return results.sort((a, b) => b.score - a.score);
+}
+//# sourceMappingURL=modality.js.map

package/dist/index.d.ts

@@ -10,8 +10,8 @@ import { getCosmos } from "./engines/planet/planet.js";
 import { buildHarmonia } from "./engines/harmonia/api.js";
 import type { FeastQuery, Feast, Pascha, Season, Grade } from "./engines/cal/types.js";
 import type { CantusQuery, Chant, OrdinaryChant, PropriumQuery, OrdinariumQuery, OfficiumQuery, PsalmusQuery } from "./engines/chant/types.js";
-import type { TemperamentumInput, Temperamentum, Tuning, TemperamentumOpts, Pitch, PitchInput, Step, Neume, NeumeShape, Interval, ModeData, CadenceFigure, GamutOptions, Tonus, TonusOpts } from "./engines/temper/api.js";
-import type { Score, ScoreOpts, PondusInput, PondusOpts, AccentusInput, AccentusOpts, Cadence, CadenceTarget, CadenceApproach, MidiOpts, MidiEmitResult, MidiJsonResult, MidiJsonEvent, MusicXmlOpts, MusicXmlEmitResult } from "./engines/score/api.js";
+import type { TemperamentumInput, Temperamentum, Tuning, TemperamentumOpts, Pitch, PitchInput, Step, Neume, NeumeShape, Interval, ModeData, CadenceFigure, Modus, TunedNote, GamutOptions, Tonus, TonusOpts } from "./engines/temper/api.js";
+import type { Score, ScoreOpts, PondusInput, PondusOpts, AccentusInput, AccentusOpts, Cadence, CadenceTarget, CadenceApproach, Modulation, MidiOpts, MidiEmitResult, MidiJsonResult, MidiJsonEvent, MusicXmlOpts, MusicXmlEmitResult } from "./engines/score/api.js";
 import type { ChantTabulaRow } from "./engines/score/tabula.js";
 import type { Imprint, Attractor, VowelAttractor, ModalAffinity } from "./engines/imprint.js";
 import type { Prosody, RhythmicProfile, NoteRange, CadenceDistribution } from "./engines/score/prosody.js";
@@ -36,5 +36,5 @@ declare const tonus: {
 };
 export default tonus;
 export { SEASON_LABELS, TEMPUS_NAMES, GRADE_ORDER, GRADE_NAMES, gradeOrder, compareGrade, ritusToGrade, } from "./engines/cal/types.js";
-export type { Feast, FeastQuery, Pascha, Season, Grade, Chant, CantusQuery, OrdinaryChant, PropriumQuery, OrdinariumQuery, OfficiumQuery, PsalmusQuery, Temperamentum, TemperamentumInput, TemperamentumOpts, Tuning, Pitch, PitchInput, Step, Neume, NeumeShape, Interval, ModeData, CadenceFigure, GamutOptions, Tonus, TonusOpts, Score, ScoreOpts, PondusInput, PondusOpts, AccentusInput, AccentusOpts, Cadence, CadenceTarget, CadenceApproach, MidiOpts, MidiEmitResult, MidiJsonResult, MidiJsonEvent, MusicXmlOpts, MusicXmlEmitResult, ChantTabulaRow, Note, Performance, Phrase, Syllable, RestEvent, ParseError, ArsisThesis, VoicedPitch, Cosmos, CosmosQuery, Body, BodyName, Aspect, Imprint, Attractor, VowelAttractor, ModalAffinity, Prosody, RhythmicProfile, NoteRange, CadenceDistribution, Harmony, HarmoniaOpts, VoicedBody, VoicedAspect, Frame, Author, HarmonyTabulaRow, PlanetVowel, };
+export type { Feast, FeastQuery, Pascha, Season, Grade, Chant, CantusQuery, OrdinaryChant, PropriumQuery, OrdinariumQuery, OfficiumQuery, PsalmusQuery, Temperamentum, TemperamentumInput, TemperamentumOpts, Tuning, Pitch, PitchInput, Step, Neume, NeumeShape, Interval, ModeData, CadenceFigure, Modus, TunedNote, GamutOptions, Tonus, TonusOpts, Score, ScoreOpts, PondusInput, PondusOpts, AccentusInput, AccentusOpts, Cadence, CadenceTarget, CadenceApproach, Modulation, MidiOpts, MidiEmitResult, MidiJsonResult, MidiJsonEvent, MusicXmlOpts, MusicXmlEmitResult, ChantTabulaRow, Note, Performance, Phrase, Syllable, RestEvent, ParseError, ArsisThesis, VoicedPitch, Cosmos, CosmosQuery, Body, BodyName, Aspect, Imprint, Attractor, VowelAttractor, ModalAffinity, Prosody, RhythmicProfile, NoteRange, CadenceDistribution, Harmony, HarmoniaOpts, VoicedBody, VoicedAspect, Frame, Author, HarmonyTabulaRow, PlanetVowel, };
 //# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tonus",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "private": false,
   "type": "module",
   "description": "Medieval music analysis and performance: GABC plainchant exports, liturgical calendar, tuning systems, ephemeris, and the harmony of the spheres",