@k-l-lambda/lilylet 0.1.32 → 0.1.34

package/lib/meiEncoder.js

@@ -470,14 +470,13 @@ const restEventToMEI = (event, indent, keyFifths = 0, ottavaShift = 0) => {
     return `${indent}<rest ${attrs} />\n`;
 };
 // Convert TupletEvent to MEI
-const tupletEventToMEI = (event, indent, layerStaff, keyFifths = 0, currentStaff, ottavaShift = 0) => {
+const tupletEventToMEI = (event, indent, layerStaff, keyFifths = 0, currentStaff, ottavaShift = 0, inParentBeam = false) => {
     // LilyPond \times 2/3 means "multiply duration by 2/3"
     // So 3 notes × 2/3 = 2 beats worth (3 in time of 2)
     // MEI: num = number of notes written, numbase = normal equivalent
     const num = event.ratio.denominator; // denominator = actual note count
     const numbase = event.ratio.numerator; // numerator = time equivalent
     let xml = `${indent}<tuplet xml:id="${generateId('tuplet')}" num="${num}" numbase="${numbase}">\n`;
-    let inBeam = false;
     const baseIndent = indent + '    ';
     // Effective staff for cross-staff notation
     const effectiveStaff = currentStaff ?? layerStaff;
@@ -490,28 +489,17 @@ const tupletEventToMEI = (event, indent, layerStaff, keyFifths = 0, currentStaff
     const mordents = [];
     const turns = [];
     const arpeggios = [];
+    // If we're inside a parent beam, don't create internal beams - notes go directly into tuplet
+    // MEI allows: <beam><tuplet><note/>...</tuplet><tuplet><note/>...</tuplet></beam>
+    // Beam state is managed by encodeLayer, not here.
     for (const e of event.events) {
-        // Check for beam marks in note events
-        let beamStart = false;
-        let beamEnd = false;
-        if (e.type === 'note') {
-            const markOptions = extractMarkOptions(e.marks);
-            beamStart = markOptions.beamStart;
-            beamEnd = markOptions.beamEnd;
-        }
-        // Open beam element if beam starts
-        if (beamStart && !inBeam) {
-            xml += `${baseIndent}<beam xml:id="${generateId('beam')}">\n`;
-            inBeam = true;
-        }
-        const currentIndent = inBeam ? baseIndent + '    ' : baseIndent;
         if (e.type === 'note') {
             // For cross-staff notation: set note's staff if different from layerStaff
             const noteEvent = e;
             const effectiveNoteEvent = effectiveStaff && layerStaff && effectiveStaff !== layerStaff
                 ? { ...noteEvent, staff: effectiveStaff }
                 : noteEvent;
-            const result = noteEventToMEI(effectiveNoteEvent, currentIndent, layerStaff, false, undefined, keyFifths, ottavaShift);
+            const result = noteEventToMEI(effectiveNoteEvent, baseIndent, layerStaff, false, undefined, keyFifths, ottavaShift);
             xml += result.xml;
             // Collect slur info
             if (result.slurStart)
@@ -533,18 +521,9 @@ const tupletEventToMEI = (event, indent, layerStaff, keyFifths = 0, currentStaff
                 arpeggios.push({ plist: result.elementId });
         }
         else if (e.type === 'rest') {
-            xml += restEventToMEI(e, currentIndent, keyFifths, ottavaShift);
-        }
-        // Close beam element if beam ends
-        if (beamEnd && inBeam) {
-            xml += `${baseIndent}</beam>\n`;
-            inBeam = false;
+            xml += restEventToMEI(e, baseIndent, keyFifths, ottavaShift);
         }
     }
-    // Close any unclosed beam
-    if (inBeam) {
-        xml += `${baseIndent}</beam>\n`;
-    }
     xml += `${indent}</tuplet>\n`;
     return { xml, slurStarts, slurEnds, dynamics, fermatas, trills, mordents, turns, arpeggios };
 };
@@ -615,11 +594,34 @@ const tremoloEventToMEI = (event, indent, keyFifths = 0, ottavaShift = 0) => {
     result += `${indent}</fTrem>\n`;
     return result;
 };
+// Helper: check if an event (or any note inside a tuplet) has beam start/end
+const getEventBeamMarks = (event) => {
+    if (event.type === 'note') {
+        const markOptions = extractMarkOptions(event.marks);
+        return { beamStart: markOptions.beamStart, beamEnd: markOptions.beamEnd };
+    }
+    if (event.type === 'tuplet') {
+        const tuplet = event;
+        let beamStart = false;
+        let beamEnd = false;
+        for (const e of tuplet.events) {
+            if (e.type === 'note') {
+                const markOptions = extractMarkOptions(e.marks);
+                if (markOptions.beamStart)
+                    beamStart = true;
+                if (markOptions.beamEnd)
+                    beamEnd = true;
+            }
+        }
+        return { beamStart, beamEnd };
+    }
+    return { beamStart: false, beamEnd: false };
+};
 // Encode a layer (voice)
 const encodeLayer = (voice, layerN, indent, initialTiePitches = [], keyFifths = 0, initialClef, initialSlur = null, initialHairpin = null) => {
     const layerId = generateId("layer");
     let xml = `${indent}<layer xml:id="${layerId}" n="${layerN}">\n`;
-    let inBeam = false;
+    let beamElementOpen = false; // Whether actual <beam> element is open (passed to tuplets)
     const baseIndent = indent + '    ';
     // Track current clef to only emit changes
     let currentClef = initialClef;
@@ -667,21 +669,14 @@ const encodeLayer = (voice, layerN, indent, initialTiePitches = [], keyFifths =
         return true;
     };
     for (const event of voice.events) {
-        // Check for beam start/end in note events
-        let beamStart = false;
-        let beamEnd = false;
-        if (event.type === 'note') {
-            const noteEvent = event;
-            const markOptions = extractMarkOptions(noteEvent.marks);
-            beamStart = markOptions.beamStart;
-            beamEnd = markOptions.beamEnd;
-        }
+        // Check for beam start/end in this event (including inside tuplets)
+        const { beamStart, beamEnd } = getEventBeamMarks(event);
         // Open beam element if beam starts
-        if (beamStart && !inBeam) {
+        if (beamStart && !beamElementOpen) {
             xml += `${baseIndent}<beam xml:id="${generateId('beam')}">\n`;
-            inBeam = true;
+            beamElementOpen = true;
         }
-        const currentIndent = inBeam ? baseIndent + '    ' : baseIndent;
+        const currentIndent = beamElementOpen ? baseIndent + '    ' : baseIndent;
         switch (event.type) {
             case 'note': {
                 const noteEvent = event;
@@ -790,7 +785,9 @@ const encodeLayer = (voice, layerN, indent, initialTiePitches = [], keyFifths =
                 xml += restEventToMEI(event, currentIndent, keyFifths, currentOttavaShift);
                 break;
             case 'tuplet': {
-                const tupletResult = tupletEventToMEI(event, currentIndent, voice.staff, keyFifths, currentStaff, currentOttavaShift);
+                // Tuplet can be nested inside beam in MEI: <beam><tuplet>...</tuplet></beam>
+                // Pass beamElementOpen to tuplet so it knows not to create its own beam
+                const tupletResult = tupletEventToMEI(event, currentIndent, voice.staff, keyFifths, currentStaff, currentOttavaShift, beamElementOpen);
                 xml += tupletResult.xml;
                 // Process slur ends first (to close any pending slurs from before this tuplet)
                 for (const endId of tupletResult.slurEnds) {
@@ -883,13 +880,13 @@ const encodeLayer = (voice, layerN, indent, initialTiePitches = [], keyFifths =
                 break;
         }
         // Close beam element if beam ends
-        if (beamEnd && inBeam) {
+        if (beamEnd && beamElementOpen) {
             xml += `${baseIndent}</beam>\n`;
-            inBeam = false;
+            beamElementOpen = false;
         }
     }
     // Close any unclosed beam
-    if (inBeam) {
+    if (beamElementOpen) {
         xml += `${baseIndent}</beam>\n`;
     }
     // Close any unclosed ottava span at end of layer
@@ -1374,9 +1371,15 @@ const encode = (doc, options = {}) => {
     }
     // Encode measures
     measures.forEach((measure, mi) => {
-        // Update key signature if measure has one
+        // Check for key signature change and output scoreDef if needed
         if (measure.key) {
-            currentKey = keyToFifths(measure.key);
+            const newKey = keyToFifths(measure.key);
+            if (newKey !== currentKey) {
+                currentKey = newKey;
+                const newKeySig = KEY_SIGS[currentKey] || "0";
+                // Output a scoreDef with the new key signature
+                mei += `${indent}${indent}${indent}${indent}${indent}${indent}<scoreDef xml:id="${generateId('scoredef')}" key.sig="${newKeySig}" />\n`;
+            }
         }
         mei += encodeMeasure(measure, mi + 1, `${indent}${indent}${indent}${indent}${indent}${indent}`, totalStaves, tieState, slurState, hairpinState, currentKey, partInfos, clefState);
     });

package/lib/musicXmlDecoder.js

@@ -60,6 +60,75 @@ class SpannerTracker {
         this.ties.clear();
     }
 }
+// ============ Tuplet Tracker ============
+/**
+ * Track tuplet groups by number attribute.
+ * Collects notes between tuplet start and stop to create TupletEvent.
+ */
+class TupletTracker {
+    // Map from tuplet number to collected events and ratio
+    activeTuplets = new Map();
+    /**
+     * Start a new tuplet group
+     */
+    startTuplet(number = 1) {
+        this.activeTuplets.set(number, { events: [] });
+    }
+    /**
+     * Add an event to active tuplet(s)
+     * Returns true if the event was added to at least one tuplet
+     */
+    addEvent(event) {
+        if (this.activeTuplets.size === 0)
+            return false;
+        // Add to all active tuplets (in case of nested tuplets)
+        for (const [, tuplet] of this.activeTuplets) {
+            // Set ratio from first event's duration.tuplet
+            if (!tuplet.ratio && event.duration.tuplet) {
+                // In Lilylet, ratio is denominator/numerator (e.g., 2/3 for triplet)
+                tuplet.ratio = {
+                    numerator: event.duration.tuplet.denominator,
+                    denominator: event.duration.tuplet.numerator,
+                };
+            }
+            // Store event without tuplet info in duration (it's handled at TupletEvent level)
+            const cleanEvent = { ...event, duration: { ...event.duration } };
+            delete cleanEvent.duration.tuplet;
+            tuplet.events.push(cleanEvent);
+        }
+        return true;
+    }
+    /**
+     * Stop a tuplet group and return the TupletEvent
+     */
+    stopTuplet(number = 1) {
+        const tuplet = this.activeTuplets.get(number);
+        if (!tuplet || tuplet.events.length === 0) {
+            this.activeTuplets.delete(number);
+            return undefined;
+        }
+        this.activeTuplets.delete(number);
+        // Default ratio if not set (shouldn't happen normally)
+        const ratio = tuplet.ratio || { numerator: 2, denominator: 3 };
+        return {
+            type: 'tuplet',
+            ratio,
+            events: tuplet.events,
+        };
+    }
+    /**
+     * Check if any tuplet is active
+     */
+    isActive() {
+        return this.activeTuplets.size > 0;
+    }
+    /**
+     * Reset tracker
+     */
+    reset() {
+        this.activeTuplets.clear();
+    }
+}
 class VoiceTracker {
     voices = new Map();
     currentPosition = 0;
@@ -737,7 +806,7 @@ const directionToMarks = (direction, spannerTracker) => {
 /**
  * Convert a MusicXML measure to Lilylet events, grouped by voice
  */
-const convertMeasure = (measureEl, voiceTracker, spannerTracker, ottavaTracker) => {
+const convertMeasure = (measureEl, voiceTracker, spannerTracker, ottavaTracker, tupletTracker) => {
     let key;
     let timeSig;
     let barline;
@@ -782,6 +851,11 @@ const convertMeasure = (measureEl, voiceTracker, spannerTracker, ottavaTracker)
             const voiceNum = note.voice;
             const staffNum = note.staff || 1;
             currentVoice = voiceNum;
+            // Check for tuplet start BEFORE processing the note
+            const tupletNotation = note.notations?.tuplet;
+            if (tupletNotation?.type === 'start') {
+                tupletTracker.startTuplet(tupletNotation.number);
+            }
             // Add any pending context changes before the note (tempo, ottava)
             if (pendingContextChanges.length > 0) {
                 for (const ctx of pendingContextChanges) {
@@ -801,7 +875,13 @@ const convertMeasure = (measureEl, voiceTracker, spannerTracker, ottavaTracker)
                 };
                 // Grace notes don't advance time
                 const advanceDuration = note.isGrace ? 0 : note.duration.divisions;
-                voiceTracker.addEvent(voiceNum, restEvent, advanceDuration, staffNum);
+                // Check if we're in a tuplet
+                if (tupletTracker.isActive()) {
+                    tupletTracker.addEvent(restEvent);
+                }
+                else {
+                    voiceTracker.addEvent(voiceNum, restEvent, advanceDuration, staffNum);
+                }
             }
             else if (note.pitch) {
                 // Note or chord - convert MusicXmlPitch to Lilylet Pitch
@@ -858,7 +938,30 @@ const convertMeasure = (measureEl, voiceTracker, spannerTracker, ottavaTracker)
                 }
                 // Grace notes don't advance time
                 const advanceDuration = note.isGrace ? 0 : note.duration.divisions;
-                voiceTracker.addEvent(voiceNum, noteEvent, advanceDuration, staffNum);
+                // Check if we're in a tuplet
+                if (tupletTracker.isActive()) {
+                    tupletTracker.addEvent(noteEvent);
+                }
+                else {
+                    voiceTracker.addEvent(voiceNum, noteEvent, advanceDuration, staffNum);
+                }
+            }
+            // Check for tuplet stop AFTER processing the note
+            if (tupletNotation?.type === 'stop') {
+                const tupletEvent = tupletTracker.stopTuplet(tupletNotation.number);
+                if (tupletEvent) {
+                    // Calculate total duration of tuplet for voiceTracker
+                    let totalDuration = 0;
+                    for (const evt of tupletEvent.events) {
+                        if (evt.duration) {
+                            // Convert division to duration units (quarter = 1)
+                            totalDuration += (4 / evt.duration.division) * voiceTracker.getDivisions();
+                        }
+                    }
+                    // Apply tuplet ratio to get actual duration
+                    totalDuration = totalDuration * tupletEvent.ratio.numerator / tupletEvent.ratio.denominator;
+                    voiceTracker.addEvent(voiceNum, tupletEvent, totalDuration, staffNum);
+                }
             }
         }
         else if (tagName === 'direction') {
@@ -917,6 +1020,7 @@ const convertPart = (partEl) => {
     const voiceTracker = new VoiceTracker();
     const spannerTracker = new SpannerTracker();
     const ottavaTracker = { current: 0 };
+    const tupletTracker = new TupletTracker();
     let lastKey;
     let lastTimeSig;
     let isFirstMeasure = true;
@@ -924,7 +1028,7 @@ const convertPart = (partEl) => {
     const measureEls = getDirectChildren(partEl, 'measure');
     for (const measureEl of measureEls) {
         voiceTracker.reset();
-        const { voiceMap, key, timeSig, barline, harmonies, clefs } = convertMeasure(measureEl, voiceTracker, spannerTracker, ottavaTracker);
+        const { voiceMap, key, timeSig, barline, harmonies, clefs } = convertMeasure(measureEl, voiceTracker, spannerTracker, ottavaTracker, tupletTracker);
         // Update running key/time
         if (key)
             lastKey = key;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k-l-lambda/lilylet",
-  "version": "0.1.32",
+  "version": "0.1.34",
   "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",

package/source/lilylet/meiEncoder.ts

@@ -609,7 +609,7 @@ interface TupletEventResult {
 }
 
 // Convert TupletEvent to MEI
-const tupletEventToMEI = (event: TupletEvent, indent: string, layerStaff?: number, keyFifths: number = 0, currentStaff?: number, ottavaShift: number = 0): TupletEventResult => {
+const tupletEventToMEI = (event: TupletEvent, indent: string, layerStaff?: number, keyFifths: number = 0, currentStaff?: number, ottavaShift: number = 0, inParentBeam: boolean = false): TupletEventResult => {
 	// LilyPond \times 2/3 means "multiply duration by 2/3"
 	// So 3 notes × 2/3 = 2 beats worth (3 in time of 2)
 	// MEI: num = number of notes written, numbase = normal equivalent
@@ -618,7 +618,6 @@ const tupletEventToMEI = (event: TupletEvent, indent: string, layerStaff?: numbe
 
 	let xml = `${indent}<tuplet xml:id="${generateId('tuplet')}" num="${num}" numbase="${numbase}">\n`;
 
-	let inBeam = false;
 	const baseIndent = indent + '    ';
 
 	// Effective staff for cross-staff notation
@@ -634,31 +633,18 @@ const tupletEventToMEI = (event: TupletEvent, indent: string, layerStaff?: numbe
 	const turns: TurnRef[] = [];
 	const arpeggios: ArpegRef[] = [];
 
-	for (const e of event.events) {
-		// Check for beam marks in note events
-		let beamStart = false;
-		let beamEnd = false;
-		if (e.type === 'note') {
-			const markOptions = extractMarkOptions((e as NoteEvent).marks);
-			beamStart = markOptions.beamStart;
-			beamEnd = markOptions.beamEnd;
-		}
-
-		// Open beam element if beam starts
-		if (beamStart && !inBeam) {
-			xml += `${baseIndent}<beam xml:id="${generateId('beam')}">\n`;
-			inBeam = true;
-		}
-
-		const currentIndent = inBeam ? baseIndent + '    ' : baseIndent;
+	// If we're inside a parent beam, don't create internal beams - notes go directly into tuplet
+	// MEI allows: <beam><tuplet><note/>...</tuplet><tuplet><note/>...</tuplet></beam>
+	// Beam state is managed by encodeLayer, not here.
 
+	for (const e of event.events) {
 		if (e.type === 'note') {
 			// For cross-staff notation: set note's staff if different from layerStaff
 			const noteEvent = e as NoteEvent;
 			const effectiveNoteEvent = effectiveStaff && layerStaff && effectiveStaff !== layerStaff
 				? { ...noteEvent, staff: effectiveStaff }
 				: noteEvent;
-			const result = noteEventToMEI(effectiveNoteEvent, currentIndent, layerStaff, false, undefined, keyFifths, ottavaShift);
+			const result = noteEventToMEI(effectiveNoteEvent, baseIndent, layerStaff, false, undefined, keyFifths, ottavaShift);
 			xml += result.xml;
 
 			// Collect slur info
@@ -673,21 +659,10 @@ const tupletEventToMEI = (event: TupletEvent, indent: string, layerStaff?: numbe
 			if (result.turn) turns.push({ startid: result.elementId });
 			if (result.arpeggio) arpeggios.push({ plist: result.elementId });
 		} else if (e.type === 'rest') {
-			xml += restEventToMEI(e as RestEvent, currentIndent, keyFifths, ottavaShift);
-		}
-
-		// Close beam element if beam ends
-		if (beamEnd && inBeam) {
-			xml += `${baseIndent}</beam>\n`;
-			inBeam = false;
+			xml += restEventToMEI(e as RestEvent, baseIndent, keyFifths, ottavaShift);
 		}
 	}
 
-	// Close any unclosed beam
-	if (inBeam) {
-		xml += `${baseIndent}</beam>\n`;
-	}
-
 	xml += `${indent}</tuplet>\n`;
 	return { xml, slurStarts, slurEnds, dynamics, fermatas, trills, mordents, turns, arpeggios };
 };
@@ -865,12 +840,35 @@ interface LayerResult {
 	endingClef?: Clef;  // For cross-measure clef tracking
 }
 
+
+// Helper: check if an event (or any note inside a tuplet) has beam start/end
+const getEventBeamMarks = (event: NoteEvent | RestEvent | TupletEvent | TremoloEvent | ContextChange | BarlineEvent | HarmonyEvent | MarkupEvent | { type: 'pitchReset' }): { beamStart: boolean; beamEnd: boolean } => {
+	if (event.type === 'note') {
+		const markOptions = extractMarkOptions((event as NoteEvent).marks);
+		return { beamStart: markOptions.beamStart, beamEnd: markOptions.beamEnd };
+	}
+	if (event.type === 'tuplet') {
+		const tuplet = event as TupletEvent;
+		let beamStart = false;
+		let beamEnd = false;
+		for (const e of tuplet.events) {
+			if (e.type === 'note') {
+				const markOptions = extractMarkOptions((e as NoteEvent).marks);
+				if (markOptions.beamStart) beamStart = true;
+				if (markOptions.beamEnd) beamEnd = true;
+			}
+		}
+		return { beamStart, beamEnd };
+	}
+	return { beamStart: false, beamEnd: false };
+};
+
 // Encode a layer (voice)
 const encodeLayer = (voice: Voice, layerN: number, indent: string, initialTiePitches: Pitch[] = [], keyFifths: number = 0, initialClef?: Clef, initialSlur: string | null = null, initialHairpin: { form: 'cres' | 'dim'; startId: string } | null = null): LayerResult => {
 	const layerId = generateId("layer");
 	let xml = `${indent}<layer xml:id="${layerId}" n="${layerN}">\n`;
 
-	let inBeam = false;
+	let beamElementOpen = false;  // Whether actual <beam> element is open (passed to tuplets)
 	const baseIndent = indent + '    ';
 
 	// Track current clef to only emit changes
@@ -928,23 +926,16 @@ const encodeLayer = (voice: Voice, layerN: number, indent: string, initialTiePit
 	};
 
 	for (const event of voice.events) {
-		// Check for beam start/end in note events
-		let beamStart = false;
-		let beamEnd = false;
-		if (event.type === 'note') {
-			const noteEvent = event as NoteEvent;
-			const markOptions = extractMarkOptions(noteEvent.marks);
-			beamStart = markOptions.beamStart;
-			beamEnd = markOptions.beamEnd;
-		}
+		// Check for beam start/end in this event (including inside tuplets)
+		const { beamStart, beamEnd } = getEventBeamMarks(event);
 
 		// Open beam element if beam starts
-		if (beamStart && !inBeam) {
+		if (beamStart && !beamElementOpen) {
 			xml += `${baseIndent}<beam xml:id="${generateId('beam')}">\n`;
-			inBeam = true;
+			beamElementOpen = true;
 		}
 
-		const currentIndent = inBeam ? baseIndent + '    ' : baseIndent;
+		const currentIndent = beamElementOpen ? baseIndent + '    ' : baseIndent;
 
 		switch (event.type) {
 			case 'note': {
@@ -1061,7 +1052,9 @@ const encodeLayer = (voice: Voice, layerN: number, indent: string, initialTiePit
 				xml += restEventToMEI(event as RestEvent, currentIndent, keyFifths, currentOttavaShift);
 				break;
 			case 'tuplet': {
-				const tupletResult = tupletEventToMEI(event as TupletEvent, currentIndent, voice.staff, keyFifths, currentStaff, currentOttavaShift);
+				// Tuplet can be nested inside beam in MEI: <beam><tuplet>...</tuplet></beam>
+				// Pass beamElementOpen to tuplet so it knows not to create its own beam
+				const tupletResult = tupletEventToMEI(event as TupletEvent, currentIndent, voice.staff, keyFifths, currentStaff, currentOttavaShift, beamElementOpen);
 				xml += tupletResult.xml;
 
 				// Process slur ends first (to close any pending slurs from before this tuplet)
@@ -1158,14 +1151,14 @@ const encodeLayer = (voice: Voice, layerN: number, indent: string, initialTiePit
 		}
 
 		// Close beam element if beam ends
-		if (beamEnd && inBeam) {
+		if (beamEnd && beamElementOpen) {
 			xml += `${baseIndent}</beam>\n`;
-			inBeam = false;
+			beamElementOpen = false;
 		}
 	}
 
 	// Close any unclosed beam
-	if (inBeam) {
+	if (beamElementOpen) {
 		xml += `${baseIndent}</beam>\n`;
 	}
 
@@ -1754,9 +1747,15 @@ const encode = (doc: LilyletDoc, options: MEIEncoderOptions = {}): string => {
 
 	// Encode measures
 	measures.forEach((measure, mi) => {
-		// Update key signature if measure has one
+		// Check for key signature change and output scoreDef if needed
 		if (measure.key) {
-			currentKey = keyToFifths(measure.key);
+			const newKey = keyToFifths(measure.key);
+			if (newKey !== currentKey) {
+				currentKey = newKey;
+				const newKeySig = KEY_SIGS[currentKey] || "0";
+				// Output a scoreDef with the new key signature
+				mei += `${indent}${indent}${indent}${indent}${indent}${indent}<scoreDef xml:id="${generateId('scoredef')}" key.sig="${newKeySig}" />\n`;
+			}
 		}
 		mei += encodeMeasure(measure, mi + 1, `${indent}${indent}${indent}${indent}${indent}${indent}`, totalStaves, tieState, slurState, hairpinState, currentKey, partInfos, clefState);
 	});

package/source/lilylet/musicXmlDecoder.ts

@@ -27,6 +27,7 @@ import {
 	NavigationMarkType,
 	BarlineEvent,
 	HarmonyEvent,
+	TupletEvent,
 } from './types';
 
 import {
@@ -132,6 +133,88 @@ class SpannerTracker {
 	}
 }
 
+// ============ Tuplet Tracker ============
+
+/**
+ * Track tuplet groups by number attribute.
+ * Collects notes between tuplet start and stop to create TupletEvent.
+ */
+class TupletTracker {
+	// Map from tuplet number to collected events and ratio
+	private activeTuplets: Map<number, {
+		events: (NoteEvent | RestEvent)[];
+		ratio?: Fraction;
+	}> = new Map();
+
+	/**
+	 * Start a new tuplet group
+	 */
+	startTuplet(number: number = 1): void {
+		this.activeTuplets.set(number, { events: [] });
+	}
+
+	/**
+	 * Add an event to active tuplet(s)
+	 * Returns true if the event was added to at least one tuplet
+	 */
+	addEvent(event: NoteEvent | RestEvent): boolean {
+		if (this.activeTuplets.size === 0) return false;
+
+		// Add to all active tuplets (in case of nested tuplets)
+		for (const [, tuplet] of this.activeTuplets) {
+			// Set ratio from first event's duration.tuplet
+			if (!tuplet.ratio && event.duration.tuplet) {
+				// In Lilylet, ratio is denominator/numerator (e.g., 2/3 for triplet)
+				tuplet.ratio = {
+					numerator: event.duration.tuplet.denominator,
+					denominator: event.duration.tuplet.numerator,
+				};
+			}
+			// Store event without tuplet info in duration (it's handled at TupletEvent level)
+			const cleanEvent = { ...event, duration: { ...event.duration } };
+			delete cleanEvent.duration.tuplet;
+			tuplet.events.push(cleanEvent);
+		}
+		return true;
+	}
+
+	/**
+	 * Stop a tuplet group and return the TupletEvent
+	 */
+	stopTuplet(number: number = 1): TupletEvent | undefined {
+		const tuplet = this.activeTuplets.get(number);
+		if (!tuplet || tuplet.events.length === 0) {
+			this.activeTuplets.delete(number);
+			return undefined;
+		}
+
+		this.activeTuplets.delete(number);
+
+		// Default ratio if not set (shouldn't happen normally)
+		const ratio = tuplet.ratio || { numerator: 2, denominator: 3 };
+
+		return {
+			type: 'tuplet',
+			ratio,
+			events: tuplet.events,
+		};
+	}
+
+	/**
+	 * Check if any tuplet is active
+	 */
+	isActive(): boolean {
+		return this.activeTuplets.size > 0;
+	}
+
+	/**
+	 * Reset tracker
+	 */
+	reset(): void {
+		this.activeTuplets.clear();
+	}
+}
+
 // ============ Voice Position Tracker ============
 
 /**
@@ -940,7 +1023,8 @@ const convertMeasure = (
 	measureEl: Element,
 	voiceTracker: VoiceTracker,
 	spannerTracker: SpannerTracker,
-	ottavaTracker: { current: number }
+	ottavaTracker: { current: number },
+	tupletTracker: TupletTracker
 ): MeasureConversionResult => {
 	let key: KeySignature | undefined;
 	let timeSig: Fraction | undefined;
@@ -994,6 +1078,12 @@ const convertMeasure = (
 			const staffNum = note.staff || 1;
 			currentVoice = voiceNum;
 
+			// Check for tuplet start BEFORE processing the note
+			const tupletNotation = note.notations?.tuplet;
+			if (tupletNotation?.type === 'start') {
+				tupletTracker.startTuplet(tupletNotation.number);
+			}
+
 			// Add any pending context changes before the note (tempo, ottava)
 			if (pendingContextChanges.length > 0) {
 				for (const ctx of pendingContextChanges) {
@@ -1023,7 +1113,13 @@ const convertMeasure = (
 
 				// Grace notes don't advance time
 				const advanceDuration = note.isGrace ? 0 : note.duration.divisions;
-				voiceTracker.addEvent(voiceNum, restEvent, advanceDuration, staffNum);
+
+				// Check if we're in a tuplet
+				if (tupletTracker.isActive()) {
+					tupletTracker.addEvent(restEvent);
+				} else {
+					voiceTracker.addEvent(voiceNum, restEvent, advanceDuration, staffNum);
+				}
 			} else if (note.pitch) {
 				// Note or chord - convert MusicXmlPitch to Lilylet Pitch
 				const lilyletPitch = musicXmlPitchToLilylet(note.pitch);
@@ -1093,7 +1189,31 @@ const convertMeasure = (
 
 				// Grace notes don't advance time
 				const advanceDuration = note.isGrace ? 0 : note.duration.divisions;
-				voiceTracker.addEvent(voiceNum, noteEvent, advanceDuration, staffNum);
+
+				// Check if we're in a tuplet
+				if (tupletTracker.isActive()) {
+					tupletTracker.addEvent(noteEvent);
+				} else {
+					voiceTracker.addEvent(voiceNum, noteEvent, advanceDuration, staffNum);
+				}
+			}
+
+			// Check for tuplet stop AFTER processing the note
+			if (tupletNotation?.type === 'stop') {
+				const tupletEvent = tupletTracker.stopTuplet(tupletNotation.number);
+				if (tupletEvent) {
+					// Calculate total duration of tuplet for voiceTracker
+					let totalDuration = 0;
+					for (const evt of tupletEvent.events) {
+						if (evt.duration) {
+							// Convert division to duration units (quarter = 1)
+							totalDuration += (4 / evt.duration.division) * voiceTracker.getDivisions();
+						}
+					}
+					// Apply tuplet ratio to get actual duration
+					totalDuration = totalDuration * tupletEvent.ratio.numerator / tupletEvent.ratio.denominator;
+					voiceTracker.addEvent(voiceNum, tupletEvent, totalDuration, staffNum);
+				}
 			}
 		} else if (tagName === 'direction') {
 			const direction = parseDirection(child);
@@ -1158,6 +1278,7 @@ const convertPart = (partEl: Element): { measures: Measure[]; name?: string } =>
 	const voiceTracker = new VoiceTracker();
 	const spannerTracker = new SpannerTracker();
 	const ottavaTracker = { current: 0 };
+	const tupletTracker = new TupletTracker();
 
 	let lastKey: KeySignature | undefined;
 	let lastTimeSig: Fraction | undefined;
@@ -1168,7 +1289,7 @@ const convertPart = (partEl: Element): { measures: Measure[]; name?: string } =>
 
 	for (const measureEl of measureEls) {
 		voiceTracker.reset();
-		const { voiceMap, key, timeSig, barline, harmonies, clefs } = convertMeasure(measureEl, voiceTracker, spannerTracker, ottavaTracker);
+		const { voiceMap, key, timeSig, barline, harmonies, clefs } = convertMeasure(measureEl, voiceTracker, spannerTracker, ottavaTracker, tupletTracker);
 
 		// Update running key/time
 		if (key) lastKey = key;