@k-l-lambda/lilylet 0.1.49 → 0.1.50

package/source/lilylet/musicXmlEncoder.ts

@@ -37,11 +37,14 @@ import {
 	Fraction,
 } from "./types";
 
+import {
+	DIVISIONS,
+	DIVISION_TO_TYPE,
+	calculateDuration,
+} from "./musicXmlUtils";
 
-// === Constants and Reverse Mappings ===
 
-// Standard divisions per quarter note
-const DIVISIONS = 4;
+// === Constants and Reverse Mappings ===
 
 // Phonet to MusicXML step
 const PHONET_TO_STEP: Record<string, string> = {
@@ -63,19 +66,6 @@ const ACCIDENTAL_TO_ALTER: Record<string, number> = {
 	natural: 0,
 };
 
-// Division to MusicXML note type
-const DIVISION_TO_TYPE: Record<number, string> = {
-	0.5: 'breve',
-	1: 'whole',
-	2: 'half',
-	4: 'quarter',
-	8: 'eighth',
-	16: '16th',
-	32: '32nd',
-	64: '64th',
-	128: '128th',
-};
-
 // Key signature to fifths (major keys)
 const KEY_TO_FIFTHS: Record<string, number> = {
 	'c': 0,
@@ -161,34 +151,6 @@ const indent = (level: number): string => '  '.repeat(level);
 
 // === Encoding Functions ===
 
-/**
- * Calculate duration in MusicXML divisions
- */
-const calculateDuration = (duration: Duration): number => {
-	// Base duration: DIVISIONS * (4 / division)
-	// e.g., quarter (4) = DIVISIONS * 1 = 4
-	//       half (2) = DIVISIONS * 2 = 8
-	//       eighth (8) = DIVISIONS * 0.5 = 2
-	let dur = DIVISIONS * (4 / duration.division);
-
-	// Apply dots
-	if (duration.dots) {
-		let dotValue = dur / 2;
-		for (let i = 0; i < duration.dots; i++) {
-			dur += dotValue;
-			dotValue /= 2;
-		}
-	}
-
-	// Apply tuplet ratio
-	if (duration.tuplet) {
-		dur = dur * duration.tuplet.denominator / duration.tuplet.numerator;
-	}
-
-	return Math.round(dur);
-};
-
-
 /**
  * Encode pitch to MusicXML
  */
@@ -224,9 +186,12 @@ const encodeDuration = (duration: Duration, level: number): string => {
 	}
 
 	if (duration.tuplet) {
+		// MusicXML: actual-notes = notes played (Lilylet denominator)
+		//           normal-notes = normal count (Lilylet numerator)
+		// e.g., \times 2/3 → actual=3, normal=2
 		xml += `${indent(level)}<time-modification>\n`;
-		xml += `${indent(level + 1)}<actual-notes>${duration.tuplet.numerator}</actual-notes>\n`;
-		xml += `${indent(level + 1)}<normal-notes>${duration.tuplet.denominator}</normal-notes>\n`;
+		xml += `${indent(level + 1)}<actual-notes>${duration.tuplet.denominator}</actual-notes>\n`;
+		xml += `${indent(level + 1)}<normal-notes>${duration.tuplet.numerator}</normal-notes>\n`;
 		xml += `${indent(level)}</time-modification>\n`;
 	}
 
@@ -349,6 +314,10 @@ const encodeNotations = (marks: Mark[], level: number): string => {
 				otherNotations.push(`<slur type="${mark.start ? 'start' : 'stop'}" number="1"/>`);
 				break;
 
+			case 'tuplet' as any:
+				otherNotations.push(`<tuplet type="${(mark as any).start ? 'start' : 'stop'}"/>`);
+				break;
+
 			case 'fingering':
 				// Fingering goes in technical
 				break;
@@ -494,6 +463,49 @@ const encodeRest = (
 };
 
 
+/**
+ * Encode a rest event with tuplet notation start/stop
+ */
+const encodeRestWithTuplet = (
+	event: RestEvent,
+	voice: number,
+	staff: number,
+	level: number,
+	isFirst: boolean,
+	isLast: boolean
+): string => {
+	let xml = `${indent(level)}<note>\n`;
+
+	xml += `${indent(level + 1)}<rest`;
+	if (event.fullMeasure) {
+		xml += ' measure="yes"';
+	}
+	xml += '/>\n';
+
+	xml += encodeDuration(event.duration, level + 1);
+
+	xml += `${indent(level + 1)}<voice>${voice}</voice>\n`;
+
+	if (staff > 0) {
+		xml += `${indent(level + 1)}<staff>${staff}</staff>\n`;
+	}
+
+	// Add tuplet notations
+	xml += `${indent(level + 1)}<notations>\n`;
+	if (isFirst) {
+		xml += `${indent(level + 2)}<tuplet type="start"/>\n`;
+	}
+	if (isLast) {
+		xml += `${indent(level + 2)}<tuplet type="stop"/>\n`;
+	}
+	xml += `${indent(level + 1)}</notations>\n`;
+
+	xml += `${indent(level)}</note>\n`;
+
+	return xml;
+};
+
+
 /**
  * Encode direction element (dynamics, tempo, etc.)
  */
@@ -627,10 +639,11 @@ const encodeHarmony = (event: HarmonyEvent, level: number): string => {
 
 
 /**
- * Encode a complete measure
+ * Encode a complete measure for a single part
  */
 const encodeMeasure = (
 	measure: Measure,
+	partIndex: number,
 	measureNumber: number,
 	isFirst: boolean,
 	prevKey: KeySignature | undefined,
@@ -639,32 +652,33 @@ const encodeMeasure = (
 ): string => {
 	let xml = `${indent(level)}<measure number="${measureNumber}">\n`;
 
+	const part = measure.parts[partIndex];
+	if (!part) {
+		xml += `${indent(level)}</measure>\n`;
+		return xml;
+	}
+
 	// Determine if we need attributes
 	const needAttributes = isFirst ||
 		(measure.key && JSON.stringify(measure.key) !== JSON.stringify(prevKey)) ||
 		(measure.timeSig && JSON.stringify(measure.timeSig) !== JSON.stringify(prevTime));
 
-	// Find max staff number
+	// Find max staff number within this part
 	let maxStaff = 1;
-	for (const part of measure.parts) {
-		for (const voice of part.voices) {
-			maxStaff = Math.max(maxStaff, voice.staff || 1);
-		}
+	for (const voice of part.voices) {
+		maxStaff = Math.max(maxStaff, voice.staff || 1);
 	}
 
 	// Encode attributes if needed
 	if (needAttributes) {
-		// Find clef from first voice
+		// Find clef from first voice of this part
 		let clef: Clef | undefined;
-		for (const part of measure.parts) {
-			for (const voice of part.voices) {
-				for (const event of voice.events) {
-					if (event.type === 'context' && event.clef) {
-						clef = event.clef;
-						break;
-					}
+		for (const voice of part.voices) {
+			for (const event of voice.events) {
+				if (event.type === 'context' && event.clef) {
+					clef = event.clef;
+					break;
 				}
-				if (clef) break;
 			}
 			if (clef) break;
 		}
@@ -678,95 +692,124 @@ const encodeMeasure = (
 		});
 	}
 
-	// Encode voices
+	// Encode voices (voice numbering starts at 1 for each part)
 	let voiceNum = 1;
 	let currentPosition = 0;
 
-	for (const part of measure.parts) {
-		for (const voice of part.voices) {
-			const staff = voice.staff || 1;
-			let voicePosition = 0;
-
-			// Backup if needed
-			if (currentPosition > 0 && voiceNum > 1) {
-				xml += `${indent(level + 1)}<backup>\n`;
-				xml += `${indent(level + 2)}<duration>${currentPosition}</duration>\n`;
-				xml += `${indent(level + 1)}</backup>\n`;
-				voicePosition = 0;
-			}
+	for (const voice of part.voices) {
+		let currentStaff = voice.staff || 1;
+		let voicePosition = 0;
 
-			for (const event of voice.events) {
-				switch (event.type) {
-					case 'note': {
-						// Check for direction marks (dynamics, hairpins, pedals)
-						const directionMarks = event.marks?.filter(m =>
-							m.markType === 'dynamic' || m.markType === 'hairpin' || m.markType === 'pedal'
-						) || [];
-						if (directionMarks.length > 0) {
-							xml += encodeDirection(directionMarks, level + 1);
-						}
+		// Backup if needed
+		if (currentPosition > 0 && voiceNum > 1) {
+			xml += `${indent(level + 1)}<backup>\n`;
+			xml += `${indent(level + 2)}<duration>${currentPosition}</duration>\n`;
+			xml += `${indent(level + 1)}</backup>\n`;
+			voicePosition = 0;
+		}
 
-						// Encode main note
-						xml += encodeNote(event, voiceNum, staff, level + 1);
-						const dur = calculateDuration(event.duration);
-						voicePosition += dur;
-
-						// Encode chord notes
-						for (let i = 1; i < event.pitches.length; i++) {
-							const chordEvent: NoteEvent = {
-								...event,
-								pitches: [event.pitches[i]],
-							};
-							xml += encodeNote(chordEvent, voiceNum, staff, level + 1, true);
-						}
-						break;
+		for (const event of voice.events) {
+			switch (event.type) {
+				case 'note': {
+					// Check for direction marks (dynamics, hairpins, pedals)
+					const directionMarks = event.marks?.filter(m =>
+						m.markType === 'dynamic' || m.markType === 'hairpin' || m.markType === 'pedal'
+					) || [];
+					if (directionMarks.length > 0) {
+						xml += encodeDirection(directionMarks, level + 1);
 					}
 
-					case 'rest': {
-						xml += encodeRest(event, voiceNum, staff, level + 1);
-						const dur = calculateDuration(event.duration);
-						voicePosition += dur;
-						break;
+					// Encode main note
+					xml += encodeNote(event, voiceNum, currentStaff, level + 1);
+					const dur = calculateDuration(event.duration);
+					voicePosition += dur;
+
+					// Encode chord notes
+					for (let i = 1; i < event.pitches.length; i++) {
+						const chordEvent: NoteEvent = {
+							...event,
+							pitches: [event.pitches[i]],
+						};
+						xml += encodeNote(chordEvent, voiceNum, currentStaff, level + 1, true);
 					}
+					break;
+				}
 
-					case 'context': {
-						if (event.tempo) {
-							xml += encodeTempo(event.tempo, level + 1);
-						}
-						// Other context changes are handled in attributes
-						break;
+				case 'rest': {
+					xml += encodeRest(event, voiceNum, currentStaff, level + 1);
+					const dur = calculateDuration(event.duration);
+					voicePosition += dur;
+					break;
+				}
+
+				case 'context': {
+					if (event.tempo) {
+						xml += encodeTempo(event.tempo, level + 1);
+					}
+					if (event.staff) {
+						currentStaff = event.staff;
 					}
+					// Other context changes are handled in attributes
+					break;
+				}
 
-					case 'tuplet': {
-						for (const subEvent of event.events) {
-							if (subEvent.type === 'note') {
-								xml += encodeNote(subEvent, voiceNum, staff, level + 1);
-								const dur = calculateDuration(subEvent.duration);
-								voicePosition += dur;
-							} else if (subEvent.type === 'rest') {
-								xml += encodeRest(subEvent, voiceNum, staff, level + 1);
-								const dur = calculateDuration(subEvent.duration);
-								voicePosition += dur;
+				case 'tuplet': {
+					const tupletEvents = event.events;
+					for (let ti = 0; ti < tupletEvents.length; ti++) {
+						const subEvent = tupletEvents[ti];
+						// Set tuplet ratio on duration so encodeDuration emits <time-modification>
+						const originalTuplet = subEvent.duration.tuplet;
+						subEvent.duration.tuplet = event.ratio;
+
+						const isFirst = ti === 0;
+						const isLast = ti === tupletEvents.length - 1;
+
+						if (subEvent.type === 'note') {
+							// Add tuplet notation marks
+							const tupletMarks: Mark[] = [];
+							if (isFirst) tupletMarks.push({ markType: 'tuplet', start: true } as any);
+							if (isLast) tupletMarks.push({ markType: 'tuplet', start: false } as any);
+
+							if (tupletMarks.length > 0) {
+								const origMarks = subEvent.marks;
+								subEvent.marks = [...(subEvent.marks || []), ...tupletMarks];
+								xml += encodeNote(subEvent, voiceNum, currentStaff, level + 1);
+								subEvent.marks = origMarks;
+							} else {
+								xml += encodeNote(subEvent, voiceNum, currentStaff, level + 1);
 							}
+							const dur = calculateDuration(subEvent.duration);
+							voicePosition += dur;
+						} else if (subEvent.type === 'rest') {
+							if (isFirst || isLast) {
+								xml += encodeRestWithTuplet(subEvent, voiceNum, currentStaff, level + 1, isFirst, isLast);
+							} else {
+								xml += encodeRest(subEvent, voiceNum, currentStaff, level + 1);
+							}
+							const dur = calculateDuration(subEvent.duration);
+							voicePosition += dur;
 						}
-						break;
-					}
 
-					case 'barline': {
-						xml += encodeBarline(event, level + 1);
-						break;
+						// Restore original tuplet value
+						subEvent.duration.tuplet = originalTuplet;
 					}
+					break;
+				}
 
-					case 'harmony': {
-						xml += encodeHarmony(event, level + 1);
-						break;
-					}
+				case 'barline': {
+					xml += encodeBarline(event, level + 1);
+					break;
 				}
-			}
 
-			currentPosition = Math.max(currentPosition, voicePosition);
-			voiceNum++;
+				case 'harmony': {
+					xml += encodeHarmony(event, level + 1);
+					break;
+				}
+			}
 		}
+
+		currentPosition = Math.max(currentPosition, voicePosition);
+		voiceNum++;
 	}
 
 	xml += `${indent(level)}</measure>\n`;
@@ -823,30 +866,42 @@ export const encode = (doc: LilyletDoc): string => {
 		xml += encodeMetadata(doc.metadata, 1);
 	}
 
-	// Part list (single part for now)
+	// Determine number of parts from first measure
+	const numParts = doc.measures.length > 0 ? doc.measures[0].parts.length : 1;
+
+	// Part list
 	xml += `${indent(1)}<part-list>\n`;
-	xml += `${indent(2)}<score-part id="P1">\n`;
-	xml += `${indent(3)}<part-name>${doc.metadata?.title ? escapeXml(doc.metadata.title) : 'Music'}</part-name>\n`;
-	xml += `${indent(2)}</score-part>\n`;
+	for (let pi = 0; pi < numParts; pi++) {
+		const partId = `P${pi + 1}`;
+		const partName = doc.measures[0]?.parts[pi]?.name
+			|| (numParts === 1 ? (doc.metadata?.title ? escapeXml(doc.metadata.title) : 'Music') : `Part ${pi + 1}`);
+		xml += `${indent(2)}<score-part id="${partId}">\n`;
+		xml += `${indent(3)}<part-name>${escapeXml(partName)}</part-name>\n`;
+		xml += `${indent(2)}</score-part>\n`;
+	}
 	xml += `${indent(1)}</part-list>\n`;
 
-	// Part content
-	xml += `${indent(1)}<part id="P1">\n`;
+	// Encode each part
+	for (let pi = 0; pi < numParts; pi++) {
+		const partId = `P${pi + 1}`;
+		xml += `${indent(1)}<part id="${partId}">\n`;
 
-	let prevKey: KeySignature | undefined;
-	let prevTime: Fraction | undefined;
+		let prevKey: KeySignature | undefined;
+		let prevTime: Fraction | undefined;
 
-	for (let i = 0; i < doc.measures.length; i++) {
-		const measure = doc.measures[i];
-		const isFirst = i === 0;
+		for (let i = 0; i < doc.measures.length; i++) {
+			const measure = doc.measures[i];
+			const isFirst = i === 0;
 
-		xml += encodeMeasure(measure, i + 1, isFirst, prevKey, prevTime, 2);
+			xml += encodeMeasure(measure, pi, i + 1, isFirst, prevKey, prevTime, 2);
+
+			if (measure.key) prevKey = measure.key;
+			if (measure.timeSig) prevTime = measure.timeSig;
+		}
 
-		if (measure.key) prevKey = measure.key;
-		if (measure.timeSig) prevTime = measure.timeSig;
+		xml += `${indent(1)}</part>\n`;
 	}
 
-	xml += `${indent(1)}</part>\n`;
 	xml += '</score-partwise>\n';
 
 	return xml;

package/source/lilylet/musicXmlUtils.ts

@@ -158,10 +158,13 @@ export const convertPitch = (
 	};
 };
 
-// ============ Duration Conversion ============
+// ============ Duration Constants & Mappings ============
+
+// Standard divisions per quarter note (shared by encoder/decoder)
+export const DIVISIONS = 4;
 
 // MusicXML note type to division (1=whole, 2=half, 4=quarter, etc.)
-const TYPE_TO_DIVISION: Record<string, number> = {
+export const TYPE_TO_DIVISION: Record<string, number> = {
 	maxima: 0.125,
 	long: 0.25,
 	breve: 0.5,
@@ -178,6 +181,43 @@ const TYPE_TO_DIVISION: Record<string, number> = {
 	'1024th': 1024,
 };
 
+// Division to MusicXML note type (inverse of TYPE_TO_DIVISION)
+export const DIVISION_TO_TYPE: Record<number, string> = Object.fromEntries(
+	Object.entries(TYPE_TO_DIVISION).map(([type, div]) => [div, type])
+);
+
+/**
+ * Calculate duration in MusicXML divisions.
+ * Shared by encoder (with DIVISIONS=4) and potentially decoder.
+ *
+ * Duration.tuplet is in Lilylet ratio semantics:
+ *   \times 2/3 → {numerator:2, denominator:3} → multiply by 2/3
+ */
+export const calculateDuration = (duration: Duration, divisions: number = DIVISIONS): number => {
+	// Base duration: divisions * (4 / division)
+	// e.g., quarter (4) = divisions * 1
+	//       half (2) = divisions * 2
+	//       eighth (8) = divisions * 0.5
+	let dur = divisions * (4 / duration.division);
+
+	// Apply dots
+	if (duration.dots) {
+		let dotValue = dur / 2;
+		for (let i = 0; i < duration.dots; i++) {
+			dur += dotValue;
+			dotValue /= 2;
+		}
+	}
+
+	// Apply tuplet ratio: Lilylet ratio num/den means multiply by num/den
+	// e.g., \times 2/3 means each note's actual duration = written * 2/3
+	if (duration.tuplet) {
+		dur = dur * duration.tuplet.numerator / duration.tuplet.denominator;
+	}
+
+	return Math.round(dur);
+};
+
 /**
  * Convert MusicXML duration to Lilylet Duration
  *
@@ -218,9 +258,11 @@ export const convertDuration = (
 	};
 
 	if (timeModification) {
+		// Store as Lilylet ratio: normalNotes/actualNotes
+		// MusicXML actual=3, normal=2 (triplet) → Lilylet ratio {num:2, den:3}
 		result.tuplet = {
-			numerator: timeModification.actualNotes,
-			denominator: timeModification.normalNotes,
+			numerator: timeModification.normalNotes,
+			denominator: timeModification.actualNotes,
 		};
 	}
 

package/source/lilylet/serializer.ts

@@ -771,6 +771,9 @@ const serializeMetadata = (metadata: any): string => {
 	if (metadata.lyricist) {
 		lines.push('[lyricist "' + escapeString(metadata.lyricist) + '"]');
 	}
+	if (metadata.autoBeam) {
+		lines.push('[auto-beam "' + escapeString(metadata.autoBeam) + '"]');
+	}
 
 	return lines.join('\n');
 };

package/source/lilylet/types.ts

@@ -286,6 +286,7 @@ export interface Metadata {
 	opus?: string;
 	instrument?: string;
 	genre?: string;
+	autoBeam?: 'auto' | 'on' | 'off';
 }
 
 // Part within a measure: can be a single staff or grand staff (multiple staves)