@k-l-lambda/lilylet 0.1.69 → 0.1.71

package/source/lilylet/index.ts

@@ -2,6 +2,7 @@
 export * from "./types";
 export * from "./parser";
 export * from "./serializer";
+export * from "./staffLayout";
 
 import * as meiEncoder from "./meiEncoder";
 import * as musicXmlDecoder from "./musicXmlDecoder";

package/source/lilylet/lilylet.jison

@@ -130,6 +130,25 @@
 	const dynamicEvent = (type) => ({ type: 'dynamic', dynamicType: type });
 	const markupMark = (content) => ({ markType: 'markup', content });
 
+	// Build an { instruments: { <key>: { name, shortName? } } } fragment from a
+	// `[instrument-<key>` header token. <key> is a staff-layout group key — a single
+	// staff id ("1", "v1", "b") or a range ("1-2", "pl-pr") — taken verbatim after the
+	// "[instrument-" prefix so it lines up with staffLayout's groupKey().
+	const instrumentStaff = (token, name, shortName) => {
+		const key = token.slice('[instrument-'.length);
+		const entry = shortName !== undefined ? { name, shortName } : { name };
+		return { instruments: { [key]: entry } };
+	};
+
+	// Merge two header fragments. Plain fields are overwritten by the later one, but the
+	// `instruments` map is deep-merged so multiple [instrument-<key>] lines accumulate.
+	const mergeHeaders = (a, b) => {
+		const merged = { ...a, ...b };
+		if (a.instruments || b.instruments)
+			merged.instruments = { ...a.instruments, ...b.instruments };
+		return merged;
+	};
+
 	// Parse PITCH token (e.g., "c", "cs", "bf", "css", "bff") into phonet and accidental
 	const parsePitch = (text, octave) => {
 		const phonet = text[0].toLowerCase();
@@ -227,8 +246,10 @@
 \[arranger						return 'HEADER_ARRANGER'
 \[lyricist						return 'HEADER_LYRICIST'
 \[opus							return 'HEADER_OPUS'
+\[instrument\-[A-Za-z0-9_]+(?:\-[A-Za-z0-9_]+)*	return 'HEADER_INSTRUMENT_STAFF'
 \[instrument					return 'HEADER_INSTRUMENT'
 \[genre							return 'HEADER_GENRE'
+\[staves						return 'HEADER_STAVES'
 \[auto\-beam					return 'HEADER_AUTOBEAM'
 \]								return ']'
 
@@ -350,6 +371,8 @@ document
 content
 	: headers measures							-> ({ metadata: $1, measures: $2 })
 	| headers newlines measures					-> ({ metadata: $1, measures: $3 })
+	| newlines headers measures					-> ({ metadata: $2, measures: $3 })
+	| newlines headers newlines measures		-> ({ metadata: $2, measures: $4 })
 	| newlines measures							-> ({ metadata: undefined, measures: $2 })
 	| measures									-> ({ metadata: undefined, measures: $1 })
 	;
@@ -361,9 +384,9 @@ newlines
 
 headers
 	: header									-> $1
-	| headers header							-> ({ ...$1, ...$2 })
+	| headers header							-> mergeHeaders($1, $2)
 	| headers NEWLINE							-> $1
-	| headers NEWLINE header					-> ({ ...$1, ...$3 })
+	| headers NEWLINE header					-> mergeHeaders($1, $3)
 	;
 
 header
@@ -374,7 +397,10 @@ header
 	| HEADER_LYRICIST STRING ']'				-> ({ lyricist: $2.slice(1, -1) })
 	| HEADER_OPUS STRING ']'					-> ({ opus: $2.slice(1, -1) })
 	| HEADER_INSTRUMENT STRING ']'				-> ({ instrument: $2.slice(1, -1) })
+	| HEADER_INSTRUMENT_STAFF STRING ']'		-> instrumentStaff($1, $2.slice(1, -1))
+	| HEADER_INSTRUMENT_STAFF STRING STRING ']'	-> instrumentStaff($1, $2.slice(1, -1), $3.slice(1, -1))
 	| HEADER_GENRE STRING ']'					-> ({ genre: $2.slice(1, -1) })
+	| HEADER_STAVES STRING ']'					-> ({ staves: $2.slice(1, -1) })
 	| HEADER_AUTOBEAM STRING ']'				-> ({ autoBeam: $2.slice(1, -1) })
 	;
 

package/source/lilylet/meiEncoder.ts

@@ -25,7 +25,10 @@ import {
 	NavigationMarkType,
 	Tempo,
 	Event,
+	InstrumentName,
 } from "./types";
+import { parseStaffLayout, StaffGroup, StaffGroupType } from "./staffLayout";
+import { gmProgramOf } from "./gmInstruments";
 
 
 // MEI key signatures: positive = sharps, negative = flats
@@ -80,41 +83,73 @@ const CLEF_SHAPES: Record<string, { shape: string; line: number }> = {
 };
 
 
-// Resolve a clef string into MEI shape/line plus optional octave displacement.
-// Octave transposition follows the LilyPond convention: a "_8"/"_15" suffix lowers
-// the sounding pitch by one/two octaves (the small 8/15 is drawn below the clef),
-// and "^8"/"^15" raises it (drawn above). MEI encodes this as dis ("8" | "15")
-// and dis.place ("below" | "above").
-const resolveClef = (clefStr: string): { shape: string; line: number; dis?: "8" | "15"; disPlace?: "above" | "below" } => {
-	const match = clefStr.match(/^(.*?)([_^])(8|15)$/);
+// 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,
+// 5 = 5th, 8 = octave, 15 = two octaves); "_" lowers the sounding pitch, "^"
+// 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.
+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] === "^");
 	return {
 		shape: clefInfo.shape,
 		line: clefInfo.line,
-		dis: match[3] as "8" | "15",
-		disPlace: match[2] === "^" ? "above" : "below",
+		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 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);
-	let attrs = `shape="${c.shape}" line="${c.line}"`;
-	if (c.dis) attrs += ` dis="${c.dis}" dis.place="${c.disPlace}"`;
-	return attrs;
+	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).
+// 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 => {
 	const c = resolveClef(clefStr);
 	let attrs = `clef.shape="${c.shape}" clef.line="${c.line}"`;
-	if (c.dis) attrs += ` clef.dis="${c.dis}" clef.dis.place="${c.disPlace}"`;
+	if (c.trans) attrs += ` trans.diat="${c.trans.diat}" trans.semi="${c.trans.semi}"`;
 	return attrs;
 };
 
 
+
 // Lilylet duration division to MEI dur
 // division: 1=whole, 2=half, 4=quarter, 8=eighth, etc.
 const DURATIONS: Record<number, string> = {
@@ -1705,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',
@@ -1995,6 +2060,116 @@ const analyzePartStructure = (doc: LilyletDoc): PartInfo[] => {
 	return partInfos;
 };
 
+// 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;
+};
+
+// Recursively emit a <staffGrp>/<staffDef> tree from a parsed [staves] layout group.
+// `staffDefAttrs` maps a leaf staff index (0-based, in layout order) to the attribute
+// string for the matching global staff's <staffDef>. `instruments` maps a layout group
+// key (staffLayout's groupKey: a staff id or range) to its instrument name; matching
+// names are emitted as <label>/<labelAbbr> on the staffGrp (groups) or staffDef (leaves).
+// bar.thru reflects the group's conjunction (Solid).
+const layoutGroupToMEI = (
+	group: StaffGroup,
+	staffDefAttrs: string[],
+	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, 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 + "    ", 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 + "    ", channels);
+	} else {
+		for (const sub of group.subs || []) {
+			xml += layoutGroupToMEI(sub, staffDefAttrs, leafCounter, indent + "    ", instruments, channels);
+		}
+	}
+	xml += `${indent}</staffGrp>\n`;
+	return xml;
+};
+
+// Emit a <staffDef> from its attribute string, with optional instrument <label> children.
+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 + "    ", channels);
+	xml += `${indent}</staffDef>\n`;
+	return xml;
+};
+
 // Encode scoreDef with part groups
 const encodeScoreDef = (
 	keySig: string,
@@ -2002,36 +2177,79 @@ const encodeScoreDef = (
 	timeDen: number,
 	partInfos: PartInfo[],
 	indent: string,
-	meterSymbol?: 'common' | 'cut'
+	meterSymbol?: 'common' | 'cut',
+	stavesCode?: string,
+	instruments: { [key: string]: InstrumentName } = {}
 ): 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`;
-	xml += `${indent}    <staffGrp xml:id="${generateId("staffgrp")}">\n`;
 
-	for (let pi = 0; pi < partInfos.length; pi++) {
-		const info = partInfos[pi];
-
-		// If part has multiple staves (grand staff), wrap in staffGrp with brace
-		if (info.maxStaff > 1) {
-			xml += `${indent}        <staffGrp xml:id="${generateId("staffgrp")}" symbol="brace" bar.thru="true">\n`;
-			for (let ls = 1; ls <= info.maxStaff; ls++) {
-				const globalStaff = info.staffOffset + ls;
-				const clef = info.clefs[ls] || Clef.treble;
-				xml += `${indent}            <staffDef xml:id="${generateId('staffdef')}" n="${globalStaff}" lines="5" ${staffDefClefAttrs(clef)} />\n`;
+	// Flat ordered list of global staves (n + clef), in part/voice order.
+	const flatStaves: { n: number; clef: Clef }[] = [];
+	for (const info of partInfos) {
+		for (let ls = 1; ls <= info.maxStaff; ls++) {
+			flatStaves.push({ n: info.staffOffset + ls, clef: info.clefs[ls] || Clef.treble });
+		}
+	}
+
+	// If a [staves] layout is present and its leaf count matches the staves, drive
+	// the nested staffGrp (bracket/bracketsq/brace) from it. Otherwise fall back to
+	// the per-part grand-staff grouping.
+	let layoutUsed = false;
+	if (stavesCode) {
+		const layout = parseStaffLayout(stavesCode);
+		if (layout.stavesCount === flatStaves.length) {
+			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, channels);
+			layoutUsed = true;
+		}
+	}
+
+	if (!layoutUsed) {
+		xml += `${indent}    <staffGrp xml:id="${generateId("staffgrp")}">\n`;
+
+		for (let pi = 0; pi < partInfos.length; pi++) {
+			const info = partInfos[pi];
+
+			// If part has multiple staves (grand staff), wrap in staffGrp with brace.
+			// Instrument key for a part follows staffLayout's groupKey: a single staff
+			// number, or "first-last" for a grand staff.
+			if (info.maxStaff > 1) {
+				const first = info.staffOffset + 1;
+				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}            `, 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}            `, channels);
+				}
+				xml += `${indent}        </staffGrp>\n`;
+			} else {
+				// Single staff part
+				const globalStaff = info.staffOffset + 1;
+				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}        `, channels);
 			}
-			xml += `${indent}        </staffGrp>\n`;
-		} else {
-			// Single staff part
-			const globalStaff = info.staffOffset + 1;
-			const clef = info.clefs[1] || Clef.treble;
-			xml += `${indent}        <staffDef xml:id="${generateId('staffdef')}" n="${globalStaff}" lines="5" ${staffDefClefAttrs(clef)} />\n`;
 		}
+
+		xml += `${indent}    </staffGrp>\n`;
 	}
 
-	xml += `${indent}    </staffGrp>\n`;
 	xml += `${indent}</scoreDef>\n`;
 	return xml;
 };
@@ -2397,7 +2615,7 @@ const encode = (doc: LilyletDoc, options: MEIEncoderOptions = {}): string => {
 	mei += `${indent}${indent}<body>\n`;
 	mei += `${indent}${indent}${indent}<mdiv xml:id="${generateId("mdiv")}">\n`;
 	mei += `${indent}${indent}${indent}${indent}<score xml:id="${generateId("score")}">\n`;
-	mei += encodeScoreDef(keySig, currentTimeNum, currentTimeDen, partInfos, `${indent}${indent}${indent}${indent}${indent}`, currentMeterSymbol);
+	mei += encodeScoreDef(keySig, currentTimeNum, currentTimeDen, partInfos, `${indent}${indent}${indent}${indent}${indent}`, currentMeterSymbol, doc.metadata?.staves, doc.metadata?.instruments);
 	mei += `${indent}${indent}${indent}${indent}${indent}<section xml:id="${generateId("section")}">\n`;
 
 	// Track tie state across measures for cross-measure ties
@@ -2415,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}`;
 		}
 	}
 
@@ -2471,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/musicXmlDecoder.ts

@@ -749,6 +749,15 @@ const parseMetadata = (doc: Document): Metadata => {
 				}
 			}
 		}
+
+		// Staff layout: recover the raw [staves] string stashed at encode time.
+		const miscFields = getElements(identificationEl, 'miscellaneous-field');
+		for (const field of miscFields) {
+			if (getAttribute(field, 'name') === 'lilylet-staves') {
+				const code = field.textContent?.trim();
+				if (code) metadata.staves = code;
+			}
+		}
 	}
 
 	return Object.keys(metadata).length > 0 ? metadata : {};