@k-l-lambda/lilylet 0.1.88 → 0.1.90

package/lib/clefTransposition.d.ts

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

package/lib/clefTransposition.js

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

package/lib/lilylet/abcDecoder.js

@@ -7,6 +7,7 @@ import parse from "../abc/parser.js";
 import { Phonet, Accidental, ArticulationType, OrnamentType, DynamicType, HairpinType, PedalType, NavigationMarkType, Placement, } from "./types.js";
 import { parseStaffLayout, StaffGroupType } from "./staffLayout.js";
 import { buildMeasureLayout, applyNavText } from "./measureLayoutFromXml.js";
+import { parseClefSuffix, withClefTransposition } from "./clefTransposition.js";
 // ============ Constants ============
 // NotaGen catalog tags appear as leading single-% comments in ABC files,
 // in the order: period, composer, instrumentation. They are mapped to
@@ -426,28 +427,34 @@ const convertClef = (clefStr) => {
 };
 /**
  * Fold an ABC voice `transpose=N` property (a written→sounding shift in
- * SEMITONES) into the Lilylet clef-suffix form `_M` / `^M`, where M is a
- * diatonic interval number. ABC carries only semitones, so the diatonic
- * interval is approximated by the nearest scale-step count
- * (steps = round(semi * 7/12), interval number = |steps| + 1); `_` lowers,
- * `^` raises. The Lilylet→MEI encoder later expands the suffix back into
- * trans.diat / trans.semi (see meiEncoder.resolveClef). This is exact when the
- * semitone count is a major/perfect interval (e.g. -2, -9, +2, ±12) and a
- * nearest-interval approximation otherwise.
+ * SEMITONES) into the Lilylet clef suffix, which the →MEI encoder later expands
+ * into trans.diat / trans.semi (see meiEncoder.resolveClef).
+ *
+ * The conversion is EXACT: clefTransposition.semitonesToClefSuffix returns the
+ * suffix for the interval that spans exactly this many semitones, using the `m`
+ * (minor) form where the major/perfect interval does not fit — so -3 becomes
+ * `_m3` rather than the nearest major third `_3`. It previously approximated with
+ * round(semi * 7/12), which put a one-semitone error on the sounding pitch of
+ * every minor-interval transposition (-3 A clarinet, -8, -10 E-flat instruments:
+ * 37% of transposing voices in the corpora checked).
+ *
+ * A semitone count with no exact suffix (only the tritone, ±6, within an octave)
+ * is dropped with a warning rather than rounded: a silent one-semitone pitch error
+ * is worse than a visibly absent transposition.
  */
 const transposeClefSuffix = (clef, semitones) => {
     if (!clef || !semitones)
         return clef;
-    // A clef that already carries an octave suffix (treble_8 etc.) is left as-is;
-    // stacking another shift on top is not meaningful for ABC sources.
-    if (/[_^]\d+$/.test(clef))
+    // A clef that already carries a transposition suffix (treble_8 etc.) is left
+    // as-is; stacking another shift on top is not meaningful for ABC sources.
+    if (parseClefSuffix(clef))
         return clef;
-    const steps = Math.round((semitones * 7) / 12);
-    if (steps === 0)
+    const transposed = withClefTransposition(clef, semitones);
+    if (transposed === undefined) {
+        console.warn(`abcDecoder: transpose=${semitones} has no exact clef suffix; transposition dropped for clef "${clef}"`);
         return clef;
-    const num = Math.abs(steps) + 1;
-    const suffix = (steps < 0 ? "_" : "^") + num;
-    return (clef + suffix);
+    }
+    return transposed;
 };
 /**
  * Convert ABC barline to Lilylet barline style
@@ -1450,6 +1457,14 @@ const decodeTune = (tune, options = {}) => {
     // [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;
+    // ABC voice numbers whose declared clef has already been emitted. A voice gets its
+    // clef on the measure where it FIRST carries music, which is not always measure 0:
+    // a header field the grammar does not consume (e.g. `I:percmap`) degenerates into a
+    // phantom measure 0 holding a single patch with no voice number, and the emission
+    // was previously gated on `mi === 0`, so every real voice lost its clef — and with
+    // it its transposition. Keying on the voice number instead of the measure index
+    // makes the emission independent of what measure 0 happens to contain.
+    const emittedClefVoices = new Set();
     for (let mi = 0; mi < measures.length; mi++) {
         const abcMeasure = measures[mi];
         // Group patches by voice number
@@ -1585,29 +1600,39 @@ const decodeTune = (tune, options = {}) => {
         for (const pi of sortedPartIndices) {
             const voicesMap = partVoicesMap.get(pi);
             const voices = [];
+            // Voice -> the ABC voice number it came from, recovered from the map key
+            // (voiceKey = staffInPart * 1000 + voiceNum). Voice itself carries no voice
+            // number, and the clef below is a per-voice property, so the association has
+            // to be kept explicitly rather than searched for.
+            const voiceNumOf = new Map();
             const sortedKeys = Array.from(voicesMap.keys()).sort((a, b) => a - b);
             for (const key of sortedKeys) {
-                voices.push(voicesMap.get(key));
+                const voice = voicesMap.get(key);
+                voices.push(voice);
+                voiceNumOf.set(voice, key % 1000);
             }
             const part = { voices };
-            // Add clef context to first voice of each staff on first measure
-            if (mi === 0) {
-                for (const voice of voices) {
-                    // Find voices for this part's staff and add initial clef
-                    const voiceNums = Array.from(voicePatches.keys());
-                    for (const vn of voiceNums) {
-                        if (scoreLayout) {
-                            const assign = scoreLayout.get(vn);
-                            if (assign && assign.partIndex === pi && assign.staffInPart === voice.staff) {
-                                const clef = voiceClefs.get(vn);
-                                if (clef) {
-                                    voice.events.unshift({ type: "context", clef });
-                                    break;
-                                }
-                            }
-                        }
-                    }
-                }
+            // Give each voice its OWN declared clef on the measure where it first
+            // appears. A clef must be per voice, not per staff: an ABC voice folds its
+            // `transpose=` into the clef suffix, so two voices sharing a staff can
+            // legitimately differ, and lilylet's model is per-voice throughout
+            // (onsets.measureOnsets tracks clefByVoice, serializer.findVoiceClef reads
+            // one clef per Voice).
+            //
+            // This used to scan for the FIRST voice whose scoreLayout assignment matched
+            // (partIndex, staff) and break, so every voice on a shared staff inherited
+            // the first one's clef — the WRONG clef, taking its transposition with it.
+            // A `%%score` arc such as `( 1 2 )` puts both voices on one staff and is
+            // exactly that shape.
+            for (const voice of voices) {
+                const vn = voiceNumOf.get(voice);
+                if (emittedClefVoices.has(vn))
+                    continue;
+                const clef = voiceClefs.get(vn);
+                if (!clef)
+                    continue;
+                voice.events.unshift({ type: "context", clef });
+                emittedClefVoices.add(vn);
             }
             parts.push(part);
         }

package/lib/lilylet/clefTransposition.d.ts

@@ -0,0 +1,111 @@
+/**
+ * The canonical grammar for Lilylet's transposing-clef suffix, and the only place
+ * that converts between a suffix and a semitone count.
+ *
+ * A Lilylet clef may carry a written→sounding transposition as a suffix:
+ *
+ *   treble_8    an octave down          (-12)
+ *   treble^2    a major second up       (+2)
+ *   treble_5    a perfect fifth down    (-7)
+ *   treble_m3   a MINOR third down      (-3)
+ *   treble_m7   a minor seventh down    (-10)
+ *
+ * `_` lowers, `^` raises, the number is a diatonic interval, and an `m` before the
+ * number selects the MINOR form of that interval. Without `m` the interval is the
+ * major/perfect one, which is what every suffix written before the `m` form existed
+ * means — so plain `_N`/`^N` keeps its original value and old documents are read
+ * exactly as before.
+ *
+ * Why `m` exists: the diatonic interval number alone cannot express a minor
+ * interval, so the semitone counts 1, 3, 8 and 10 were unreachable. Those are not
+ * exotic — a minor third is the A clarinet and a minor seventh is a common brass
+ * transposition, so an ABC `transpose=-3` had no exact suffix and was rounded to
+ * `_3` (-4), putting a one-semitone error on the sounding pitch. With `m` the only
+ * remaining gap is 6 semitones, the tritone, which is neither major/perfect nor
+ * minor (it is an augmented fourth or diminished fifth). No instrument transposes
+ * by a tritone and the shape does not occur in any corpus checked, so it is left
+ * unrepresentable rather than given a spelling that would have to be arbitrary.
+ *
+ * NOTE ON LILYPOND: LilyPond's own `\clef "treble_8"` suffix is a NOTATIONAL
+ * device — it repositions middle C on the staff and does not change sounding pitch
+ * at all (LilyPond expresses instrument transposition with the separate
+ * `\transposition <pitch>`, which takes a pitch and so reaches every semitone).
+ * Lilylet deliberately diverges: here the suffix DOES carry the sounding shift, and
+ * `m` is the extension that makes that carrying lossless. LilyPond rejects `_m3` as
+ * an unknown clef type, so a Lilylet clef using `m` is not portable to LilyPond
+ * as-is.
+ */
+/** A parsed transposing-clef suffix. */
+export interface ClefSuffix {
+    /** The clef name with the suffix removed, e.g. "treble". */
+    base: string;
+    /** Diatonic interval number as written: 8 for an octave, 3 for a third. */
+    interval: number;
+    /** True when the suffix selected the minor form (`m` present). */
+    minor: boolean;
+    /** true = `^` (up), false = `_` (down). */
+    up: boolean;
+}
+/**
+ * Parse a clef string into its base name and transposition suffix.
+ * Returns undefined when the clef carries no suffix, or when the suffix is
+ * malformed (including `m` on a perfect interval such as `_m4`).
+ */
+export declare const parseClefSuffix: (clefStr: string) => ClefSuffix | undefined;
+/** The clef name with any transposition suffix stripped. */
+export declare const clefBaseName: (clefStr: string) => string;
+/**
+ * The written→sounding semitone shift a clef string declares; 0 when it declares
+ * none (no suffix, or a suffix that cannot be interpreted).
+ */
+export declare const clefSuffixSemitones: (clefStr: string) => number;
+/**
+ * The written→sounding transposition as MEI's att.transposition pair, in the
+ * `{diat, semi}` form: diatonic steps and semitones, both signed. A minor third
+ * down is `{diat: -2, semi: -3}` — the two differ, which is exactly the
+ * information the diatonic number alone cannot carry.
+ */
+export declare const clefSuffixTransposition: (clefStr: string) => {
+    diat: number;
+    semi: number;
+} | undefined;
+/**
+ * The suffix that expresses `semitones` EXACTLY, or undefined when no suffix can.
+ * Never approximates: a caller that gets undefined must handle the gap rather than
+ * emit a shift it cannot honour. The only unrepresentable interval within an octave
+ * is 6 semitones (the tritone) — see the module comment.
+ *
+ * Returns the suffix alone (e.g. "_m3"), to be appended to a clef base name.
+ */
+export declare const semitonesToClefSuffix: (semitones: number) => string | undefined;
+/**
+ * Apply a semitone transposition to a clef name, returning the suffixed clef.
+ * Returns undefined when the shift has no exact suffix, so the caller can decide
+ * between dropping the transposition and reporting it — silently rounding is what
+ * produced wrong sounding pitches before this module existed.
+ */
+export declare const withClefTransposition: (base: string, semitones: number) => string | undefined;
+/**
+ * Whether LilyPond itself accepts this suffix on a clef name. LilyPond's grammar is
+ * `([_^])([^0-9a-zA-Z]*)([1-9][0-9]*)` — a sign then a bare number — so it has no
+ * place for the `m` that selects a minor interval, and `\clef "treble_m3"` is
+ * rejected outright as an unknown clef type.
+ */
+export declare const isLilyPondClefSuffix: (clefStr: string) => boolean;
+/**
+ * The LilyPond `\transposition` pitch that declares a written→sounding shift of
+ * `semitones`, or undefined when the shift is beyond the two octaves either side of
+ * c' that instrument transpositions occupy.
+ *
+ * This is the mechanism that carries sounding pitch in LilyPond: `\transposition`
+ * takes a pitch, reaches every semitone, and DOES move MIDI, while the clef suffix
+ * is purely notational and moves nothing. The two are orthogonal, so a lilylet clef
+ * whose suffix means a sounding shift translates to BOTH — the suffix for the glyph
+ * (when LilyPond accepts it) and `\transposition` for the sound.
+ *
+ * The pitch is spelled relative to c', the no-transposition reference: an octave
+ * mark `'` per octave above, a `,` per octave below. Compound intervals are real —
+ * a major ninth down (-14) is the written form of some orchestral parts — so the
+ * range is not limited to a single octave.
+ */
+export declare const lilyPondTranspositionPitch: (semitones: number) => string | undefined;

package/lib/lilylet/clefTransposition.js

@@ -0,0 +1,175 @@
+/**
+ * The canonical grammar for Lilylet's transposing-clef suffix, and the only place
+ * that converts between a suffix and a semitone count.
+ *
+ * A Lilylet clef may carry a written→sounding transposition as a suffix:
+ *
+ *   treble_8    an octave down          (-12)
+ *   treble^2    a major second up       (+2)
+ *   treble_5    a perfect fifth down    (-7)
+ *   treble_m3   a MINOR third down      (-3)
+ *   treble_m7   a minor seventh down    (-10)
+ *
+ * `_` lowers, `^` raises, the number is a diatonic interval, and an `m` before the
+ * number selects the MINOR form of that interval. Without `m` the interval is the
+ * major/perfect one, which is what every suffix written before the `m` form existed
+ * means — so plain `_N`/`^N` keeps its original value and old documents are read
+ * exactly as before.
+ *
+ * Why `m` exists: the diatonic interval number alone cannot express a minor
+ * interval, so the semitone counts 1, 3, 8 and 10 were unreachable. Those are not
+ * exotic — a minor third is the A clarinet and a minor seventh is a common brass
+ * transposition, so an ABC `transpose=-3` had no exact suffix and was rounded to
+ * `_3` (-4), putting a one-semitone error on the sounding pitch. With `m` the only
+ * remaining gap is 6 semitones, the tritone, which is neither major/perfect nor
+ * minor (it is an augmented fourth or diminished fifth). No instrument transposes
+ * by a tritone and the shape does not occur in any corpus checked, so it is left
+ * unrepresentable rather than given a spelling that would have to be arbitrary.
+ *
+ * NOTE ON LILYPOND: LilyPond's own `\clef "treble_8"` suffix is a NOTATIONAL
+ * device — it repositions middle C on the staff and does not change sounding pitch
+ * at all (LilyPond expresses instrument transposition with the separate
+ * `\transposition <pitch>`, which takes a pitch and so reaches every semitone).
+ * Lilylet deliberately diverges: here the suffix DOES carry the sounding shift, and
+ * `m` is the extension that makes that carrying lossless. LilyPond rejects `_m3` as
+ * an unknown clef type, so a Lilylet clef using `m` is not portable to LilyPond
+ * as-is.
+ */
+// Semitones spanned by the MAJOR/PERFECT form of each diatonic step count
+// (0 = unison, 1 = second, … 6 = seventh).
+const DIATONIC_SEMITONES = [0, 2, 4, 5, 7, 9, 11];
+// Diatonic step counts that have a minor form: seconds, thirds, sixths, sevenths.
+// Unison, fourth and fifth are perfect and take no `m`.
+const MINOR_CAPABLE_STEPS = new Set([1, 2, 5, 6]);
+// `_`/`^`, an optional `m`, then a positive interval number with no leading zero.
+const SUFFIX_RE = /^(.*?)([_^])(m?)([1-9][0-9]*)$/;
+/** Semitones spanned by a diatonic interval number, or undefined if `m` is invalid for it. */
+const intervalSemitones = (interval, minor) => {
+    const steps = interval - 1; // diatonic steps above unison
+    const within = steps % 7;
+    if (minor && !MINOR_CAPABLE_STEPS.has(within))
+        return undefined;
+    const semis = DIATONIC_SEMITONES[within] + 12 * Math.floor(steps / 7);
+    return minor ? semis - 1 : semis;
+};
+/**
+ * Parse a clef string into its base name and transposition suffix.
+ * Returns undefined when the clef carries no suffix, or when the suffix is
+ * malformed (including `m` on a perfect interval such as `_m4`).
+ */
+export const parseClefSuffix = (clefStr) => {
+    const match = SUFFIX_RE.exec(clefStr || "");
+    if (!match)
+        return undefined;
+    const interval = parseInt(match[4], 10);
+    const minor = match[3] === "m";
+    // Reject a suffix we cannot interpret rather than silently mis-reading it.
+    if (intervalSemitones(interval, minor) === undefined)
+        return undefined;
+    return { base: match[1], interval, minor, up: match[2] === "^" };
+};
+/** The clef name with any transposition suffix stripped. */
+export const clefBaseName = (clefStr) => parseClefSuffix(clefStr)?.base ?? clefStr;
+/**
+ * The written→sounding semitone shift a clef string declares; 0 when it declares
+ * none (no suffix, or a suffix that cannot be interpreted).
+ */
+export const clefSuffixSemitones = (clefStr) => {
+    const parsed = parseClefSuffix(clefStr);
+    if (!parsed)
+        return 0;
+    const semis = intervalSemitones(parsed.interval, parsed.minor);
+    return parsed.up ? semis : -semis;
+};
+/**
+ * The written→sounding transposition as MEI's att.transposition pair, in the
+ * `{diat, semi}` form: diatonic steps and semitones, both signed. A minor third
+ * down is `{diat: -2, semi: -3}` — the two differ, which is exactly the
+ * information the diatonic number alone cannot carry.
+ */
+export const clefSuffixTransposition = (clefStr) => {
+    const parsed = parseClefSuffix(clefStr);
+    if (!parsed)
+        return undefined;
+    const semis = intervalSemitones(parsed.interval, parsed.minor);
+    const sign = parsed.up ? 1 : -1;
+    return { diat: sign * (parsed.interval - 1), semi: sign * semis };
+};
+/**
+ * The suffix that expresses `semitones` EXACTLY, or undefined when no suffix can.
+ * Never approximates: a caller that gets undefined must handle the gap rather than
+ * emit a shift it cannot honour. The only unrepresentable interval within an octave
+ * is 6 semitones (the tritone) — see the module comment.
+ *
+ * Returns the suffix alone (e.g. "_m3"), to be appended to a clef base name.
+ */
+export const semitonesToClefSuffix = (semitones) => {
+    if (!Number.isInteger(semitones) || semitones === 0)
+        return undefined;
+    const magnitude = Math.abs(semitones);
+    const sign = semitones < 0 ? "_" : "^";
+    // Search interval numbers covering the requested magnitude; octaves shift by 7
+    // diatonic steps, so an octave-and-a-bit needs interval numbers beyond 8.
+    const maxInterval = Math.floor(magnitude / 12) * 7 + 8;
+    for (let interval = 1; interval <= maxInterval; interval++) {
+        for (const minor of [false, true]) {
+            if (intervalSemitones(interval, minor) === magnitude)
+                return `${sign}${minor ? "m" : ""}${interval}`;
+        }
+    }
+    return undefined;
+};
+/**
+ * Apply a semitone transposition to a clef name, returning the suffixed clef.
+ * Returns undefined when the shift has no exact suffix, so the caller can decide
+ * between dropping the transposition and reporting it — silently rounding is what
+ * produced wrong sounding pitches before this module existed.
+ */
+export const withClefTransposition = (base, semitones) => {
+    if (semitones === 0)
+        return base;
+    const suffix = semitonesToClefSuffix(semitones);
+    return suffix === undefined ? undefined : base + suffix;
+};
+/**
+ * Whether LilyPond itself accepts this suffix on a clef name. LilyPond's grammar is
+ * `([_^])([^0-9a-zA-Z]*)([1-9][0-9]*)` — a sign then a bare number — so it has no
+ * place for the `m` that selects a minor interval, and `\clef "treble_m3"` is
+ * rejected outright as an unknown clef type.
+ */
+export const isLilyPondClefSuffix = (clefStr) => {
+    const parsed = parseClefSuffix(clefStr);
+    return parsed !== undefined && !parsed.minor;
+};
+// Note names for the twelve semitones above c, in ENGLISH spelling (`bf`, not Dutch
+// `bes`) — lilypondEncoder emits `\language "english"`, under which a Dutch name is
+// rejected as "wrong type for argument 1, expecting pitch". Flats throughout: a
+// transposing instrument is named by its flat spelling.
+const ENGLISH_PITCH_NAMES = ["c", "df", "d", "ef", "e", "f", "gf", "g", "af", "a", "bf", "b"];
+/**
+ * The LilyPond `\transposition` pitch that declares a written→sounding shift of
+ * `semitones`, or undefined when the shift is beyond the two octaves either side of
+ * c' that instrument transpositions occupy.
+ *
+ * This is the mechanism that carries sounding pitch in LilyPond: `\transposition`
+ * takes a pitch, reaches every semitone, and DOES move MIDI, while the clef suffix
+ * is purely notational and moves nothing. The two are orthogonal, so a lilylet clef
+ * whose suffix means a sounding shift translates to BOTH — the suffix for the glyph
+ * (when LilyPond accepts it) and `\transposition` for the sound.
+ *
+ * The pitch is spelled relative to c', the no-transposition reference: an octave
+ * mark `'` per octave above, a `,` per octave below. Compound intervals are real —
+ * a major ninth down (-14) is the written form of some orchestral parts — so the
+ * range is not limited to a single octave.
+ */
+export const lilyPondTranspositionPitch = (semitones) => {
+    if (!Number.isInteger(semitones) || Math.abs(semitones) > 24)
+        return undefined;
+    // Reduce to a pitch class plus an octave count, measuring from c'.
+    const within = ((semitones % 12) + 12) % 12;
+    const octaves = Math.floor(semitones / 12);
+    const name = ENGLISH_PITCH_NAMES[within];
+    // c' is the reference and carries one `'`; each octave adds or removes one.
+    const marks = 1 + octaves;
+    return name + (marks >= 0 ? "'".repeat(marks) : ",".repeat(-marks));
+};

package/lib/lilylet/index.d.ts

@@ -4,6 +4,7 @@ export * from "./serializer";
 export * from "./staffLayout";
 export * from "./measureLayout";
 export * from "./onsets";
+export * from "./clefTransposition";
 export * from "./transposition";
 import * as meiEncoder from "./meiEncoder";
 import * as musicXmlDecoder from "./musicXmlDecoder";

package/lib/lilylet/index.js

@@ -4,6 +4,7 @@ export * from "./serializer.js";
 export * from "./staffLayout.js";
 export * from "./measureLayout.js";
 export * from "./onsets.js";
+export * from "./clefTransposition.js";
 export * from "./transposition.js";
 import * as meiEncoder from "./meiEncoder.js";
 import * as musicXmlDecoder from "./musicXmlDecoder.js";

package/lib/lilylet/lilypondDecoder.js

@@ -10,6 +10,7 @@ import * as lilyParser from "@k-l-lambda/lotus/lib/inc/lilyParser/index.js";
 // @ts-ignore - CommonJS module
 import * as lilypondParser from "@k-l-lambda/lotus/lib.browser/lib/lilyParser.js";
 import { Clef, StemDirection, Accidental, Phonet, ArticulationType, OrnamentType, DynamicType, HairpinType, PedalType, NavigationMarkType, Placement, } from "./types.js";
+import { clefBaseName, parseClefSuffix, withClefTransposition } from "./clefTransposition.js";
 // Phonet names mapping
 const PHONET_NAMES = {
     0: Phonet.c,
@@ -37,6 +38,72 @@ const LILYPOND_CLEF_MAP = {
     alto: Clef.alto,
     C: Clef.alto,
 };
+/**
+ * Fold a standing `\transposition` shift onto a clef as a lilylet suffix.
+ *
+ * The two carry different things in LilyPond and must not be added: a clef suffix
+ * there is notational and moves no pitch, while `\transposition` moves pitch and
+ * draws nothing. lilylet's suffix means sounding shift, so `\transposition` is the
+ * authority whenever it is present — a file with BOTH `\clef "treble_8"` and
+ * `\transposition c` (which is what lilypondEncoder emits for an octave clef) states
+ * one octave, not two.
+ *
+ * With no `\transposition`, a suffix already on the clef is kept as-is: that is the
+ * plain octave-clef part, where the notation is taken to imply its own shift.
+ */
+const applyTransposition = (clef, semitones) => {
+    if (!clef || semitones === 0)
+        return clef;
+    const base = clefBaseName(clef);
+    const shifted = withClefTransposition(base, semitones);
+    if (shifted === undefined) {
+        console.warn(`lilypondDecoder: \\transposition of ${semitones} semitones has no exact clef suffix; dropped for clef "${clef}"`);
+        return clef;
+    }
+    return shifted;
+};
+// Semitones above c for each diatonic step index (0 = c ... 6 = b).
+const PHONET_SEMITONES = [0, 2, 4, 5, 7, 9, 11];
+/**
+ * Semitone offset from c' of a `\transposition` pitch term, which is how LilyPond
+ * states a transposing instrument's written->sounding shift (the clef suffix there is
+ * notational and states nothing). Returns 0 for a pitch that cannot be read.
+ */
+const transpositionSemitones = (term) => {
+    const el = term?.args?.[0];
+    if (!el)
+        return 0;
+    const step = el.phonetStep;
+    const octave = el.absolutePitch?.octave;
+    if (typeof step !== 'number' || typeof octave !== 'number')
+        return 0;
+    // c' is the no-transposition reference, and sits at 12 in this scale.
+    return (PHONET_SEMITONES[step] + (el.alterValue || 0) + 12 * octave) - 12;
+};
+/**
+ * A LilyPond clef name to a lilylet Clef, keeping any transposing suffix.
+ *
+ * The map is keyed on BASE names, so looking up the whole string missed every
+ * suffixed clef ("treble_8" is not a key) and `if (clef)` then dropped the clef
+ * event altogether — the transposition went with it. Resolve the base through the
+ * map and reattach the suffix, which is the form lilylet's own model uses.
+ *
+ * A suffix LilyPond cannot write (the `m` minor-interval form) cannot appear in
+ * LilyPond input, so nothing here has to handle it; parseClefSuffix simply returns
+ * undefined for an unsuffixed name and the base is used as-is.
+ */
+const resolveLilyPondClef = (clefName) => {
+    const direct = LILYPOND_CLEF_MAP[clefName];
+    if (direct)
+        return direct;
+    const parsed = parseClefSuffix(clefName);
+    if (!parsed)
+        return undefined;
+    const base = LILYPOND_CLEF_MAP[parsed.base];
+    if (!base)
+        return undefined;
+    return (base + clefName.slice(parsed.base.length));
+};
 // Key signature fifths to pitch/accidental mapping
 const KEY_FIFTHS_MAP = {
     [-7]: { pitch: Phonet.c, accidental: Accidental.flat, mode: 'major' },
@@ -468,6 +535,9 @@ const parseLilyDocument = (lilyDocument) => {
         let lastKey = undefined; // Track value changes (key fifths)
         let lastTimeSig = undefined; // Track value changes (as string for comparison)
         let lastClef = undefined; // Track value changes
+        // \transposition is a standing declaration: it applies to every clef emitted
+        // after it, and lilylet folds the shift into the clef suffix.
+        let transposeSemis = 0;
         let lastOttava = undefined; // Track value changes
         let lastStemDirection = undefined; // Track value changes
         let partialEmitted = false; // Emit \partial context once per track
@@ -570,7 +640,7 @@ const parseLilyDocument = (lilyDocument) => {
                     }
                     // Handle clef context change (emit when value changes)
                     if (context.clef) {
-                        const clef = LILYPOND_CLEF_MAP[context.clef.clefName];
+                        const clef = applyTransposition(resolveLilyPondClef(context.clef.clefName), transposeSemis);
                         if (clef && clef !== lastClef) {
                             voice.events.push({
                                 type: 'context',
@@ -683,9 +753,25 @@ const parseLilyDocument = (lilyDocument) => {
                         }
                     }
                 }
+                else if (term instanceof lilyParser.LilyTerms.Transposition) {
+                    const semis = transpositionSemitones(term);
+                    if (semis !== transposeSemis) {
+                        transposeSemis = semis;
+                        // A `\transposition` AFTER the clef still governs it, so re-emit the
+                        // clef with the shift folded in rather than let the already-emitted
+                        // plain clef stand. Order between the two is not fixed in the wild.
+                        if (lastClef) {
+                            const corrected = applyTransposition(clefBaseName(lastClef), transposeSemis);
+                            if (corrected && corrected !== lastClef) {
+                                voice.events.push({ type: 'context', clef: corrected });
+                                lastClef = corrected;
+                            }
+                        }
+                    }
+                }
                 // Handle standalone clef (emit when value changes)
                 else if (term instanceof lilyParser.LilyTerms.Clef) {
-                    const clef = LILYPOND_CLEF_MAP[term.clefName];
+                    const clef = applyTransposition(resolveLilyPondClef(term.clefName), transposeSemis);
                     if (clef && clef !== lastClef) {
                         voice.events.push({
                             type: 'context',

package/lib/lilylet/lilypondEncoder.js

@@ -5,6 +5,7 @@
  * Uses relative pitch mode matching LilyPond's default behavior.
  */
 import { Accidental, } from "./types.js";
+import { clefBaseName, clefSuffixSemitones, isLilyPondClefSuffix, lilyPondTranspositionPitch } from "./clefTransposition.js";
 // === Constants and Mappings ===
 const PHONETS = "cdefgab";
 // Key signature to LilyPond notation (using English note names)
@@ -227,10 +228,39 @@ const encodeTimeSig = (timeSig) => {
     return `\\time ${timeSig.numerator}/${timeSig.denominator}`;
 };
 /**
- * Encode clef to LilyPond
+ * Encode clef to LilyPond.
+ *
+ * A lilylet clef suffix carries a written→sounding shift; LilyPond's does not —
+ * there the suffix only repositions middle C on the staff and MIDI is untouched,
+ * and sounding pitch comes from the separate `\transposition <pitch>`. The two are
+ * orthogonal, so a transposing clef translates to BOTH: the suffix for the glyph,
+ * `\transposition` for the sound. Emitting only the suffix (what this did before)
+ * produced a file whose notation was right and whose MIDI was a transposition out.
+ *
+ * The clef string is quoted. LilyPond accepts a bare name unquoted, but `_m3`
+ * lexes as `_` followed by `m3` and breaks the parse; quoting is valid for every
+ * form. A `m` suffix has no LilyPond glyph at all (unknown clef type), so the base
+ * clef is emitted and the shift rides entirely on `\transposition`.
  */
 const encodeClef = (clef) => {
-    return `\\clef ${CLEF_MAP[clef] || clef}`;
+    const clefStr = clef;
+    const shift = clefSuffixSemitones(clefStr);
+    // Keep the suffix only when LilyPond can render it; otherwise fall back to the
+    // base name rather than emit a clef LilyPond rejects.
+    const name = (shift === 0 || isLilyPondClefSuffix(clefStr)) ? clefStr : clefBaseName(clefStr);
+    const mapped = CLEF_MAP[name] || name;
+    const parts = [];
+    // \transposition comes FIRST so that a reader tracking it as a standing
+    // declaration has the shift in hand by the time the clef arrives.
+    if (shift !== 0) {
+        const pitch = lilyPondTranspositionPitch(shift);
+        if (pitch)
+            parts.push(`\\transposition ${pitch}`);
+        else
+            console.warn(`lilypondEncoder: clef "${clefStr}" shift ${shift} has no \\transposition pitch; sounding pitch not declared`);
+    }
+    parts.push(`\\clef "${mapped}"`);
+    return parts.join(' ');
 };
 /**
  * Encode tempo to LilyPond