@k-l-lambda/lilylet 0.1.38 → 0.1.40

package/lib/lilypondEncoder.d.ts

@@ -16,6 +16,11 @@ interface RenderOptions {
 }
 /**
  * Encode a complete LilyletDoc to LilyPond format
+ *
+ * Structure:
+ * - Multiple parts → outer <<>>
+ * - Part with multiple staves → GrandStaff
+ * - Part with single staff → standalone Staff
  */
 export declare const encode: (doc: LilyletDoc, options?: RenderOptions) => string;
 /**

package/lib/lilypondEncoder.js

@@ -102,6 +102,19 @@ const BARLINE_MAP = {
     ":..:": ":..:",
     ":..:|": ":..:|",
 };
+// === Helper Functions ===
+/**
+ * Generate a spacer rest that fills a measure based on time signature.
+ * Uses multiplication syntax: s{denominator}*{numerator}
+ * @param timeSig - Time signature { numerator, denominator }
+ * @returns LilyPond spacer rest string (e.g., "s4*3" for 3/4, "s8*6" for 6/8)
+ */
+const getSpacerRest = (timeSig) => {
+    if (!timeSig)
+        return 's1';
+    const { numerator, denominator } = timeSig;
+    return `s${denominator}*${numerator}`;
+};
 /**
  * Calculate the octave markers needed to serialize a pitch in relative mode.
  */
@@ -448,9 +461,10 @@ const encodeBarlineEvent = (event) => {
 };
 /**
  * Encode a harmony event (chord symbol)
+ * Uses the lilylet extension: \chords "text" (parsed by modified lotus grammar)
  */
 const encodeHarmonyEvent = (event) => {
-    return `^\\markup { ${event.text} }`;
+    return `\\chords "${event.text}"`;
 };
 /**
  * Encode a markup event
@@ -552,29 +566,63 @@ const encodeMetadata = (metadata) => {
 };
 /**
  * Encode a complete LilyletDoc to LilyPond format
+ *
+ * Structure:
+ * - Multiple parts → outer <<>>
+ * - Part with multiple staves → GrandStaff
+ * - Part with single staff → standalone Staff
  */
 export const encode = (doc, options = {}) => {
     const opts = { ...DEFAULT_OPTIONS, ...options };
-    // Collect all voices across measures, grouped by staff
-    const staffVoices = new Map(); // staff -> measure -> voice content
+    // Filter out trailing empty measures (measures with no musical content)
+    const hasMusicContent = (measure) => {
+        for (const part of measure.parts) {
+            for (const voice of part.voices) {
+                for (const event of voice.events) {
+                    if (event.type === 'note' || event.type === 'rest' || event.type === 'tuplet' || event.type === 'tremolo') {
+                        return true;
+                    }
+                }
+            }
+        }
+        return false;
+    };
+    // Trim trailing empty measures
+    let measureCount = doc.measures.length;
+    while (measureCount > 0 && !hasMusicContent(doc.measures[measureCount - 1])) {
+        measureCount--;
+    }
+    const measures = doc.measures.slice(0, measureCount);
+    // Determine number of parts from the document
+    const partCount = Math.max(...measures.map(m => m.parts.length), 1);
+    const partVoices = [];
+    for (let pi = 0; pi < partCount; pi++) {
+        partVoices.push(new Map());
+    }
+    // Track time signature for each measure (for spacer rests)
+    const measureTimeSigs = [];
     let currentKey;
     let currentTimeSig;
-    for (let mi = 0; mi < doc.measures.length; mi++) {
-        const measure = doc.measures[mi];
+    for (let mi = 0; mi < measures.length; mi++) {
+        const measure = measures[mi];
         // Update context from measure
         if (measure.key)
             currentKey = measure.key;
         if (measure.timeSig)
             currentTimeSig = measure.timeSig;
+        // Store time signature for this measure
+        measureTimeSigs[mi] = currentTimeSig;
         // Process each part
-        for (const part of measure.parts) {
+        for (let pi = 0; pi < measure.parts.length; pi++) {
+            const part = measure.parts[pi];
+            const staffMap = partVoices[pi];
             for (let vi = 0; vi < part.voices.length; vi++) {
                 const voice = part.voices[vi];
                 const staff = voice.staff || 1;
-                if (!staffVoices.has(staff)) {
-                    staffVoices.set(staff, []);
+                if (!staffMap.has(staff)) {
+                    staffMap.set(staff, []);
                 }
-                const staffMeasures = staffVoices.get(staff);
+                const staffMeasures = staffMap.get(staff);
                 // Ensure we have enough measure slots
                 while (staffMeasures.length <= mi) {
                     staffMeasures.push([]);
@@ -589,31 +637,75 @@ export const encode = (doc, options = {}) => {
             }
         }
     }
-    // Build music content
-    const staffCount = Math.max(...Array.from(staffVoices.keys()));
-    const staffStrings = [];
-    for (let si = 1; si <= staffCount; si++) {
-        const measures = staffVoices.get(si) || [];
+    // Build a staff string (used for both GrandStaff children and standalone Staff)
+    // Staff ID format: "partIndex_staffIndex" (e.g., "1_1", "1_2", "2_1") for multi-part decoding
+    const buildStaffString = (measures, staffId, indent) => {
         // Find max voices per measure for this staff
         const maxVoices = Math.max(...measures.map(m => m.length), 1);
         // Build voice lines
         const voiceLines = [];
         for (let vi = 0; vi < maxVoices; vi++) {
             const measureContents = measures.map((m, mi) => {
-                const content = m[vi] || 's1'; // Space rest if no content
-                return `        ${content} |  % ${mi + 1}`;
+                // Use correct spacer rest based on time signature
+                const spacer = getSpacerRest(measureTimeSigs[mi]);
+                const content = m[vi] || spacer;
+                // Wrap each measure in its own \relative c' to reset pitch context
+                return `${indent}    \\relative c' { ${content} } |  % ${mi + 1}`;
             });
-            voiceLines.push(`      \\new Voice \\relative c' {\n${measureContents.join('\n')}\n      }`);
+            voiceLines.push(`${indent}  \\new Voice {\n${measureContents.join('\n')}\n${indent}  }`);
+        }
+        return `${indent}\\new Staff = "${staffId}" <<\n${voiceLines.join('\n')}\n${indent}>>`;
+    };
+    // Build music content for each part
+    const partStrings = [];
+    for (let pi = 0; pi < partCount; pi++) {
+        const staffMap = partVoices[pi];
+        const staffNums = Array.from(staffMap.keys()).sort((a, b) => a - b);
+        if (staffNums.length === 0) {
+            // Empty part, skip
+            continue;
         }
-        staffStrings.push(`    \\new Staff = "${si}" <<\n${voiceLines.join('\n')}\n    >>`);
+        const partIndex = pi + 1; // 1-based part index
+        if (staffNums.length === 1) {
+            // Single staff part → standalone Staff
+            const staffNum = staffNums[0];
+            const measures = staffMap.get(staffNum);
+            const staffId = `${partIndex}_${staffNum}`;
+            const staffStr = buildStaffString(measures, staffId, '    ');
+            partStrings.push(staffStr);
+        }
+        else {
+            // Multiple staves → GrandStaff
+            const staffStrings = [];
+            for (const staffNum of staffNums) {
+                const measures = staffMap.get(staffNum);
+                const staffId = `${partIndex}_${staffNum}`;
+                const staffStr = buildStaffString(measures, staffId, '      ');
+                staffStrings.push(staffStr);
+            }
+            partStrings.push(`    \\new GrandStaff <<\n${staffStrings.join('\n')}\n    >>`);
+        }
+    }
+    const musicContent = partStrings.join('\n');
+    // Determine outer wrapper
+    // - Single part with single staff → just Staff (no outer <<>>)
+    // - Single part with multiple staves → GrandStaff (no extra outer <<>>)
+    // - Multiple parts → outer <<>>
+    let scoreContent;
+    if (partCount === 1 && partStrings.length === 1) {
+        // Single part - use as-is (already has Staff or GrandStaff)
+        scoreContent = musicContent;
+    }
+    else {
+        // Multiple parts - wrap in <<>>
+        scoreContent = `  <<\n${musicContent}\n  >>`;
     }
-    const musicContent = staffStrings.join('\n');
     // Build header
     const headerContent = doc.metadata ? encodeMetadata(doc.metadata) : '  tagline = ##f';
     // Build document
     const paperWidth = typeof opts.paper?.width === 'number' ? `${opts.paper.width}\\mm` : opts.paper?.width || '210\\mm';
     const paperHeight = typeof opts.paper?.height === 'number' ? `${opts.paper.height}\\mm` : opts.paper?.height || '297\\mm';
-    const lyDoc = `\\version "2.24.0"
+    const lyDoc = `\\version "2.22.0"
 
 \\language "english"
 
@@ -638,9 +730,7 @@ ${headerContent}
 }
 
 \\score {
-  \\new GrandStaff <<
-${musicContent}
-  >>
+${scoreContent}
 
   \\layout { }${opts.withMIDI ? '\n  \\midi { }' : ''}
 }

package/lib/meiEncoder.js

@@ -32,7 +32,8 @@ const keyToFifths = (key) => {
         fifths -= 7;
     if (key.mode === 'minor')
         fifths -= 3;
-    return fifths;
+    // Clamp to valid range [-7, 7] since standard notation doesn't support more than 7 sharps/flats
+    return Math.max(-7, Math.min(7, fifths));
 };
 const CLEF_SHAPES = {
     treble: { shape: "G", line: 2 },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k-l-lambda/lilylet",
-  "version": "0.1.38",
+  "version": "0.1.40",
   "description": "Lilylet is a lilyopnd-like sheet music language designed for Markdown rendering and symbolic music representation in AIGC applications.",
   "type": "module",
   "main": "lib/index.js",
@@ -37,7 +37,7 @@
   "license": "ISC",
   "homepage": "https://github.com/k-l-lambda/lilylet#readme",
   "optionalDependencies": {
-    "@k-l-lambda/lotus": "^1.0.3"
+    "@k-l-lambda/lotus": "^1.0.5"
   },
   "devDependencies": {
     "@types/node": "^20.11.20",

package/source/lilylet/lilypondDecoder.ts

@@ -20,6 +20,9 @@ import {
 	RestEvent,
 	ContextChange,
 	MarkupEvent,
+	HarmonyEvent,
+	TupletEvent,
+	TremoloEvent,
 	Pitch,
 	Duration,
 	Mark,
@@ -206,6 +209,7 @@ interface ParsedMeasure {
 
 interface ParsedVoice {
 	staff: number;
+	partIndex: number;  // 1-based part index (from staff ID format "partIndex_staffIndex")
 	events: Event[];
 }
 
@@ -237,25 +241,152 @@ const convertDuration = (duration: any): Duration => {
 };
 
 
-// Convert key fifths to KeySignature
-const convertKeySignature = (fifths: number): KeySignature | undefined => {
-	const mapping = KEY_FIFTHS_MAP[fifths];
-	if (mapping) {
+// Parse raw pitch string (e.g., "c'", "fis''", "bes,") to Pitch
+const parseRawPitch = (pitchStr: string): Pitch | undefined => {
+	if (!pitchStr) return undefined;
+
+	// Match: base note (a-g), optional accidentals (is/es/isis/eses), optional octave marks ('/, or ,)
+	const match = pitchStr.match(/^([a-g])(isis|eses|is|es)?([',]*)$/);
+	if (!match) return undefined;
+
+	const [, note, accidental, octaveMarks] = match;
+
+	// Map note to phonet
+	const phonetMap: Record<string, Phonet> = {
+		c: Phonet.c, d: Phonet.d, e: Phonet.e, f: Phonet.f,
+		g: Phonet.g, a: Phonet.a, b: Phonet.b,
+	};
+	const phonet = phonetMap[note];
+	if (!phonet) return undefined;
+
+	// Map accidental
+	const accidentalMap: Record<string, Accidental> = {
+		is: Accidental.sharp,
+		es: Accidental.flat,
+		isis: Accidental.doubleSharp,
+		eses: Accidental.doubleFlat,
+	};
+	const acc = accidental ? accidentalMap[accidental] : undefined;
+
+	// Calculate octave from marks (default octave 0 = C4)
+	let octave = 0;
+	for (const mark of octaveMarks || '') {
+		if (mark === "'") octave++;
+		else if (mark === ",") octave--;
+	}
+
+	return { phonet, accidental: acc, octave };
+};
+
+
+// Parse raw duration object from tuplet body
+const parseRawDuration = (duration: any): Duration | undefined => {
+	if (!duration) return undefined;
+	const number = parseInt(duration.number, 10);
+	if (isNaN(number)) return undefined;
+	return {
+		division: number,
+		dots: duration.dots || 0,
+	};
+};
+
+
+// Convert raw Chord from tuplet body to NoteEvent
+const convertRawChord = (chord: any, defaultDuration?: Duration): NoteEvent | undefined => {
+	if (!chord || chord.proto !== 'Chord') return undefined;
+
+	const pitches: Pitch[] = [];
+	for (const pitchElem of chord.pitches || []) {
+		const pitch = parseRawPitch(pitchElem.pitch);
+		if (pitch) pitches.push(pitch);
+	}
+
+	if (pitches.length === 0) return undefined;
+
+	const duration = parseRawDuration(chord.duration) || defaultDuration;
+	if (!duration) return undefined;
+
+	return {
+		type: 'note',
+		pitches,
+		duration,
+	};
+};
+
+
+// Parse pitch name with accidental (e.g., "cf" -> { pitch: Phonet.c, accidental: Accidental.flat })
+const parsePitchName = (name: string): { pitch: Phonet; accidental?: Accidental } | undefined => {
+	if (!name || name.length === 0) return undefined;
+
+	const phonetChar = name[0].toLowerCase();
+	const phonet = {
+		'c': Phonet.c, 'd': Phonet.d, 'e': Phonet.e, 'f': Phonet.f,
+		'g': Phonet.g, 'a': Phonet.a, 'b': Phonet.b
+	}[phonetChar];
+
+	if (!phonet) return undefined;
+
+	const accidentalPart = name.slice(1);
+	let accidental: Accidental | undefined;
+	if (accidentalPart === 's' || accidentalPart === 'is') {
+		accidental = Accidental.sharp;
+	} else if (accidentalPart === 'ss' || accidentalPart === 'isis') {
+		accidental = Accidental.doubleSharp;
+	} else if (accidentalPart === 'f' || accidentalPart === 'es') {
+		accidental = Accidental.flat;
+	} else if (accidentalPart === 'ff' || accidentalPart === 'eses') {
+		accidental = Accidental.doubleFlat;
+	}
+
+	return { pitch: phonet, accidental };
+};
+
+// Convert key from context to KeySignature
+const convertKeySignature = (keyContext: any): KeySignature | undefined => {
+	const args = keyContext?.args;
+
+	// Always parse from args to get correct pitch and mode
+	if (Array.isArray(args) && args.length >= 2) {
+		const pitchStr = args[0];
+		const modeStr = args[1];
+
+		const pitchInfo = parsePitchName(pitchStr);
+		if (pitchInfo) {
+			const mode = modeStr?.includes('minor') ? 'minor' : 'major';
+			return {
+				pitch: pitchInfo.pitch,
+				accidental: pitchInfo.accidental,
+				mode,
+			};
+		}
+	}
+
+	// Fallback to fifths lookup for compatibility (major keys only)
+	const fifths = keyContext?.key;
+	if (fifths !== undefined && KEY_FIFTHS_MAP[fifths]) {
+		const mapping = KEY_FIFTHS_MAP[fifths];
 		return {
 			pitch: mapping.pitch,
 			accidental: mapping.accidental,
 			mode: mapping.mode,
 		};
 	}
+
 	return undefined;
 };
 
 
-// Parse post-events to marks
-const parsePostEvents = (postEvents: any[]): Mark[] => {
+// Parse post-events to marks and detect harmony events
+interface PostEventResult {
+	marks: Mark[];
+	harmonyText?: string;
+}
+
+const parsePostEvents = (postEvents: any[]): PostEventResult => {
 	const marks: Mark[] = [];
+	let harmonyText: string | undefined;
 
-	if (!postEvents) return marks;
+	if (!postEvents) return { marks };
 
 	for (const event of postEvents) {
 		// String events
@@ -309,7 +440,31 @@ const parsePostEvents = (postEvents: any[]): Mark[] => {
 				} else if (cmd === 'segno') {
 					marks.push({ markType: 'navigation', type: NavigationMarkType.segno });
 				} else if (cmd === '\\markup' || cmd === 'markup') {
-					// Markup attached to note
+					// Check if this is a harmony (chord symbol) - marked with \bold
+					const harmony = extractHarmonyFromMarkup(arg.args);
+					if (harmony) {
+						harmonyText = harmony;
+					} else {
+						// Regular markup attached to note
+						const text = extractTextFromObject(arg.args);
+						if (text && !containsTempoWord(text)) {
+							const direction = event.direction;
+							const placement: Placement | undefined =
+								direction === 'up' ? Placement.above :
+								direction === 'down' ? Placement.below : undefined;
+							marks.push({ markType: 'markup', content: text, placement });
+						}
+					}
+				}
+			}
+
+			// Handle markup command directly (proto: 'MarkupCommand')
+			if (arg && typeof arg === 'object' && arg.proto === 'MarkupCommand') {
+				// Check if this is a harmony (chord symbol) - marked with \bold
+				const harmony = extractHarmonyFromMarkup(arg.args);
+				if (harmony) {
+					harmonyText = harmony;
+				} else {
 					const text = extractTextFromObject(arg.args);
 					if (text && !containsTempoWord(text)) {
 						const direction = event.direction;
@@ -320,22 +475,10 @@ const parsePostEvents = (postEvents: any[]): Mark[] => {
 					}
 				}
 			}
-
-			// Handle markup command directly (proto: 'Command' with \\markup)
-			if (arg && typeof arg === 'object' && arg.proto === 'Command' && arg.cmd === '\\markup') {
-				const text = extractTextFromObject(arg.args);
-				if (text && !containsTempoWord(text)) {
-					const direction = event.direction;
-					const placement: Placement | undefined =
-						direction === 'up' ? Placement.above :
-						direction === 'down' ? Placement.below : undefined;
-					marks.push({ markType: 'markup', content: text, placement });
-				}
-			}
 		}
 	}
 
-	return marks;
+	return { marks, harmonyText };
 };
 
 
@@ -353,11 +496,36 @@ const parseLilyDocument = (lilyDocument: lilyParser.LilyDocument): ParsedMeasure
 			}
 		};
 
-		const staffName = track.contextDict?.Staff;
-		if (staffName) {
-			appendStaff(staffName);
+		// Parse staff name to extract partIndex and staff number
+		// Format: "partIndex_staffIndex" (e.g., "1_1", "1_2", "2_1")
+		// Falls back to partIndex=1 if format doesn't match
+		const parseStaffName = (name: string): { partIndex: number; staffNum: number } => {
+			const match = name.match(/^(\d+)_(\d+)$/);
+			if (match) {
+				return { partIndex: parseInt(match[1], 10), staffNum: parseInt(match[2], 10) };
+			}
+			// Fallback: single part, staff number from name or 1
+			const num = parseInt(name, 10);
+			return { partIndex: 1, staffNum: isNaN(num) ? 1 : num };
+		};
+
+		// Use track.contextDict.Staff as the authoritative staff name (from Staff definition)
+		// This won't be affected by \change Staff commands inside the track
+		const initialStaffName = track.contextDict?.Staff;
+		if (initialStaffName) {
+			appendStaff(initialStaffName);
 		}
-		let staff = staffName ? staffNames.indexOf(staffName) + 1 : 1;
+		const parsedStaff = initialStaffName ? parseStaffName(initialStaffName) : { partIndex: 1, staffNum: 1 };
+		// Use these as fixed values for this track - don't update from context.staffName
+		const trackStaff = parsedStaff.staffNum;
+		const trackPartIndex = parsedStaff.partIndex;
+
+		// Track emitted context events across measures for this voice
+		let lastKey: number | undefined = undefined;  // Track value changes (key fifths)
+		let lastTimeSig: string | undefined = undefined;  // Track value changes (as string for comparison)
+		let lastClef: Clef | undefined = undefined;  // Track value changes
+		let lastOttava: number | undefined = undefined;  // Track value changes
+		let lastStemDirection: string | undefined = undefined;  // Track value changes
 
 		const context = new lilyParser.TrackContext(undefined, {
 			listener: (term: lilyParser.BaseTerm, context: lilyParser.TrackContext) => {
@@ -373,18 +541,13 @@ const parseLilyDocument = (lilyDocument: lilyParser.LilyDocument): ParsedMeasure
 					});
 				}
 
-				// Update staff from context
-				if (context.staffName) {
-					appendStaff(context.staffName);
-					staff = staffNames.indexOf(context.staffName) + 1;
-				}
-
 				const measure = measureMap.get(mi)!;
 
-				// Initialize voice for this track
+				// Initialize voice for this track (use fixed staff/part from track definition)
 				if (!measure.voices[vi]) {
 					measure.voices[vi] = {
-						staff,
+						staff: trackStaff,
+						partIndex: trackPartIndex,
 						events: [],
 					};
 				}
@@ -411,30 +574,62 @@ const parseLilyDocument = (lilyDocument: lilyParser.LilyDocument): ParsedMeasure
 
 				// Handle music events
 				if (term instanceof lilyParser.MusicEvent) {
-					// Update staff from voice events
-					voice.staff = staff;
+					// Staff is fixed per track (from track definition)
+					voice.staff = trackStaff;
+
+					// Handle key context change (emit when value changes)
+					if (context.key && context.key.key !== lastKey) {
+						const key = convertKeySignature(context.key);
+						if (key) {
+							voice.events.push({
+								type: 'context',
+								key,
+							});
+							lastKey = context.key.key;
+						}
+					}
+
+					// Handle time signature context change (emit when value changes)
+					if (context.time) {
+						const timeSigStr = `${context.time.value.numerator}/${context.time.value.denominator}`;
+						if (timeSigStr !== lastTimeSig) {
+							voice.events.push({
+								type: 'context',
+								timeSig: {
+									numerator: context.time.value.numerator,
+									denominator: context.time.value.denominator,
+								},
+							});
+							lastTimeSig = timeSigStr;
+						}
+					}
 
-					// Handle clef context change
-					if (context.clef && !voice.events.some(e => e.type === 'context' && (e as ContextChange).clef)) {
+					// Handle clef context change (emit when value changes)
+					if (context.clef) {
 						const clef = LILYPOND_CLEF_MAP[context.clef.clefName];
-						if (clef) {
+						if (clef && clef !== lastClef) {
 							voice.events.push({
 								type: 'context',
 								clef,
 							});
+							lastClef = clef;
 						}
 					}
 
-					// Handle ottava
-					if (context.octave?.value && !voice.events.some(e => e.type === 'context' && (e as ContextChange).ottava !== undefined)) {
-						voice.events.push({
-							type: 'context',
-							ottava: context.octave.value,
-						});
+					// Handle ottava (emit when value changes)
+					if (context.octave != null) {
+						const currentOttava = context.octave.value ?? 0;
+						if (currentOttava !== lastOttava) {
+							voice.events.push({
+								type: 'context',
+								ottava: currentOttava,
+							});
+							lastOttava = currentOttava;
+						}
 					}
 
-					// Handle stem direction context
-					if (context.stemDirection && !voice.events.some(e => e.type === 'context' && (e as ContextChange).stemDirection)) {
+					// Handle stem direction context change (emit when value changes)
+					if (context.stemDirection && context.stemDirection !== lastStemDirection) {
 						const stemDir = context.stemDirection === 'Up' ? StemDirection.up :
 							context.stemDirection === 'Down' ? StemDirection.down : undefined;
 						if (stemDir) {
@@ -442,6 +637,7 @@ const parseLilyDocument = (lilyDocument: lilyParser.LilyDocument): ParsedMeasure
 								type: 'context',
 								stemDirection: stemDir,
 							});
+							lastStemDirection = context.stemDirection;
 						}
 					}
 
@@ -460,7 +656,7 @@ const parseLilyDocument = (lilyDocument: lilyParser.LilyDocument): ParsedMeasure
 						}
 
 						if (pitches.length > 0) {
-							const marks = parsePostEvents(term.post_events);
+							const { marks, harmonyText } = parsePostEvents(term.post_events);
 
 							// Add beam marks
 							if (term.beamOn) {
@@ -486,6 +682,15 @@ const parseLilyDocument = (lilyDocument: lilyParser.LilyDocument): ParsedMeasure
 							}
 
 							voice.events.push(noteEvent);
+
+							// Add harmony event if detected (chord symbol encoded as \bold markup)
+							if (harmonyText) {
+								const harmonyEvent: HarmonyEvent = {
+									type: 'harmony',
+									text: harmonyText,
+								};
+								voice.events.push(harmonyEvent);
+							}
 						}
 					}
 					// Process Rest
@@ -508,40 +713,45 @@ const parseLilyDocument = (lilyDocument: lilyParser.LilyDocument): ParsedMeasure
 						voice.events.push(restEvent);
 					}
 				}
-				// Handle standalone stem direction
+				// Handle standalone stem direction (emit when value changes)
 				else if (term instanceof lilyParser.LilyTerms.StemDirection) {
-					const stemDir = term.direction === 'Up' ? StemDirection.up :
-						term.direction === 'Down' ? StemDirection.down : undefined;
-					if (stemDir) {
-						voice.events.push({
-							type: 'context',
-							stemDirection: stemDir,
-						});
+					if (term.direction !== lastStemDirection) {
+						const stemDir = term.direction === 'Up' ? StemDirection.up :
+							term.direction === 'Down' ? StemDirection.down : undefined;
+						if (stemDir) {
+							voice.events.push({
+								type: 'context',
+								stemDirection: stemDir,
+							});
+							lastStemDirection = term.direction;
+						}
 					}
 				}
-				// Handle standalone clef
+				// Handle standalone clef (emit when value changes)
 				else if (term instanceof lilyParser.LilyTerms.Clef) {
 					const clef = LILYPOND_CLEF_MAP[term.clefName];
-					if (clef) {
+					if (clef && clef !== lastClef) {
 						voice.events.push({
 							type: 'context',
 							clef,
 						});
+						lastClef = clef;
 					}
 				}
 				// Handle ottava shift
 				else if (term instanceof lilyParser.LilyTerms.OctaveShift) {
-					voice.events.push({
-						type: 'context',
-						ottava: term.value,
-					});
+					if (term.value !== lastOttava) {
+						voice.events.push({
+							type: 'context',
+							ottava: term.value,
+						});
+						lastOttava = term.value;
+					}
 				}
 				// Handle staff change
 				else if (term instanceof lilyParser.LilyTerms.Change) {
-					if (term.args?.[0]?.key === 'Staff') {
-						// Staff change mid-voice
-						voice.staff = staff;
-					}
+					// Ignore \change Staff commands - staff is fixed per track
+					// (Cross-staff notation is not supported in this decoder)
 				}
 				// Handle tempo
 				else if (term instanceof lilyParser.LilyTerms.Tempo) {
@@ -553,17 +763,146 @@ const parseLilyDocument = (lilyDocument: lilyParser.LilyDocument): ParsedMeasure
 						});
 					}
 				}
-				// Handle standalone markup command
+				// Handle standalone markup command and barlines
 				else {
 					const termAny = term as any;
 					if (termAny.proto === 'Command' && (termAny.cmd === '\\markup' || termAny.cmd === 'markup')) {
-						const text = extractTextFromObject(termAny.args);
-						if (text && !containsTempoWord(text)) {
-							const markupEvent: MarkupEvent = {
-								type: 'markup',
-								content: text,
+						// Check if this is a harmony (chord symbol) - marked with \bold
+						const harmonyText = extractHarmonyFromMarkup(termAny.args);
+						if (harmonyText) {
+							const harmonyEvent: HarmonyEvent = {
+								type: 'harmony',
+								text: harmonyText,
 							};
-							voice.events.push(markupEvent);
+							voice.events.push(harmonyEvent);
+						} else {
+							const text = extractTextFromObject(termAny.args);
+							if (text && !containsTempoWord(text)) {
+								const markupEvent: MarkupEvent = {
+									type: 'markup',
+									content: text,
+								};
+								voice.events.push(markupEvent);
+							}
+						}
+					}
+					// Handle barline command - barlines belong to the previous measure
+					else if (termAny.proto === 'Command' && termAny.cmd === 'bar') {
+						const style = termAny.args?.[0]?.exp;
+						if (style && mi > 0) {
+							// Remove quotes from the style string
+							const barStyle = style.replace(/^"|"$/g, '');
+							// Add to previous measure's voice
+							const prevMeasure = measureMap.get(mi - 1);
+							if (prevMeasure && prevMeasure.voices[vi]) {
+								prevMeasure.voices[vi].events.push({
+									type: 'barline',
+									style: barStyle,
+								});
+							}
+						}
+					}
+					// Handle ChordSymbol (inline chord symbol: \chords "text")
+					else if (termAny.proto === 'ChordSymbol') {
+						// Extract text from LiteralString (e.g., { exp: '"C"' } -> "C")
+						let text = termAny.text;
+						if (typeof text === 'object' && text?.exp) {
+							text = text.exp.replace(/^"|"$/g, '');
+						} else if (typeof text === 'string') {
+							text = text.replace(/^"|"$/g, '');
+						}
+						const harmonyEvent: HarmonyEvent = {
+							type: 'harmony',
+							text: text,
+						};
+						voice.events.push(harmonyEvent);
+					}
+					// Handle tuplet
+					// Note: Lotus emits Chord events BEFORE the Tuplet term, so we need to
+					// remove the already-added notes and wrap them in a TupletEvent
+					else if (termAny.proto === 'Tuplet') {
+						const ratioStr = termAny.args?.[0];  // e.g., "3/2"
+						const body = termAny.args?.[1]?.body || [];
+
+						if (ratioStr && body.length > 0) {
+							// Parse ratio string
+							const ratioMatch = ratioStr.match(/^(\d+)\/(\d+)$/);
+							if (ratioMatch) {
+								const [, num, denom] = ratioMatch;
+								const ratio: Fraction = {
+									numerator: parseInt(denom, 10),  // Swapped: lilylet uses actual/normal
+									denominator: parseInt(num, 10),
+								};
+
+								// Count how many note/rest events are in the tuplet body
+								const noteCount = body.filter((item: any) =>
+									item.proto === 'Chord' || item.proto === 'Rest'
+								).length;
+
+								// Remove the last noteCount note/rest events from voice.events
+								// (they were already added by the Chord/Rest handlers)
+								const tupletEvents: Event[] = [];
+								let removed = 0;
+								while (removed < noteCount && voice.events.length > 0) {
+									const lastEvent = voice.events[voice.events.length - 1];
+									if (lastEvent.type === 'note' || lastEvent.type === 'rest') {
+										tupletEvents.unshift(voice.events.pop()!);
+										removed++;
+									} else {
+										break;  // Stop if we hit a non-note/rest event
+									}
+								}
+
+								if (tupletEvents.length > 0) {
+									const tupletEvent: TupletEvent = {
+										type: 'tuplet',
+										ratio,
+										events: tupletEvents,
+									};
+									voice.events.push(tupletEvent);
+								}
+							}
+						}
+					}
+					// Handle repeat tremolo
+					else if (termAny.proto === 'Repeat' && termAny.args?.[0] === 'tremolo') {
+						const count = parseInt(termAny.args?.[1], 10);
+						const body = termAny.args?.[2]?.body || [];
+
+						if (!isNaN(count) && body.length === 2) {
+							// Double tremolo has exactly 2 pitches
+							const pitch1 = body[0]?.pitches?.[0]?.pitch;
+							const pitch2 = body[1]?.pitches?.[0]?.pitch;
+							const duration = body[0]?.duration;
+
+							if (pitch1 && pitch2 && duration) {
+								const pitchA = parseRawPitch(pitch1);
+								const pitchB = parseRawPitch(pitch2);
+								const div = parseInt(duration.number, 10);
+
+								if (pitchA && pitchB && !isNaN(div)) {
+									// Remove the 2 notes that were already added
+									let removed = 0;
+									while (removed < 2 && voice.events.length > 0) {
+										const lastEvent = voice.events[voice.events.length - 1];
+										if (lastEvent.type === 'note') {
+											voice.events.pop();
+											removed++;
+										} else {
+											break;
+										}
+									}
+
+									const tremoloEvent: TremoloEvent = {
+										type: 'tremolo',
+										pitchA: [pitchA],
+										pitchB: [pitchB],
+										count,
+										division: div,
+									};
+									voice.events.push(tremoloEvent);
+								}
+							}
 						}
 					}
 				}
@@ -590,6 +929,8 @@ const hasRealContent = (events: Event[]): boolean => {
 	return events.some(e => {
 		if (e.type === 'note') return true;
 		if (e.type === 'rest' && !(e as RestEvent).invisible) return true;
+		if (e.type === 'tuplet') return true;
+		if (e.type === 'tremolo') return true;
 		return false;
 	});
 };
@@ -672,6 +1013,43 @@ const extractTextFromObject = (obj: any): string | undefined => {
 };
 
 
+// Check if markup contains \bold command (indicates harmony/chord symbol)
+// Returns the text if it's a harmony, undefined otherwise
+const extractHarmonyFromMarkup = (obj: any): string | undefined => {
+	if (!obj) return undefined;
+
+	// Check array of args
+	if (Array.isArray(obj)) {
+		for (const item of obj) {
+			const result = extractHarmonyFromMarkup(item);
+			if (result !== undefined) return result;
+		}
+		return undefined;
+	}
+
+	if (obj && typeof obj === 'object') {
+		// Check if this is a \bold command (can be Command or MarkupCommand)
+		if ((obj.proto === 'Command' || obj.proto === 'MarkupCommand') &&
+			(obj.cmd === 'bold' || obj.cmd === '\\bold')) {
+			// Extract the text from args
+			return extractTextFromObject(obj.args);
+		}
+
+		// Recursively search InlineBlock body
+		if (obj.proto === 'InlineBlock' && obj.body) {
+			return extractHarmonyFromMarkup(obj.body);
+		}
+
+		// Recursively search args
+		if (obj.args) {
+			return extractHarmonyFromMarkup(obj.args);
+		}
+	}
+
+	return undefined;
+};
+
+
 // Extract string value from header field
 const extractStringValue = (value: any): string | undefined => {
 	const text = extractTextFromObject(value);
@@ -726,17 +1104,30 @@ const extractMetadata = (lilyDocument: lilyParser.LilyDocument): Metadata | unde
 const parsedMeasuresToDoc = (parsedMeasures: ParsedMeasure[], metadata?: Metadata): LilyletDoc => {
 	const measures: Measure[] = parsedMeasures.map(pm => {
 		// Filter out voices that only contain spacer rests and context changes
-		const voices = pm.voices
-			.filter(v => hasRealContent(v.events))
-			.map(v => ({
+		const filteredVoices = pm.voices.filter(v => hasRealContent(v.events));
+
+		// Group voices by partIndex
+		const partMap = new Map<number, Array<{ staff: number; events: Event[] }>>();
+		for (const v of filteredVoices) {
+			const pi = v.partIndex || 1;
+			if (!partMap.has(pi)) {
+				partMap.set(pi, []);
+			}
+			partMap.get(pi)!.push({
 				staff: v.staff,
 				events: v.events,
-			}));
+			});
+		}
+
+		// Convert to parts array (sorted by part index)
+		const partIndices = Array.from(partMap.keys()).sort((a, b) => a - b);
+		const parts = partIndices.map(pi => ({
+			voices: partMap.get(pi)!,
+		}));
 
+		// Fallback to single empty part if no voices
 		const measure: Measure = {
-			parts: [{
-				voices,
-			}],
+			parts: parts.length > 0 ? parts : [{ voices: [] }],
 		};
 
 		if (pm.key !== null) {
@@ -750,7 +1141,9 @@ const parsedMeasuresToDoc = (parsedMeasures: ParsedMeasure[], metadata?: Metadat
 		}
 
 		return measure;
-	});
+	})
+	// Filter out empty measures (no voices in any part)
+	.filter(m => m.parts.some(p => p.voices.length > 0));
 
 	const doc: LilyletDoc = { measures };
 	if (metadata) {

package/source/lilylet/lilypondEncoder.ts

@@ -149,6 +149,21 @@ const BARLINE_MAP: Record<string, string> = {
 };
 
 
+// === Helper Functions ===
+
+/**
+ * Generate a spacer rest that fills a measure based on time signature.
+ * Uses multiplication syntax: s{denominator}*{numerator}
+ * @param timeSig - Time signature { numerator, denominator }
+ * @returns LilyPond spacer rest string (e.g., "s4*3" for 3/4, "s8*6" for 6/8)
+ */
+const getSpacerRest = (timeSig?: { numerator: number; denominator: number }): string => {
+	if (!timeSig) return 's1';
+	const { numerator, denominator } = timeSig;
+	return `s${denominator}*${numerator}`;
+};
+
+
 // === Pitch Environment for Relative Mode ===
 
 interface PitchEnv {
@@ -571,9 +586,10 @@ const encodeBarlineEvent = (event: BarlineEvent): string => {
 
 /**
  * Encode a harmony event (chord symbol)
+ * Uses the lilylet extension: \chords "text" (parsed by modified lotus grammar)
  */
 const encodeHarmonyEvent = (event: HarmonyEvent): string => {
-	return `^\\markup { ${event.text} }`;
+	return `\\chords "${event.text}"`;
 };
 
 
@@ -692,33 +708,76 @@ const encodeMetadata = (metadata: Metadata): string => {
 
 /**
  * Encode a complete LilyletDoc to LilyPond format
+ *
+ * Structure:
+ * - Multiple parts → outer <<>>
+ * - Part with multiple staves → GrandStaff
+ * - Part with single staff → standalone Staff
  */
 export const encode = (doc: LilyletDoc, options: RenderOptions = {}): string => {
 	const opts = { ...DEFAULT_OPTIONS, ...options };
 
-	// Collect all voices across measures, grouped by staff
-	const staffVoices: Map<number, string[][]> = new Map();  // staff -> measure -> voice content
+	// Filter out trailing empty measures (measures with no musical content)
+	const hasMusicContent = (measure: Measure): boolean => {
+		for (const part of measure.parts) {
+			for (const voice of part.voices) {
+				for (const event of voice.events) {
+					if (event.type === 'note' || event.type === 'rest' || event.type === 'tuplet' || event.type === 'tremolo') {
+						return true;
+					}
+				}
+			}
+		}
+		return false;
+	};
+
+	// Trim trailing empty measures
+	let measureCount = doc.measures.length;
+	while (measureCount > 0 && !hasMusicContent(doc.measures[measureCount - 1])) {
+		measureCount--;
+	}
+	const measures = doc.measures.slice(0, measureCount);
+
+	// Determine number of parts from the document
+	const partCount = Math.max(...measures.map(m => m.parts.length), 1);
+
+	// For each part, collect voices grouped by staff
+	// partVoices[partIndex][staff] = measureContents[][]  (measure -> voice contents)
+	type StaffVoicesMap = Map<number, string[][]>;
+	const partVoices: StaffVoicesMap[] = [];
+	for (let pi = 0; pi < partCount; pi++) {
+		partVoices.push(new Map());
+	}
+
+	// Track time signature for each measure (for spacer rests)
+	const measureTimeSigs: Array<{ numerator: number; denominator: number } | undefined> = [];
 
 	let currentKey: KeySignature | undefined;
-	let currentTimeSig: any;
+	let currentTimeSig: { numerator: number; denominator: number } | undefined;
 
-	for (let mi = 0; mi < doc.measures.length; mi++) {
-		const measure = doc.measures[mi];
+	for (let mi = 0; mi < measures.length; mi++) {
+		const measure = measures[mi];
 
 		// Update context from measure
 		if (measure.key) currentKey = measure.key;
 		if (measure.timeSig) currentTimeSig = measure.timeSig;
 
+		// Store time signature for this measure
+		measureTimeSigs[mi] = currentTimeSig;
+
 		// Process each part
-		for (const part of measure.parts) {
+		for (let pi = 0; pi < measure.parts.length; pi++) {
+			const part = measure.parts[pi];
+			const staffMap = partVoices[pi];
+
 			for (let vi = 0; vi < part.voices.length; vi++) {
 				const voice = part.voices[vi];
 				const staff = voice.staff || 1;
 
-				if (!staffVoices.has(staff)) {
-					staffVoices.set(staff, []);
+				if (!staffMap.has(staff)) {
+					staffMap.set(staff, []);
 				}
-				const staffMeasures = staffVoices.get(staff)!;
+				const staffMeasures = staffMap.get(staff)!;
 
 				// Ensure we have enough measure slots
 				while (staffMeasures.length <= mi) {
@@ -737,13 +796,9 @@ export const encode = (doc: LilyletDoc, options: RenderOptions = {}): string =>
 		}
 	}
 
-	// Build music content
-	const staffCount = Math.max(...Array.from(staffVoices.keys()));
-	const staffStrings: string[] = [];
-
-	for (let si = 1; si <= staffCount; si++) {
-		const measures = staffVoices.get(si) || [];
-
+	// Build a staff string (used for both GrandStaff children and standalone Staff)
+	// Staff ID format: "partIndex_staffIndex" (e.g., "1_1", "1_2", "2_1") for multi-part decoding
+	const buildStaffString = (measures: string[][], staffId: string, indent: string): string => {
 		// Find max voices per measure for this staff
 		const maxVoices = Math.max(...measures.map(m => m.length), 1);
 
@@ -751,16 +806,66 @@ export const encode = (doc: LilyletDoc, options: RenderOptions = {}): string =>
 		const voiceLines: string[] = [];
 		for (let vi = 0; vi < maxVoices; vi++) {
 			const measureContents = measures.map((m, mi) => {
-				const content = m[vi] || 's1';  // Space rest if no content
-				return `        ${content} |  % ${mi + 1}`;
+				// Use correct spacer rest based on time signature
+				const spacer = getSpacerRest(measureTimeSigs[mi]);
+				const content = m[vi] || spacer;
+				// Wrap each measure in its own \relative c' to reset pitch context
+				return `${indent}    \\relative c' { ${content} } |  % ${mi + 1}`;
 			});
-			voiceLines.push(`      \\new Voice \\relative c' {\n${measureContents.join('\n')}\n      }`);
+			voiceLines.push(`${indent}  \\new Voice {\n${measureContents.join('\n')}\n${indent}  }`);
 		}
 
-		staffStrings.push(`    \\new Staff = "${si}" <<\n${voiceLines.join('\n')}\n    >>`);
+		return `${indent}\\new Staff = "${staffId}" <<\n${voiceLines.join('\n')}\n${indent}>>`;
+	};
+
+	// Build music content for each part
+	const partStrings: string[] = [];
+
+	for (let pi = 0; pi < partCount; pi++) {
+		const staffMap = partVoices[pi];
+		const staffNums = Array.from(staffMap.keys()).sort((a, b) => a - b);
+
+		if (staffNums.length === 0) {
+			// Empty part, skip
+			continue;
+		}
+
+		const partIndex = pi + 1;  // 1-based part index
+
+		if (staffNums.length === 1) {
+			// Single staff part → standalone Staff
+			const staffNum = staffNums[0];
+			const measures = staffMap.get(staffNum)!;
+			const staffId = `${partIndex}_${staffNum}`;
+			const staffStr = buildStaffString(measures, staffId, '    ');
+			partStrings.push(staffStr);
+		} else {
+			// Multiple staves → GrandStaff
+			const staffStrings: string[] = [];
+			for (const staffNum of staffNums) {
+				const measures = staffMap.get(staffNum)!;
+				const staffId = `${partIndex}_${staffNum}`;
+				const staffStr = buildStaffString(measures, staffId, '      ');
+				staffStrings.push(staffStr);
+			}
+			partStrings.push(`    \\new GrandStaff <<\n${staffStrings.join('\n')}\n    >>`);
+		}
 	}
 
-	const musicContent = staffStrings.join('\n');
+	const musicContent = partStrings.join('\n');
+
+	// Determine outer wrapper
+	// - Single part with single staff → just Staff (no outer <<>>)
+	// - Single part with multiple staves → GrandStaff (no extra outer <<>>)
+	// - Multiple parts → outer <<>>
+	let scoreContent: string;
+	if (partCount === 1 && partStrings.length === 1) {
+		// Single part - use as-is (already has Staff or GrandStaff)
+		scoreContent = musicContent;
+	} else {
+		// Multiple parts - wrap in <<>>
+		scoreContent = `  <<\n${musicContent}\n  >>`;
+	}
 
 	// Build header
 	const headerContent = doc.metadata ? encodeMetadata(doc.metadata) : '  tagline = ##f';
@@ -769,7 +874,7 @@ export const encode = (doc: LilyletDoc, options: RenderOptions = {}): string =>
 	const paperWidth = typeof opts.paper?.width === 'number' ? `${opts.paper.width}\\mm` : opts.paper?.width || '210\\mm';
 	const paperHeight = typeof opts.paper?.height === 'number' ? `${opts.paper.height}\\mm` : opts.paper?.height || '297\\mm';
 
-	const lyDoc = `\\version "2.24.0"
+	const lyDoc = `\\version "2.22.0"
 
 \\language "english"
 
@@ -794,9 +899,7 @@ ${headerContent}
 }
 
 \\score {
-  \\new GrandStaff <<
-${musicContent}
-  >>
+${scoreContent}
 
   \\layout { }${opts.withMIDI ? '\n  \\midi { }' : ''}
 }

package/source/lilylet/meiEncoder.ts

@@ -60,7 +60,8 @@ const keyToFifths = (key?: { pitch: string; accidental?: Accidental; mode: strin
 
 	if (key.mode === 'minor') fifths -= 3;
 
-	return fifths;
+	// Clamp to valid range [-7, 7] since standard notation doesn't support more than 7 sharps/flats
+	return Math.max(-7, Math.min(7, fifths));
 };