@barmark/cli 0.7.0 → 0.8.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,33 @@ package uses [semantic versioning](https://semver.org/).
6
6
 
7
7
  ## [Unreleased]
8
8
 
9
+ ## [0.8.0] - 2026-11-08
10
+
11
+ ### Added
12
+
13
+ - **`barmark export --midi <chart> --out <file.mid>`** writes a Standard
14
+ MIDI File of the chart's play order with `@barmark/midi`. `--out` is
15
+ required (a usage error without it, as is giving `--midi` and
16
+ `--musicxml` together); `--part <label>` exports one part. What MIDI
17
+ can't hold goes to stderr as `file: bar N: warning: message`; a chart
18
+ with errors writes nothing.
19
+ - **`barmark import <file.mid|.midi>`** reads a MIDI file as a chart.
20
+ Its diagnostics go to stderr as `file: bar N (track T): severity:
21
+ message`, control characters shown as U+FFFD; it exits 1 when no chart
22
+ came out. `--tracks 2,Piano` names the tracks that carry the harmony,
23
+ by number (from 1) or name; `--tracks` with a MusicXML score, or
24
+ `--part` with a MIDI file, is a usage error.
25
+ - **`--version`** lists `@barmark/midi`.
26
+
27
+ ### Changed
28
+
29
+ - **Uses** barmark 0.21.0, @barmark/render 0.17.1, @barmark/musicxml
30
+ 0.7.1, @barmark/midi 0.2.0 and, through it, @barmark/sync 0.2.1.
31
+ - `barmark export` with no format now says `give a format: --musicxml or
32
+ --midi`.
33
+ - **The npm homepage is https://www.barmark.dev**, not the package's
34
+ folder on GitHub.
35
+
9
36
  ## [0.7.0] - 2026-11-08
10
37
 
11
38
  ### Changed
@@ -242,7 +269,8 @@ The first release of the `barmark` command. Uses `barmark` 0.8.0 and
242
269
  - **The `barmark` command:** `check`, `format`, `render` and `transpose`
243
270
  for `.chart.md` files, on npm and as standalone binaries.
244
271
 
245
- [Unreleased]: https://github.com/kevinpeckham/barmark/compare/cli-v0.7.0...HEAD
272
+ [Unreleased]: https://github.com/kevinpeckham/barmark/compare/cli-v0.8.0...HEAD
273
+ [0.8.0]: https://github.com/kevinpeckham/barmark/compare/cli-v0.7.0...cli-v0.8.0
246
274
  [0.7.0]: https://github.com/kevinpeckham/barmark/compare/cli-v0.6.6...cli-v0.7.0
247
275
  [0.6.6]: https://github.com/kevinpeckham/barmark/compare/cli-v0.6.5...cli-v0.6.6
248
276
  [0.6.5]: https://github.com/kevinpeckham/barmark/compare/cli-v0.6.4...cli-v0.6.5
package/README.md CHANGED
@@ -3,8 +3,8 @@
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, and `@barmark/musicxml` for MusicXML, at exact
7
- versions, so a chart means the same thing everywhere.
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.
8
8
 
9
9
  ## Install
10
10
 
@@ -35,6 +35,8 @@ dot-folders and symlinks. `-` reads from stdin.
35
35
  barmark check songs # errors and warnings, file:line
36
36
  barmark export --musicxml song.chart.md --out song.musicxml # for MuseScore, Dorico…
37
37
  barmark import song.musicxml --out song.chart.md # or a compressed song.mxl
38
+ barmark export --midi song.chart.md --out song.mid # for a DAW or a practice player
39
+ barmark import song.mid --out song.chart.md # chords named from the notes
38
40
  barmark check --strict --format github songs # warnings fail too; PR annotations
39
41
  barmark format song.chart.md # print it in standard form
40
42
  barmark format --write songs # rewrite the files that change
@@ -66,6 +68,20 @@ one part alone, its notes as note sets. It exits 0 when a chart came out,
66
68
  even with warnings, and 1 when none did or the `.mxl` is bad. It does not
67
69
  read stdin.
68
70
 
71
+ `export --midi` writes a Standard MIDI File of the chart's play order
72
+ (chords voiced on piano, the tempo map, markers and lyrics); `--out` is
73
+ required, and `--part <label>` exports one part. What MIDI can't hold is
74
+ listed on stderr as `song.chart.md: bar 9: warning: message`, such as an
75
+ open repeat (`x ...`) played once. A chart with errors is not exported.
76
+
77
+ `import` reads a MIDI file (`.mid` or `.midi`) as a chart too, naming a
78
+ chord from the notes of the tracks that carry the harmony and turning
79
+ lyric events into lyric rows. Its messages are listed on stderr as
80
+ `song.mid: bar 12 (track 2): warning: message`. `--tracks 2,Piano`
81
+ names the harmony's tracks by number or name (ignoring case) instead of
82
+ letting the import choose. As for MusicXML, it exits 1 when no chart came
83
+ out.
84
+
69
85
  ## Exit codes
70
86
 
71
87
  | Code | Meaning |
package/dist/args.js CHANGED
@@ -20,3 +20,9 @@ export function oneOf(flag, value, allowed) {
20
20
  const list = `${allowed.slice(0, -1).join(", ")} or ${allowed.at(-1)}`;
21
21
  throw new UsageError(`--${flag} must be ${list}, not "${value}"`);
22
22
  }
23
+ /** `--semitones -2`: join a negative number to its flag, which parseArgs would read as a flag. */
24
+ export const joinNegative = (args, flag) => args.flatMap((arg, i) => arg === flag && /^-\d/.test(args[i + 1] ?? "")
25
+ ? [`${flag}=${args[i + 1]}`]
26
+ : i > 0 && args[i - 1] === flag && /^-\d/.test(arg)
27
+ ? []
28
+ : [arg]);
package/dist/export.js CHANGED
@@ -1,30 +1,59 @@
1
- /** barmark export: a chart in another format; MusicXML for now. */
1
+ /** barmark export: a chart in another format: MusicXML, or a MIDI file. */
2
2
  import { basename } from "node:path";
3
+ import { exportMidi } from "@barmark/midi";
3
4
  import { exportMusicXml } from "@barmark/musicxml";
4
5
  import { parseFlags } from "./args.js";
5
6
  import { readCharts, STDIN } from "./inputs.js";
6
7
  import { UsageError } from "./io.js";
7
- import { onlyChart, writeOutput } from "./output.js";
8
+ import { onlyChart, writeFile, writeOutput } from "./output.js";
8
9
  import { textLine } from "./report.js";
10
+ /** `file: bar N: warning: message`, as `check` prints its findings; a loss with no bar has no place. */
11
+ export function lossLine(path, loss) {
12
+ return `${path}: ${loss.bar === undefined ? "" : `bar ${loss.bar}: `}warning: ${loss.message}`;
13
+ }
14
+ const diagnosticLine = (path, d) => d.line ? textLine(path, d) : `${path}: ${d.message}`;
15
+ /** The format the flags name: exactly one; --midi writes bytes, so it needs --out. */
16
+ function formatOf(values) {
17
+ if (values.musicxml && values.midi)
18
+ throw new UsageError("give one format: --musicxml or --midi");
19
+ if (values.midi) {
20
+ if (values.out === undefined)
21
+ throw new UsageError("--midi writes a file: give --out <file.mid>");
22
+ return "midi";
23
+ }
24
+ if (values.musicxml)
25
+ return "musicxml";
26
+ throw new UsageError("give a format: --musicxml or --midi");
27
+ }
9
28
  export async function exportCommand(args, io) {
10
29
  const { values, positionals } = parseFlags(args, {
11
30
  musicxml: { type: "boolean" },
31
+ midi: { type: "boolean" },
12
32
  out: { type: "string" },
13
33
  part: { type: "string" },
14
34
  });
15
- if (!values.musicxml)
16
- throw new UsageError("give a format: --musicxml");
35
+ const format = formatOf(values);
17
36
  const { path, text } = onlyChart(await readCharts(positionals, io, { folders: false }), "export");
18
- const result = exportMusicXml(text, {
37
+ const options = {
19
38
  ...(values.part === undefined ? {} : { part: values.part }),
20
39
  ...(path === STDIN ? {} : { title: basename(path).replace(/(\.chart)?\.[^.]*$/, "") }),
21
- });
40
+ };
41
+ const result = format === "midi" ? exportMidi(text, options) : exportMusicXml(text, options);
22
42
  // As transpose does: problems to stderr, and no file written from a chart with errors.
23
43
  for (const d of result.diagnostics)
24
- io.stderr(`${d.line ? textLine(path, d) : `${path}: ${d.message}`}\n`);
25
- if (result.ok)
44
+ io.stderr(`${diagnosticLine(path, d)}\n`);
45
+ if (!result.ok) {
46
+ if (values.out !== undefined)
47
+ io.stderr(`${values.out} not written: the chart has errors\n`);
48
+ return 1;
49
+ }
50
+ if ("bytes" in result) {
51
+ for (const loss of result.losses)
52
+ io.stderr(`${lossLine(path, loss)}\n`);
53
+ // formatOf made --out required for --midi.
54
+ writeFile(values.out, result.bytes, io);
55
+ }
56
+ else
26
57
  writeOutput(result.xml, values.out, io);
27
- else if (values.out !== undefined)
28
- io.stderr(`${values.out} not written: the chart has errors\n`);
29
- return result.ok ? 0 : 1;
58
+ return 0;
30
59
  }
package/dist/help.js CHANGED
@@ -3,9 +3,9 @@ export const HELP = `Usage: barmark <command> [options]
3
3
 
4
4
  Commands:
5
5
  check <paths…> Report each chart's errors and warnings
6
- export <file> Write a chart as MusicXML (--musicxml)
6
+ export <file> Write a chart as MusicXML or MIDI (--musicxml, --midi)
7
7
  format <paths…> Print or rewrite charts in standard form
8
- import <file> Read a MusicXML score as a chart
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
10
  render <file> Write a chart as a standalone HTML page
11
11
  transpose <file> Print a chart in another key
@@ -29,13 +29,16 @@ inside them; - reads stdin.
29
29
  github: annotations on a pull request
30
30
  json: an array of { file, diagnostics }
31
31
  `,
32
- export: `Usage: barmark export --musicxml <file> [options]
32
+ export: `Usage: barmark export (--musicxml | --midi) <file> [options]
33
33
 
34
34
  The chart as MusicXML 4.0, for MuseScore, Dorico, Sibelius or Finale: one
35
- part per declared part, playing in the chart's order. A chart with errors
36
- is not exported; problems go to stderr.
35
+ part per declared part, playing in the chart's order. Or as a MIDI file
36
+ of its play order, for a DAW or a practice player; what MIDI can't hold
37
+ goes to stderr as file: bar N: warning: message. A chart with errors is
38
+ not exported; problems go to stderr.
37
39
 
38
- --musicxml Export MusicXML (the one format for now)
40
+ --musicxml Export MusicXML
41
+ --midi Export a Standard MIDI File (needs --out)
39
42
  --out <file> Write to a file instead of stdout
40
43
  --part <label> Export only this part
41
44
  `,
@@ -65,11 +68,15 @@ A standalone HTML page of the chart, with the Edwin font embedded.
65
68
 
66
69
  A MusicXML score (.musicxml, .xml or compressed .mxl; from MuseScore, Dorico, Sibelius, Finale…) as a chart.
67
70
  Chord symbols become chords; what the chart can't carry over goes to
68
- stderr as file: measure N (Part): message. Exits 0 when a chart came out,
69
- even with warnings; 1 when none did or the .mxl is bad. Does not read stdin.
71
+ stderr as file: measure N (Part): message. A MIDI file (.mid or .midi)
72
+ too: chords named from its notes, lyrics as lyric rows; its messages as
73
+ file: bar N (track T): message. Exits 0 when a chart came out, even with
74
+ warnings; 1 when none did or the file is bad. Does not read stdin.
70
75
 
71
76
  --out <file> Write to a file instead of stdout
72
- --part <name> Import one part alone, its notes as note sets
77
+ --part <name> MusicXML: import one part alone, its notes as note sets
78
+ --tracks <list> MIDI: the tracks that carry the harmony, by number
79
+ or name, comma-separated (default: chosen)
73
80
  `,
74
81
  part: `Usage: barmark part <label> <file> [options]
75
82
 
package/dist/import.js CHANGED
@@ -1,54 +1,95 @@
1
- /** barmark import: a MusicXML score (.musicxml, .xml or .mxl) as a chart. */
1
+ /** barmark import: a MusicXML score (.musicxml, .xml or .mxl) or a MIDI file (.mid or .midi) as a chart. */
2
+ import { importMidi } from "@barmark/midi";
2
3
  import { decodeXmlBytes, importMusicXml, readMxl } from "@barmark/musicxml";
3
- import { parseFlags } from "./args.js";
4
+ import { joinNegative, parseFlags } from "./args.js";
4
5
  import { readBytes } from "./inputs.js";
5
6
  import { UsageError } from "./io.js";
6
7
  import { writeOutput } from "./output.js";
7
8
  /** Control characters shown as U+FFFD: nothing from a file reaches the terminal as an escape sequence. */
8
- const printable = (text) => text.replace(/\p{Cc}/gu, "\uFFFD");
9
+ const printable = (text) => text.replace(/\p{Cc}/gu, "�");
10
+ /** `path: place: severity: message`, the place left out when there is none. */
11
+ const line = (path, where, d) => {
12
+ const place = where.filter(Boolean).join(" ");
13
+ return printable(`${path}: ${place ? `${place}: ` : ""}${d.severity}: ${d.message}`);
14
+ };
9
15
  /**
10
16
  * `file: measure N (Part): severity: message`, as `check` prints its
11
17
  * `file:line: severity: message`; each piece of the place left out when the
12
18
  * diagnostic has none, or when the message names its measures itself.
13
19
  */
14
20
  export function importLine(path, d) {
15
- const where = [
21
+ return line(path, [
16
22
  // A diagnostic with `measures` names them in its message; the message is never searched.
17
23
  d.measure === undefined || d.measures !== undefined ? "" : `measure ${d.measure}`,
18
24
  d.part === undefined ? "" : `(${d.part})`,
19
- ].filter(Boolean);
20
- const place = where.length ? `${where.join(" ")}: ` : "";
21
- return printable(`${path}: ${place}${d.severity}: ${d.message}`);
25
+ ], d);
26
+ }
27
+ /** `file: bar N (track T): severity: message`, as `importLine` prints a score's. */
28
+ export function midiLine(path, d) {
29
+ return line(path, [d.bar === undefined ? "" : `bar ${d.bar}`, d.track === undefined ? "" : `(track ${d.track})`], d);
30
+ }
31
+ /** A `--tracks` entry that looks like a number: a track number, 1-based. */
32
+ function trackNumber(entry) {
33
+ const n = Number(entry);
34
+ if (!Number.isSafeInteger(n) || n < 1)
35
+ throw new UsageError(`--tracks: "${entry}" is not a track number (they start at 1)`);
36
+ return n;
37
+ }
38
+ /** `--tracks 2,Piano`: each entry a 1-based track number, or else a track's name. */
39
+ export function tracksOf(list) {
40
+ const entries = list.split(",").map((entry) => entry.trim());
41
+ if (entries.some((entry) => entry === ""))
42
+ throw new UsageError("--tracks takes track numbers or names, separated by commas");
43
+ return entries.map((entry) => (/^[+-]?\d+$/.test(entry) ? trackNumber(entry) : entry));
22
44
  }
23
45
  /** The score's XML text: a .mxl is unpacked. Rejects with a message naming the problem. */
24
46
  async function scoreText(bytes, path) {
25
47
  return /\.mxl$/i.test(path) ? readMxl(bytes) : decodeXmlBytes(bytes);
26
48
  }
49
+ function midiImport(bytes, path, tracks) {
50
+ const result = importMidi(new Uint8Array(bytes), tracks === undefined ? {} : { tracks });
51
+ return { text: result.text, lines: result.diagnostics.map((d) => midiLine(path, d)) };
52
+ }
53
+ async function scoreImport(bytes, path, part) {
54
+ let xml;
55
+ try {
56
+ xml = await scoreText(bytes, path);
57
+ }
58
+ catch (error) {
59
+ return {
60
+ text: "",
61
+ lines: [printable(`${path}: ${error instanceof Error ? error.message : String(error)}`)],
62
+ };
63
+ }
64
+ const result = importMusicXml(xml, part === undefined ? {} : { part });
65
+ return { text: result.text, lines: result.diagnostics.map((d) => importLine(path, d)) };
66
+ }
27
67
  export async function importCommand(args, io) {
28
- const { values, positionals } = parseFlags(args, {
68
+ const { values, positionals } = parseFlags(joinNegative(args, "--tracks"), {
29
69
  out: { type: "string" },
30
70
  part: { type: "string" },
71
+ tracks: { type: "string" },
31
72
  });
32
73
  const [path, ...rest] = positionals;
33
74
  if (path === undefined)
34
75
  throw new UsageError("no file given");
35
76
  if (rest.length)
36
77
  throw new UsageError("import takes one file");
78
+ const midi = /\.midi?$/i.test(path);
79
+ if (midi && values.part !== undefined)
80
+ throw new UsageError("--part is for MusicXML; a MIDI file takes --tracks");
81
+ if (!midi && values.tracks !== undefined)
82
+ throw new UsageError("--tracks is for MIDI; a MusicXML score takes --part");
83
+ const tracks = values.tracks === undefined ? undefined : tracksOf(values.tracks);
37
84
  const bytes = readBytes(path, io);
38
- let xml;
39
- try {
40
- xml = await scoreText(bytes, path);
41
- }
42
- catch (error) {
43
- io.stderr(`${printable(`${path}: ${error instanceof Error ? error.message : String(error)}`)}\n`);
44
- return 1;
45
- }
46
- const result = importMusicXml(xml, values.part === undefined ? {} : { part: values.part });
47
- for (const d of result.diagnostics)
48
- io.stderr(`${importLine(path, d)}\n`);
85
+ const { text, lines } = midi
86
+ ? midiImport(bytes, path, tracks)
87
+ : await scoreImport(bytes, path, values.part);
88
+ for (const l of lines)
89
+ io.stderr(`${l}\n`);
49
90
  // As export does: no file written from an import that gave nothing.
50
- if (result.text === "")
91
+ if (text === "")
51
92
  return 1;
52
- writeOutput(result.text, values.out, io);
93
+ writeOutput(text, values.out, io);
53
94
  return 0;
54
95
  }
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 } = io.versions;
25
- io.stdout(`@barmark/cli ${cli} (barmark ${barmark}, @barmark/render ${render}, @barmark/musicxml ${musicxml})\n`);
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`);
26
26
  return 0;
27
27
  }
28
28
  if (name === "--help" || name === "-h") {
package/dist/node-io.js CHANGED
@@ -13,6 +13,7 @@ function versions() {
13
13
  barmark: versionAt("barmark"),
14
14
  render: versionAt("@barmark/render"),
15
15
  musicxml: versionAt("@barmark/musicxml"),
16
+ midi: versionAt("@barmark/midi"),
16
17
  };
17
18
  }
18
19
  async function readStdin() {
package/dist/output.js CHANGED
@@ -4,12 +4,15 @@ import { renameSync, rmSync, statSync, writeFileSync } from "node:fs";
4
4
  import { basename, dirname, join, resolve } from "node:path";
5
5
  import { UsageError } from "./io.js";
6
6
  export function writeOutput(text, out, io) {
7
- if (out === undefined) {
7
+ if (out === undefined)
8
8
  io.stdout(text);
9
- return;
10
- }
9
+ else
10
+ writeFile(out, text, io);
11
+ }
12
+ /** Text or bytes to the file named by --out; `Io` stays text-only, so bytes never reach stdout. */
13
+ export function writeFile(out, data, io) {
11
14
  try {
12
- writeFileSync(resolve(io.cwd, out), text);
15
+ writeFileSync(resolve(io.cwd, out), data);
13
16
  }
14
17
  catch {
15
18
  throw new UsageError(`cannot write ${out}`);
package/dist/transpose.js CHANGED
@@ -1,16 +1,10 @@
1
1
  /** barmark transpose: a chart in another key, by key name or by semitones. */
2
2
  import { transposeChart } from "barmark";
3
- import { parseFlags } from "./args.js";
3
+ import { joinNegative, parseFlags } from "./args.js";
4
4
  import { readCharts } from "./inputs.js";
5
5
  import { UsageError } from "./io.js";
6
6
  import { onlyChart, writeOutput } from "./output.js";
7
7
  import { textLine } from "./report.js";
8
- /** `--semitones -2`: join a negative number to its flag, which parseArgs would read as a flag. */
9
- const joinNegative = (args) => args.flatMap((arg, i) => arg === "--semitones" && /^-\d/.test(args[i + 1] ?? "")
10
- ? [`--semitones=${args[i + 1]}`]
11
- : i > 0 && args[i - 1] === "--semitones" && /^-\d/.test(arg)
12
- ? []
13
- : [arg]);
14
8
  function moveOf(to, semitones) {
15
9
  if (to !== undefined && semitones !== undefined)
16
10
  throw new UsageError("give --to or --semitones, not both");
@@ -23,7 +17,7 @@ function moveOf(to, semitones) {
23
17
  return { semitones: Number(semitones) };
24
18
  }
25
19
  export async function transpose(args, io) {
26
- const { values, positionals } = parseFlags(joinNegative(args), {
20
+ const { values, positionals } = parseFlags(joinNegative(args, "--semitones"), {
27
21
  to: { type: "string" },
28
22
  semitones: { type: "string" },
29
23
  out: { type: "string" },
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@barmark/cli",
3
- "version": "0.7.0",
3
+ "version": "0.8.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": {
@@ -27,7 +27,7 @@
27
27
  ],
28
28
  "author": "Kevin Peckham",
29
29
  "license": "MIT",
30
- "homepage": "https://github.com/kevinpeckham/barmark/tree/main/packages/cli#readme",
30
+ "homepage": "https://www.barmark.dev",
31
31
  "repository": {
32
32
  "type": "git",
33
33
  "url": "git+https://github.com/kevinpeckham/barmark.git",
@@ -37,9 +37,10 @@
37
37
  "url": "https://github.com/kevinpeckham/barmark/issues"
38
38
  },
39
39
  "dependencies": {
40
- "barmark": "0.20.0",
41
- "@barmark/render": "0.17.0",
42
- "@barmark/musicxml": "0.7.0"
40
+ "barmark": "0.21.0",
41
+ "@barmark/render": "0.17.1",
42
+ "@barmark/musicxml": "0.7.1",
43
+ "@barmark/midi": "0.2.0"
43
44
  },
44
45
  "scripts": {
45
46
  "build": "rm -rf dist && tsc -p tsconfig.build.json",