@k-l-lambda/lilylet 0.1.81 → 0.1.83

package/lib/lilylet/onsets.js

@@ -0,0 +1,144 @@
+/**
+ * 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.js";
+import { Accidental } from "./types.js";
+// 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 = { c: 0, d: 2, e: 4, f: 5, g: 7, a: 9, b: 11 };
+const ACCIDENTAL_SEMITONE = {
+    [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) => {
+    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, shift = 0) => {
+    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;
+};
+// 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, staff, voice, scale, startCursor, clefRef, out) => {
+    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) => 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) => pitchToMidi(p, clefRef.shift)), staff, voice, grace: false });
+            cursor += each;
+            out.push({ onset: cursor, onsetNorm: 0, durationDiv: each,
+                midi: (ev.pitchB || []).map((p) => 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) => {
+    let curTime = null;
+    const clefByVoice = [];
+    return (doc.measures || []).map((m, mi) => {
+        if (m.timeSig)
+            curTime = m.timeSig;
+        const notes = [];
+        let maxCursor = 0;
+        let vIndex = 0;
+        // a \partial anywhere in the measure (any voice's leading contextChange) shortens the bar.
+        let partial = 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/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/lib/onsets.d.ts

@@ -0,0 +1 @@
+export * from "./lilylet/onsets.js";

package/lib/onsets.js

@@ -0,0 +1 @@
+export * from "./lilylet/onsets.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k-l-lambda/lilylet",
-  "version": "0.1.81",
+  "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",
@@ -49,7 +50,12 @@
     "test:bpe": "tsx ./tests/unit/bpeTokenizer.test.ts",
     "test:measures": "tsx ./tests/unit/measureLayout.test.ts",
     "test:measures-xml": "tsx ./tests/unit/measureLayoutFromXml.test.ts",
+    "test:measures-builder": "tsx ./tests/unit/measureLayoutBuilder.test.ts",
     "test:abc-repeats": "tsx ./tests/unit/abcRepeatLayout.test.ts",
+    "test:abc-instrument": "tsx ./tests/unit/abcInstrumentName.test.ts",
+    "test:abc-partial": "tsx ./tests/unit/abcPartialPickup.test.ts",
+    "test:clef-onset": "tsx ./tests/unit/clefOnsetTranspose.test.ts",
+    "test:fine-rhythm-onset": "tsx ./tests/unit/fineRhythmOnset.test.ts",
     "build:tests": "tsc -p tsconfig.tests.json; cp source/lilylet/grammar.jison.js lib-tests/source/lilylet/ && cp source/abc/grammar.jison.js lib-tests/source/abc/ && node tools/fixEsmExtensions.cjs lib-tests && ln -sfn ../../tests/assets lib-tests/tests/assets",
     "test:roundtrip:compiled": "node lib-tests/tests/lilypond-roundtrip.js",
     "ts": "tsx"

package/source/lilylet/abcDecoder.ts

@@ -16,6 +16,7 @@ import {
 	RestEvent,
 	ContextChange,
 	TupletEvent,
+	TremoloEvent,
 	Pitch,
 	Duration,
 	Mark,
@@ -249,6 +250,65 @@ const convertDuration = (abcDuration: { numerator: number; denominator: number }
 	return { division: Math.pow(2, Math.max(0, log2)), dots: 0 };
 };
 
+// A whole note is WHOLE_TICKS ticks. 2^7·3^3·5·7 = 120960 divides by every dot (·3/2, ·7/4),
+// tuplet (÷3, ÷5, ÷7), and common division, so a voice's played length is an exact integer —
+// no float rounding when we compare it to the bar length (unlike calculateDuration's Math.round).
+const WHOLE_TICKS = 120960;
+
+// A resolved Duration's tick length (dots + optional lilylet tuplet ratio num/den applied).
+const durationTicks = (d: Duration): number => {
+	let t = WHOLE_TICKS / d.division;
+	if (d.dots) {
+		let dot = t / 2;
+		for (let i = 0; i < d.dots; i++) { t += dot; dot /= 2; }
+	}
+	if (d.tuplet) t = t * d.tuplet.numerator / d.tuplet.denominator;
+	return t;
+};
+
+// Sum the played tick length of an event list. Context / barline / markup / dynamic events
+// take no time, and GRACE notes steal none (they carry a nominal duration but do not advance
+// the beat). A tuplet/times group scales its inner notes by ratio num/den (e.g. \tuplet 3/2 of
+// eighths = a quarter). This mirrors the parser's own \partial check so the emitted \partial
+// never trips a partial-mismatch warning. Used to measure a voice against its bar length.
+const eventsTicks = (events: Event[]): number => {
+	let total = 0;
+	for (const ev of events) {
+		if (ev.type === "note" || ev.type === "rest") {
+			if ((ev as NoteEvent).grace) continue;
+			total += durationTicks((ev as NoteEvent | RestEvent).duration);
+		}
+		else if (ev.type === "tuplet" || ev.type === "times") {
+			const t = ev as TupletEvent;
+			const factor = t.ratio ? t.ratio.numerator / t.ratio.denominator : 1;
+			for (const inner of t.events || []) {
+				if ((inner.type === "note" || inner.type === "rest") && !(inner as NoteEvent).grace)
+					total += durationTicks(inner.duration) * factor;
+			}
+		}
+		else if (ev.type === "tremolo") {
+			const tr = ev as TremoloEvent;
+			total += 2 * (WHOLE_TICKS / tr.division);
+		}
+	}
+	return total;
+};
+
+// Build a \partial Duration (single {division, dots}) for a pickup of `ticks` whole-note ticks.
+// LilyPond's \partial takes one duration token, so only power-of-2 divisions with up to 2 dots
+// are expressible; a length that isn't (e.g. a 5/8 pickup) returns null and no \partial is added
+// (the bar simply renders short) rather than emitting a wrong duration.
+const ticksToPartialDuration = (ticks: number): Duration | null => {
+	if (ticks <= 0) return null;
+	for (let division = 1; division <= 128; division *= 2) {
+		const base = WHOLE_TICKS / division;
+		if (ticks === base) return { division, dots: 0 };
+		if (ticks === base * 1.5) return { division, dots: 1 };
+		if (ticks === base * 1.75) return { division, dots: 2 };
+	}
+	return null;
+};
+
 /**
  * Apply broken rhythm adjustment.
  * broken > 0 (A>B): current note gets dotted, next gets halved
@@ -564,6 +624,11 @@ const collectAbcRepeatInfo = (bars: AbcBarInfo[]): MeasureRepeatInfo[] => {
 		// ("|:" forward, ":|:"/"::"/":||:" end-and-start).
 		const startsNext = trailBar.includes("|:") || isEndStart;
 		if (startsNext && idx < n) {
+			// A new repeat section opening here also CLOSES any still-open ending
+			// (a volta cannot span into the next repeat section). abc2xml back-patches
+			// the ending-stop onto this measure; without this a final volta (e.g.
+			// ":|2 …|:") would overshoot to the next volta/section bar far ahead.
+			if (openEndingStart >= 1 && openEndingStart <= idx) closeOpenEnding(idx);
 			infos[idx].repeatStart = true;
 		}
 
@@ -769,6 +834,16 @@ const abcLayoutToStaves = (layout: ABC.StaffGroup[]): string | null => {
  * `voiceInstr` maps an ABC voice number to its {name, shortName}. The layout's staff ids
  * are arc-first voice numbers, so a staff id "5" looks up voice 5's name.
  */
+
+// ABC quoted strings carry literal escape sequences (e.g. `nm="Violin\nsolo"` is the 11
+// characters V-i-o-l-i-n-\-n-s-o-l-o). The lilylet doc model holds DECODED strings — the
+// serializer's escapeString re-encodes a real newline back to `\n`. Without decoding here,
+// the stored backslash would be escaped a second time (`\n` → `\\n`). Mirror the lilylet
+// grammar's `unq` unescape table so both import paths agree.
+const ABC_UNESCAPE: { [c: string]: string } = { n: "\n", r: "\r", t: "\t", '"': '"', "\\": "\\" };
+const unescapeAbcString = (s: string): string =>
+	s.replace(/\\(.)/g, (m, c) => (c in ABC_UNESCAPE ? ABC_UNESCAPE[c] : m));
+
 const abcInstrumentsToLilylet = (
 	stavesCode: string,
 	voiceInstr: Map<number, InstrumentName>,
@@ -1484,8 +1559,8 @@ const decodeTune = (tune: ABC.Tune, options: DecodeOptions = {}): LilyletDoc =>
 				if (isNaN(v)) continue;
 				const short = props.snm ?? props.sname;
 				voiceInstr.set(v, typeof short === "string" && short.length
-					? { name, shortName: short }
-					: { name });
+					? { name: unescapeAbcString(name), shortName: unescapeAbcString(short) }
+					: { name: unescapeAbcString(name) });
 			}
 			if (voiceInstr.size > 0) {
 				const instruments = abcInstrumentsToLilylet(metadata.staves, voiceInstr);
@@ -1519,6 +1594,11 @@ const decodeTune = (tune: ABC.Tune, options: DecodeOptions = {}): LilyletDoc =>
 	// parts are assembled (mirrors the MusicXML path attaching nav to a note).
 	const navMarksByMeasure = new Map<number, Mark[]>();
 
+	// Running effective time signature (seeded from the header M:, updated by any inline
+	// [M:...] change). A bar whose played length is SHORTER than this gets a \partial (see
+	// the pickup/anacrusis handling below the per-measure assembly).
+	let curTime: TimeSig | undefined = timeSig;
+
 	for (let mi = 0; mi < measures.length; mi++) {
 		const abcMeasure = measures[mi];
 
@@ -1726,6 +1806,62 @@ const decodeTune = (tune: ABC.Tune, options: DecodeOptions = {}): LilyletDoc =>
 			}
 		}
 
+		// Pickup / short bar → \partial. Update the running time signature from any inline
+		// [M:...] this bar carried (the LAST \time in the bar wins — a bar may restate then
+		// change meter, e.g. \time 3/4 \time 9/8), then compare the bar's played length (the
+		// longest voice, so a bar that is complete in ANY voice is not treated as short)
+		// against the meter's full-bar length. A strictly shorter bar is an anacrusis (bar 1)
+		// or a truncated final bar; emit \partial <bar-length> on the first voice so LilyPond
+		// renders the incomplete bar. A full-measure rest (Z/R) voice is skipped — it fills the
+		// bar by definition, so it must not drag the measured length down.
+		{
+			for (const part of parts) {
+				for (const voice of part.voices) {
+					for (const e of voice.events) {
+						if (e.type === "context" && (e as ContextChange).time) {
+							const t = (e as ContextChange).time!;
+							curTime = { numerator: t.numerator, denominator: t.denominator };
+						}
+					}
+				}
+			}
+			if (curTime) {
+				const barTicks = WHOLE_TICKS * curTime.numerator / curTime.denominator;
+				// \partial is a GLOBAL timing directive — it shortens the bar for every voice at
+				// once. So it is only correct when every sounding voice has the SAME short length.
+				// Collect each voice's played ticks; a full-measure-rest (Z/R) voice fills the bar
+				// and is ignored. If the voices are ragged (different lengths — e.g. a messy meter
+				// change where some voices are 6/8 and others 8/8), no single \partial fits them
+				// all, so we emit none rather than one that mis-sizes some voices.
+				const lengths: number[] = [];
+				let anyFull = false;
+				for (const part of parts) {
+					for (const voice of part.voices) {
+						if (voice.events.some(e => e.type === "rest" && (e as RestEvent).fullMeasure)) { anyFull = true; continue; }
+						const t = eventsTicks(voice.events);
+						if (t > 0) lengths.push(t);
+					}
+				}
+				const uniform = lengths.length > 0 && lengths.every(t => t === lengths[0]);
+				const played = uniform ? lengths[0] : 0;
+				if (!anyFull && uniform && played < barTicks) {
+					const partial = ticksToPartialDuration(played);
+					if (partial) {
+						// Insert after any leading key/time context so the emitted order is
+						// \key … \time … \partial …  (LilyPond wants \partial after \time).
+						const target = measure.parts[0]?.voices[0];
+						if (target) {
+							let at = 0;
+							while (at < target.events.length && target.events[at].type === "context"
+								&& ((target.events[at] as ContextChange).key || (target.events[at] as ContextChange).time)
+								&& !(target.events[at] as ContextChange).clef) at++;
+							target.events.splice(at, 0, { type: "context", partial } as ContextChange);
+						}
+					}
+				}
+			}
+		}
+
 		lilyletMeasures.push(measure);
 	}