@k-l-lambda/lilylet 0.1.88 → 0.1.90

package/lib/lilylet/meiEncoder.js

@@ -2,6 +2,7 @@ import { Clef, Accidental, OrnamentType, StemDirection, HairpinType, PedalType,
 import { parseStaffLayout, StaffGroupType } from "./staffLayout.js";
 import { gmProgramOf } from "./gmInstruments.js";
 import { parseMeasureLayout, expandMeasureLayout, decomposeToSegments } from "./measureLayout.js";
+import { clefBaseName, clefSuffixTransposition } from "./clefTransposition.js";
 // MEI key signatures: positive = sharps, negative = flats
 const KEY_SIGS = {
     0: "0",
@@ -49,36 +50,27 @@ const CLEF_SHAPES = {
 };
 // Semitone offsets of the major/perfect intervals within one diatonic octave,
 // indexed by diatonic step (0 = unison, 1 = 2nd, … 6 = 7th).
-const DIATONIC_SEMITONES = [0, 2, 4, 5, 7, 9, 11];
 // Convert a LilyPond clef interval-number suffix into an MEI written→sounding
 // transposition. The number N is a diatonic interval number (2 = 2nd, 3 = 3rd,
 // 5 = 5th, 8 = octave, 15 = two octaves); "_" lowers the sounding pitch, "^"
 // raises it. Returns { diat, semi } where diat is the diatonic step shift
 // (N - 1, signed) and semi is the corresponding chromatic shift in semitones,
 // extended octave-wise for compound intervals.
-const clefTransposition = (intervalNumber, up) => {
-    const k = intervalNumber - 1; // diatonic steps
-    const semis = DIATONIC_SEMITONES[k % 7] + 12 * Math.floor(k / 7);
-    const sign = up ? 1 : -1;
-    return { diat: sign * k, semi: sign * semis };
-};
 // Resolve a clef string into MEI shape/line plus optional written→sounding
-// transposition. Per the LilyPond convention a "_N"/"^N" suffix transposes the
-// clef down/up by the diatonic interval N (e.g. "treble_8" octave down,
-// "treble_5" fifth down, "treble^3" third up). MEI's clef.dis only covers octave
-// displacement (8|15|22), so all clef transposition — octaves included — is
-// encoded uniformly via att.transposition (trans.diat / trans.semi) on staffDef.
+// transposition. A "_N"/"^N" suffix transposes the clef down/up by the diatonic
+// interval N ("treble_8" octave down, "treble_5" fifth down), and "_mN"/"^mN"
+// selects that interval's minor form ("treble_m3" = minor third down) — see
+// clefTransposition.ts. MEI's clef.dis only covers octave displacement
+// (8|15|22), so all clef transposition — octaves included — is encoded uniformly
+// via att.transposition (trans.diat / trans.semi) on staffDef. A minor interval is
+// exactly why both fields are needed: a minor third is {diat:-2, semi:-3}.
 const resolveClef = (clefStr) => {
-    const match = clefStr.match(/^(.*?)([_^])(\d+)$/);
-    const base = match ? match[1] : clefStr;
-    const clefInfo = CLEF_SHAPES[base] || CLEF_SHAPES.treble;
-    if (!match)
-        return { shape: clefInfo.shape, line: clefInfo.line };
-    const trans = clefTransposition(Number(match[3]), match[2] === "^");
+    const clefInfo = CLEF_SHAPES[clefBaseName(clefStr)] || CLEF_SHAPES.treble;
+    const trans = clefSuffixTransposition(clefStr);
     return {
         shape: clefInfo.shape,
         line: clefInfo.line,
-        trans,
+        ...(trans ? { trans } : {}),
     };
 };
 // Attributes for a standalone <clef> element (mid-measure clef change).

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/lib/lilylet/onsets.d.ts

@@ -9,10 +9,11 @@
  * Shared by tools/astServer.ts (the HTTP onset API) and the clef-onset unit test.
  */
 /**
- * The written->sounding semitone shift a clef string declares. Per the LilyPond convention a
- * "_N"/"^N" suffix transposes DOWN/UP by the diatonic interval N: "treble_8" = octave down
- * (-12), "treble^8" = +12, "treble_15" = two octaves down (-24), "treble_5" = fifth down (-7).
- * A plain clef (no suffix) declares 0.
+ * The written->sounding semitone shift a clef string declares. A "_N"/"^N" suffix transposes
+ * DOWN/UP by the diatonic interval N ("treble_8" = octave down, -12; "treble_5" = fifth down,
+ * -7), and an "m" before the number selects that interval's MINOR form ("treble_m3" = minor
+ * third down, -3). A plain clef declares 0. See clefTransposition.ts for the grammar; this is
+ * a thin alias kept because clefShift is the name the onset API and its tests already use.
  */
 export declare const clefShift: (clefStr: string) => number;
 /**

package/lib/lilylet/onsets.js

@@ -10,6 +10,7 @@
  */
 import { calculateDuration } from "./musicXmlUtils.js";
 import { Accidental } from "./types.js";
+import { clefSuffixSemitones } from "./clefTransposition.js";
 // Onset resolution in ticks per quarter note. calculateDuration() rounds its result to an
 // integer, so it must run at a resolution fine enough to represent every note value exactly:
 // the shared DIVISIONS=4 (MusicXML export) rounds a 32nd (0.5) and a dotted 16th (1.5) to
@@ -21,22 +22,14 @@ const ACCIDENTAL_SEMITONE = {
     [Accidental.natural]: 0, [Accidental.sharp]: 1, [Accidental.flat]: -1,
     [Accidental.doubleSharp]: 2, [Accidental.doubleFlat]: -2,
 };
-// Diatonic-step -> semitones within an octave (unison..seventh), for "_N"/"^N" clef suffixes.
-const DIATONIC_SEMITONES = [0, 2, 4, 5, 7, 9, 11];
 /**
- * The written->sounding semitone shift a clef string declares. Per the LilyPond convention a
- * "_N"/"^N" suffix transposes DOWN/UP by the diatonic interval N: "treble_8" = octave down
- * (-12), "treble^8" = +12, "treble_15" = two octaves down (-24), "treble_5" = fifth down (-7).
- * A plain clef (no suffix) declares 0.
+ * The written->sounding semitone shift a clef string declares. A "_N"/"^N" suffix transposes
+ * DOWN/UP by the diatonic interval N ("treble_8" = octave down, -12; "treble_5" = fifth down,
+ * -7), and an "m" before the number selects that interval's MINOR form ("treble_m3" = minor
+ * third down, -3). A plain clef declares 0. See clefTransposition.ts for the grammar; this is
+ * a thin alias kept because clefShift is the name the onset API and its tests already use.
  */
-export const clefShift = (clefStr) => {
-    const m = /^.*?([_^])(\d+)$/.exec(clefStr || "");
-    if (!m)
-        return 0;
-    const k = parseInt(m[2], 10) - 1; // diatonic steps above unison
-    const semis = DIATONIC_SEMITONES[k % 7] + 12 * Math.floor(k / 7);
-    return (m[1] === "^" ? 1 : -1) * semis;
-};
+export const clefShift = (clefStr) => clefSuffixSemitones(clefStr);
 /**
  * Sounding MIDI pitch of a resolved (absolute-octave) Lilylet pitch. Octave 0 = middle-C
  * octave = MIDI 60 (see parser.resolveRelativePitch). `shift` is the active clef's

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k-l-lambda/lilylet",
-  "version": "0.1.88",
+  "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",
@@ -55,6 +55,9 @@
     "test:abc-instrument": "tsx ./tests/unit/abcInstrumentName.test.ts",
     "test:abc-partial": "tsx ./tests/unit/abcPartialPickup.test.ts",
     "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/abc/abc.jison

@@ -213,6 +213,7 @@ SPECIAL								[:!^_,'/<>={}()\[\]|.\-+~&]
 
 ^[T][:][\s]*						{ var pre = this.matched.slice(0, this.matched.length - yytext.length); if (pre === '' || pre.slice(-1) === '\n') { this.pushState('title_string'); return 'T:'; } this.unput(yytext.slice(1)); yytext = 'T'; return 'T'; }
 ^[C][:][\s]*						{ var pre = this.matched.slice(0, this.matched.length - yytext.length); if (pre === '' || pre.slice(-1) === '\n') { this.pushState('title_string'); return 'C:'; } this.unput(yytext.slice(1)); yytext = 'C'; return 'A'; }
+^[ABDFGHINORSWZ][:](?![|])[ \t]*	{ var pre = this.matched.slice(0, this.matched.length - yytext.length); if (pre === '' || pre.slice(-1) === '\n') { this.pushState('title_string'); yytext = yytext[0]; return 'TEXT_FIELD'; } this.unput(yytext.slice(1)); yytext = yytext[0]; return 'H'; }
 <title_string>\n					{ this.popState(); }
 <title_string>[^\n]+				return 'STR_CONTENT'
 
@@ -379,6 +380,7 @@ head_line
 	| 'K:' key_signature				-> header('K', $2)
 	| 'V:' header_value					-> header('V', $2)
 	| H ':' header_value				-> header($1, $3)
+	| TEXT_FIELD string_content			-> header($1, $2)
 	;
 
 header_value