@k-l-lambda/lilylet 0.1.49 → 0.1.51

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

@@ -31,6 +31,7 @@ import {
 	PedalType,
 	Tempo,
 	Placement,
+	Metadata,
 } from "./types";
 
 
@@ -259,6 +260,9 @@ const serializeMarks = (marks: Mark[]): string => {
 				if (pedalStr) parts.push(pedalStr);
 				break;
 			}
+			case 'fingering':
+				parts.push('-' + mark.finger);
+				break;
 		}
 	}
 
@@ -584,14 +588,16 @@ const findVoiceClef = (voice: Voice): Clef | undefined => {
 // Takes currentStaff (what parser thinks staff is) and returns { str, newStaff }
 // If isGrandStaff is true, always output \staff command for clarity
 // measureContext provides key/time for first voice
-// staffClef is the clef for this voice's staff (tracked across measures)
+// allStaffClefs is the clef map for all staves (tracked across measures)
+// emittedClefs tracks which clefs have already been output (avoids duplicates)
 const serializeVoice = (
 	voice: Voice,
 	currentStaff: number,
 	isGrandStaff: boolean = false,
 	measureContext?: MeasureContext,
 	isFirstVoice: boolean = false,
-	staffClef?: Clef
+	allStaffClefs?: Record<number, Clef>,
+	emittedClefs?: Record<number, Clef>
 ): { str: string; newStaff: number } => {
 	const parts: string[] = [];
 	let prevDuration: Duration | undefined;
@@ -625,25 +631,63 @@ const serializeVoice = (
 		}
 	}
 
-	// Output clef for every voice (use staff clef tracked across measures, or find from voice events)
-	const voiceClef = staffClef || findVoiceClef(voice);
-	if (voiceClef) {
+	// Output clef only if not yet emitted or changed for this staff
+	const voiceClef = allStaffClefs?.[voice.staff] || findVoiceClef(voice);
+	const clefAlreadyEmitted = voiceClef && emittedClefs?.[voice.staff] === voiceClef;
+	if (voiceClef && !clefAlreadyEmitted) {
 		parts.push('\\clef "' + CLEF_MAP[voiceClef] + '"');
+		if (emittedClefs) emittedClefs[voice.staff] = voiceClef;
 	}
+	// Skip redundant clef context events if this staff's clef is already established
+	const clefOutputted = !!voiceClef && !!emittedClefs?.[voice.staff];
 
-	// Track if we've already output the clef to avoid duplication
-	let clefOutputted = !!voiceClef;
+	let activeStaff = voice.staff;
+	let activeStemDir: StemDirection | undefined;
 
 	for (const event of voice.events) {
-		// Skip clef context events if we've already output the clef at the beginning
-		if (clefOutputted && event.type === 'context') {
+		if (event.type === 'context') {
 			const ctx = event as ContextChange;
-			if (ctx.clef && !ctx.key && !ctx.time && !ctx.ottava && !ctx.stemDirection && !ctx.tempo && !ctx.staff) {
-				// This is a clef-only context event, skip it
+			// Skip context events that belong to a different staff (cross-staff clef/ottava)
+			if (ctx.staff && ctx.staff !== voice.staff) {
+				continue;
+			}
+			// Skip clef-only context events if clef already established for this staff
+			if (clefOutputted && ctx.clef && !ctx.key && !ctx.time && !ctx.ottava && !ctx.stemDirection && !ctx.tempo) {
 				continue;
 			}
 		}
 
+		if (event.type === 'note') {
+			const noteEvt = event as NoteEvent;
+
+			// Cross-staff: emit \staff when note's effective staff differs from active
+			const effectiveStaff = noteEvt.staff || voice.staff;
+			if (effectiveStaff !== activeStaff) {
+				activeStaff = effectiveStaff;
+				parts.push('\\staff "' + activeStaff + '"');
+				// Emit the target staff's clef if it differs from what was last emitted for this staff
+				const targetClef = allStaffClefs?.[activeStaff];
+				if (targetClef && emittedClefs?.[activeStaff] !== targetClef) {
+					parts.push('\\clef "' + CLEF_MAP[targetClef] + '"');
+					if (emittedClefs) emittedClefs[activeStaff] = targetClef;
+				}
+			}
+
+			// Stem direction: emit \stemUp/\stemDown/\stemNeutral on change
+			const stemDir = noteEvt.stemDirection;
+			if (stemDir !== activeStemDir) {
+				if (stemDir === StemDirection.up) {
+					parts.push('\\stemUp');
+				} else if (stemDir === StemDirection.down) {
+					parts.push('\\stemDown');
+				} else if (activeStemDir) {
+					// Was set, now undefined → reset to neutral
+					parts.push('\\stemNeutral');
+				}
+				activeStemDir = stemDir;
+			}
+		}
+
 		const { str: eventStr, newEnv } = serializeEvent(event, pitchEnv, prevDuration);
 		pitchEnv = newEnv;
 
@@ -656,6 +700,9 @@ const serializeVoice = (
 			prevDuration = (event as NoteEvent).duration;
 		} else if (event.type === 'rest') {
 			prevDuration = (event as RestEvent).duration;
+		} else if (event.type === 'context' && (event as ContextChange).clef && emittedClefs) {
+			const ctx = event as ContextChange;
+			emittedClefs[ctx.staff || activeStaff] = ctx.clef!;
 		}
 	}
 
@@ -671,7 +718,8 @@ const serializePart = (
 	isGrandStaff: boolean = false,
 	measureContext?: MeasureContext,
 	isFirstPart: boolean = false,
-	clefsByStaff?: Record<number, Clef>
+	clefsByStaff?: Record<number, Clef>,
+	emittedClefs?: Record<number, Clef>
 ): { str: string; newStaff: number } => {
 	if (part.voices.length === 0) {
 		return { str: '', newStaff: currentStaff };
@@ -683,10 +731,8 @@ const serializePart = (
 	for (let i = 0; i < part.voices.length; i++) {
 		const voice = part.voices[i];
 		// Pass measureContext to all voices, isFirstVoice for key/time
-		// Pass staff clef from clefsByStaff map
 		const isFirstVoice = isFirstPart && i === 0;
-		const staffClef = clefsByStaff?.[voice.staff];
-		const { str, newStaff } = serializeVoice(voice, staff, isGrandStaff, measureContext, isFirstVoice, staffClef);
+		const { str, newStaff } = serializeVoice(voice, staff, isGrandStaff, measureContext, isFirstVoice, clefsByStaff, emittedClefs);
 		voiceStrs.push(str);
 		staff = newStaff;
 	}
@@ -705,7 +751,8 @@ const serializeMeasure = (
 	isGrandStaff: boolean = false,
 	currentKey?: KeySignature,
 	currentTime?: { numerator: number; denominator: number; symbol?: 'common' | 'cut' },
-	staffClefs?: Record<number, Clef>
+	staffClefs?: Record<number, Clef>,
+	emittedClefs?: Record<number, Clef>
 ): { str: string; newStaff: number } => {
 	const parts: string[] = [];
 
@@ -723,7 +770,7 @@ const serializeMeasure = (
 	// Parts
 	let staff = currentStaff;
 	if (measure.parts.length === 1) {
-		const { str: partStr, newStaff } = serializePart(measure.parts[0], staff, isGrandStaff, measureContext, true, clefsByStaff);
+		const { str: partStr, newStaff } = serializePart(measure.parts[0], staff, isGrandStaff, measureContext, true, clefsByStaff, emittedClefs);
 		if (partStr) {
 			parts.push(partStr);
 		}
@@ -734,7 +781,7 @@ const serializeMeasure = (
 		for (let i = 0; i < measure.parts.length; i++) {
 			const part = measure.parts[i];
 			// Pass measureContext to all parts, isFirstPart to first part only
-			const { str, newStaff } = serializePart(part, staff, isGrandStaff, measureContext, i === 0, clefsByStaff);
+			const { str, newStaff } = serializePart(part, staff, isGrandStaff, measureContext, i === 0, clefsByStaff, emittedClefs);
 			if (str) {
 				partStrs.push(str);
 			}
@@ -753,7 +800,7 @@ const escapeString = (str: string): string => {
 };
 
 // Serialize metadata
-const serializeMetadata = (metadata: any): string => {
+const serializeMetadata = (metadata: Metadata): string => {
 	const lines: string[] = [];
 
 	if (metadata.title) {
@@ -771,6 +818,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');
 };
@@ -806,6 +856,7 @@ export const serializeLilyletDoc = (doc: LilyletDoc): string => {
 	let currentKey: KeySignature | undefined;
 	let currentTime: { numerator: number; denominator: number; symbol?: 'common' | 'cut' } | undefined;
 	const staffClefs: Record<number, Clef> = {}; // Track clef per staff
+	const emittedClefs: Record<number, Clef> = {}; // Track which clefs have been output
 
 	for (let i = 0; i < doc.measures.length; i++) {
 		const measure = doc.measures[i];
@@ -822,13 +873,16 @@ export const serializeLilyletDoc = (doc: LilyletDoc): string => {
 			for (const voice of part.voices) {
 				for (const event of voice.events) {
 					if (event.type === 'context' && (event as ContextChange).clef) {
-						staffClefs[voice.staff] = (event as ContextChange).clef!;
+						const ctx = event as ContextChange;
+						// Use the event's staff if specified (cross-staff), otherwise the voice's staff
+						const clefStaff = ctx.staff || voice.staff;
+						staffClefs[clefStaff] = ctx.clef!;
 					}
 				}
 			}
 		}
 
-		const { str: measureStr, newStaff } = serializeMeasure(measure, i === 0, currentStaff, isGrandStaff, currentKey, currentTime, staffClefs);
+		const { str: measureStr, newStaff } = serializeMeasure(measure, i === 0, currentStaff, isGrandStaff, currentKey, currentTime, staffClefs, emittedClefs);
 		// Always include measure, even if empty (use space rest for empty measures)
 		measureStrs.push(measureStr || 's1');
 		currentStaff = newStaff;

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)