songsheet 6.3.0 → 7.0.0

package/CLAUDE.md

@@ -149,30 +149,3 @@ Atom       = SectionRef | ChordList | '(' Sequence ')'
 ```
 
 Examples: `(VERSE, CHORUS*2)`, `(D G D A)*4`, `D G D A D`
-
-## Future Features
-
-### Percentage-based timing (`%`)
-Support `%` notation for specifying timing or duration within a measure:
-
-```
-G%50 C%50            — split measure: 50% G, 50% C
-D%75 G%25            — 3/4 D, 1/4 G
-```
-
-This would add a `duration` or `percent` field to chord objects:
-```js
-{ root: 'G', type: '', percent: 50 }
-```
-
-### Key detection
-Auto-detect the song's key from its chord progression. Useful for intelligent transposition suggestions.
-
-### Measure/bar grouping
-Currently `|` markers are tracked by column position. Future: group chords into explicit measures with bar lines as structural delimiters.
-
-### Multi-voice / harmony lines
-Support for parallel harmony notation — multiple chord lines mapped to the same lyric line.
-
-### Nashville number system output
-Convert chord roots to Nashville numbers (1, 2, 3...) relative to the detected or specified key.

package/index.d.ts

@@ -58,6 +58,26 @@ export interface TimeSignature {
   value: number
 }
 
+export interface PlaybackChord {
+  root: string
+  type: string
+  bass?: string
+  nashville?: boolean
+  diamond?: boolean
+  push?: boolean
+  stop?: boolean
+  beatStart: number
+  durationInBeats: number
+}
+
+export interface PlaybackMeasure {
+  measureIndex: number
+  structureIndex: number
+  lineIndex: number
+  timeSignature: TimeSignature
+  chords: PlaybackChord[]
+}
+
 export interface Song {
   title: string
   author: string
@@ -66,9 +86,11 @@ export interface Song {
   key: string | null
   sections: Record<string, Section>
   structure: StructureEntry[]
+  playback: PlaybackMeasure[]
 }
 
 export function parse(raw: string): Song
 export function transpose(song: Song, semitones: number, options?: { preferFlats?: boolean }): Song
 export function toNashville(song: Song, key: string): Song
 export function toStandard(song: Song, key: string): Song
+export function buildPlaybackTimeline(structure: StructureEntry[], timeSignature: TimeSignature | null): PlaybackMeasure[]

package/index.js

@@ -1,3 +1,4 @@
 export { parse } from './src/parser.js'
 export { transpose } from './src/transpose.js'
 export { toNashville, toStandard } from './src/notation.js'
+export { buildPlaybackTimeline } from './src/playback.js'

package/package.json

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

package/src/lexer.js

@@ -186,8 +186,8 @@ export function scanChordLine(line) {
     return null
   }
 
-  // must have at least one chord
-  if (!tokens.some(t => t.type === 'CHORD')) return null
+  // must have at least one chord or bar line
+  if (tokens.length === 0) return null
 
   return tokens
 }

package/src/notation.js

@@ -167,10 +167,22 @@ function convertSong(song, key, toNNS) {
     expression: convertExpressionNode(entry.expression, keySemitone, toNNS, preferFlats),
   }))
 
+  // Convert playback timeline
+  const newPlayback = song.playback
+    ? song.playback.map(measure => ({
+        ...measure,
+        chords: measure.chords.map(c => {
+          const converted = convertChord(c, keySemitone, toNNS, preferFlats)
+          return { ...converted, beatStart: c.beatStart, durationInBeats: c.durationInBeats }
+        }),
+      }))
+    : undefined
+
   return {
     ...song,
     sections: newSections,
     structure: newStructure,
+    ...(newPlayback !== undefined && { playback: newPlayback }),
   }
 }
 

package/src/parser.js

@@ -1,4 +1,5 @@
 import { scanChordLine, isChordLine, lexExpression, ExprTokenTypes } from './lexer.js'
+import { buildPlaybackTimeline } from './playback.js'
 
 // ─── Token-to-Chord Helpers ──────────────────────────────────────────
 
@@ -499,7 +500,8 @@ export function parse(rawSongsheet) {
     }
   }
 
-  return { title, author, bpm, timeSignature, key, sections, structure }
+  const playback = buildPlaybackTimeline(structure, timeSignature)
+  return { title, author, bpm, timeSignature, key, sections, structure, playback }
 }
 
 function inferSectionType(sections, lyrics, chords) {

package/src/playback.js

@@ -0,0 +1,121 @@
+/**
+ * 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) {
+  if (chord.splitMeasure && chord.splitMeasure.length > 0) {
+    return chord.splitMeasure.map(sc => {
+      const pc = { root: sc.root, type: sc.type }
+      if (sc.bass) pc.bass = sc.bass
+      if (sc.nashville) pc.nashville = true
+      if (sc.diamond) pc.diamond = true
+      if (sc.push) pc.push = true
+      if (sc.stop) pc.stop = true
+      return pc
+    })
+  }
+  const pc = { root: chord.root, type: chord.type }
+  if (chord.bass) pc.bass = chord.bass
+  if (chord.nashville) pc.nashville = true
+  if (chord.diamond) pc.diamond = true
+  if (chord.push) pc.push = true
+  if (chord.stop) pc.stop = true
+  return [pc]
+}
+
+/**
+ * Build a PlaybackMeasure from an array of expanded PlaybackChords.
+ * Divides beats equally among the chords.
+ */
+function buildMeasure(chords, measureIndex, structureIndex, lineIndex, ts) {
+  const beats = ts.beats
+  const beatPerChord = chords.length > 0 ? beats / chords.length : beats
+  const assignedChords = chords.map((c, i) => ({
+    ...c,
+    beatStart: i * beatPerChord,
+    durationInBeats: beatPerChord,
+  }))
+  return {
+    measureIndex,
+    structureIndex,
+    lineIndex,
+    timeSignature: ts,
+    chords: assignedChords,
+  }
+}
+
+/**
+ * Build the playback timeline from the song's structure array.
+ *
+ * @param {Array} structure - song.structure entries
+ * @param {Object|null} timeSignature - { beats, value } or null (defaults to 4/4)
+ * @returns {Array} PlaybackMeasure[]
+ */
+export function buildPlaybackTimeline(structure, timeSignature) {
+  const ts = timeSignature || { beats: 4, value: 4 }
+  const measures = []
+  let measureIndex = 0
+
+  for (let si = 0; si < structure.length; si++) {
+    const entry = structure[si]
+
+    if (entry.lines.length > 0) {
+      // Lines with chords and barlines
+      for (let li = 0; li < entry.lines.length; li++) {
+        const line = entry.lines[li]
+        if (line.chords.length === 0 && line.barLines.length === 0) continue
+
+        // Merge chords and barlines into column-sorted markers
+        const markers = []
+        for (const chord of line.chords) {
+          markers.push({ col: chord.column, type: 'chord', chord })
+        }
+        for (const bar of line.barLines) {
+          markers.push({ col: bar.column, type: 'bar' })
+        }
+        markers.sort((a, b) => a.col - b.col)
+
+        const hasBarlines = line.barLines.length > 0
+
+        if (hasBarlines) {
+          // 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))
+            measureIndex++
+          }
+        } else {
+          // No barlines: each chord is its own measure
+          for (const chord of line.chords) {
+            const expanded = expandChord(chord)
+            measures.push(buildMeasure(expanded, measureIndex, si, li, ts))
+            measureIndex++
+          }
+        }
+      }
+    } else {
+      // Expression-only entries (FILL, INSTRUMENTAL, etc.) — chords only, no lines
+      for (const chord of entry.chords) {
+        const expanded = expandChord(chord)
+        measures.push(buildMeasure(expanded, measureIndex, si, -1, ts))
+        measureIndex++
+      }
+    }
+  }
+
+  return measures
+}

package/src/transpose.js

@@ -108,9 +108,21 @@ export function transpose(song, semitones, options = {}) {
     expression: transposeExpressionNode(entry.expression, semitones, preferFlats),
   }))
 
+  // Transpose playback timeline
+  const newPlayback = song.playback
+    ? song.playback.map(measure => ({
+        ...measure,
+        chords: measure.chords.map(c => {
+          const transposed = transposeChordObj(c, semitones, preferFlats)
+          return { ...transposed, beatStart: c.beatStart, durationInBeats: c.durationInBeats }
+        }),
+      }))
+    : undefined
+
   return {
     ...song,
     sections: newSections,
     structure: newStructure,
+    ...(newPlayback !== undefined && { playback: newPlayback }),
   }
 }

package/test/playback.test.js

@@ -0,0 +1,217 @@
+import { describe, it, expect } from 'vitest'
+import { readFileSync } from 'fs'
+import { parse } from '../src/parser.js'
+import { buildPlaybackTimeline } from '../src/playback.js'
+
+function loadSong(file) {
+  return parse(readFileSync(file, 'utf8'))
+}
+
+describe('buildPlaybackTimeline', () => {
+  describe('no barlines — each chord is its own measure', () => {
+    it('creates one measure per chord', () => {
+      const song = parse('TITLE\n\nG                D\n Lyrics here\n               C\n More lyrics')
+      const playback = song.playback
+      expect(playback.length).toBeGreaterThanOrEqual(3)
+      // Each measure should have exactly 1 chord with full beat allocation
+      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)
+      }
+    })
+  })
+
+  describe('barlines present — chords grouped into measures', () => {
+    it('| G | C | D | creates 3 measures, 1 chord each', () => {
+      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')
+      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('| C D | creates 1 measure with 2 chords at beats 0 and 2', () => {
+      const song = parse('TITLE\n\n| C D |\n Lyrics')
+      const playback = song.playback
+      expect(playback.length).toBe(1)
+      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)
+    })
+
+    it('D | creates 1 measure with D getting full measure', () => {
+      const song = parse('TITLE\n\nD |\n Lyrics')
+      const playback = song.playback
+      expect(playback.length).toBe(1)
+      expect(playback[0].chords.length).toBe(1)
+      expect(playback[0].chords[0].root).toBe('D')
+      expect(playback[0].chords[0].durationInBeats).toBe(4)
+    })
+
+    it('leading | with no preceding chords is discarded', () => {
+      const song = parse('TITLE\n\n| G |\n Lyrics')
+      const playback = song.playback
+      expect(playback.length).toBe(1)
+      expect(playback[0].chords[0].root).toBe('G')
+    })
+  })
+
+  describe('split measure expansion', () => {
+    it('[G C] expands into 2 PlaybackChords sharing one measure', () => {
+      const song = parse('TITLE\n\n[G C]\n Lyrics')
+      const playback = song.playback
+      expect(playback.length).toBe(1)
+      expect(playback[0].chords.length).toBe(2)
+      expect(playback[0].chords[0].root).toBe('G')
+      expect(playback[0].chords[0].beatStart).toBe(0)
+      expect(playback[0].chords[0].durationInBeats).toBe(2)
+      expect(playback[0].chords[1].root).toBe('C')
+      expect(playback[0].chords[1].beatStart).toBe(2)
+      expect(playback[0].chords[1].durationInBeats).toBe(2)
+    })
+  })
+
+  describe('decorator preservation', () => {
+    it('preserves push flag', () => {
+      const song = parse('TITLE\n\n^G\n Lyrics')
+      expect(song.playback[0].chords[0].push).toBe(true)
+    })
+
+    it('preserves diamond flag', () => {
+      const song = parse('TITLE\n\n<G>\n Lyrics')
+      expect(song.playback[0].chords[0].diamond).toBe(true)
+    })
+
+    it('preserves stop flag', () => {
+      const song = parse('TITLE\n\nG!\n Lyrics')
+      expect(song.playback[0].chords[0].stop).toBe(true)
+    })
+  })
+
+  describe('expression-only entries', () => {
+    it('FILL chords become measures with lineIndex -1', () => {
+      const song = parse('TITLE\n\nG\n Lyrics\n\nFILL: D G A')
+      const fillMeasures = song.playback.filter(m => m.lineIndex === -1)
+      expect(fillMeasures.length).toBe(3)
+      expect(fillMeasures[0].chords[0].root).toBe('D')
+      expect(fillMeasures[1].chords[0].root).toBe('G')
+      expect(fillMeasures[2].chords[0].root).toBe('A')
+    })
+  })
+
+  describe('3/4 time signature', () => {
+    it('divides beats by 3', () => {
+      const song = parse('TITLE\n(3/4 time)\n\n| G C D |\n Lyrics')
+      const playback = song.playback
+      expect(playback.length).toBe(1)
+      expect(playback[0].chords.length).toBe(3)
+      expect(playback[0].chords[0].durationInBeats).toBe(1)
+      expect(playback[0].chords[1].durationInBeats).toBe(1)
+      expect(playback[0].chords[2].durationInBeats).toBe(1)
+      expect(playback[0].timeSignature.beats).toBe(3)
+    })
+  })
+
+  describe('back-references', () => {
+    it('sets correct structureIndex and lineIndex', () => {
+      const song = parse('TITLE\n\nG\n Line 1\n          D\n Line 2')
+      expect(song.playback[0].structureIndex).toBe(0)
+      expect(song.playback[0].lineIndex).toBe(0)
+      expect(song.playback[1].structureIndex).toBe(0)
+      expect(song.playback[1].lineIndex).toBe(1)
+    })
+
+    it('increments measureIndex correctly', () => {
+      const song = parse('TITLE\n\nG\n Line 1\n          D\n Line 2')
+      expect(song.playback[0].measureIndex).toBe(0)
+      expect(song.playback[1].measureIndex).toBe(1)
+    })
+  })
+
+  describe('fixture: spent-some-time-in-buffalo.txt', () => {
+    const song = loadSong('./spent-some-time-in-buffalo.txt')
+
+    it('produces playback measures', () => {
+      expect(song.playback.length).toBeGreaterThan(0)
+    })
+
+    it('has correct structure back-references', () => {
+      for (const m of song.playback) {
+        expect(m.structureIndex).toBeGreaterThanOrEqual(0)
+        expect(m.structureIndex).toBeLessThan(song.structure.length)
+      }
+    })
+
+    it('uses barline grouping for chord lines with barlines', () => {
+      // The verse has patterns like "D  |" — D followed by barline = 1 measure
+      // Check that the first structure entry (verse) doesn't duplicate chords at barlines
+      const verseMeasures = song.playback.filter(m => m.structureIndex === 0)
+      // Verse line 1: "D                        |" — 1 chord D before barline = 1 measure
+      // Verse line 2: "G                                 |" — 1 chord G before barline = 1 measure
+      // Verse line 3: "        A                               C                                   D     |"
+      //   — 3 chords (A, C, D) before barline = 1 measure with 3 chords
+      expect(verseMeasures.length).toBe(3)
+      expect(verseMeasures[0].chords[0].root).toBe('D')
+      expect(verseMeasures[1].chords[0].root).toBe('G')
+      expect(verseMeasures[2].chords.length).toBe(3)
+    })
+
+    it('measure indices are sequential', () => {
+      for (let i = 0; i < song.playback.length; i++) {
+        expect(song.playback[i].measureIndex).toBe(i)
+      }
+    })
+  })
+
+  describe('fixture: riot-on-a-screen.txt', () => {
+    const song = loadSong('./riot-on-a-screen.txt')
+
+    it('produces playback measures', () => {
+      expect(song.playback.length).toBeGreaterThan(0)
+    })
+
+    it('has no barlines — each chord is its own measure', () => {
+      // Riot on a screen has no barlines, so each chord should be its own measure
+      for (const m of song.playback) {
+        // Each measure should have 1 chord (unless split measure)
+        expect(m.chords.length).toBeGreaterThanOrEqual(1)
+      }
+    })
+
+    it('measure indices are sequential', () => {
+      for (let i = 0; i < song.playback.length; i++) {
+        expect(song.playback[i].measureIndex).toBe(i)
+      }
+    })
+  })
+
+  describe('buildPlaybackTimeline standalone', () => {
+    it('returns empty array for empty structure', () => {
+      expect(buildPlaybackTimeline([], null)).toEqual([])
+    })
+
+    it('defaults to 4/4 when timeSignature is null', () => {
+      const structure = [{
+        sectionType: 'verse',
+        sectionIndex: 0,
+        chords: [{ root: 'G', type: '' }],
+        lyrics: [],
+        lines: [],
+        expression: null,
+      }]
+      const playback = buildPlaybackTimeline(structure, null)
+      expect(playback[0].timeSignature).toEqual({ beats: 4, value: 4 })
+    })
+  })
+})