@k-l-lambda/lilylet 0.1.83 → 0.1.85

package/lib/lilylet/musicXmlDecoder.js

@@ -408,6 +408,23 @@ const parseNote = (noteEl, divisions) => {
             number: getAttributeNumber(el, 'number') || 1,
         }));
     }
+    // Lyrics are direct children of <note>; retain one slot per verse.
+    const lyricEls = getDirectChildren(noteEl, 'lyric');
+    let lyrics;
+    if (lyricEls.length > 0) {
+        lyrics = lyricEls.map(lyricEl => {
+            const rawSyllabic = getElementText(lyricEl, 'syllabic');
+            const syllabic = rawSyllabic === 'begin' || rawSyllabic === 'middle' ||
+                rawSyllabic === 'end' || rawSyllabic === 'single' ? rawSyllabic : 'single';
+            const textEl = getDirectChildren(lyricEl, 'text')[0];
+            return {
+                number: getAttributeNumber(lyricEl, 'number') || 1,
+                text: textEl?.textContent ?? undefined,
+                syllabic,
+                extend: getDirectChildren(lyricEl, 'extend').length > 0,
+            };
+        });
+    }
     return {
         isChord,
         isRest,
@@ -426,6 +443,7 @@ const parseNote = (noteEl, divisions) => {
         notations,
         fingerings,
         beams,
+        lyrics,
     };
 };
 /**
@@ -1043,6 +1061,39 @@ const convertMeasure = (measureEl, voiceTracker, spannerTracker, ottavaTracker,
     let leadingBarline;
     const harmonies = [];
     const clefs = new Map();
+    const lyricLanes = new Map();
+    const lyricForNote = (note, voiceNum, staffNum) => {
+        if (note.isGrace || note.isChord || note.isRest)
+            return;
+        let state = lyricLanes.get(voiceNum);
+        if (!state) {
+            state = { staff: staffNum, lanes: new Map(), noteIndex: 0 };
+            lyricLanes.set(voiceNum, state);
+        }
+        const byVerse = new Map((note.lyrics || []).map(l => [l.number, l]));
+        for (const number of byVerse.keys()) {
+            if (!state.lanes.has(number)) {
+                const lane = [];
+                for (let i = 0; i < state.noteIndex; i++)
+                    lane.push({ skip: true });
+                state.lanes.set(number, lane);
+            }
+        }
+        for (const [number, lane] of state.lanes) {
+            const lyric = byVerse.get(number);
+            if (!lyric) {
+                lane.push({ skip: true });
+            }
+            else {
+                lane.push({
+                    text: lyric.text,
+                    hyphen: lyric.syllabic === 'begin' || lyric.syllabic === 'middle' ? true : undefined,
+                    extend: lyric.extend || undefined,
+                });
+            }
+        }
+        state.noteIndex++;
+    };
     // Pending marks from directions (to attach to next note), per voice
     const pendingMarks = new Map();
     // Accumulated <forward> ticks waiting for the next note, whose <voice> tells us
@@ -1124,6 +1175,7 @@ const convertMeasure = (measureEl, voiceTracker, spannerTracker, ottavaTracker,
             const note = parseNote(child, voiceTracker.getDivisions());
             const voiceNum = note.voice;
             const staffNum = note.staff || 1;
+            lyricForNote(note, voiceNum, staffNum);
             currentVoice = voiceNum;
             // Record that this staff now has notes this measure and which voice is
             // active on it, so a subsequent mid-measure <clef> attaches inline here.
@@ -1431,8 +1483,9 @@ const convertMeasure = (measureEl, voiceTracker, spannerTracker, ottavaTracker,
             }
             if (voiceNum === undefined)
                 voiceNum = voices.keys().next().value;
-            if (voiceNum !== undefined)
-                voiceTracker.addEvent(voiceNum, pc.ctx, 0, pc.staff);
+            if (voiceNum === undefined)
+                voiceNum = 1;
+            voiceTracker.addEvent(voiceNum, pc.ctx, 0, pc.staff ?? 1);
         }
         pendingContextChanges.length = 0;
     }
@@ -1442,6 +1495,7 @@ const convertMeasure = (measureEl, voiceTracker, spannerTracker, ottavaTracker,
         voiceMap.set(voiceNum, {
             events: voiceState.events,
             staff: voiceState.staff,
+            lyrics: lyricLanes.get(voiceNum)?.lanes || new Map(),
         });
     }
     return { voiceMap, key, timeSig, barline, leadingBarline, harmonies, clefs };
@@ -1566,6 +1620,9 @@ const convertPart = (partEl) => {
             voices.push({
                 staff: voiceData.staff,
                 events,
+                lyrics: voiceData.lyrics.size > 0
+                    ? Array.from(voiceData.lyrics.entries()).sort(([a], [b]) => a - b).map(([verse, syllables]) => ({ verse, syllables }))
+                    : undefined,
             });
         }
         // If no voices found, create an empty one

package/lib/lilylet/musicXmlEncoder.js

@@ -103,6 +103,30 @@ const escapeXml = (text) => {
         .replace(/'/g, ''');
 };
 const indent = (level) => '  '.repeat(level);
+const makeLyricCursors = (lanes) => (lanes || []).map(lane => ({ lane, index: 0, inChain: false }));
+const lyricForCursor = (cursor) => {
+    const syllable = cursor.lane.syllables[cursor.index++];
+    if (!syllable || syllable.skip || syllable.text === undefined)
+        return undefined;
+    const syllabic = cursor.inChain
+        ? (syllable.hyphen ? 'middle' : 'end')
+        : (syllable.hyphen ? 'begin' : 'single');
+    cursor.inChain = !!syllable.hyphen;
+    return `<lyric number="${cursor.lane.verse || 1}"><syllabic>${syllabic}</syllabic>` +
+        `<text>${escapeXml(syllable.text)}</text>${syllable.extend ? '<extend/>' : ''}</lyric>`;
+};
+const lyricXmlForNote = (cursors, level, grace) => {
+    if (grace)
+        return '';
+    let xml = '';
+    for (const cursor of cursors) {
+        const lyric = lyricForCursor(cursor);
+        if (lyric) {
+            xml += `${indent(level)}${lyric}\n`;
+        }
+    }
+    return xml;
+};
 // === Encoding Functions ===
 /**
  * Encode pitch to MusicXML
@@ -289,7 +313,7 @@ const encodeNotations = (marks, level) => {
 /**
  * Encode a note event
  */
-const encodeNote = (event, voice, staff, level, isChord = false) => {
+const encodeNote = (event, voice, staff, level, isChord = false, lyricXml = '') => {
     let xml = `${indent(level)}<note>\n`;
     if (isChord) {
         xml += `${indent(level + 1)}<chord/>\n`;
@@ -341,6 +365,7 @@ const encodeNote = (event, voice, staff, level, isChord = false) => {
     if (event.marks && event.marks.length > 0) {
         xml += encodeNotations(event.marks, level + 1);
     }
+    xml += lyricXml;
     xml += `${indent(level)}</note>\n`;
     return xml;
 };
@@ -579,6 +604,7 @@ const encodeMeasure = (measure, partIndex, measureNumber, isFirst, prevKey, prev
     for (const voice of part.voices) {
         let currentStaff = voice.staff || 1;
         let voicePosition = 0;
+        const lyricCursors = makeLyricCursors(voice.lyrics);
         // Backup if needed
         if (currentPosition > 0 && voiceNum > 1) {
             xml += `${indent(level + 1)}<backup>\n`;
@@ -597,7 +623,7 @@ const encodeMeasure = (measure, partIndex, measureNumber, isFirst, prevKey, prev
                         xml += encodeDirection(directionMarks, level + 1, currentStaff, maxStaff > 1);
                     }
                     // Encode main note
-                    xml += encodeNote(event, voiceNum, currentStaff, level + 1);
+                    xml += encodeNote(event, voiceNum, currentStaff, level + 1, false, lyricXmlForNote(lyricCursors, level + 2, event.grace));
                     const dur = calculateDuration(event.duration);
                     voicePosition += dur;
                     // Encode chord notes. Marks live on the parent NoteEvent (the whole
@@ -658,11 +684,11 @@ const encodeMeasure = (measure, partIndex, measureNumber, isFirst, prevKey, prev
                             if (tupletMarks.length > 0) {
                                 const origMarks = subEvent.marks;
                                 subEvent.marks = [...(subEvent.marks || []), ...tupletMarks];
-                                xml += encodeNote(subEvent, voiceNum, currentStaff, level + 1);
+                                xml += encodeNote(subEvent, voiceNum, currentStaff, level + 1, false, lyricXmlForNote(lyricCursors, level + 2, subEvent.grace));
                                 subEvent.marks = origMarks;
                             }
                             else {
-                                xml += encodeNote(subEvent, voiceNum, currentStaff, level + 1);
+                                xml += encodeNote(subEvent, voiceNum, currentStaff, level + 1, false, lyricXmlForNote(lyricCursors, level + 2, subEvent.grace));
                             }
                             const dur = calculateDuration(subEvent.duration);
                             voicePosition += dur;

package/lib/lilylet/musicXmlTypes.d.ts

@@ -42,6 +42,13 @@ export interface MusicXmlAttributes {
     staves?: number;
 }
 export type MusicXmlStemDirection = 'up' | 'down';
+export type MusicXmlLyricSyllabic = 'single' | 'begin' | 'middle' | 'end';
+export interface MusicXmlLyric {
+    number: number;
+    text?: string;
+    syllabic?: MusicXmlLyricSyllabic;
+    extend?: boolean;
+}
 export interface MusicXmlNotations {
     ties?: {
         type: 'start' | 'stop';
@@ -84,6 +91,7 @@ export interface MusicXmlNote {
         type: 'begin' | 'continue' | 'end';
         number: number;
     }[];
+    lyrics?: MusicXmlLyric[];
 }
 export interface MusicXmlDynamic {
     type: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k-l-lambda/lilylet",
-  "version": "0.1.83",
+  "version": "0.1.85",
   "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/musicXmlDecoder.ts

@@ -30,6 +30,8 @@ import {
 	BarlineEvent,
 	HarmonyEvent,
 	TupletEvent,
+	LyricLane,
+	LyricSyllable,
 } from './types';
 
 import {
@@ -44,6 +46,7 @@ import {
 	MusicXmlHarmony,
 	MusicXmlNotations,
 	MusicXmlPitch,
+	MusicXmlLyric,
 } from './musicXmlTypes';
 
 import {
@@ -554,6 +557,24 @@ const parseNote = (noteEl: Element, divisions: number): MusicXmlNote => {
 		}));
 	}
 
+	// Lyrics are direct children of <note>; retain one slot per verse.
+	const lyricEls = getDirectChildren(noteEl, 'lyric');
+	let lyrics: MusicXmlLyric[] | undefined;
+	if (lyricEls.length > 0) {
+		lyrics = lyricEls.map(lyricEl => {
+			const rawSyllabic = getElementText(lyricEl, 'syllabic');
+			const syllabic = rawSyllabic === 'begin' || rawSyllabic === 'middle' ||
+				rawSyllabic === 'end' || rawSyllabic === 'single' ? rawSyllabic : 'single';
+			const textEl = getDirectChildren(lyricEl, 'text')[0];
+			return {
+				number: getAttributeNumber(lyricEl, 'number') || 1,
+				text: textEl?.textContent ?? undefined,
+				syllabic,
+				extend: getDirectChildren(lyricEl, 'extend').length > 0,
+			};
+		});
+	}
+
 	return {
 		isChord,
 		isRest,
@@ -572,6 +593,7 @@ const parseNote = (noteEl: Element, divisions: number): MusicXmlNote => {
 		notations,
 		fingerings,
 		beams,
+		lyrics,
 	};
 };
 
@@ -1192,7 +1214,7 @@ const directionToMarks = (
  * Result of converting a measure - now includes voices grouped by voice number
  */
 interface MeasureConversionResult {
-	voiceMap: Map<number, { events: Event[]; staff: number }>;
+	voiceMap: Map<number, { events: Event[]; staff: number; lyrics: Map<number, LyricSyllable[]> }>;
 	key?: KeySignature;
 	timeSig?: Fraction;
 	barline?: BarlineEvent;
@@ -1267,6 +1289,36 @@ const convertMeasure = (
 	let leadingBarline: BarlineEvent | undefined;
 	const harmonies: HarmonyEvent[] = [];
 	const clefs: Map<number, ContextChange> = new Map();
+	const lyricLanes: Map<number, { staff: number; lanes: Map<number, LyricSyllable[]>; noteIndex: number }> = new Map();
+	const lyricForNote = (note: MusicXmlNote, voiceNum: number, staffNum: number): void => {
+		if (note.isGrace || note.isChord || note.isRest) return;
+		let state = lyricLanes.get(voiceNum);
+		if (!state) {
+			state = { staff: staffNum, lanes: new Map(), noteIndex: 0 };
+			lyricLanes.set(voiceNum, state);
+		}
+		const byVerse = new Map((note.lyrics || []).map(l => [l.number, l]));
+		for (const number of byVerse.keys()) {
+			if (!state.lanes.has(number)) {
+				const lane: LyricSyllable[] = [];
+				for (let i = 0; i < state.noteIndex; i++) lane.push({ skip: true });
+				state.lanes.set(number, lane);
+			}
+		}
+		for (const [number, lane] of state.lanes) {
+			const lyric = byVerse.get(number);
+			if (!lyric) {
+				lane.push({ skip: true });
+			} else {
+				lane.push({
+					text: lyric.text,
+					hyphen: lyric.syllabic === 'begin' || lyric.syllabic === 'middle' ? true : undefined,
+					extend: lyric.extend || undefined,
+				});
+			}
+		}
+		state.noteIndex++;
+	};
 
 	// Pending marks from directions (to attach to next note), per voice
 	const pendingMarks: Map<number, Mark[]> = new Map();
@@ -1353,6 +1405,7 @@ const convertMeasure = (
 			const note = parseNote(child, voiceTracker.getDivisions());
 			const voiceNum = note.voice;
 			const staffNum = note.staff || 1;
+			lyricForNote(note, voiceNum, staffNum);
 			currentVoice = voiceNum;
 			// Record that this staff now has notes this measure and which voice is
 			// active on it, so a subsequent mid-measure <clef> attaches inline here.
@@ -1681,17 +1734,19 @@ const convertMeasure = (
 				if (vs.staff === pc.staff) { voiceNum = vn; break; }
 			}
 			if (voiceNum === undefined) voiceNum = voices.keys().next().value;
-			if (voiceNum !== undefined) voiceTracker.addEvent(voiceNum, pc.ctx, 0, pc.staff);
+			if (voiceNum === undefined) voiceNum = 1;
+			voiceTracker.addEvent(voiceNum, pc.ctx, 0, pc.staff ?? 1);
 		}
 		pendingContextChanges.length = 0;
 	}
 
 	// Build voice map from tracker
-	const voiceMap = new Map<number, { events: Event[]; staff: number }>();
+	const voiceMap = new Map<number, { events: Event[]; staff: number; lyrics: Map<number, LyricSyllable[]> }>();
 	for (const [voiceNum, voiceState] of voiceTracker.getVoices()) {
 		voiceMap.set(voiceNum, {
 			events: voiceState.events,
 			staff: voiceState.staff,
+			lyrics: lyricLanes.get(voiceNum)?.lanes || new Map(),
 		});
 	}
 
@@ -1825,6 +1880,9 @@ const convertPart = (partEl: Element): { measures: Measure[]; name?: string } =>
 			voices.push({
 				staff: voiceData.staff,
 				events,
+				lyrics: voiceData.lyrics.size > 0
+					? Array.from(voiceData.lyrics.entries()).sort(([a], [b]) => a - b).map(([verse, syllables]) => ({ verse, syllables }))
+					: undefined,
 			});
 		}
 

package/source/lilylet/musicXmlEncoder.ts

@@ -36,6 +36,8 @@ import {
 	Tempo,
 	Metadata,
 	Fraction,
+	LyricLane,
+	LyricSyllable,
 } from "./types";
 
 import {
@@ -157,6 +159,38 @@ const escapeXml = (text: string): string => {
 
 const indent = (level: number): string => '  '.repeat(level);
 
+interface MusicXmlLyricCursor {
+	lane: LyricLane;
+	index: number;
+	inChain: boolean;
+}
+
+const makeLyricCursors = (lanes: LyricLane[] | undefined): MusicXmlLyricCursor[] =>
+	(lanes || []).map(lane => ({ lane, index: 0, inChain: false }));
+
+const lyricForCursor = (cursor: MusicXmlLyricCursor): string | undefined => {
+	const syllable = cursor.lane.syllables[cursor.index++];
+	if (!syllable || syllable.skip || syllable.text === undefined) return undefined;
+	const syllabic = cursor.inChain
+		? (syllable.hyphen ? 'middle' : 'end')
+		: (syllable.hyphen ? 'begin' : 'single');
+	cursor.inChain = !!syllable.hyphen;
+	return `<lyric number="${cursor.lane.verse || 1}"><syllabic>${syllabic}</syllabic>` +
+		`<text>${escapeXml(syllable.text)}</text>${syllable.extend ? '<extend/>' : ''}</lyric>`;
+};
+
+const lyricXmlForNote = (cursors: MusicXmlLyricCursor[], level: number, grace?: boolean): string => {
+	if (grace) return '';
+	let xml = '';
+	for (const cursor of cursors) {
+		const lyric = lyricForCursor(cursor);
+		if (lyric) {
+			xml += `${indent(level)}${lyric}\n`;
+		}
+	}
+	return xml;
+};
+
 
 // === Encoding Functions ===
 
@@ -396,7 +430,8 @@ const encodeNote = (
 	voice: number,
 	staff: number,
 	level: number,
-	isChord: boolean = false
+	isChord: boolean = false,
+	lyricXml: string = ''
 ): string => {
 	let xml = `${indent(level)}<note>\n`;
 
@@ -458,6 +493,7 @@ const encodeNote = (
 		xml += encodeNotations(event.marks, level + 1);
 	}
 
+	xml += lyricXml;
 	xml += `${indent(level)}</note>\n`;
 
 	return xml;
@@ -762,6 +798,7 @@ const encodeMeasure = (
 	for (const voice of part.voices) {
 		let currentStaff = voice.staff || 1;
 		let voicePosition = 0;
+		const lyricCursors = makeLyricCursors(voice.lyrics);
 
 		// Backup if needed
 		if (currentPosition > 0 && voiceNum > 1) {
@@ -785,7 +822,8 @@ const encodeMeasure = (
 					}
 
 					// Encode main note
-					xml += encodeNote(event, voiceNum, currentStaff, level + 1);
+					xml += encodeNote(event, voiceNum, currentStaff, level + 1, false,
+						lyricXmlForNote(lyricCursors, level + 2, event.grace));
 					const dur = calculateDuration(event.duration);
 					voicePosition += dur;
 
@@ -854,10 +892,12 @@ const encodeMeasure = (
 							if (tupletMarks.length > 0) {
 								const origMarks = subEvent.marks;
 								subEvent.marks = [...(subEvent.marks || []), ...tupletMarks];
-								xml += encodeNote(subEvent, voiceNum, currentStaff, level + 1);
+									xml += encodeNote(subEvent, voiceNum, currentStaff, level + 1, false,
+										lyricXmlForNote(lyricCursors, level + 2, subEvent.grace));
 								subEvent.marks = origMarks;
 							} else {
-								xml += encodeNote(subEvent, voiceNum, currentStaff, level + 1);
+									xml += encodeNote(subEvent, voiceNum, currentStaff, level + 1, false,
+										lyricXmlForNote(lyricCursors, level + 2, subEvent.grace));
 							}
 							const dur = calculateDuration(subEvent.duration);
 							voicePosition += dur;

package/source/lilylet/musicXmlTypes.ts

@@ -53,6 +53,15 @@ export interface MusicXmlAttributes {
 
 export type MusicXmlStemDirection = 'up' | 'down';
 
+export type MusicXmlLyricSyllabic = 'single' | 'begin' | 'middle' | 'end';
+
+export interface MusicXmlLyric {
+	number: number;
+	text?: string;
+	syllabic?: MusicXmlLyricSyllabic;
+	extend?: boolean;
+}
+
 export interface MusicXmlNotations {
 	ties?: { type: 'start' | 'stop' }[];
 	slurs?: { type: 'start' | 'stop'; number: number }[];
@@ -81,6 +90,7 @@ export interface MusicXmlNote {
 	notations?: MusicXmlNotations;
 	fingerings?: number[];      // one per chord member; a single note has at most one
 	beams?: { type: 'begin' | 'continue' | 'end'; number: number }[];
+	lyrics?: MusicXmlLyric[];
 }
 
 // ============ Direction Types ============