@k-l-lambda/lilylet 0.1.66 → 0.1.68

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,8 +4,35 @@
  * Converts ABC notation files to Lilylet's internal LilyletDoc format.
  */
 import parse from "../abc/parser.js";
-import { Phonet, Accidental, Clef, 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
+// Lilylet metadata: period -> genre, instrumentation -> instrument.
+const NOTAGEN_PERIOD_SET = new Set([
+    "Baroque", "Classical", "Romantic",
+]);
+const NOTAGEN_INSTRUMENTATION_SET = new Set([
+    "Art Song", "Chamber", "Choral", "Keyboard", "Orchestral", "Vocal-Orchestral",
+]);
+const NOTAGEN_COMPOSER_SET = new Set([
+    "Bach, Johann Sebastian", "Bartok, Bela", "Beethoven, Ludwig van", "Berlioz, Hector",
+    "Bizet, Georges", "Boulanger, Lili", "Boulton, Harold", "Brahms, Johannes",
+    "Burgmuller, Friedrich", "Butterworth, George", "Chaminade, Cecile", "Chausson, Ernest",
+    "Chopin, Frederic", "Corelli, Arcangelo", "Cornelius, Peter", "Debussy, Claude",
+    "Dvorak, Antonin", "Faisst, Clara", "Faure, Gabriel", "Franz, Robert",
+    "Gonzaga, Chiquinha", "Grandval, Clemence de", "Grieg, Edvard", "Handel, George Frideric",
+    "Haydn, Joseph", "Hensel, Fanny", "Holmes, Augusta Mary Anne", "Jaell, Marie",
+    "Kinkel, Johanna", "Kralik, Mathilde", "Lang, Josephine", "Lehmann, Liza",
+    "Liszt, Franz", "Mayer, Emilie", "Medtner, Nikolay", "Mendelssohn, Felix",
+    "Mozart, Wolfgang Amadeus", "Munktell, Helena", "Paradis, Maria Theresia von",
+    "Parratt, Walter", "Prokofiev, Sergey", "Rachmaninoff, Sergei", "Ravel, Maurice",
+    "Reichardt, Louise", "Saint-Georges, Joseph Bologne", "Saint-Saens, Camille",
+    "Satie, Erik", "Scarlatti, Domenico", "Schroter, Corona", "Schubert, Franz",
+    "Schumann, Clara", "Schumann, Robert", "Scriabin, Aleksandr", "Shostakovich, Dmitry",
+    "Sibelius, Jean", "Smetana, Bedrich", "Tchaikovsky, Pyotr", "Viardot, Pauline",
+    "Vivaldi, Antonio", "Warlock, Peter", "Wolf, Hugo", "Zumsteeg, Emilie",
+]);
 const ABC_PHONET_MAP = {
     "C": Phonet.c, "D": Phonet.d, "E": Phonet.e, "F": Phonet.f, "G": Phonet.g, "A": Phonet.a, "B": Phonet.b,
     "c": Phonet.c, "d": Phonet.d, "e": Phonet.e, "f": Phonet.f, "g": Phonet.g, "a": Phonet.a, "b": Phonet.b,
@@ -64,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}`);
@@ -74,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;
 };
@@ -233,17 +289,71 @@ 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
  */
 const convertClef = (clefStr) => {
-    switch (clefStr?.toLowerCase()) {
-        case "treble": return Clef.treble;
-        case "bass": return Clef.bass;
+    // Split off an optional ABC octave shift suffix: "treble-8", "bass+8", "treble-15".
+    // ABC: "-N" lowers the sounding pitch (small N drawn below), "+N" raises it.
+    // LilyPond/Lilylet: "_N" = below, "^N" = above. Translate the sign accordingly.
+    const shift = clefStr?.match(/^(.*?)([+-])(8|15)$/);
+    const base = shift ? shift[1] : clefStr;
+    let resolved;
+    switch (base?.toLowerCase()) {
+        case "treble":
+            resolved = "treble";
+            break;
+        case "bass":
+            resolved = "bass";
+            break;
         case "alto":
-        case "tenor": return Clef.alto;
+        case "tenor":
+            resolved = "alto";
+            break;
         default: return undefined;
     }
+    if (shift)
+        resolved += (shift[2] === "-" ? "_" : "^") + shift[3];
+    return resolved;
 };
 /**
  * Convert ABC barline to Lilylet barline style
@@ -267,11 +377,41 @@ const convertBarline = (bar) => {
             return "|";
     }
 };
-/**
- * Parse %%score layout to determine voice→(part, staff) mapping.
- * {(...) | (...)} = one part with two staves
- * (...) = voices sharing one staff
- */
+// All voice numbers under a node, flattened.
+const collectScoreVoices = (node) => {
+    if (typeof node === "string") {
+        const v = parseInt(node, 10);
+        return isNaN(v) ? [] : [v];
+    }
+    const voices = [];
+    for (const item of node.items || []) {
+        voices.push(...collectScoreVoices(item));
+    }
+    return voices;
+};
+// Expand a node into a list of parts; each part is a list of staves; each staff is a list of voices.
+const scoreNodeToParts = (node) => {
+    if (typeof node === "string") {
+        const v = parseInt(node, 10);
+        return isNaN(v) ? [] : [[[v]]];
+    }
+    if (node.bound === "square") {
+        // each child is its own part
+        const parts = [];
+        for (const child of node.items || []) {
+            parts.push(...scoreNodeToParts(child));
+        }
+        return parts;
+    }
+    if (node.bound === "curly") {
+        // one part, each child is a separate staff (grand staff)
+        const staves = (node.items || []).map(child => collectScoreVoices(child)).filter(s => s.length > 0);
+        return staves.length > 0 ? [staves] : [];
+    }
+    // arc or no bound: one part, all voices on a single staff
+    const voices = collectScoreVoices(node);
+    return voices.length > 0 ? [[voices]] : [];
+};
 const parseScoreLayout = (headers) => {
     const layoutHeader = headers.find((h) => h.staffLayout);
     if (!layoutHeader)
@@ -279,86 +419,15 @@ const parseScoreLayout = (headers) => {
     const layout = layoutHeader.staffLayout;
     const voiceMap = new Map();
     let partIndex = 0;
-    for (const group of layout) {
-        if (group.bound === "curly") {
-            // Curly braces = one instrument/part with multiple staves
-            let staffInPart = 1;
-            for (const item of group.items) {
-                if (typeof item === "string") {
-                    voiceMap.set(parseInt(item), { partIndex, staffInPart });
+    for (const top of layout) {
+        for (const part of scoreNodeToParts(top)) {
+            part.forEach((staff, staffIdx) => {
+                for (const voice of staff) {
+                    voiceMap.set(voice, { partIndex, staffInPart: staffIdx + 1 });
                 }
-                else if (item.items) {
-                    const sg = item;
-                    for (const subItem of sg.items) {
-                        if (typeof subItem === "string") {
-                            voiceMap.set(parseInt(subItem), { partIndex, staffInPart });
-                        }
-                        else if (subItem.items) {
-                            for (const leaf of subItem.items) {
-                                if (typeof leaf === "string") {
-                                    voiceMap.set(parseInt(leaf), { partIndex, staffInPart });
-                                }
-                            }
-                        }
-                    }
-                    staffInPart++;
-                }
-            }
-            partIndex++;
-        }
-        else if (group.bound === "arc" || !group.bound) {
-            // Arc or plain = voices sharing a staff in same part
-            for (const item of group.items) {
-                if (typeof item === "string") {
-                    voiceMap.set(parseInt(item), { partIndex, staffInPart: 1 });
-                }
-                else if (item.items) {
-                    for (const subItem of item.items) {
-                        if (typeof subItem === "string") {
-                            voiceMap.set(parseInt(subItem), { partIndex, staffInPart: 1 });
-                        }
-                    }
-                }
-            }
+            });
             partIndex++;
         }
-        else {
-            // Square bracket or unknown - treat each item as separate part
-            for (const item of group.items) {
-                if (typeof item === "string") {
-                    voiceMap.set(parseInt(item), { partIndex, staffInPart: 1 });
-                    partIndex++;
-                }
-                else if (item.items) {
-                    const sg = item;
-                    if (sg.bound === "curly") {
-                        let staffInPart = 1;
-                        for (const subItem of sg.items) {
-                            if (typeof subItem === "string") {
-                                voiceMap.set(parseInt(subItem), { partIndex, staffInPart });
-                            }
-                            else if (subItem.items) {
-                                for (const leaf of subItem.items) {
-                                    if (typeof leaf === "string") {
-                                        voiceMap.set(parseInt(leaf), { partIndex, staffInPart });
-                                    }
-                                }
-                                staffInPart++;
-                            }
-                        }
-                        partIndex++;
-                    }
-                    else {
-                        for (const subItem of sg.items) {
-                            if (typeof subItem === "string") {
-                                voiceMap.set(parseInt(subItem), { partIndex, staffInPart: 1 });
-                            }
-                        }
-                        partIndex++;
-                    }
-                }
-            }
-        }
     }
     return voiceMap.size > 0 ? voiceMap : null;
 };
@@ -491,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];
@@ -512,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") {
@@ -554,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)) {
@@ -613,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;
         }
@@ -627,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);
@@ -635,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++;
@@ -686,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;
@@ -707,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);
@@ -766,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
@@ -790,8 +897,19 @@ const decodeTune = (tune) => {
         }
     }
     for (const h of headers) {
-        if (h.comment)
+        const comment = h.comment;
+        if (typeof comment === "string") {
+            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)
             continue;
         const header = h;
@@ -881,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++) {
@@ -899,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;
@@ -1003,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,