@k-l-lambda/lilylet 0.1.89 → 0.1.90

package/lib/lilylet/clefTransposition.d.ts

@@ -85,3 +85,27 @@ export declare const semitonesToClefSuffix: (semitones: number) => string | unde
  * 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

@@ -131,3 +131,45 @@ export const withClefTransposition = (base, semitones) => {
     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/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

package/lib/lilylet/musicXmlDecoder.js

@@ -6,6 +6,7 @@
  */
 import { DOMParser } from '@xmldom/xmldom';
 import { HairpinType, NavigationMarkType, OrnamentType, Placement, } from "./types.js";
+import { withClefTransposition } from "./clefTransposition.js";
 import { getElementText, getElementInt, getElements, getDirectChildren, getChildElements, getAttribute, getAttributeNumber, hasElement, convertPitch, convertDuration, convertKeySignature, convertClef, convertStemDirection, convertArticulation, convertOrnament, convertDynamic, convertPedal, convertBarlineStyle, convertHarmonyToText, createFraction, TYPE_TO_DIVISION, } from "./musicXmlUtils.js";
 import { measureLayoutFromPart } from "./measureLayoutFromXml.js";
 // ============ Spanner Tracker ============
@@ -491,6 +492,20 @@ const parseAttributes = (attrEl) => {
             }
         }
     }
+    // Instrument transposition. This is what carries a transposing part's sounding
+    // pitch in MusicXML (<clef-octave-change> is only the glyph), and it was never
+    // read, so every transposing instrument decoded as sounding-as-written.
+    const transposeEl = getElements(attrEl, 'transpose')[0];
+    if (transposeEl) {
+        const chromatic = getElementInt(transposeEl, 'chromatic');
+        if (chromatic != null) {
+            result.transpose = {
+                diatonic: getElementInt(transposeEl, 'diatonic') ?? undefined,
+                chromatic,
+                octaveChange: getElementInt(transposeEl, 'octave-change') ?? undefined,
+            };
+        }
+    }
     // Staves
     const staves = getElementInt(attrEl, 'staves');
     if (staves !== undefined) {
@@ -1038,6 +1053,35 @@ const forwardGapToRests = (gapTicks, divisions) => {
     }
     return rests;
 };
+/**
+ * Fold a MusicXML transposition onto a lilylet clef as a suffix.
+ *
+ * MusicXML keeps the two apart: <transpose> is the sounding shift and moves pitch,
+ * <clef-octave-change> is the "8" glyph under the clef and moves nothing. A lilylet
+ * suffix means sounding shift, so only ONE of them may be folded in — adding both
+ * would double an octave clef that also declares <transpose> (the shape this
+ * encoder itself now emits) into two octaves.
+ *
+ * <transpose> wins when present, being the explicit statement of sounding pitch.
+ * Absent it, an octave clef is read as implying its own shift, which is what a
+ * tenor-voice or guitar treble_8 part means.
+ *
+ * A shift with no exact suffix (only the tritone) leaves the clef plain rather than
+ * rounding: a silently wrong sounding pitch is worse than a visibly absent shift.
+ */
+const clefWithShift = (clef, transposeSemitones, clefOctaveChange) => {
+    if (!clef)
+        return clef;
+    const semitones = transposeSemitones !== 0 ? transposeSemitones : 12 * (clefOctaveChange ?? 0);
+    if (semitones === 0)
+        return clef;
+    const shifted = withClefTransposition(clef, semitones);
+    if (shifted === undefined) {
+        console.warn(`musicXmlDecoder: transposition ${semitones} has no exact clef suffix; dropped for clef "${clef}"`);
+        return clef;
+    }
+    return shifted;
+};
 /**
  * Total time a TupletEvent advances the voice, in voiceTracker duration units.
  * Sum the inner note/rest values then apply the tuplet ratio (triplet etc.).
@@ -1054,7 +1098,10 @@ const tupletAdvanceDuration = (tupletEvent, divisions) => {
 /**
  * Convert a MusicXML measure to Lilylet events, grouped by voice
  */
-const convertMeasure = (measureEl, voiceTracker, spannerTracker, ottavaTracker, tupletTracker) => {
+const convertMeasure = (measureEl, voiceTracker, spannerTracker, ottavaTracker, tupletTracker, 
+// A part's <transpose> is declared once, usually in measure 1, and stays in force
+// for the whole part, so it has to survive across measures like the ottava does.
+transposeTracker) => {
     let key;
     let timeSig;
     let barline;
@@ -1136,10 +1183,15 @@ const convertMeasure = (measureEl, voiceTracker, spannerTracker, ottavaTracker,
             if (attrs.time) {
                 timeSig = createFraction(attrs.time.beats, attrs.time.beatType);
             }
+            // Instrument transposition, in force from here to the end of the part.
+            if (attrs.transpose) {
+                const { chromatic, octaveChange } = attrs.transpose;
+                transposeTracker.semitones = chromatic + 12 * (octaveChange ?? 0);
+            }
             // Clefs - store by staff number
             if (attrs.clefs) {
                 for (const clefEntry of attrs.clefs) {
-                    const clef = convertClef(clefEntry.clef.sign, clefEntry.clef.line);
+                    const clef = clefWithShift(convertClef(clefEntry.clef.sign, clefEntry.clef.line), transposeTracker.semitones, clefEntry.clef.clefOctaveChange);
                     if (clef) {
                         const staff = clefEntry.staff;
                         if (staffHasNotes.has(staff)) {
@@ -1508,6 +1560,7 @@ const convertPart = (partEl) => {
     const voiceTracker = new VoiceTracker();
     const spannerTracker = new SpannerTracker();
     const ottavaTracker = { current: 0 };
+    const transposeTracker = { semitones: 0 };
     const tupletTracker = new TupletTracker();
     let lastKey;
     let lastTimeSig;
@@ -1523,7 +1576,7 @@ const convertPart = (partEl) => {
     const measureEls = getDirectChildren(partEl, 'measure');
     for (const measureEl of measureEls) {
         voiceTracker.reset();
-        const { voiceMap, key, timeSig, barline, leadingBarline, harmonies, clefs } = convertMeasure(measureEl, voiceTracker, spannerTracker, ottavaTracker, tupletTracker);
+        const { voiceMap, key, timeSig, barline, leadingBarline, harmonies, clefs } = convertMeasure(measureEl, voiceTracker, spannerTracker, ottavaTracker, tupletTracker, transposeTracker);
         // A forward-repeat (or any `location="left"`) barline belongs at the END of
         // the PREVIOUS measure in lilylet's "\bar = current measure's end bar" model.
         // Append it to the previous measure's first voice; if this is the first

package/lib/lilylet/musicXmlEncoder.js

@@ -7,6 +7,7 @@
 import { StemDirection, Accidental, HairpinType, PedalType, NavigationMarkType, } from "./types.js";
 import { DIVISIONS, DIVISION_TO_TYPE, calculateDuration, } from "./musicXmlUtils.js";
 import { parseStaffLayout } from "./staffLayout.js";
+import { clefBaseName, clefSuffixSemitones, clefSuffixTransposition } from "./clefTransposition.js";
 // === Constants and Reverse Mappings ===
 // Phonet to MusicXML step
 const PHONET_TO_STEP = {
@@ -210,13 +211,44 @@ const encodeAttributes = (level, options) => {
         xml += `${indent(level + 1)}<staves>${options.staves}</staves>\n`;
     }
     if (options.clef) {
-        const clefInfo = CLEF_TO_SIGN[options.clef];
+        // Look the sign/line up under the BASE name. A lilylet clef may carry a
+        // transposition suffix ("treble_8", "treble_m3"), and keying the table on the
+        // whole string missed every one of them — `clefInfo` came back undefined and
+        // the <clef> element was dropped entirely, sign and line with it.
+        const clefStr = options.clef;
+        const clefInfo = CLEF_TO_SIGN[clefBaseName(clefStr)];
         if (clefInfo) {
             xml += `${indent(level + 1)}<clef>\n`;
             xml += `${indent(level + 2)}<sign>${clefInfo.sign}</sign>\n`;
             xml += `${indent(level + 2)}<line>${clefInfo.line}</line>\n`;
+            // A whole-octave shift also has a notational form: the "8" drawn under or
+            // over the clef. This is the glyph only — sounding pitch rides on
+            // <transpose> below, exactly as in LilyPond.
+            const semitones = clefSuffixSemitones(clefStr);
+            if (semitones % 12 === 0 && semitones !== 0)
+                xml += `${indent(level + 2)}<clef-octave-change>${semitones / 12}</clef-octave-change>\n`;
             xml += `${indent(level + 1)}</clef>\n`;
         }
+        // The written->sounding transposition. MusicXML carries the diatonic step count
+        // and the chromatic semitone count separately, which is what lets a minor third
+        // (-2 steps, -3 semitones) be expressed exactly. <transpose> follows <clef> in
+        // the attributes content order.
+        const trans = clefSuffixTransposition(clefStr);
+        if (trans) {
+            // <diatonic> and <chromatic> hold the WITHIN-OCTAVE remainder and whole
+            // octaves go in <octave-change>, so both must be reduced by the same octave
+            // count: 7 diatonic steps and 12 semitones each. Reducing only the semitones
+            // would make an octave clef read as two octaves.
+            const octaveChange = Math.trunc(trans.semi / 12);
+            const diatonic = trans.diat - 7 * octaveChange;
+            const chromatic = trans.semi - 12 * octaveChange;
+            xml += `${indent(level + 1)}<transpose>\n`;
+            xml += `${indent(level + 2)}<diatonic>${diatonic}</diatonic>\n`;
+            xml += `${indent(level + 2)}<chromatic>${chromatic}</chromatic>\n`;
+            if (octaveChange !== 0)
+                xml += `${indent(level + 2)}<octave-change>${octaveChange}</octave-change>\n`;
+            xml += `${indent(level + 1)}</transpose>\n`;
+        }
     }
     xml += `${indent(level)}</attributes>\n`;
     return xml;

package/lib/lilylet/musicXmlTypes.d.ts

@@ -31,6 +31,11 @@ export interface MusicXmlClef {
     line?: number;
     clefOctaveChange?: number;
 }
+export interface MusicXmlTranspose {
+    diatonic?: number;
+    chromatic: number;
+    octaveChange?: number;
+}
 export interface MusicXmlAttributes {
     divisions?: number;
     key?: MusicXmlKey;
@@ -40,6 +45,7 @@ export interface MusicXmlAttributes {
         clef: MusicXmlClef;
     }[];
     staves?: number;
+    transpose?: MusicXmlTranspose;
 }
 export type MusicXmlStemDirection = 'up' | 'down';
 export type MusicXmlLyricSyllabic = 'single' | 'begin' | 'middle' | 'end';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k-l-lambda/lilylet",
-  "version": "0.1.89",
+  "version": "0.1.90",
   "description": "Lilylet is a lilyopnd-like sheet music language designed for Markdown rendering and symbolic music representation in AIGC applications.",
   "type": "module",
   "main": "lib/index.js",
@@ -57,6 +57,7 @@
     "test:clef-onset": "tsx ./tests/unit/clefOnsetTranspose.test.ts",
     "test:abc-transpose": "tsx ./tests/unit/abcTransposingClef.test.ts",
     "test:clef-transposition": "tsx ./tests/unit/clefTransposition.test.ts",
+    "test:clef-translation": "tsx ./tests/unit/clefTranslation.test.ts",
     "test:fine-rhythm-onset": "tsx ./tests/unit/fineRhythmOnset.test.ts",
     "test:transpose": "tsx ./tests/unit/astTranspose.test.ts",
     "build:tests": "tsc -p tsconfig.tests.json; cp source/lilylet/grammar.jison.js lib-tests/source/lilylet/ && cp source/abc/grammar.jison.js lib-tests/source/abc/ && node tools/fixEsmExtensions.cjs lib-tests && ln -sfn ../../tests/assets lib-tests/tests/assets",

package/source/lilylet/clefTransposition.ts

@@ -147,3 +147,51 @@ export const withClefTransposition = (base: string, semitones: number): string |
 	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: string): boolean => {
+	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: number): string | undefined => {
+	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/source/lilylet/lilypondDecoder.ts

@@ -43,6 +43,8 @@ import {
 	Tempo,
 } from "./types";
 
+import { clefBaseName, parseClefSuffix, withClefTransposition } from "./clefTransposition";
+
 
 // Phonet names mapping
 const PHONET_NAMES: Record<number, Phonet> = {
@@ -77,6 +79,72 @@ const LILYPOND_CLEF_MAP: Record<string, Clef> = {
 };
 
 
+/**
+ * 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: Clef | undefined, semitones: number): Clef | undefined => {
+	if (!clef || semitones === 0) return clef;
+	const base = clefBaseName(clef as string);
+	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 as Clef;
+};
+
+// 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: any): number => {
+	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: string): Clef | undefined => {
+	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)) as Clef;
+};
+
+
 // Key signature fifths to pitch/accidental mapping
 const KEY_FIFTHS_MAP: Record<number, { pitch: Phonet; accidental?: Accidental; mode: 'major' | 'minor' }> = {
 	[-7]: { pitch: Phonet.c, accidental: Accidental.flat, mode: 'major' },
@@ -569,6 +637,9 @@ const parseLilyDocument = (lilyDocument: lilyParser.LilyDocument): ParsedMeasure
 		let lastKey: number | undefined = undefined;  // Track value changes (key fifths)
 		let lastTimeSig: string | undefined = undefined;  // Track value changes (as string for comparison)
 		let lastClef: Clef | undefined = 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: number | undefined = undefined;  // Track value changes
 		let lastStemDirection: string | undefined = undefined;  // Track value changes
 		let partialEmitted = false;  // Emit \partial context once per track
@@ -669,7 +740,7 @@ const parseLilyDocument = (lilyDocument: lilyParser.LilyDocument): ParsedMeasure
 
 					// 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',
@@ -796,9 +867,25 @@ const parseLilyDocument = (lilyDocument: lilyParser.LilyDocument): ParsedMeasure
 						}
 					}
 				}
+				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 as string) as Clef, 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/source/lilylet/lilypondEncoder.ts

@@ -38,6 +38,8 @@ import {
 	Placement,
 } from "./types";
 
+import { clefBaseName, clefSuffixSemitones, isLilyPondClefSuffix, lilyPondTranspositionPitch } from "./clefTransposition";
+
 
 // === Constants and Mappings ===
 
@@ -306,10 +308,42 @@ const encodeTimeSig = (timeSig: { numerator: number; denominator: number; symbol
 
 
 /**
- * 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: Clef): string => {
-	return `\\clef ${CLEF_MAP[clef] || clef}`;
+	const clefStr = clef as string;
+	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: string[] = [];
+
+	// \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(' ');
 };
 
 

package/source/lilylet/musicXmlDecoder.ts

@@ -8,6 +8,7 @@
 import { DOMParser } from '@xmldom/xmldom';
 
 import {
+	Clef,
 	LilyletDoc,
 	Measure,
 	Part,
@@ -49,6 +50,8 @@ import {
 	MusicXmlLyric,
 } from './musicXmlTypes';
 
+import { withClefTransposition } from './clefTransposition';
+
 import {
 	getElementText,
 	getElementInt,
@@ -647,6 +650,21 @@ const parseAttributes = (attrEl: Element): MusicXmlAttributes => {
 		}
 	}
 
+	// Instrument transposition. This is what carries a transposing part's sounding
+	// pitch in MusicXML (<clef-octave-change> is only the glyph), and it was never
+	// read, so every transposing instrument decoded as sounding-as-written.
+	const transposeEl = getElements(attrEl, 'transpose')[0];
+	if (transposeEl) {
+		const chromatic = getElementInt(transposeEl, 'chromatic');
+		if (chromatic != null) {
+			result.transpose = {
+				diatonic: getElementInt(transposeEl, 'diatonic') ?? undefined,
+				chromatic,
+				octaveChange: getElementInt(transposeEl, 'octave-change') ?? undefined,
+			};
+		}
+	}
+
 	// Staves
 	const staves = getElementInt(attrEl, 'staves');
 	if (staves !== undefined) {
@@ -1260,6 +1278,38 @@ const forwardGapToRests = (gapTicks: number, divisions: number): RestEvent[] =>
 	return rests;
 };
 
+/**
+ * Fold a MusicXML transposition onto a lilylet clef as a suffix.
+ *
+ * MusicXML keeps the two apart: <transpose> is the sounding shift and moves pitch,
+ * <clef-octave-change> is the "8" glyph under the clef and moves nothing. A lilylet
+ * suffix means sounding shift, so only ONE of them may be folded in — adding both
+ * would double an octave clef that also declares <transpose> (the shape this
+ * encoder itself now emits) into two octaves.
+ *
+ * <transpose> wins when present, being the explicit statement of sounding pitch.
+ * Absent it, an octave clef is read as implying its own shift, which is what a
+ * tenor-voice or guitar treble_8 part means.
+ *
+ * A shift with no exact suffix (only the tritone) leaves the clef plain rather than
+ * rounding: a silently wrong sounding pitch is worse than a visibly absent shift.
+ */
+const clefWithShift = (
+	clef: Clef | undefined,
+	transposeSemitones: number,
+	clefOctaveChange?: number,
+): Clef | undefined => {
+	if (!clef) return clef;
+	const semitones = transposeSemitones !== 0 ? transposeSemitones : 12 * (clefOctaveChange ?? 0);
+	if (semitones === 0) return clef;
+	const shifted = withClefTransposition(clef as string, semitones);
+	if (shifted === undefined) {
+		console.warn(`musicXmlDecoder: transposition ${semitones} has no exact clef suffix; dropped for clef "${clef}"`);
+		return clef;
+	}
+	return shifted as Clef;
+};
+
 /**
  * Total time a TupletEvent advances the voice, in voiceTracker duration units.
  * Sum the inner note/rest values then apply the tuplet ratio (triplet etc.).
@@ -1281,7 +1331,10 @@ const convertMeasure = (
 	voiceTracker: VoiceTracker,
 	spannerTracker: SpannerTracker,
 	ottavaTracker: { current: number },
-	tupletTracker: TupletTracker
+	tupletTracker: TupletTracker,
+	// A part's <transpose> is declared once, usually in measure 1, and stays in force
+	// for the whole part, so it has to survive across measures like the ottava does.
+	transposeTracker: { semitones: number }
 ): MeasureConversionResult => {
 	let key: KeySignature | undefined;
 	let timeSig: Fraction | undefined;
@@ -1369,10 +1422,20 @@ const convertMeasure = (
 				timeSig = createFraction(attrs.time.beats, attrs.time.beatType);
 			}
 
+			// Instrument transposition, in force from here to the end of the part.
+			if (attrs.transpose) {
+				const { chromatic, octaveChange } = attrs.transpose;
+				transposeTracker.semitones = chromatic + 12 * (octaveChange ?? 0);
+			}
+
 			// Clefs - store by staff number
 			if (attrs.clefs) {
 				for (const clefEntry of attrs.clefs) {
-					const clef = convertClef(clefEntry.clef.sign, clefEntry.clef.line);
+					const clef = clefWithShift(
+						convertClef(clefEntry.clef.sign, clefEntry.clef.line),
+						transposeTracker.semitones,
+						clefEntry.clef.clefOctaveChange,
+					);
 					if (clef) {
 						const staff = clefEntry.staff;
 						if (staffHasNotes.has(staff)) {
@@ -1761,6 +1824,7 @@ const convertPart = (partEl: Element): { measures: Measure[]; name?: string } =>
 	const voiceTracker = new VoiceTracker();
 	const spannerTracker = new SpannerTracker();
 	const ottavaTracker = { current: 0 };
+	const transposeTracker = { semitones: 0 };
 	const tupletTracker = new TupletTracker();
 
 	let lastKey: KeySignature | undefined;
@@ -1779,7 +1843,7 @@ const convertPart = (partEl: Element): { measures: Measure[]; name?: string } =>
 
 	for (const measureEl of measureEls) {
 		voiceTracker.reset();
-		const { voiceMap, key, timeSig, barline, leadingBarline, harmonies, clefs } = convertMeasure(measureEl, voiceTracker, spannerTracker, ottavaTracker, tupletTracker);
+		const { voiceMap, key, timeSig, barline, leadingBarline, harmonies, clefs } = convertMeasure(measureEl, voiceTracker, spannerTracker, ottavaTracker, tupletTracker, transposeTracker);
 
 		// A forward-repeat (or any `location="left"`) barline belongs at the END of
 		// the PREVIOUS measure in lilylet's "\bar = current measure's end bar" model.

package/source/lilylet/musicXmlEncoder.ts

@@ -48,6 +48,8 @@ import {
 
 import { parseStaffLayout, StaffGroup, StaffGroupType } from "./staffLayout";
 
+import { clefBaseName, clefSuffixSemitones, clefSuffixTransposition } from "./clefTransposition";
+
 
 // === Constants and Reverse Mappings ===
 
@@ -304,13 +306,45 @@ const encodeAttributes = (
 	}
 
 	if (options.clef) {
-		const clefInfo = CLEF_TO_SIGN[options.clef];
+		// Look the sign/line up under the BASE name. A lilylet clef may carry a
+		// transposition suffix ("treble_8", "treble_m3"), and keying the table on the
+		// whole string missed every one of them — `clefInfo` came back undefined and
+		// the <clef> element was dropped entirely, sign and line with it.
+		const clefStr = options.clef as string;
+		const clefInfo = CLEF_TO_SIGN[clefBaseName(clefStr)];
 		if (clefInfo) {
 			xml += `${indent(level + 1)}<clef>\n`;
 			xml += `${indent(level + 2)}<sign>${clefInfo.sign}</sign>\n`;
 			xml += `${indent(level + 2)}<line>${clefInfo.line}</line>\n`;
+			// A whole-octave shift also has a notational form: the "8" drawn under or
+			// over the clef. This is the glyph only — sounding pitch rides on
+			// <transpose> below, exactly as in LilyPond.
+			const semitones = clefSuffixSemitones(clefStr);
+			if (semitones % 12 === 0 && semitones !== 0)
+				xml += `${indent(level + 2)}<clef-octave-change>${semitones / 12}</clef-octave-change>\n`;
 			xml += `${indent(level + 1)}</clef>\n`;
 		}
+
+		// The written->sounding transposition. MusicXML carries the diatonic step count
+		// and the chromatic semitone count separately, which is what lets a minor third
+		// (-2 steps, -3 semitones) be expressed exactly. <transpose> follows <clef> in
+		// the attributes content order.
+		const trans = clefSuffixTransposition(clefStr);
+		if (trans) {
+			// <diatonic> and <chromatic> hold the WITHIN-OCTAVE remainder and whole
+			// octaves go in <octave-change>, so both must be reduced by the same octave
+			// count: 7 diatonic steps and 12 semitones each. Reducing only the semitones
+			// would make an octave clef read as two octaves.
+			const octaveChange = Math.trunc(trans.semi / 12);
+			const diatonic = trans.diat - 7 * octaveChange;
+			const chromatic = trans.semi - 12 * octaveChange;
+			xml += `${indent(level + 1)}<transpose>\n`;
+			xml += `${indent(level + 2)}<diatonic>${diatonic}</diatonic>\n`;
+			xml += `${indent(level + 2)}<chromatic>${chromatic}</chromatic>\n`;
+			if (octaveChange !== 0)
+				xml += `${indent(level + 2)}<octave-change>${octaveChange}</octave-change>\n`;
+			xml += `${indent(level + 1)}</transpose>\n`;
+		}
 	}
 
 	xml += `${indent(level)}</attributes>\n`;

package/source/lilylet/musicXmlTypes.ts

@@ -41,12 +41,22 @@ export interface MusicXmlClef {
 	clefOctaveChange?: number; // -1, 0, 1
 }
 
+// A part's written->sounding transposition. diatonic/chromatic hold the
+// within-octave remainder and octaveChange the whole octaves, so the total shift is
+// chromatic + 12 * octaveChange semitones.
+export interface MusicXmlTranspose {
+	diatonic?: number;
+	chromatic: number;
+	octaveChange?: number;
+}
+
 export interface MusicXmlAttributes {
 	divisions?: number;     // Divisions per quarter note
 	key?: MusicXmlKey;
 	time?: MusicXmlTime;
 	clefs?: { staff: number; clef: MusicXmlClef }[];  // Clefs by staff number
 	staves?: number;        // Number of staves
+	transpose?: MusicXmlTranspose;  // Instrument transposition, folded into the clef suffix
 }
 
 // ============ Note Types ============