@k-l-lambda/lilylet 0.1.70 → 0.1.71

package/source/lilylet/meiEncoder.ts

@@ -28,6 +28,7 @@ import {
 	InstrumentName,
 } from "./types";
 import { parseStaffLayout, StaffGroup, StaffGroupType } from "./staffLayout";
+import { gmProgramOf } from "./gmInstruments";
 
 
 // MEI key signatures: positive = sharps, negative = flats
@@ -120,13 +121,24 @@ const resolveClef = (clefStr: string): { shape: string; line: number; trans?: {
 
 // Attributes for a standalone <clef> element (mid-measure clef change).
 // A mid-measure <clef> cannot carry att.transposition (that is a staff-level
-// property on <staffDef>); a mid-piece change of transposition would require a
-// new <staffDef>, which is out of scope here. So only shape/line are emitted.
+// property Verovio only reads from <staffDef>); the visible clef shape/line is
+// emitted here, and a sounding-pitch transposition change is mirrored by a
+// between-measure <scoreDef>/<staffDef trans.*> emitted in the measure loop
+// (see emitClefTranspositionScoreDef). So only shape/line are emitted here.
 const clefElementAttrs = (clefStr: string): string => {
 	const c = resolveClef(clefStr);
 	return `shape="${c.shape}" line="${c.line}"`;
 };
 
+// The written→sounding transposition a clef declares, as {diat, semi}; {0,0}
+// when the clef declares none. Used to detect mid-piece transposition changes
+// and to emit the resetting <staffDef> when a transposing clef is replaced by a
+// plain one (Verovio retains a prior trans.* until an explicit 0/0 overrides it).
+const clefTransOf = (clefStr: string): { diat: number; semi: number } => {
+	const c = resolveClef(clefStr);
+	return c.trans || { diat: 0, semi: 0 };
+};
+
 // Attributes for a <staffDef> clef (clef.* namespace), plus att.transposition
 // (trans.diat / trans.semi) when the clef declares a transposition.
 const staffDefClefAttrs = (clefStr: string): string => {
@@ -1728,6 +1740,36 @@ const generateTempoElement = (tempo: Tempo, indent: string, staff: number = 1):
 // Clef state for cross-measure clef tracking - maps staff number to current clef
 type ClefState = Record<number, Clef>;
 
+// The clef governing a measure's sounding pitch on one global staff: the clef
+// carried in from the previous measure, overridden by a leading clef change that
+// appears before the first note/rest in the measure (the normal boundary-change
+// case). A clef change occurring *after* notes does not retune this measure — it
+// becomes the carried clef for the next measure via clefState. This per-measure
+// granularity matches what Verovio honors for MIDI: a transposition change takes
+// effect only via a between-measure <scoreDef>/<staffDef trans.*>, never from a
+// mid-measure <clef> element.
+const measureStartClef = (measure: Measure, globalStaff: number, partInfos: PartInfo[], carriedClef?: string): string | undefined => {
+	let active = carriedClef;
+	for (let pi = 0; pi < measure.parts.length; pi++) {
+		const partOffset = partInfos[pi]?.staffOffset || 0;
+		for (const voice of measure.parts[pi].voices) {
+			if ((partOffset + (voice.staff || 1)) !== globalStaff) continue;
+			for (const event of voice.events) {
+				if (event.type === 'note' || event.type === 'rest' ||
+					event.type === 'tuplet' || event.type === 'times' || event.type === 'tremolo') {
+					break; // notes have started; a later clef change governs the next measure
+				}
+				if (event.type === 'context') {
+					const ctx = event as ContextChange;
+					if (ctx.clef) active = ctx.clef;
+				}
+			}
+		}
+	}
+	return active;
+};
+
+
 // Barline style to MEI @right attribute mapping
 const BARLINE_TO_MEI: Record<string, string> = {
 	'|': 'single',
@@ -2021,16 +2063,54 @@ const analyzePartStructure = (doc: LilyletDoc): PartInfo[] => {
 // MEI staffGrp @symbol for a layout group type (Default → none; Square → bracketsq).
 const LAYOUT_SYMBOL: (string | null)[] = [null, "brace", "bracket", "bracketsq"];
 
+// MIDI channel allocator: assigns one channel per distinct GM program so that
+// instruments get separate timbres. Verovio defaults every staff to channel 0
+// unless <instrDef midi.channel> is set, which would make all ProgramChanges
+// collide on one channel (only the last program would sound). We dedup by
+// program number — duplicate desks (e.g. two "Violins" staves) share a channel
+// — and skip channel 9 (the GM percussion channel) for pitched instruments.
+interface ChannelAllocator {
+	byProgram: Map<number, number>;
+	nextChannel: number;
+}
+
+const newChannelAllocator = (): ChannelAllocator => ({ byProgram: new Map(), nextChannel: 0 });
+
+// Channel for a program: reuse the channel already assigned to that program,
+// else take the next free channel (skipping 9). Wraps past 16 as graceful
+// degradation for scores with more than 15 distinct timbres.
+const allocChannel = (alloc: ChannelAllocator, program: number): number => {
+	const existing = alloc.byProgram.get(program);
+	if (existing !== undefined) return existing;
+	let ch = alloc.nextChannel;
+	if (ch % 16 === 9) ch++;		// skip GM drum channel
+	const assigned = ch % 16;
+	alloc.byProgram.set(program, assigned);
+	alloc.nextChannel = ch + 1;
+	return assigned;
+};
+
 // Build <label>/<labelAbbr> child XML for an instrument entry, or "" if none.
+// When the instrument name resolves to a General MIDI program, also emit an
+// <instrDef midi.instrnum midi.channel> sibling so Verovio's MIDI export assigns
+// that timbre (it honors only the numeric @midi.instrnum) on its own channel
+// (@midi.channel, else all instruments collide on channel 0). Unknown names emit
+// just the label, leaving Verovio's default program (0 = piano).
 const instrumentLabelXML = (
 	instr: InstrumentName | undefined,
 	indent: string,
+	channels?: ChannelAllocator,
 ): string => {
 	if (!instr) return "";
 	let xml = `${indent}<label>${escapeXml(instr.name)}</label>\n`;
 	if (instr.shortName !== undefined) {
 		xml += `${indent}<labelAbbr>${escapeXml(instr.shortName)}</labelAbbr>\n`;
 	}
+	const program = gmProgramOf(instr.name);
+	if (program !== undefined) {
+		const chanAttr = channels ? ` midi.channel="${allocChannel(channels, program)}"` : "";
+		xml += `${indent}<instrDef xml:id="${generateId("instrdef")}" midi.instrnum="${program}"${chanAttr} />\n`;
+	}
 	return xml;
 };
 
@@ -2046,28 +2126,29 @@ const layoutGroupToMEI = (
 	leafCounter: { i: number },
 	indent: string,
 	instruments: { [key: string]: InstrumentName },
+	channels: ChannelAllocator,
 ): string => {
 	const isLeaf = !!group.staff && (!group.subs || group.subs.length === 0);
 	const instr = group.key !== undefined ? instruments[group.key] : undefined;
 
 	// A leaf with no grouping symbol (Default) emits just the next staffDef (with label).
 	if (isLeaf && (group.type === StaffGroupType.Default || !LAYOUT_SYMBOL[group.type])) {
-		return staffDefWithLabel(staffDefAttrs[leafCounter.i++], instr, indent);
+		return staffDefWithLabel(staffDefAttrs[leafCounter.i++], instr, indent, channels);
 	}
 
 	const symbol = LAYOUT_SYMBOL[group.type] ? ` symbol="${LAYOUT_SYMBOL[group.type]}"` : "";
 	const barThru = (group.bar ?? 0) > 1 ? ' bar.thru="true"' : '';
 	let xml = `${indent}<staffGrp xml:id="${generateId("staffgrp")}"${symbol}${barThru}>\n`;
 	// A multi-staff group's instrument name labels the whole group.
-	if (!isLeaf) xml += instrumentLabelXML(instr, indent + "    ");
+	if (!isLeaf) xml += instrumentLabelXML(instr, indent + "    ", channels);
 	if (isLeaf) {
 		// A single staff that still carries a grouping bracket (e.g. "<b>"): MEI allows
 		// a staffGrp wrapping one staffDef. The instrument names the lone staff, so the
 		// label goes on the staffDef inside.
-		xml += staffDefWithLabel(staffDefAttrs[leafCounter.i++], instr, indent + "    ");
+		xml += staffDefWithLabel(staffDefAttrs[leafCounter.i++], instr, indent + "    ", channels);
 	} else {
 		for (const sub of group.subs || []) {
-			xml += layoutGroupToMEI(sub, staffDefAttrs, leafCounter, indent + "    ", instruments);
+			xml += layoutGroupToMEI(sub, staffDefAttrs, leafCounter, indent + "    ", instruments, channels);
 		}
 	}
 	xml += `${indent}</staffGrp>\n`;
@@ -2079,11 +2160,12 @@ const staffDefWithLabel = (
 	attrs: string | undefined,
 	instr: InstrumentName | undefined,
 	indent: string,
+	channels?: ChannelAllocator,
 ): string => {
 	if (attrs === undefined) return "";
 	if (!instr) return `${indent}<staffDef ${attrs} />\n`;
 	let xml = `${indent}<staffDef ${attrs}>\n`;
-	xml += instrumentLabelXML(instr, indent + "    ");
+	xml += instrumentLabelXML(instr, indent + "    ", channels);
 	xml += `${indent}</staffDef>\n`;
 	return xml;
 };
@@ -2101,6 +2183,10 @@ const encodeScoreDef = (
 ): string => {
 	const scoreDefId = generateId("scoredef");
 
+	// One MIDI channel allocator per score: assigns a distinct channel per GM
+	// program so instruments don't collide on channel 0 (see allocChannel).
+	const channels = newChannelAllocator();
+
 	// Build meter attributes
 	const meterSymAttr = meterSymbol ? ` meter.sym="${meterSymbol}"` : '';
 	let xml = `${indent}<scoreDef xml:id="${scoreDefId}" key.sig="${keySig}"${meterSymAttr} meter.count="${timeNum}" meter.unit="${timeDen}">\n`;
@@ -2123,7 +2209,7 @@ const encodeScoreDef = (
 			const staffDefAttrs = flatStaves.map(
 				s => `xml:id="${generateId('staffdef')}" n="${s.n}" lines="5" ${staffDefClefAttrs(s.clef)}`
 			);
-			xml += layoutGroupToMEI(layout.group, staffDefAttrs, { i: 0 }, `${indent}    `, instruments);
+			xml += layoutGroupToMEI(layout.group, staffDefAttrs, { i: 0 }, `${indent}    `, instruments, channels);
 			layoutUsed = true;
 		}
 	}
@@ -2142,13 +2228,13 @@ const encodeScoreDef = (
 				const last = info.staffOffset + info.maxStaff;
 				const instr = instruments[`${first}-${last}`];
 				xml += `${indent}        <staffGrp xml:id="${generateId("staffgrp")}" symbol="brace" bar.thru="true">\n`;
-				xml += instrumentLabelXML(instr, `${indent}            `);
+				xml += instrumentLabelXML(instr, `${indent}            `, channels);
 				for (let ls = 1; ls <= info.maxStaff; ls++) {
 					const globalStaff = info.staffOffset + ls;
 					const clef = info.clefs[ls] || Clef.treble;
 					const leafInstr = instruments[`${globalStaff}`];
 					const attrs = `xml:id="${generateId('staffdef')}" n="${globalStaff}" lines="5" ${staffDefClefAttrs(clef)}`;
-					xml += staffDefWithLabel(attrs, leafInstr, `${indent}            `);
+					xml += staffDefWithLabel(attrs, leafInstr, `${indent}            `, channels);
 				}
 				xml += `${indent}        </staffGrp>\n`;
 			} else {
@@ -2157,7 +2243,7 @@ const encodeScoreDef = (
 				const clef = info.clefs[1] || Clef.treble;
 				const leafInstr = instruments[`${globalStaff}`];
 				const attrs = `xml:id="${generateId('staffdef')}" n="${globalStaff}" lines="5" ${staffDefClefAttrs(clef)}`;
-				xml += staffDefWithLabel(attrs, leafInstr, `${indent}        `);
+				xml += staffDefWithLabel(attrs, leafInstr, `${indent}        `, channels);
 			}
 		}
 
@@ -2547,11 +2633,18 @@ const encode = (doc: LilyletDoc, options: MEIEncoderOptions = {}): string => {
 
 	// Initialize clef state from partInfos (convert local staff to global staff)
 	const clefState: ClefState = {};
+	// Running written→sounding transposition per global staff, as the verbatim
+	// "diat,semi" key. Seeded from the initial clefs (which the leading <scoreDef>
+	// already encoded via staffDefClefAttrs), then advanced whenever a measure
+	// starts under a clef with a different transposition.
+	const transState: Record<number, string> = {};
 	for (let pi = 0; pi < partInfos.length; pi++) {
 		const partInfo = partInfos[pi];
 		for (const [localStaffStr, clef] of Object.entries(partInfo.clefs)) {
 			const globalStaff = partInfo.staffOffset + parseInt(localStaffStr);
 			clefState[globalStaff] = clef;
+			const t = clefTransOf(clef);
+			transState[globalStaff] = `${t.diat},${t.semi}`;
 		}
 	}
 
@@ -2603,6 +2696,37 @@ const encode = (doc: LilyletDoc, options: MEIEncoderOptions = {}): string => {
 				mei += `${indent}${indent}${indent}${indent}${indent}${indent}<scoreDef xml:id="${generateId('scoredef')}"${meterSymAttr} meter.count="${currentTimeNum}" meter.unit="${currentTimeDen}" />\n`;
 			}
 		}
+		// Check for a written→sounding transposition change at this measure
+		// boundary and mirror it into MIDI. Verovio applies att.transposition only
+		// from <staffDef>, never from a mid-measure <clef>, so a change of
+		// transposing clef must be re-declared via a between-measure <scoreDef>.
+		// We emit only the staves whose transposition actually changed (a partial
+		// <staffGrp> leaves the others' state intact), using explicit "0,0" to
+		// clear a prior transposition when a transposing clef is replaced by a
+		// plain one. mi === 0 is already covered by the leading <scoreDef>.
+		if (mi > 0) {
+			const changed: string[] = [];
+			for (let si = 1; si <= totalStaves; si++) {
+				const startClef = measureStartClef(measure, si, partInfos, clefState[si]);
+				if (startClef === undefined) continue;
+				const t = clefTransOf(startClef);
+				const key = `${t.diat},${t.semi}`;
+				if (transState[si] === undefined) { transState[si] = key; continue; }
+				if (key !== transState[si]) {
+					transState[si] = key;
+					const c = resolveClef(startClef);
+					changed.push(`${indent}${indent}${indent}${indent}${indent}${indent}${indent}${indent}<staffDef xml:id="${generateId('staffdef')}" n="${si}" lines="5" clef.shape="${c.shape}" clef.line="${c.line}" trans.diat="${t.diat}" trans.semi="${t.semi}" />`);
+				}
+			}
+			if (changed.length > 0) {
+				const sd = `${indent}${indent}${indent}${indent}${indent}${indent}`;
+				mei += `${sd}<scoreDef xml:id="${generateId('scoredef')}">\n`;
+				mei += `${sd}${indent}<staffGrp xml:id="${generateId('staffgrp')}">\n`;
+				mei += changed.join("\n") + "\n";
+				mei += `${sd}${indent}</staffGrp>\n`;
+				mei += `${sd}</scoreDef>\n`;
+			}
+		}
 		mei += encodeMeasure(measure, mi + 1, `${indent}${indent}${indent}${indent}${indent}${indent}`, totalStaves, tieState, slurState, hairpinState, ottavaState, currentKey, partInfos, clefState, octaveEndReplacements);
 	});
 

package/source/lilylet/staffLayout.ts

@@ -240,6 +240,82 @@ export class StaffLayout {
 
 export const parseStaffLayout = (code: string): StaffLayout => new StaffLayout(tokenize(code));
 
+// ── Staff-layout serialization (inverse of parseStaffLayout) ──
+// Reconstruct a layout string from a parsed StaffLayout by walking the group tree,
+// so every staff slot and conjunction is preserved structurally (a regex strip of the
+// ids would drop a BARE anonymous leaf — its empty token gets swallowed by whitespace).
+//
+// `anonymous` emits empty ids (the parser re-auto-names slots "1","2",… by position).
+// `idMap` optionally overrides individual staff ids by their original id.
+//
+// Conjunction rendering: Solid → "-", Dashed → ".", Blank → " " ONLY when both sides
+// are bracketed groups (the brackets self-delimit the slots); otherwise Blank → ","
+// so an adjacent empty/bare leaf still tokenizes as its own slot.
+
+const CONJ_CHAR: { [c in StaffConjunctionType]: string } = {
+	[StaffConjunctionType.Solid]: "-",
+	[StaffConjunctionType.Dashed]: ".",
+	[StaffConjunctionType.Blank]: ",",
+};
+
+export interface SerializeStaffLayoutOptions {
+	anonymous?: boolean;
+	idMap?: (originalId: string) => string;
+}
+
+export const serializeStaffLayout = (layout: StaffLayout, options: SerializeStaffLayoutOptions = {}): string => {
+	const { anonymous = false, idMap } = options;
+	const isGrouped = (group: StaffGroup): boolean => group.type !== StaffGroupType.Default && !!group.subs;
+
+	const leafText = (id: string): string => (anonymous ? "" : idMap ? idMap(id) : id);
+
+	// flat leaf index of a group's first / last staff (for the inter-child conjunction).
+	const firstLeafIndex = (group: StaffGroup): number => layout.staffIds.indexOf(groupHead(group)!);
+	const lastLeafIndex = (group: StaffGroup): number => layout.staffIds.indexOf(groupTail(group)!);
+
+	const sep = (conj: StaffConjunctionType, left: StaffGroup, right: StaffGroup): string => {
+		if (conj !== StaffConjunctionType.Blank) return CONJ_CHAR[conj];
+		// Blank: a space is safe only when both neighbours are bracketed (self-delimiting).
+		return isGrouped(left) && isGrouped(right) ? " " : ",";
+	};
+
+	const emit = (group: StaffGroup): string => {
+		if (!group.subs) return leafText(group.staff!);  // Default leaf
+
+		const open = group.type === StaffGroupType.Brace ? "{" : group.type === StaffGroupType.Bracket ? "<" : group.type === StaffGroupType.Square ? "[" : "";
+		const close = group.type === StaffGroupType.Brace ? "}" : group.type === StaffGroupType.Bracket ? ">" : group.type === StaffGroupType.Square ? "]" : "";
+
+		let inner = "";
+		group.subs.forEach((sub, i) => {
+			inner += emit(sub);
+			if (i < group.subs!.length - 1) {
+				const next = group.subs![i + 1];
+				const conj = layout.conjunctions[lastLeafIndex(sub)] ?? StaffConjunctionType.Blank;
+				inner += sep(conj, sub, next);
+				void firstLeafIndex;  // (lastLeafIndex(sub) === firstLeafIndex(next) - 1)
+			}
+		});
+		return open + inner + close;
+	};
+
+	let out = emit(layout.group);
+
+	// A TRAILING bare anonymous leaf emits "" with nothing after it to delimit the slot
+	// (a leaf before a closing bracket is fine — the bracket gives it bounds; an internal
+	// one is flushed by the next separator). The tokenizer only flushes a final empty item
+	// if it carries bounds, so append one "," to materialize that last empty slot. This only
+	// arises when the OUTERMOST container is the Default sequence (no enclosing bracket) and
+	// its last child is a bare leaf; if the whole layout is wrapped in a bracket, the closing
+	// bracket already delimits the final leaf. The trailing conjunction is dropped on re-parse
+	// (conjunctions = items[0..n-1]), so it is harmless. Anonymous output only.
+	if (anonymous && layout.group.type === StaffGroupType.Default && layout.group.subs) {
+		const lastTop = layout.group.subs[layout.group.subs.length - 1];
+		if (!lastTop.subs && lastTop.staff !== undefined) out += ",";
+	}
+
+	return out;
+};
+
 // ── MEI staffGrp encoding (ported from FindLab staffLayout/encoding.js encodeMEI) ──
 // Recursively emit nested <staffGrp> with symbol (brace/bracket/square) and bar.thru,
 // with <staffDef n="..."> leaves keyed by staff index. nameDict maps a group key to a