@k-l-lambda/lilylet 0.1.88 → 0.1.89

package/source/lilylet/abcDecoder.ts

@@ -42,6 +42,7 @@ import {
 } from "./types";
 import { parseStaffLayout, StaffGroup, StaffGroupType } from "./staffLayout";
 import { MeasureRepeatInfo, buildMeasureLayout, applyNavText } from "./measureLayoutFromXml";
+import { parseClefSuffix, withClefTransposition } from "./clefTransposition";
 
 
 // ============ Constants ============
@@ -476,25 +477,32 @@ const convertClef = (clefStr: string): Clef | undefined => {
 
 /**
  * Fold an ABC voice `transpose=N` property (a written→sounding shift in
- * SEMITONES) into the Lilylet clef-suffix form `_M` / `^M`, where M is a
- * diatonic interval number. ABC carries only semitones, so the diatonic
- * interval is approximated by the nearest scale-step count
- * (steps = round(semi * 7/12), interval number = |steps| + 1); `_` lowers,
- * `^` raises. The Lilylet→MEI encoder later expands the suffix back into
- * trans.diat / trans.semi (see meiEncoder.resolveClef). This is exact when the
- * semitone count is a major/perfect interval (e.g. -2, -9, +2, ±12) and a
- * nearest-interval approximation otherwise.
+ * SEMITONES) into the Lilylet clef suffix, which the →MEI encoder later expands
+ * into trans.diat / trans.semi (see meiEncoder.resolveClef).
+ *
+ * The conversion is EXACT: clefTransposition.semitonesToClefSuffix returns the
+ * suffix for the interval that spans exactly this many semitones, using the `m`
+ * (minor) form where the major/perfect interval does not fit — so -3 becomes
+ * `_m3` rather than the nearest major third `_3`. It previously approximated with
+ * round(semi * 7/12), which put a one-semitone error on the sounding pitch of
+ * every minor-interval transposition (-3 A clarinet, -8, -10 E-flat instruments:
+ * 37% of transposing voices in the corpora checked).
+ *
+ * A semitone count with no exact suffix (only the tritone, ±6, within an octave)
+ * is dropped with a warning rather than rounded: a silent one-semitone pitch error
+ * is worse than a visibly absent transposition.
  */
 const transposeClefSuffix = (clef: Clef | undefined, semitones: number): Clef | undefined => {
 	if (!clef || !semitones) return clef;
-	// A clef that already carries an octave suffix (treble_8 etc.) is left as-is;
-	// stacking another shift on top is not meaningful for ABC sources.
-	if (/[_^]\d+$/.test(clef as string)) return clef;
-	const steps = Math.round((semitones * 7) / 12);
-	if (steps === 0) return clef;
-	const num = Math.abs(steps) + 1;
-	const suffix = (steps < 0 ? "_" : "^") + num;
-	return (clef + suffix) as Clef;
+	// A clef that already carries a transposition suffix (treble_8 etc.) is left
+	// as-is; stacking another shift on top is not meaningful for ABC sources.
+	if (parseClefSuffix(clef as string)) return clef;
+	const transposed = withClefTransposition(clef as string, semitones);
+	if (transposed === undefined) {
+		console.warn(`abcDecoder: transpose=${semitones} has no exact clef suffix; transposition dropped for clef "${clef}"`);
+		return clef;
+	}
+	return transposed as Clef;
 };
 
 /**
@@ -1599,6 +1607,15 @@ const decodeTune = (tune: ABC.Tune, options: DecodeOptions = {}): LilyletDoc =>
 	// the pickup/anacrusis handling below the per-measure assembly).
 	let curTime: TimeSig | undefined = timeSig;
 
+	// ABC voice numbers whose declared clef has already been emitted. A voice gets its
+	// clef on the measure where it FIRST carries music, which is not always measure 0:
+	// a header field the grammar does not consume (e.g. `I:percmap`) degenerates into a
+	// phantom measure 0 holding a single patch with no voice number, and the emission
+	// was previously gated on `mi === 0`, so every real voice lost its clef — and with
+	// it its transposition. Keying on the voice number instead of the measure index
+	// makes the emission independent of what measure 0 happens to contain.
+	const emittedClefVoices = new Set<number>();
+
 	for (let mi = 0; mi < measures.length; mi++) {
 		const abcMeasure = measures[mi];
 
@@ -1745,31 +1762,39 @@ const decodeTune = (tune: ABC.Tune, options: DecodeOptions = {}): LilyletDoc =>
 		for (const pi of sortedPartIndices) {
 			const voicesMap = partVoicesMap.get(pi)!;
 			const voices: Voice[] = [];
+			// Voice -> the ABC voice number it came from, recovered from the map key
+			// (voiceKey = staffInPart * 1000 + voiceNum). Voice itself carries no voice
+			// number, and the clef below is a per-voice property, so the association has
+			// to be kept explicitly rather than searched for.
+			const voiceNumOf = new Map<Voice, number>();
 			const sortedKeys = Array.from(voicesMap.keys()).sort((a, b) => a - b);
 			for (const key of sortedKeys) {
-				voices.push(voicesMap.get(key)!);
+				const voice = voicesMap.get(key)!;
+				voices.push(voice);
+				voiceNumOf.set(voice, key % 1000);
 			}
 
 			const part: Part = { voices };
 
-			// Add clef context to first voice of each staff on first measure
-			if (mi === 0) {
-				for (const voice of voices) {
-					// Find voices for this part's staff and add initial clef
-					const voiceNums = Array.from(voicePatches.keys());
-					for (const vn of voiceNums) {
-						if (scoreLayout) {
-							const assign = scoreLayout.get(vn);
-							if (assign && assign.partIndex === pi && assign.staffInPart === voice.staff) {
-								const clef = voiceClefs.get(vn);
-								if (clef) {
-									voice.events.unshift({ type: "context", clef } as ContextChange);
-									break;
-								}
-							}
-						}
-					}
-				}
+			// Give each voice its OWN declared clef on the measure where it first
+			// appears. A clef must be per voice, not per staff: an ABC voice folds its
+			// `transpose=` into the clef suffix, so two voices sharing a staff can
+			// legitimately differ, and lilylet's model is per-voice throughout
+			// (onsets.measureOnsets tracks clefByVoice, serializer.findVoiceClef reads
+			// one clef per Voice).
+			//
+			// This used to scan for the FIRST voice whose scoreLayout assignment matched
+			// (partIndex, staff) and break, so every voice on a shared staff inherited
+			// the first one's clef — the WRONG clef, taking its transposition with it.
+			// A `%%score` arc such as `( 1 2 )` puts both voices on one staff and is
+			// exactly that shape.
+			for (const voice of voices) {
+				const vn = voiceNumOf.get(voice)!;
+				if (emittedClefVoices.has(vn)) continue;
+				const clef = voiceClefs.get(vn);
+				if (!clef) continue;
+				voice.events.unshift({ type: "context", clef } as ContextChange);
+				emittedClefVoices.add(vn);
 			}
 
 			parts.push(part);

package/source/lilylet/clefTransposition.ts

@@ -0,0 +1,149 @@
+/**
+ * The canonical grammar for Lilylet's transposing-clef suffix, and the only place
+ * that converts between a suffix and a semitone count.
+ *
+ * A Lilylet clef may carry a written→sounding transposition as a suffix:
+ *
+ *   treble_8    an octave down          (-12)
+ *   treble^2    a major second up       (+2)
+ *   treble_5    a perfect fifth down    (-7)
+ *   treble_m3   a MINOR third down      (-3)
+ *   treble_m7   a minor seventh down    (-10)
+ *
+ * `_` lowers, `^` raises, the number is a diatonic interval, and an `m` before the
+ * number selects the MINOR form of that interval. Without `m` the interval is the
+ * major/perfect one, which is what every suffix written before the `m` form existed
+ * means — so plain `_N`/`^N` keeps its original value and old documents are read
+ * exactly as before.
+ *
+ * Why `m` exists: the diatonic interval number alone cannot express a minor
+ * interval, so the semitone counts 1, 3, 8 and 10 were unreachable. Those are not
+ * exotic — a minor third is the A clarinet and a minor seventh is a common brass
+ * transposition, so an ABC `transpose=-3` had no exact suffix and was rounded to
+ * `_3` (-4), putting a one-semitone error on the sounding pitch. With `m` the only
+ * remaining gap is 6 semitones, the tritone, which is neither major/perfect nor
+ * minor (it is an augmented fourth or diminished fifth). No instrument transposes
+ * by a tritone and the shape does not occur in any corpus checked, so it is left
+ * unrepresentable rather than given a spelling that would have to be arbitrary.
+ *
+ * NOTE ON LILYPOND: LilyPond's own `\clef "treble_8"` suffix is a NOTATIONAL
+ * device — it repositions middle C on the staff and does not change sounding pitch
+ * at all (LilyPond expresses instrument transposition with the separate
+ * `\transposition <pitch>`, which takes a pitch and so reaches every semitone).
+ * Lilylet deliberately diverges: here the suffix DOES carry the sounding shift, and
+ * `m` is the extension that makes that carrying lossless. LilyPond rejects `_m3` as
+ * an unknown clef type, so a Lilylet clef using `m` is not portable to LilyPond
+ * as-is.
+ */
+
+// Semitones spanned by the MAJOR/PERFECT form of each diatonic step count
+// (0 = unison, 1 = second, … 6 = seventh).
+const DIATONIC_SEMITONES = [0, 2, 4, 5, 7, 9, 11];
+
+// Diatonic step counts that have a minor form: seconds, thirds, sixths, sevenths.
+// Unison, fourth and fifth are perfect and take no `m`.
+const MINOR_CAPABLE_STEPS = new Set([1, 2, 5, 6]);
+
+/** A parsed transposing-clef suffix. */
+export interface ClefSuffix {
+	/** The clef name with the suffix removed, e.g. "treble". */
+	base: string;
+	/** Diatonic interval number as written: 8 for an octave, 3 for a third. */
+	interval: number;
+	/** True when the suffix selected the minor form (`m` present). */
+	minor: boolean;
+	/** true = `^` (up), false = `_` (down). */
+	up: boolean;
+}
+
+// `_`/`^`, an optional `m`, then a positive interval number with no leading zero.
+const SUFFIX_RE = /^(.*?)([_^])(m?)([1-9][0-9]*)$/;
+
+/** Semitones spanned by a diatonic interval number, or undefined if `m` is invalid for it. */
+const intervalSemitones = (interval: number, minor: boolean): number | undefined => {
+	const steps = interval - 1;						// diatonic steps above unison
+	const within = steps % 7;
+	if (minor && !MINOR_CAPABLE_STEPS.has(within)) return undefined;
+	const semis = DIATONIC_SEMITONES[within] + 12 * Math.floor(steps / 7);
+	return minor ? semis - 1 : semis;
+};
+
+/**
+ * Parse a clef string into its base name and transposition suffix.
+ * Returns undefined when the clef carries no suffix, or when the suffix is
+ * malformed (including `m` on a perfect interval such as `_m4`).
+ */
+export const parseClefSuffix = (clefStr: string): ClefSuffix | undefined => {
+	const match = SUFFIX_RE.exec(clefStr || "");
+	if (!match) return undefined;
+	const interval = parseInt(match[4], 10);
+	const minor = match[3] === "m";
+	// Reject a suffix we cannot interpret rather than silently mis-reading it.
+	if (intervalSemitones(interval, minor) === undefined) return undefined;
+	return { base: match[1], interval, minor, up: match[2] === "^" };
+};
+
+/** The clef name with any transposition suffix stripped. */
+export const clefBaseName = (clefStr: string): string =>
+	parseClefSuffix(clefStr)?.base ?? clefStr;
+
+/**
+ * The written→sounding semitone shift a clef string declares; 0 when it declares
+ * none (no suffix, or a suffix that cannot be interpreted).
+ */
+export const clefSuffixSemitones = (clefStr: string): number => {
+	const parsed = parseClefSuffix(clefStr);
+	if (!parsed) return 0;
+	const semis = intervalSemitones(parsed.interval, parsed.minor)!;
+	return parsed.up ? semis : -semis;
+};
+
+/**
+ * The written→sounding transposition as MEI's att.transposition pair, in the
+ * `{diat, semi}` form: diatonic steps and semitones, both signed. A minor third
+ * down is `{diat: -2, semi: -3}` — the two differ, which is exactly the
+ * information the diatonic number alone cannot carry.
+ */
+export const clefSuffixTransposition = (clefStr: string): { diat: number; semi: number } | undefined => {
+	const parsed = parseClefSuffix(clefStr);
+	if (!parsed) return undefined;
+	const semis = intervalSemitones(parsed.interval, parsed.minor)!;
+	const sign = parsed.up ? 1 : -1;
+	return { diat: sign * (parsed.interval - 1), semi: sign * semis };
+};
+
+/**
+ * The suffix that expresses `semitones` EXACTLY, or undefined when no suffix can.
+ * Never approximates: a caller that gets undefined must handle the gap rather than
+ * emit a shift it cannot honour. The only unrepresentable interval within an octave
+ * is 6 semitones (the tritone) — see the module comment.
+ *
+ * Returns the suffix alone (e.g. "_m3"), to be appended to a clef base name.
+ */
+export const semitonesToClefSuffix = (semitones: number): string | undefined => {
+	if (!Number.isInteger(semitones) || semitones === 0) return undefined;
+	const magnitude = Math.abs(semitones);
+	const sign = semitones < 0 ? "_" : "^";
+	// Search interval numbers covering the requested magnitude; octaves shift by 7
+	// diatonic steps, so an octave-and-a-bit needs interval numbers beyond 8.
+	const maxInterval = Math.floor(magnitude / 12) * 7 + 8;
+	for (let interval = 1; interval <= maxInterval; interval++) {
+		for (const minor of [false, true]) {
+			if (intervalSemitones(interval, minor) === magnitude)
+				return `${sign}${minor ? "m" : ""}${interval}`;
+		}
+	}
+	return undefined;
+};
+
+/**
+ * Apply a semitone transposition to a clef name, returning the suffixed clef.
+ * Returns undefined when the shift has no exact suffix, so the caller can decide
+ * between dropping the transposition and reporting it — silently rounding is what
+ * produced wrong sounding pitches before this module existed.
+ */
+export const withClefTransposition = (base: string, semitones: number): string | undefined => {
+	if (semitones === 0) return base;
+	const suffix = semitonesToClefSuffix(semitones);
+	return suffix === undefined ? undefined : base + suffix;
+};

package/source/lilylet/index.ts

@@ -5,6 +5,7 @@ export * from "./serializer";
 export * from "./staffLayout";
 export * from "./measureLayout";
 export * from "./onsets";
+export * from "./clefTransposition";
 export * from "./transposition";
 
 import * as meiEncoder from "./meiEncoder";

package/source/lilylet/meiEncoder.ts

@@ -32,6 +32,7 @@ import {
 import { parseStaffLayout, StaffGroup, StaffGroupType } from "./staffLayout";
 import { gmProgramOf } from "./gmInstruments";
 import { parseMeasureLayout, expandMeasureLayout, decomposeToSegments } from "./measureLayout";
+import { clefBaseName, clefSuffixTransposition } from "./clefTransposition";
 
 
 // MEI key signatures: positive = sharps, negative = flats
@@ -88,7 +89,7 @@ const CLEF_SHAPES: Record<string, { shape: string; line: number }> = {
 
 // Semitone offsets of the major/perfect intervals within one diatonic octave,
 // indexed by diatonic step (0 = unison, 1 = 2nd, … 6 = 7th).
-const DIATONIC_SEMITONES = [0, 2, 4, 5, 7, 9, 11];
+
 
 // Convert a LilyPond clef interval-number suffix into an MEI written→sounding
 // transposition. The number N is a diatonic interval number (2 = 2nd, 3 = 3rd,
@@ -96,29 +97,23 @@ const DIATONIC_SEMITONES = [0, 2, 4, 5, 7, 9, 11];
 // raises it. Returns { diat, semi } where diat is the diatonic step shift
 // (N - 1, signed) and semi is the corresponding chromatic shift in semitones,
 // extended octave-wise for compound intervals.
-const clefTransposition = (intervalNumber: number, up: boolean): { diat: number; semi: number } => {
-	const k = intervalNumber - 1;					// diatonic steps
-	const semis = DIATONIC_SEMITONES[k % 7] + 12 * Math.floor(k / 7);
-	const sign = up ? 1 : -1;
-	return { diat: sign * k, semi: sign * semis };
-};
+
 
 // Resolve a clef string into MEI shape/line plus optional written→sounding
-// transposition. Per the LilyPond convention a "_N"/"^N" suffix transposes the
-// clef down/up by the diatonic interval N (e.g. "treble_8" octave down,
-// "treble_5" fifth down, "treble^3" third up). MEI's clef.dis only covers octave
-// displacement (8|15|22), so all clef transposition — octaves included — is
-// encoded uniformly via att.transposition (trans.diat / trans.semi) on staffDef.
+// transposition. A "_N"/"^N" suffix transposes the clef down/up by the diatonic
+// interval N ("treble_8" octave down, "treble_5" fifth down), and "_mN"/"^mN"
+// selects that interval's minor form ("treble_m3" = minor third down) — see
+// clefTransposition.ts. MEI's clef.dis only covers octave displacement
+// (8|15|22), so all clef transposition — octaves included — is encoded uniformly
+// via att.transposition (trans.diat / trans.semi) on staffDef. A minor interval is
+// exactly why both fields are needed: a minor third is {diat:-2, semi:-3}.
 const resolveClef = (clefStr: string): { shape: string; line: number; trans?: { diat: number; semi: number } } => {
-	const match = clefStr.match(/^(.*?)([_^])(\d+)$/);
-	const base = match ? match[1] : clefStr;
-	const clefInfo = CLEF_SHAPES[base] || CLEF_SHAPES.treble;
-	if (!match) return { shape: clefInfo.shape, line: clefInfo.line };
-	const trans = clefTransposition(Number(match[3]), match[2] === "^");
+	const clefInfo = CLEF_SHAPES[clefBaseName(clefStr)] || CLEF_SHAPES.treble;
+	const trans = clefSuffixTransposition(clefStr);
 	return {
 		shape: clefInfo.shape,
 		line: clefInfo.line,
-		trans,
+		...(trans ? { trans } : {}),
 	};
 };
 

package/source/lilylet/onsets.ts

@@ -11,6 +11,7 @@
 
 import { calculateDuration } from "./musicXmlUtils";
 import { Accidental } from "./types";
+import { clefSuffixSemitones } from "./clefTransposition";
 
 // Onset resolution in ticks per quarter note. calculateDuration() rounds its result to an
 // integer, so it must run at a resolution fine enough to represent every note value exactly:
@@ -25,22 +26,14 @@ const ACCIDENTAL_SEMITONE: Record<string, number> = {
 	[Accidental.doubleSharp]: 2, [Accidental.doubleFlat]: -2,
 };
 
-// Diatonic-step -> semitones within an octave (unison..seventh), for "_N"/"^N" clef suffixes.
-const DIATONIC_SEMITONES = [0, 2, 4, 5, 7, 9, 11];
-
 /**
- * The written->sounding semitone shift a clef string declares. Per the LilyPond convention a
- * "_N"/"^N" suffix transposes DOWN/UP by the diatonic interval N: "treble_8" = octave down
- * (-12), "treble^8" = +12, "treble_15" = two octaves down (-24), "treble_5" = fifth down (-7).
- * A plain clef (no suffix) declares 0.
+ * The written->sounding semitone shift a clef string declares. A "_N"/"^N" suffix transposes
+ * DOWN/UP by the diatonic interval N ("treble_8" = octave down, -12; "treble_5" = fifth down,
+ * -7), and an "m" before the number selects that interval's MINOR form ("treble_m3" = minor
+ * third down, -3). A plain clef declares 0. See clefTransposition.ts for the grammar; this is
+ * a thin alias kept because clefShift is the name the onset API and its tests already use.
  */
-export const clefShift = (clefStr: string): number => {
-	const m = /^.*?([_^])(\d+)$/.exec(clefStr || "");
-	if (!m) return 0;
-	const k = parseInt(m[2], 10) - 1;					// diatonic steps above unison
-	const semis = DIATONIC_SEMITONES[k % 7] + 12 * Math.floor(k / 7);
-	return (m[1] === "^" ? 1 : -1) * semis;
-};
+export const clefShift = (clefStr: string): number => clefSuffixSemitones(clefStr);
 
 /**
  * Sounding MIDI pitch of a resolved (absolute-octave) Lilylet pitch. Octave 0 = middle-C