@k-l-lambda/lilylet 0.1.82 → 0.1.84

package/lib/lilylet/highlight.d.ts

@@ -1,5 +1,5 @@
 /** Generic highlight scopes Lilylet tokens can carry. */
-export type HighlightScope = "articulation" | "bar" | "brace" | "chordBracket" | "comment" | "dynamic" | "grace" | "hairpin" | "header" | "keyword" | "markup" | "mode" | "navigation" | "number" | "octave" | "operator" | "ornament" | "paren" | "pedal" | "pitch" | "punctuation" | "rest" | "separator" | "squareBracket" | "stem" | "string" | "tie" | "tuplet";
+export type HighlightScope = "articulation" | "bar" | "brace" | "chordBracket" | "comment" | "dynamic" | "grace" | "hairpin" | "header" | "keyword" | "lyric" | "markup" | "mode" | "navigation" | "number" | "octave" | "operator" | "ornament" | "paren" | "pedal" | "pitch" | "punctuation" | "rest" | "separator" | "squareBracket" | "stem" | "string" | "tie" | "tuplet";
 export interface HighlightRule {
     /** Sticky, case-insensitive regex anchored at the scan position. */
     re: RegExp;

package/lib/lilylet/highlight.js

@@ -50,6 +50,7 @@ export const HIGHLIGHT_RULES = [
     { re: /(?:\\segno\b)/iy, scope: "navigation" },
     { re: /(?:\\chords\b)/iy, scope: "keyword" },
     { re: /(?:\\markup\b)/iy, scope: "markup" },
+    { re: /(?:\\addlyrics\b)/iy, scope: "lyric" },
     { re: /(?:\\<)/iy, scope: "hairpin" },
     { re: /(?:\\>)/iy, scope: "hairpin" },
     { re: /(?:\\!)/iy, scope: "hairpin" },
@@ -109,6 +110,13 @@ export const HIGHLIGHT_RULES = [
     { re: /(?:=)/iy, scope: "operator" },
     { re: /(?:[rR])/iy, scope: "rest" },
     { re: /(?:[sS])/iy, scope: "rest" },
+    { re: /(?:\{)/iy, scope: "brace" },
+    { re: /(?:\})/iy, scope: "brace" },
+    { re: /(?:--)/iy, scope: "lyric" },
+    { re: /(?:__\b)/iy, scope: "lyric" },
+    { re: /(?:_\b)/iy, scope: "lyric" },
+    { re: /(?:"([^\"\\]|\\.)*")/iy, scope: "string" },
+    { re: /(?:[^ \t\r\n{}\"\\]+)/iy, scope: "string" },
 ];
 /**
  * Match a single token at `pos` in `line` using longest-match. Returns the

package/lib/lilylet/meiEncoder.js

@@ -266,6 +266,42 @@ const tremoloToStemMod = (division) => {
     }
     return undefined;
 };
+const lyricWordPosition = (syllables, index) => {
+    const syllable = syllables[index];
+    if (!syllable?.text)
+        return 'u';
+    const previous = index > 0 ? syllables[index - 1] : undefined;
+    if (previous?.text && previous.hyphen)
+        return syllable.hyphen ? 'm' : 't';
+    return syllable.hyphen ? 'i' : 'u';
+};
+const lyricSyllableXml = (lane, index, indent) => {
+    const syllable = lane.syllables[index];
+    if (!syllable || syllable.skip || syllable.text === undefined)
+        return '';
+    const wordpos = lyricWordPosition(lane.syllables, index);
+    const con = syllable.extend ? 'u' : syllable.hyphen ? 'd' : undefined;
+    const attrs = ` wordpos="${wordpos}"${con ? ` con="${con}"` : ''}`;
+    return `${indent}<syl${attrs}>${escapeXml(syllable.text)}</syl>\n`;
+};
+const makeLyricCursors = (lanes, indent) => (lanes || []).map((lane) => {
+    let index = 0;
+    const consume = () => {
+        const current = index++;
+        const syllable = lane.syllables[current];
+        if (!syllable || syllable.skip || syllable.text === undefined)
+            return '';
+        const verse = lane.verse || 1;
+        return `${indent}<verse n="${verse}">\n${lyricSyllableXml(lane, current, indent + '    ')}${indent}</verse>\n`;
+    };
+    return { consume, consumeRest: () => { index++; } };
+});
+const lyricXmlForEvent = (cursors, indent) => {
+    let xml = '';
+    for (const cursor of cursors)
+        xml += cursor.consume();
+    return xml;
+};
 // Build note element
 const buildNoteElement = (pitch, dur, dots, indent, inChord, options = {}, noteId) => {
     const id = noteId || generateId('note');
@@ -295,8 +331,7 @@ const buildNoteElement = (pitch, dur, dots, indent, inChord, options = {}, noteI
         if (stemMod)
             attrs += ` stem.mod="${stemMod}"`;
     }
-    // Only artics remain as child elements; ornaments are control events
-    const hasChildren = !inChord && options.artics && options.artics.length > 0;
+    const hasChildren = !inChord && ((options.artics && options.artics.length > 0) || !!options.lyricXml);
     if (!hasChildren) {
         return `${indent}<note ${attrs} />\n`;
     }
@@ -316,6 +351,8 @@ const buildNoteElement = (pitch, dur, dots, indent, inChord, options = {}, noteI
             result += `${indent}    <artic artic="${defaultArtics.join(' ')}" />\n`;
         }
     }
+    if (options.lyricXml)
+        result += options.lyricXml;
     result += `${indent}</note>\n`;
     return result;
 };
@@ -466,7 +503,7 @@ const extractMarkOptions = (marks) => {
     return result;
 };
 // Convert NoteEvent to MEI
-const noteEventToMEI = (event, indent, layerStaff, tieEnd, contextStemDir, keyFifths = 0, ottavaShift = 0, measureAccidentals) => {
+const noteEventToMEI = (event, indent, layerStaff, tieEnd, contextStemDir, keyFifths = 0, ottavaShift = 0, measureAccidentals, lyricXml = '') => {
     const dur = DURATIONS[event.duration.division] || "4";
     const dots = event.duration.dots || 0;
     const markOptions = extractMarkOptions(event.marks);
@@ -503,7 +540,7 @@ const noteEventToMEI = (event, indent, layerStaff, tieEnd, contextStemDir, keyFi
         const pitch = encodePitch(event.pitches[0], keyFifths, ottavaShift, measureAccidentals);
         const noteId = generateId('note');
         return {
-            xml: buildNoteElement(pitch, dur, dots, indent, false, noteOptions, noteId),
+            xml: buildNoteElement(pitch, dur, dots, indent, false, { ...noteOptions, lyricXml }, noteId),
             elementId: noteId,
             hairpin: markOptions.hairpin,
             pedal: markOptions.pedal,
@@ -565,6 +602,8 @@ const noteEventToMEI = (event, indent, layerStaff, tieEnd, contextStemDir, keyFi
             result += `${indent}    <artic artic="${defaultArtics.join(' ')}" />\n`;
         }
     }
+    if (lyricXml)
+        result += lyricXml;
     result += `${indent}</chord>\n`;
     return {
         xml: result,
@@ -642,7 +681,7 @@ const tupletHasInternalBeams = (event) => {
     return starts > 0 && starts === ends;
 };
 // Convert TupletEvent to MEI
-const tupletEventToMEI = (event, indent, layerStaff, keyFifths = 0, currentStaff, ottavaShift = 0, inParentBeam = false, measureAccidentals, currentClef) => {
+const tupletEventToMEI = (event, indent, layerStaff, keyFifths = 0, currentStaff, ottavaShift = 0, inParentBeam = false, measureAccidentals, currentClef, lyricCursors = []) => {
     // 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
@@ -685,7 +724,8 @@ const tupletEventToMEI = (event, indent, layerStaff, keyFifths = 0, currentStaff
             const effectiveNoteEvent = effectiveStaff && layerStaff && effectiveStaff !== layerStaff
                 ? { ...noteEvent, staff: effectiveStaff }
                 : noteEvent;
-            const result = noteEventToMEI(effectiveNoteEvent, noteIndent, layerStaff, false, undefined, keyFifths, ottavaShift, measureAccidentals);
+            const lyricXml = lyricCursors.length ? lyricXmlForEvent(lyricCursors, noteIndent + '    ') : '';
+            const result = noteEventToMEI(effectiveNoteEvent, noteIndent, layerStaff, false, undefined, keyFifths, ottavaShift, measureAccidentals, lyricXml);
             xml += result.xml;
             if (!firstNoteId)
                 firstNoteId = result.elementId;
@@ -863,6 +903,7 @@ const encodeLayer = (voice, layerN, indent, initialTiePitches = [], keyFifths =
     let xml = `${indent}<layer xml:id="${layerId}" n="${layerN}">\n`;
     let beamElementOpen = false; // Whether actual <beam> element is open (passed to tuplets)
     const baseIndent = indent + '    ';
+    const lyricCursors = makeLyricCursors(voice.lyrics, baseIndent);
     // Track current clef to only emit changes
     let currentClef = initialClef;
     // Track hairpin spans. Use a stack of open hairpins (not a single slot): the
@@ -1021,7 +1062,8 @@ const encodeLayer = (voice, layerN, indent, initialTiePitches = [], keyFifths =
                 const effectiveNoteEvent = currentStaff !== voice.staff
                     ? { ...noteEvent, staff: currentStaff }
                     : noteEvent;
-                const result = noteEventToMEI(effectiveNoteEvent, currentIndent, voice.staff, tieEnd, currentStemDirection, keyFifths, currentOttavaShift, measureAccidentals);
+                const eventLyricXml = isGraceNote ? '' : lyricXmlForEvent(lyricCursors, currentIndent + '    ');
+                const result = noteEventToMEI(effectiveNoteEvent, currentIndent, voice.staff, tieEnd, currentStemDirection, keyFifths, currentOttavaShift, measureAccidentals, eventLyricXml);
                 xml += result.xml;
                 lastNoteId = result.elementId;
                 extendOttavaEnd(result.elementId);
@@ -1166,7 +1208,7 @@ const encodeLayer = (voice, layerN, indent, initialTiePitches = [], keyFifths =
                 // Pass beamElementOpen to tuplet so it knows not to create its own beam
                 // A pending ottava shift applies to the tuplet's notes' written octave.
                 applyPendingOttavaShift();
-                const tupletResult = tupletEventToMEI(event, currentIndent, voice.staff, keyFifths, currentStaff, currentOttavaShift, beamElementOpen, measureAccidentals, currentClef);
+                const tupletResult = tupletEventToMEI(event, currentIndent, voice.staff, keyFifths, currentStaff, currentOttavaShift, beamElementOpen, measureAccidentals, currentClef, lyricCursors);
                 xml += tupletResult.xml;
                 // An ottava span can open on, run through, or close at a tuplet (common
                 // in etudes where the 8va covers a whole tuplet run). Anchor the span on

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.
@@ -1442,6 +1494,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 +1619,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/lib/lilylet/serializer.js

@@ -788,6 +788,14 @@ const serializeVoice = (voice, currentStaff, isGrandStaff = false, measureContex
     if (graceGroupOpen) {
         parts.push('}');
     }
+    // \addlyrics lanes are scoped to this voice; emit them inside the voice so
+    // they bind to THIS voice's notes (e.g. lyrics under staff 1 serialize
+    // within staff 1's voice, not as a trailing measure-level block).
+    if (voice.lyrics && voice.lyrics.length) {
+        for (const lane of voice.lyrics) {
+            parts.push(serializeLyricLane(lane));
+        }
+    }
     return { str: parts.join(' '), newStaff: voice.staff };
 };
 // Serialize a part, tracking staff state across voices
@@ -813,6 +821,34 @@ const serializePart = (part, currentStaff, isGrandStaff = false, measureContext,
     // Multiple voices: separated by \\ with newline
     return { str: voiceStrs.join(' \\\\\n'), newStaff: staff };
 };
+// Serialize a \addlyrics lane: syllables separated by `--` (hyphen), `_` (skip),
+// `__` (extender). Bare words are emitted unquoted when they contain no
+// reserved characters, otherwise they are quoted and escaped. A syllable may
+// carry text AND a connector: the text is emitted first, then `--`/`__`, so
+// melismas (`text __`) and hyphenation (`text --`) never lose the syllable text.
+const serializeLyricLane = (lane) => {
+    const out = [];
+    for (const s of lane.syllables) {
+        if (s.skip) {
+            out.push('_');
+            continue;
+        }
+        const t = s.text ?? '';
+        // An extender with no preceding text is an orphan (e.g. a leading `__`);
+        // emit it alone rather than an empty quoted string.
+        if (!t && s.extend) {
+            out.push('__');
+            continue;
+        }
+        const bare = /^[^ \t\r\n{}"\\]+$/.test(t);
+        out.push(bare ? t : `"${escapeString(t)}"`);
+        if (s.hyphen)
+            out.push('--');
+        if (s.extend)
+            out.push('__');
+    }
+    return `\\addlyrics { ${out.join(' ')} }`;
+};
 // Serialize a measure, tracking staff state across parts
 // Always output key/time at start of each measure
 const serializeMeasure = (measure, _isFirst, currentStaff, isGrandStaff = false, currentKey, currentTime, partStaffClefs, partEmittedClefs) => {

package/lib/lilylet/types.d.ts

@@ -165,6 +165,16 @@ export interface Tempo {
     beat?: Duration;
     bpm?: number;
 }
+export interface LyricSyllable {
+    text?: string;
+    hyphen?: boolean;
+    skip?: boolean;
+    extend?: boolean;
+}
+export interface LyricLane {
+    verse?: number;
+    syllables: LyricSyllable[];
+}
 export interface NoteEvent {
     type: 'note';
     pitches: Pitch[];
@@ -235,6 +245,7 @@ export type Event = NoteEvent | RestEvent | ContextChange | TremoloEvent | Tuple
 export interface Voice {
     staff: number;
     events: Event[];
+    lyrics?: LyricLane[];
 }
 export interface Metadata {
     title?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k-l-lambda/lilylet",
-  "version": "0.1.82",
+  "version": "0.1.84",
   "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",
@@ -41,6 +41,7 @@
     "test:abc": "tsx ./tests/abc-decoder.ts",
     "test:roundtrip": "tsx ./tests/lilypond-roundtrip.ts",
     "test:lyl-roundtrip": "tsx ./tests/lyl-roundtrip.ts",
+    "test:lyrics": "tsx ./tests/lyrics-roundtrip.ts",
     "test:xml-roundtrip": "tsx ./tests/musicxml-roundtrip.ts",
     "test:abc-svg": "tsx ./tests/abc-abcjs-svg.ts",
     "train:bpe": "tsx ./tools/trainBpeTokenizer.ts",