@k-l-lambda/lilylet 0.1.30 → 0.1.32

package/lib/lilypondDecoder.js

@@ -0,0 +1,645 @@
+/**
+ * LilyPond to Lilylet Decoder
+ *
+ * Converts LilyPond notation files to Lilylet document format using the lotus parser.
+ * This module is browser-compatible - it uses pre-compiled parser from lotus.
+ */
+// Import directly from the compiled lib directory to avoid ESM issues
+import * as lilyParser from "@k-l-lambda/lotus/lib/inc/lilyParser/index.js";
+// Import pre-compiled LilyPond parser (browser-compatible)
+// @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";
+// Phonet names mapping
+const PHONET_NAMES = {
+    0: Phonet.c,
+    1: Phonet.d,
+    2: Phonet.e,
+    3: Phonet.f,
+    4: Phonet.g,
+    5: Phonet.a,
+    6: Phonet.b,
+};
+// Alter value to accidental
+const ALTER_TO_ACCIDENTAL = {
+    [-2]: Accidental.doubleFlat,
+    [-1]: Accidental.flat,
+    [0]: Accidental.natural,
+    [1]: Accidental.sharp,
+    [2]: Accidental.doubleSharp,
+};
+// LilyPond clef names to Lilylet clef
+const LILYPOND_CLEF_MAP = {
+    treble: Clef.treble,
+    G: Clef.treble,
+    bass: Clef.bass,
+    F: Clef.bass,
+    alto: Clef.alto,
+    C: Clef.alto,
+};
+// Key signature fifths to pitch/accidental mapping
+const KEY_FIFTHS_MAP = {
+    [-7]: { pitch: Phonet.c, accidental: Accidental.flat, mode: 'major' },
+    [-6]: { pitch: Phonet.g, accidental: Accidental.flat, mode: 'major' },
+    [-5]: { pitch: Phonet.d, accidental: Accidental.flat, mode: 'major' },
+    [-4]: { pitch: Phonet.a, accidental: Accidental.flat, mode: 'major' },
+    [-3]: { pitch: Phonet.e, accidental: Accidental.flat, mode: 'major' },
+    [-2]: { pitch: Phonet.b, accidental: Accidental.flat, mode: 'major' },
+    [-1]: { pitch: Phonet.f, mode: 'major' },
+    [0]: { pitch: Phonet.c, mode: 'major' },
+    [1]: { pitch: Phonet.g, mode: 'major' },
+    [2]: { pitch: Phonet.d, mode: 'major' },
+    [3]: { pitch: Phonet.a, mode: 'major' },
+    [4]: { pitch: Phonet.e, mode: 'major' },
+    [5]: { pitch: Phonet.b, mode: 'major' },
+    [6]: { pitch: Phonet.f, accidental: Accidental.sharp, mode: 'major' },
+    [7]: { pitch: Phonet.c, accidental: Accidental.sharp, mode: 'major' },
+};
+// Articulation mapping from LilyPond
+const ARTICULATION_MAP = {
+    staccato: ArticulationType.staccato,
+    staccatissimo: ArticulationType.staccatissimo,
+    tenuto: ArticulationType.tenuto,
+    marcato: ArticulationType.marcato,
+    accent: ArticulationType.accent,
+    portato: ArticulationType.portato,
+};
+// Ornament mapping from LilyPond
+const ORNAMENT_MAP = {
+    trill: OrnamentType.trill,
+    turn: OrnamentType.turn,
+    mordent: OrnamentType.mordent,
+    prall: OrnamentType.prall,
+    fermata: OrnamentType.fermata,
+    shortfermata: OrnamentType.shortFermata,
+    arpeggio: OrnamentType.arpeggio,
+};
+// Dynamic regex and mapping
+const DYNAMIC_REGEX = /^[fpmrsz]+$/;
+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,
+    rfz: DynamicType.rfz,
+};
+// Common tempo text words (from fprod corpus analysis)
+// Single words, lowercase for case-insensitive matching
+const TEMPO_WORDS = new Set([
+    // Basic tempo markings (Italian) - very slow to very fast
+    'grave', 'largo', 'larghetto', 'lento', 'adagio', 'adagietto',
+    'andante', 'andantino', 'moderato', 'allegretto', 'allegro',
+    'vivace', 'presto', 'prestissimo',
+    // Tempo modifiers
+    'molto', 'poco', 'più', 'meno', 'assai', 'con', 'moto', 'brio',
+    'ma', 'non', 'troppo', 'cantabile', 'sostenuto', 'espressivo',
+    'grazioso', 'maestoso', 'agitato', 'animato', 'tranquillo',
+    // Tempo changes
+    'tempo', 'primo',
+    'rit', 'ritard', 'ritardando', 'riten', 'ritenuto',
+    'rall', 'rallentando',
+    'accel', 'accelerando',
+    'allarg', 'allargando',
+    'calando', 'morendo', 'smorzando', 'smorz',
+    'rubato',
+]);
+// Check if text contains any tempo-related word (case-insensitive)
+const containsTempoWord = (text) => {
+    // Remove punctuation and split into words
+    const words = text.toLowerCase().replace(/[.,!?]/g, '').split(/\s+/);
+    return words.some(word => TEMPO_WORDS.has(word));
+};
+// Convert lotus Tempo to Lilylet Tempo
+const convertTempo = (lotusTempo) => {
+    if (!lotusTempo)
+        return undefined;
+    const tempo = {};
+    // Text (e.g., "Allegro")
+    if (lotusTempo.text) {
+        tempo.text = typeof lotusTempo.text === 'string'
+            ? lotusTempo.text
+            : extractTextFromObject(lotusTempo.text);
+    }
+    // Metronome mark (e.g., ♩ = 120)
+    if (lotusTempo.beatsPerMinute !== undefined && Number.isFinite(lotusTempo.beatsPerMinute)) {
+        tempo.bpm = lotusTempo.beatsPerMinute;
+        // Beat unit (note value)
+        if (lotusTempo.unit) {
+            tempo.beat = convertDuration(lotusTempo.unit);
+        }
+    }
+    // Return undefined if no meaningful tempo data
+    if (!tempo.text && !tempo.bpm) {
+        return undefined;
+    }
+    return tempo;
+};
+// Convert LilyPond pitch to Lilylet pitch
+const convertPitch = (phonetStep, alterValue, octave) => {
+    const phonet = PHONET_NAMES[phonetStep % 7];
+    const accidental = alterValue !== 0 ? ALTER_TO_ACCIDENTAL[alterValue] : undefined;
+    // Lotus parser absolute octave: 0 = C3, 1 = C4, 2 = C5
+    // Lilylet octave: 0 = C4, 1 = C5, -1 = C3
+    // Conversion: lilyletOctave = lotusAbsoluteOctave - 1
+    const lilyletOctave = octave - 1;
+    return {
+        phonet,
+        accidental,
+        octave: lilyletOctave,
+    };
+};
+// Convert LilyPond duration to Lilylet duration
+const convertDuration = (duration) => {
+    return {
+        division: Math.pow(2, duration.division),
+        dots: duration.dots || 0,
+    };
+};
+// Convert key fifths to KeySignature
+const convertKeySignature = (fifths) => {
+    const mapping = KEY_FIFTHS_MAP[fifths];
+    if (mapping) {
+        return {
+            pitch: mapping.pitch,
+            accidental: mapping.accidental,
+            mode: mapping.mode,
+        };
+    }
+    return undefined;
+};
+// Parse post-events to marks
+const parsePostEvents = (postEvents) => {
+    const marks = [];
+    if (!postEvents)
+        return marks;
+    for (const event of postEvents) {
+        // String events
+        if (typeof event === 'string') {
+            if (event === '~') {
+                marks.push({ markType: 'tie', start: true });
+            }
+            else if (event === '(') {
+                marks.push({ markType: 'slur', start: true });
+            }
+            else if (event === ')') {
+                marks.push({ markType: 'slur', start: false });
+            }
+            continue;
+        }
+        // PostEvent objects
+        if (event && typeof event === 'object') {
+            const arg = event.arg;
+            // String articulation/ornament
+            if (typeof arg === 'string') {
+                const cleanArg = arg.replace(/^-/, '');
+                if (ARTICULATION_MAP[cleanArg]) {
+                    marks.push({ markType: 'articulation', type: ARTICULATION_MAP[cleanArg] });
+                }
+                else if (ORNAMENT_MAP[cleanArg]) {
+                    marks.push({ markType: 'ornament', type: ORNAMENT_MAP[cleanArg] });
+                }
+            }
+            // Fingering (number 1-5)
+            if (typeof arg === 'number' && arg >= 1 && arg <= 5) {
+                marks.push({ markType: 'fingering', finger: arg });
+            }
+            // Command (dynamics, hairpins, etc.)
+            if (arg && typeof arg === 'object' && 'cmd' in arg) {
+                const cmd = arg.cmd;
+                if (DYNAMIC_REGEX.test(cmd) && DYNAMIC_MAP[cmd]) {
+                    marks.push({ markType: 'dynamic', type: DYNAMIC_MAP[cmd] });
+                }
+                else if (cmd === '<') {
+                    marks.push({ markType: 'hairpin', type: HairpinType.crescendoStart });
+                }
+                else if (cmd === '>') {
+                    marks.push({ markType: 'hairpin', type: HairpinType.diminuendoStart });
+                }
+                else if (cmd === '!') {
+                    marks.push({ markType: 'hairpin', type: HairpinType.crescendoEnd }); // or diminuendoEnd
+                }
+                else if (cmd === 'sustainOn') {
+                    marks.push({ markType: 'pedal', type: PedalType.sustainOn });
+                }
+                else if (cmd === 'sustainOff') {
+                    marks.push({ markType: 'pedal', type: PedalType.sustainOff });
+                }
+                else if (cmd === 'coda') {
+                    marks.push({ markType: 'navigation', type: NavigationMarkType.coda });
+                }
+                else if (cmd === 'segno') {
+                    marks.push({ markType: 'navigation', type: NavigationMarkType.segno });
+                }
+                else if (cmd === '\\markup' || cmd === 'markup') {
+                    // Markup attached to note
+                    const text = extractTextFromObject(arg.args);
+                    if (text && !containsTempoWord(text)) {
+                        const direction = event.direction;
+                        const placement = direction === 'up' ? Placement.above :
+                            direction === 'down' ? Placement.below : undefined;
+                        marks.push({ markType: 'markup', content: text, placement });
+                    }
+                }
+            }
+            // Handle markup command directly (proto: 'Command' with \\markup)
+            if (arg && typeof arg === 'object' && arg.proto === 'Command' && arg.cmd === '\\markup') {
+                const text = extractTextFromObject(arg.args);
+                if (text && !containsTempoWord(text)) {
+                    const direction = event.direction;
+                    const placement = direction === 'up' ? Placement.above :
+                        direction === 'down' ? Placement.below : undefined;
+                    marks.push({ markType: 'markup', content: text, placement });
+                }
+            }
+        }
+    }
+    return marks;
+};
+// Parse a LilyPond document to measures
+const parseLilyDocument = (lilyDocument) => {
+    const measureMap = new Map();
+    const staffNames = [];
+    const interpreter = lilyDocument.interpret();
+    interpreter.layoutMusic.musicTracks.forEach((track, vi) => {
+        const appendStaff = (staffName) => {
+            if (!staffNames.includes(staffName)) {
+                staffNames.push(staffName);
+            }
+        };
+        const staffName = track.contextDict?.Staff;
+        if (staffName) {
+            appendStaff(staffName);
+        }
+        let staff = staffName ? staffNames.indexOf(staffName) + 1 : 1;
+        const context = new lilyParser.TrackContext(undefined, {
+            listener: (term, context) => {
+                const mi = term._measure;
+                if (mi === undefined)
+                    return;
+                if (!measureMap.has(mi)) {
+                    measureMap.set(mi, {
+                        key: null,
+                        timeSig: null,
+                        voices: [],
+                        partial: false,
+                    });
+                }
+                // Update staff from context
+                if (context.staffName) {
+                    appendStaff(context.staffName);
+                    staff = staffNames.indexOf(context.staffName) + 1;
+                }
+                const measure = measureMap.get(mi);
+                // Initialize voice for this track
+                if (!measure.voices[vi]) {
+                    measure.voices[vi] = {
+                        staff,
+                        events: [],
+                    };
+                }
+                const voice = measure.voices[vi];
+                // Update key/time from context on music events
+                if (term instanceof lilyParser.MusicEvent ||
+                    term instanceof lilyParser.LilyTerms.StemDirection ||
+                    term instanceof lilyParser.LilyTerms.OctaveShift) {
+                    if (context.key && measure.key === null) {
+                        measure.key = context.key.key;
+                    }
+                    if (context.time && measure.timeSig === null) {
+                        measure.timeSig = {
+                            numerator: context.time.value.numerator,
+                            denominator: context.time.value.denominator,
+                        };
+                    }
+                    if (context.partialDuration) {
+                        measure.partial = true;
+                    }
+                }
+                // Handle music events
+                if (term instanceof lilyParser.MusicEvent) {
+                    // Update staff from voice events
+                    voice.staff = staff;
+                    // Handle clef context change
+                    if (context.clef && !voice.events.some(e => e.type === 'context' && e.clef)) {
+                        const clef = LILYPOND_CLEF_MAP[context.clef.clefName];
+                        if (clef) {
+                            voice.events.push({
+                                type: 'context',
+                                clef,
+                            });
+                        }
+                    }
+                    // Handle ottava
+                    if (context.octave?.value && !voice.events.some(e => e.type === 'context' && e.ottava !== undefined)) {
+                        voice.events.push({
+                            type: 'context',
+                            ottava: context.octave.value,
+                        });
+                    }
+                    // Handle stem direction context
+                    if (context.stemDirection && !voice.events.some(e => e.type === 'context' && e.stemDirection)) {
+                        const stemDir = context.stemDirection === 'Up' ? StemDirection.up :
+                            context.stemDirection === 'Down' ? StemDirection.down : undefined;
+                        if (stemDir) {
+                            voice.events.push({
+                                type: 'context',
+                                stemDirection: stemDir,
+                            });
+                        }
+                    }
+                    // Process Chord (note or chord)
+                    if (term instanceof lilyParser.LilyTerms.Chord) {
+                        const pitches = [];
+                        for (const pitch of term.pitchesValue) {
+                            if (pitch instanceof lilyParser.LilyTerms.ChordElement) {
+                                pitches.push(convertPitch(pitch.phonetStep, pitch.alterValue || 0, pitch.absolutePitch.octave));
+                            }
+                        }
+                        if (pitches.length > 0) {
+                            const marks = parsePostEvents(term.post_events);
+                            // Add beam marks
+                            if (term.beamOn) {
+                                marks.push({ markType: 'beam', start: true });
+                            }
+                            else if (term.beamOff) {
+                                marks.push({ markType: 'beam', start: false });
+                            }
+                            // Add tie
+                            if (term.isTying) {
+                                marks.push({ markType: 'tie', start: true });
+                            }
+                            const noteEvent = {
+                                type: 'note',
+                                pitches,
+                                duration: convertDuration(term.durationValue),
+                                grace: context.inGrace || undefined,
+                            };
+                            if (marks.length > 0) {
+                                noteEvent.marks = marks;
+                            }
+                            voice.events.push(noteEvent);
+                        }
+                    }
+                    // Process Rest
+                    else if (term instanceof lilyParser.LilyTerms.Rest) {
+                        const restEvent = {
+                            type: 'rest',
+                            duration: convertDuration(term.durationValue),
+                            invisible: term.isSpacer || undefined,
+                        };
+                        // Positioned rest
+                        if (!term.isSpacer && context.pitch) {
+                            restEvent.pitch = convertPitch(context.pitch.phonetStep, 0, context.pitch.octave);
+                        }
+                        voice.events.push(restEvent);
+                    }
+                }
+                // Handle standalone stem direction
+                else if (term instanceof lilyParser.LilyTerms.StemDirection) {
+                    const stemDir = term.direction === 'Up' ? StemDirection.up :
+                        term.direction === 'Down' ? StemDirection.down : undefined;
+                    if (stemDir) {
+                        voice.events.push({
+                            type: 'context',
+                            stemDirection: stemDir,
+                        });
+                    }
+                }
+                // Handle standalone clef
+                else if (term instanceof lilyParser.LilyTerms.Clef) {
+                    const clef = LILYPOND_CLEF_MAP[term.clefName];
+                    if (clef) {
+                        voice.events.push({
+                            type: 'context',
+                            clef,
+                        });
+                    }
+                }
+                // Handle ottava shift
+                else if (term instanceof lilyParser.LilyTerms.OctaveShift) {
+                    voice.events.push({
+                        type: 'context',
+                        ottava: term.value,
+                    });
+                }
+                // Handle staff change
+                else if (term instanceof lilyParser.LilyTerms.Change) {
+                    if (term.args?.[0]?.key === 'Staff') {
+                        // Staff change mid-voice
+                        voice.staff = staff;
+                    }
+                }
+                // Handle tempo
+                else if (term instanceof lilyParser.LilyTerms.Tempo) {
+                    const tempo = convertTempo(term);
+                    if (tempo) {
+                        voice.events.push({
+                            type: 'context',
+                            tempo,
+                        });
+                    }
+                }
+                // Handle standalone markup command
+                else {
+                    const termAny = term;
+                    if (termAny.proto === 'Command' && (termAny.cmd === '\\markup' || termAny.cmd === 'markup')) {
+                        const text = extractTextFromObject(termAny.args);
+                        if (text && !containsTempoWord(text)) {
+                            const markupEvent = {
+                                type: 'markup',
+                                content: text,
+                            };
+                            voice.events.push(markupEvent);
+                        }
+                    }
+                }
+            },
+        });
+        context.execute(track.music);
+    });
+    // Filter out empty voices and convert to array, sorted by measure number
+    const measures = Array.from(measureMap.entries())
+        .sort(([a], [b]) => a - b)
+        .map(([, measure]) => measure);
+    for (const measure of measures) {
+        measure.voices = measure.voices.filter(Boolean);
+    }
+    return measures;
+};
+// Check if a voice has real music content (not just spacer rests and context changes)
+const hasRealContent = (events) => {
+    return events.some(e => {
+        if (e.type === 'note')
+            return true;
+        if (e.type === 'rest' && !e.invisible)
+            return true;
+        return false;
+    });
+};
+// Remove quotes from string literal
+const unquoteString = (str) => {
+    if (str.startsWith('"') && str.endsWith('"')) {
+        return str.slice(1, -1);
+    }
+    return str;
+};
+// Extract text from lotus parser objects recursively
+const extractTextFromObject = (obj) => {
+    if (!obj)
+        return undefined;
+    // Simple string
+    if (typeof obj === 'string') {
+        return obj;
+    }
+    // Array - concatenate all text
+    if (Array.isArray(obj)) {
+        const texts = [];
+        for (const item of obj) {
+            const text = extractTextFromObject(item);
+            if (text)
+                texts.push(text);
+        }
+        return texts.join(' ').trim() || undefined;
+    }
+    // Object with proto property (lotus parser objects)
+    if (obj && typeof obj === 'object' && obj.proto) {
+        switch (obj.proto) {
+            case 'LiteralString':
+                // exp contains quoted string like '"Hello"'
+                if (obj.exp) {
+                    return unquoteString(obj.exp);
+                }
+                break;
+            case 'MarkupCommand':
+            case 'Command':
+                // Recursively extract from args
+                if (obj.args) {
+                    return extractTextFromObject(obj.args);
+                }
+                break;
+            case 'InlineBlock':
+                // Extract from body, skip primitive commands
+                if (obj.body) {
+                    const texts = [];
+                    for (const item of obj.body) {
+                        if (item.proto !== 'Primitive') {
+                            const text = extractTextFromObject(item);
+                            if (text)
+                                texts.push(text);
+                        }
+                    }
+                    return texts.join(' ').trim() || undefined;
+                }
+                break;
+            case 'String':
+                if (obj.value) {
+                    return obj.value;
+                }
+                break;
+        }
+    }
+    // Fallback: try value property
+    if (obj.value !== undefined) {
+        return extractTextFromObject(obj.value);
+    }
+    return undefined;
+};
+// Extract string value from header field
+const extractStringValue = (value) => {
+    const text = extractTextFromObject(value);
+    return text ? text.trim() : undefined;
+};
+// Extract metadata from LilyDocument
+const extractMetadata = (lilyDocument) => {
+    try {
+        const attrs = lilyDocument.globalAttributesReadOnly();
+        const metadata = {};
+        // Extract each field, handling markup structures
+        if (attrs.title) {
+            metadata.title = extractStringValue(attrs.title);
+        }
+        if (attrs.subtitle) {
+            metadata.subtitle = extractStringValue(attrs.subtitle);
+        }
+        if (attrs.composer) {
+            metadata.composer = extractStringValue(attrs.composer);
+        }
+        if (attrs.arranger) {
+            metadata.arranger = extractStringValue(attrs.arranger);
+        }
+        if (attrs.poet) {
+            metadata.lyricist = extractStringValue(attrs.poet);
+        }
+        if (attrs.opus) {
+            metadata.opus = extractStringValue(attrs.opus);
+        }
+        if (attrs.instrument) {
+            metadata.instrument = extractStringValue(attrs.instrument);
+        }
+        // Return undefined if no metadata fields were populated
+        if (Object.keys(metadata).length === 0) {
+            return undefined;
+        }
+        return metadata;
+    }
+    catch (e) {
+        // If metadata extraction fails, continue without it
+        return undefined;
+    }
+};
+// Convert parsed measures to LilyletDoc
+const parsedMeasuresToDoc = (parsedMeasures, metadata) => {
+    const measures = parsedMeasures.map(pm => {
+        // Filter out voices that only contain spacer rests and context changes
+        const voices = pm.voices
+            .filter(v => hasRealContent(v.events))
+            .map(v => ({
+            staff: v.staff,
+            events: v.events,
+        }));
+        const measure = {
+            parts: [{
+                    voices,
+                }],
+        };
+        if (pm.key !== null) {
+            measure.key = convertKeySignature(pm.key);
+        }
+        if (pm.timeSig) {
+            measure.timeSig = pm.timeSig;
+        }
+        if (pm.partial) {
+            measure.partial = true;
+        }
+        return measure;
+    });
+    const doc = { measures };
+    if (metadata) {
+        doc.metadata = metadata;
+    }
+    return doc;
+};
+/**
+ * Decode a LilyPond string to LilyletDoc (synchronous, browser-compatible)
+ */
+const decode = (lilypondSource) => {
+    const rawData = lilypondParser.parse(lilypondSource);
+    const lilyDocument = new lilyParser.LilyDocument(rawData);
+    const parsedMeasures = parseLilyDocument(lilyDocument);
+    const metadata = extractMetadata(lilyDocument);
+    return parsedMeasuresToDoc(parsedMeasures, metadata);
+};
+/**
+ * Decode from pre-parsed LilyDocument (synchronous, for when you already have parsed data)
+ */
+const decodeFromDocument = (lilyDocument) => {
+    const parsedMeasures = parseLilyDocument(lilyDocument);
+    const metadata = extractMetadata(lilyDocument);
+    return parsedMeasuresToDoc(parsedMeasures, metadata);
+};
+export { decode, decodeFromDocument, parseLilyDocument, };