@k-l-lambda/lilylet 0.1.81 → 0.1.83

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/onsets.ts

@@ -0,0 +1,158 @@
+/**
+ * Note-onset extraction from a parsed Lilylet document.
+ *
+ * Walks measures -> parts -> voices -> events, accumulating each note's ONSET (position
+ * within its measure, in duration units of RES=480 per quarter) and its SOUNDING
+ * MIDI pitch. Sounding pitch honors octave-/interval-transposing clefs ("treble_8" sounds
+ * an octave lower than written, etc.), tracked per voice and PERSISTED across measures.
+ *
+ * Shared by tools/astServer.ts (the HTTP onset API) and the clef-onset unit test.
+ */
+
+import { calculateDuration } from "./musicXmlUtils";
+import { Accidental } from "./types";
+
+// Onset resolution in ticks per quarter note. calculateDuration() rounds its result to an
+// integer, so it must run at a resolution fine enough to represent every note value exactly:
+// the shared DIVISIONS=4 (MusicXML export) rounds a 32nd (0.5) and a dotted 16th (1.5) to
+// integers, drifting the onset cursor. 480 is divisible by all common note/dot/tuplet values,
+// so durations stay exact. Onsets are reported in these units and also normalized per measure.
+const RES = 480;
+
+const PHONET_SEMITONE: Record<string, number> = { c: 0, d: 2, e: 4, f: 5, g: 7, a: 9, b: 11 };
+const ACCIDENTAL_SEMITONE: Record<string, number> = {
+	[Accidental.natural]: 0, [Accidental.sharp]: 1, [Accidental.flat]: -1,
+	[Accidental.doubleSharp]: 2, [Accidental.doubleFlat]: -2,
+};
+
+// Diatonic-step -> semitones within an octave (unison..seventh), for "_N"/"^N" clef suffixes.
+const DIATONIC_SEMITONES = [0, 2, 4, 5, 7, 9, 11];
+
+/**
+ * The written->sounding semitone shift a clef string declares. Per the LilyPond convention a
+ * "_N"/"^N" suffix transposes DOWN/UP by the diatonic interval N: "treble_8" = octave down
+ * (-12), "treble^8" = +12, "treble_15" = two octaves down (-24), "treble_5" = fifth down (-7).
+ * A plain clef (no suffix) declares 0.
+ */
+export const clefShift = (clefStr: string): number => {
+	const m = /^.*?([_^])(\d+)$/.exec(clefStr || "");
+	if (!m) return 0;
+	const k = parseInt(m[2], 10) - 1;					// diatonic steps above unison
+	const semis = DIATONIC_SEMITONES[k % 7] + 12 * Math.floor(k / 7);
+	return (m[1] === "^" ? 1 : -1) * semis;
+};
+
+/**
+ * Sounding MIDI pitch of a resolved (absolute-octave) Lilylet pitch. Octave 0 = middle-C
+ * octave = MIDI 60 (see parser.resolveRelativePitch). `shift` is the active clef's
+ * written->sounding semitone transposition.
+ */
+export const pitchToMidi = (pitch: any, shift = 0): number => {
+	const semi = PHONET_SEMITONE[pitch.phonet] ?? 0;
+	const acc = pitch.accidental ? (ACCIDENTAL_SEMITONE[pitch.accidental] ?? 0) : 0;
+	return 60 + (pitch.octave || 0) * 12 + semi + acc + shift;
+};
+
+export interface NoteOnset {
+	onset: number; onsetNorm: number; durationDiv: number;
+	midi: number[]; staff: number; voice: number; grace: boolean;
+}
+
+export interface MeasureOnsets {
+	index: number;
+	timeSig: { numerator: number; denominator: number } | null;
+	measureDivisions: number;
+	notes: NoteOnset[];
+}
+
+// Walk a voice's events, accumulating onset in duration units. Tuplet/times scale their inner
+// durations by ratio (num/den). Grace notes take no time. `clefRef.shift` is the active clef's
+// written->sounding shift, updated by \clef contextChanges (persisted by the caller across
+// measures). Returns the total consumed duration (the voice's played length).
+const walkVoice = (events: any[], staff: number, voice: number,
+	scale: number, startCursor: number, clefRef: { shift: number }, out: NoteOnset[]): number => {
+	let cursor = startCursor;
+	for (const ev of events) {
+		if (ev.type === "context" && typeof ev.clef === "string") {
+			clefRef.shift = clefShift(ev.clef);
+		}
+		else if (ev.type === "note") {
+			const dur = calculateDuration(ev.duration, RES) * scale;
+			const midi = (ev.pitches || []).map((p: any) => pitchToMidi(p, clefRef.shift));
+			if (ev.grace) {
+				out.push({ onset: cursor, onsetNorm: 0, durationDiv: 0, midi, staff: ev.staff ?? staff, voice, grace: true });
+				continue; // grace steals no measure time
+			}
+			out.push({ onset: cursor, onsetNorm: 0, durationDiv: dur, midi, staff: ev.staff ?? staff, voice, grace: false });
+			cursor += dur;
+		}
+		else if (ev.type === "rest") {
+			cursor += calculateDuration(ev.duration, RES) * scale;
+		}
+		else if (ev.type === "tuplet" || ev.type === "times") {
+			const r = ev.ratio || { numerator: 1, denominator: 1 };
+			cursor = walkVoice(ev.events || [], staff, voice, scale * (r.numerator / r.denominator), cursor, clefRef, out);
+		}
+		else if (ev.type === "tremolo") {
+			const each = (RES * 4 / ev.division) * scale;
+			out.push({ onset: cursor, onsetNorm: 0, durationDiv: each,
+				midi: (ev.pitchA || []).map((p: any) => pitchToMidi(p, clefRef.shift)), staff, voice, grace: false });
+			cursor += each;
+			out.push({ onset: cursor, onsetNorm: 0, durationDiv: each,
+				midi: (ev.pitchB || []).map((p: any) => pitchToMidi(p, clefRef.shift)), staff, voice, grace: false });
+			cursor += each;
+		}
+		// barline / markup / dynamic / harmony / pitchReset: no time
+	}
+	return cursor;
+};
+
+/**
+ * Per-measure note onsets for a parsed LilyletDoc. The active clef transposition is tracked
+ * per (positional) voice index and PERSISTS across measures — a \clef stays in force until the
+ * next one, so a "treble_8" set in measure 1 still lowers measure 2 by an octave.
+ *
+ * Measure length (`measureDivisions`, used to normalize onsets to [0,1)) comes from the time
+ * signature for a full bar, but an INCOMPLETE bar carrying a `\partial` (a pickup, or a bar
+ * split by a repeat barline) is only as long as its `\partial` value. Honoring `\partial` makes
+ * the lilylet bar length match the corresponding MIDI measure's tick span (MuseScore emits a
+ * short 1/8 or 3/8 measure for exactly these), so the two onset grids align.
+ */
+export const measureOnsets = (doc: any): MeasureOnsets[] => {
+	let curTime: any = null;
+	const clefByVoice: { shift: number }[] = [];
+	return (doc.measures || []).map((m: any, mi: number): MeasureOnsets => {
+		if (m.timeSig) curTime = m.timeSig;
+		const notes: NoteOnset[] = [];
+		let maxCursor = 0;
+		let vIndex = 0;
+		// a \partial anywhere in the measure (any voice's leading contextChange) shortens the bar.
+		let partial: any = null;
+		for (const part of m.parts || []) {
+			for (const voice of part.voices || []) {
+				if (!clefByVoice[vIndex]) clefByVoice[vIndex] = { shift: 0 };
+				for (const ev of voice.events || []) {
+					if (ev.type === "context" && ev.partial) { partial = ev.partial; break; }
+					if (ev.type === "note" || ev.type === "rest" || ev.type === "tuplet"
+						|| ev.type === "times" || ev.type === "tremolo") break;	// partial must precede notes
+				}
+				const end = walkVoice(voice.events || [], voice.staff ?? 1, vIndex, 1, 0, clefByVoice[vIndex], notes);
+				maxCursor = Math.max(maxCursor, end);
+				vIndex += 1;
+			}
+		}
+		// bar length: \partial value if the bar is incomplete, else the full time-signature bar,
+		// else (no time sig) the longest voice cursor.
+		const fullBar = curTime ? RES * 4 * curTime.numerator / curTime.denominator : maxCursor;
+		const barDiv = partial ? calculateDuration(partial, RES) : fullBar;
+		const span = barDiv > 0 ? barDiv : (maxCursor > 0 ? maxCursor : 1);
+		for (const n of notes)
+			n.onsetNorm = n.onset / span;
+		return {
+			index: mi + 1,
+			timeSig: curTime ? { numerator: curTime.numerator, denominator: curTime.denominator } : null,
+			measureDivisions: span,
+			notes,
+		};
+	});
+};

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 {