@k-l-lambda/lilylet 0.1.33 → 0.1.35

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
@@ -1240,9 +1237,11 @@ const analyzePartStructure = (doc) => {
     return partInfos;
 };
 // Encode scoreDef with part groups
-const encodeScoreDef = (keySig, timeNum, timeDen, partInfos, indent) => {
+const encodeScoreDef = (keySig, timeNum, timeDen, partInfos, indent, meterSymbol) => {
     const scoreDefId = generateId("scoredef");
-    let xml = `${indent}<scoreDef xml:id="${scoreDefId}" key.sig="${keySig}" meter.count="${timeNum}" meter.unit="${timeDen}">\n`;
+    // Build meter attributes
+    const meterSymAttr = meterSymbol ? ` meter.sym="${meterSymbol}"` : '';
+    let xml = `${indent}<scoreDef xml:id="${scoreDefId}" key.sig="${keySig}"${meterSymAttr} meter.count="${timeNum}" meter.unit="${timeDen}">\n`;
     xml += `${indent}    <staffGrp xml:id="${generateId("staffgrp")}">\n`;
     for (let pi = 0; pi < partInfos.length; pi++) {
         const info = partInfos[pi];
@@ -1284,6 +1283,7 @@ const encode = (doc, options = {}) => {
     let currentKey = 0;
     let currentTimeNum = 4;
     let currentTimeDen = 4;
+    let currentMeterSymbol = undefined;
     const firstMeasure = doc.measures[0];
     if (firstMeasure.key) {
         currentKey = keyToFifths(firstMeasure.key);
@@ -1291,6 +1291,7 @@ const encode = (doc, options = {}) => {
     if (firstMeasure.timeSig) {
         currentTimeNum = firstMeasure.timeSig.numerator;
         currentTimeDen = firstMeasure.timeSig.denominator;
+        currentMeterSymbol = firstMeasure.timeSig.symbol;
     }
     const keySig = KEY_SIGS[currentKey] || "0";
     // Build MEI document
@@ -1335,7 +1336,7 @@ const encode = (doc, options = {}) => {
     mei += `${indent}${indent}<body>\n`;
     mei += `${indent}${indent}${indent}<mdiv xml:id="${generateId("mdiv")}">\n`;
     mei += `${indent}${indent}${indent}${indent}<score xml:id="${generateId("score")}">\n`;
-    mei += encodeScoreDef(keySig, currentTimeNum, currentTimeDen, partInfos, `${indent}${indent}${indent}${indent}${indent}`);
+    mei += encodeScoreDef(keySig, currentTimeNum, currentTimeDen, partInfos, `${indent}${indent}${indent}${indent}${indent}`, currentMeterSymbol);
     mei += `${indent}${indent}${indent}${indent}${indent}<section xml:id="${generateId("section")}">\n`;
     // Track tie state across measures for cross-measure ties
     const tieState = {};
@@ -1384,6 +1385,20 @@ const encode = (doc, options = {}) => {
                 mei += `${indent}${indent}${indent}${indent}${indent}${indent}<scoreDef xml:id="${generateId('scoredef')}" key.sig="${newKeySig}" />\n`;
             }
         }
+        // Check for time signature change and output scoreDef if needed
+        if (measure.timeSig && mi > 0) {
+            const newTimeNum = measure.timeSig.numerator;
+            const newTimeDen = measure.timeSig.denominator;
+            const newMeterSymbol = measure.timeSig.symbol;
+            if (newTimeNum !== currentTimeNum || newTimeDen !== currentTimeDen || newMeterSymbol !== currentMeterSymbol) {
+                currentTimeNum = newTimeNum;
+                currentTimeDen = newTimeDen;
+                currentMeterSymbol = newMeterSymbol;
+                // Output a scoreDef with the new time signature
+                const meterSymAttr = currentMeterSymbol ? ` meter.sym="${currentMeterSymbol}"` : '';
+                mei += `${indent}${indent}${indent}${indent}${indent}${indent}<scoreDef xml:id="${generateId('scoredef')}"${meterSymAttr} meter.count="${currentTimeNum}" meter.unit="${currentTimeDen}" />\n`;
+            }
+        }
         mei += encodeMeasure(measure, mi + 1, `${indent}${indent}${indent}${indent}${indent}${indent}`, totalStaves, tieState, slurState, hairpinState, currentKey, partInfos, clefState);
     });
     mei += `${indent}${indent}${indent}${indent}${indent}</section>\n`;

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/lib/serializer.js

@@ -448,7 +448,13 @@ const serializeVoice = (voice, currentStaff, isGrandStaff = false, measureContex
             parts.push('\\key ' + keyStr);
         }
         if (measureContext.time) {
-            parts.push('\\time ' + measureContext.time.numerator + '/' + measureContext.time.denominator);
+            const { numerator, denominator, symbol } = measureContext.time;
+            // Output \numericTimeSignature before 4/4 or 2/2 if no symbol is set
+            // (meaning numeric display was explicitly requested)
+            if (!symbol && ((numerator === 4 && denominator === 4) || (numerator === 2 && denominator === 2))) {
+                parts.push('\\numericTimeSignature');
+            }
+            parts.push('\\time ' + numerator + '/' + denominator);
         }
     }
     for (const event of voice.events) {

package/lib/types.d.ts

@@ -83,6 +83,9 @@ export interface Fraction {
     numerator: number;
     denominator: number;
 }
+export interface TimeSig extends Fraction {
+    symbol?: 'common' | 'cut';
+}
 export interface Pitch {
     phonet: Phonet;
     accidental?: Accidental;
@@ -231,7 +234,7 @@ export interface Part {
 }
 export interface Measure {
     key?: KeySignature;
-    timeSig?: Fraction;
+    timeSig?: TimeSig;
     parts: Part[];
     partial?: boolean;
 }

package/package.json

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