@k-l-lambda/lilylet 0.1.62 → 0.1.64

package/lib/source/lilylet/musicXmlUtils.js

@@ -0,0 +1,469 @@
+/**
+ * MusicXML Utility Functions
+ *
+ * Helper functions for parsing MusicXML elements and converting values.
+ */
+import { Phonet, Accidental, Clef, StemDirection, ArticulationType, OrnamentType, DynamicType, HairpinType, PedalType, } from "./types.js";
+// ============ XML Element Helpers ============
+/**
+ * Get text content of a child element by tag name
+ */
+export const getElementText = (parent, tagName) => {
+    const el = parent.getElementsByTagName(tagName)[0];
+    return el?.textContent?.trim() || undefined;
+};
+/**
+ * Get numeric content of a child element
+ */
+export const getElementNumber = (parent, tagName) => {
+    const text = getElementText(parent, tagName);
+    if (text === undefined)
+        return undefined;
+    const num = parseFloat(text);
+    return isNaN(num) ? undefined : num;
+};
+/**
+ * Get integer content of a child element
+ */
+export const getElementInt = (parent, tagName) => {
+    const text = getElementText(parent, tagName);
+    if (text === undefined)
+        return undefined;
+    const num = parseInt(text, 10);
+    return isNaN(num) ? undefined : num;
+};
+/**
+ * Check if element has a child with given tag name
+ */
+export const hasElement = (parent, tagName) => {
+    return parent.getElementsByTagName(tagName).length > 0;
+};
+/**
+ * Get attribute value from element
+ */
+export const getAttribute = (el, name) => {
+    const attr = el.getAttribute(name);
+    return attr || undefined;
+};
+/**
+ * Get numeric attribute value
+ */
+export const getAttributeNumber = (el, name) => {
+    const text = getAttribute(el, name);
+    if (text === undefined)
+        return undefined;
+    const num = parseFloat(text);
+    return isNaN(num) ? undefined : num;
+};
+/**
+ * Get all child elements with given tag name
+ */
+export const getElements = (parent, tagName) => {
+    return Array.from(parent.getElementsByTagName(tagName));
+};
+/**
+ * Get all direct child elements (xmldom compatible - uses childNodes)
+ */
+export const getChildElements = (parent) => {
+    const result = [];
+    for (let i = 0; i < parent.childNodes.length; i++) {
+        const node = parent.childNodes[i];
+        if (node.nodeType === 1) { // ELEMENT_NODE
+            result.push(node);
+        }
+    }
+    return result;
+};
+/**
+ * Get direct child elements (not nested)
+ * Note: Uses childNodes instead of children for xmldom compatibility
+ */
+export const getDirectChildren = (parent, tagName) => {
+    const result = [];
+    for (let i = 0; i < parent.childNodes.length; i++) {
+        const node = parent.childNodes[i];
+        if (node.nodeType === 1 && node.tagName === tagName) {
+            result.push(node);
+        }
+    }
+    return result;
+};
+// ============ Pitch Conversion ============
+const STEP_TO_PHONET = {
+    C: Phonet.c,
+    D: Phonet.d,
+    E: Phonet.e,
+    F: Phonet.f,
+    G: Phonet.g,
+    A: Phonet.a,
+    B: Phonet.b,
+};
+const ALTER_TO_ACCIDENTAL = {
+    [-2]: Accidental.doubleFlat,
+    [-1]: Accidental.flat,
+    [1]: Accidental.sharp,
+    [2]: Accidental.doubleSharp,
+};
+/**
+ * Convert MusicXML pitch to Lilylet Pitch
+ * MusicXML octave 4 = middle C octave = Lilylet octave 0
+ */
+export const convertPitch = (step, alter, octave) => {
+    const phonet = STEP_TO_PHONET[step.toUpperCase()];
+    if (!phonet) {
+        throw new Error(`Invalid pitch step: ${step}`);
+    }
+    const accidental = alter !== undefined && alter !== 0
+        ? ALTER_TO_ACCIDENTAL[alter]
+        : undefined;
+    // MusicXML octave 4 = Lilylet octave 0
+    const lilyletOctave = octave - 4;
+    return {
+        phonet,
+        accidental,
+        octave: lilyletOctave,
+    };
+};
+// ============ Duration Constants & Mappings ============
+// Standard divisions per quarter note (shared by encoder/decoder)
+export const DIVISIONS = 4;
+// MusicXML note type to division (1=whole, 2=half, 4=quarter, etc.)
+export const TYPE_TO_DIVISION = {
+    maxima: 0.125,
+    long: 0.25,
+    breve: 0.5,
+    whole: 1,
+    half: 2,
+    quarter: 4,
+    eighth: 8,
+    '16th': 16,
+    '32nd': 32,
+    '64th': 64,
+    '128th': 128,
+    '256th': 256,
+    '512th': 512,
+    '1024th': 1024,
+};
+// Division to MusicXML note type (inverse of TYPE_TO_DIVISION)
+export const DIVISION_TO_TYPE = Object.fromEntries(Object.entries(TYPE_TO_DIVISION).map(([type, div]) => [div, type]));
+/**
+ * Calculate duration in MusicXML divisions.
+ * Shared by encoder (with DIVISIONS=4) and potentially decoder.
+ *
+ * Duration.tuplet is in Lilylet ratio semantics:
+ *   \times 2/3 → {numerator:2, denominator:3} → multiply by 2/3
+ */
+export const calculateDuration = (duration, divisions = DIVISIONS) => {
+    // Base duration: divisions * (4 / division)
+    // e.g., quarter (4) = divisions * 1
+    //       half (2) = divisions * 2
+    //       eighth (8) = divisions * 0.5
+    let dur = divisions * (4 / duration.division);
+    // Apply dots
+    if (duration.dots) {
+        let dotValue = dur / 2;
+        for (let i = 0; i < duration.dots; i++) {
+            dur += dotValue;
+            dotValue /= 2;
+        }
+    }
+    // Apply tuplet ratio: Lilylet ratio num/den means multiply by num/den
+    // e.g., \times 2/3 means each note's actual duration = written * 2/3
+    if (duration.tuplet) {
+        dur = dur * duration.tuplet.numerator / duration.tuplet.denominator;
+    }
+    return Math.round(dur);
+};
+/**
+ * Convert MusicXML duration to Lilylet Duration
+ *
+ * @param divisions - Current divisions value (divisions per quarter note)
+ * @param duration - Duration value in divisions
+ * @param type - Note type (quarter, eighth, etc.)
+ * @param dots - Number of dots
+ * @param timeModification - Tuplet info
+ */
+export const convertDuration = (divisions, duration, type, dots = 0, timeModification) => {
+    let division;
+    if (type && TYPE_TO_DIVISION[type]) {
+        division = TYPE_TO_DIVISION[type];
+    }
+    else {
+        // Calculate from duration and divisions
+        // duration / divisions = quarter notes
+        // division = 4 / quarter_notes
+        const quarterNotes = duration / divisions;
+        division = 4 / quarterNotes;
+        // Round to nearest valid division
+        const validDivisions = [0.5, 1, 2, 4, 8, 16, 32, 64, 128];
+        division = validDivisions.reduce((prev, curr) => Math.abs(curr - division) < Math.abs(prev - division) ? curr : prev);
+    }
+    const result = {
+        division,
+        dots,
+    };
+    if (timeModification) {
+        // Store as Lilylet ratio: normalNotes/actualNotes
+        // MusicXML actual=3, normal=2 (triplet) → Lilylet ratio {num:2, den:3}
+        result.tuplet = {
+            numerator: timeModification.normalNotes,
+            denominator: timeModification.actualNotes,
+        };
+    }
+    return result;
+};
+// ============ Key Signature Conversion ============
+// Fifths to key signature mapping (major mode)
+const FIFTHS_TO_KEY_MAJOR = {
+    [-7]: { pitch: Phonet.c, accidental: Accidental.flat },
+    [-6]: { pitch: Phonet.g, accidental: Accidental.flat },
+    [-5]: { pitch: Phonet.d, accidental: Accidental.flat },
+    [-4]: { pitch: Phonet.a, accidental: Accidental.flat },
+    [-3]: { pitch: Phonet.e, accidental: Accidental.flat },
+    [-2]: { pitch: Phonet.b, accidental: Accidental.flat },
+    [-1]: { pitch: Phonet.f },
+    [0]: { pitch: Phonet.c },
+    [1]: { pitch: Phonet.g },
+    [2]: { pitch: Phonet.d },
+    [3]: { pitch: Phonet.a },
+    [4]: { pitch: Phonet.e },
+    [5]: { pitch: Phonet.b },
+    [6]: { pitch: Phonet.f, accidental: Accidental.sharp },
+    [7]: { pitch: Phonet.c, accidental: Accidental.sharp },
+};
+// Fifths to key signature mapping (minor mode)
+const FIFTHS_TO_KEY_MINOR = {
+    [-7]: { pitch: Phonet.a, accidental: Accidental.flat },
+    [-6]: { pitch: Phonet.e, accidental: Accidental.flat },
+    [-5]: { pitch: Phonet.b, accidental: Accidental.flat },
+    [-4]: { pitch: Phonet.f },
+    [-3]: { pitch: Phonet.c },
+    [-2]: { pitch: Phonet.g },
+    [-1]: { pitch: Phonet.d },
+    [0]: { pitch: Phonet.a },
+    [1]: { pitch: Phonet.e },
+    [2]: { pitch: Phonet.b },
+    [3]: { pitch: Phonet.f, accidental: Accidental.sharp },
+    [4]: { pitch: Phonet.c, accidental: Accidental.sharp },
+    [5]: { pitch: Phonet.g, accidental: Accidental.sharp },
+    [6]: { pitch: Phonet.d, accidental: Accidental.sharp },
+    [7]: { pitch: Phonet.a, accidental: Accidental.sharp },
+};
+/**
+ * Convert MusicXML key (fifths, mode) to KeySignature
+ */
+export const convertKeySignature = (fifths, mode) => {
+    const isMinor = mode?.toLowerCase() === 'minor';
+    const mapping = isMinor
+        ? FIFTHS_TO_KEY_MINOR[fifths]
+        : FIFTHS_TO_KEY_MAJOR[fifths];
+    if (!mapping) {
+        console.warn(`Unknown key signature: fifths=${fifths}, mode=${mode}`);
+        return undefined;
+    }
+    return {
+        pitch: mapping.pitch,
+        accidental: mapping.accidental,
+        mode: isMinor ? 'minor' : 'major',
+    };
+};
+// ============ Clef Conversion ============
+/**
+ * Convert MusicXML clef (sign, line) to Lilylet Clef
+ */
+export const convertClef = (sign, line) => {
+    const upperSign = sign.toUpperCase();
+    if (upperSign === 'G') {
+        return Clef.treble;
+    }
+    else if (upperSign === 'F') {
+        return Clef.bass;
+    }
+    else if (upperSign === 'C') {
+        // C clef - alto clef on line 3, tenor on line 4
+        return Clef.alto;
+    }
+    console.warn(`Unknown clef: sign=${sign}, line=${line}`);
+    return undefined;
+};
+// ============ Stem Direction Conversion ============
+export const convertStemDirection = (stem) => {
+    switch (stem.toLowerCase()) {
+        case 'up':
+            return StemDirection.up;
+        case 'down':
+            return StemDirection.down;
+        default:
+            return undefined;
+    }
+};
+// ============ Articulation Conversion ============
+const ARTICULATION_MAP = {
+    staccato: ArticulationType.staccato,
+    staccatissimo: ArticulationType.staccatissimo,
+    tenuto: ArticulationType.tenuto,
+    accent: ArticulationType.accent,
+    'strong-accent': ArticulationType.marcato,
+    detachedLegato: ArticulationType.portato,
+    'detached-legato': ArticulationType.portato,
+};
+export const convertArticulation = (name) => {
+    return ARTICULATION_MAP[name];
+};
+// ============ Ornament Conversion ============
+const ORNAMENT_MAP = {
+    trill: OrnamentType.trill,
+    'trill-mark': OrnamentType.trill,
+    turn: OrnamentType.turn,
+    'inverted-turn': OrnamentType.turn,
+    mordent: OrnamentType.mordent,
+    'inverted-mordent': OrnamentType.prall,
+};
+export const convertOrnament = (name) => {
+    return ORNAMENT_MAP[name];
+};
+// ============ Dynamic Conversion ============
+const DYNAMIC_MAP = {
+    ppp: DynamicType.ppp,
+    pp: DynamicType.pp,
+    p: DynamicType.p,
+    mp: DynamicType.mp,
+    mf: DynamicType.mf,
+    f: DynamicType.f,
+    ff: DynamicType.ff,
+    fff: DynamicType.fff,
+    sfz: DynamicType.sfz,
+    sf: DynamicType.sfz,
+    rfz: DynamicType.rfz,
+    rf: DynamicType.rfz,
+    fz: DynamicType.sfz,
+    sfp: DynamicType.sfz,
+    sfpp: DynamicType.sfz,
+    fp: DynamicType.f, // forte-piano, approximate
+};
+export const convertDynamic = (name) => {
+    return DYNAMIC_MAP[name.toLowerCase()];
+};
+// ============ Hairpin Conversion ============
+export const convertWedge = (type, isStart) => {
+    if (type === 'crescendo') {
+        return isStart ? HairpinType.crescendoStart : HairpinType.crescendoEnd;
+    }
+    else if (type === 'diminuendo') {
+        return isStart ? HairpinType.diminuendoStart : HairpinType.diminuendoEnd;
+    }
+    else if (type === 'stop') {
+        // For stop, we need context to know if it's crescendo or diminuendo end
+        // Default to crescendo end
+        return HairpinType.crescendoEnd;
+    }
+    return undefined;
+};
+// ============ Pedal Conversion ============
+export const convertPedal = (type) => {
+    switch (type.toLowerCase()) {
+        case 'start':
+            return PedalType.sustainOn;
+        case 'stop':
+            return PedalType.sustainOff;
+        case 'change':
+            // Pedal change = off then on (we'll emit sustainOff)
+            return PedalType.sustainOff;
+        default:
+            return undefined;
+    }
+};
+// ============ Barline Conversion ============
+const BARLINE_STYLE_MAP = {
+    regular: '|',
+    'light-light': '||',
+    'light-heavy': '|.',
+    'heavy-light': '.|',
+    'heavy-heavy': '||',
+    dashed: ':',
+    dotted: ';',
+    none: '',
+};
+export const convertBarlineStyle = (barStyle, repeatDirection) => {
+    if (repeatDirection === 'backward') {
+        return ':|.';
+    }
+    if (repeatDirection === 'forward') {
+        return '.|:';
+    }
+    if (barStyle) {
+        return BARLINE_STYLE_MAP[barStyle] || '|';
+    }
+    return '|';
+};
+// ============ Harmony/Chord Symbol Conversion ============
+const KIND_MAP = {
+    major: '',
+    minor: 'm',
+    augmented: 'aug',
+    diminished: 'dim',
+    dominant: '7',
+    'major-seventh': 'maj7',
+    'minor-seventh': 'm7',
+    'diminished-seventh': 'dim7',
+    'augmented-seventh': 'aug7',
+    'half-diminished': 'm7b5',
+    'major-minor': 'mMaj7',
+    'major-sixth': '6',
+    'minor-sixth': 'm6',
+    'dominant-ninth': '9',
+    'major-ninth': 'maj9',
+    'minor-ninth': 'm9',
+    suspended: 'sus',
+    'suspended-second': 'sus2',
+    'suspended-fourth': 'sus4',
+    power: '5',
+    none: '',
+};
+const STEP_NAMES = {
+    C: 'C',
+    D: 'D',
+    E: 'E',
+    F: 'F',
+    G: 'G',
+    A: 'A',
+    B: 'B',
+};
+const ALTER_SYMBOLS = {
+    [-2]: 'bb',
+    [-1]: 'b',
+    [0]: '',
+    [1]: '#',
+    [2]: '##',
+};
+/**
+ * Convert MusicXML harmony to chord symbol text
+ */
+export const convertHarmonyToText = (rootStep, rootAlter, kind, bassStep, bassAlter) => {
+    let result = STEP_NAMES[rootStep.toUpperCase()] || rootStep;
+    if (rootAlter) {
+        result += ALTER_SYMBOLS[rootAlter] || '';
+    }
+    const kindSuffix = KIND_MAP[kind];
+    if (kindSuffix !== undefined) {
+        result += kindSuffix;
+    }
+    else {
+        // Unknown kind, just append as-is
+        result += kind;
+    }
+    // Add bass note if present (slash chord)
+    if (bassStep) {
+        result += '/';
+        result += STEP_NAMES[bassStep.toUpperCase()] || bassStep;
+        if (bassAlter) {
+            result += ALTER_SYMBOLS[bassAlter] || '';
+        }
+    }
+    return result;
+};
+// ============ Time Signature Helpers ============
+export const createFraction = (numerator, denominator) => ({
+    numerator,
+    denominator,
+});

package/lib/source/lilylet/parser.d.ts

@@ -0,0 +1,14 @@
+import { LilyletDoc } from "./types";
+export interface ParseWarning {
+    type: 'partial-mismatch';
+    message: string;
+    declared: number;
+    actual: number;
+}
+declare const parseCode: (code: string) => LilyletDoc;
+/**
+ * Return warnings emitted during the most recent parseCode() call.
+ * Currently reports \partial duration mismatches.
+ */
+declare const getParseWarnings: () => ParseWarning[];
+export { parseCode, getParseWarnings, };

package/lib/source/lilylet/parser.js

@@ -0,0 +1,161 @@
+// @ts-ignore - jison generated file
+import { parser, parse as grammarParse } from "./grammar.jison.js";
+const PHONETS = "cdefgab";
+/**
+ * Resolve relative pitch to absolute octave.
+ *
+ * In LilyPond relative mode:
+ * - The base pitch starts at middle C (step=0, octave=0)
+ * - For each note, the interval is calculated from the previous pitch
+ * - If |interval| > 3 (more than a 4th), the octave is adjusted to find nearest pitch
+ * - Explicit ' and , markers add/subtract octaves from this calculated position
+ *
+ * Example: c to g = interval +4, so we go DOWN a 4th (octave -1) instead of up a 5th
+ *          c to f = interval +3, so we go UP a 4th (same octave)
+ */
+const resolveRelativePitch = (env, pitch) => {
+    const step = PHONETS.indexOf(pitch.phonet);
+    if (step === -1) {
+        throw new Error(`Invalid phonet: "${pitch.phonet}". Expected one of: c, d, e, f, g, a, b`);
+    }
+    const interval = step - env.step;
+    // Calculate octave adjustment based on interval
+    // If interval > 3, go down instead of up (e.g., c to g is down a 4th)
+    // If interval < -3, go up instead of down (e.g., g to c is up a 4th)
+    const octInc = Math.floor(Math.abs(interval) / 4) * -Math.sign(interval);
+    // Update environment and pitch
+    // pitch.octave contains the explicit ' and , markers from parsing
+    env.octave += pitch.octave + octInc;
+    env.step = step;
+    // Store absolute octave back in pitch
+    pitch.octave = env.octave;
+};
+/**
+ * Process events in a voice to resolve relative pitches.
+ * Pitch reset events (from newlines) reset the pitch base to middle C.
+ */
+const resolveVoicePitches = (events, env) => {
+    for (const event of events) {
+        if (event.type === 'pitchReset') {
+            // Reset pitch base to middle C on newline
+            env.step = 0;
+            env.octave = 0;
+        }
+        else if (event.type === 'note') {
+            const noteEvent = event;
+            const pitches = noteEvent.pitches;
+            if (pitches.length > 0) {
+                // First pitch is relative to previous note/chord's first pitch
+                resolveRelativePitch(env, pitches[0]);
+                // For chord: subsequent pitches are relative to each other
+                if (pitches.length > 1) {
+                    const chordEnv = { step: env.step, octave: env.octave };
+                    for (let i = 1; i < pitches.length; i++) {
+                        resolveRelativePitch(chordEnv, pitches[i]);
+                    }
+                }
+            }
+        }
+        else if (event.type === 'rest') {
+            // Rest with pitch (e.g., a''\rest) should update the pitch environment
+            const restEvent = event;
+            if (restEvent.pitch) {
+                resolveRelativePitch(env, restEvent.pitch);
+            }
+        }
+        else if (event.type === 'tuplet') {
+            // Process tuplet events
+            for (const tupletEvent of event.events) {
+                if (tupletEvent.type === 'note') {
+                    const pitches = tupletEvent.pitches;
+                    if (pitches.length > 0) {
+                        resolveRelativePitch(env, pitches[0]);
+                        if (pitches.length > 1) {
+                            const chordEnv = { step: env.step, octave: env.octave };
+                            for (let i = 1; i < pitches.length; i++) {
+                                resolveRelativePitch(chordEnv, pitches[i]);
+                            }
+                        }
+                    }
+                }
+                else if (tupletEvent.type === 'rest') {
+                    const restEvent = tupletEvent;
+                    if (restEvent.pitch) {
+                        resolveRelativePitch(env, restEvent.pitch);
+                    }
+                }
+            }
+        }
+        else if (event.type === 'tremolo') {
+            // Process tremolo pitches
+            if (event.pitchA.length > 0) {
+                resolveRelativePitch(env, event.pitchA[0]);
+                if (event.pitchA.length > 1) {
+                    const chordEnv = { step: env.step, octave: env.octave };
+                    for (let i = 1; i < event.pitchA.length; i++) {
+                        resolveRelativePitch(chordEnv, event.pitchA[i]);
+                    }
+                }
+            }
+            if (event.pitchB.length > 0) {
+                resolveRelativePitch(env, event.pitchB[0]);
+                if (event.pitchB.length > 1) {
+                    const chordEnv = { step: env.step, octave: env.octave };
+                    for (let i = 1; i < event.pitchB.length; i++) {
+                        resolveRelativePitch(chordEnv, event.pitchB[i]);
+                    }
+                }
+            }
+        }
+    }
+};
+/**
+ * Process all pitches in a document to resolve relative pitch mode.
+ *
+ * Structure: measure > part > voice
+ * - Pitch environment is continuous across measures unless a pitchReset event is encountered
+ * - pitchReset events are generated from newlines in the source code
+ * - Each part/voice combination maintains its own pitch environment
+ */
+const resolveDocumentPitches = (doc) => {
+    // Track pitch environment per (part index, voice index) across all measures
+    // Key format: "partIndex-voiceIndex"
+    const envMap = {};
+    for (const measure of doc.measures) {
+        for (let pi = 0; pi < measure.parts.length; pi++) {
+            const part = measure.parts[pi];
+            for (let vi = 0; vi < part.voices.length; vi++) {
+                const voice = part.voices[vi];
+                const key = `${pi}-${vi}`;
+                // Get or create env for this part/voice combination
+                if (!envMap[key]) {
+                    envMap[key] = { step: 0, octave: 0 };
+                }
+                // Process voice events with the persistent env
+                // pitchReset events within will reset the env to middle C
+                resolveVoicePitches(voice.events, envMap[key]);
+            }
+        }
+    }
+};
+const parseCode = (code) => {
+    // Reset parser state before each parse to avoid contamination
+    if (parser && parser.resetState) {
+        parser.resetState();
+    }
+    const raw = grammarParse(code);
+    // Resolve relative pitch mode
+    resolveDocumentPitches(raw);
+    return raw;
+};
+/**
+ * Return warnings emitted during the most recent parseCode() call.
+ * Currently reports \partial duration mismatches.
+ */
+const getParseWarnings = () => {
+    if (parser && parser.getWarnings) {
+        return parser.getWarnings();
+    }
+    return [];
+};
+export { parseCode, getParseWarnings, };

package/lib/source/lilylet/serializer.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Lilylet Document Serializer
+ *
+ * Converts LilyletDoc to Lilylet (.lyl) string format.
+ * Uses relative pitch mode matching the parser's behavior.
+ */
+import { LilyletDoc } from "./types";
+/**
+ * Serialize a LilyletDoc to Lilylet (.lyl) string format
+ */
+export declare const serializeLilyletDoc: (doc: LilyletDoc) => string;