@k-l-lambda/lilylet 0.1.66 → 0.1.68

package/source/lilylet/abcDecoder.ts

@@ -34,11 +34,42 @@ import {
 	NavigationMarkType,
 	Tempo,
 	BarlineEvent,
+	MarkupEvent,
+	DynamicEvent,
+	Placement,
 } from "./types";
 
 
 // ============ 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: Record<string, Phonet> = {
 	"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,
@@ -97,12 +128,25 @@ const convertAccidental = (acc: number | null): Accidental | undefined => {
 	}
 };
 
+/**
+ * Pitch-conversion context for resolving ABC's implicit accidentals into lilylet's
+ * absolute pitch model. ABC applies the key signature and in-measure accidentals
+ * implicitly to bare note letters; lilylet note names carry their own accidental, so
+ * we resolve the effective accidental here.
+ */
+interface PitchContext {
+	keyAlterations: Map<Phonet, Accidental>;  // letters altered by the active key signature
+	// In-measure accidental memory, keyed by "phonet:octave". An explicit accidental
+	// persists for the rest of the measure at that pitch/octave (standard notation rule).
+	measureAccidentals: Map<string, Accidental | "natural">;
+}
+
 /**
  * Convert ABC pitch to Lilylet Pitch
  * Uppercase C-B = octave 0, lowercase c-b = octave 1
  * quotes (from ' and ,) add/subtract octaves
  */
-const convertPitch = (abcPitch: ABC.Pitch): Pitch => {
+const convertPitch = (abcPitch: ABC.Pitch, ctx?: PitchContext): Pitch => {
 	const phonet = ABC_PHONET_MAP[abcPitch.phonet];
 	if (!phonet) {
 		throw new Error(`Unknown ABC phonet: ${abcPitch.phonet}`);
@@ -114,10 +158,36 @@ const convertPitch = (abcPitch: ABC.Pitch): Pitch => {
 	const octave = baseOctave + (abcPitch.quotes || 0);
 
 	const pitch: 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;
 };
 
@@ -282,16 +352,60 @@ const convertKeySignature = (abcKey: ABC.KeySignature): KeySignature => {
 	};
 };
 
+// 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[] = [Phonet.f, Phonet.c, Phonet.g, Phonet.d, Phonet.a, Phonet.e, Phonet.b];
+const FLAT_ORDER: Phonet[] = [Phonet.b, Phonet.e, Phonet.a, Phonet.d, Phonet.g, Phonet.c, Phonet.f];
+
+const KEY_NAME_TO_FIFTHS: Record<string, number> = {
+	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: KeySignature): number => {
+	let letter = key.pitch as string;
+	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: KeySignature): Map<Phonet, Accidental> => {
+	const fifths = keySignatureFifths(key);
+	const map = new Map<Phonet, Accidental>();
+	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: string): Clef | undefined => {
-	switch (clefStr?.toLowerCase()) {
-		case "treble": return Clef.treble;
-		case "bass": return Clef.bass;
-		case "alto": case "tenor": return Clef.alto;
+	// 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: string | undefined;
+	switch (base?.toLowerCase()) {
+		case "treble": resolved = "treble"; break;
+		case "bass": resolved = "bass"; break;
+		case "alto": case "tenor": resolved = "alto"; break;
 		default: return undefined;
 	}
+	if (shift) resolved += (shift[2] === "-" ? "_" : "^") + shift[3];
+	return resolved as Clef;
 };
 
 /**
@@ -323,9 +437,60 @@ interface StaffAssignment {
 
 /**
  * Parse %%score layout to determine voice→(part, staff) mapping.
- * {(...) | (...)} = one part with two staves
- * (...) = voices sharing one staff
+ *
+ * Grouping semantics (recursive, any nesting depth):
+ *   [ ... ]  square: each child becomes a separate part        -> serialized with \\\
+ *   ( ... )  arc:    all voices share one staff in one part     -> voices joined with \\
+ *   { ... }  curly:  one part, each child is a separate staff   -> grand staff
+ *   leaf     a bare voice number "1" (often wrapped as {items:["1"]}) -> one part, one staff
+ *
+ * The AST wraps each leaf voice one level deep, e.g. ( 1 2 ) becomes
+ *   {bound:'arc', items:[{items:['1']},{items:['2']}]}
+ * so leaves must be collected recursively rather than assuming a fixed depth.
  */
+
+type ScoreNode = ABC.StaffGroup | string;
+
+// All voice numbers under a node, flattened.
+const collectScoreVoices = (node: ScoreNode): number[] => {
+	if (typeof node === "string") {
+		const v = parseInt(node, 10);
+		return isNaN(v) ? [] : [v];
+	}
+	const voices: number[] = [];
+	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: ScoreNode): number[][][] => {
+	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: number[][][] = [];
+		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: any[]
 ): Map<number, StaffAssignment> | null => {
@@ -336,78 +501,14 @@ const parseScoreLayout = (
 	const voiceMap = new Map<number, StaffAssignment>();
 
 	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 });
-				} else if ((item as ABC.StaffGroup).items) {
-					const sg = item as ABC.StaffGroup;
-					for (const subItem of sg.items) {
-						if (typeof subItem === "string") {
-							voiceMap.set(parseInt(subItem), { partIndex, staffInPart });
-						} else if ((subItem as ABC.StaffGroup).items) {
-							for (const leaf of (subItem as ABC.StaffGroup).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 as ABC.StaffGroup).items) {
-					for (const subItem of (item as ABC.StaffGroup).items) {
-						if (typeof subItem === "string") {
-							voiceMap.set(parseInt(subItem), { partIndex, staffInPart: 1 });
-						}
-					}
+	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 });
 				}
-			}
+			});
 			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 as ABC.StaffGroup).items) {
-					const sg = item as ABC.StaffGroup;
-					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 as ABC.StaffGroup).items) {
-								for (const leaf of (subItem as ABC.StaffGroup).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++;
-					}
-				}
-			}
 		}
 	}
 
@@ -544,7 +645,8 @@ interface VoiceConfig {
 const processBarPatch = (
 	patch: ABC.BarPatch,
 	unitLength: { numerator: number; denominator: number },
-	slurDepth: { count: number }
+	slurDepth: { count: number },
+	pitchCtx?: PitchContext
 ): { events: Event[]; barline?: string } => {
 	const events: Event[] = [];
 	const terms = patch.terms || [];
@@ -554,6 +656,11 @@ const processBarPatch = (
 	// Collect all events first, then handle broken rhythms and tuplets
 	const rawNoteRests: { event: NoteEvent | RestEvent; index: number; broken?: number }[] = [];
 
+	// 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: number | null = null;
+
 	let i = 0;
 	while (i < terms.length) {
 		const term = terms[i];
@@ -568,10 +675,18 @@ const processBarPatch = (
 						events.push({ type: "context", clef } as ContextChange);
 					}
 				} else if (ctrl.value?.root) {
+					const newKey = convertKeySignature(ctrl.value);
 					events.push({
 						type: "context",
-						key: convertKeySignature(ctrl.value),
+						key: newKey,
 					} as ContextChange);
+					// 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") {
 				if (ctrl.value?.numerator && ctrl.value?.denominator) {
@@ -609,7 +724,7 @@ const processBarPatch = (
 			while (j < terms.length && collected < r) {
 				const nextTerm = terms[j];
 				if ((nextTerm as ABC.EventTerm).event) {
-					const evt = convertEventTerm(nextTerm as ABC.EventTerm, unitLength, pendingMarks, pendingContextChanges);
+					const evt = convertEventTerm(nextTerm as ABC.EventTerm, unitLength, pendingMarks, pendingContextChanges, pitchCtx);
 					if (evt) {
 						// Push any pending context changes before tuplet
 						for (const ctx of pendingContextChanges.splice(0)) {
@@ -669,10 +784,16 @@ const processBarPatch = (
 		// Text
 		if ((term as ABC.TextTerm).text !== undefined) {
 			const text = (term as ABC.TextTerm).text;
-			// Check if it's a tempo/expression marking
-			if (text.startsWith("^")) {
-				// Markup text above staff
-			}
+			// ABC chord/annotation text: a leading ^ / _ marks placement above / below;
+			// other position prefixes (<,>,@) just denote placement we don't model, so strip.
+			let placement: Placement | undefined;
+			let content = text;
+			if (text.startsWith("^")) { 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: MarkupEvent = { type: "markup", content };
+			if (placement) markup.placement = placement;
+			events.push(markup);
 			i++;
 			continue;
 		}
@@ -686,7 +807,7 @@ const processBarPatch = (
 				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);
@@ -694,12 +815,19 @@ const processBarPatch = (
 					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") as (NoteEvent | RestEvent)[];
 					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++;
@@ -747,7 +875,8 @@ const convertEventTerm = (
 	eventTerm: ABC.EventTerm,
 	unitLength: { numerator: number; denominator: number },
 	pendingMarks: Mark[],
-	pendingContextChanges: ContextChange[]
+	pendingContextChanges: ContextChange[],
+	pitchCtx?: PitchContext
 ): Event | Event[] | undefined => {
 	const eventData = eventTerm.event;
 	if (!eventData) return undefined;
@@ -771,16 +900,24 @@ const convertEventTerm = (
 			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: DynamicEvent[] = pendingMarks
+			.filter(m => m.markType === "dynamic")
+			.map(m => ({ type: "dynamic", dynamicType: (m as { type: DynamicType }).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);
+	).map(p => convertPitch(p, pitchCtx));
 
 	if (pitches.length === 0) return undefined;
 
@@ -855,7 +992,14 @@ const convertGraceEvents = (
 /**
  * Decode an ABC tune into a LilyletDoc
  */
-const decodeTune = (tune: ABC.Tune): LilyletDoc => {
+export interface DecodeOptions {
+	// Extract NotaGen catalog metadata from the leading
+	// %period/%composer/%instrumentation comments. These are NotaGen's own
+	// convention, not standard ABC, so this is off by default.
+	catalogComments?: boolean;
+}
+
+const decodeTune = (tune: ABC.Tune, options: DecodeOptions = {}): LilyletDoc => {
 	const headers = tune.header;
 	const body = tune.body;
 
@@ -878,7 +1022,16 @@ const decodeTune = (tune: ABC.Tune): LilyletDoc => {
 	}
 
 	for (const h of headers) {
-		if ((h as any).comment) continue;
+		const comment = (h as any).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 as any).staffLayout) continue;
 
 		const header = h as { name: string; value: any };
@@ -966,6 +1119,12 @@ const decodeTune = (tune: ABC.Tune): LilyletDoc => {
 	const measures = body.measures;
 	const voiceSlurDepths = new Map<number, { count: number }>();
 
+	// 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<Phonet, Accidental>();
+	const voiceKeyAlterations = new Map<number, Map<Phonet, Accidental>>();
+
 	// Process each ABC measure into Lilylet Measure
 	const lilyletMeasures: Measure[] = [];
 
@@ -989,12 +1148,22 @@ const decodeTune = (tune: ABC.Tune): LilyletDoc => {
 			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: PitchContext = {
+				keyAlterations: voiceKeyAlterations.get(voiceNum)!,
+				measureAccidentals: new Map(),
+			};
+
 			// Merge all patches for this voice in this measure
 			const allEvents: Event[] = [];
 			let barline: string | undefined;
 
 			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;
@@ -1114,32 +1283,32 @@ const decodeTune = (tune: ABC.Tune): LilyletDoc => {
  * Decode ABC notation string to LilyletDoc.
  * If the ABC contains multiple tunes, only the first is decoded.
  */
-export const decode = (abcString: string): LilyletDoc => {
+export const decode = (abcString: string, options: DecodeOptions = {}): LilyletDoc => {
 	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: string): LilyletDoc[] => {
+export const decodeAll = (abcString: string, options: DecodeOptions = {}): LilyletDoc[] => {
 	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: string): Promise<LilyletDoc> => {
+export const decodeFile = async (filePath: string, options: DecodeOptions = {}): Promise<LilyletDoc> => {
 	const fs = await import("fs/promises");
 	const content = await fs.readFile(filePath, "utf-8");
-	return decode(content);
+	return decode(content, options);
 };
 
 export default {