@k-l-lambda/lilylet 0.1.35 → 0.1.36

package/README.md

@@ -1,7 +1,37 @@
 # Lilylet
 
+![](./docs/live-demo.gif)
+
 Lilylet is a LilyPond-like music notation language designed for Markdown rendering and symbolic music representation in AIGC applications.
 
+## Hello World
+
+```lyl
+\key c \major \time 4/4 \clef "treble" c1 \bar "|."
+```
+![](./docs/hello-world.svg)
+
+
+## A Comprehensive Example
+
+```lyl
+[title "Jesu, meine Freude"]
+[subtitle "BWV 610"]
+[composer "J.S. Bach"]
+
+\staff "1" \key c \minor \time 4/4 \clef "treble" \stemUp g'4 g f ef \\
+\staff "1" \stemDown ef16[ d ef8]~ ef16[ f ef d] c8[ d]~ d[ c] \\
+\staff "2" \clef "bass" c16[ b c8]~ c16[ b c g] a8[ g]~ g16[ g af ef] \\
+\staff "3" \clef "bass" r8 c,16[ d] ef[ d ef8]~ ef16[ a, b g] c[ b c8] | % 1
+
+\staff "1" \stemUp d2 c\fermata \\
+\staff "1" \stemDown c8[ c4 b8] c8.[ \staff "2" \stemUp g16] \staff "1" c[ b c d] \\
+\staff "2" f,16[ ef f d] g[ af g f] ef[ d ef8]~ ef16[ f ef d] \\
+\staff "3" r16 g,[ af f] g[ f g8] c,2 | % 2
+```
+![](./docs/BWV610.svg)
+
+
 ## Try It Online
 
 - [Live Editor](https://k-l-lambda.github.io/lilylet-live-editor/) - Interactive editor with real-time music notation rendering
@@ -33,28 +63,3 @@ LilyPond is powerful but overly flexible—the same music can be written in mult
 - **Shorter context description**: Removes redundant information, allowing LLMs to process more music content within limited context windows
 - **Formatted layout**: Fixed syntax structure facilitates model learning and generation
 - **Markdown-embeddable**: Music snippets can be directly embedded in documents
-
-### Basic Syntax
-
-| Element | Syntax | Description |
-|---------|--------|-------------|
-| Staff | `\staff "1"` | Specifies which staff the current voice belongs to |
-| Key | `\key c \major` | C major |
-| Time | `\time 4/4` | 4/4 time signature |
-| Clef | `\clef "treble"` | Treble clef |
-| Notes | `c4 d8 e16` | C quarter note, D eighth note, E sixteenth note |
-| Accidentals | `cs` `cf` `css` `cff` | C sharp, C flat, C double-sharp, C double-flat |
-| Octave | `c'` `c,` | One octave higher, one octave lower |
-| Chord | `<c e g>4` | C major triad, quarter note |
-| Voice separator | `\\` | Separates multiple voices within the same staff |
-| Part separator | `\\\` | Separates different instrument tracks (parts) in a score |
-| Bar line | `\|` | Separates measures |
-
-## Syntax Example
-
-```lilylet
-\staff "1" \key e \major \time 2/4 \clef "treble" \stemUp e8 [ ds16 e16 ] fs4 ~ \\
-\staff "1" s4 \stemDown ds4 ~ \\
-\staff "2" \key e \major \clef "bass" \stemUp e,,4 b4 \\
-\staff "2" \stemDown e,,16 [ b'8 -> b16 ] b,16 [ b'8 -> b16 ] |
-```

package/lib/grammar.jison.js

@@ -150,7 +150,7 @@ case 25:
  this.$ = $$[$0-3].concat([part($$[$0])]); 
 break;
 case 26:
- currentStaff = 1; 
+ currentStaff = 1; currentOttava = 0; 
 break;
 case 27:
  this.$ = [voice(currentStaff, $$[$0])]; 
@@ -174,7 +174,16 @@ case 43:
 this.$ = markupEvent($$[$0].slice(1, -1));
 break;
 case 44:
-this.$ = ({ type: 'pitchReset' });
+
+		// On newline, reset ottava to 0 if it's non-zero (like pitch base resets)
+		if (currentOttava !== 0) {
+			const ottavaReset = contextChange({ ottava: 0 });
+			currentOttava = 0;
+			this.$ = [ottavaReset, { type: 'pitchReset' }];
+		} else {
+			this.$ = { type: 'pitchReset' };
+		}
+	
 break;
 case 45: case 46:
  currentDuration = $$[$0-1]; this.$ = noteEvent($$[$0-2], $$[$0-1], $$[$0]); 
@@ -299,13 +308,13 @@ case 85:
  currentStaff = Number($$[$0].slice(1, -1)); this.$ = currentStaff; 
 break;
 case 86:
-this.$ = Number($$[$0]);
+ currentOttava = Number($$[$0]); this.$ = currentOttava; 
 break;
 case 87:
-this.$ = -Number($$[$0]);
+ currentOttava = -Number($$[$0]); this.$ = currentOttava; 
 break;
 case 88:
-this.$ = 0;
+ currentOttava = 0; this.$ = 0; 
 break;
 case 89:
 this.$ = 'up';
@@ -737,6 +746,7 @@ parse: function parse(input) {
 	let currentTimeSig = null;
 	let currentDuration = { division: 4, dots: 0 }; // default quarter note
 	let numericTimeSignature = false; // When true, 4/4 and 2/2 use numeric display instead of C/C|
+	let currentOttava = 0; // Current ottava level, resets on newline
 
 	// Reset parser state - call before each parse
 	const resetParserState = () => {
@@ -745,6 +755,7 @@ parse: function parse(input) {
 		currentTimeSig = null;
 		currentDuration = { division: 4, dots: 0 };
 		numericTimeSignature = false;
+		currentOttava = 0;
 	};
 
 	// Export reset function

package/lib/meiEncoder.js

@@ -618,7 +618,7 @@ const getEventBeamMarks = (event) => {
     return { beamStart: false, beamEnd: false };
 };
 // Encode a layer (voice)
-const encodeLayer = (voice, layerN, indent, initialTiePitches = [], keyFifths = 0, initialClef, initialSlur = null, initialHairpin = null) => {
+const encodeLayer = (voice, layerN, indent, initialTiePitches = [], keyFifths = 0, initialClef, initialSlur = null, initialHairpin = null, initialOctave = null) => {
     const layerId = generateId("layer");
     let xml = `${indent}<layer xml:id="${layerId}" n="${layerN}">\n`;
     let beamElementOpen = false; // Whether actual <beam> element is open (passed to tuplets)
@@ -630,12 +630,13 @@ const encodeLayer = (voice, layerN, indent, initialTiePitches = [], keyFifths =
     let currentHairpin = initialHairpin;
     // Track pedal marks (each is independent, not paired spans)
     const pedals = [];
-    // Track octave spans
+    // Track octave spans - initialize from previous measure if continuing
     const octaves = [];
-    let currentOctave = null;
+    let currentOctave = initialOctave ? { dis: initialOctave.dis, disPlace: initialOctave.disPlace, startId: initialOctave.startId } : null;
     let pendingOttava = null; // Track ottava to apply to next note
-    let currentOttavaShift = 0; // Track current ottava shift for pitch encoding
+    let currentOttavaShift = initialOctave?.shift || 0; // Track current ottava shift for pitch encoding
     let lastNoteId = null; // Track last note id for ending ottava spans
+    let ottavaExplicitlyClosed = false; // Track if ottava was explicitly closed by \ottava #0
     // Track slur spans - slurs must be encoded as control events in MEI
     const slurs = [];
     let currentSlur = initialSlur ? { startId: initialSlur } : null;
@@ -697,7 +698,17 @@ const encodeLayer = (voice, layerN, indent, initialTiePitches = [], keyFifths =
                 if (pendingOttava !== null && pendingOttava !== 0) {
                     const dis = Math.abs(pendingOttava) === 2 ? 15 : 8;
                     const disPlace = pendingOttava > 0 ? 'above' : 'below';
-                    currentOctave = { dis, disPlace, startId: result.elementId };
+                    // Close existing span first if it has a different value
+                    if (currentOctave && (currentOctave.dis !== dis || currentOctave.disPlace !== disPlace)) {
+                        // Different value - close the old span
+                        // Use the lastNoteId from before this note (which we saved before processing)
+                        // Note: The span from previous measure will be closed by encodeMeasure
+                        currentOctave = null;
+                    }
+                    // Start new span if we don't already have one with the same value
+                    if (!currentOctave) {
+                        currentOctave = { dis, disPlace, startId: result.elementId };
+                    }
                     pendingOttava = null;
                 }
                 // Update pending tie pitches
@@ -835,12 +846,25 @@ const encodeLayer = (voice, layerN, indent, initialTiePitches = [], keyFifths =
                                 endId: lastNoteId,
                             });
                             currentOctave = null;
+                            ottavaExplicitlyClosed = true; // Mark that we explicitly closed the span
                         }
-                        currentOttavaShift = 0; // Reset the shift
+                        // Note: if no lastNoteId (e.g., at measure start), keep currentOctave alive
+                        // It may be continued by a subsequent ottava command with the same value
+                        currentOttavaShift = 0; // Reset the shift (will be restored if continued)
                     }
                     else {
-                        // Start new ottava span - will be applied to next note
-                        pendingOttava = ctx.ottava;
+                        // Check if this continues an existing span (same value)
+                        const dis = Math.abs(ctx.ottava) === 2 ? 15 : 8;
+                        const disPlace = ctx.ottava > 0 ? 'above' : 'below';
+                        if (currentOctave && currentOctave.dis === dis && currentOctave.disPlace === disPlace) {
+                            // Continuation - restore the shift but don't change the span
+                            currentOttavaShift = ctx.ottava;
+                        }
+                        else {
+                            // Different value - start new ottava span (will be applied to next note)
+                            // If there's an existing span with different value, it will be closed when the note is processed
+                            pendingOttava = ctx.ottava;
+                        }
                     }
                 }
                 // Check for stem direction changes
@@ -889,20 +913,16 @@ const encodeLayer = (voice, layerN, indent, initialTiePitches = [], keyFifths =
     if (beamElementOpen) {
         xml += `${baseIndent}</beam>\n`;
     }
-    // Close any unclosed ottava span at end of layer
-    if (currentOctave && lastNoteId) {
-        octaves.push({
-            dis: currentOctave.dis,
-            disPlace: currentOctave.disPlace,
-            startId: currentOctave.startId,
-            endId: lastNoteId,
-        });
-    }
+    // Don't close ottava span at measure end - it may continue in the next measure
+    // Build pending octave state to return
+    const pendingOctave = currentOctave
+        ? { dis: currentOctave.dis, disPlace: currentOctave.disPlace, startId: currentOctave.startId, shift: currentOttavaShift }
+        : null;
     xml += `${indent}</layer>\n`;
-    return { xml, hairpins, pedals, octaves, slurs, arpeggios, fermatas, trills, mordents, turns, dynamics, fingerings, navigations, harmonies, barlines, markups, pendingTiePitches, pendingSlur: currentSlur?.startId || null, pendingHairpin: currentHairpin, endingClef: currentClef };
+    return { xml, hairpins, pedals, octaves, slurs, arpeggios, fermatas, trills, mordents, turns, dynamics, fingerings, navigations, harmonies, barlines, markups, pendingTiePitches, pendingSlur: currentSlur?.startId || null, pendingHairpin: currentHairpin, pendingOctave, ottavaExplicitlyClosed, endingClef: currentClef, lastNoteId, currentOttavaShift };
 };
 // Encode a staff
-const encodeStaff = (voices, staffN, indent, tieState = {}, slurState = {}, hairpinState = {}, keyFifths = 0, initialClef) => {
+const encodeStaff = (voices, staffN, indent, tieState = {}, slurState = {}, hairpinState = {}, ottavaState = {}, keyFifths = 0, initialClef) => {
     const staffId = generateId("staff");
     let xml = `${indent}<staff xml:id="${staffId}" n="${staffN}">\n`;
     const allHairpins = [];
@@ -923,6 +943,9 @@ const encodeStaff = (voices, staffN, indent, tieState = {}, slurState = {}, hair
     const pendingTies = {};
     const pendingSlurs = {};
     const pendingHairpins = {};
+    const pendingOctaves = {};
+    const ottavaExplicitlyClosed = {};
+    const lastNoteIds = {};
     let endingClef = initialClef;
     if (voices.length === 0) {
         xml += `${indent}    <layer xml:id="${generateId('layer')}" n="1" />\n`;
@@ -934,7 +957,8 @@ const encodeStaff = (voices, staffN, indent, tieState = {}, slurState = {}, hair
             const initialTies = tieState[tieKey] || [];
             const initialSlur = slurState[tieKey] || null;
             const initialHairpin = hairpinState[tieKey] || null;
-            const result = encodeLayer(voice, layerN, indent + '    ', initialTies, keyFifths, endingClef, initialSlur, initialHairpin);
+            const initialOctave = ottavaState[tieKey] || null;
+            const result = encodeLayer(voice, layerN, indent + '    ', initialTies, keyFifths, endingClef, initialSlur, initialHairpin, initialOctave);
             xml += result.xml;
             allHairpins.push(...result.hairpins);
             allPedals.push(...result.pedals);
@@ -963,6 +987,16 @@ const encodeStaff = (voices, staffN, indent, tieState = {}, slurState = {}, hair
             if (result.pendingHairpin) {
                 pendingHairpins[tieKey] = result.pendingHairpin;
             }
+            // Track pending ottava spans for this layer
+            if (result.pendingOctave) {
+                pendingOctaves[tieKey] = result.pendingOctave;
+            }
+            // Track if ottava was explicitly closed in this layer
+            if (result.ottavaExplicitlyClosed) {
+                ottavaExplicitlyClosed[tieKey] = true;
+            }
+            // Track last note IDs for this layer (for closing ottava spans)
+            lastNoteIds[tieKey] = result.lastNoteId;
             // Track ending clef for cross-measure tracking
             if (result.endingClef) {
                 endingClef = result.endingClef;
@@ -990,6 +1024,9 @@ const encodeStaff = (voices, staffN, indent, tieState = {}, slurState = {}, hair
         pendingTies,
         pendingSlurs,
         pendingHairpins,
+        pendingOctaves,
+        ottavaExplicitlyClosed,
+        lastNoteIds,
         endingClef,
     };
 };
@@ -1030,8 +1067,8 @@ const BARLINE_TO_MEI = {
     ':..:': 'rptboth',
 };
 // Encode a measure
-// encodeMeasure accepts mutable tieState, slurState, hairpinState and clefState that persist across measures
-const encodeMeasure = (measure, measureN, indent, totalStaves, tieState, slurState, hairpinState, keyFifths = 0, partInfos = [], clefState = {}) => {
+// encodeMeasure accepts mutable tieState, slurState, hairpinState, ottavaState and clefState that persist across measures
+const encodeMeasure = (measure, measureN, indent, totalStaves, tieState, slurState, hairpinState, ottavaState, keyFifths = 0, partInfos = [], clefState = {}) => {
     const measureId = generateId("measure");
     let staffContent = ''; // Build staff content first, then add measure tag with barline
     const allHairpins = [];
@@ -1083,11 +1120,11 @@ const encodeMeasure = (measure, measureN, indent, totalStaves, tieState, slurSta
             voicesByStaff[globalStaff].push(voice);
         }
     }
-    // Encode each staff, passing and updating tie state, slur state, hairpin state and clef state
+    // Encode each staff, passing and updating tie state, slur state, hairpin state, ottava state and clef state
     for (let si = 1; si <= totalStaves; si++) {
         const voices = voicesByStaff[si] || [];
         const initialClef = clefState[si];
-        const result = encodeStaff(voices, si, indent + '    ', tieState, slurState, hairpinState, keyFifths, initialClef);
+        const result = encodeStaff(voices, si, indent + '    ', tieState, slurState, hairpinState, ottavaState, keyFifths, initialClef);
         staffContent += result.xml;
         allHairpins.push(...result.hairpins);
         allPedals.push(...result.pedals);
@@ -1110,6 +1147,56 @@ const encodeMeasure = (measure, measureN, indent, totalStaves, tieState, slurSta
         Object.assign(slurState, result.pendingSlurs);
         // Update hairpin state with pending hairpins from this staff
         Object.assign(hairpinState, result.pendingHairpins);
+        // Update ottava state with pending octaves from this staff
+        // Also handle closing spans when ottava ends
+        const currentStaffPrefix = `${si}-`;
+        for (const [key, pending] of Object.entries(result.pendingOctaves)) {
+            if (pending) {
+                // Check if this is a continuation or a new span
+                const prevPending = ottavaState[key];
+                if (prevPending && prevPending.shift === pending.shift) {
+                    // Same ottava value continues - keep the original startId
+                    ottavaState[key] = { ...pending, startId: prevPending.startId };
+                }
+                else {
+                    // Different ottava value - close the old span first if exists
+                    if (prevPending) {
+                        const lastNoteId = result.lastNoteIds[key];
+                        if (lastNoteId) {
+                            allOctaves.push({
+                                dis: prevPending.dis,
+                                disPlace: prevPending.disPlace,
+                                startId: prevPending.startId,
+                                endId: lastNoteId,
+                            });
+                        }
+                    }
+                    // Start new span
+                    ottavaState[key] = pending;
+                }
+            }
+        }
+        // For layers in this staff that had pending octaves but didn't in this measure, close the spans
+        for (const [key, pending] of Object.entries(ottavaState)) {
+            // Only process keys for the current staff
+            if (key.startsWith(currentStaffPrefix) && pending && !result.pendingOctaves[key]) {
+                // Check if the span was already explicitly closed in encodeLayer
+                // If so, don't generate another span (it was already pushed to octaves in encodeLayer)
+                if (!result.ottavaExplicitlyClosed[key]) {
+                    // Ottava ended without explicit close - generate the closing span
+                    const lastNoteId = result.lastNoteIds[key];
+                    if (lastNoteId) {
+                        allOctaves.push({
+                            dis: pending.dis,
+                            disPlace: pending.disPlace,
+                            startId: pending.startId,
+                            endId: lastNoteId,
+                        });
+                    }
+                }
+                delete ottavaState[key];
+            }
+        }
         // Update clef state with ending clef from this staff
         if (result.endingClef) {
             clefState[si] = result.endingClef;
@@ -1344,6 +1431,8 @@ const encode = (doc, options = {}) => {
     const slurState = {};
     // Track hairpin state across measures for cross-measure hairpins
     const hairpinState = {};
+    // Track ottava state across measures for cross-measure ottava spans
+    const ottavaState = {};
     // Initialize clef state from partInfos (convert local staff to global staff)
     const clefState = {};
     for (let pi = 0; pi < partInfos.length; pi++) {
@@ -1399,7 +1488,7 @@ const encode = (doc, options = {}) => {
                 mei += `${indent}${indent}${indent}${indent}${indent}${indent}<scoreDef xml:id="${generateId('scoredef')}"${meterSymAttr} meter.count="${currentTimeNum}" meter.unit="${currentTimeDen}" />\n`;
             }
         }
-        mei += encodeMeasure(measure, mi + 1, `${indent}${indent}${indent}${indent}${indent}${indent}`, totalStaves, tieState, slurState, hairpinState, currentKey, partInfos, clefState);
+        mei += encodeMeasure(measure, mi + 1, `${indent}${indent}${indent}${indent}${indent}${indent}`, totalStaves, tieState, slurState, hairpinState, ottavaState, currentKey, partInfos, clefState);
     });
     mei += `${indent}${indent}${indent}${indent}${indent}</section>\n`;
     mei += `${indent}${indent}${indent}${indent}</score>\n`;

package/lib/musicXmlDecoder.js

@@ -727,13 +727,13 @@ const directionToContextChange = (direction, ottavaTracker) => {
             ottava = 0;
             ottavaTracker.current = 0;
         }
-        else if (type === 'up') {
-            // 8va = 1, 15ma = 2
+        else if (type === 'down') {
+            // 8va = 1, 15ma = 2 (type="down" means written notes sound higher)
             ottava = size === 15 ? 2 : 1;
             ottavaTracker.current = ottava;
         }
-        else if (type === 'down') {
-            // 8vb = -1, 15mb = -2
+        else if (type === 'up') {
+            // 8vb = -1, 15mb = -2 (type="up" means written notes sound lower)
             ottava = size === 15 ? -2 : -1;
             ottavaTracker.current = ottava;
         }

package/lib/serializer.js

@@ -406,6 +406,14 @@ const serializeTremoloEvent = (event, env) => {
     parts.push(' }');
     return { str: parts.join(''), newEnv: currentEnv };
 };
+// Serialize a barline event
+const serializeBarlineEvent = (event) => {
+    // Only output non-default barlines
+    if (event.style && event.style !== '|') {
+        return '\\bar "' + event.style + '"';
+    }
+    return '';
+};
 // Serialize a single event with pitch environment tracking
 const serializeEvent = (event, env, prevDuration) => {
     switch (event.type) {
@@ -419,15 +427,30 @@ const serializeEvent = (event, env, prevDuration) => {
             return serializeTupletEvent(event, env);
         case 'tremolo':
             return serializeTremoloEvent(event, env);
+        case 'barline':
+            return { str: serializeBarlineEvent(event), newEnv: env };
         default:
             return { str: '', newEnv: env };
     }
 };
+// Find first clef in voice events
+const findVoiceClef = (voice) => {
+    for (const event of voice.events) {
+        if (event.type === 'context') {
+            const ctx = event;
+            if (ctx.clef) {
+                return ctx.clef;
+            }
+        }
+    }
+    return undefined;
+};
 // Serialize a voice with pitch environment tracking
 // Takes currentStaff (what parser thinks staff is) and returns { str, newStaff }
 // If isGrandStaff is true, always output \staff command for clarity
-// If measureContext is provided, output key/time after \staff (for first voice only)
-const serializeVoice = (voice, currentStaff, isGrandStaff = false, measureContext) => {
+// measureContext provides key/time for first voice
+// staffClef is the clef for this voice's staff (tracked across measures)
+const serializeVoice = (voice, currentStaff, isGrandStaff = false, measureContext, isFirstVoice = false, staffClef) => {
     const parts = [];
     let prevDuration;
     // Each voice starts fresh from middle C (step=0, octave=0)
@@ -437,8 +460,8 @@ const serializeVoice = (voice, currentStaff, isGrandStaff = false, measureContex
     if (isGrandStaff || voice.staff !== currentStaff) {
         parts.push('\\staff "' + voice.staff + '"');
     }
-    // Output key/time signatures after \staff (for first voice of first measure)
-    if (measureContext) {
+    // Output key/time signatures after \staff (for first voice only)
+    if (measureContext && isFirstVoice) {
         if (measureContext.key) {
             let keyStr = String(measureContext.key.pitch);
             if (measureContext.key.accidental) {
@@ -457,7 +480,22 @@ const serializeVoice = (voice, currentStaff, isGrandStaff = false, measureContex
             parts.push('\\time ' + numerator + '/' + denominator);
         }
     }
+    // Output clef for every voice (use staff clef tracked across measures, or find from voice events)
+    const voiceClef = staffClef || findVoiceClef(voice);
+    if (voiceClef) {
+        parts.push('\\clef "' + CLEF_MAP[voiceClef] + '"');
+    }
+    // Track if we've already output the clef to avoid duplication
+    let clefOutputted = !!voiceClef;
     for (const event of voice.events) {
+        // Skip clef context events if we've already output the clef at the beginning
+        if (clefOutputted && event.type === 'context') {
+            const ctx = event;
+            if (ctx.clef && !ctx.key && !ctx.time && !ctx.ottava && !ctx.stemDirection && !ctx.tempo && !ctx.staff) {
+                // This is a clef-only context event, skip it
+                continue;
+            }
+        }
         const { str: eventStr, newEnv } = serializeEvent(event, pitchEnv, prevDuration);
         pitchEnv = newEnv;
         if (eventStr) {
@@ -474,8 +512,8 @@ const serializeVoice = (voice, currentStaff, isGrandStaff = false, measureContex
     return { str: parts.join(' '), newStaff: voice.staff };
 };
 // Serialize a part, tracking staff state across voices
-// If measureContext is provided, pass it to the first voice only
-const serializePart = (part, currentStaff, isGrandStaff = false, measureContext) => {
+// measureContext is passed to all voices (for clef), but key/time only to first voice
+const serializePart = (part, currentStaff, isGrandStaff = false, measureContext, isFirstPart = false, clefsByStaff) => {
     if (part.voices.length === 0) {
         return { str: '', newStaff: currentStaff };
     }
@@ -483,9 +521,11 @@ const serializePart = (part, currentStaff, isGrandStaff = false, measureContext)
     let staff = currentStaff;
     for (let i = 0; i < part.voices.length; i++) {
         const voice = part.voices[i];
-        // Only pass measureContext to first voice
-        const ctx = i === 0 ? measureContext : undefined;
-        const { str, newStaff } = serializeVoice(voice, staff, isGrandStaff, ctx);
+        // Pass measureContext to all voices, isFirstVoice for key/time
+        // Pass staff clef from clefsByStaff map
+        const isFirstVoice = isFirstPart && i === 0;
+        const staffClef = clefsByStaff?.[voice.staff];
+        const { str, newStaff } = serializeVoice(voice, staff, isGrandStaff, measureContext, isFirstVoice, staffClef);
         voiceStrs.push(str);
         staff = newStaff;
     }
@@ -493,17 +533,22 @@ const serializePart = (part, currentStaff, isGrandStaff = false, measureContext)
     return { str: voiceStrs.join(' \\\\\n'), newStaff: staff };
 };
 // Serialize a measure, tracking staff state across parts
-const serializeMeasure = (measure, isFirst, currentStaff, isGrandStaff = false) => {
+// Always output key/time at start of each measure
+const serializeMeasure = (measure, _isFirst, currentStaff, isGrandStaff = false, currentKey, currentTime, staffClefs) => {
     const parts = [];
-    // Build measure context for first voice (key/time signatures)
-    const measureContext = isFirst ? {
-        key: measure.key,
-        time: measure.timeSig,
-    } : undefined;
+    // Build measure context for all voices (key/time)
+    // Key and time are written to first voice, clef to all voices based on staff
+    // Use passed currentKey/currentTime which tracks across all measures
+    const measureContext = {
+        key: currentKey,
+        time: currentTime,
+    };
+    // Pass staffClefs to parts for per-voice clef lookup
+    const clefsByStaff = staffClefs || {};
     // Parts
     let staff = currentStaff;
     if (measure.parts.length === 1) {
-        const { str: partStr, newStaff } = serializePart(measure.parts[0], staff, isGrandStaff, measureContext);
+        const { str: partStr, newStaff } = serializePart(measure.parts[0], staff, isGrandStaff, measureContext, true, clefsByStaff);
         if (partStr) {
             parts.push(partStr);
         }
@@ -514,9 +559,8 @@ const serializeMeasure = (measure, isFirst, currentStaff, isGrandStaff = false)
         const partStrs = [];
         for (let i = 0; i < measure.parts.length; i++) {
             const part = measure.parts[i];
-            // Only pass measureContext to first part
-            const ctx = i === 0 ? measureContext : undefined;
-            const { str, newStaff } = serializePart(part, staff, isGrandStaff, ctx);
+            // Pass measureContext to all parts, isFirstPart to first part only
+            const { str, newStaff } = serializePart(part, staff, isGrandStaff, measureContext, i === 0, clefsByStaff);
             if (str) {
                 partStrs.push(str);
             }
@@ -567,10 +611,32 @@ export const serializeLilyletDoc = (doc) => {
     const isGrandStaff = doc.measures.some(m => m.parts.some(p => p.voices.some(v => v.staff > 1)));
     // Measures with bar lines, measure numbers, and double newlines
     // Track staff state across measures (parser remembers staff across bar lines)
+    // Track key/time/clef across measures to output in every measure
     const measureStrs = [];
     let currentStaff = 1; // Parser starts at staff 1
+    let currentKey;
+    let currentTime;
+    const staffClefs = {}; // Track clef per staff
     for (let i = 0; i < doc.measures.length; i++) {
-        const { str: measureStr, newStaff } = serializeMeasure(doc.measures[i], i === 0, currentStaff, isGrandStaff);
+        const measure = doc.measures[i];
+        // Update current key/time if measure has them
+        if (measure.key) {
+            currentKey = measure.key;
+        }
+        if (measure.timeSig) {
+            currentTime = measure.timeSig;
+        }
+        // Collect clefs from this measure's voices
+        for (const part of measure.parts) {
+            for (const voice of part.voices) {
+                for (const event of voice.events) {
+                    if (event.type === 'context' && event.clef) {
+                        staffClefs[voice.staff] = event.clef;
+                    }
+                }
+            }
+        }
+        const { str: measureStr, newStaff } = serializeMeasure(measure, i === 0, currentStaff, isGrandStaff, currentKey, currentTime, staffClefs);
         // Always include measure, even if empty (use space rest for empty measures)
         measureStrs.push(measureStr || 's1');
         currentStaff = newStaff;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k-l-lambda/lilylet",
-  "version": "0.1.35",
+  "version": "0.1.36",
   "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",

package/source/lilylet/grammar.jison.js

@@ -150,7 +150,7 @@ case 25:
  this.$ = $$[$0-3].concat([part($$[$0])]); 
 break;
 case 26:
- currentStaff = 1; 
+ currentStaff = 1; currentOttava = 0; 
 break;
 case 27:
  this.$ = [voice(currentStaff, $$[$0])]; 
@@ -174,7 +174,16 @@ case 43:
 this.$ = markupEvent($$[$0].slice(1, -1));
 break;
 case 44:
-this.$ = ({ type: 'pitchReset' });
+
+		// On newline, reset ottava to 0 if it's non-zero (like pitch base resets)
+		if (currentOttava !== 0) {
+			const ottavaReset = contextChange({ ottava: 0 });
+			currentOttava = 0;
+			this.$ = [ottavaReset, { type: 'pitchReset' }];
+		} else {
+			this.$ = { type: 'pitchReset' };
+		}
+	
 break;
 case 45: case 46:
  currentDuration = $$[$0-1]; this.$ = noteEvent($$[$0-2], $$[$0-1], $$[$0]); 
@@ -299,13 +308,13 @@ case 85:
  currentStaff = Number($$[$0].slice(1, -1)); this.$ = currentStaff; 
 break;
 case 86:
-this.$ = Number($$[$0]);
+ currentOttava = Number($$[$0]); this.$ = currentOttava; 
 break;
 case 87:
-this.$ = -Number($$[$0]);
+ currentOttava = -Number($$[$0]); this.$ = currentOttava; 
 break;
 case 88:
-this.$ = 0;
+ currentOttava = 0; this.$ = 0; 
 break;
 case 89:
 this.$ = 'up';
@@ -737,6 +746,7 @@ parse: function parse(input) {
 	let currentTimeSig = null;
 	let currentDuration = { division: 4, dots: 0 }; // default quarter note
 	let numericTimeSignature = false; // When true, 4/4 and 2/2 use numeric display instead of C/C|
+	let currentOttava = 0; // Current ottava level, resets on newline
 
 	// Reset parser state - call before each parse
 	const resetParserState = () => {
@@ -745,6 +755,7 @@ parse: function parse(input) {
 		currentTimeSig = null;
 		currentDuration = { division: 4, dots: 0 };
 		numericTimeSignature = false;
+		currentOttava = 0;
 	};
 
 	// Export reset function

package/source/lilylet/lilylet.jison

@@ -129,6 +129,7 @@
 	let currentTimeSig = null;
 	let currentDuration = { division: 4, dots: 0 }; // default quarter note
 	let numericTimeSignature = false; // When true, 4/4 and 2/2 use numeric display instead of C/C|
+	let currentOttava = 0; // Current ottava level, resets on newline
 
 	// Reset parser state - call before each parse
 	const resetParserState = () => {
@@ -137,6 +138,7 @@
 		currentTimeSig = null;
 		currentDuration = { division: 4, dots: 0 };
 		numericTimeSignature = false;
+		currentOttava = 0;
 	};
 
 	// Export reset function
@@ -323,7 +325,7 @@ parts
 	;
 
 part_start
-	: /* empty */								%{ currentStaff = 1; %}
+	: /* empty */								%{ currentStaff = 1; currentOttava = 0; %}
 	;
 
 part_voices
@@ -362,7 +364,16 @@ markup_event
 	;
 
 pitch_reset_event
-	: NEWLINE							-> ({ type: 'pitchReset' })
+	: NEWLINE							%{
+		// On newline, reset ottava to 0 if it's non-zero (like pitch base resets)
+		if (currentOttava !== 0) {
+			const ottavaReset = contextChange({ ottava: 0 });
+			currentOttava = 0;
+			$$ = [ottavaReset, { type: 'pitchReset' }];
+		} else {
+			$$ = { type: 'pitchReset' };
+		}
+	%}
 	;
 
 note_event
@@ -475,9 +486,9 @@ staff_cmd
 	;
 
 ottava_cmd
-	: CMD_OTTAVA '#' NUMBER						-> Number($3)
-	| CMD_OTTAVA '#' '-' NUMBER					-> -Number($4)
-	| CMD_OTTAVA								-> 0
+	: CMD_OTTAVA '#' NUMBER						%{ currentOttava = Number($3); $$ = currentOttava; %}
+	| CMD_OTTAVA '#' '-' NUMBER					%{ currentOttava = -Number($4); $$ = currentOttava; %}
+	| CMD_OTTAVA								%{ currentOttava = 0; $$ = 0; %}
 	;
 
 stem_cmd

package/source/lilylet/meiEncoder.ts

@@ -816,6 +816,15 @@ type TieState = Record<string, Pitch[]>;
 type SlurState = Record<string, string | null>;  // voice key -> pending slur startId
 type HairpinState = Record<string, { form: 'cres' | 'dim'; startId: string } | null>;  // voice key -> pending hairpin
 
+// Pending octave span for cross-measure continuation
+interface PendingOctave {
+	dis: 8 | 15;
+	disPlace: 'above' | 'below';
+	startId: string;
+	shift: number;  // The ottava value (1, -1, 2, -2)
+}
+type OttavaState = Record<string, PendingOctave | null>;  // voice key -> pending octave span
+
 // Layer result type
 interface LayerResult {
 	xml: string;
@@ -837,7 +846,11 @@ interface LayerResult {
 	pendingTiePitches: Pitch[];  // For cross-measure tie tracking
 	pendingSlur: string | null;  // For cross-measure slur tracking (startId)
 	pendingHairpin: { form: 'cres' | 'dim'; startId: string } | null;  // For cross-measure hairpin tracking
+	pendingOctave: PendingOctave | null;  // For cross-measure ottava span tracking
+	ottavaExplicitlyClosed: boolean;  // True if ottava was closed by explicit \ottava #0 in this layer
 	endingClef?: Clef;  // For cross-measure clef tracking
+	lastNoteId: string | null;  // For cross-measure ottava span end tracking
+	currentOttavaShift: number;  // Current ottava shift for pitch encoding
 }
 
 
@@ -864,7 +877,7 @@ const getEventBeamMarks = (event: NoteEvent | RestEvent | TupletEvent | TremoloE
 };
 
 // Encode a layer (voice)
-const encodeLayer = (voice: Voice, layerN: number, indent: string, initialTiePitches: Pitch[] = [], keyFifths: number = 0, initialClef?: Clef, initialSlur: string | null = null, initialHairpin: { form: 'cres' | 'dim'; startId: string } | null = null): LayerResult => {
+const encodeLayer = (voice: Voice, layerN: number, indent: string, initialTiePitches: Pitch[] = [], keyFifths: number = 0, initialClef?: Clef, initialSlur: string | null = null, initialHairpin: { form: 'cres' | 'dim'; startId: string } | null = null, initialOctave: PendingOctave | null = null): LayerResult => {
 	const layerId = generateId("layer");
 	let xml = `${indent}<layer xml:id="${layerId}" n="${layerN}">\n`;
 
@@ -881,12 +894,14 @@ const encodeLayer = (voice: Voice, layerN: number, indent: string, initialTiePit
 	// Track pedal marks (each is independent, not paired spans)
 	const pedals: PedalMark[] = [];
 
-	// Track octave spans
+	// Track octave spans - initialize from previous measure if continuing
 	const octaves: OctaveSpan[] = [];
-	let currentOctave: { dis: 8 | 15; disPlace: 'above' | 'below'; startId: string } | null = null;
+	let currentOctave: { dis: 8 | 15; disPlace: 'above' | 'below'; startId: string } | null =
+		initialOctave ? { dis: initialOctave.dis, disPlace: initialOctave.disPlace, startId: initialOctave.startId } : null;
 	let pendingOttava: number | null = null;  // Track ottava to apply to next note
-	let currentOttavaShift: number = 0;  // Track current ottava shift for pitch encoding
+	let currentOttavaShift: number = initialOctave?.shift || 0;  // Track current ottava shift for pitch encoding
 	let lastNoteId: string | null = null;  // Track last note id for ending ottava spans
+	let ottavaExplicitlyClosed: boolean = false;  // Track if ottava was explicitly closed by \ottava #0
 
 	// Track slur spans - slurs must be encoded as control events in MEI
 	const slurs: SlurSpan[] = [];
@@ -961,7 +976,17 @@ const encodeLayer = (voice: Voice, layerN: number, indent: string, initialTiePit
 				if (pendingOttava !== null && pendingOttava !== 0) {
 					const dis: 8 | 15 = Math.abs(pendingOttava) === 2 ? 15 : 8;
 					const disPlace: 'above' | 'below' = pendingOttava > 0 ? 'above' : 'below';
-					currentOctave = { dis, disPlace, startId: result.elementId };
+					// Close existing span first if it has a different value
+					if (currentOctave && (currentOctave.dis !== dis || currentOctave.disPlace !== disPlace)) {
+						// Different value - close the old span
+						// Use the lastNoteId from before this note (which we saved before processing)
+						// Note: The span from previous measure will be closed by encodeMeasure
+						currentOctave = null;
+					}
+					// Start new span if we don't already have one with the same value
+					if (!currentOctave) {
+						currentOctave = { dis, disPlace, startId: result.elementId };
+					}
 					pendingOttava = null;
 				}
 
@@ -1106,11 +1131,23 @@ const encodeLayer = (voice: Voice, layerN: number, indent: string, initialTiePit
 								endId: lastNoteId,
 							});
 							currentOctave = null;
+							ottavaExplicitlyClosed = true;  // Mark that we explicitly closed the span
 						}
-						currentOttavaShift = 0;  // Reset the shift
+						// Note: if no lastNoteId (e.g., at measure start), keep currentOctave alive
+						// It may be continued by a subsequent ottava command with the same value
+						currentOttavaShift = 0;  // Reset the shift (will be restored if continued)
 					} else {
-						// Start new ottava span - will be applied to next note
-						pendingOttava = ctx.ottava;
+						// Check if this continues an existing span (same value)
+						const dis: 8 | 15 = Math.abs(ctx.ottava) === 2 ? 15 : 8;
+						const disPlace: 'above' | 'below' = ctx.ottava > 0 ? 'above' : 'below';
+						if (currentOctave && currentOctave.dis === dis && currentOctave.disPlace === disPlace) {
+							// Continuation - restore the shift but don't change the span
+							currentOttavaShift = ctx.ottava;
+						} else {
+							// Different value - start new ottava span (will be applied to next note)
+							// If there's an existing span with different value, it will be closed when the note is processed
+							pendingOttava = ctx.ottava;
+						}
 					}
 				}
 				// Check for stem direction changes
@@ -1162,18 +1199,14 @@ const encodeLayer = (voice: Voice, layerN: number, indent: string, initialTiePit
 		xml += `${baseIndent}</beam>\n`;
 	}
 
-	// Close any unclosed ottava span at end of layer
-	if (currentOctave && lastNoteId) {
-		octaves.push({
-			dis: currentOctave.dis,
-			disPlace: currentOctave.disPlace,
-			startId: currentOctave.startId,
-			endId: lastNoteId,
-		});
-	}
+	// Don't close ottava span at measure end - it may continue in the next measure
+	// Build pending octave state to return
+	const pendingOctave: PendingOctave | null = currentOctave
+		? { dis: currentOctave.dis, disPlace: currentOctave.disPlace, startId: currentOctave.startId, shift: currentOttavaShift }
+		: null;
 
 	xml += `${indent}</layer>\n`;
-	return { xml, hairpins, pedals, octaves, slurs, arpeggios, fermatas, trills, mordents, turns, dynamics, fingerings, navigations, harmonies, barlines, markups, pendingTiePitches, pendingSlur: currentSlur?.startId || null, pendingHairpin: currentHairpin, endingClef: currentClef };
+	return { xml, hairpins, pedals, octaves, slurs, arpeggios, fermatas, trills, mordents, turns, dynamics, fingerings, navigations, harmonies, barlines, markups, pendingTiePitches, pendingSlur: currentSlur?.startId || null, pendingHairpin: currentHairpin, pendingOctave, ottavaExplicitlyClosed, endingClef: currentClef, lastNoteId, currentOttavaShift };
 };
 
 // Staff result type
@@ -1197,11 +1230,14 @@ interface StaffResult {
 	pendingTies: TieState;  // For cross-measure tie tracking
 	pendingSlurs: SlurState;  // For cross-measure slur tracking
 	pendingHairpins: HairpinState;  // For cross-measure hairpin tracking
+	pendingOctaves: OttavaState;  // For cross-measure ottava span tracking
+	ottavaExplicitlyClosed: Record<string, boolean>;  // Track which layers had ottava explicitly closed
+	lastNoteIds: Record<string, string | null>;  // For cross-measure ottava span end tracking
 	endingClef?: Clef;  // For cross-measure clef tracking
 }
 
 // Encode a staff
-const encodeStaff = (voices: Voice[], staffN: number, indent: string, tieState: TieState = {}, slurState: SlurState = {}, hairpinState: HairpinState = {}, keyFifths: number = 0, initialClef?: Clef): StaffResult => {
+const encodeStaff = (voices: Voice[], staffN: number, indent: string, tieState: TieState = {}, slurState: SlurState = {}, hairpinState: HairpinState = {}, ottavaState: OttavaState = {}, keyFifths: number = 0, initialClef?: Clef): StaffResult => {
 	const staffId = generateId("staff");
 	let xml = `${indent}<staff xml:id="${staffId}" n="${staffN}">\n`;
 	const allHairpins: HairpinSpan[] = [];
@@ -1222,6 +1258,9 @@ const encodeStaff = (voices: Voice[], staffN: number, indent: string, tieState:
 	const pendingTies: TieState = {};
 	const pendingSlurs: SlurState = {};
 	const pendingHairpins: HairpinState = {};
+	const pendingOctaves: OttavaState = {};
+	const ottavaExplicitlyClosed: Record<string, boolean> = {};
+	const lastNoteIds: Record<string, string | null> = {};
 	let endingClef: Clef | undefined = initialClef;
 
 	if (voices.length === 0) {
@@ -1233,7 +1272,8 @@ const encodeStaff = (voices: Voice[], staffN: number, indent: string, tieState:
 			const initialTies = tieState[tieKey] || [];
 			const initialSlur = slurState[tieKey] || null;
 			const initialHairpin = hairpinState[tieKey] || null;
-			const result = encodeLayer(voice, layerN, indent + '    ', initialTies, keyFifths, endingClef, initialSlur, initialHairpin);
+			const initialOctave = ottavaState[tieKey] || null;
+			const result = encodeLayer(voice, layerN, indent + '    ', initialTies, keyFifths, endingClef, initialSlur, initialHairpin, initialOctave);
 			xml += result.xml;
 			allHairpins.push(...result.hairpins);
 			allPedals.push(...result.pedals);
@@ -1262,6 +1302,16 @@ const encodeStaff = (voices: Voice[], staffN: number, indent: string, tieState:
 			if (result.pendingHairpin) {
 				pendingHairpins[tieKey] = result.pendingHairpin;
 			}
+			// Track pending ottava spans for this layer
+			if (result.pendingOctave) {
+				pendingOctaves[tieKey] = result.pendingOctave;
+			}
+			// Track if ottava was explicitly closed in this layer
+			if (result.ottavaExplicitlyClosed) {
+				ottavaExplicitlyClosed[tieKey] = true;
+			}
+			// Track last note IDs for this layer (for closing ottava spans)
+			lastNoteIds[tieKey] = result.lastNoteId;
 			// Track ending clef for cross-measure tracking
 			if (result.endingClef) {
 				endingClef = result.endingClef;
@@ -1290,6 +1340,9 @@ const encodeStaff = (voices: Voice[], staffN: number, indent: string, tieState:
 		pendingTies,
 		pendingSlurs,
 		pendingHairpins,
+		pendingOctaves,
+		ottavaExplicitlyClosed,
+		lastNoteIds,
 		endingClef,
 	};
 };
@@ -1339,8 +1392,8 @@ const BARLINE_TO_MEI: Record<string, string> = {
 };
 
 // Encode a measure
-// encodeMeasure accepts mutable tieState, slurState, hairpinState and clefState that persist across measures
-const encodeMeasure = (measure: Measure, measureN: number, indent: string, totalStaves: number, tieState: TieState, slurState: SlurState, hairpinState: HairpinState, keyFifths: number = 0, partInfos: PartInfo[] = [], clefState: ClefState = {}): string => {
+// encodeMeasure accepts mutable tieState, slurState, hairpinState, ottavaState and clefState that persist across measures
+const encodeMeasure = (measure: Measure, measureN: number, indent: string, totalStaves: number, tieState: TieState, slurState: SlurState, hairpinState: HairpinState, ottavaState: OttavaState, keyFifths: number = 0, partInfos: PartInfo[] = [], clefState: ClefState = {}): string => {
 	const measureId = generateId("measure");
 	let staffContent = '';  // Build staff content first, then add measure tag with barline
 	const allHairpins: HairpinSpan[] = [];
@@ -1395,11 +1448,11 @@ const encodeMeasure = (measure: Measure, measureN: number, indent: string, total
 		}
 	}
 
-	// Encode each staff, passing and updating tie state, slur state, hairpin state and clef state
+	// Encode each staff, passing and updating tie state, slur state, hairpin state, ottava state and clef state
 	for (let si = 1; si <= totalStaves; si++) {
 		const voices = voicesByStaff[si] || [];
 		const initialClef = clefState[si];
-		const result = encodeStaff(voices, si, indent + '    ', tieState, slurState, hairpinState, keyFifths, initialClef);
+		const result = encodeStaff(voices, si, indent + '    ', tieState, slurState, hairpinState, ottavaState, keyFifths, initialClef);
 		staffContent += result.xml;
 		allHairpins.push(...result.hairpins);
 		allPedals.push(...result.pedals);
@@ -1422,6 +1475,55 @@ const encodeMeasure = (measure: Measure, measureN: number, indent: string, total
 		Object.assign(slurState, result.pendingSlurs);
 		// Update hairpin state with pending hairpins from this staff
 		Object.assign(hairpinState, result.pendingHairpins);
+		// Update ottava state with pending octaves from this staff
+		// Also handle closing spans when ottava ends
+		const currentStaffPrefix = `${si}-`;
+		for (const [key, pending] of Object.entries(result.pendingOctaves)) {
+			if (pending) {
+				// Check if this is a continuation or a new span
+				const prevPending = ottavaState[key];
+				if (prevPending && prevPending.shift === pending.shift) {
+					// Same ottava value continues - keep the original startId
+					ottavaState[key] = { ...pending, startId: prevPending.startId };
+				} else {
+					// Different ottava value - close the old span first if exists
+					if (prevPending) {
+						const lastNoteId = result.lastNoteIds[key];
+						if (lastNoteId) {
+							allOctaves.push({
+								dis: prevPending.dis,
+								disPlace: prevPending.disPlace,
+								startId: prevPending.startId,
+								endId: lastNoteId,
+							});
+						}
+					}
+					// Start new span
+					ottavaState[key] = pending;
+				}
+			}
+		}
+		// For layers in this staff that had pending octaves but didn't in this measure, close the spans
+		for (const [key, pending] of Object.entries(ottavaState)) {
+			// Only process keys for the current staff
+			if (key.startsWith(currentStaffPrefix) && pending && !result.pendingOctaves[key]) {
+				// Check if the span was already explicitly closed in encodeLayer
+				// If so, don't generate another span (it was already pushed to octaves in encodeLayer)
+				if (!result.ottavaExplicitlyClosed[key]) {
+					// Ottava ended without explicit close - generate the closing span
+					const lastNoteId = result.lastNoteIds[key];
+					if (lastNoteId) {
+						allOctaves.push({
+							dis: pending.dis,
+							disPlace: pending.disPlace,
+							startId: pending.startId,
+							endId: lastNoteId,
+						});
+					}
+				}
+				delete ottavaState[key];
+			}
+		}
 		// Update clef state with ending clef from this staff
 		if (result.endingClef) {
 			clefState[si] = result.endingClef;
@@ -1718,6 +1820,9 @@ const encode = (doc: LilyletDoc, options: MEIEncoderOptions = {}): string => {
 	// Track hairpin state across measures for cross-measure hairpins
 	const hairpinState: HairpinState = {};
 
+	// Track ottava state across measures for cross-measure ottava spans
+	const ottavaState: OttavaState = {};
+
 	// Initialize clef state from partInfos (convert local staff to global staff)
 	const clefState: ClefState = {};
 	for (let pi = 0; pi < partInfos.length; pi++) {
@@ -1776,7 +1881,7 @@ const encode = (doc: LilyletDoc, options: MEIEncoderOptions = {}): string => {
 				mei += `${indent}${indent}${indent}${indent}${indent}${indent}<scoreDef xml:id="${generateId('scoredef')}"${meterSymAttr} meter.count="${currentTimeNum}" meter.unit="${currentTimeDen}" />\n`;
 			}
 		}
-		mei += encodeMeasure(measure, mi + 1, `${indent}${indent}${indent}${indent}${indent}${indent}`, totalStaves, tieState, slurState, hairpinState, currentKey, partInfos, clefState);
+		mei += encodeMeasure(measure, mi + 1, `${indent}${indent}${indent}${indent}${indent}${indent}`, totalStaves, tieState, slurState, hairpinState, ottavaState, currentKey, partInfos, clefState);
 	});
 
 	mei += `${indent}${indent}${indent}${indent}${indent}</section>\n`;

package/source/lilylet/musicXmlDecoder.ts

@@ -922,12 +922,12 @@ const directionToContextChange = (
 		if (type === 'stop') {
 			ottava = 0;
 			ottavaTracker.current = 0;
-		} else if (type === 'up') {
-			// 8va = 1, 15ma = 2
+		} else if (type === 'down') {
+			// 8va = 1, 15ma = 2 (type="down" means written notes sound higher)
 			ottava = size === 15 ? 2 : 1;
 			ottavaTracker.current = ottava;
-		} else if (type === 'down') {
-			// 8vb = -1, 15mb = -2
+		} else if (type === 'up') {
+			// 8vb = -1, 15mb = -2 (type="up" means written notes sound lower)
 			ottava = size === 15 ? -2 : -1;
 			ottavaTracker.current = ottava;
 		} else {

package/source/lilylet/serializer.ts

@@ -16,6 +16,7 @@ import {
 	ContextChange,
 	TupletEvent,
 	TremoloEvent,
+	BarlineEvent,
 	Pitch,
 	Duration,
 	Mark,
@@ -524,6 +525,16 @@ const serializeTremoloEvent = (
 };
 
 
+// Serialize a barline event
+const serializeBarlineEvent = (event: BarlineEvent): string => {
+	// Only output non-default barlines
+	if (event.style && event.style !== '|') {
+		return '\\bar "' + event.style + '"';
+	}
+	return '';
+};
+
+
 // Serialize a single event with pitch environment tracking
 const serializeEvent = (
 	event: Event,
@@ -541,27 +552,46 @@ const serializeEvent = (
 			return serializeTupletEvent(event as TupletEvent, env);
 		case 'tremolo':
 			return serializeTremoloEvent(event as TremoloEvent, env);
+		case 'barline':
+			return { str: serializeBarlineEvent(event as BarlineEvent), newEnv: env };
 		default:
 			return { str: '', newEnv: env };
 	}
 };
 
 
-// Key/time signature info to inject into first voice
+// Key/time/clef signature info to inject into voices
 interface MeasureContext {
 	key?: KeySignature;
 	time?: { numerator: number; denominator: number; symbol?: 'common' | 'cut' };
+	clef?: Clef;
 }
 
+// Find first clef in voice events
+const findVoiceClef = (voice: Voice): Clef | undefined => {
+	for (const event of voice.events) {
+		if (event.type === 'context') {
+			const ctx = event as ContextChange;
+			if (ctx.clef) {
+				return ctx.clef;
+			}
+		}
+	}
+	return undefined;
+};
+
 // Serialize a voice with pitch environment tracking
 // Takes currentStaff (what parser thinks staff is) and returns { str, newStaff }
 // If isGrandStaff is true, always output \staff command for clarity
-// If measureContext is provided, output key/time after \staff (for first voice only)
+// measureContext provides key/time for first voice
+// staffClef is the clef for this voice's staff (tracked across measures)
 const serializeVoice = (
 	voice: Voice,
 	currentStaff: number,
 	isGrandStaff: boolean = false,
-	measureContext?: MeasureContext
+	measureContext?: MeasureContext,
+	isFirstVoice: boolean = false,
+	staffClef?: Clef
 ): { str: string; newStaff: number } => {
 	const parts: string[] = [];
 	let prevDuration: Duration | undefined;
@@ -574,8 +604,8 @@ const serializeVoice = (
 		parts.push('\\staff "' + voice.staff + '"');
 	}
 
-	// Output key/time signatures after \staff (for first voice of first measure)
-	if (measureContext) {
+	// Output key/time signatures after \staff (for first voice only)
+	if (measureContext && isFirstVoice) {
 		if (measureContext.key) {
 			let keyStr = String(measureContext.key.pitch);
 			if (measureContext.key.accidental) {
@@ -595,7 +625,25 @@ const serializeVoice = (
 		}
 	}
 
+	// Output clef for every voice (use staff clef tracked across measures, or find from voice events)
+	const voiceClef = staffClef || findVoiceClef(voice);
+	if (voiceClef) {
+		parts.push('\\clef "' + CLEF_MAP[voiceClef] + '"');
+	}
+
+	// Track if we've already output the clef to avoid duplication
+	let clefOutputted = !!voiceClef;
+
 	for (const event of voice.events) {
+		// Skip clef context events if we've already output the clef at the beginning
+		if (clefOutputted && event.type === 'context') {
+			const ctx = event as ContextChange;
+			if (ctx.clef && !ctx.key && !ctx.time && !ctx.ottava && !ctx.stemDirection && !ctx.tempo && !ctx.staff) {
+				// This is a clef-only context event, skip it
+				continue;
+			}
+		}
+
 		const { str: eventStr, newEnv } = serializeEvent(event, pitchEnv, prevDuration);
 		pitchEnv = newEnv;
 
@@ -616,12 +664,14 @@ const serializeVoice = (
 
 
 // Serialize a part, tracking staff state across voices
-// If measureContext is provided, pass it to the first voice only
+// measureContext is passed to all voices (for clef), but key/time only to first voice
 const serializePart = (
 	part: Part,
 	currentStaff: number,
 	isGrandStaff: boolean = false,
-	measureContext?: MeasureContext
+	measureContext?: MeasureContext,
+	isFirstPart: boolean = false,
+	clefsByStaff?: Record<number, Clef>
 ): { str: string; newStaff: number } => {
 	if (part.voices.length === 0) {
 		return { str: '', newStaff: currentStaff };
@@ -632,9 +682,11 @@ const serializePart = (
 
 	for (let i = 0; i < part.voices.length; i++) {
 		const voice = part.voices[i];
-		// Only pass measureContext to first voice
-		const ctx = i === 0 ? measureContext : undefined;
-		const { str, newStaff } = serializeVoice(voice, staff, isGrandStaff, ctx);
+		// Pass measureContext to all voices, isFirstVoice for key/time
+		// Pass staff clef from clefsByStaff map
+		const isFirstVoice = isFirstPart && i === 0;
+		const staffClef = clefsByStaff?.[voice.staff];
+		const { str, newStaff } = serializeVoice(voice, staff, isGrandStaff, measureContext, isFirstVoice, staffClef);
 		voiceStrs.push(str);
 		staff = newStaff;
 	}
@@ -645,19 +697,33 @@ const serializePart = (
 
 
 // Serialize a measure, tracking staff state across parts
-const serializeMeasure = (measure: Measure, isFirst: boolean, currentStaff: number, isGrandStaff: boolean = false): { str: string; newStaff: number } => {
+// Always output key/time at start of each measure
+const serializeMeasure = (
+	measure: Measure,
+	_isFirst: boolean,
+	currentStaff: number,
+	isGrandStaff: boolean = false,
+	currentKey?: KeySignature,
+	currentTime?: { numerator: number; denominator: number; symbol?: 'common' | 'cut' },
+	staffClefs?: Record<number, Clef>
+): { str: string; newStaff: number } => {
 	const parts: string[] = [];
 
-	// Build measure context for first voice (key/time signatures)
-	const measureContext: MeasureContext | undefined = isFirst ? {
-		key: measure.key,
-		time: measure.timeSig,
-	} : undefined;
+	// Build measure context for all voices (key/time)
+	// Key and time are written to first voice, clef to all voices based on staff
+	// Use passed currentKey/currentTime which tracks across all measures
+	const measureContext: MeasureContext = {
+		key: currentKey,
+		time: currentTime,
+	};
+
+	// Pass staffClefs to parts for per-voice clef lookup
+	const clefsByStaff = staffClefs || {};
 
 	// Parts
 	let staff = currentStaff;
 	if (measure.parts.length === 1) {
-		const { str: partStr, newStaff } = serializePart(measure.parts[0], staff, isGrandStaff, measureContext);
+		const { str: partStr, newStaff } = serializePart(measure.parts[0], staff, isGrandStaff, measureContext, true, clefsByStaff);
 		if (partStr) {
 			parts.push(partStr);
 		}
@@ -667,9 +733,8 @@ const serializeMeasure = (measure: Measure, isFirst: boolean, currentStaff: numb
 		const partStrs: string[] = [];
 		for (let i = 0; i < measure.parts.length; i++) {
 			const part = measure.parts[i];
-			// Only pass measureContext to first part
-			const ctx = i === 0 ? measureContext : undefined;
-			const { str, newStaff } = serializePart(part, staff, isGrandStaff, ctx);
+			// Pass measureContext to all parts, isFirstPart to first part only
+			const { str, newStaff } = serializePart(part, staff, isGrandStaff, measureContext, i === 0, clefsByStaff);
 			if (str) {
 				partStrs.push(str);
 			}
@@ -735,10 +800,35 @@ export const serializeLilyletDoc = (doc: LilyletDoc): string => {
 
 	// Measures with bar lines, measure numbers, and double newlines
 	// Track staff state across measures (parser remembers staff across bar lines)
+	// Track key/time/clef across measures to output in every measure
 	const measureStrs: string[] = [];
 	let currentStaff = 1; // Parser starts at staff 1
+	let currentKey: KeySignature | undefined;
+	let currentTime: { numerator: number; denominator: number; symbol?: 'common' | 'cut' } | undefined;
+	const staffClefs: Record<number, Clef> = {}; // Track clef per staff
+
 	for (let i = 0; i < doc.measures.length; i++) {
-		const { str: measureStr, newStaff } = serializeMeasure(doc.measures[i], i === 0, currentStaff, isGrandStaff);
+		const measure = doc.measures[i];
+		// Update current key/time if measure has them
+		if (measure.key) {
+			currentKey = measure.key;
+		}
+		if (measure.timeSig) {
+			currentTime = measure.timeSig;
+		}
+
+		// Collect clefs from this measure's voices
+		for (const part of measure.parts) {
+			for (const voice of part.voices) {
+				for (const event of voice.events) {
+					if (event.type === 'context' && (event as ContextChange).clef) {
+						staffClefs[voice.staff] = (event as ContextChange).clef!;
+					}
+				}
+			}
+		}
+
+		const { str: measureStr, newStaff } = serializeMeasure(measure, i === 0, currentStaff, isGrandStaff, currentKey, currentTime, staffClefs);
 		// Always include measure, even if empty (use space rest for empty measures)
 		measureStrs.push(measureStr || 's1');
 		currentStaff = newStaff;