@k-l-lambda/lilylet 0.1.82 → 0.1.83

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/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.83",
   "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",