@k-l-lambda/lilylet 0.1.82 → 0.1.83

package/source/lilylet/highlight.ts

@@ -18,6 +18,7 @@ export type HighlightScope =
 	| "hairpin"
 	| "header"
 	| "keyword"
+	| "lyric"
 	| "markup"
 	| "mode"
 	| "navigation"
@@ -96,6 +97,7 @@ export const HIGHLIGHT_RULES: HighlightRule[] = [
 	{ 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" },
@@ -155,6 +157,13 @@ export const HIGHLIGHT_RULES: HighlightRule[] = [
 	{ 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" },
 ];
 
 /**

package/source/lilylet/lilylet.jison

@@ -34,6 +34,20 @@
 		};
 	};
 
+	// Build a lyric lane (one \addlyrics block) from raw lyric items. `--` is a
+	// connector that hyphenates the preceding syllable (it does not consume a
+	// note slot); `_` is a skipped slot; `__` extends the preceding syllable.
+	const addlyricsLane = (items) => {
+		const syllables = [];
+		for (const it of items) {
+			if (it.text !== undefined) syllables.push({ text: it.text });
+			else if (it.hyphen) { if (syllables.length) syllables[syllables.length - 1].hyphen = true; }
+			else if (it.skip) syllables.push({ skip: true });
+			else if (it.extend) { if (syllables.length) syllables[syllables.length - 1].extend = true; else syllables.push({ extend: true }); }
+		}
+		return { syllables };
+	};
+
 	const restEvent = (dur, options = {}) => ({
 		type: 'rest',
 		duration: dur,
@@ -51,7 +65,7 @@
 		mode,
 	});
 
-	const voice = (staff, events) => {
+	const voice = (staff, events, lyrics) => {
 		// Use the first \staff "N" context event that appears before any musical event
 		// (notes/rests/tuplets) as the authoritative voice.staff.
 		// Skip pitchReset events (from NEWLINE tokens at voice-line boundaries).
@@ -67,9 +81,13 @@
 			}
 			break; // first musical/structural event — stop
 		}
+		// \addlyrics lanes are scoped to THIS voice; verse numbers are 1-based by
+		// order of \addlyrics blocks within the voice.
+		const lanes = lyrics && lyrics.length ? lyrics.map((lane, i) => ({ verse: i + 1, ...lane })) : undefined;
 		return {
 			staff: leadingStaff != null ? leadingStaff : 1,
 			events,
+			lyrics: lanes,
 		};
 	};
 
@@ -241,6 +259,7 @@
 
 %option flex unicode case-insensitive
 
+%x lyric
 
 %%
 
@@ -262,7 +281,7 @@
 \[auto\-beam					return 'HEADER_AUTOBEAM'
 \]								return ']'
 
-\"([^\"\\]|\\.)*\"					return 'STRING'
+\"([^\"\\]|\\.)*\"				return 'STRING'
 
 "\\clef"						return 'CMD_CLEF'
 "\\key"							return 'CMD_KEY'
@@ -292,6 +311,7 @@
 "\\segno"						return 'CMD_SEGNO'
 "\\chords"						return 'CMD_CHORDS'
 "\\markup"						return 'CMD_MARKUP'
+"\\addlyrics"					{ this.pushState('lyric'); return 'CMD_ADDLYRICS'; }
 
 "\\<"							return 'CMD_CRESC_BEGIN'
 "\\>"							return 'CMD_DIM_BEGIN'
@@ -369,6 +389,17 @@
 .								{}
 
 
+<lyric>"{"						return '{'
+<lyric>"}"						{ this.popState(); return '}'; }
+<lyric>[ \t]+					{}
+<lyric>(\r?\n)+					{}
+<lyric>"--"						return 'LYRIC_HYPHEN'
+<lyric>"__"						return 'LYRIC_EXTENDER'
+<lyric>"_"						return 'LYRIC_SKIP'
+<lyric>\"([^\"\\]|\\.)*\"		return 'LYRIC_WORD'
+<lyric>[^ \t\r\n{}\"\\]+		return 'LYRIC_WORD'
+
+
 /lex
 
 %start document
@@ -423,7 +454,7 @@ measures
 	;
 
 measure_content
-	: parts										%{
+	: parts									%{
 		// Check \partial declarations: warn if declared duration ≠ actual voice ticks
 		let partialDur = null;
 		outer: for (const p of $1) {
@@ -454,6 +485,17 @@ measure_content
 	%}
 	;
 
+addlyrics_opt
+	: /* empty */								{ $$ = undefined; }
+	| addlyrics_blocks							{ $$ = $1; }
+	;
+
+addlyrics_blocks
+	: addlyrics_block							{ $$ = [$1]; }
+	| addlyrics_blocks addlyrics_block			{ $$ = $1.concat([$2]); }
+	| addlyrics_blocks NEWLINE					{ $$ = $1; }
+	;
+
 parts
 	: part_voices								{ $$ = [part($1)]; }
 	| parts PART_SEP part_start part_voices		{ $$ = $1.concat([part($4)]); }
@@ -464,8 +506,12 @@ part_start
 	;
 
 part_voices
-	: voice_events								{ $$ = [voice(currentStaff, $1)]; }
-	| part_voices VOICE_SEP voice_events		{ $$ = $1.concat([voice(currentStaff, $3)]); }
+	: voice_block								{ $$ = [voice(currentStaff, $1.events, $1.lyrics)]; }
+	| part_voices VOICE_SEP voice_block			{ $$ = $1.concat([voice(currentStaff, $3.events, $3.lyrics)]); }
+	;
+
+voice_block
+	: voice_events addlyrics_opt				{ $$ = { events: $1, lyrics: $2 }; }
 	;
 
 voice_events
@@ -787,3 +833,19 @@ markup_mark
 glissando_mark
 	: CMD_GLISSANDO								-> glissando()
 	;
+
+addlyrics_block
+	: CMD_ADDLYRICS '{' lyric_sequence '}'		-> addlyricsLane($3)
+	;
+
+lyric_sequence
+	: /* empty */								{ $$ = []; }
+	| lyric_sequence lyric_item					{ $$ = $1.concat([$2]); }
+	;
+
+lyric_item
+	: LYRIC_WORD								-> ({ text: $1.charAt(0) === '"' ? unq($1) : $1 })
+	| LYRIC_HYPHEN								-> ({ hyphen: true })
+	| LYRIC_SKIP								-> ({ skip: true })
+	| LYRIC_EXTENDER							-> ({ extend: true })
+	;

package/source/lilylet/meiEncoder.ts

@@ -26,6 +26,8 @@ import {
 	Tempo,
 	Event,
 	InstrumentName,
+	LyricLane,
+	LyricSyllable,
 } from "./types";
 import { parseStaffLayout, StaffGroup, StaffGroupType } from "./staffLayout";
 import { gmProgramOf } from "./gmInstruments";
@@ -327,6 +329,49 @@ const tremoloToStemMod = (division: number): string | undefined => {
 	return undefined;
 };
 
+// Encode the lyric slots attached to one rhythmic event. Lanes are measure-local
+// because the parser stores them on the Voice created for that measure.
+interface LyricCursor {
+	consume(): string;
+	consumeRest(): void;
+}
+
+const lyricWordPosition = (syllables: LyricSyllable[], index: number): 'i' | 'm' | 't' | 'u' => {
+	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: LyricLane, index: number, indent: string): string => {
+	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: LyricLane[] | undefined, indent: string): LyricCursor[] =>
+	(lanes || []).map((lane) => {
+		let index = 0;
+		const consume = (): string => {
+			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: LyricCursor[], indent: string): string => {
+	let xml = '';
+	for (const cursor of cursors) xml += cursor.consume();
+	return xml;
+};
+
 // Build note element
 const buildNoteElement = (
 	pitch: { pname: string; oct: number; octGes?: number; accid?: string; accidGes?: string },
@@ -341,7 +386,8 @@ const buildNoteElement = (
 		staff?: number;
 		layerStaff?: number;
 		artics?: { type: string; placement?: 'above' | 'below' }[];
-		tremolo?: number;
+			tremolo?: number;
+			lyricXml?: string;
 	} = {},
 	noteId?: string
 ): string => {
@@ -366,8 +412,7 @@ const buildNoteElement = (
 		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`;
@@ -392,6 +437,8 @@ const buildNoteElement = (
 		}
 	}
 
+	if (options.lyricXml) result += options.lyricXml;
+
 	result += `${indent}</note>\n`;
 	return result;
 };
@@ -592,7 +639,8 @@ const noteEventToMEI = (
 	contextStemDir?: StemDirection,
 	keyFifths: number = 0,
 	ottavaShift: number = 0,
-	measureAccidentals?: Map<string, string>
+	measureAccidentals?: Map<string, string>,
+	lyricXml: string = ''
 ): NoteEventResult => {
 	const dur = DURATIONS[event.duration.division] || "4";
 	const dots = event.duration.dots || 0;
@@ -630,7 +678,7 @@ const noteEventToMEI = (
 		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,
@@ -693,6 +741,7 @@ const noteEventToMEI = (
 		}
 	}
 
+		if (lyricXml) result += lyricXml;
 	result += `${indent}</chord>\n`;
 	return {
 		xml: result,
@@ -795,7 +844,7 @@ const tupletHasInternalBeams = (event: TupletEvent): boolean => {
 };
 
 // Convert TupletEvent to MEI
-const tupletEventToMEI = (event: TupletEvent, indent: string, layerStaff?: number, keyFifths: number = 0, currentStaff?: number, ottavaShift: number = 0, inParentBeam: boolean = false, measureAccidentals?: Map<string, string>, currentClef?: string): TupletEventResult => {
+const tupletEventToMEI = (event: TupletEvent, indent: string, layerStaff?: number, keyFifths: number = 0, currentStaff?: number, ottavaShift: number = 0, inParentBeam: boolean = false, measureAccidentals?: Map<string, string>, currentClef?: string, lyricCursors: LyricCursor[] = []): 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
@@ -847,7 +896,8 @@ const tupletEventToMEI = (event: TupletEvent, indent: string, layerStaff?: numbe
 			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;
@@ -1152,6 +1202,8 @@ const encodeLayer = (voice: Voice, layerN: number, indent: string, initialTiePit
 	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: Clef | undefined = initialClef;
 
@@ -1327,7 +1379,8 @@ const encodeLayer = (voice: Voice, layerN: number, indent: string, initialTiePit
 					? { ...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);
@@ -1472,7 +1525,7 @@ const encodeLayer = (voice: Voice, layerN: number, indent: string, initialTiePit
 				// 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 as TupletEvent, currentIndent, voice.staff, keyFifths, currentStaff, currentOttavaShift, beamElementOpen, measureAccidentals, currentClef);
+				const tupletResult = tupletEventToMEI(event as TupletEvent, 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

package/source/lilylet/serializer.ts

@@ -28,6 +28,7 @@ import {
 	StemDirection,
 	Accidental,
 	ArticulationType,
+	LyricLane,
 	OrnamentType,
 	DynamicType,
 	HairpinType,
@@ -928,6 +929,15 @@ const serializeVoice = (
 		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 };
 };
 
@@ -969,6 +979,33 @@ const serializePart = (
 };
 
 
+// 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: LyricLane): string => {
+	const out: string[] = [];
+	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 = (

package/source/lilylet/types.ts

@@ -214,6 +214,26 @@ export interface Tempo {
 	bpm?: number;
 }
 
+// === Lyrics ===
+
+// A lyric syllable within a lane, aligned by order to a voice's note events
+// (like LilyPond \lyricsto / \addlyrics). `hyphen` means the syllable is joined
+// to the next with a hyphen (LilyPond `--`); `skip` advances past a note with
+// no syllable (LilyPond `_`); `extend` draws an extender line (LilyPond `__`).
+export interface LyricSyllable {
+	text?: string;
+	hyphen?: boolean;
+	skip?: boolean;
+	extend?: boolean;
+}
+
+// A lyrics lane (verse) scoped to a voice. Verse numbers are 1-based and
+// assigned by order of \addlyrics blocks within the voice.
+export interface LyricLane {
+	verse?: number;
+	syllables: LyricSyllable[];
+}
+
 // === Events ===
 
 export interface NoteEvent {
@@ -301,6 +321,10 @@ export type Event = NoteEvent | RestEvent | ContextChange | TremoloEvent | Tuple
 export interface Voice {
 	staff: number;
 	events: Event[];
+	// \addlyrics lanes scoped to this voice. Lyrics align to THIS voice's note
+	// events, so a lane is serialized inside the voice it belongs to (e.g. a
+	// vocal line under staff 1), not as a trailing measure-level block.
+	lyrics?: LyricLane[];
 }
 
 export interface Metadata {