@k-l-lambda/lilylet 0.1.88 → 0.1.90

package/source/lilylet/musicXmlDecoder.ts

@@ -8,6 +8,7 @@
 import { DOMParser } from '@xmldom/xmldom';
 
 import {
+	Clef,
 	LilyletDoc,
 	Measure,
 	Part,
@@ -49,6 +50,8 @@ import {
 	MusicXmlLyric,
 } from './musicXmlTypes';
 
+import { withClefTransposition } from './clefTransposition';
+
 import {
 	getElementText,
 	getElementInt,
@@ -647,6 +650,21 @@ const parseAttributes = (attrEl: Element): MusicXmlAttributes => {
 		}
 	}
 
+	// Instrument transposition. This is what carries a transposing part's sounding
+	// pitch in MusicXML (<clef-octave-change> is only the glyph), and it was never
+	// read, so every transposing instrument decoded as sounding-as-written.
+	const transposeEl = getElements(attrEl, 'transpose')[0];
+	if (transposeEl) {
+		const chromatic = getElementInt(transposeEl, 'chromatic');
+		if (chromatic != null) {
+			result.transpose = {
+				diatonic: getElementInt(transposeEl, 'diatonic') ?? undefined,
+				chromatic,
+				octaveChange: getElementInt(transposeEl, 'octave-change') ?? undefined,
+			};
+		}
+	}
+
 	// Staves
 	const staves = getElementInt(attrEl, 'staves');
 	if (staves !== undefined) {
@@ -1260,6 +1278,38 @@ const forwardGapToRests = (gapTicks: number, divisions: number): RestEvent[] =>
 	return rests;
 };
 
+/**
+ * Fold a MusicXML transposition onto a lilylet clef as a suffix.
+ *
+ * MusicXML keeps the two apart: <transpose> is the sounding shift and moves pitch,
+ * <clef-octave-change> is the "8" glyph under the clef and moves nothing. A lilylet
+ * suffix means sounding shift, so only ONE of them may be folded in — adding both
+ * would double an octave clef that also declares <transpose> (the shape this
+ * encoder itself now emits) into two octaves.
+ *
+ * <transpose> wins when present, being the explicit statement of sounding pitch.
+ * Absent it, an octave clef is read as implying its own shift, which is what a
+ * tenor-voice or guitar treble_8 part means.
+ *
+ * A shift with no exact suffix (only the tritone) leaves the clef plain rather than
+ * rounding: a silently wrong sounding pitch is worse than a visibly absent shift.
+ */
+const clefWithShift = (
+	clef: Clef | undefined,
+	transposeSemitones: number,
+	clefOctaveChange?: number,
+): Clef | undefined => {
+	if (!clef) return clef;
+	const semitones = transposeSemitones !== 0 ? transposeSemitones : 12 * (clefOctaveChange ?? 0);
+	if (semitones === 0) return clef;
+	const shifted = withClefTransposition(clef as string, semitones);
+	if (shifted === undefined) {
+		console.warn(`musicXmlDecoder: transposition ${semitones} has no exact clef suffix; dropped for clef "${clef}"`);
+		return clef;
+	}
+	return shifted as Clef;
+};
+
 /**
  * Total time a TupletEvent advances the voice, in voiceTracker duration units.
  * Sum the inner note/rest values then apply the tuplet ratio (triplet etc.).
@@ -1281,7 +1331,10 @@ const convertMeasure = (
 	voiceTracker: VoiceTracker,
 	spannerTracker: SpannerTracker,
 	ottavaTracker: { current: number },
-	tupletTracker: TupletTracker
+	tupletTracker: TupletTracker,
+	// A part's <transpose> is declared once, usually in measure 1, and stays in force
+	// for the whole part, so it has to survive across measures like the ottava does.
+	transposeTracker: { semitones: number }
 ): MeasureConversionResult => {
 	let key: KeySignature | undefined;
 	let timeSig: Fraction | undefined;
@@ -1369,10 +1422,20 @@ const convertMeasure = (
 				timeSig = createFraction(attrs.time.beats, attrs.time.beatType);
 			}
 
+			// Instrument transposition, in force from here to the end of the part.
+			if (attrs.transpose) {
+				const { chromatic, octaveChange } = attrs.transpose;
+				transposeTracker.semitones = chromatic + 12 * (octaveChange ?? 0);
+			}
+
 			// Clefs - store by staff number
 			if (attrs.clefs) {
 				for (const clefEntry of attrs.clefs) {
-					const clef = convertClef(clefEntry.clef.sign, clefEntry.clef.line);
+					const clef = clefWithShift(
+						convertClef(clefEntry.clef.sign, clefEntry.clef.line),
+						transposeTracker.semitones,
+						clefEntry.clef.clefOctaveChange,
+					);
 					if (clef) {
 						const staff = clefEntry.staff;
 						if (staffHasNotes.has(staff)) {
@@ -1761,6 +1824,7 @@ const convertPart = (partEl: Element): { measures: Measure[]; name?: string } =>
 	const voiceTracker = new VoiceTracker();
 	const spannerTracker = new SpannerTracker();
 	const ottavaTracker = { current: 0 };
+	const transposeTracker = { semitones: 0 };
 	const tupletTracker = new TupletTracker();
 
 	let lastKey: KeySignature | undefined;
@@ -1779,7 +1843,7 @@ const convertPart = (partEl: Element): { measures: Measure[]; name?: string } =>
 
 	for (const measureEl of measureEls) {
 		voiceTracker.reset();
-		const { voiceMap, key, timeSig, barline, leadingBarline, harmonies, clefs } = convertMeasure(measureEl, voiceTracker, spannerTracker, ottavaTracker, tupletTracker);
+		const { voiceMap, key, timeSig, barline, leadingBarline, harmonies, clefs } = convertMeasure(measureEl, voiceTracker, spannerTracker, ottavaTracker, tupletTracker, transposeTracker);
 
 		// A forward-repeat (or any `location="left"`) barline belongs at the END of
 		// the PREVIOUS measure in lilylet's "\bar = current measure's end bar" model.

package/source/lilylet/musicXmlEncoder.ts

@@ -48,6 +48,8 @@ import {
 
 import { parseStaffLayout, StaffGroup, StaffGroupType } from "./staffLayout";
 
+import { clefBaseName, clefSuffixSemitones, clefSuffixTransposition } from "./clefTransposition";
+
 
 // === Constants and Reverse Mappings ===
 
@@ -304,13 +306,45 @@ const encodeAttributes = (
 	}
 
 	if (options.clef) {
-		const clefInfo = CLEF_TO_SIGN[options.clef];
+		// Look the sign/line up under the BASE name. A lilylet clef may carry a
+		// transposition suffix ("treble_8", "treble_m3"), and keying the table on the
+		// whole string missed every one of them — `clefInfo` came back undefined and
+		// the <clef> element was dropped entirely, sign and line with it.
+		const clefStr = options.clef as string;
+		const clefInfo = CLEF_TO_SIGN[clefBaseName(clefStr)];
 		if (clefInfo) {
 			xml += `${indent(level + 1)}<clef>\n`;
 			xml += `${indent(level + 2)}<sign>${clefInfo.sign}</sign>\n`;
 			xml += `${indent(level + 2)}<line>${clefInfo.line}</line>\n`;
+			// A whole-octave shift also has a notational form: the "8" drawn under or
+			// over the clef. This is the glyph only — sounding pitch rides on
+			// <transpose> below, exactly as in LilyPond.
+			const semitones = clefSuffixSemitones(clefStr);
+			if (semitones % 12 === 0 && semitones !== 0)
+				xml += `${indent(level + 2)}<clef-octave-change>${semitones / 12}</clef-octave-change>\n`;
 			xml += `${indent(level + 1)}</clef>\n`;
 		}
+
+		// The written->sounding transposition. MusicXML carries the diatonic step count
+		// and the chromatic semitone count separately, which is what lets a minor third
+		// (-2 steps, -3 semitones) be expressed exactly. <transpose> follows <clef> in
+		// the attributes content order.
+		const trans = clefSuffixTransposition(clefStr);
+		if (trans) {
+			// <diatonic> and <chromatic> hold the WITHIN-OCTAVE remainder and whole
+			// octaves go in <octave-change>, so both must be reduced by the same octave
+			// count: 7 diatonic steps and 12 semitones each. Reducing only the semitones
+			// would make an octave clef read as two octaves.
+			const octaveChange = Math.trunc(trans.semi / 12);
+			const diatonic = trans.diat - 7 * octaveChange;
+			const chromatic = trans.semi - 12 * octaveChange;
+			xml += `${indent(level + 1)}<transpose>\n`;
+			xml += `${indent(level + 2)}<diatonic>${diatonic}</diatonic>\n`;
+			xml += `${indent(level + 2)}<chromatic>${chromatic}</chromatic>\n`;
+			if (octaveChange !== 0)
+				xml += `${indent(level + 2)}<octave-change>${octaveChange}</octave-change>\n`;
+			xml += `${indent(level + 1)}</transpose>\n`;
+		}
 	}
 
 	xml += `${indent(level)}</attributes>\n`;

package/source/lilylet/musicXmlTypes.ts

@@ -41,12 +41,22 @@ export interface MusicXmlClef {
 	clefOctaveChange?: number; // -1, 0, 1
 }
 
+// A part's written->sounding transposition. diatonic/chromatic hold the
+// within-octave remainder and octaveChange the whole octaves, so the total shift is
+// chromatic + 12 * octaveChange semitones.
+export interface MusicXmlTranspose {
+	diatonic?: number;
+	chromatic: number;
+	octaveChange?: number;
+}
+
 export interface MusicXmlAttributes {
 	divisions?: number;     // Divisions per quarter note
 	key?: MusicXmlKey;
 	time?: MusicXmlTime;
 	clefs?: { staff: number; clef: MusicXmlClef }[];  // Clefs by staff number
 	staves?: number;        // Number of staves
+	transpose?: MusicXmlTranspose;  // Instrument transposition, folded into the clef suffix
 }
 
 // ============ Note Types ============

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