songsheet 7.2.0 → 7.4.0

package/CLAUDE.md

@@ -1,6 +1,6 @@
 # Songsheet
 
-A zero-dependency songsheet parser and transposer. Parses plaintext songsheet files into a structured AST with chord-lyric character alignment.
+A zero-dependency songsheet parser and transposer. Parses plaintext songsheet files into a structured AST with chord-lyric character alignment and a playback timeline.
 
 ## Quick Start
 
@@ -15,16 +15,20 @@ const songInBb = transpose(song, 3, { preferFlats: true })
 ## Architecture
 
 ```
-index.js              — Public API: re-exports parse + transpose
+index.js              — Public API: parse, transpose, toNashville, toStandard, buildPlaybackTimeline
 index.d.ts            — TypeScript type definitions (adjacent to index.js)
 src/
   lexer.js            — scanChordLine(), isChordLine(), lexExpression()
   parser.js           — parse(), expression parser, section assembly
+  playback.js         — buildPlaybackTimeline(), barline/measure expansion
+  notation.js         — toNashville(), toStandard()
   transpose.js        — transpose(), note math
 test/
   lexer.test.js       — Chord line detection, bar lines, slash chords, edge cases
   parser.test.js      — All 4 song fixture tests + bar line + time signature tests
   expression.test.js  — Expression parsing and resolution
+  playback.test.js    — Timeline generation, barline semantics, marker indexing
+  nns.test.js         — Nashville Number System parsing/conversion coverage
   transpose.test.js   — Semitone math, round-trips, flat/sharp preference, slash chords
 *.txt                 — Song fixtures (do not modify)
 ```
@@ -62,10 +66,13 @@ npx vitest run test/parser.test.js   # single file
       lines: [
         {
           chords: [{ root: 'G', type: '', column: 0 }, ...],
-          barLines: [],           // column positions of | markers
+          barLines: [
+            { column: 12, chord: { root: 'G', type: '' } }  // optional carried context
+          ],
           lyrics: 'lyric line 1',
           characters: [
             { character: 'B', chord: { root: 'G', type: '' } },
+            { character: '|', barLine: true },
             { character: 'l' },
             ...
           ]
@@ -84,6 +91,23 @@ npx vitest run test/parser.test.js   # single file
       expression: null,   // non-null on directive entries
     },
     ...
+  ],
+  playback: [
+    {
+      measureIndex: 0,
+      structureIndex: 0,
+      lineIndex: 0,
+      timeSignature: { beats: 3, value: 4 },
+      chords: [
+        {
+          root: 'G',
+          type: '',
+          markerIndex: 0,        // marker index in merged chord/bar marker row (optional)
+          beatStart: 0,
+          durationInBeats: 3
+        }
+      ]
+    }
   ]
 }
 ```
@@ -96,8 +120,11 @@ npx vitest run test/parser.test.js   # single file
 - **Synchronous parse**: No Promise wrapper, plain objects (no Immutable.js)
 - **Expression AST preserved**: `(VERSE, CHORUS*2)` stored as tree AND resolved to flat chords
 - **Character alignment includes barLines**: `{ character: 'r', barLine: true }` at `|` column positions
+- **Barline context is carried across chord lines**: leading `|` on a new line can repeat the prior chord
 - **Column preservation**: Chord lines are never trimmed — column positions match the original file
 - **Title metadata**: BPM and time signature parsed from `(120 BPM, 3/4 time)` in the title block
+- **Playback timeline**: parser output includes `playback[]` measures with `beatStart`/`durationInBeats` and optional `markerIndex` for UI highlighting
+- **Strict bracket split syntax**: only `[A B ...]` creates multi-chord measures; `|` markers repeat measures and never group adjacent chords
 - **TypeScript types**: `index.d.ts` adjacent to `index.js` — consumers get types automatically with bundler module resolution
 
 ## Songsheet Format

package/README.md

@@ -1,6 +1,6 @@
 # songsheet
 
-A zero-dependency songsheet parser and transposer. Parses plaintext songsheet files into a structured AST with chord-lyric character alignment.
+A zero-dependency songsheet parser and transposer. Parses plaintext songsheet files into a structured AST with chord-lyric alignment and builds a playback timeline.
 
 ## Install
 
@@ -111,10 +111,13 @@ Examples: `(VERSE, CHORUS*2)`, `(D G D A)*4`, `D G D A D`
       lines: [
         {
           chords: [{ root: 'G', type: '', column: 0 }, ...],
-          barLines: [],           // column positions of | markers
+          barLines: [             // | markers with optional carried chord context
+            { column: 12, chord: { root: 'G', type: '' } }
+          ],
           lyrics: 'lyric line 1',
           characters: [
             { character: 'B', chord: { root: 'G', type: '' } },
+            { character: '|', barLine: true },
             { character: 'l' },
             ...
           ]
@@ -135,13 +138,49 @@ Examples: `(VERSE, CHORUS*2)`, `(D G D A)*4`, `D G D A D`
       expression: null,   // non-null on directive entries
     },
     ...
+  ],
+
+  // Flattened playback timeline (measure-by-measure)
+  playback: [
+    {
+      measureIndex: 0,
+      structureIndex: 0,
+      lineIndex: 0,
+      timeSignature: { beats: 3, value: 4 },
+      chords: [
+        {
+          root: 'G',
+          type: '',
+          markerIndex: 0,       // marker index in the rendered line (optional)
+          beatStart: 0,
+          durationInBeats: 3
+        }
+      ]
+    }
   ]
 }
 ```
 
+## Playback Barline Semantics
+
+Playback is derived from each line's chords and `|` markers using these rules:
+
+1. Each chord token is its own measure unless written as bracket split syntax (`[C D]`).
+2. Each `|` repeats a measure.
+3. Barline repeats use chord context carried by the parser, so leading bars on a line can repeat the previous line's chord.
+
+Examples:
+
+- `[C D]` -> one measure split evenly between `C` and `D`
+- `C D |` -> `C`, `D`, `D`
+- `| C D |` -> `C`, `D`, `D`
+- `| G | C | D |` -> `G`, `G`, `C`, `C`, `D`, `D`
+- `C C/B Am G F | Fsus4 F` -> `C`, `C/B`, `Am`, `G`, `F`, `F`, `Fsus4`, `F`
+- `C | F C` then `| | G |` -> `C`, `C`, `F`, `C`, `C`, `C`, `G`, `G`
+
 ## Transposition
 
-`transpose()` deep-walks the AST and replaces every chord root (and bass note on slash chords). It auto-detects whether the song uses flats or sharps, or you can override with `{ preferFlats: true }`.
+`transpose()` deep-walks the AST and replaces every chord root (and bass note on slash chords). It auto-detects whether the song uses flats or sharps, or you can override with `{ preferFlats: true }`. Playback timing metadata (`beatStart`, `durationInBeats`, `markerIndex`) is preserved.
 
 ```js
 const song = parse(rawText)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "songsheet",
-  "version": "7.2.0",
+  "version": "7.4.0",
   "description": "A songsheet interpreter",
   "type": "module",
   "exports": "./index.js",

package/src/notation.js

@@ -173,7 +173,9 @@ function convertSong(song, key, toNNS) {
         ...measure,
         chords: measure.chords.map(c => {
           const converted = convertChord(c, keySemitone, toNNS, preferFlats)
-          return { ...converted, beatStart: c.beatStart, durationInBeats: c.durationInBeats }
+          const playbackChord = { ...converted, beatStart: c.beatStart, durationInBeats: c.durationInBeats }
+          if (c.markerIndex !== undefined) playbackChord.markerIndex = c.markerIndex
+          return playbackChord
         }),
       }))
     : undefined

package/src/playback.js

@@ -2,7 +2,7 @@
  * Expand a chord into PlaybackChord(s). If the chord has a splitMeasure,
  * each sub-chord becomes a separate PlaybackChord; otherwise a single one.
  */
-function expandChord(chord) {
+function expandChord(chord, markerIndex) {
   if (chord.splitMeasure && chord.splitMeasure.length > 0) {
     return chord.splitMeasure.map(sc => {
       const pc = { root: sc.root, type: sc.type }
@@ -11,6 +11,7 @@ function expandChord(chord) {
       if (sc.diamond) pc.diamond = true
       if (sc.push) pc.push = true
       if (sc.stop) pc.stop = true
+      if (markerIndex !== undefined) pc.markerIndex = markerIndex
       return pc
     })
   }
@@ -20,6 +21,7 @@ function expandChord(chord) {
   if (chord.diamond) pc.diamond = true
   if (chord.push) pc.push = true
   if (chord.stop) pc.stop = true
+  if (markerIndex !== undefined) pc.markerIndex = markerIndex
   return [pc]
 }
 
@@ -44,62 +46,6 @@ function buildMeasure(chords, measureIndex, structureIndex, lineIndex, ts) {
   }
 }
 
-/**
- * Check if barlines on this line actually separate chords (e.g., | G | C | D |)
- * vs. just trailing after all chords (e.g., A C D |).
- * Returns true only when a barline appears between two chords.
- */
-function detectInterBarlines(markers) {
-  let seenChord = false
-  let seenBarAfterChord = false
-  for (const m of markers) {
-    if (m.type === 'chord') {
-      if (seenBarAfterChord) return true
-      seenChord = true
-    } else if (m.type === 'bar' && seenChord) {
-      seenBarAfterChord = true
-    }
-  }
-  return false
-}
-
-/**
- * Detect consecutive barlines (e.g., C || D), which usually indicate
- * repeated held measures rather than explicit bar-delimited grouping.
- */
-function hasConsecutiveBars(markers) {
-  let prevWasBar = false
-  for (const m of markers) {
-    if (m.type === 'bar') {
-      if (prevWasBar) return true
-      prevWasBar = true
-    } else {
-      prevWasBar = false
-    }
-  }
-  return false
-}
-
-/**
- * Decide whether a line should be grouped by explicit barline boundaries.
- *
- * Heuristic:
- * - require at least one barline between chords
- * - require barline density to be at least chord density
- * - reject consecutive barlines (treated as hold repeats)
- *
- * Sparse barlines like "C C/B Am G F | Fsus4 F" stay in chord-per-measure mode.
- */
-function shouldGroupByBarlines(markers) {
-  const chordCount = markers.filter(m => m.type === 'chord').length
-  const barCount = markers.length - chordCount
-  if (chordCount === 0 || barCount === 0) return false
-  if (!detectInterBarlines(markers)) return false
-  if (barCount < chordCount) return false
-  if (hasConsecutiveBars(markers)) return false
-  return true
-}
-
 /**
  * Build the playback timeline from the song's structure array.
  *
@@ -127,51 +73,43 @@ export function buildPlaybackTimeline(structure, timeSignature) {
           markers.push({ col: chord.column, type: 'chord', chord })
         }
         for (const bar of line.barLines) {
-          markers.push({ col: bar.column, type: 'bar' })
+          markers.push({ col: bar.column, type: 'bar', bar })
         }
         markers.sort((a, b) => a.col - b.col)
 
-        if (shouldGroupByBarlines(markers)) {
-          // Group chords by barline boundaries
-          let currentChords = []
-          for (const m of markers) {
-            if (m.type === 'chord') {
-              currentChords.push(...expandChord(m.chord))
-            } else {
-              // Bar line: flush accumulated chords as a measure
-              if (currentChords.length > 0) {
-                measures.push(buildMeasure(currentChords, measureIndex, si, li, ts))
-                measureIndex++
-                currentChords = []
-              }
-              // Leading barline with no preceding chords → discard (visual marker only)
-            }
-          }
-          // Any remaining chords after the last barline form a measure
-          if (currentChords.length > 0) {
-            measures.push(buildMeasure(currentChords, measureIndex, si, li, ts))
+        // Strict bracket syntax: only [A B ...] creates multi-chord measures.
+        // Barlines never group multiple adjacent chord tokens into one measure;
+        // instead they repeat the current/last carried chord for another measure.
+        let lastExpanded = null
+        for (let mi = 0; mi < markers.length; mi++) {
+          const m = markers[mi]
+          if (m.type === 'chord') {
+            lastExpanded = expandChord(m.chord, mi)
+            measures.push(buildMeasure(lastExpanded, measureIndex, si, li, ts))
             measureIndex++
-          }
-        } else {
-          // No inter-barlines: each chord is its own measure.
-          // Trailing barlines repeat the preceding chord for one additional measure.
-          let lastExpanded = null
-          for (const m of markers) {
-            if (m.type === 'chord') {
-              lastExpanded = expandChord(m.chord)
-              measures.push(buildMeasure(lastExpanded, measureIndex, si, li, ts))
-              measureIndex++
-            } else if (m.type === 'bar' && lastExpanded) {
-              measures.push(buildMeasure([...lastExpanded], measureIndex, si, li, ts))
+          } else if (m.type === 'bar') {
+            // Use parser-provided bar chord context when available.
+            // This enables leading bars on a new line (e.g. "| | G |")
+            // to repeat the previous line's carried chord.
+            let repeatedAtBar = null
+            if (m.bar && m.bar.chord) {
+              repeatedAtBar = expandChord(m.bar.chord, mi)
+            } else if (lastExpanded) {
+              repeatedAtBar = lastExpanded.map(c => ({ ...c, markerIndex: mi }))
+            }
+            if (repeatedAtBar) {
+              measures.push(buildMeasure(repeatedAtBar, measureIndex, si, li, ts))
               measureIndex++
+              lastExpanded = repeatedAtBar
             }
           }
         }
       }
     } else {
       // Expression-only entries (FILL, INSTRUMENTAL, etc.) — chords only, no lines
-      for (const chord of entry.chords) {
-        const expanded = expandChord(chord)
+      for (let ci = 0; ci < entry.chords.length; ci++) {
+        const chord = entry.chords[ci]
+        const expanded = expandChord(chord, ci)
         measures.push(buildMeasure(expanded, measureIndex, si, -1, ts))
         measureIndex++
       }

package/src/transpose.js

@@ -114,7 +114,9 @@ export function transpose(song, semitones, options = {}) {
         ...measure,
         chords: measure.chords.map(c => {
           const transposed = transposeChordObj(c, semitones, preferFlats)
-          return { ...transposed, beatStart: c.beatStart, durationInBeats: c.durationInBeats }
+          const playbackChord = { ...transposed, beatStart: c.beatStart, durationInBeats: c.durationInBeats }
+          if (c.markerIndex !== undefined) playbackChord.markerIndex = c.markerIndex
+          return playbackChord
         }),
       }))
     : undefined

package/test/playback.test.js

@@ -22,14 +22,12 @@ describe('buildPlaybackTimeline', () => {
     })
   })
 
-  describe('barlines present — chords grouped into measures', () => {
-    it('| G | C | D | creates 3 measures, 1 chord each', () => {
+  describe('barlines present — bars repeat measures (no multi-chord grouping)', () => {
+    it('| G | C | D | repeats each bar-marked chord', () => {
       const song = parse('TITLE\n\n| G | C | D |\n Lyrics')
       const playback = song.playback
-      expect(playback.length).toBe(3)
-      expect(playback[0].chords[0].root).toBe('G')
-      expect(playback[1].chords[0].root).toBe('C')
-      expect(playback[2].chords[0].root).toBe('D')
+      expect(playback.length).toBe(6)
+      expect(playback.map(m => m.chords[0].root)).toEqual(['G', 'G', 'C', 'C', 'D', 'D'])
       for (const m of playback) {
         expect(m.chords.length).toBe(1)
         expect(m.chords[0].beatStart).toBe(0)
@@ -46,19 +44,16 @@ describe('buildPlaybackTimeline', () => {
       expect(playback[2].chords[0].root).toBe('D')
     })
 
-    it('| C D | G | groups by barlines when inter-barlines present', () => {
+    it('| C D | G | does not form multi-chord measures without brackets', () => {
       const song = parse('TITLE\n\n| C D | G |\n Lyrics')
       const playback = song.playback
-      // Barline between D and G → barline grouping applies
-      expect(playback.length).toBe(2)
-      expect(playback[0].chords.length).toBe(2)
-      expect(playback[0].chords[0].root).toBe('C')
-      expect(playback[0].chords[0].beatStart).toBe(0)
-      expect(playback[0].chords[0].durationInBeats).toBe(2)
-      expect(playback[0].chords[1].root).toBe('D')
-      expect(playback[0].chords[1].beatStart).toBe(2)
-      expect(playback[0].chords[1].durationInBeats).toBe(2)
-      expect(playback[1].chords[0].root).toBe('G')
+      expect(playback.length).toBe(5)
+      expect(playback.map(m => m.chords[0].root)).toEqual(['C', 'D', 'D', 'G', 'G'])
+      for (const m of playback) {
+        expect(m.chords.length).toBe(1)
+        expect(m.chords[0].beatStart).toBe(0)
+        expect(m.chords[0].durationInBeats).toBe(4)
+      }
     })
 
     it('sparse inter-barline usage stays chord-per-measure with bar repeat', () => {
@@ -75,6 +70,18 @@ describe('buildPlaybackTimeline', () => {
       expect(playback[7].chords[0].type).toBe('')
     })
 
+    it('leading bars on next line repeat carried chord context', () => {
+      const song = parse(
+        'TITLE\n(3/4 time)\n\nC   |   F  C\nA way out on-line\n  |        |               G         |\nA thousand miles from what I know as mine'
+      )
+      const playback = song.playback
+      const roots = playback.map(m => m.chords[0].root + (m.chords[0].bass ? '/' + m.chords[0].bass : ''))
+      expect(roots).toEqual(['C', 'C', 'F', 'C', 'C', 'C', 'G', 'G'])
+      for (const m of playback) {
+        expect(m.chords[0].durationInBeats).toBe(3)
+      }
+    })
+
     it('D | creates 2 measures: D then barline repeats D', () => {
       const song = parse('TITLE\n\nD |\n Lyrics')
       const playback = song.playback
@@ -145,15 +152,15 @@ describe('buildPlaybackTimeline', () => {
       expect(playback[0].timeSignature.beats).toBe(3)
     })
 
-    it('inter-barline grouping divides beats by 3', () => {
+    it('barline repeats in 3/4 remain full-measure chords', () => {
       const song = parse('TITLE\n(3/4 time)\n\n| G | C D |\n Lyrics')
       const playback = song.playback
-      expect(playback.length).toBe(2)
-      expect(playback[0].chords[0].root).toBe('G')
-      expect(playback[0].chords[0].durationInBeats).toBe(3)
-      expect(playback[1].chords.length).toBe(2)
-      expect(playback[1].chords[0].durationInBeats).toBe(1.5)
-      expect(playback[1].chords[1].durationInBeats).toBe(1.5)
+      expect(playback.length).toBe(5)
+      expect(playback.map(m => m.chords[0].root)).toEqual(['G', 'G', 'C', 'D', 'D'])
+      for (const m of playback) {
+        expect(m.chords.length).toBe(1)
+        expect(m.chords[0].durationInBeats).toBe(3)
+      }
     })
   })
 
@@ -171,6 +178,22 @@ describe('buildPlaybackTimeline', () => {
       expect(song.playback[0].measureIndex).toBe(0)
       expect(song.playback[1].measureIndex).toBe(1)
     })
+
+    it('assigns playback markerIndex values for chords and bar repeats', () => {
+      const song = parse('TITLE\n\nC D |\n Lyrics')
+      expect(song.playback[0].chords[0].markerIndex).toBe(0) // C marker
+      expect(song.playback[1].chords[0].markerIndex).toBe(1) // D marker
+      expect(song.playback[2].chords[0].markerIndex).toBe(2) // trailing bar marker
+    })
+
+    it('assigns markerIndex for bar repeats without barline grouping', () => {
+      const song = parse('TITLE\n\n| C D | G |\n Lyrics')
+      expect(song.playback[0].chords[0].markerIndex).toBe(1) // C marker
+      expect(song.playback[1].chords[0].markerIndex).toBe(2) // D marker
+      expect(song.playback[2].chords[0].markerIndex).toBe(3) // repeated D at bar marker
+      expect(song.playback[3].chords[0].markerIndex).toBe(4) // G marker
+      expect(song.playback[4].chords[0].markerIndex).toBe(5) // repeated G at bar marker
+    })
   })
 
   describe('fixture: spent-some-time-in-buffalo.txt', () => {