@libraz/libcantus 0.9.0

package/src/groove/index.ts

@@ -0,0 +1,230 @@
+/**
+ * Groove and humanization: nudging quantized note events toward a more human
+ * feel, and capturing/replaying the timing-and-velocity "feel" of a
+ * performance as a reusable groove template.
+ *
+ * Positions and durations are measured in quarter-note beats, matching the
+ * library-wide convention. Randomness, where used, always goes through the
+ * seeded PRNG from the `random` module so results are fully reproducible.
+ */
+
+import { beatsPerBar, metricWeight, type TimeSignature } from '../meter/index.js';
+import { createRng } from '../random/index.js';
+import type { NoteEvent } from '../types.js';
+
+/** Options controlling {@link humanize}. */
+export type HumanizeOptions = {
+  /** Time signature used to derive metric accents. Default 4/4. */
+  ts?: TimeSignature;
+  /** Maximum timing jitter in quarter-note beats, applied as ±this value. Default 0.02. */
+  timing?: number;
+  /** Maximum velocity jitter (MIDI units), applied as ±this value. Default 8. */
+  velocity?: number;
+  /** How much louder strong beats get relative to weak ones, in MIDI velocity units. Default 12. */
+  accent?: number;
+  /** Velocity assumed for events with no `velocity` of their own. Default 80. */
+  baseVelocity?: number;
+  /** Seed for the deterministic PRNG. Default 0. */
+  seed?: number;
+};
+
+/** Default time signature for {@link humanize} when none is given. */
+const DEFAULT_TS: TimeSignature = { numerator: 4, denominator: 4 };
+const DEFAULT_TIMING = 0.02;
+const DEFAULT_VELOCITY_JITTER = 8;
+const DEFAULT_ACCENT = 12;
+const DEFAULT_BASE_VELOCITY = 80;
+const MAX_METRIC_WEIGHT = 3;
+const MIN_VELOCITY = 1;
+const MAX_VELOCITY = 127;
+
+/**
+ * Humanize a sequence of note events by nudging their timing and velocity
+ * with small, deterministic (seeded) randomness plus a metric-accent shape:
+ * events on strong beats (see {@link metricWeight}) come out louder on
+ * average than events on weak ones.
+ *
+ * Each returned event is a copy; `startBeat` is jittered within
+ * `[-timing, +timing]` beats and clamped to be non-negative, and `velocity`
+ * is the event's own velocity (or `baseVelocity` if it has none) plus an
+ * accent term scaled by the event's metric weight plus a jitter within
+ * `[-velocity, +velocity]`, clamped to `[1, 127]` and rounded. The metric
+ * weight is computed from each event's original (pre-jitter) `startBeat`.
+ * `pitch` and `durationBeat` pass through unchanged, and the output keeps the
+ * input order.
+ *
+ * @param events The events to humanize.
+ * @param opts Humanization options.
+ * @returns Humanized copies of `events`, in input order.
+ */
+export function humanize(events: NoteEvent[], opts: HumanizeOptions = {}): NoteEvent[] {
+  const ts = opts.ts ?? DEFAULT_TS;
+  const timing = opts.timing ?? DEFAULT_TIMING;
+  const velocityJitter = opts.velocity ?? DEFAULT_VELOCITY_JITTER;
+  const accent = opts.accent ?? DEFAULT_ACCENT;
+  const baseVelocity = opts.baseVelocity ?? DEFAULT_BASE_VELOCITY;
+  const rng = createRng(opts.seed ?? 0);
+
+  return events.map((event) => {
+    const timingOffset = rng.float(-timing, timing);
+    const startBeat = Math.max(0, event.startBeat + timingOffset);
+
+    const weight = metricWeight(event.startBeat, ts);
+    const accentBoost = (weight / MAX_METRIC_WEIGHT) * accent;
+    const velocityOffset = rng.float(-velocityJitter, velocityJitter);
+    const rawVelocity = (event.velocity ?? baseVelocity) + accentBoost + velocityOffset;
+    const velocity = Math.min(MAX_VELOCITY, Math.max(MIN_VELOCITY, Math.round(rawVelocity)));
+
+    return {
+      pitch: event.pitch,
+      startBeat,
+      durationBeat: event.durationBeat,
+      velocity,
+    };
+  });
+}
+
+/** The recorded feel at a single grid slot: an average timing deviation and velocity. */
+export type GrooveSlot = {
+  /** Average `actualStartBeat - quantizedBeat` (in quarter-note beats) for events landing on this slot. */
+  timingOffset: number;
+  /** Average velocity of events landing on this slot; 0 if none did. */
+  velocity: number;
+};
+
+/** A per-bar grid of timing and velocity deviations captured from a performance. */
+export type GrooveTemplate = {
+  /** Grid resolution: equal grid steps per quarter-note beat. */
+  subdivision: number;
+  /** Number of grid slots per bar (`beatsPerBar(ts) * subdivision`). */
+  slotsPerBar: number;
+  /** One entry per grid slot, in slot-index order (slot 0 is the downbeat). */
+  slots: GrooveSlot[];
+};
+
+/**
+ * Quantize a beat position to the nearest grid slot at the given subdivision,
+ * within the bar that contains it.
+ *
+ * @param beat Absolute position in quarter-note beats.
+ * @param barBeats Bar length in quarter-note beats.
+ * @param subdivision Grid steps per quarter-note beat.
+ * @param slotsPerBar Number of grid slots per bar.
+ * @returns The quantized absolute beat and its 0-based slot index within the bar.
+ */
+function quantizeToGrid(
+  beat: number,
+  barBeats: number,
+  subdivision: number,
+  slotsPerBar: number,
+): { quantizedBeat: number; slotIndex: number } {
+  const barIndex = Math.floor(beat / barBeats);
+  const modBeat = beat - barIndex * barBeats;
+  let slotIndex = Math.round(modBeat * subdivision);
+  let effectiveBarIndex = barIndex;
+  // Rounding the last slot in a bar up to the grid step count means it
+  // actually lands on the next bar's downbeat.
+  if (slotIndex >= slotsPerBar) {
+    slotIndex = 0;
+    effectiveBarIndex += 1;
+  }
+  return {
+    quantizedBeat: effectiveBarIndex * barBeats + slotIndex / subdivision,
+    slotIndex,
+  };
+}
+
+/**
+ * Extract a groove template from a set of note events: for each grid slot,
+ * the average timing deviation from the quantized grid and the average
+ * velocity of events landing on it. Slots with no events default to
+ * `{ timingOffset: 0, velocity: 0 }`.
+ *
+ * @param events The (typically "groovy", human-played) events to analyze.
+ * @param ts The time signature, used to compute the bar length.
+ * @param subdivision Grid resolution: equal grid steps per quarter-note beat.
+ * @returns The extracted groove template.
+ */
+export function extractGrooveTemplate(
+  events: NoteEvent[],
+  ts: TimeSignature,
+  subdivision: number,
+): GrooveTemplate {
+  const barBeats = beatsPerBar(ts);
+  const slotsPerBar = Math.round(barBeats * subdivision);
+  const offsetSums = new Array<number>(slotsPerBar).fill(0);
+  const velocitySums = new Array<number>(slotsPerBar).fill(0);
+  const counts = new Array<number>(slotsPerBar).fill(0);
+  const velocityCounts = new Array<number>(slotsPerBar).fill(0);
+
+  for (const event of events) {
+    const { quantizedBeat, slotIndex } = quantizeToGrid(
+      event.startBeat,
+      barBeats,
+      subdivision,
+      slotsPerBar,
+    );
+    offsetSums[slotIndex] = (offsetSums[slotIndex] ?? 0) + (event.startBeat - quantizedBeat);
+    counts[slotIndex] = (counts[slotIndex] ?? 0) + 1;
+    // Only events that carry a velocity contribute to the velocity average, so a
+    // velocity-less event does not pull the slot's recorded velocity toward zero.
+    if (event.velocity !== undefined) {
+      velocitySums[slotIndex] = (velocitySums[slotIndex] ?? 0) + event.velocity;
+      velocityCounts[slotIndex] = (velocityCounts[slotIndex] ?? 0) + 1;
+    }
+  }
+
+  const slots: GrooveSlot[] = [];
+  for (let i = 0; i < slotsPerBar; i += 1) {
+    const count = counts[i] ?? 0;
+    if (count === 0) {
+      slots.push({ timingOffset: 0, velocity: 0 });
+      continue;
+    }
+    const velocityCount = velocityCounts[i] ?? 0;
+    slots.push({
+      timingOffset: (offsetSums[i] ?? 0) / count,
+      velocity: velocityCount > 0 ? (velocitySums[i] ?? 0) / velocityCount : 0,
+    });
+  }
+
+  return { subdivision, slotsPerBar, slots };
+}
+
+/**
+ * Apply a groove template to a set of (typically quantized) note events: each
+ * event is snapped to its grid slot and then offset by that slot's recorded
+ * timing deviation, pushing stiff timing toward the template's feel.
+ * Velocity is set to the slot's recorded average when it recorded any
+ * (`velocity > 0`); otherwise the event's own velocity is left untouched.
+ *
+ * @param events The events to reshape.
+ * @param template The groove template, from {@link extractGrooveTemplate}.
+ * @param ts The time signature, used to compute the bar length.
+ * @returns Reshaped copies of `events`, in input order.
+ */
+export function applyGrooveTemplate(
+  events: NoteEvent[],
+  template: GrooveTemplate,
+  ts: TimeSignature,
+): NoteEvent[] {
+  const barBeats = beatsPerBar(ts);
+  return events.map((event) => {
+    const { quantizedBeat, slotIndex } = quantizeToGrid(
+      event.startBeat,
+      barBeats,
+      template.subdivision,
+      template.slotsPerBar,
+    );
+    const slot = template.slots[slotIndex];
+    const startBeat = quantizedBeat + (slot?.timingOffset ?? 0);
+    const velocity = slot && slot.velocity > 0 ? Math.round(slot.velocity) : event.velocity;
+
+    return {
+      pitch: event.pitch,
+      startBeat,
+      durationBeat: event.durationBeat,
+      velocity,
+    };
+  });
+}

package/src/harmonize/index.ts

@@ -0,0 +1,367 @@
+import type { Chord, ChordQuality } from '../chord/index.js';
+import { chordPitchClasses, diatonicTriad, makeChord } from '../chord/index.js';
+import type { HarmonyRole } from '../harmony/index.js';
+import { roleOf } from '../harmony/index.js';
+import type { TimeSignature } from '../meter/index.js';
+import { isStrongBeat } from '../meter/index.js';
+import type { GeneratedChord } from '../progression/index.js';
+import { isScaleTone, majorKey, scaleTonesInDegreeOrder } from '../scale/index.js';
+import type { KeyScale, NoteEvent } from '../types.js';
+
+/** A melody note supplied to the harmonizer: a {@link NoteEvent}. */
+export type MelodyNote = NoteEvent;
+
+/** Options controlling {@link harmonizeMelody}. */
+export type HarmonizeOptions = {
+  melody: MelodyNote[];
+  key: KeyScale | 'infer';
+  harmonicRhythm: number;
+  reharmonize: 'diatonic' | 'secondaryDominant' | 'borrowed';
+  placement: { transposeSearch: boolean; octaveSearch: boolean };
+  seed?: number;
+};
+
+/** The chosen transpose, key, chord path, and per-note roles. */
+export type HarmonizeResult = {
+  transposeSemitones: number;
+  key: KeyScale;
+  chords: GeneratedChord[];
+  melodyRoles: { noteIndex: number; role: HarmonyRole }[];
+};
+
+type Candidate = {
+  rootPc: number;
+  quality: ChordQuality;
+  degree?: number;
+  secondaryDominant: boolean;
+  targetDegree?: number;
+  base: number;
+};
+
+type Segment = { startBeat: number; endBeat: number; noteIndices: number[] };
+
+const FALLBACK: Candidate = { rootPc: 0, quality: 'maj', secondaryDominant: false, base: 0 };
+
+/** Default meter used to weight metric accents when none is supplied. */
+const DEFAULT_METER: TimeSignature = { numerator: 4, denominator: 4 };
+
+/** Comfortable melodic range (MIDI) and the per-semitone cost of leaving it. */
+const COMFORT_LOW = 55;
+const COMFORT_HIGH = 79;
+const TESSITURA_WEIGHT = 0.001;
+
+function pitchClass(pitch: number): number {
+  return ((Math.trunc(pitch) % 12) + 12) % 12;
+}
+
+function mulberry32(seed: number): () => number {
+  let state = seed >>> 0;
+  return () => {
+    state = (state + 0x6d2b79f5) >>> 0;
+    let t = state;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+/** Estimate the best-fit major key from a melody's pitch-class weighting. */
+function inferKey(melody: MelodyNote[]): KeyScale {
+  let best = 0;
+  let bestScore = Number.NEGATIVE_INFINITY;
+  for (let tonic = 0; tonic < 12; tonic += 1) {
+    const key = majorKey(tonic);
+    let score = 0;
+    for (const n of melody) {
+      const w = Math.max(0.25, n.durationBeat);
+      if (isScaleTone(n.pitch, key)) {
+        score += w;
+      }
+      if (pitchClass(n.pitch) === tonic) {
+        score += 0.5 * w;
+      }
+    }
+    if (score > bestScore) {
+      bestScore = score;
+      best = tonic;
+    }
+  }
+  return majorKey(best);
+}
+
+/** Enumerate candidate chords for the key, gated by reharmonization strength. */
+function buildCandidates(key: KeyScale, reharmonize: HarmonizeOptions['reharmonize']): Candidate[] {
+  const tones = scaleTonesInDegreeOrder(key);
+  const candidates: Candidate[] = tones.map((rootPc, degree) => ({
+    rootPc,
+    quality: diatonicTriad(degree, key).quality,
+    degree,
+    secondaryDominant: false,
+    base: 0,
+  }));
+
+  const tonic = tones[0] ?? 0;
+  if (reharmonize !== 'diatonic') {
+    for (const target of [1, 3, 4, 5]) {
+      const targetRoot = tones[target] ?? 0;
+      candidates.push({
+        rootPc: (targetRoot + 7) % 12,
+        quality: 'dom7',
+        secondaryDominant: true,
+        targetDegree: target,
+        base: 1.5,
+      });
+    }
+  }
+
+  if (reharmonize === 'borrowed') {
+    candidates.push({
+      rootPc: (tonic + 10) % 12,
+      quality: 'maj',
+      secondaryDominant: false,
+      base: 2,
+    }); // bVII
+    candidates.push({
+      rootPc: (tonic + 8) % 12,
+      quality: 'maj',
+      secondaryDominant: false,
+      base: 2,
+    }); // bVI
+    candidates.push({
+      rootPc: (tonic + 5) % 12,
+      quality: 'min',
+      secondaryDominant: false,
+      base: 2,
+    }); // iv
+  }
+
+  return candidates;
+}
+
+/**
+ * Melody-fit cost of a candidate over a segment's notes.
+ *
+ * Each note is weighted by the portion of its duration that overlaps the
+ * segment, so a note sustained across a boundary contributes to every segment
+ * it sounds in rather than only the one it starts in.
+ */
+function emissionCost(seg: Segment, cand: Candidate, melody: MelodyNote[], key: KeyScale): number {
+  const pcs = chordPitchClasses(makeChord(cand.rootPc, cand.quality));
+  let cost = cand.base;
+  for (const idx of seg.noteIndices) {
+    const note = melody[idx];
+    if (!note) {
+      continue;
+    }
+    const overlapStart = Math.max(note.startBeat, seg.startBeat);
+    const overlap = Math.min(note.startBeat + note.durationBeat, seg.endBeat) - overlapStart;
+    if (overlap <= 0) {
+      continue;
+    }
+    const w = Math.max(0.25, overlap);
+    if (pcs.includes(pitchClass(note.pitch))) {
+      continue;
+    }
+    const strong = isStrongBeat(overlapStart, DEFAULT_METER);
+    cost += (strong ? 10 : 2) * w;
+    if (!isScaleTone(note.pitch, key)) {
+      cost += w;
+    }
+  }
+  return cost;
+}
+
+/**
+ * Register cost of a placed melody: a small penalty for notes pushed outside a
+ * comfortable range. Kept far below emission/transition costs so it only breaks
+ * ties between otherwise-equal octave placements.
+ */
+function tessituraCost(melody: MelodyNote[]): number {
+  let cost = 0;
+  for (const n of melody) {
+    if (n.pitch < COMFORT_LOW) {
+      cost += (COMFORT_LOW - n.pitch) * TESSITURA_WEIGHT;
+    } else if (n.pitch > COMFORT_HIGH) {
+      cost += (n.pitch - COMFORT_HIGH) * TESSITURA_WEIGHT;
+    }
+  }
+  return cost;
+}
+
+/** Functional-flow cost of moving from one candidate chord to the next. */
+function transitionCost(prev: Candidate, cur: Candidate, tonicPc: number): number {
+  let cost = 0;
+  if ((prev.rootPc - cur.rootPc + 12) % 12 === 7) {
+    cost -= 2; // descending-fifth root motion
+  }
+  if (
+    prev.rootPc === (tonicPc + 7) % 12 &&
+    (prev.quality === 'maj' || prev.quality === 'dom7') &&
+    cur.rootPc === tonicPc
+  ) {
+    cost -= 3; // V -> I
+  }
+  if (prev.secondaryDominant) {
+    cost += cur.degree === prev.targetDegree ? -3 : 2;
+  }
+  const dist = Math.min((prev.rootPc - cur.rootPc + 12) % 12, (cur.rootPc - prev.rootPc + 12) % 12);
+  cost += dist * 0.3;
+  return cost;
+}
+
+/** Run one Viterbi harmonization pass over a fixed melody and key. */
+function harmonizeOnce(
+  melody: MelodyNote[],
+  key: KeyScale,
+  candidates: Candidate[],
+  segments: Segment[],
+  jitter: number[],
+): { cost: number; path: number[] } {
+  const tonicPc = pitchClass(key.rootPc);
+  const n = candidates.length;
+  const candAt = (i: number): Candidate => candidates[i] ?? FALLBACK;
+  const seg0 = segments[0];
+
+  let dp = candidates.map(
+    (c, ci) => (seg0 ? emissionCost(seg0, c, melody, key) : 0) + (jitter[ci] ?? 0),
+  );
+  const back: number[][] = [];
+
+  for (let s = 1; s < segments.length; s += 1) {
+    const seg = segments[s];
+    if (!seg) {
+      continue;
+    }
+    const next: number[] = [];
+    const ptr: number[] = [];
+    for (let c = 0; c < n; c += 1) {
+      let best = Number.POSITIVE_INFINITY;
+      let bestPrev = 0;
+      for (let p = 0; p < n; p += 1) {
+        const cost =
+          (dp[p] ?? Number.POSITIVE_INFINITY) + transitionCost(candAt(p), candAt(c), tonicPc);
+        if (cost < best) {
+          best = cost;
+          bestPrev = p;
+        }
+      }
+      next[c] = best + emissionCost(seg, candAt(c), melody, key) + (jitter[c] ?? 0);
+      ptr[c] = bestPrev;
+    }
+    dp = next;
+    back.push(ptr);
+  }
+
+  let bestCost = Number.POSITIVE_INFINITY;
+  let bestEnd = 0;
+  for (let c = 0; c < n; c += 1) {
+    const cadence = candAt(c).rootPc === tonicPc ? -2 : 0;
+    const total = (dp[c] ?? Number.POSITIVE_INFINITY) + cadence;
+    if (total < bestCost) {
+      bestCost = total;
+      bestEnd = c;
+    }
+  }
+
+  const path: number[] = new Array<number>(segments.length).fill(bestEnd);
+  for (let s = segments.length - 2; s >= 0; s -= 1) {
+    const ptr = back[s];
+    const nextIdx = path[s + 1] ?? bestEnd;
+    path[s] = ptr ? (ptr[nextIdx] ?? bestEnd) : bestEnd;
+  }
+  return { cost: bestCost, path };
+}
+
+/**
+ * Harmonize a melody with a min-cost chord progression.
+ *
+ * The melody is segmented by `harmonicRhythm`; each segment is scored against
+ * diatonic (and, per `reharmonize`, secondary-dominant and borrowed) candidate
+ * chords by melody fit, and a Viterbi search picks the lowest-cost path using a
+ * functional-flow transition cost. When `placement.transposeSearch`/`octaveSearch`
+ * is set, the whole melody is transposed across a range and the best
+ * `(transpose, progression)` pair is returned; a small tessitura cost breaks
+ * ties toward placements that keep the melody in a comfortable register.
+ *
+ * @param opts Melody, key (or `'infer'`), harmonic rhythm, reharmonization
+ *   strength, height-search flags, and seed.
+ * @returns The chosen transpose, key, chord path, and per-note roles.
+ */
+export function harmonizeMelody(opts: HarmonizeOptions): HarmonizeResult {
+  const key = opts.key === 'infer' ? inferKey(opts.melody) : opts.key;
+  const candidates = buildCandidates(key, opts.reharmonize);
+  const candAt = (i: number): Candidate => candidates[i] ?? FALLBACK;
+  const rng = mulberry32(opts.seed ?? 0);
+  const jitter = candidates.map(() => rng() * 1e-6);
+
+  const melodyEnd = opts.melody.reduce((m, n) => Math.max(m, n.startBeat + n.durationBeat), 0);
+  const hr = Math.max(0.25, opts.harmonicRhythm);
+  const segCount = Math.max(1, Math.ceil(melodyEnd / hr));
+  const segments: Segment[] = [];
+  for (let s = 0; s < segCount; s += 1) {
+    const startBeat = s * hr;
+    const endBeat = startBeat + hr;
+    const noteIndices = opts.melody
+      .map((n, i) => ({ n, i }))
+      .filter(({ n }) => n.startBeat < endBeat && n.startBeat + n.durationBeat > startBeat)
+      .map(({ i }) => i);
+    segments.push({ startBeat, endBeat, noteIndices });
+  }
+
+  const transposes: number[] = [0];
+  if (opts.placement.transposeSearch) {
+    for (let s = -6; s <= 6; s += 1) {
+      if (s !== 0) {
+        transposes.push(s);
+      }
+    }
+  }
+  if (opts.placement.octaveSearch) {
+    for (const o of [-12, 12]) {
+      if (!transposes.includes(o)) {
+        transposes.push(o);
+      }
+    }
+  }
+
+  let bestCost = Number.POSITIVE_INFINITY;
+  let bestTs = 0;
+  let bestPath: number[] = [];
+  let bestMelody = opts.melody;
+  for (const ts of transposes) {
+    const shifted = opts.melody.map((n) => ({ ...n, pitch: n.pitch + ts }));
+    const { cost, path } = harmonizeOnce(shifted, key, candidates, segments, jitter);
+    const total = cost + tessituraCost(shifted);
+    if (total < bestCost) {
+      bestCost = total;
+      bestTs = ts;
+      bestPath = path;
+      bestMelody = shifted;
+    }
+  }
+
+  const chords: GeneratedChord[] = bestPath.map((ci, s) => {
+    const cand = candAt(ci);
+    const chord: GeneratedChord = {
+      rootPc: cand.rootPc,
+      quality: cand.quality,
+      startBeat: segments[s]?.startBeat ?? s * hr,
+    };
+    if (cand.degree !== undefined) {
+      chord.degree = cand.degree;
+    }
+    if (cand.secondaryDominant) {
+      chord.secondaryDominant = true;
+    }
+    return chord;
+  });
+
+  const melodyRoles = bestMelody.map((note, noteIndex) => {
+    const segIdx = Math.min(segments.length - 1, Math.max(0, Math.floor(note.startBeat / hr)));
+    const cand = candAt(bestPath[segIdx] ?? 0);
+    const chord: Chord = makeChord(cand.rootPc, cand.quality);
+    return { noteIndex, role: roleOf(note.pitch, chord).role };
+  });
+
+  return { transposeSemitones: bestTs, key, chords, melodyRoles };
+}

package/src/harmony/index.ts

@@ -0,0 +1,75 @@
+import type { Chord } from '../chord/index.js';
+
+/** Harmonic role a pitch plays within a chord. */
+export type HarmonyRole = 'root' | 'third' | 'fifth' | 'sixth' | 'seventh' | 'tension' | 'doubling';
+
+/**
+ * How firmly a pitch is locked to the chord's identity.
+ *
+ * - `identity`: moving it produces a different chord (the root).
+ * - `quality`: moving it flips the chord quality (the third).
+ * - `voicing`: it can move freely without changing chord identity or quality.
+ */
+export type LockLevel = 'identity' | 'quality' | 'voicing';
+
+/** A pitch's role, lock level, and owning chord. */
+export type VoicedRole = {
+  role: HarmonyRole;
+  lock: LockLevel;
+  belongsToChordId: number;
+};
+
+/**
+ * Classify a pitch's harmonic role and lock level within a chord.
+ *
+ * The role comes from the pitch's interval class above the chord root: root (0),
+ * third (3/4), fifth (6/7/8), seventh (10/11), and 9/11/13 tensions (2/5/9, and
+ * the flat ninth 1). The root locks the chord identity, the third locks its
+ * quality, and everything else is free voicing. In a suspended chord (a chord
+ * whose intervals include a 4th (5) or 2nd (2) but no third), the suspended tone
+ * takes the third's place as the quality-defining tone and is locked to
+ * `quality`, since moving it changes the chord. Detecting an octave doubling
+ * requires the surrounding voicing, which this single-pitch query does not carry,
+ * so `doubling` is part of the type but not returned here.
+ *
+ * @param pitch MIDI pitch or bare pitch class.
+ * @param chord The chord providing the root reference.
+ * @param chordId Identifier stored on the result (defaults to 0).
+ * @returns The pitch's role, lock level, and owning chord id.
+ */
+export function roleOf(pitch: number, chord: Chord, chordId = 0): VoicedRole {
+  const interval = (((Math.trunc(pitch) - chord.rootPc) % 12) + 12) % 12;
+  const tones = new Set(chord.intervals.map((i) => ((i % 12) + 12) % 12));
+  const hasHigherSeventh = tones.has(10) || tones.has(11);
+  const hasThird = tones.has(3) || tones.has(4);
+  const isSuspendedTone =
+    !hasThird && ((interval === 5 && tones.has(5)) || (interval === 2 && tones.has(2)));
+  let role: HarmonyRole;
+  let lock: LockLevel;
+  if (interval === 0) {
+    role = 'root';
+    lock = 'identity';
+  } else if (isSuspendedTone) {
+    role = 'third'; // suspended tone occupies the third's quality-defining slot
+    lock = 'quality';
+  } else if (interval === 3 || interval === 4) {
+    role = 'third';
+    lock = 'quality';
+  } else if (interval === 6 || interval === 7 || interval === 8) {
+    role = 'fifth';
+    lock = 'voicing';
+  } else if (interval === 9 && tones.has(3) && tones.has(6) && !hasHigherSeventh) {
+    role = 'seventh'; // diminished seventh
+    lock = 'voicing';
+  } else if (interval === 9 && tones.has(9) && !hasHigherSeventh) {
+    role = 'sixth';
+    lock = 'voicing';
+  } else if (interval === 10 || interval === 11) {
+    role = 'seventh';
+    lock = 'voicing';
+  } else {
+    role = 'tension';
+    lock = 'voicing';
+  }
+  return { role, lock, belongsToChordId: chordId };
+}