@k-l-lambda/lilylet 0.1.63 → 0.1.65

package/lib/source/lilylet/lilypondEncoder.js

@@ -0,0 +1,893 @@
+/**
+ * Lilylet to LilyPond Encoder
+ *
+ * Converts LilyletDoc to LilyPond (.ly) format.
+ * Uses relative pitch mode matching LilyPond's default behavior.
+ */
+import { Accidental, } from "./types.js";
+// === Constants and Mappings ===
+const PHONETS = "cdefgab";
+// Key signature to LilyPond notation (using English note names)
+const KEY_MAP = {
+    c: { major: "c \\major", minor: "c \\minor" },
+    d: { major: "d \\major", minor: "d \\minor" },
+    e: { major: "e \\major", minor: "e \\minor" },
+    f: { major: "f \\major", minor: "f \\minor" },
+    g: { major: "g \\major", minor: "g \\minor" },
+    a: { major: "a \\major", minor: "a \\minor" },
+    b: { major: "b \\major", minor: "b \\minor" },
+};
+// Accidentals for key signatures
+const KEY_ACCIDENTAL_MAP = {
+    sharp: "s",
+    flat: "f",
+    doubleSharp: "ss",
+    doubleFlat: "ff",
+};
+// Clef names
+const CLEF_MAP = {
+    treble: "treble",
+    bass: "bass",
+    alto: "alto",
+};
+// Accidental to LilyPond notation
+const ACCIDENTAL_MAP = {
+    natural: "!",
+    sharp: "s",
+    flat: "f",
+    doubleSharp: "ss",
+    doubleFlat: "ff",
+};
+// Articulation to LilyPond notation
+const ARTICULATION_MAP = {
+    staccato: "-.",
+    staccatissimo: "-!",
+    tenuto: "--",
+    marcato: "-^",
+    accent: "->",
+    portato: "-_",
+};
+// Ornament to LilyPond notation
+const ORNAMENT_MAP = {
+    trill: "\\trill",
+    turn: "\\turn",
+    mordent: "\\mordent",
+    prall: "\\prall",
+    fermata: "\\fermata",
+    shortFermata: "\\shortfermata",
+    arpeggio: "\\arpeggio",
+};
+// Dynamic to LilyPond notation
+const DYNAMIC_MAP = {
+    ppp: "\\ppp",
+    pp: "\\pp",
+    p: "\\p",
+    mp: "\\mp",
+    mf: "\\mf",
+    f: "\\f",
+    ff: "\\ff",
+    fff: "\\fff",
+    sfz: "\\sfz",
+    rfz: "\\rfz",
+};
+// Hairpin to LilyPond notation
+const HAIRPIN_MAP = {
+    crescendoStart: "\\<",
+    crescendoEnd: "\\!",
+    diminuendoStart: "\\>",
+    diminuendoEnd: "\\!",
+};
+// Pedal to LilyPond notation
+const PEDAL_MAP = {
+    sustainOn: "\\sustainOn",
+    sustainOff: "\\sustainOff",
+    sostenutoOn: "\\sostenutoOn",
+    sostenutoOff: "\\sostenutoOff",
+    unaCordaOn: "\\unaCorda",
+    unaCordaOff: "\\treCorde",
+};
+// Stem direction
+const STEM_MAP = {
+    up: "\\stemUp",
+    down: "\\stemDown",
+    auto: "\\stemNeutral",
+};
+// Barline styles
+const BARLINE_MAP = {
+    "|": "|",
+    "||": "||",
+    "|.": "|.",
+    ".|:": ".|:",
+    ":|.": ":|.",
+    ":..:": ":..:",
+    ":..:|": ":..:|",
+};
+// === Helper Functions ===
+/**
+ * Generate a spacer rest that fills a measure based on time signature.
+ * Uses multiplication syntax: s{denominator}*{numerator}
+ * @param timeSig - Time signature { numerator, denominator }
+ * @returns LilyPond spacer rest string (e.g., "s4*3" for 3/4, "s8*6" for 6/8)
+ */
+const getSpacerRest = (timeSig) => {
+    if (!timeSig)
+        return 's1';
+    const { numerator, denominator } = timeSig;
+    return `s${denominator}*${numerator}`;
+};
+// === Partial Measure Helpers ===
+const TPQN = 480;
+const voiceDurationTicks = (voice) => {
+    let ticks = 0;
+    const addEvent = (e, factor = 1) => {
+        if (e.type === 'note' || e.type === 'rest') {
+            const ev = e;
+            if (ev.grace)
+                return;
+            let t = (TPQN * 4) / ev.duration.division;
+            let dot = t / 2;
+            for (let i = 0; i < ev.duration.dots; i++) {
+                t += dot;
+                dot /= 2;
+            }
+            ticks += Math.round(t * factor);
+        }
+        else if (e.type === 'tuplet' || e.type === 'times') {
+            const te = e;
+            const f = factor * te.ratio.numerator / te.ratio.denominator;
+            for (const inner of te.events)
+                addEvent(inner, f);
+        }
+    };
+    for (const e of voice.events)
+        addEvent(e);
+    return ticks;
+};
+const ticksToLyDuration = (ticks) => {
+    const whole = TPQN * 4;
+    for (const div of [1, 2, 4, 8, 16, 32, 64]) {
+        const t = whole / div;
+        if (Math.abs(ticks - t) < 1)
+            return String(div);
+        if (Math.abs(ticks - Math.round(t * 1.5)) < 1)
+            return `${div}.`;
+        if (Math.abs(ticks - Math.round(t * 1.75)) < 1)
+            return `${div}..`;
+    }
+    return '4';
+};
+// Return a spacer-rest suffix to pad a voice to the full measure duration.
+// Uses s16*N to avoid complexity with dotted/compound values.
+const padVoiceToMeasure = (voiceTicks, measureTicks) => {
+    const remaining = Math.round(measureTicks - voiceTicks);
+    if (remaining <= 0)
+        return '';
+    const sixteenth = Math.round(TPQN / 4); // 120 ticks
+    const numSixteenths = Math.round(remaining / sixteenth);
+    if (numSixteenths <= 0)
+        return '';
+    return numSixteenths === 1 ? ' s16' : ` s16*${numSixteenths}`;
+};
+/**
+ * Calculate the octave markers needed to serialize a pitch in relative mode.
+ */
+const getRelativeOctaveMarkers = (env, pitch) => {
+    const step = PHONETS.indexOf(pitch.phonet);
+    if (step === -1) {
+        return { markers: '', newEnv: env };
+    }
+    const interval = step - env.step;
+    // Parser's octave adjustment calculation
+    const octInc = Math.floor(Math.abs(interval) / 4) * -Math.sign(interval);
+    // Without any markers, parser would calculate:
+    const baseOctave = env.octave + octInc;
+    // We need markers to reach pitch.octave from baseOctave
+    const markerCount = pitch.octave - baseOctave;
+    let markers = '';
+    if (markerCount > 0) {
+        markers = "'".repeat(markerCount);
+    }
+    else if (markerCount < 0) {
+        markers = ",".repeat(-markerCount);
+    }
+    // Update environment
+    const newEnv = {
+        step: step,
+        octave: pitch.octave
+    };
+    return { markers, newEnv };
+};
+const DEFAULT_OPTIONS = {
+    paper: { width: 210, height: 297 }, // A4 size in mm
+    fontSize: 20,
+    withMIDI: false,
+    autoBeaming: false,
+};
+// === Encoding Functions ===
+/**
+ * Encode key signature to LilyPond
+ */
+const encodeKey = (key) => {
+    let keyStr = key.pitch;
+    if (key.accidental) {
+        keyStr += KEY_ACCIDENTAL_MAP[key.accidental] || '';
+    }
+    return `\\key ${keyStr} \\${key.mode}`;
+};
+/**
+ * Encode time signature to LilyPond
+ */
+const encodeTimeSig = (timeSig) => {
+    if (timeSig.symbol === 'common') {
+        return "\\time 4/4"; // LilyPond handles C automatically
+    }
+    if (timeSig.symbol === 'cut') {
+        return "\\time 2/2"; // LilyPond handles C| automatically
+    }
+    return `\\time ${timeSig.numerator}/${timeSig.denominator}`;
+};
+/**
+ * Encode clef to LilyPond
+ */
+const encodeClef = (clef) => {
+    return `\\clef ${CLEF_MAP[clef] || clef}`;
+};
+/**
+ * Encode tempo to LilyPond
+ */
+const encodeTempo = (tempo) => {
+    let result = "\\tempo";
+    if (tempo.text) {
+        result += ` "${tempo.text}"`;
+    }
+    if (tempo.beat && tempo.bpm) {
+        const beatValue = tempo.beat.division;
+        let dots = "";
+        if (tempo.beat.dots) {
+            dots = ".".repeat(tempo.beat.dots);
+        }
+        result += ` ${beatValue}${dots} = ${tempo.bpm}`;
+    }
+    return result;
+};
+/**
+ * Encode a single pitch in relative mode
+ */
+const encodePitch = (pitch, env) => {
+    let result = pitch.phonet;
+    // Add accidental
+    if (pitch.accidental && pitch.accidental !== Accidental.natural) {
+        result += ACCIDENTAL_MAP[pitch.accidental] || '';
+    }
+    else if (pitch.accidental === Accidental.natural) {
+        result += '!';
+    }
+    // Calculate relative octave markers
+    const { markers, newEnv } = getRelativeOctaveMarkers(env, pitch);
+    result += markers;
+    return { str: result, newEnv };
+};
+/**
+ * Encode duration to LilyPond
+ */
+const encodeDuration = (duration) => {
+    let result = String(duration.division);
+    if (duration.dots) {
+        result += ".".repeat(duration.dots);
+    }
+    return result;
+};
+/**
+ * Encode marks (articulations, dynamics, etc.) to LilyPond
+ */
+const encodeMarks = (marks) => {
+    let result = '';
+    for (const mark of marks) {
+        switch (mark.markType) {
+            case 'articulation':
+                result += ARTICULATION_MAP[mark.type] || '';
+                break;
+            case 'ornament':
+                result += ORNAMENT_MAP[mark.type] || '';
+                break;
+            case 'dynamic':
+                result += DYNAMIC_MAP[mark.type] || '';
+                break;
+            case 'hairpin':
+                result += HAIRPIN_MAP[mark.type] || '';
+                break;
+            case 'tie':
+                if (mark.start) {
+                    result += '~';
+                }
+                break;
+            case 'slur':
+                result += mark.start ? '(' : ')';
+                break;
+            case 'beam':
+                result += mark.start ? '[' : ']';
+                break;
+            case 'pedal':
+                result += PEDAL_MAP[mark.type] || '';
+                break;
+            case 'fingering':
+                result += `-${mark.finger}`;
+                break;
+            case 'navigation':
+                if (mark.type === 'coda') {
+                    result += '\\coda';
+                }
+                else if (mark.type === 'segno') {
+                    result += '\\segno';
+                }
+                break;
+            case 'markup':
+                const placement = mark.placement === 'below' ? '_' : '^';
+                result += `${placement}\\markup { ${mark.content} }`;
+                break;
+        }
+    }
+    return result;
+};
+/**
+ * Encode a note event
+ */
+const encodeNoteEvent = (event, env, lastDuration) => {
+    let result = '';
+    let newEnv = env;
+    // Grace note
+    if (event.grace) {
+        result += '\\grace ';
+    }
+    // Stem direction
+    if (event.stemDirection) {
+        result += STEM_MAP[event.stemDirection] + ' ';
+    }
+    // Pitches (chord or single note)
+    if (event.pitches.length > 1) {
+        result += '<';
+        const pitchStrs = [];
+        let firstPitchEnv;
+        for (let i = 0; i < event.pitches.length; i++) {
+            // In LilyPond relative mode, each pitch in a chord is relative
+            // to the previous pitch in the chord (cascading).
+            // After the chord, env becomes the first pitch.
+            const { str, newEnv: ne } = encodePitch(event.pitches[i], newEnv);
+            pitchStrs.push(str);
+            newEnv = ne;
+            if (i === 0)
+                firstPitchEnv = ne;
+        }
+        // After chord, reference resets to first pitch
+        newEnv = firstPitchEnv;
+        result += pitchStrs.join(' ');
+        result += '>';
+    }
+    else if (event.pitches.length === 1) {
+        const { str, newEnv: ne } = encodePitch(event.pitches[0], newEnv);
+        result += str;
+        newEnv = ne;
+    }
+    // Duration (only if different from last)
+    const needDuration = !lastDuration ||
+        lastDuration.division !== event.duration.division ||
+        lastDuration.dots !== event.duration.dots;
+    if (needDuration) {
+        result += encodeDuration(event.duration);
+    }
+    // Tremolo
+    if (event.tremolo) {
+        result += `:${event.tremolo}`;
+    }
+    // Marks
+    if (event.marks) {
+        result += encodeMarks(event.marks);
+    }
+    return { str: result, newEnv, newDuration: event.duration };
+};
+/**
+ * Encode a rest event
+ */
+const encodeRestEvent = (event, env, lastDuration) => {
+    let result = '';
+    // Rest type
+    if (event.fullMeasure) {
+        result += 'R';
+    }
+    else if (event.invisible) {
+        result += 's';
+    }
+    else {
+        result += 'r';
+    }
+    // Duration
+    const needDuration = !lastDuration ||
+        lastDuration.division !== event.duration.division ||
+        lastDuration.dots !== event.duration.dots;
+    if (needDuration) {
+        result += encodeDuration(event.duration);
+    }
+    // Positioned rest
+    let newEnv = env;
+    if (event.pitch && !event.fullMeasure && !event.invisible) {
+        const { str, newEnv: ne } = encodePitch(event.pitch, env);
+        result = str + result.slice(1); // Replace 'r' with pitch
+        result += '\\rest';
+        newEnv = ne;
+    }
+    return { str: result, newEnv, newDuration: event.duration };
+};
+/**
+ * Encode a context change event
+ */
+const encodeContextChange = (event) => {
+    const parts = [];
+    if (event.key) {
+        parts.push(encodeKey(event.key));
+    }
+    if (event.time) {
+        parts.push(encodeTimeSig(event.time));
+    }
+    if (event.clef) {
+        parts.push(encodeClef(event.clef));
+    }
+    if (event.ottava !== undefined) {
+        parts.push(`\\ottava #${event.ottava}`);
+    }
+    if (event.stemDirection) {
+        parts.push(STEM_MAP[event.stemDirection]);
+    }
+    if (event.tempo) {
+        parts.push(encodeTempo(event.tempo));
+    }
+    if (event.staff) {
+        parts.push(`\\change Staff = "${event.staff}"`);
+    }
+    return parts.join(' ');
+};
+/**
+ * Encode a tuplet event
+ */
+const encodeTupletEvent = (event, env, lastDuration) => {
+    // \times preserves type:"times"; \tuplet is denominator/numerator
+    const header = event.type === 'times'
+        ? `\\times ${event.ratio.numerator}/${event.ratio.denominator}`
+        : `\\tuplet ${event.ratio.denominator}/${event.ratio.numerator}`;
+    let result = `${header} { `;
+    let newEnv = env;
+    let newDuration = lastDuration;
+    for (const subEvent of event.events) {
+        if (subEvent.type === 'note') {
+            const { str, newEnv: ne, newDuration: nd } = encodeNoteEvent(subEvent, newEnv, newDuration);
+            result += str + ' ';
+            newEnv = ne;
+            newDuration = nd;
+        }
+        else if (subEvent.type === 'rest') {
+            const { str, newEnv: ne, newDuration: nd } = encodeRestEvent(subEvent, newEnv, newDuration);
+            result += str + ' ';
+            newEnv = ne;
+            newDuration = nd;
+        }
+        else if (subEvent.type === 'context') {
+            result += encodeContextChange(subEvent) + ' ';
+        }
+    }
+    result += '}';
+    return { str: result, newEnv, newDuration };
+};
+/**
+ * Encode a tremolo event
+ */
+const encodeTremoloEvent = (event, env) => {
+    let newEnv = env;
+    // First chord/note
+    let pitchA = '';
+    if (event.pitchA.length > 1) {
+        pitchA += '<';
+        const pitchStrs = [];
+        let firstPitchEnv;
+        for (let i = 0; i < event.pitchA.length; i++) {
+            const { str, newEnv: ne } = encodePitch(event.pitchA[i], newEnv);
+            pitchStrs.push(str);
+            newEnv = ne;
+            if (i === 0)
+                firstPitchEnv = ne;
+        }
+        newEnv = firstPitchEnv;
+        pitchA += pitchStrs.join(' ');
+        pitchA += '>';
+    }
+    else if (event.pitchA.length === 1) {
+        const { str, newEnv: ne } = encodePitch(event.pitchA[0], newEnv);
+        pitchA += str;
+        newEnv = ne;
+    }
+    // Second chord/note
+    let pitchB = '';
+    if (event.pitchB.length > 1) {
+        pitchB += '<';
+        const pitchStrs = [];
+        let firstPitchEnv;
+        for (let i = 0; i < event.pitchB.length; i++) {
+            const { str, newEnv: ne } = encodePitch(event.pitchB[i], newEnv);
+            pitchStrs.push(str);
+            newEnv = ne;
+            if (i === 0)
+                firstPitchEnv = ne;
+        }
+        newEnv = firstPitchEnv;
+        pitchB += pitchStrs.join(' ');
+        pitchB += '>';
+    }
+    else if (event.pitchB.length === 1) {
+        const { str, newEnv: ne } = encodePitch(event.pitchB[0], newEnv);
+        pitchB += str;
+        newEnv = ne;
+    }
+    const result = `\\repeat tremolo ${event.count} { ${pitchA}${event.division} ${pitchB}${event.division} }`;
+    return { str: result, newEnv };
+};
+/**
+ * Encode a barline event
+ */
+const encodeBarlineEvent = (event) => {
+    const style = BARLINE_MAP[event.style] || event.style;
+    if (style === '|') {
+        return ''; // Default barline, no need to encode
+    }
+    return `\\bar "${style}"`;
+};
+/**
+ * Encode a harmony event (chord symbol)
+ * Uses the lilylet extension: \chords "text" (parsed by modified lotus grammar)
+ */
+const encodeHarmonyEvent = (event) => {
+    return `\\chords "${event.text}"`;
+};
+/**
+ * Encode a markup event
+ */
+const encodeMarkupEvent = (event) => {
+    const placement = event.placement === 'below' ? '_' : '^';
+    return `${placement}\\markup { ${event.content} }`;
+};
+/**
+ * Encode a voice to LilyPond
+ */
+const encodeVoice = (voice, measureContext, voiceIndex) => {
+    let result = '';
+    let env = { step: 0, octave: 0 }; // Start at middle C
+    let lastDuration = null;
+    for (const event of voice.events) {
+        switch (event.type) {
+            case 'note': {
+                const { str, newEnv, newDuration } = encodeNoteEvent(event, env, lastDuration);
+                result += str + ' ';
+                env = newEnv;
+                lastDuration = newDuration;
+                break;
+            }
+            case 'rest': {
+                const { str, newEnv, newDuration } = encodeRestEvent(event, env, lastDuration);
+                result += str + ' ';
+                env = newEnv;
+                lastDuration = newDuration;
+                break;
+            }
+            case 'context': {
+                result += encodeContextChange(event) + ' ';
+                break;
+            }
+            case 'tuplet':
+            case 'times': {
+                const { str, newEnv, newDuration } = encodeTupletEvent(event, env, lastDuration);
+                result += str + ' ';
+                env = newEnv;
+                lastDuration = newDuration;
+                break;
+            }
+            case 'tremolo': {
+                const { str, newEnv } = encodeTremoloEvent(event, env);
+                result += str + ' ';
+                env = newEnv;
+                break;
+            }
+            case 'barline': {
+                const str = encodeBarlineEvent(event);
+                if (str) {
+                    result += str + ' ';
+                }
+                break;
+            }
+            case 'harmony': {
+                result += encodeHarmonyEvent(event) + ' ';
+                break;
+            }
+            case 'markup': {
+                result += encodeMarkupEvent(event) + ' ';
+                break;
+            }
+            case 'pitchReset': {
+                // Ignore: each measure already gets its own \relative c' block,
+                // and within a measure the LilyPond reference pitch is not reset.
+                break;
+            }
+        }
+    }
+    return result.trim();
+};
+/**
+ * Encode metadata to LilyPond header block
+ */
+const encodeMetadata = (metadata) => {
+    const entries = [];
+    if (metadata.title) {
+        entries.push(`  title = "${metadata.title}"`);
+    }
+    if (metadata.subtitle) {
+        entries.push(`  subtitle = "${metadata.subtitle}"`);
+    }
+    if (metadata.composer) {
+        entries.push(`  composer = "${metadata.composer}"`);
+    }
+    if (metadata.arranger) {
+        entries.push(`  arranger = "${metadata.arranger}"`);
+    }
+    if (metadata.lyricist) {
+        entries.push(`  poet = "${metadata.lyricist}"`);
+    }
+    if (metadata.opus) {
+        entries.push(`  opus = "${metadata.opus}"`);
+    }
+    if (metadata.instrument) {
+        entries.push(`  instrument = "${metadata.instrument}"`);
+    }
+    entries.push('  tagline = ##f');
+    return entries.join('\n');
+};
+/**
+ * Encode a complete LilyletDoc to LilyPond format
+ *
+ * Structure:
+ * - Multiple parts → outer <<>>
+ * - Part with multiple staves → GrandStaff
+ * - Part with single staff → standalone Staff
+ */
+export const encode = (doc, options = {}) => {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    // Filter out trailing empty measures (measures with no musical content)
+    const hasMusicContent = (measure) => {
+        for (const part of measure.parts) {
+            for (const voice of part.voices) {
+                for (const event of voice.events) {
+                    if (event.type === 'note' || event.type === 'rest' || event.type === 'tuplet' || event.type === 'times' || event.type === 'tremolo') {
+                        return true;
+                    }
+                }
+            }
+        }
+        return false;
+    };
+    // Trim trailing empty measures
+    let measureCount = doc.measures.length;
+    while (measureCount > 0 && !hasMusicContent(doc.measures[measureCount - 1])) {
+        measureCount--;
+    }
+    const measures = doc.measures.slice(0, measureCount);
+    // Determine number of parts from the document
+    const partCount = Math.max(...measures.map(m => m.parts.length), 1);
+    const partVoices = [];
+    for (let pi = 0; pi < partCount; pi++) {
+        partVoices.push(new Map());
+    }
+    // Track time signature for each measure (for spacer rests)
+    const measureTimeSigs = [];
+    // Track partial (pickup) measure durations as LY duration strings (e.g. "8" for \partial 8)
+    const measurePartialDurs = [];
+    let currentKey;
+    let currentTimeSig;
+    for (let mi = 0; mi < measures.length; mi++) {
+        const measure = measures[mi];
+        // Update context from measure
+        if (measure.key)
+            currentKey = measure.key;
+        if (measure.timeSig)
+            currentTimeSig = measure.timeSig;
+        // Store time signature for this measure
+        measureTimeSigs[mi] = currentTimeSig;
+        // Detect partial (pickup) measures and compute their duration.
+        // Only the first measure (mi===0) can be an implicit partial;
+        // subsequent incomplete measures are NOT treated as partial.
+        const isExplicitPartial = measure.partial === true;
+        if (isExplicitPartial || (mi === 0 && currentTimeSig)) {
+            let maxVoiceTicks = 0;
+            for (const part of measure.parts) {
+                for (const v of part.voices) {
+                    maxVoiceTicks = Math.max(maxVoiceTicks, voiceDurationTicks(v));
+                }
+            }
+            const expectedTicks = currentTimeSig
+                ? Math.round(TPQN * 4 * currentTimeSig.numerator / currentTimeSig.denominator)
+                : TPQN * 4;
+            if (maxVoiceTicks > 0 && maxVoiceTicks < expectedTicks) {
+                measurePartialDurs[mi] = ticksToLyDuration(maxVoiceTicks);
+            }
+            else {
+                measurePartialDurs[mi] = undefined;
+            }
+        }
+        else {
+            measurePartialDurs[mi] = undefined;
+        }
+        // Process each part
+        for (let pi = 0; pi < measure.parts.length; pi++) {
+            const part = measure.parts[pi];
+            const staffMap = partVoices[pi];
+            for (let vi = 0; vi < part.voices.length; vi++) {
+                const voice = part.voices[vi];
+                const staff = voice.staff || 1;
+                if (!staffMap.has(staff)) {
+                    staffMap.set(staff, []);
+                }
+                const staffMeasures = staffMap.get(staff);
+                // Ensure we have enough measure slots
+                while (staffMeasures.length <= mi) {
+                    staffMeasures.push([]);
+                }
+                // Encode voice content
+                let voiceContent = encodeVoice(voice, {
+                    key: currentKey,
+                    timeSig: currentTimeSig,
+                    isFirst: mi === 0
+                }, vi);
+                // For non-partial measures, pad incomplete voices to fill the full
+                // measure duration. lotus doesn't auto-advance on barlines, so
+                // under-full voices cause measure boundary miscounting.
+                if (!measurePartialDurs[mi] && currentTimeSig) {
+                    const expectedTicks = Math.round(TPQN * 4 * currentTimeSig.numerator / currentTimeSig.denominator);
+                    const voiceTicks = voiceDurationTicks(voice);
+                    voiceContent += padVoiceToMeasure(voiceTicks, expectedTicks);
+                }
+                staffMeasures[mi].push(voiceContent);
+            }
+        }
+    }
+    // Build a staff string (used for both GrandStaff children and standalone Staff)
+    // Staff ID format: "partIndex_staffIndex" (e.g., "1_1", "1_2", "2_1") for multi-part decoding
+    const buildStaffString = (measures, staffId, indent) => {
+        // Find max voices per measure for this staff
+        const maxVoices = Math.max(...measures.map(m => m.length), 1);
+        // Build voice lines
+        const voiceLines = [];
+        for (let vi = 0; vi < maxVoices; vi++) {
+            let prevTimeSigStr;
+            const measureContents = measures.map((m, mi) => {
+                // For partial (pickup) measures, use a partial-duration spacer
+                const partialDur = measurePartialDurs[mi];
+                const spacer = partialDur ? `s${partialDur}` : getSpacerRest(measureTimeSigs[mi]);
+                let content = m[vi] || spacer;
+                // Inject \time if the content lacks it and the time sig changed.
+                // lotus processes each voice independently — without \time it
+                // defaults to 4/4, miscounting measure boundaries for other meters.
+                const ts = measureTimeSigs[mi];
+                if (ts) {
+                    const tsStr = `${ts.numerator}/${ts.denominator}`;
+                    if (tsStr !== prevTimeSigStr && !content.includes('\\time')) {
+                        content = `${encodeTimeSig(ts)} ${content}`;
+                    }
+                    prevTimeSigStr = tsStr;
+                }
+                // For partial measures, prepend \partial DUR before all other commands
+                // so the lotus interpreter correctly tracks the pickup measure boundary.
+                if (partialDur && !content.includes('\\partial')) {
+                    content = `\\partial ${partialDur} ${content}`;
+                }
+                // Wrap each measure in its own \relative c' to reset pitch context
+                return `${indent}    \\relative c' { ${content} } |  % ${mi + 1}`;
+            });
+            voiceLines.push(`${indent}  \\new Voice {\n${measureContents.join('\n')}\n${indent}  }`);
+        }
+        return `${indent}\\new Staff = "${staffId}" <<\n${voiceLines.join('\n')}\n${indent}>>`;
+    };
+    // Build music content for each part
+    const partStrings = [];
+    for (let pi = 0; pi < partCount; pi++) {
+        const staffMap = partVoices[pi];
+        const staffNums = Array.from(staffMap.keys()).sort((a, b) => a - b);
+        if (staffNums.length === 0) {
+            // Empty part, skip
+            continue;
+        }
+        const partIndex = pi + 1; // 1-based part index
+        if (staffNums.length === 1) {
+            // Single staff part → standalone Staff
+            const staffNum = staffNums[0];
+            const measures = staffMap.get(staffNum);
+            const staffId = `${partIndex}_${staffNum}`;
+            const staffStr = buildStaffString(measures, staffId, '    ');
+            partStrings.push(staffStr);
+        }
+        else {
+            // Multiple staves → GrandStaff
+            const staffStrings = [];
+            for (const staffNum of staffNums) {
+                const measures = staffMap.get(staffNum);
+                const staffId = `${partIndex}_${staffNum}`;
+                const staffStr = buildStaffString(measures, staffId, '      ');
+                staffStrings.push(staffStr);
+            }
+            partStrings.push(`    \\new GrandStaff <<\n${staffStrings.join('\n')}\n    >>`);
+        }
+    }
+    const musicContent = partStrings.join('\n');
+    // Determine outer wrapper
+    // - Single part with single staff → just Staff (no outer <<>>)
+    // - Single part with multiple staves → GrandStaff (no extra outer <<>>)
+    // - Multiple parts → outer <<>>
+    let scoreContent;
+    if (partCount === 1 && partStrings.length === 1) {
+        // Single part - use as-is (already has Staff or GrandStaff)
+        scoreContent = musicContent;
+    }
+    else {
+        // Multiple parts - wrap in <<>>
+        scoreContent = `  <<\n${musicContent}\n  >>`;
+    }
+    // Build header
+    const headerContent = doc.metadata ? encodeMetadata(doc.metadata) : '  tagline = ##f';
+    // Build document
+    const paperWidth = typeof opts.paper?.width === 'number' ? `${opts.paper.width}\\mm` : opts.paper?.width || '210\\mm';
+    const paperHeight = typeof opts.paper?.height === 'number' ? `${opts.paper.height}\\mm` : opts.paper?.height || '297\\mm';
+    const lyDoc = `\\version "2.22.0"
+
+\\language "english"
+
+\\header {
+${headerContent}
+}
+
+#(set-global-staff-size ${opts.fontSize})
+
+\\paper {
+  paper-width = ${paperWidth}
+  paper-height = ${paperHeight}
+  ragged-last = ##t
+  ragged-last-bottom = ##f
+}
+
+\\layout {
+  \\context {
+    \\Score
+    autoBeaming = ##${opts.autoBeaming ? 't' : 'f'}
+  }
+}
+
+\\score {
+${scoreContent}
+
+  \\layout { }${opts.withMIDI ? '\n  \\midi { }' : ''}
+}
+`;
+    return lyDoc;
+};
+/**
+ * Encode LilyletDoc to minimal LilyPond (music content only, no headers)
+ */
+export const encodeMinimal = (doc) => {
+    const parts = [];
+    for (const measure of doc.measures) {
+        for (const part of measure.parts) {
+            for (const voice of part.voices) {
+                const content = encodeVoice(voice, { isFirst: false }, 0);
+                parts.push(content);
+            }
+        }
+        parts.push('|');
+    }
+    return parts.join(' ');
+};
+export default {
+    encode,
+    encodeMinimal,
+};