@barmark/lyricsheet 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +79 -0
- package/LICENSE +21 -0
- package/README.md +168 -2
- package/dist/export/cells.d.ts +22 -0
- package/dist/export/cells.js +64 -0
- package/dist/export/changes.d.ts +18 -0
- package/dist/export/changes.js +70 -0
- package/dist/export/defines.d.ts +7 -0
- package/dist/export/defines.js +97 -0
- package/dist/export/grid.d.ts +9 -0
- package/dist/export/grid.js +210 -0
- package/dist/export/index.d.ts +3 -0
- package/dist/export/index.js +118 -0
- package/dist/export/lists.d.ts +13 -0
- package/dist/export/lists.js +33 -0
- package/dist/export/losses.d.ts +8 -0
- package/dist/export/losses.js +41 -0
- package/dist/export/lyrics.d.ts +61 -0
- package/dist/export/lyrics.js +269 -0
- package/dist/export/merge.d.ts +31 -0
- package/dist/export/merge.js +64 -0
- package/dist/export/meta.d.ts +10 -0
- package/dist/export/meta.js +67 -0
- package/dist/export/plan.d.ts +51 -0
- package/dist/export/plan.js +175 -0
- package/dist/export/sheet.d.ts +11 -0
- package/dist/export/sheet.js +51 -0
- package/dist/export/spell.d.ts +18 -0
- package/dist/export/spell.js +77 -0
- package/dist/export/text.d.ts +60 -0
- package/dist/export/text.js +53 -0
- package/dist/export/types.d.ts +72 -0
- package/dist/export/types.js +1 -0
- package/dist/export/written.d.ts +29 -0
- package/dist/export/written.js +117 -0
- package/dist/index.d.ts +3 -0
- package/dist/index.js +2 -0
- package/dist/version.d.ts +2 -0
- package/dist/version.js +2 -0
- package/package.json +47 -5
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to `@barmark/lyricsheet` are recorded here. The format
|
|
4
|
+
follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the
|
|
5
|
+
package uses [semantic versioning](https://semver.org/).
|
|
6
|
+
|
|
7
|
+
## [Unreleased]
|
|
8
|
+
|
|
9
|
+
## [0.1.0] - 2026-11-19
|
|
10
|
+
|
|
11
|
+
### Added
|
|
12
|
+
|
|
13
|
+
- The package: a barmark chart exported as a lyric sheet in ChordPro's
|
|
14
|
+
text format, and what the export could not carry. It needs `barmark`
|
|
15
|
+
and `@barmark/fretboard`; ChordPro is a separate project that this
|
|
16
|
+
package only writes for. From the command line it is `barmark export
|
|
17
|
+
--lyricsheet` (`@barmark/cli`).
|
|
18
|
+
- **`exportLyricsheet(chart, options?)`** answers `{ ok: true, text,
|
|
19
|
+
diagnostics, losses }` or `{ ok: false, diagnostics }` and never
|
|
20
|
+
throws, under Node or Bun. Options: `part` (the part's label), `title`
|
|
21
|
+
(for a chart with none) and `diagrams: "guitar"`. A chart with an
|
|
22
|
+
error, an unknown part or no bars is refused; with `part`, an error
|
|
23
|
+
anywhere in the chart refuses, since the words come from the whole
|
|
24
|
+
chart. Types: `LyricsheetOptions`, `LyricsheetResult`,
|
|
25
|
+
`LyricsheetLoss`, `LyricsheetLossCode`; `VERSION`.
|
|
26
|
+
- **The header**: title, credits, key, time and tempo as directives. A
|
|
27
|
+
sheet always has a title line (the chart's, else `title`, else
|
|
28
|
+
`{title: }`).
|
|
29
|
+
- **Sung sections** as lyric environments, in play order: each chord
|
|
30
|
+
before the syllable it lands on, a chord on no syllable standing
|
|
31
|
+
alone, `{chorus}` for a replayed chorus singing the same words, a
|
|
32
|
+
repeat singing the same words kept in one environment. `N.C.`, stops,
|
|
33
|
+
`?`, note sets, words, rehearsal marks and fermatas are annotations;
|
|
34
|
+
key, time and tempo changes are written where they happen, each with
|
|
35
|
+
a comment a reader sees; text lines, rit., accel. and feel are
|
|
36
|
+
comments. One part's harmony (the one named, else the first that
|
|
37
|
+
writes chord symbols) and the singer's words.
|
|
38
|
+
- **Sections with no words** as grids (`{start_of_grid: label="Intro"
|
|
39
|
+
shape="1+4x4+1"}`), so a chart with no lyrics loses almost nothing: a
|
|
40
|
+
cell per beat of the bar's own meter (6/8 two, 12/8 four), `.` for a
|
|
41
|
+
beat held, `/` for a name played again, `C~G` for chords sharing a
|
|
42
|
+
beat, `%` where the chart wrote it, words as right-margin text and
|
|
43
|
+
rehearsal marks as left-margin text. An occurrence that plays its
|
|
44
|
+
written lines straight through keeps `|:`, `:|`, voltas and `x N`;
|
|
45
|
+
any other (cut by a jump, an ending for several passes) is written as
|
|
46
|
+
played.
|
|
47
|
+
- **`diagrams: "guitar"`**: a `{define: Am base-fret 1 frets x 0 2 2 1
|
|
48
|
+
0}` line for every chord name the sheet writes, once each in the
|
|
49
|
+
order first written, between the header and the first section, from
|
|
50
|
+
`@barmark/fretboard`'s shapes. A shape that reaches the fifth fret
|
|
51
|
+
starts at its lowest fretted one, since a diagram is four frets tall.
|
|
52
|
+
A written voicing is the name's shape when every use of the name
|
|
53
|
+
writes that one voicing and a hand can play it. A chord name
|
|
54
|
+
ChordPro's parser rejects is accepted once it is defined.
|
|
55
|
+
- **Losses**, each reported once with its bars: `key-mode`,
|
|
56
|
+
`other-parts`, `other-lines`, `stacked-verses`, `chord-moved`,
|
|
57
|
+
`text-changed`, `chord-names`, `note-sets`, `voicing`, `marks`,
|
|
58
|
+
`bar-meter`, `fermata`, `mark-moved`, `no-shape` and `shell-shape`.
|
|
59
|
+
The README's table says what each means.
|
|
60
|
+
- **Chart text never reaches a reader as markup.** Brackets, braces and
|
|
61
|
+
angle brackets that would make a tag (even across two syllables) are
|
|
62
|
+
written as parentheses, a lyric line's leading `#` after a space, a
|
|
63
|
+
control character or a Unicode noncharacter as a space, a
|
|
64
|
+
line-ending backslash as `/`; and since ChordPro unescapes `{`
|
|
65
|
+
and `\u{7b}` on every line before it reads it, a backslash before a
|
|
66
|
+
`u` is written with a word joiner (U+2060, drawn as nothing) after
|
|
67
|
+
it. Each is a `text-changed` loss.
|
|
68
|
+
- **Bounded time**: linear in the chart, however large a repeat count
|
|
69
|
+
(`x 999999999` after a jump builds no more bars than the chart
|
|
70
|
+
plays).
|
|
71
|
+
- Checked by a golden sheet for every fixture chart (with diagrams for
|
|
72
|
+
four); a played yardstick that reads each sheet back into chords and
|
|
73
|
+
words in play order; ChordPro's own `chordpro --strict` on every
|
|
74
|
+
golden, on the maintainer's machine only; scale tests that a
|
|
75
|
+
quadratic fails, the large shapes also under Node; and every chart of
|
|
76
|
+
the corpus, with and without diagrams.
|
|
77
|
+
|
|
78
|
+
[Unreleased]: https://github.com/kevinpeckham/barmark/compare/lyricsheet-v0.1.0...HEAD
|
|
79
|
+
[0.1.0]: https://github.com/kevinpeckham/barmark/releases/tag/lyricsheet-v0.1.0
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Kevin Peckham
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,169 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @barmark/lyricsheet
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Export a [barmark](https://barmark.dev) chord chart as a lyric sheet: chords over the words, with the song's title, credits, key, time and tempo, in the text format [ChordPro](https://www.chordpro.org) reads, so any ChordPro reader can show, print or transpose it. It says what ChordPro could not carry, and with `diagrams: "guitar"` it writes a guitar shape for every chord (a `{define}` line), from `@barmark/fretboard`.
|
|
4
|
+
|
|
5
|
+
```sh
|
|
6
|
+
npm install @barmark/lyricsheet
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
It needs `barmark`, which reads the chart, and `@barmark/fretboard`, which finds the shapes. ChordPro is a separate project: this package only writes text for it and does not include or call it.
|
|
10
|
+
|
|
11
|
+
## API
|
|
12
|
+
|
|
13
|
+
```ts
|
|
14
|
+
import { exportLyricsheet } from "@barmark/lyricsheet";
|
|
15
|
+
|
|
16
|
+
const r = exportLyricsheet(chartText, { part: "Vocals", diagrams: "guitar" });
|
|
17
|
+
if (r.ok) save("song.cho", r.text);
|
|
18
|
+
else console.error(r.diagnostics);
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
```ts
|
|
22
|
+
function exportLyricsheet(chart: string, options?: LyricsheetOptions): LyricsheetResult;
|
|
23
|
+
const VERSION: string; // the package's version
|
|
24
|
+
|
|
25
|
+
type LyricsheetOptions = {
|
|
26
|
+
/** Write this part's lines: the part's label, as `extractPart` takes it. */
|
|
27
|
+
part?: string;
|
|
28
|
+
/** The title, when the chart has none. */
|
|
29
|
+
title?: string;
|
|
30
|
+
/** Add guitar chord diagrams: a `{define}` for every chord the sheet writes. */
|
|
31
|
+
diagrams?: "guitar";
|
|
32
|
+
};
|
|
33
|
+
|
|
34
|
+
type LyricsheetResult =
|
|
35
|
+
| { ok: true; text: string; diagnostics: ChartDiagnostic[]; losses: LyricsheetLoss[] }
|
|
36
|
+
| { ok: false; diagnostics: ChartDiagnostic[] };
|
|
37
|
+
|
|
38
|
+
type LyricsheetLoss = {
|
|
39
|
+
code: LyricsheetLossCode; // the table below
|
|
40
|
+
message: string;
|
|
41
|
+
bar?: number; // the played bar's position, as `PlayedBar.index`
|
|
42
|
+
written?: number; // that bar's written number (0 is the pickup)
|
|
43
|
+
};
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
`exportLyricsheet` never throws, on any chart or under Node or Bun. A chart with an error, an unknown `part` or no bars returns `{ ok: false, diagnostics }` and no text; with `part`, an error anywhere in the chart refuses too, since the words come from the whole chart (the singer's line), and the diagnostics are the whole chart's. Otherwise `text` is the sheet (one final newline, no tab, no control character, no trailing space), `diagnostics` the whole chart's warnings, each once, in line order, and `losses` what the sheet could not carry. With no `part`, the part written is the first declared one that writes a chord symbol, with the words the singer sings.
|
|
47
|
+
|
|
48
|
+
The [`barmark` command](https://www.npmjs.com/package/@barmark/cli) does the same from a terminal: `barmark export --lyricsheet chart.md --out chart.cho` (with `--part` and `--diagrams guitar`; `-` reads the chart from stdin).
|
|
49
|
+
|
|
50
|
+
## An example
|
|
51
|
+
|
|
52
|
+
```
|
|
53
|
+
# Ferry Lights
|
|
54
|
+
composer: Our Band
|
|
55
|
+
key: G, time: 4/4, tempo: 96
|
|
56
|
+
|
|
57
|
+
## Verse
|
|
58
|
+
| G | Cm | G | D |
|
|
59
|
+
lyrics: | Down / by the | riv- er | wait- ing | / |
|
|
60
|
+
|
|
61
|
+
## Bridge
|
|
62
|
+
| Em | C | G D | G |
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
The sheet:
|
|
66
|
+
|
|
67
|
+
```
|
|
68
|
+
{title: Ferry Lights}
|
|
69
|
+
{composer: Our Band}
|
|
70
|
+
{key: G}
|
|
71
|
+
{time: 4/4}
|
|
72
|
+
{tempo: 96}
|
|
73
|
+
|
|
74
|
+
{start_of_verse: label="Verse"}
|
|
75
|
+
[G]Down by the [Cm]river [G]waiting [D]
|
|
76
|
+
{end_of_verse}
|
|
77
|
+
|
|
78
|
+
{start_of_grid: label="Bridge" shape="1+4x4+1"}
|
|
79
|
+
| Em . . . | C . . . | G . D . | G . . . |
|
|
80
|
+
{end_of_grid}
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
With `diagrams: "guitar"`, the same sheet has a block of defines between the header and the first section:
|
|
84
|
+
|
|
85
|
+
```
|
|
86
|
+
{title: Ferry Lights}
|
|
87
|
+
{composer: Our Band}
|
|
88
|
+
{key: G}
|
|
89
|
+
{time: 4/4}
|
|
90
|
+
{tempo: 96}
|
|
91
|
+
|
|
92
|
+
{define: G base-fret 1 frets 3 2 0 0 0 3}
|
|
93
|
+
{define: Cm base-fret 3 frets x 1 3 3 2 1}
|
|
94
|
+
{define: D base-fret 1 frets x x 0 2 3 2}
|
|
95
|
+
{define: Em base-fret 1 frets 0 2 2 0 0 0}
|
|
96
|
+
{define: C base-fret 1 frets x 3 2 0 1 0}
|
|
97
|
+
|
|
98
|
+
{start_of_verse: label="Verse"}
|
|
99
|
+
[G]Down by the [Cm]river [G]waiting [D]
|
|
100
|
+
{end_of_verse}
|
|
101
|
+
|
|
102
|
+
{start_of_grid: label="Bridge" shape="1+4x4+1"}
|
|
103
|
+
| Em . . . | C . . . | G . D . | G . . . |
|
|
104
|
+
{end_of_grid}
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
## Guitar diagrams
|
|
108
|
+
|
|
109
|
+
With `diagrams: "guitar"` the sheet defines every chord name its body writes (in lyric lines and in grid cells), once each, in the order the sheet first writes them, in a block after the header's directives and before the first section. A define is `{define: Am base-fret 1 frets x 0 2 2 1 0}`: frets from the lowest string, `x` a muted string, `0` an open one, every other fret counted from `base-fret`. A diagram is four frets tall, so a shape that reaches the fifth fret starts at its lowest fretted one (`Cm` is `base-fret 3 frets x 1 3 3 2 1`). Barres are not written.
|
|
110
|
+
|
|
111
|
+
- ChordPro keeps one shape per name. A voicing written after a chord (`Cmaj7{E3 G3 B3}`) is that name's shape when every use of the name in the sheet writes the same voicing and a hand can play it; otherwise the name's own shape is written, and the voicing is a `voicing` loss.
|
|
112
|
+
- A chord with no playable shape gets no define and one `no-shape` loss naming it. An altered chord (`C7alt`) is defined as a shell and one `shell-shape` loss says its altered tones are not in the shape.
|
|
113
|
+
- `N.C.`, `?`, stops, note sets and fermatas are annotations, not chords, and have no define.
|
|
114
|
+
- The chart's chord names are the ones defined, as the sheet writes them (`Am7b5` for `Am7(b5)`).
|
|
115
|
+
|
|
116
|
+
## What it writes
|
|
117
|
+
|
|
118
|
+
Each section that sings words is a ChordPro lyric environment (`{start_of_verse}`, `{start_of_chorus}` or `{start_of_bridge}`, by the heading's first word; the label is the heading as written), in the order the chart plays: a repeat whose passes sing verses 1 and 2 is written twice (a repeat singing the same words again stays in one environment, its lines written again), a `D.S.` is unfolded, and a replayed chorus that sings what the chorus before it sang is `{chorus}`. Each written bar line is one lyric line, each chord written before the syllable it lands on (`[C]riv`), and a chord that lands on no syllable standing alone in its place (`waiting [D] for`). `N.C.`, a stop, `?`, a note set, words on a bar, a rehearsal mark and a fermata are annotations (`[*N.C.]`), printed as text and never read as chords. Key, time and tempo changes are written where they happen, each with a comment a reader sees (`{comment: Key: D}`); a rit., an accel., a swing feel and text lines are comments. A sheet always has a title line: the chart's title, else `title`, else `{title: }`. A lyric sheet keeps the order of chords and words, not their timing: where in its bar a chord falls is not written.
|
|
119
|
+
|
|
120
|
+
Each section with no words is a ChordPro grid, the one ChordPro construct with bars: `{start_of_grid: label="Intro" shape="1+4x4+1"}`, one grid line per written bar line, a cell per beat of the bar's own meter (a 6/8 bar has two, its beat the dotted quarter), and a margin cell on each side. In a cell, `.` holds the chord before, `/` plays the same chord again, chords that share a beat are joined by `~` (`C~G`), and `%` repeats the bar before where the chart wrote `%` and that bar is the measure before it in the line, in the same meter. `N.C.`, `*Stop`, `*?` and a note set's notes (`*C,E,G`) are cells printed as text; a fermata is a measure of its own, `*…`; words on a bar are right-margin text (in double quotes when they read as a count, `"x3"`) and a rehearsal mark left-margin text (`@B`) at the start of a line of its own, unless its line has `x N` (then it is written at the line's start). A section played straight through keeps its repeat signs (`|:`, `:|`, voltas `|1` and `|2`, and `x3` in the right margin); one cut short by a jump or `->`, or repeated by its heading, is written bar by bar as played, and an open repeat is followed by `{comment: repeat ad lib.}` inside the grid. The grid's shape is its widest line's, so each section occurrence is one grid. No line ends in a backslash (ChordPro would join the next line to it): a final `\` is written `/`.
|
|
121
|
+
|
|
122
|
+
## What is not a loss
|
|
123
|
+
|
|
124
|
+
A lyric sheet keeps the order of chords and words, not their timing: a chord is written before the syllable it lands on, and where in its bar it falls, how long it lasts and the rhythm of the words are not written. A grid keeps a cell for each beat. That is the form of a lyric sheet, not a loss, and is not reported.
|
|
125
|
+
|
|
126
|
+
## Losses
|
|
127
|
+
|
|
128
|
+
Each loss is reported once per code, at its lowest bar, naming the bars (`(3 bars: 2, 5, 9)`). `no-shape` and `shell-shape` name no bar: they are about a chord name, wherever it is written.
|
|
129
|
+
|
|
130
|
+
| Code | What is lost, and why |
|
|
131
|
+
|---|---|
|
|
132
|
+
| `key-mode` | A church mode other than ionian and aeolian: ChordPro's `{key}` names a major or minor key only. |
|
|
133
|
+
| `other-parts` | Parts other than the one written: ChordPro has one chord line per lyric line. |
|
|
134
|
+
| `other-lines` | Only the part's chords and the sung words are written: its other lines (a melody's notes, a second staff) are not. |
|
|
135
|
+
| `stacked-verses` | Verses stacked on the same bars (not one verse per pass of a repeat) are written one pass per verse, each with its chords: ChordPro has no stacking. |
|
|
136
|
+
| `chord-moved` | A chord between two syllables of one word is written before the word's next syllable, since standing alone would split the word. |
|
|
137
|
+
| `text-changed` | Titles, labels, lyrics, words and text holding `[`, `]`, `{` or `}`, or a `<` with a `>` after it anywhere on the written line, even in another syllable (written as parentheses), or a lyric line starting with `#` (written after a space): ChordPro has no escape, and would read them as chords, directives, markup or a comment. A `<` or `>` alone stays. Braces in a title or credit (written as spaces). Also a tab or any other control character (written as a space: ChordPro ends a line at a carriage return), a Unicode noncharacter such as U+FFFF (a space: ChordPro would then read the whole sheet as Latin-1), a backslash ending a line (written `/`), a heading's backslash-n (a word joiner, drawn as nothing, keeps the label on one line), a backslash before a `u` anywhere (a word joiner after it: ChordPro reads `\u007b` and `\u{7b}` as the character they name, on every line, before anything else) and grid margin words that read as a count (quoted). |
|
|
138
|
+
| `chord-names` | A chord name ChordPro's chord parser does not know (for example `F#m(b6)`), written as barmark spells it; readers may show it as text. With `diagrams: "guitar"` it is reported only when it has no shape: a name the sheet defines is drawn from its definition. |
|
|
139
|
+
| `note-sets` | A note set, written as its notes' names as text (joined by commas in a grid cell), not a chord; its octaves and root mark are lost. |
|
|
140
|
+
| `voicing` | A voicing's exact notes: only the chord's name is written. With `diagrams: "guitar"`, a voicing every use of its chord writes, and a hand can play, is the chord's diagram and not a loss; otherwise the diagram is the chord's own shape, since ChordPro keeps one shape per name. |
|
|
141
|
+
| `marks` | Pushes, accents, hits and pedal marks: the chord is written unmarked. |
|
|
142
|
+
| `bar-meter` | A one-bar meter: lyric lines do not show a bar's own meter. |
|
|
143
|
+
| `mark-moved` | A rehearsal mark inside a grid line with `x N`, written at the line's start: the count is the whole line's, so the line is not split at the mark. |
|
|
144
|
+
| `fermata` | A fermata, written as the annotation `*…` (ChordPro has none): a reader sees an ellipsis over the words, or in a grid's cell, not a fermata sign. |
|
|
145
|
+
| `no-shape` | With `diagrams: "guitar"`: a chord with no playable guitar shape (no shape within one hand's limits sounds the chord: a span of at most three frets, four fingers, frets 0 to 15, at least three strings, no muted string inside, the bass the lowest note; see `@barmark/fretboard`'s "The limits"), so no diagram is written for it. Listed by name, ten at most. |
|
|
146
|
+
| `shell-shape` | With `diagrams: "guitar"`: an altered chord (`7alt`) has only a shell for a shape, its root, third and flat seventh: its altered tones are not in the diagram. Listed by name. |
|
|
147
|
+
|
|
148
|
+
## Known gaps
|
|
149
|
+
|
|
150
|
+
ChordPro's own chord parser rejects some chord names barmark reads. The export writes such a chord in another spelling barmark reads as the same chord when the parser takes one (`C7(b9)` as `C7b9`, `C(9)` as `Cadd9`, an alteration after an extension without its parentheses) and otherwise as barmark spells it (`C(6)`, `F#m(b6)`, `Cb`): a gap. A reader may show a gap as text, and reports it as a `chord-names` loss. With `diagrams: "guitar"` each gap that has a shape is defined, and a defined name draws as a diagram, so it is no longer a loss.
|
|
151
|
+
|
|
152
|
+
## Known limits
|
|
153
|
+
|
|
154
|
+
- Two long chord names sharing one grid cell (`Cmaj7~Dm7b5`) overprint each other in ChordPro's own renderer, since every cell has the same width.
|
|
155
|
+
- Verses stacked on the same bars are written one pass per verse, each with its chords (the `stacked-verses` loss): ChordPro has no stacking.
|
|
156
|
+
- A section repeated by its heading's count is written pass by pass, not as a repeat.
|
|
157
|
+
- A sheet writes one part's chords; the others are left out (`other-parts`).
|
|
158
|
+
|
|
159
|
+
## How it is checked
|
|
160
|
+
|
|
161
|
+
- Golden files: every fixture chart under `tests/fixtures` has the sheet the export must write for it, byte for byte, with diagrams for the four charts that have one (`defines`, `shenandoah`, `morning-song`, `spellings`).
|
|
162
|
+
- Injection: for every place chart text reaches the sheet (a syllable, the title and credits, a heading, words, a text line, the `title` option), a chart that spells a directive, a chord or a grid bar with escapes, in every spelling ChordPro unescapes, writes a sheet that a reader unescaping as ChordPro does reads with nothing the chart did not play; and the `injection` golden, through ChordPro's own tool, prints its escapes as written under its own title.
|
|
163
|
+
- A played yardstick: a test-only reader reads each sheet back into the chords and words in play order, and compares them with what the chart plays, so a sheet that lost a chord or a word fails.
|
|
164
|
+
- ChordPro's own tool, on the maintainer's machine only: every golden sheet is run through ChordPro's reference `chordpro` with `--strict` (`bun scripts/chordpro-check.ts`), and the warnings it may give are exactly those the chart's gaps and key predict.
|
|
165
|
+
- Scale tests (a 1,000-bar chart exports in time linear in its length, the define block's time on 20,000 distinct names against 5,000, and a run of the built package under Node on 140,000 names and 200,000 text lines, which pass under Bun even where Node throws) and a test that walks the whole corpus.
|
|
166
|
+
|
|
167
|
+
## License
|
|
168
|
+
|
|
169
|
+
MIT
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A grid bar's cells (spec 4.3, the grid column): one per beat of the
|
|
3
|
+
* bar's own meter, as `beatsOf` counts beats. So a 4/4 bar has four cells,
|
|
4
|
+
* a `[2/4]` bar or a pickup of two beats two, and 6/8, 9/8 and 12/8, whose
|
|
5
|
+
* beat is the dotted quarter in barmark's reading, two, three and four:
|
|
6
|
+
* each cell then holds three eighths.
|
|
7
|
+
*
|
|
8
|
+
* A slot or group member that attacks on a beat is that beat's cell; ones
|
|
9
|
+
* that attack between beats share their beat's cell with `~`, in time
|
|
10
|
+
* order (`C~G`), after a `.` when nothing attacks on the beat itself
|
|
11
|
+
* (`.~G`). A beat on which nothing attacks is `.` (a hold `/` in barmark).
|
|
12
|
+
* A name that attacks again in its bar is `/` (ChordPro: play here), when
|
|
13
|
+
* it is a cell's only attack: the reference's PDF writer dies on a `/`
|
|
14
|
+
* inside a `~` cell (measured 2026-11-19), so there the name is written
|
|
15
|
+
* again. What a slot writes, and its losses, is the lyric lines' rule,
|
|
16
|
+
* with `N.C.` as a cell of its own and a note set's notes joined by commas,
|
|
17
|
+
* since a space ends a cell (a no-break space does too).
|
|
18
|
+
*/
|
|
19
|
+
import { type PlayedBar } from "barmark";
|
|
20
|
+
import type { Out } from "./types.js";
|
|
21
|
+
/** A bar's cells, or `%` and its other beats held when the chart wrote `%` there. */
|
|
22
|
+
export declare function barCells(bar: PlayedBar, simile: boolean, out: Out): string[];
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A grid bar's cells (spec 4.3, the grid column): one per beat of the
|
|
3
|
+
* bar's own meter, as `beatsOf` counts beats. So a 4/4 bar has four cells,
|
|
4
|
+
* a `[2/4]` bar or a pickup of two beats two, and 6/8, 9/8 and 12/8, whose
|
|
5
|
+
* beat is the dotted quarter in barmark's reading, two, three and four:
|
|
6
|
+
* each cell then holds three eighths.
|
|
7
|
+
*
|
|
8
|
+
* A slot or group member that attacks on a beat is that beat's cell; ones
|
|
9
|
+
* that attack between beats share their beat's cell with `~`, in time
|
|
10
|
+
* order (`C~G`), after a `.` when nothing attacks on the beat itself
|
|
11
|
+
* (`.~G`). A beat on which nothing attacks is `.` (a hold `/` in barmark).
|
|
12
|
+
* A name that attacks again in its bar is `/` (ChordPro: play here), when
|
|
13
|
+
* it is a cell's only attack: the reference's PDF writer dies on a `/`
|
|
14
|
+
* inside a `~` cell (measured 2026-11-19), so there the name is written
|
|
15
|
+
* again. What a slot writes, and its losses, is the lyric lines' rule,
|
|
16
|
+
* with `N.C.` as a cell of its own and a note set's notes joined by commas,
|
|
17
|
+
* since a space ends a cell (a no-break space does too).
|
|
18
|
+
*/
|
|
19
|
+
import { beatsOf } from "barmark";
|
|
20
|
+
import { membersAt, slotText } from "./lyrics.js";
|
|
21
|
+
/** A slot's text as a grid cell writes it: `N.C.` bare; a note set's notes joined by commas. */
|
|
22
|
+
function cellText(text) {
|
|
23
|
+
if (text === "*N.C.")
|
|
24
|
+
return "N.C.";
|
|
25
|
+
return text.startsWith("*") ? text.replace(/ /g, ",") : text;
|
|
26
|
+
}
|
|
27
|
+
/** Every slot's attack in the bar, in time order; holds and a repeated N.C. or stop attack nothing. */
|
|
28
|
+
function attacksOf(bar, beats, out) {
|
|
29
|
+
const each = beats / Math.max(1, bar.slots.length);
|
|
30
|
+
const st = { last: null };
|
|
31
|
+
return bar.slots.flatMap((slot, k) => membersAt(slot, k * each, each).flatMap((m) => {
|
|
32
|
+
const text = slotText(m.slot, st, bar, out);
|
|
33
|
+
return text === null ? [] : [{ beat: m.at, text: cellText(text) }];
|
|
34
|
+
}));
|
|
35
|
+
}
|
|
36
|
+
/** Which beat a time in beats falls in, robust to the float sums of thirds. */
|
|
37
|
+
const beatOf = (beat) => Math.floor(beat + 1e-9);
|
|
38
|
+
/** One beat's cell, given its attacks and the attack before them in the bar. */
|
|
39
|
+
function cellOf(k, here, before) {
|
|
40
|
+
const [first] = here;
|
|
41
|
+
if (!first)
|
|
42
|
+
return ".";
|
|
43
|
+
const texts = here.map((a) => a.text);
|
|
44
|
+
if (first.beat > k + 1e-9)
|
|
45
|
+
return [".", ...texts].join("~");
|
|
46
|
+
const again = here.length === 1 && !first.text.startsWith("*") && first.text !== "N.C.";
|
|
47
|
+
return again && before?.text === first.text ? "/" : texts.join("~");
|
|
48
|
+
}
|
|
49
|
+
/** A bar's cells, or `%` and its other beats held when the chart wrote `%` there. */
|
|
50
|
+
export function barCells(bar, simile, out) {
|
|
51
|
+
const beats = beatsOf(bar.meter);
|
|
52
|
+
if (simile)
|
|
53
|
+
return ["%", ...Array.from({ length: beats - 1 }, () => ".")];
|
|
54
|
+
const attacks = attacksOf(bar, beats, out);
|
|
55
|
+
const cells = [];
|
|
56
|
+
let i = 0;
|
|
57
|
+
for (let k = 0; k < beats; k++) {
|
|
58
|
+
const from = i;
|
|
59
|
+
while (i < attacks.length && beatOf(attacks[i]?.beat ?? 0) <= k)
|
|
60
|
+
i++;
|
|
61
|
+
cells.push(cellOf(k, attacks.slice(from, i), attacks[from - 1]));
|
|
62
|
+
}
|
|
63
|
+
return cells;
|
|
64
|
+
}
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What changes between one played bar and the next, written where it
|
|
3
|
+
* happens (spec 4.6): ChordPro applies a key or time "from where it was
|
|
4
|
+
* specified". The reference prints nothing for a `{key}`, `{time}` or
|
|
5
|
+
* `{tempo}` inside a song, so each mid-chart change is also a comment a
|
|
6
|
+
* reader sees, on the line before it (spec 4.6, amended 2026-11-18).
|
|
7
|
+
*/
|
|
8
|
+
import type { PlayedBar } from "barmark";
|
|
9
|
+
import type { Out } from "./types.js";
|
|
10
|
+
/**
|
|
11
|
+
* The lines a bar needs written before it, given the bar played before
|
|
12
|
+
* (none at the chart's start): key, time and tempo changes, each with its
|
|
13
|
+
* comment; a rit., an accel., `a tempo` and a feel as comments. The grid
|
|
14
|
+
* writer calls it as the lyric writer does, once per written line.
|
|
15
|
+
*/
|
|
16
|
+
export declare function changeLines(prev: PlayedBar | undefined, bar: PlayedBar, first: PlayedBar, out: Out): string[];
|
|
17
|
+
/** A text line as `{comment: …}` (spec 4.6), its markup changed and reported. */
|
|
18
|
+
export declare function comment(text: string, bar: PlayedBar | undefined, out: Out): string;
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
import { pushAll } from "./lists.js";
|
|
2
|
+
import { directive, keyText } from "./meta.js";
|
|
3
|
+
import { plain, textChanged } from "./text.js";
|
|
4
|
+
const stateOf = (bar) => {
|
|
5
|
+
const t = bar.time ?? bar.meter;
|
|
6
|
+
return { ...bar, time: `${t.n}/${t.d}` };
|
|
7
|
+
};
|
|
8
|
+
/** What the header has written before the first bar: its key, time and tempo, a straight feel. */
|
|
9
|
+
function opening(first) {
|
|
10
|
+
const { swingPercent: _, ...rest } = stateOf(first);
|
|
11
|
+
return { ...rest, tempoChange: null, feel: "straight" };
|
|
12
|
+
}
|
|
13
|
+
/** A mid-chart change: a comment a reader sees (`Key: D`), then the directive itself. */
|
|
14
|
+
const shown = (name, title, value) => [
|
|
15
|
+
directive("comment", `${title}: ${value}`),
|
|
16
|
+
directive(name, value),
|
|
17
|
+
];
|
|
18
|
+
/** The key as `{key}`, a mode it cannot name being a loss. */
|
|
19
|
+
function keyLines(from, to, bar, out) {
|
|
20
|
+
const same = from.key?.tonic === to.key?.tonic && from.key?.mode === to.key?.mode;
|
|
21
|
+
if (!to.key || same)
|
|
22
|
+
return [];
|
|
23
|
+
const text = keyText(to.key);
|
|
24
|
+
if (text !== null)
|
|
25
|
+
return shown("key", "Key", text);
|
|
26
|
+
out.losses.add("key-mode", `ChordPro's {key} cannot name the mode ${to.key.mode}, so it is left out`, bar);
|
|
27
|
+
return [];
|
|
28
|
+
}
|
|
29
|
+
/** A gradual change as it starts: `rit.`, `accel. to 140`. */
|
|
30
|
+
function gradualText(from, to) {
|
|
31
|
+
const a = from.tempoChange;
|
|
32
|
+
const b = to.tempoChange;
|
|
33
|
+
if (!b || (a?.kind === b.kind && a.to === b.to))
|
|
34
|
+
return null;
|
|
35
|
+
return `${b.kind === "rit" ? "rit." : "accel."}${b.to === null ? "" : ` to ${b.to}`}`;
|
|
36
|
+
}
|
|
37
|
+
/** A gradual change ending: `a tempo` when the tempo goes back, nothing when a new tempo is written. */
|
|
38
|
+
const endText = (from, to) => from.tempoChange && !to.tempoChange && from.tempo === to.tempo ? "a tempo" : null;
|
|
39
|
+
/** The feel, when it changes: swing, shuffle or swing 16 with any amount, or straight again. */
|
|
40
|
+
function feelText(from, to) {
|
|
41
|
+
if (from.feel === to.feel && from.swingPercent === to.swingPercent)
|
|
42
|
+
return null;
|
|
43
|
+
return to.swingPercent === undefined ? to.feel : `${to.feel} ${to.swingPercent}%`;
|
|
44
|
+
}
|
|
45
|
+
/**
|
|
46
|
+
* The lines a bar needs written before it, given the bar played before
|
|
47
|
+
* (none at the chart's start): key, time and tempo changes, each with its
|
|
48
|
+
* comment; a rit., an accel., `a tempo` and a feel as comments. The grid
|
|
49
|
+
* writer calls it as the lyric writer does, once per written line.
|
|
50
|
+
*/
|
|
51
|
+
export function changeLines(prev, bar, first, out) {
|
|
52
|
+
const from = prev ? stateOf(prev) : opening(first);
|
|
53
|
+
const to = stateOf(bar);
|
|
54
|
+
const lines = keyLines(from, to, bar, out);
|
|
55
|
+
if (from.time !== to.time)
|
|
56
|
+
pushAll(lines, shown("time", "Time", to.time));
|
|
57
|
+
if (to.tempo !== null && from.tempo !== to.tempo)
|
|
58
|
+
pushAll(lines, shown("tempo", "Tempo", String(to.tempo)));
|
|
59
|
+
for (const text of [gradualText(from, to) ?? endText(from, to), feelText(from, to)])
|
|
60
|
+
if (text !== null)
|
|
61
|
+
lines.push(directive("comment", text));
|
|
62
|
+
return lines;
|
|
63
|
+
}
|
|
64
|
+
/** A text line as `{comment: …}` (spec 4.6), its markup changed and reported. */
|
|
65
|
+
export function comment(text, bar, out) {
|
|
66
|
+
const written = plain(text);
|
|
67
|
+
if (written !== text)
|
|
68
|
+
textChanged(out.losses, bar);
|
|
69
|
+
return directive("comment", written);
|
|
70
|
+
}
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
import type { Out, Use } from "./types.js";
|
|
2
|
+
/**
|
|
3
|
+
* The define lines for the chords the body wrote, one per name in the
|
|
4
|
+
* order first written, and the losses of those with no (or only a shell)
|
|
5
|
+
* shape. A gap chord that is defined is no longer a `chord-names` loss.
|
|
6
|
+
*/
|
|
7
|
+
export declare function defineLines(uses: Use[], out: Out): string[];
|
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Guitar chord shapes as `{define}` lines (spec 6): with `diagrams: "guitar"`
|
|
3
|
+
* a define for every chord name the body writes, from `@barmark/fretboard`,
|
|
4
|
+
* so a reader draws the diagram. ChordPro has one shape per name, and a
|
|
5
|
+
* `{define}` placed before a name's first use quiets the reference tool's
|
|
6
|
+
* warnings about it, even for a name its own chord parser rejects (a gap).
|
|
7
|
+
*/
|
|
8
|
+
import { shapeFor } from "@barmark/fretboard";
|
|
9
|
+
import { lose } from "./lyrics.js";
|
|
10
|
+
import { directive } from "./meta.js";
|
|
11
|
+
import { isGap, spelled } from "./spell.js";
|
|
12
|
+
/** The uses grouped by the name written, in the order each name is first written. */
|
|
13
|
+
function entriesOf(uses) {
|
|
14
|
+
const entries = new Map();
|
|
15
|
+
for (const u of uses) {
|
|
16
|
+
const name = spelled(u.chord);
|
|
17
|
+
let e = entries.get(name);
|
|
18
|
+
if (!e) {
|
|
19
|
+
e = { name, chord: u.chord, voicings: new Map(), voiced: [], bars: [] };
|
|
20
|
+
entries.set(name, e);
|
|
21
|
+
}
|
|
22
|
+
e.voicings.set(u.voicing?.canonical ?? null, u.voicing);
|
|
23
|
+
e.bars.push(u.bar);
|
|
24
|
+
if (u.voicing)
|
|
25
|
+
e.voiced.push(u.bar);
|
|
26
|
+
}
|
|
27
|
+
return [...entries.values()];
|
|
28
|
+
}
|
|
29
|
+
/**
|
|
30
|
+
* The shape a name's diagram shows: the written voicing's when every use
|
|
31
|
+
* writes that one voicing and it fits a hand, else the name's own.
|
|
32
|
+
*/
|
|
33
|
+
function shapeOf(e) {
|
|
34
|
+
const [only, ...more] = [...e.voicings.values()];
|
|
35
|
+
if (only && more.length === 0) {
|
|
36
|
+
const r = shapeFor(e.chord, only);
|
|
37
|
+
if (r.ok && r.caveat === null)
|
|
38
|
+
return { shape: r.shape, voiced: true, shell: false };
|
|
39
|
+
}
|
|
40
|
+
const own = shapeFor(e.chord);
|
|
41
|
+
return own.ok ? { shape: own.shape, voiced: false, shell: own.caveat === "shell" } : null;
|
|
42
|
+
}
|
|
43
|
+
/**
|
|
44
|
+
* The `{define}` text of a shape: `base-fret` and `frets` (low string
|
|
45
|
+
* first, `x` muted, `0` open), each fret counted from `base-fret`. The
|
|
46
|
+
* diagram is four frets tall, so a shape reaching the fifth fret starts at
|
|
47
|
+
* its lowest fretted one (a shape spans at most three frets).
|
|
48
|
+
*/
|
|
49
|
+
function frets(shape) {
|
|
50
|
+
const fretted = shape.frets.filter((f) => f > 0);
|
|
51
|
+
// At most six strings: a spread of this list is small.
|
|
52
|
+
const base = Math.max(...fretted, 0) <= 4 ? 1 : Math.min(...fretted);
|
|
53
|
+
const text = shape.frets.map((f) => (f < 0 ? "x" : f === 0 ? "0" : String(f - base + 1)));
|
|
54
|
+
return { base, text: text.join(" ") };
|
|
55
|
+
}
|
|
56
|
+
/** Names as a loss message lists them: the first ten, and how many more. */
|
|
57
|
+
function listed(names) {
|
|
58
|
+
const shown = names.slice(0, 10).join(", ");
|
|
59
|
+
return names.length > 10 ? `${shown} and ${names.length - 10} more` : shown;
|
|
60
|
+
}
|
|
61
|
+
const NOT_DRAWN = "a voicing is written as its chord's name and its notes are not drawn: the chord's own shape is, when it has one (a name has one shape, and the chart's voicings of it differ, or the voicing does not fit the guitar)";
|
|
62
|
+
/** What a name's diagram does not carry: the voicing's notes (unless drawn), and a gap's name (unless defined). */
|
|
63
|
+
function report(e, got, out) {
|
|
64
|
+
if (!got?.voiced)
|
|
65
|
+
for (const bar of e.voiced)
|
|
66
|
+
out.losses.add("voicing", NOT_DRAWN, bar);
|
|
67
|
+
if (got === null && isGap(e.chord))
|
|
68
|
+
for (const bar of e.bars)
|
|
69
|
+
lose(out, "chord-names", bar);
|
|
70
|
+
}
|
|
71
|
+
/**
|
|
72
|
+
* The define lines for the chords the body wrote, one per name in the
|
|
73
|
+
* order first written, and the losses of those with no (or only a shell)
|
|
74
|
+
* shape. A gap chord that is defined is no longer a `chord-names` loss.
|
|
75
|
+
*/
|
|
76
|
+
export function defineLines(uses, out) {
|
|
77
|
+
const lines = [];
|
|
78
|
+
const bare = [];
|
|
79
|
+
const shell = [];
|
|
80
|
+
for (const e of entriesOf(uses)) {
|
|
81
|
+
const got = shapeOf(e);
|
|
82
|
+
report(e, got, out);
|
|
83
|
+
if (got === null) {
|
|
84
|
+
bare.push(e.name);
|
|
85
|
+
continue;
|
|
86
|
+
}
|
|
87
|
+
if (got.shell)
|
|
88
|
+
shell.push(e.name);
|
|
89
|
+
const { base, text } = frets(got.shape);
|
|
90
|
+
lines.push(directive("define", `${e.name} base-fret ${base} frets ${text}`));
|
|
91
|
+
}
|
|
92
|
+
if (bare.length)
|
|
93
|
+
out.losses.add("no-shape", `no guitar shape: ${listed(bare)}, so no diagram is written for ${bare.length === 1 ? "it" : "them"}`);
|
|
94
|
+
if (shell.length)
|
|
95
|
+
out.losses.add("shell-shape", `a shape that stands for an altered chord leaves its altered tones out: ${listed(shell)}`);
|
|
96
|
+
return lines;
|
|
97
|
+
}
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
import { type Context } from "./lyrics.js";
|
|
2
|
+
import type { Occurrence } from "./plan.js";
|
|
3
|
+
import type { Out } from "./types.js";
|
|
4
|
+
import { type Written } from "./written.js";
|
|
5
|
+
export type GridContext = Context & {
|
|
6
|
+
written: Written;
|
|
7
|
+
};
|
|
8
|
+
/** A section occurrence with no words as one grid (spec 4.1, 4.3, 4.5, 4.6). */
|
|
9
|
+
export declare function gridSection(o: Occurrence, out: Out, context: GridContext): void;
|