@k-l-lambda/lilylet 0.1.86 → 0.1.89

package/lib/lilylet/transposition.js

@@ -0,0 +1,238 @@
+import { Accidental, Phonet, } from "./types.js";
+const PHONET_SEMITONE = {
+    [Phonet.c]: 0,
+    [Phonet.d]: 2,
+    [Phonet.e]: 4,
+    [Phonet.f]: 5,
+    [Phonet.g]: 7,
+    [Phonet.a]: 9,
+    [Phonet.b]: 11,
+};
+const ACCIDENTAL_SEMITONE = {
+    [Accidental.natural]: 0,
+    [Accidental.sharp]: 1,
+    [Accidental.flat]: -1,
+    [Accidental.doubleSharp]: 2,
+    [Accidental.doubleFlat]: -2,
+};
+// Chromatic pitches have several enharmonic names. Follow the transposition
+// direction where a choice exists: upward motion prefers sharps, downward
+// motion prefers flats. Both tables use only accidentals supported by Lilylet.
+const SHARP_SPELLINGS = [
+    { phonet: Phonet.c },
+    { phonet: Phonet.c, accidental: Accidental.sharp },
+    { phonet: Phonet.d },
+    { phonet: Phonet.d, accidental: Accidental.sharp },
+    { phonet: Phonet.e },
+    { phonet: Phonet.f },
+    { phonet: Phonet.f, accidental: Accidental.sharp },
+    { phonet: Phonet.g },
+    { phonet: Phonet.g, accidental: Accidental.sharp },
+    { phonet: Phonet.a },
+    { phonet: Phonet.a, accidental: Accidental.sharp },
+    { phonet: Phonet.b },
+];
+const FLAT_SPELLINGS = [
+    { phonet: Phonet.c },
+    { phonet: Phonet.d, accidental: Accidental.flat },
+    { phonet: Phonet.d },
+    { phonet: Phonet.e, accidental: Accidental.flat },
+    { phonet: Phonet.e },
+    { phonet: Phonet.f },
+    { phonet: Phonet.g, accidental: Accidental.flat },
+    { phonet: Phonet.g },
+    { phonet: Phonet.a, accidental: Accidental.flat },
+    { phonet: Phonet.a },
+    { phonet: Phonet.b, accidental: Accidental.flat },
+    { phonet: Phonet.b },
+];
+const MAJOR_KEY_BY_FIFTHS = {
+    [-6]: { phonet: Phonet.g, accidental: Accidental.flat },
+    [-5]: { phonet: Phonet.d, accidental: Accidental.flat },
+    [-4]: { phonet: Phonet.a, accidental: Accidental.flat },
+    [-3]: { phonet: Phonet.e, accidental: Accidental.flat },
+    [-2]: { phonet: Phonet.b, accidental: Accidental.flat },
+    [-1]: { phonet: Phonet.f },
+    [0]: { phonet: Phonet.c },
+    [1]: { phonet: Phonet.g },
+    [2]: { phonet: Phonet.d },
+    [3]: { phonet: Phonet.a },
+    [4]: { phonet: Phonet.e },
+    [5]: { phonet: Phonet.b },
+    [6]: { phonet: Phonet.f, accidental: Accidental.sharp },
+};
+const MINOR_KEY_BY_FIFTHS = {
+    [-6]: { phonet: Phonet.e, accidental: Accidental.flat },
+    [-5]: { phonet: Phonet.b, accidental: Accidental.flat },
+    [-4]: { phonet: Phonet.f },
+    [-3]: { phonet: Phonet.c },
+    [-2]: { phonet: Phonet.g },
+    [-1]: { phonet: Phonet.d },
+    [0]: { phonet: Phonet.a },
+    [1]: { phonet: Phonet.e },
+    [2]: { phonet: Phonet.b },
+    [3]: { phonet: Phonet.f, accidental: Accidental.sharp },
+    [4]: { phonet: Phonet.c, accidental: Accidental.sharp },
+    [5]: { phonet: Phonet.g, accidental: Accidental.sharp },
+    [6]: { phonet: Phonet.d, accidental: Accidental.sharp },
+};
+const DIATONIC_INDEX = {
+    [Phonet.c]: 0,
+    [Phonet.d]: 1,
+    [Phonet.e]: 2,
+    [Phonet.f]: 3,
+    [Phonet.g]: 4,
+    [Phonet.a]: 5,
+    [Phonet.b]: 6,
+};
+const NATURAL_MAJOR_FIFTHS = {
+    [Phonet.c]: 0, [Phonet.d]: 2, [Phonet.e]: 4, [Phonet.f]: -1,
+    [Phonet.g]: 1, [Phonet.a]: 3, [Phonet.b]: 5,
+};
+const MAJOR_SCALE = [0, 2, 4, 5, 7, 9, 11];
+const MINOR_SCALE = [0, 2, 3, 5, 7, 8, 10];
+const mod = (value, divisor) => ((value % divisor) + divisor) % divisor;
+const pitchClass = (pitch) => PHONET_SEMITONE[pitch.phonet] + (pitch.accidental ? ACCIDENTAL_SEMITONE[pitch.accidental] : 0);
+const keyDegreePitchClass = (key, degree) => {
+    const scale = key.mode === "minor" ? MINOR_SCALE : MAJOR_SCALE;
+    return mod(keyPitchClass(key) + scale[degree], 12);
+};
+const signedAlteration = (actual, expected) => {
+    let alteration = mod(actual - expected + 6, 12) - 6;
+    if (alteration === -6)
+        alteration = 6;
+    return alteration;
+};
+const accidentalFor = (alteration) => ({
+    [-2]: Accidental.doubleFlat,
+    [-1]: Accidental.flat,
+    [0]: undefined,
+    [1]: Accidental.sharp,
+    [2]: Accidental.doubleSharp,
+}[alteration]);
+const transposePitchInKey = (pitch, sourceKey, targetKey, semitones) => {
+    const sourceDegree = mod(DIATONIC_INDEX[pitch.phonet] - DIATONIC_INDEX[sourceKey.pitch], 7);
+    const alteration = signedAlteration(pitchClass(pitch), keyDegreePitchClass(sourceKey, sourceDegree));
+    const targetIndex = mod(DIATONIC_INDEX[targetKey.pitch] + sourceDegree, 7);
+    const targetPhonet = Object.keys(DIATONIC_INDEX).find(phonet => DIATONIC_INDEX[phonet] === targetIndex);
+    const targetExpected = keyDegreePitchClass(targetKey, sourceDegree);
+    const writtenAccidental = signedAlteration(targetExpected + alteration, PHONET_SEMITONE[targetPhonet]);
+    const accidental = accidentalFor(writtenAccidental);
+    if (accidental === undefined && writtenAccidental !== 0)
+        return undefined;
+    const targetAbsolute = pitch.octave * 12 + pitchClass(pitch) + semitones;
+    const rawTargetClass = PHONET_SEMITONE[targetPhonet] + writtenAccidental;
+    const octave = Math.floor((targetAbsolute - rawTargetClass) / 12);
+    return {
+        phonet: targetPhonet,
+        ...(accidental ? { accidental } : {}),
+        octave,
+        ...(pitch.courtesy !== undefined ? { courtesy: pitch.courtesy } : {}),
+    };
+};
+const spellingFor = (pitchClass, semitones) => (semitones < 0 ? FLAT_SPELLINGS : SHARP_SPELLINGS)[mod(pitchClass, 12)];
+const keyFifths = (key) => {
+    let fifths = NATURAL_MAJOR_FIFTHS[key.pitch];
+    if (key.accidental === Accidental.sharp)
+        fifths += 7;
+    else if (key.accidental === Accidental.flat)
+        fifths -= 7;
+    if (key.mode === "minor")
+        fifths -= 3;
+    return fifths;
+};
+const spellingPitchClass = (spelling) => mod(PHONET_SEMITONE[spelling.phonet] + (spelling.accidental ? ACCIDENTAL_SEMITONE[spelling.accidental] : 0), 12);
+const keyPitchClass = (key) => spellingPitchClass({ phonet: key.pitch, accidental: key.accidental });
+const normalizedKeyFor = (pitchClass, mode, semitones) => {
+    const candidates = Object.entries(mode === "minor" ? MINOR_KEY_BY_FIFTHS : MAJOR_KEY_BY_FIFTHS)
+        .map(([fifths, spelling]) => ({ fifths: Number(fifths), spelling }))
+        .filter(candidate => spellingPitchClass(candidate.spelling) === mod(pitchClass, 12));
+    const preferred = candidates.find(candidate => semitones < 0 ? candidate.fifths < 0 : candidate.fifths >= 0)
+        ?? candidates[0];
+    if (!preferred)
+        throw new Error(`No normalized ${mode} key for pitch class ${mod(pitchClass, 12)}`);
+    return {
+        pitch: preferred.spelling.phonet,
+        ...(preferred.spelling.accidental ? { accidental: preferred.spelling.accidental } : {}),
+        mode,
+    };
+};
+/** Transpose one resolved Lilylet pitch by an integer number of semitones. */
+export const transposePitch = (pitch, semitones) => {
+    if (semitones === 0)
+        return { ...pitch };
+    const absolute = pitch.octave * 12 + pitchClass(pitch) + semitones;
+    const octave = Math.floor(absolute / 12);
+    const spelling = spellingFor(absolute, semitones);
+    return {
+        phonet: spelling.phonet,
+        ...(spelling.accidental ? { accidental: spelling.accidental } : {}),
+        octave,
+        ...(pitch.courtesy !== undefined ? { courtesy: pitch.courtesy } : {}),
+    };
+};
+const transposeKey = (key, semitones) => {
+    const sourceClass = keyPitchClass(key);
+    const target = spellingFor(sourceClass + semitones, semitones);
+    const directional = {
+        pitch: target.phonet,
+        ...(target.accidental ? { accidental: target.accidental } : {}),
+        mode: key.mode,
+    };
+    return Math.abs(keyFifths(directional)) <= 6
+        ? directional
+        : normalizedKeyFor(sourceClass + semitones, key.mode, semitones);
+};
+const transposePitchWithKeys = (pitch, sourceKey, targetKey, semitones) => transposePitchInKey(pitch, sourceKey, targetKey, semitones) ?? transposePitch(pitch, semitones);
+const transposeEvent = (event, semitones, state) => {
+    switch (event.type) {
+        case "note":
+            return { ...event, pitches: event.pitches.map(pitch => transposePitchWithKeys(pitch, state.source, state.target, semitones)) };
+        case "rest":
+            return { ...event, ...(event.pitch ? { pitch: transposePitchWithKeys(event.pitch, state.source, state.target, semitones) } : {}) };
+        case "context": {
+            const context = event;
+            if (context.key) {
+                state.source = context.key;
+                state.target = transposeKey(context.key, semitones);
+            }
+            return { ...context, ...(context.key ? { key: state.target } : {}) };
+        }
+        case "tremolo":
+            return { ...event,
+                pitchA: event.pitchA.map(p => transposePitchWithKeys(p, state.source, state.target, semitones)),
+                pitchB: event.pitchB.map(p => transposePitchWithKeys(p, state.source, state.target, semitones)) };
+        case "tuplet":
+        case "times":
+            return { ...event, events: event.events.map(inner => transposeEvent(inner, semitones, state)) };
+        default:
+            return { ...event };
+    }
+};
+const transposeVoice = (voice, semitones, measureKey) => {
+    const state = { source: measureKey, target: transposeKey(measureKey, semitones) };
+    return { ...voice, events: voice.events.map(event => transposeEvent(event, semitones, state)) };
+};
+const transposePart = (part, semitones, measureKey) => ({
+    ...part,
+    voices: part.voices.map(voice => transposeVoice(voice, semitones, measureKey)),
+});
+const transposeMeasure = (measure, semitones, inheritedKey) => {
+    const sourceKey = measure.key ?? inheritedKey;
+    const targetKey = transposeKey(sourceKey, semitones);
+    return {
+        ...measure,
+        ...(measure.key ? { key: targetKey } : {}),
+        parts: measure.parts.map(part => transposePart(part, semitones, sourceKey)),
+    };
+};
+/** Return a new Lilylet document with every AST pitch shifted chromatically. */
+export const transposeDoc = (doc, semitones) => {
+    if (!Number.isFinite(semitones) || !Number.isInteger(semitones)) {
+        throw new Error("transposeDoc semitones must be a finite integer");
+    }
+    return {
+        ...doc,
+        measures: doc.measures.map(measure => transposeMeasure(measure, semitones, { pitch: Phonet.c, mode: "major" })),
+    };
+};

package/lib/transposition.d.ts

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

package/lib/transposition.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k-l-lambda/lilylet",
-  "version": "0.1.86",
+  "version": "0.1.89",
   "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,7 +55,10 @@
     "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: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",
     "test:roundtrip:compiled": "node lib-tests/tests/lilypond-roundtrip.js",
     "ts": "tsx"

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