Home Manual Reference Source Test

src/model/theory.js

  1. /**
  2.  * Chromatic note-name array (12 entries starting from C);
  3.  * flat-preferring by default (also used as MIDI key-signature labels),
  4.  * sharp-preferring when keyIndex (kappa) is a sharp-favouring key.
  5.  * @param {number} [keyIndex] - 0-11 (kappa); omitted means flat-preferring.
  6.  * @return {string[]}
  7.  * @example
  8.  * noteNames();    // ["C", "Db", "D", "Eb", ...] flat default
  9.  * noteNames(0);   // ["C", "C#", "D", "D#", ...] C major prefers sharps
  10.  * noteNames(5);   // ["C", "Db", "D", "Eb", ...] F major prefers flats
  11.  */
  12. export function noteNames(keyIndex) {
  13.   return new Set([0, 2, 4, 7, 9, 11]).has(keyIndex)
  14.     ? "C C# D D# E F F# G G# A A# B".split(" ")
  15.     : "C Db D Eb E F Gb G Ab A Bb B".split(" ");
  16. }
  18. /**
  19.  * Per-part time-grid; subdivision (tau) is the LCM of voice durations.
  20.  * @param {{duration: string}[]} voice - Per-voice configs; only the first 'voices' entries are active.
  21.  * @param {number} voices - Active voice count (|S|).
  22.  * @param {number} numerator - Time-signature numerator (zeta).
  23.  * @param {number} bars - Bar count for this part (iota).
  24.  * @return {{subdivision: number, subBeatsPerBar: number, numSubBeats: number, activeBeats: Set<number>[]}}
  25.  *  Subdivision (tau); sub-beats per bar; T = iota * zeta * tau; per-voice onset sets (omicron).
  26.  */
  27. export function timeGrid(voice, voices, numerator, bars) {
  28.   const subdiv = {
  29.     whole: 1,
  30.     half: 1,
  31.     quarter: 1,
  32.     eighth: 2,
  33.     triplet: 3,
  34.     sixteenth: 4,
  35.   };
  36.   const gcd = (a, b) => (b === 0 ? a : gcd(b, a % b));
  37.   const subdivision = voice.reduce((acc, v) => {
  38.     const s = subdiv[v.duration] || 1;
  39.     return (acc / gcd(acc, s)) * s;
  40.   }, 1);
  41.   const subBeatsPerBar = numerator * subdivision;
  42.   const numSubBeats = bars * subBeatsPerBar;
  43.   const stride = {
  44.     whole: numerator * subdivision,
  45.     half: Math.max(1, Math.round((numerator * subdivision) / 2)),
  46.     quarter: subdivision,
  47.     eighth: Math.max(1, Math.round(subdivision / 2)),
  48.     triplet: Math.max(1, Math.round(subdivision / 3)),
  49.     sixteenth: Math.max(1, Math.round(subdivision / 4)),
  50.   };
  51.   const activeBeats = voice.slice(0, voices).map((v) => {
  52.     const s = stride[v.duration];
  53.     const count = Math.floor(((bars - 1) * subBeatsPerBar) / s) + 1;
  54.     return new Set(Array.from({ length: count }, (_, i) => i * s));
  55.   });
  56.   return { subdivision, subBeatsPerBar, numSubBeats, activeBeats };
  57. }
  59. /**
  60.  * Chord tones per mode (mu): pitch classes (mod 12) for each Roman-numeral.
  61.  * Insertion order = diatonic ordering. "NC" allows all classes.
  62.  * V and NC are duplicated across major/minor (small DRY trade-off).
  63.  * @type {{major: Object<string, number[]>, minor: Object<string, number[]>}}
  64.  */
  65. export const CHORDS = {
  66.   major: {
  67.     I: [0, 4, 7],
  68.     ii: [2, 5, 9],
  69.     iii: [4, 7, 11],
  70.     IV: [5, 9, 0],
  71.     V: [7, 11, 2],
  72.     vi: [9, 0, 4],
  73.     viio: [11, 2, 5],
  74.     NC: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11],
  75.   },
  76.   minor: {
  77.     i: [0, 3, 7],
  78.     iio: [2, 5, 8],
  79.     III: [3, 7, 10],
  80.     iv: [5, 8, 0],
  81.     V: [7, 11, 2],
  82.     bVI: [8, 0, 3],
  83.     bVII: [10, 2, 5],
  84.     NC: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11],
  85.   },
  86. };
  88. /**
  89.  * Roman-numeral display: with keyIndex returns the concrete chord name;
  90.  * without keyIndex returns the function-label form for UI dropdowns.
  91.  * @param {string} node - Roman-numeral chord symbol; "NC" and unknowns pass through.
  92.  * @param {number} [keyIndex] - 0-11 (kappa); omitted means label form.
  93.  * @return {string}
  94.  * @example
  95.  * chordName("I");       // "I: Tonic"  (label form, key-independent)
  96.  * chordName("V", 0);    // "G"         (dominant in C major)
  97.  * chordName("vi", 0);   // "Am"        (minor from lowercase numeral)
  98.  * chordName("viio", 0); // "Bo"        (diminished from "o" suffix)
  99.  * chordName("NC", 0);   // "NC"
  100.  */
  101. export function chordName(node, keyIndex) {
  102.   if (keyIndex === undefined) {
  103.     const labels = {
  104.       I: "Tonic",
  105.       ii: "Supertonic",
  106.       iii: "Mediant",
  107.       IV: "Subdominant",
  108.       V: "Dominant",
  109.       vi: "Submediant",
  110.       viio: "Leading Tone",
  111.       i: "Tonic",
  112.       iio: "Supertonic",
  113.       III: "Mediant",
  114.       iv: "Subdominant",
  115.       bVI: "Submediant",
  116.       bVII: "Subtonic",
  117.       NC: "No Chord",
  118.     };
  119.     return labels[node] ? `${node}: ${labels[node]}` : node;
  120.   }
  121.   if (node === "NC") {
  122.     return "NC";
  123.   }
  124.   const root = (CHORDS.major[node] ?? CHORDS.minor[node])?.[0];
  125.   if (root === undefined) {
  126.     return node;
  127.   }
  128.   const suffix = /o$/.test(node) ? "o" : /^b?[a-z]/.test(node) ? "m" : "";
  129.   return noteNames(keyIndex)[(root + keyIndex) % 12] + suffix;
  130. }
  132. /**
  133.  * Creates the chord digraph G = (V, E, w) for a given mode, optionally tuned by a corpus preset (pi).
  134.  * @param {'major'|'minor'} [mode='major'] - Tonal mode (mu); drives node set and default costs.
  135.  * @param {?Object<string, {edges: Object<string, number>, chromatic: string[]}>} [preset]
  136.  *  Corpus preset (pi) keyed by mode (mu);
  137.  *  per mode edges (corpus-frequency nu thresholded by epsilon) and chromatic nodes;
  138.  *  null falls back to DEFAULTS.
  139.  * @return {{
  140.  *   nodes: string[],
  141.  *   activeNodes: string[],
  142.  *   edges: [string,string][],
  143.  *   costs: Map<string,number>,
  144.  *   tonic: string,
  145.  * }}
  146.  *  nodes (V, incl. chromatic), activeNodes (subset participating in edges),
  147.  *  edges (E, valid-edge keys of costs), costs (w, edge cost map), tonic ("I" or "i").
  148.  */
  149. export function chordGraph(mode = "major", preset = null) {
  150.   const tonic = mode === "minor" ? "i" : "I";
  151.   const presetMode = preset?.[mode];
  152.   const nodes = [
  153.     ...Object.keys(CHORDS[mode]),
  154.     ...(presetMode?.chromatic ?? []),
  155.   ];
  156.   const costs = edgeCosts(nodes, mode, presetMode);
  157.   const edges = [...costs.keys()].map((k) => k.split("->"));
  158.   const activeNodes = nodes.filter((n) => new Set(edges.flat()).has(n));
  159.   return { nodes, activeNodes, edges, costs, tonic };
  160. }
  162. /**
  163.  * Default chord-graph configuration:
  164.  * structural costs (LOOP, NC, MISSING) and edge tables [cost, {major, minor}].
  165.  * CADENCE (after NORMAL) overwrites shared edges.
  166.  * MISSING is the sentinel cost for non-edges in the MZN cost matrix:
  167.  * higher than any valid cost so the solver never traverses non-edge cells.
  168.  * @type {{
  169.  *   CADENCE: [number, {major: string, minor: string}],
  170.  *   NORMAL: [number, {major: string, minor: string}],
  171.  *   NC: number,
  172.  *   LOOP: number,
  173.  *   MISSING: number,
  174.  * }}
  175.  */
  176. export const EDGES = {
  177.   CADENCE: [
  178.     1,
  179.     {
  180.       major: `V->I IV->I ii->V`,
  181.       minor: `V->i iv->i iio->V`,
  182.     },
  183.   ],
  184.   NORMAL: [
  185.     2,
  186.     {
  187.       major: `
  188.       I->ii I->iii I->IV I->V I->vi I->viio
  189.       ii->V ii->viio
  190.       iii->vi iii->IV
  191.       IV->V IV->I IV->viio
  192.       V->I V->vi
  193.       vi->ii vi->IV
  194.       viio->I viio->iii
  195.       `,
  196.       minor: `
  197.       i->iv i->V i->bVI i->bVII i->III i->iio
  198.       iv->V iv->i iv->iio iv->bVII
  199.       V->i V->bVI
  200.       iio->V
  201.       III->bVI III->bVII III->iv
  202.       bVI->bVII bVI->iv bVI->iio bVI->V
  203.       bVII->III bVII->i bVII->bVI
  204.       `,
  205.     },
  206.   ],
  207.   NC: 4,
  208.   LOOP: 8,
  209.   MISSING: 16,
  210. };
  212. /**
  213.  * @private Calculates costs with preset edges (skipping out-of-graph nodes) or
  214.  * default NORMAL+CADENCE table for the mode.
  215.  */
  216. function edgeCosts(nodes, mode, presetMode) {
  217.   const costs = new Map();
  218.   for (const v of nodes) {
  219.     costs.set(`${v}->${v}`, EDGES.LOOP);
  220.     if (v === "NC") {
  221.       continue;
  222.     }
  223.     costs.set(`${v}->NC`, EDGES.NC);
  224.     costs.set(`NC->${v}`, EDGES.NC);
  225.   }
  226.   if (presetMode) {
  227.     const nodeSet = new Set(nodes);
  228.     for (const [edge, cost] of Object.entries(presetMode.edges)) {
  229.       const [from, to] = edge.split("->");
  230.       if (!nodeSet.has(from) || !nodeSet.has(to)) {
  231.         continue;
  232.       }
  233.       costs.set(edge, from === to ? Math.max(cost, EDGES.LOOP) : cost);
  234.     }
  235.     return costs; // skip defaults if preset edges exist
  236.   }
  237.   for (const [cost, byMode] of [EDGES.NORMAL, EDGES.CADENCE]) {
  238.     for (const edge of byMode[mode].trim().split(/\s+/)) {
  239.       costs.set(edge, cost);
  240.     }
  241.   }
  242.   return costs;
  243. }