@k-l-lambda/lilylet 0.1.67 → 0.1.69

package/lib/lilylet/abcDecoder.d.ts

@@ -4,22 +4,28 @@
  * Converts ABC notation files to Lilylet's internal LilyletDoc format.
  */
 import { LilyletDoc } from "./types";
+/**
+ * Decode an ABC tune into a LilyletDoc
+ */
+export interface DecodeOptions {
+    catalogComments?: boolean;
+}
 /**
  * Decode ABC notation string to LilyletDoc.
  * If the ABC contains multiple tunes, only the first is decoded.
  */
-export declare const decode: (abcString: string) => LilyletDoc;
+export declare const decode: (abcString: string, options?: DecodeOptions) => LilyletDoc;
 /**
  * Decode ABC notation string to multiple LilyletDocs (one per tune).
  */
-export declare const decodeAll: (abcString: string) => LilyletDoc[];
+export declare const decodeAll: (abcString: string, options?: DecodeOptions) => LilyletDoc[];
 /**
  * Decode an ABC file to LilyletDoc
  */
-export declare const decodeFile: (filePath: string) => Promise<LilyletDoc>;
+export declare const decodeFile: (filePath: string, options?: DecodeOptions) => Promise<LilyletDoc>;
 declare const _default: {
-    decode: (abcString: string) => LilyletDoc;
-    decodeAll: (abcString: string) => LilyletDoc[];
-    decodeFile: (filePath: string) => Promise<LilyletDoc>;
+    decode: (abcString: string, options?: DecodeOptions) => LilyletDoc;
+    decodeAll: (abcString: string, options?: DecodeOptions) => LilyletDoc[];
+    decodeFile: (filePath: string, options?: DecodeOptions) => Promise<LilyletDoc>;
 };
 export default _default;

package/lib/lilylet/abcDecoder.js

@@ -4,7 +4,7 @@
  * Converts ABC notation files to Lilylet's internal LilyletDoc format.
  */
 import parse from "../abc/parser.js";
-import { Phonet, Accidental, ArticulationType, OrnamentType, DynamicType, HairpinType, PedalType, NavigationMarkType, } from "./types.js";
+import { Phonet, Accidental, ArticulationType, OrnamentType, DynamicType, HairpinType, PedalType, NavigationMarkType, Placement, } from "./types.js";
 // ============ Constants ============
 // NotaGen catalog tags appear as leading single-% comments in ABC files,
 // in the order: period, composer, instrumentation. They are mapped to
@@ -91,7 +91,7 @@ const convertAccidental = (acc) => {
  * Uppercase C-B = octave 0, lowercase c-b = octave 1
  * quotes (from ' and ,) add/subtract octaves
  */
-const convertPitch = (abcPitch) => {
+const convertPitch = (abcPitch, ctx) => {
     const phonet = ABC_PHONET_MAP[abcPitch.phonet];
     if (!phonet) {
         throw new Error(`Unknown ABC phonet: ${abcPitch.phonet}`);
@@ -101,9 +101,38 @@ const convertPitch = (abcPitch) => {
     const baseOctave = isLower ? 1 : 0;
     const octave = baseOctave + (abcPitch.quotes || 0);
     const pitch = { phonet, octave };
-    const accidental = convertAccidental(abcPitch.acc);
-    if (accidental) {
-        pitch.accidental = accidental;
+    // Resolve the effective accidental.
+    const explicit = convertAccidental(abcPitch.acc); // accidental written on this note
+    const hasExplicit = abcPitch.acc !== null && abcPitch.acc !== undefined;
+    if (ctx) {
+        const memKey = `${phonet}:${octave}`;
+        if (hasExplicit) {
+            // Explicit accidental (incl. natural) overrides and is remembered for the measure.
+            if (abcPitch.acc === 0) {
+                ctx.measureAccidentals.set(memKey, "natural");
+                // natural cancels the key alteration → no accidental on the lilylet pitch
+            }
+            else if (explicit) {
+                ctx.measureAccidentals.set(memKey, explicit);
+                pitch.accidental = explicit;
+            }
+        }
+        else {
+            // No explicit accidental: inherit from in-measure memory, else the key signature.
+            const remembered = ctx.measureAccidentals.get(memKey);
+            if (remembered !== undefined) {
+                if (remembered !== "natural")
+                    pitch.accidental = remembered;
+            }
+            else {
+                const fromKey = ctx.keyAlterations.get(phonet);
+                if (fromKey)
+                    pitch.accidental = fromKey;
+            }
+        }
+    }
+    else if (explicit) {
+        pitch.accidental = explicit;
     }
     return pitch;
 };
@@ -260,6 +289,45 @@ const convertKeySignature = (abcKey) => {
         mode: (abcKey.mode === "minor" || abcKey.mode === "min") ? "minor" : "major",
     };
 };
+// Circle-of-fifths: a lilylet key (pitch+accidental+mode) → set of letters the key
+// signature alters, and the direction (sharp/flat). ABC note letters inherit these
+// alterations implicitly (e.g. K:Eb makes B sound as Bb); lilylet pitches are absolute,
+// so the decoder must bake the alteration into each pitch's accidental.
+const SHARP_ORDER = [Phonet.f, Phonet.c, Phonet.g, Phonet.d, Phonet.a, Phonet.e, Phonet.b];
+const FLAT_ORDER = [Phonet.b, Phonet.e, Phonet.a, Phonet.d, Phonet.g, Phonet.c, Phonet.f];
+const KEY_NAME_TO_FIFTHS = {
+    c: 0, g: 1, d: 2, a: 3, e: 4, b: 5, "f#": 6, "c#": 7,
+    f: -1, bb: -2, eb: -3, ab: -4, db: -5, gb: -6, cb: -7,
+};
+// Compute the number of sharps/flats (fifths) for a resolved KeySignature.
+const keySignatureFifths = (key) => {
+    let letter = key.pitch;
+    if (key.accidental === Accidental.sharp)
+        letter += "#";
+    else if (key.accidental === Accidental.flat)
+        letter += "b";
+    let fifths = KEY_NAME_TO_FIFTHS[letter];
+    if (fifths === undefined)
+        fifths = 0;
+    // Minor keys share the fifths of their relative major (3 fifths up).
+    if (key.mode === "minor")
+        fifths += 3;
+    return fifths;
+};
+// Map of phonet → accidental implied by the key signature (only altered letters present).
+const keySignatureAlterations = (key) => {
+    const fifths = keySignatureFifths(key);
+    const map = new Map();
+    if (fifths > 0) {
+        for (let i = 0; i < fifths && i < SHARP_ORDER.length; i++)
+            map.set(SHARP_ORDER[i], Accidental.sharp);
+    }
+    else if (fifths < 0) {
+        for (let i = 0; i < -fifths && i < FLAT_ORDER.length; i++)
+            map.set(FLAT_ORDER[i], Accidental.flat);
+    }
+    return map;
+};
 /**
  * Convert ABC clef string to Lilylet Clef
  */
@@ -492,13 +560,17 @@ const processExpressiveTerm = (term, pendingMarks, pendingContextChanges, slurDe
 /**
  * Process a single ABC BarPatch (one voice's content for one measure) into events.
  */
-const processBarPatch = (patch, unitLength, slurDepth) => {
+const processBarPatch = (patch, unitLength, slurDepth, pitchCtx) => {
     const events = [];
     const terms = patch.terms || [];
     const pendingMarks = [];
     const pendingContextChanges = [];
     // Collect all events first, then handle broken rhythms and tuplets
     const rawNoteRests = [];
+    // A broken-rhythm marker (>, <) belongs to the LEFT note but modifies the pair
+    // (left, right). We can only apply it once the right note has been pushed, so we
+    // stash it here and resolve it when the next note/rest arrives.
+    let pendingBroken = null;
     let i = 0;
     while (i < terms.length) {
         const term = terms[i];
@@ -513,10 +585,19 @@ const processBarPatch = (patch, unitLength, slurDepth) => {
                     }
                 }
                 else if (ctrl.value?.root) {
+                    const newKey = convertKeySignature(ctrl.value);
                     events.push({
                         type: "context",
-                        key: convertKeySignature(ctrl.value),
+                        key: newKey,
                     });
+                    // Update the active key alterations and clear in-measure accidentals.
+                    if (pitchCtx) {
+                        const alt = keySignatureAlterations(newKey);
+                        pitchCtx.keyAlterations.clear();
+                        for (const [k, v] of alt)
+                            pitchCtx.keyAlterations.set(k, v);
+                        pitchCtx.measureAccidentals.clear();
+                    }
                 }
             }
             else if (ctrl.name === "M") {
@@ -555,7 +636,7 @@ const processBarPatch = (patch, unitLength, slurDepth) => {
             while (j < terms.length && collected < r) {
                 const nextTerm = terms[j];
                 if (nextTerm.event) {
-                    const evt = convertEventTerm(nextTerm, unitLength, pendingMarks, pendingContextChanges);
+                    const evt = convertEventTerm(nextTerm, unitLength, pendingMarks, pendingContextChanges, pitchCtx);
                     if (evt) {
                         // Push any pending context changes before tuplet
                         for (const ctx of pendingContextChanges.splice(0)) {
@@ -600,7 +681,7 @@ const processBarPatch = (patch, unitLength, slurDepth) => {
         }
         // Grace notes
         if (term.grace) {
-            const graceEvents = convertGraceEvents(term, unitLength);
+            const graceEvents = convertGraceEvents(term, unitLength, pitchCtx);
             events.push(...graceEvents);
             i++;
             continue;
@@ -614,10 +695,25 @@ const processBarPatch = (patch, unitLength, slurDepth) => {
         // Text
         if (term.text !== undefined) {
             const text = term.text;
-            // Check if it's a tempo/expression marking
+            // ABC chord/annotation text: a leading ^ / _ marks placement above / below;
+            // other position prefixes (<,>,@) just denote placement we don't model, so strip.
+            let placement;
+            let content = text;
             if (text.startsWith("^")) {
-                // Markup text above staff
+                placement = Placement.above;
+                content = text.slice(1);
+            }
+            else if (text.startsWith("_")) {
+                placement = Placement.below;
+                content = text.slice(1);
+            }
+            else if (/^[<>@]/.test(text)) {
+                content = text.slice(1);
             }
+            const markup = { type: "markup", content };
+            if (placement)
+                markup.placement = placement;
+            events.push(markup);
             i++;
             continue;
         }
@@ -628,7 +724,7 @@ const processBarPatch = (patch, unitLength, slurDepth) => {
             for (const ctx of pendingContextChanges.splice(0)) {
                 events.push(ctx);
             }
-            const evt = convertEventTerm(eventTerm, unitLength, pendingMarks, pendingContextChanges);
+            const evt = convertEventTerm(eventTerm, unitLength, pendingMarks, pendingContextChanges, pitchCtx);
             if (evt) {
                 if (Array.isArray(evt)) {
                     events.push(...evt);
@@ -636,12 +732,18 @@ const processBarPatch = (patch, unitLength, slurDepth) => {
                 else {
                     events.push(evt);
                 }
-                // Track broken rhythm
-                if (eventTerm.broken) {
+                // Resolve a broken-rhythm marker carried by the PREVIOUS note: it modifies
+                // the pair (previous note, this note). Apply now that this (the right) note exists.
+                if (pendingBroken !== null) {
                     const noteRestEvents = events.filter(e => e.type === "note" || e.type === "rest");
                     if (noteRestEvents.length >= 2) {
-                        applyBrokenRhythm(noteRestEvents, noteRestEvents.length - 2, eventTerm.broken);
+                        applyBrokenRhythm(noteRestEvents, noteRestEvents.length - 2, pendingBroken);
                     }
+                    pendingBroken = null;
+                }
+                // Stash this note's own broken marker (the right note is not parsed yet).
+                if (eventTerm.broken) {
+                    pendingBroken = eventTerm.broken;
                 }
             }
             i++;
@@ -687,7 +789,7 @@ const getDefaultTupletMultiplier = (p) => {
 /**
  * Convert a single ABC EventTerm to Lilylet event(s)
  */
-const convertEventTerm = (eventTerm, unitLength, pendingMarks, pendingContextChanges) => {
+const convertEventTerm = (eventTerm, unitLength, pendingMarks, pendingContextChanges, pitchCtx) => {
     const eventData = eventTerm.event;
     if (!eventData)
         return undefined;
@@ -708,12 +810,20 @@ const convertEventTerm = (eventTerm, unitLength, pendingMarks, pendingContextCha
         if (firstPitch.phonet === "Z") {
             rest.fullMeasure = true;
         }
-        // Consume pending marks (attach to rest if any)
+        // A dynamic that precedes a rest (e.g. ABC "!p! z") has no note to attach to.
+        // Emit it as a standalone leading DynamicEvent before the rest; lilylet attaches
+        // it to the following sounding event. Other marks on a rest are dropped.
+        const leadingDynamics = pendingMarks
+            .filter(m => m.markType === "dynamic")
+            .map(m => ({ type: "dynamic", dynamicType: m.type }));
         pendingMarks.length = 0;
+        if (leadingDynamics.length > 0) {
+            return [...leadingDynamics, rest];
+        }
         return rest;
     }
     // Note or chord
-    const pitches = chord.pitches.filter(p => p.phonet !== "z" && p.phonet !== "Z" && p.phonet !== "x" && p.phonet !== "y").map(convertPitch);
+    const pitches = chord.pitches.filter(p => p.phonet !== "z" && p.phonet !== "Z" && p.phonet !== "x" && p.phonet !== "y").map(p => convertPitch(p, pitchCtx));
     if (pitches.length === 0)
         return undefined;
     const duration = convertDuration(eventData.duration, unitLength);
@@ -742,7 +852,7 @@ const convertEventTerm = (eventTerm, unitLength, pendingMarks, pendingContextCha
 /**
  * Convert grace notes to NoteEvents with grace flag
  */
-const convertGraceEvents = (graceTerm, unitLength) => {
+const convertGraceEvents = (graceTerm, unitLength, pitchCtx) => {
     const events = [];
     if (!graceTerm.events)
         return events;
@@ -752,7 +862,7 @@ const convertGraceEvents = (graceTerm, unitLength) => {
             const chord = eventData.chord;
             if (!chord || !chord.pitches)
                 continue;
-            const pitches = chord.pitches.filter((p) => p.phonet !== "z" && p.phonet !== "Z" && p.phonet !== "x").map(convertPitch);
+            const pitches = chord.pitches.filter((p) => p.phonet !== "z" && p.phonet !== "Z" && p.phonet !== "x").map((p) => convertPitch(p, pitchCtx));
             if (pitches.length === 0)
                 continue;
             const duration = convertDuration(eventData.duration, unitLength);
@@ -767,11 +877,7 @@ const convertGraceEvents = (graceTerm, unitLength) => {
     }
     return events;
 };
-// ============ Main Decoder ============
-/**
- * Decode an ABC tune into a LilyletDoc
- */
-const decodeTune = (tune) => {
+const decodeTune = (tune, options = {}) => {
     const headers = tune.header;
     const body = tune.body;
     // Extract header fields
@@ -793,13 +899,15 @@ const decodeTune = (tune) => {
     for (const h of headers) {
         const comment = h.comment;
         if (typeof comment === "string") {
-            const value = comment.trim();
-            if (!metadata.genre && NOTAGEN_PERIOD_SET.has(value))
-                metadata.genre = value;
-            else if (!metadata.instrument && NOTAGEN_INSTRUMENTATION_SET.has(value))
-                metadata.instrument = value;
-            else if (!metadata.composer && NOTAGEN_COMPOSER_SET.has(value))
-                metadata.composer = value;
+            if (options.catalogComments) {
+                const value = comment.trim();
+                if (!metadata.genre && NOTAGEN_PERIOD_SET.has(value))
+                    metadata.genre = value;
+                else if (!metadata.instrument && NOTAGEN_INSTRUMENTATION_SET.has(value))
+                    metadata.instrument = value;
+                else if (!metadata.composer && NOTAGEN_COMPOSER_SET.has(value))
+                    metadata.composer = value;
+            }
             continue;
         }
         if (h.staffLayout)
@@ -891,6 +999,11 @@ const decodeTune = (tune) => {
     // ABC measures contain BarPatches, each with a voice control V:n
     const measures = body.measures;
     const voiceSlurDepths = new Map();
+    // Per-voice key alterations (persist across measures; mutated by inline [K:] changes).
+    // Initialized from the tune's header key signature so bare ABC letters pick up the
+    // key's sharps/flats, which lilylet pitches must carry explicitly.
+    const initialKeyAlterations = keySig ? keySignatureAlterations(keySig) : new Map();
+    const voiceKeyAlterations = new Map();
     // Process each ABC measure into Lilylet Measure
     const lilyletMeasures = [];
     for (let mi = 0; mi < measures.length; mi++) {
@@ -909,11 +1022,20 @@ const decodeTune = (tune) => {
         for (const [voiceNum, patches] of voicePatches) {
             const slurDepth = voiceSlurDepths.get(voiceNum) || { count: 0 };
             voiceSlurDepths.set(voiceNum, slurDepth);
+            // Resolve this voice's persistent key alterations (seeded from the header key).
+            if (!voiceKeyAlterations.has(voiceNum)) {
+                voiceKeyAlterations.set(voiceNum, new Map(initialKeyAlterations));
+            }
+            // Fresh in-measure accidental memory for each measure (standard notation rule).
+            const pitchCtx = {
+                keyAlterations: voiceKeyAlterations.get(voiceNum),
+                measureAccidentals: new Map(),
+            };
             // Merge all patches for this voice in this measure
             const allEvents = [];
             let barline;
             for (const patch of patches) {
-                const result = processBarPatch(patch, unitLength, slurDepth);
+                const result = processBarPatch(patch, unitLength, slurDepth, pitchCtx);
                 allEvents.push(...result.events);
                 if (result.barline && result.barline !== "|") {
                     barline = result.barline;
@@ -1013,30 +1135,30 @@ const decodeTune = (tune) => {
  * Decode ABC notation string to LilyletDoc.
  * If the ABC contains multiple tunes, only the first is decoded.
  */
-export const decode = (abcString) => {
+export const decode = (abcString, options = {}) => {
     const tunes = parse(abcString);
     if (!tunes || tunes.length === 0) {
         throw new Error("No tunes found in ABC notation");
     }
-    return decodeTune(tunes[0]);
+    return decodeTune(tunes[0], options);
 };
 /**
  * Decode ABC notation string to multiple LilyletDocs (one per tune).
  */
-export const decodeAll = (abcString) => {
+export const decodeAll = (abcString, options = {}) => {
     const tunes = parse(abcString);
     if (!tunes || tunes.length === 0) {
         throw new Error("No tunes found in ABC notation");
     }
-    return tunes.map(decodeTune);
+    return tunes.map(t => decodeTune(t, options));
 };
 /**
  * Decode an ABC file to LilyletDoc
  */
-export const decodeFile = async (filePath) => {
+export const decodeFile = async (filePath, options = {}) => {
     const fs = await import("fs/promises");
     const content = await fs.readFile(filePath, "utf-8");
-    return decode(content);
+    return decode(content, options);
 };
 export default {
     decode,