@barmark/cli 0.8.0 → 0.9.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 CHANGED
@@ -6,6 +6,34 @@ package uses [semantic versioning](https://semver.org/).
6
6
 
7
7
  ## [Unreleased]
8
8
 
9
+ ## [0.9.0] - 2026-11-09
10
+
11
+ ### Added
12
+
13
+ - **`barmark render --score <chart>`** writes a standalone HTML page of
14
+ the full engraved score instead of the bar grid: the drawing
15
+ `<barmark-score>` shows (`@barmark/score`'s `engraveChart`, by Verovio
16
+ in-process, now built in), themed by `--theme`. Open it in a browser and
17
+ print to PDF from there. `--width <px>` (320 to 40000, default 900) sets
18
+ the width it is engraved at; `--part <label>` engraves one part alone.
19
+ The grid's own flags (`--numerals`, `--no-bar-numbers`,
20
+ `--rehearsal-letters`, `--no-wrap`, `--diagnostics`, `--font-url`) are
21
+ usage errors with `--score` (exit 2), as is `--width` without it. A
22
+ chart that won't engrave writes nothing: `file: reason` on stderr, exit
23
+ 1. In the standalone binaries Verovio is an embedded file loaded on the
24
+ first score, so the other commands start as fast as before.
25
+ - **`--version`** lists `@barmark/score` and Verovio.
26
+ - The binaries' release carries Verovio's licence (`Verovio-LGPL-3.0.txt`,
27
+ `Verovio-GPL-3.0.txt`) beside `Edwin-OFL.txt`.
28
+
29
+ ### Changed
30
+
31
+ - **Uses** @barmark/musicxml 0.7.2 and @barmark/score 0.1.1 (with Verovio
32
+ 6.4.1). `barmark export --musicxml` writes a pickup as an implicit
33
+ measure 0, a chord's degrees hidden when its kind text spells them, no
34
+ slash style on a keyboard's staves, the description in the top part
35
+ only, `×N` over the bar it ends, and an acoustic guitar as one.
36
+
9
37
  ## [0.8.0] - 2026-11-08
10
38
 
11
39
  ### Added
@@ -269,7 +297,8 @@ The first release of the `barmark` command. Uses `barmark` 0.8.0 and
269
297
  - **The `barmark` command:** `check`, `format`, `render` and `transpose`
270
298
  for `.chart.md` files, on npm and as standalone binaries.
271
299
 
272
- [Unreleased]: https://github.com/kevinpeckham/barmark/compare/cli-v0.8.0...HEAD
300
+ [Unreleased]: https://github.com/kevinpeckham/barmark/compare/cli-v0.9.0...HEAD
301
+ [0.9.0]: https://github.com/kevinpeckham/barmark/compare/cli-v0.8.0...cli-v0.9.0
273
302
  [0.8.0]: https://github.com/kevinpeckham/barmark/compare/cli-v0.7.0...cli-v0.8.0
274
303
  [0.7.0]: https://github.com/kevinpeckham/barmark/compare/cli-v0.6.6...cli-v0.7.0
275
304
  [0.6.6]: https://github.com/kevinpeckham/barmark/compare/cli-v0.6.5...cli-v0.6.6
package/README.md CHANGED
@@ -3,8 +3,9 @@
3
3
  The `barmark` command: check, format, part, render, transpose, export and import
4
4
  [Barmark](https://www.barmark.dev) chord charts (`.chart.md` files) in a
5
5
  terminal or in CI. It runs the same `barmark` parser and `@barmark/render`
6
- renderer as barmark.dev, `@barmark/musicxml` for MusicXML and
7
- `@barmark/midi` for MIDI files, at exact versions, so a chart means the same thing everywhere.
6
+ renderer as barmark.dev, `@barmark/musicxml` for MusicXML,
7
+ `@barmark/score` (with Verovio) for full scores and `@barmark/midi` for
8
+ MIDI files, at exact versions, so a chart means the same thing everywhere.
8
9
 
9
10
  ## Install
10
11
 
@@ -43,6 +44,7 @@ barmark format --write songs # rewrite the files that change
43
44
  barmark format --check songs # list them and fail, for CI
44
45
  barmark part Bass song.chart.md # one part of a chart of several
45
46
  barmark render song.chart.md --out song.html # a standalone page, font included
47
+ barmark render --score song.chart.md --out song.html # the full engraved score
46
48
  barmark transpose song.chart.md --to E # or --semitones -2
47
49
  ```
48
50
 
@@ -51,8 +53,25 @@ takes the renderer's options as flags: `--theme auto|light|dark`,
51
53
  `--numerals nashville|roman`, `--no-bar-numbers`, `--rehearsal-letters`,
52
54
  `--no-wrap`, `--diagnostics`, `--part <label>` to draw one part, and `--font-url <url>` to link the font
53
55
  instead of embedding it. `barmark <command> --help` lists each command's
54
- flags; `barmark --version` prints the versions of the CLI and its
55
- libraries.
56
+ flags; `barmark --version` prints the versions of the CLI, its
57
+ libraries and Verovio.
58
+
59
+ `render --score` writes a standalone page of the full engraved score
60
+ instead of the bar grid: the drawing `<barmark-score>` shows, the chart
61
+ exported to MusicXML and engraved by [Verovio](https://www.verovio.org),
62
+ which the CLI carries (nothing else to install). The output is HTML: open
63
+ it in a browser, and print it to PDF from there. `--theme` colours it as
64
+ it does the grid, `--part <label>` engraves that part alone, and
65
+ `--width <px>` sets the width it is laid out for (320 to 40000; default
66
+ 900, a comfortable reading width: the page scales the score to fit the
67
+ window or the paper, so the width decides how many bars go on a line,
68
+ not how big the page is). The grid's own flags (`--numerals`,
69
+ `--no-bar-numbers`, `--rehearsal-letters`, `--no-wrap`, `--diagnostics`,
70
+ `--font-url`) are usage errors with `--score`, and `--width` is one
71
+ without it. A chart that won't engrave (one with errors, or no bars)
72
+ writes nothing: the reason goes to stderr as `song.chart.md: Line 5:
73
+ message`, and the exit code is 1. The score's text is set in Verovio's own
74
+ fonts, so Edwin is not embedded.
56
75
 
57
76
  `export --musicxml` writes MusicXML 4.0 that notation programs open and
58
77
  play in the chart's order; `--part <label>` exports one part. A chart
@@ -108,3 +127,13 @@ version turns that into a pull request you review.
108
127
  MIT. `render` embeds Edwin, which `@barmark/render` ships under the SIL
109
128
  Open Font License (`fonts/OFL.txt` there; the binaries' release carries it
110
129
  as `Edwin-OFL.txt`).
130
+
131
+ `render --score` uses [Verovio](https://github.com/rism-digital/verovio),
132
+ which is LGPL-3.0-only. From npm, Verovio is an ordinary dependency
133
+ (through `@barmark/score`), installed and loaded unchanged. The standalone
134
+ binaries bundle it unmodified, at the version this package pins; the
135
+ release carries
136
+ its licence as `Verovio-LGPL-3.0.txt` and the GPL it builds on as
137
+ `Verovio-GPL-3.0.txt`. The binaries are built from this repository's
138
+ source with `bun scripts/compile.ts`, so they can be rebuilt with another
139
+ Verovio. barmark's own code stays MIT.
package/dist/help.js CHANGED
@@ -7,7 +7,7 @@ Commands:
7
7
  format <paths…> Print or rewrite charts in standard form
8
8
  import <file> Read a MusicXML score or a MIDI file as a chart
9
9
  part <label> <file> Print one part of a chart of several
10
- render <file> Write a chart as a standalone HTML page
10
+ render <file> Write a chart as a standalone HTML page (--score: a full score)
11
11
  transpose <file> Print a chart in another key
12
12
 
13
13
  Options:
@@ -51,16 +51,24 @@ Charts in standard form. With one chart and no option, prints it.
51
51
  `,
52
52
  render: `Usage: barmark render <file> [options]
53
53
 
54
- A standalone HTML page of the chart, with the Edwin font embedded.
54
+ A standalone HTML page of the chart's bar grid, with the Edwin font
55
+ embedded. With --score, a page of the full engraved score instead
56
+ (Verovio, built in): open it in a browser, and print to PDF from there.
57
+ A chart that won't engrave writes nothing; the reason goes to stderr.
55
58
 
56
59
  --out <file> Write to a file instead of stdout
57
60
  --theme auto|light|dark Colors (default auto: follows the reader's system)
61
+ --part <label> Draw only this part
62
+ --score The full score instead of the grid
63
+ --width <px> With --score: the width to engrave at, 320 to
64
+ 40000 (default 900)
65
+
66
+ The grid only:
58
67
  --numerals nashville|roman
59
68
  Show chords as degrees of the key
60
69
  --no-bar-numbers Hide bar numbers
61
70
  --rehearsal-letters Letter each section A, B, C…
62
71
  --no-wrap Keep each row on one line
63
- --part <label> Draw only this part
64
72
  --diagnostics List the chart's problems below it
65
73
  --font-url <url> Link the font instead of embedding it
66
74
  `,
package/dist/main.js CHANGED
@@ -21,8 +21,8 @@ export const COMMANDS = {
21
21
  export async function main(argv, io) {
22
22
  const [name, ...args] = argv;
23
23
  if (name === "--version" || name === "-v") {
24
- const { cli, barmark, render, musicxml, midi } = io.versions;
25
- io.stdout(`@barmark/cli ${cli} (barmark ${barmark}, @barmark/render ${render}, @barmark/musicxml ${musicxml}, @barmark/midi ${midi})\n`);
24
+ const { cli, barmark, render, musicxml, score, midi, verovio } = io.versions;
25
+ io.stdout(`@barmark/cli ${cli} (barmark ${barmark}, @barmark/render ${render}, @barmark/musicxml ${musicxml}, @barmark/score ${score}, @barmark/midi ${midi}, verovio ${verovio})\n`);
26
26
  return 0;
27
27
  }
28
28
  if (name === "--help" || name === "-h") {
package/dist/node-io.js CHANGED
@@ -13,7 +13,9 @@ function versions() {
13
13
  barmark: versionAt("barmark"),
14
14
  render: versionAt("@barmark/render"),
15
15
  musicxml: versionAt("@barmark/musicxml"),
16
+ score: versionAt("@barmark/score"),
16
17
  midi: versionAt("@barmark/midi"),
18
+ verovio: versionAt("verovio"),
17
19
  };
18
20
  }
19
21
  async function readStdin() {
@@ -44,6 +46,7 @@ export function processIo() {
44
46
  export function nodeIo() {
45
47
  return {
46
48
  ...processIo(),
49
+ verovio: async () => (await import("verovio/wasm")).default,
47
50
  font: () => readFileSync(fileURLToPath(import.meta.resolve("@barmark/render/fonts/Edwin-Roman.otf"))),
48
51
  versions: versions(),
49
52
  };
package/dist/render.js CHANGED
@@ -1,10 +1,15 @@
1
- /** barmark render: a chart as a standalone HTML page, with Edwin embedded unless linked. */
1
+ /**
2
+ * barmark render: a chart as a standalone HTML page: the bar grid, with Edwin
3
+ * embedded unless linked, or with --score the full engraved score.
4
+ */
2
5
  import { basename } from "node:path";
3
6
  import { renderChart } from "@barmark/render";
4
7
  import { extractPart, parseChart } from "barmark";
5
8
  import { oneOf, parseFlags } from "./args.js";
6
9
  import { readCharts } from "./inputs.js";
10
+ import { UsageError } from "./io.js";
7
11
  import { onlyChart, writeOutput } from "./output.js";
12
+ import { DEFAULT_WIDTH, MAX_WIDTH, MIN_WIDTH, scoreBody } from "./score.js";
8
13
  const THEMES = ["auto", "light", "dark"];
9
14
  const NUMERALS = ["nashville", "roman"];
10
15
  const escapeHtml = (text) => text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
@@ -22,22 +27,44 @@ ${body}
22
27
  </html>
23
28
  `;
24
29
  }
25
- export async function render(args, io) {
26
- const { values, positionals } = parseFlags(args, {
27
- out: { type: "string" },
28
- theme: { type: "string", default: "auto" },
29
- numerals: { type: "string" },
30
- "no-bar-numbers": { type: "boolean", default: false },
31
- "rehearsal-letters": { type: "boolean", default: false },
32
- "no-wrap": { type: "boolean", default: false },
33
- diagnostics: { type: "boolean", default: false },
34
- "font-url": { type: "string" },
35
- part: { type: "string" },
36
- });
30
+ const FLAGS = {
31
+ out: { type: "string" },
32
+ theme: { type: "string", default: "auto" },
33
+ numerals: { type: "string" },
34
+ "no-bar-numbers": { type: "boolean", default: false },
35
+ "rehearsal-letters": { type: "boolean", default: false },
36
+ "no-wrap": { type: "boolean", default: false },
37
+ diagnostics: { type: "boolean", default: false },
38
+ "font-url": { type: "string" },
39
+ part: { type: "string" },
40
+ score: { type: "boolean", default: false },
41
+ width: { type: "string" },
42
+ };
43
+ /** The grid's own flags: a score has no numerals, bar-number switch, letters, rows, problem list or Edwin. */
44
+ const GRID_ONLY = [
45
+ "numerals",
46
+ "no-bar-numbers",
47
+ "rehearsal-letters",
48
+ "no-wrap",
49
+ "diagnostics",
50
+ "font-url",
51
+ ];
52
+ /** The engraving width --width gives, refusing what Verovio cannot lay out. */
53
+ function widthOf(value) {
54
+ if (value === undefined)
55
+ return DEFAULT_WIDTH;
56
+ const width = /^\d+$/.test(value) ? Number(value) : Number.NaN;
57
+ if (!(width >= MIN_WIDTH && width <= MAX_WIDTH))
58
+ throw new UsageError(`--width must be a whole number of pixels from ${MIN_WIDTH} to ${MAX_WIDTH}, not "${value}"`);
59
+ return width;
60
+ }
61
+ /** The flags as `renderChart`'s options. */
62
+ function gridOptions(values, theme, io) {
63
+ if (values.width !== undefined)
64
+ throw new UsageError("--width needs --score");
37
65
  const options = {
38
66
  fontUrl: values["font-url"] ?? `data:font/otf;base64,${Buffer.from(io.font()).toString("base64")}`,
39
67
  };
40
- const theme = oneOf("theme", values.theme, THEMES);
41
68
  if (theme !== "auto")
42
69
  options.theme = theme;
43
70
  if (values.numerals !== undefined)
@@ -50,15 +77,42 @@ export async function render(args, io) {
50
77
  options.wrap = false;
51
78
  if (values.diagnostics)
52
79
  options.diagnostics = true;
80
+ return options;
81
+ }
82
+ /** --score's width, refusing the grid's own flags. */
83
+ function scoreWidth(values) {
84
+ const given = GRID_ONLY.find((flag) => values[flag] !== undefined && values[flag] !== false);
85
+ if (given)
86
+ throw new UsageError(`--${given} does not apply to --score`);
87
+ return widthOf(values.width);
88
+ }
89
+ export async function render(args, io) {
90
+ const { values, positionals } = parseFlags(args, FLAGS);
91
+ const theme = oneOf("theme", values.theme, THEMES);
92
+ const options = values.score ? null : gridOptions(values, theme, io);
93
+ const width = values.score ? scoreWidth(values) : 0;
53
94
  const { path, text } = onlyChart(await readCharts(positionals, io, { folders: false }), "render");
54
- if (values.part !== undefined) {
55
- if (!extractPart(text, values.part)) {
56
- io.stderr(`${path}: no part labelled ${values.part}\n`);
57
- return 1;
58
- }
59
- options.part = values.part;
95
+ if (values.part !== undefined && !extractPart(text, values.part)) {
96
+ io.stderr(`${path}: no part labelled ${values.part}\n`);
97
+ return 1;
60
98
  }
61
99
  const title = parseChart(text).title ?? basename(path).replace(/\.chart\.md$|\.md$/, "");
62
- writeOutput(htmlDocument(title, renderChart(text, options)), values.out, io);
100
+ if (options) {
101
+ if (values.part !== undefined)
102
+ options.part = values.part;
103
+ writeOutput(htmlDocument(title, renderChart(text, options)), values.out, io);
104
+ return 0;
105
+ }
106
+ const score = await scoreBody(text, {
107
+ theme,
108
+ width,
109
+ label: title,
110
+ ...(values.part === undefined ? {} : { part: values.part }),
111
+ }, io);
112
+ if (!score.ok) {
113
+ io.stderr(`${path}: ${score.reason}\n`);
114
+ return 1;
115
+ }
116
+ writeOutput(htmlDocument(title, score.html), values.out, io);
63
117
  return 0;
64
118
  }
package/dist/score.js ADDED
@@ -0,0 +1,62 @@
1
+ /**
2
+ * barmark render --score: the chart engraved as a full score, the drawing
3
+ * `<barmark-score>` shows, by Verovio in this process (no worker). Verovio's
4
+ * module (about 7 MB) comes from `io.verovio` on the first score only, so the
5
+ * other commands never load it.
6
+ */
7
+ import { exportMusicXml } from "@barmark/musicxml";
8
+ import { stylesheet } from "@barmark/render";
9
+ import { engraveChart, engraveXml, scorePane, scoreStyles } from "@barmark/score";
10
+ /** The width a score is engraved at unless --width says otherwise, in CSS pixels. */
11
+ export const DEFAULT_WIDTH = 900;
12
+ /** `@barmark/score` engraves nothing narrower; Verovio's page width (2.5 units a pixel) stops at 100000. */
13
+ export const MIN_WIDTH = 320;
14
+ export const MAX_WIDTH = 40_000;
15
+ let toolkit;
16
+ /** One toolkit for the process, its log off: Verovio would otherwise print to stdout, into the page. */
17
+ function loadToolkit(verovio) {
18
+ toolkit ??= (async () => {
19
+ const esm = await import("verovio/esm");
20
+ const module = await (await verovio())();
21
+ // Verovio's typings omit the log switch; it is exported all the same (as the score worker uses it).
22
+ const { enableLog, LOG_OFF } = esm;
23
+ enableLog(LOG_OFF, module);
24
+ return new esm.VerovioToolkit(module);
25
+ })();
26
+ return toolkit;
27
+ }
28
+ /** Why the export failed, worded as `engraveChart` words it: the first error, with its line when it has one. */
29
+ function exportReason(diagnostics) {
30
+ const first = diagnostics.find((d) => d.severity === "error") ?? diagnostics[0];
31
+ if (first === undefined)
32
+ return "the chart could not be exported";
33
+ return first.line > 0 ? `Line ${first.line}: ${first.message}` : first.message;
34
+ }
35
+ /** One part alone: its MusicXML (`@barmark/musicxml`'s `part`), engraved as `engraveChart` engraves the whole. */
36
+ function engravePart(vrv, text, part, width) {
37
+ const exported = exportMusicXml(text, { part });
38
+ if (!exported.ok)
39
+ return { ok: false, reason: exportReason(exported.diagnostics) };
40
+ try {
41
+ return { ok: true, svg: engraveXml(vrv, exported.xml, { width }).svg };
42
+ }
43
+ catch (e) {
44
+ return { ok: false, reason: e instanceof Error ? e.message : String(e) };
45
+ }
46
+ }
47
+ /** The score's markup and styles for a page body, or why the chart cannot be engraved. */
48
+ export async function scoreBody(text, options, io) {
49
+ const vrv = await loadToolkit(io.verovio);
50
+ const engraved = options.part === undefined
51
+ ? engraveChart(vrv, text, { width: options.width })
52
+ : engravePart(vrv, text, options.part, options.width);
53
+ if (!engraved.ok)
54
+ return { ok: false, reason: engraved.reason };
55
+ try {
56
+ const pane = scorePane(engraved.svg, options.theme, options.label);
57
+ return { ok: true, html: `<style>${stylesheet}${scoreStyles}</style>\n${pane}` };
58
+ }
59
+ catch (e) {
60
+ return { ok: false, reason: e instanceof Error ? e.message : String(e) };
61
+ }
62
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@barmark/cli",
3
- "version": "0.8.0",
3
+ "version": "0.9.0",
4
4
  "description": "The barmark command: check, format, render, transpose and export barmark chord charts (.chart.md) from the terminal and in CI.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -39,8 +39,10 @@
39
39
  "dependencies": {
40
40
  "barmark": "0.21.0",
41
41
  "@barmark/render": "0.17.1",
42
- "@barmark/musicxml": "0.7.1",
43
- "@barmark/midi": "0.2.0"
42
+ "@barmark/musicxml": "0.7.2",
43
+ "@barmark/midi": "0.2.0",
44
+ "@barmark/score": "0.1.1",
45
+ "verovio": "6.4.1"
44
46
  },
45
47
  "scripts": {
46
48
  "build": "rm -rf dist && tsc -p tsconfig.build.json",