@barmark/lyricsheet 0.0.0 → 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 +167 -1
- 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 +48 -1
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The bars the sheet writes (spec 4.4): one part's harmony, its first
|
|
3
|
+
* line's, and the singer's words. With `part`, that part; else the first
|
|
4
|
+
* declared part that writes a chord symbol. The words come from the whole
|
|
5
|
+
* chart, since an extracted part leaves the singer's rows out unless it
|
|
6
|
+
* is the singer (grammar 7.7).
|
|
7
|
+
*/
|
|
8
|
+
import { type ChartParse } from "barmark";
|
|
9
|
+
import type { LyricsheetOptions, Out } from "./types.js";
|
|
10
|
+
/** The parse the sheet is written from: the written part's bars, each with the singer's words. */
|
|
11
|
+
export declare function sheetOf(chart: string, parse: ChartParse, options: LyricsheetOptions, out: Out, whole?: ChartParse): ChartParse;
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The bars the sheet writes (spec 4.4): one part's harmony, its first
|
|
3
|
+
* line's, and the singer's words. With `part`, that part; else the first
|
|
4
|
+
* declared part that writes a chord symbol. The words come from the whole
|
|
5
|
+
* chart, since an extracted part leaves the singer's rows out unless it
|
|
6
|
+
* is the singer (grammar 7.7).
|
|
7
|
+
*/
|
|
8
|
+
import { extractPart, parseChart, } from "barmark";
|
|
9
|
+
const same = (a, b) => a !== undefined && b !== undefined && a.toLowerCase() === b.toLowerCase();
|
|
10
|
+
/** Whether slots hold a chord symbol (not a note set). */
|
|
11
|
+
const writesChords = (slots) => slots.some((s) => (s.kind === "group" ? s.members : [s]).some((m) => m.kind === "chord" && m.chord.kind === "chord"));
|
|
12
|
+
/** The part written by default: the first declared that writes a chord symbol, else the first (spec 4.4). */
|
|
13
|
+
function defaultPart(full) {
|
|
14
|
+
const writes = (i) => full.bars.some((b) => writesChords(b.parts?.[i]?.slots ?? []));
|
|
15
|
+
return full.parts.find((_, i) => writes(i)) ?? full.parts[0];
|
|
16
|
+
}
|
|
17
|
+
/** The part who sings the lyric rows (grammar 7.7): the first voice, else the first with syllables. */
|
|
18
|
+
const singerOf = (full) => full.parts.find((p) => p.instrument === "voice") ?? full.parts.find((p) => p.sings !== undefined);
|
|
19
|
+
/** A bar's words as its singer sings them: the singer's verses, or the chart's when no part sings. */
|
|
20
|
+
function singersLyrics(bar, singer) {
|
|
21
|
+
return (bar?.lyrics ?? []).filter((l) => !singer || !l.part || same(l.part, singer));
|
|
22
|
+
}
|
|
23
|
+
/** A bar of the written part as the sheet reads it: its first line's slots and words, the singer's lyrics. */
|
|
24
|
+
function sheetBar(bar, lyrics, first, out) {
|
|
25
|
+
const { lyrics: _, lines, ...rest } = bar;
|
|
26
|
+
const written = { ...rest, ...(lyrics.length && { lyrics }) };
|
|
27
|
+
if (!lines || first === undefined)
|
|
28
|
+
return written;
|
|
29
|
+
if (lines.some((l) => !same(l.name, first)))
|
|
30
|
+
out.losses.add("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", bar);
|
|
31
|
+
const line = lines.find((l) => same(l.name, first));
|
|
32
|
+
const { words: __, ...plain } = written;
|
|
33
|
+
return { ...plain, slots: line?.slots ?? [], ...(line?.words && { words: line.words }) };
|
|
34
|
+
}
|
|
35
|
+
/** The parse the sheet is written from: the written part's bars, each with the singer's words. */
|
|
36
|
+
export function sheetOf(chart, parse, options, out, whole) {
|
|
37
|
+
const full = options.part === undefined ? parse : (whole ?? parseChart(chart));
|
|
38
|
+
const chosen = options.part === undefined ? defaultPart(full) : undefined;
|
|
39
|
+
const harmony = chosen?.label !== undefined && full.parts.length > 1
|
|
40
|
+
? (extractPart(chart, chosen.label) ?? parse)
|
|
41
|
+
: parse;
|
|
42
|
+
if (full.parts.length > 1) {
|
|
43
|
+
const others = full.parts.filter((p) => !same(p.label, harmony.parts[0]?.label));
|
|
44
|
+
out.losses.add("other-parts", `one part's chords are written (${harmony.parts[0]?.label}); the others (${others.map((p) => p.label).join(", ")}) are left out`);
|
|
45
|
+
}
|
|
46
|
+
const first = harmony.parts[0]?.lines?.[0];
|
|
47
|
+
const singer = singerOf(full)?.label;
|
|
48
|
+
const byIndex = new Map(full.bars.map((b) => [b.index, b]));
|
|
49
|
+
const bars = harmony.bars.map((b) => sheetBar(b, singersLyrics(byIndex.get(b.index), singer), first, out));
|
|
50
|
+
return { ...harmony, bars };
|
|
51
|
+
}
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* How a chord name is written (spec 4.7): barmark's canonical spelling,
|
|
3
|
+
* except where the reference `chordpro`'s chord parser rejects it and
|
|
4
|
+
* accepts another spelling barmark reads as the same chord. A **gap** is a
|
|
5
|
+
* chord whose every such spelling the parser rejects (its quoted "Unknown
|
|
6
|
+
* chord" warning); a name it parses but has no built-in diagram for is
|
|
7
|
+
* not a gap. Measured against `chordpro` 6.101.0 on 2026-11-18 over every
|
|
8
|
+
* suffix barmark enumerates, on every root and over every bass; the rules
|
|
9
|
+
* below are that measurement in our words.
|
|
10
|
+
*
|
|
11
|
+
* No renaming across families: a chord is written as the chart wrote it
|
|
12
|
+
* (`C(6)` stays `C(6)`, a gap, though `C6` sounds the same notes).
|
|
13
|
+
*/
|
|
14
|
+
import type { ChordRecord } from "barmark";
|
|
15
|
+
/** A chord as the export writes it: canonical, or the barmark alias ChordPro readers know (spec 4.7). */
|
|
16
|
+
export declare function spelled(chord: ChordRecord): string;
|
|
17
|
+
/** Whether the reference's chord parser rejects this chord in every spelling (spec 4.7's gaps), for the losses. */
|
|
18
|
+
export declare function isGap(chord: ChordRecord): boolean;
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
/** Quality, extension and sus, as the canonical spelling writes them: `m7`, `7sus4`, `` for a major triad. */
|
|
2
|
+
const familyOf = (p) => `${p.quality}${p.extension ?? ""}${p.sus ?? ""}`;
|
|
3
|
+
/** With no tones, the parser takes every chord barmark has but these. */
|
|
4
|
+
const REJECTED_BARE = new Set(["9sus2", "9sus4", "augmaj7", "m6/9"]);
|
|
5
|
+
/**
|
|
6
|
+
* An alteration after an extension loses its parentheses (`C7b9`), a
|
|
7
|
+
* ninth's alteration first (`C7b9b5`). The parser takes these runs only,
|
|
8
|
+
* by family: on a dominant seventh any one alteration but `b6`, or `b9` or
|
|
9
|
+
* `#9` followed by another; on the others a few single ones. Its own
|
|
10
|
+
* irregular list, so a table.
|
|
11
|
+
*/
|
|
12
|
+
const RUN_ON = {
|
|
13
|
+
"7": [
|
|
14
|
+
...["b5", "#5", "b9", "#9", "#11", "b13"],
|
|
15
|
+
...["b9b5", "b9#5", "b9#9", "b9#11", "b9b13", "#9b5", "#9#5", "#9#11"],
|
|
16
|
+
],
|
|
17
|
+
"9": ["b5", "#5", "#11"],
|
|
18
|
+
"13": ["b9", "#9", "#11"],
|
|
19
|
+
maj7: ["#5", "#11"],
|
|
20
|
+
maj9: ["#11"],
|
|
21
|
+
m7: ["b5"],
|
|
22
|
+
};
|
|
23
|
+
/**
|
|
24
|
+
* One added tone, written `add` where the parser rejects its parentheses:
|
|
25
|
+
* on a major triad 2, 4, 9 or 11, on a minor triad 9, on a seventh 11 and
|
|
26
|
+
* on a ninth 6. `C6(9)` and `C9(11)` it takes as written.
|
|
27
|
+
*/
|
|
28
|
+
const ADDED = {
|
|
29
|
+
"": ["2", "4", "9", "11"],
|
|
30
|
+
m: ["9"],
|
|
31
|
+
"7": ["11"],
|
|
32
|
+
"9": ["6"],
|
|
33
|
+
};
|
|
34
|
+
const GROUPED = { "6": ["9"], "9": ["11"] };
|
|
35
|
+
/** A note whose accidental lands on a natural (`Cb`, `Fb`, `B#`, `E#`): the parser takes none, as root or bass. */
|
|
36
|
+
const landsOnNatural = (note) => note !== null && /^(Cb|Fb|B#|E#)$/.test(note);
|
|
37
|
+
/** The tones with a ninth's alteration first, as the parser wants them. */
|
|
38
|
+
const ninthFirst = (tones) => [
|
|
39
|
+
...tones.filter((t) => t.endsWith("9")),
|
|
40
|
+
...tones.filter((t) => !t.endsWith("9")),
|
|
41
|
+
];
|
|
42
|
+
/** The text after the root that the parser accepts, or null when it accepts none. */
|
|
43
|
+
function acceptedSuffix(p) {
|
|
44
|
+
const family = familyOf(p);
|
|
45
|
+
const [tone, ...more] = p.tones;
|
|
46
|
+
if (tone === undefined)
|
|
47
|
+
return REJECTED_BARE.has(family) ? null : family;
|
|
48
|
+
const run = ninthFirst(p.tones).join("");
|
|
49
|
+
if (p.tones.every((t) => /^[b#]/.test(t)) && RUN_ON[family]?.includes(run))
|
|
50
|
+
return family + run;
|
|
51
|
+
if (more.length)
|
|
52
|
+
return null;
|
|
53
|
+
if (ADDED[family]?.includes(tone))
|
|
54
|
+
return `${family}add${tone}`;
|
|
55
|
+
return GROUPED[family]?.includes(tone) ? `${family}(${tone})` : null;
|
|
56
|
+
}
|
|
57
|
+
/** The spelling the parser accepts, or null when it accepts none barmark reads as this chord. */
|
|
58
|
+
function acceptedSpelling(chord) {
|
|
59
|
+
const p = chord.parts;
|
|
60
|
+
if (!p || landsOnNatural(p.root) || landsOnNatural(p.bass))
|
|
61
|
+
return null;
|
|
62
|
+
const suffix = acceptedSuffix(p);
|
|
63
|
+
if (suffix === null)
|
|
64
|
+
return null;
|
|
65
|
+
if (p.bass === null)
|
|
66
|
+
return `${p.root}${suffix}`;
|
|
67
|
+
// The parser takes a bass under any name but one with parentheses or a slash of its own.
|
|
68
|
+
return /[(/]/.test(suffix) ? null : `${p.root}${suffix}/${p.bass}`;
|
|
69
|
+
}
|
|
70
|
+
/** A chord as the export writes it: canonical, or the barmark alias ChordPro readers know (spec 4.7). */
|
|
71
|
+
export function spelled(chord) {
|
|
72
|
+
return acceptedSpelling(chord) ?? chord.canonical;
|
|
73
|
+
}
|
|
74
|
+
/** Whether the reference's chord parser rejects this chord in every spelling (spec 4.7's gaps), for the losses. */
|
|
75
|
+
export function isGap(chord) {
|
|
76
|
+
return acceptedSpelling(chord) === null;
|
|
77
|
+
}
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Text ChordPro would read as markup (the plan's Review Focus 2). ChordPro
|
|
3
|
+
* has no escape, so what it would read as markup is written otherwise, and
|
|
4
|
+
* each line changed is one `text-changed` loss:
|
|
5
|
+
*
|
|
6
|
+
* - everywhere (titles, credits, labels, lyrics, comments): a `<` with a
|
|
7
|
+
* `>` after it opens a tag to ChordPro (measured with the reference: `a
|
|
8
|
+
* < b ->` loses `< b ->`, `<b>la</b>` prints `la`), so such a `<` is
|
|
9
|
+
* written `(` and such a `>` (one with a `<` before it) `)`; a `<` or `>`
|
|
10
|
+
* alone stays (`a < b`, `<3`, `->`, `x>y` print as written, and so does
|
|
11
|
+
* `&`);
|
|
12
|
+
* - in lyrics, words and comments, which ChordPro reads as lyric lines:
|
|
13
|
+
* `[` `]` `{` `}` are written `(` `)` `(` `)`, and a `#` that would start
|
|
14
|
+
* a line gets a space before it;
|
|
15
|
+
* - everywhere, a control character (a carriage return ends a line to
|
|
16
|
+
* ChordPro) is a space, and on every written line a backslash before a
|
|
17
|
+
* `u` gets a word joiner after it: ChordPro unescapes `\uXXXX` and
|
|
18
|
+
* `\u{…}` on every line before it reads it (`unescapable`).
|
|
19
|
+
*/
|
|
20
|
+
import type { PlayedBar } from "barmark";
|
|
21
|
+
import type { Losses } from "./losses.js";
|
|
22
|
+
/** Angle brackets that would make a tag, as parentheses; linear in the text's length. */
|
|
23
|
+
export declare function untagged(text: string): string;
|
|
24
|
+
/**
|
|
25
|
+
* Every control character (C0, DEL and C1: tab, CR, VT, NUL, NEL),
|
|
26
|
+
* U+2028/2029 and every noncharacter (U+FDD0, U+FFFF) as a space: a reader
|
|
27
|
+
* may end a line at a control character (ChordPro ends one at CR), and a
|
|
28
|
+
* noncharacter fails ChordPro's strict UTF-8 decode, after which it reads
|
|
29
|
+
* the whole sheet as Latin-1. The output rules forbid them all.
|
|
30
|
+
*/
|
|
31
|
+
export declare const spaced: (text: string) => string;
|
|
32
|
+
/** Text in a lyric line or a comment as ChordPro shows it unchanged: no brackets, braces or tags, no control character. */
|
|
33
|
+
export declare const plain: (text: string) => string;
|
|
34
|
+
/**
|
|
35
|
+
* A written line with no escape ChordPro would unescape: it reads
|
|
36
|
+
* `\uXXXX`, `\u{…}` and a surrogate pair, `u` in either case, as the
|
|
37
|
+
* character, on every line before anything else, even after another
|
|
38
|
+
* backslash (measured 2026-11-19: `\\u007b` is read `\{`). So a word
|
|
39
|
+
* joiner (U+2060, drawn as nothing) goes after every backslash before a
|
|
40
|
+
* `u`, as `labelValue` does before an `n`; it never makes or moves a
|
|
41
|
+
* final backslash.
|
|
42
|
+
*/
|
|
43
|
+
export declare const unescapable: (line: string) => string;
|
|
44
|
+
/** A lyric line as written: a `#` that would start it (a comment to ChordPro) gets a space before it. */
|
|
45
|
+
export declare const unhashed: (line: string) => string;
|
|
46
|
+
/**
|
|
47
|
+
* A lyric or grid line as written: a final `\` becomes `/`. ChordPro joins
|
|
48
|
+
* a line ending in `\` to the next; `\\` there does the same (dropping one)
|
|
49
|
+
* and `\ ` would leave a trailing space (measured 2026-11-19).
|
|
50
|
+
*/
|
|
51
|
+
export declare const unjoined: (line: string) => string;
|
|
52
|
+
/**
|
|
53
|
+
* A heading as a quoted `label="…"` value shows it: `\` and `"` escaped.
|
|
54
|
+
* ChordPro splits a label into lines at a backslash-n left in it after
|
|
55
|
+
* unescaping, so a word joiner (U+2060, drawn as nothing) goes between
|
|
56
|
+
* such a backslash and its `n`, and the heading stays one line.
|
|
57
|
+
*/
|
|
58
|
+
export declare const labelValue: (text: string) => string;
|
|
59
|
+
/** One `text-changed` loss for a line written differently from its text. */
|
|
60
|
+
export declare function textChanged(losses: Losses, bar?: PlayedBar): void;
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
/** Angle brackets that would make a tag, as parentheses; linear in the text's length. */
|
|
2
|
+
export function untagged(text) {
|
|
3
|
+
const firstOpen = text.indexOf("<");
|
|
4
|
+
const lastClose = text.lastIndexOf(">");
|
|
5
|
+
if (firstOpen < 0 || lastClose < firstOpen)
|
|
6
|
+
return text;
|
|
7
|
+
// UTF-16 indexes, as indexOf gives them; `<` and `>` are never half of a pair.
|
|
8
|
+
return text.replace(/[<>]/g, (c, i) => {
|
|
9
|
+
if (c === "<")
|
|
10
|
+
return i < lastClose ? "(" : c;
|
|
11
|
+
return i > firstOpen ? ")" : c;
|
|
12
|
+
});
|
|
13
|
+
}
|
|
14
|
+
/**
|
|
15
|
+
* Every control character (C0, DEL and C1: tab, CR, VT, NUL, NEL),
|
|
16
|
+
* U+2028/2029 and every noncharacter (U+FDD0, U+FFFF) as a space: a reader
|
|
17
|
+
* may end a line at a control character (ChordPro ends one at CR), and a
|
|
18
|
+
* noncharacter fails ChordPro's strict UTF-8 decode, after which it reads
|
|
19
|
+
* the whole sheet as Latin-1. The output rules forbid them all.
|
|
20
|
+
*/
|
|
21
|
+
export const spaced = (text) => text.replace(/[\p{Cc}\p{Noncharacter_Code_Point}\u2028\u2029]/gu, " ");
|
|
22
|
+
/** Text in a lyric line or a comment as ChordPro shows it unchanged: no brackets, braces or tags, no control character. */
|
|
23
|
+
export const plain = (text) => spaced(untagged(text).replace(/[[{]/g, "(").replace(/[\]}]/g, ")"));
|
|
24
|
+
/**
|
|
25
|
+
* A written line with no escape ChordPro would unescape: it reads
|
|
26
|
+
* `\uXXXX`, `\u{…}` and a surrogate pair, `u` in either case, as the
|
|
27
|
+
* character, on every line before anything else, even after another
|
|
28
|
+
* backslash (measured 2026-11-19: `\\u007b` is read `\{`). So a word
|
|
29
|
+
* joiner (U+2060, drawn as nothing) goes after every backslash before a
|
|
30
|
+
* `u`, as `labelValue` does before an `n`; it never makes or moves a
|
|
31
|
+
* final backslash.
|
|
32
|
+
*/
|
|
33
|
+
export const unescapable = (line) => line.replace(/\\(?=u)/gi, "\\\u2060");
|
|
34
|
+
/** A lyric line as written: a `#` that would start it (a comment to ChordPro) gets a space before it. */
|
|
35
|
+
export const unhashed = (line) => (line.startsWith("#") ? ` ${line}` : line);
|
|
36
|
+
/**
|
|
37
|
+
* A lyric or grid line as written: a final `\` becomes `/`. ChordPro joins
|
|
38
|
+
* a line ending in `\` to the next; `\\` there does the same (dropping one)
|
|
39
|
+
* and `\ ` would leave a trailing space (measured 2026-11-19).
|
|
40
|
+
*/
|
|
41
|
+
export const unjoined = (line) => (line.endsWith("\\") ? `${line.slice(0, -1)}/` : line);
|
|
42
|
+
/**
|
|
43
|
+
* A heading as a quoted `label="…"` value shows it: `\` and `"` escaped.
|
|
44
|
+
* ChordPro splits a label into lines at a backslash-n left in it after
|
|
45
|
+
* unescaping, so a word joiner (U+2060, drawn as nothing) goes between
|
|
46
|
+
* such a backslash and its `n`, and the heading stays one line.
|
|
47
|
+
*/
|
|
48
|
+
export const labelValue = (text) => text.replace(/\\(?=n)/g, "\\").replace(/[\\"]/g, (c) => `\\${c}`);
|
|
49
|
+
const TEXT_CHANGED = "text holding characters ChordPro reads as markup is changed: brackets, braces and tag-like <…> become parentheses (braces in a title or credit spaces), a tab or other control character a space, a # starting a lyric line gets a space before it, a backslash ending a line becomes /, a word joiner keeps a label's backslash-n on one line and a backslash-u from reading as an escape, and words in a grid's margin that read as a count are quoted";
|
|
50
|
+
/** One `text-changed` loss for a line written differently from its text. */
|
|
51
|
+
export function textChanged(losses, bar) {
|
|
52
|
+
losses.add("text-changed", TEXT_CHANGED, bar);
|
|
53
|
+
}
|
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
import type { ChartDiagnostic, ChordRecord, PlayedBar } from "barmark";
|
|
2
|
+
import type { Losses } from "./losses.js";
|
|
3
|
+
export type LyricsheetOptions = {
|
|
4
|
+
/** Write this part's lines: the part's label, as `extractPart` takes it. */
|
|
5
|
+
part?: string;
|
|
6
|
+
/** The title, when the chart has none. */
|
|
7
|
+
title?: string;
|
|
8
|
+
/** Add guitar chord diagrams. */
|
|
9
|
+
diagrams?: "guitar";
|
|
10
|
+
};
|
|
11
|
+
/** What the export could not carry. */
|
|
12
|
+
export type LyricsheetLossCode =
|
|
13
|
+
/** A church mode other than ionian and aeolian in `key:`: ChordPro's `{key}` names a major or minor key only. */
|
|
14
|
+
"key-mode"
|
|
15
|
+
/** Parts other than the one written: ChordPro has one chord line per lyric line (spec 4.4). */
|
|
16
|
+
| "other-parts"
|
|
17
|
+
/** The written part's lines other than its first (a melody, a second hand): only their words are sung (spec 4.4). */
|
|
18
|
+
| "other-lines"
|
|
19
|
+
/** Verses stacked on the same bars, written as one pass per verse: ChordPro has no stacking (spec 4.5). */
|
|
20
|
+
| "stacked-verses"
|
|
21
|
+
/** A chord between two syllables of one word, written before the word's next syllable. */
|
|
22
|
+
| "chord-moved"
|
|
23
|
+
/** Text holding characters ChordPro reads as markup (`[`, `]`, `{`, `}`, tag-like `<…>`, a leading `#`, a control character or a noncharacter, a line-ending backslash, a backslash before `u`, a label's backslash-n, margin words like a count), changed. */
|
|
24
|
+
| "text-changed"
|
|
25
|
+
/** A chord name ChordPro's chord parser does not know (spec 4.7's gaps), written as barmark spells it. */
|
|
26
|
+
| "chord-names"
|
|
27
|
+
/** A note set, written as its notes' names as text (in a grid, joined by commas): not a chord to readers, octaves and root mark lost (spec 4.3). */
|
|
28
|
+
| "note-sets"
|
|
29
|
+
/** A voicing's exact notes: only the chord's name is written (spec 4.3). */
|
|
30
|
+
| "voicing"
|
|
31
|
+
/** Pushes, accents, hits and pedal marks: the chord is written unmarked (spec 4.3). */
|
|
32
|
+
| "marks"
|
|
33
|
+
/** A one-bar meter in lyric lines, which do not show a bar's own meter; a grid does, by its cells (spec 4.3). */
|
|
34
|
+
| "bar-meter"
|
|
35
|
+
/** A fermata, written as the text `*…`: its hold has no length (spec 4.3). */
|
|
36
|
+
| "fermata"
|
|
37
|
+
/** A rehearsal mark inside a grid line with `x N`, written at the line's start: the count is the whole line's. */
|
|
38
|
+
| "mark-moved"
|
|
39
|
+
/** A chord with no playable guitar shape, so no diagram is written for it (`diagrams: "guitar"`). */
|
|
40
|
+
| "no-shape"
|
|
41
|
+
/** An altered chord's diagram is a shell: its altered tones are not in the shape (`diagrams: "guitar"`). */
|
|
42
|
+
| "shell-shape";
|
|
43
|
+
export type LyricsheetLoss = {
|
|
44
|
+
code: LyricsheetLossCode;
|
|
45
|
+
message: string;
|
|
46
|
+
/** The played bar's position, as `PlayedBar.index`. */
|
|
47
|
+
bar?: number;
|
|
48
|
+
/** The bar's written number (0 is the pickup). */
|
|
49
|
+
written?: number;
|
|
50
|
+
};
|
|
51
|
+
export type LyricsheetResult = {
|
|
52
|
+
ok: true;
|
|
53
|
+
text: string;
|
|
54
|
+
diagnostics: ChartDiagnostic[];
|
|
55
|
+
losses: LyricsheetLoss[];
|
|
56
|
+
} | {
|
|
57
|
+
ok: false;
|
|
58
|
+
diagnostics: ChartDiagnostic[];
|
|
59
|
+
};
|
|
60
|
+
/** One chord the body writes, with the voicing written after it and the bar it is in. */
|
|
61
|
+
export type Use = {
|
|
62
|
+
chord: ChordRecord;
|
|
63
|
+
voicing: ChordRecord | null;
|
|
64
|
+
bar: PlayedBar;
|
|
65
|
+
};
|
|
66
|
+
/** What every stage writes into: the lines so far and the losses so far. */
|
|
67
|
+
export type Out = {
|
|
68
|
+
lines: string[];
|
|
69
|
+
losses: Losses;
|
|
70
|
+
/** With diagrams: every chord the body writes, in order (set only then). */
|
|
71
|
+
uses?: Use[];
|
|
72
|
+
};
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The chart's written bar lines, for the grids (spec 4.5): which written
|
|
3
|
+
* cell a played bar is (so `%` is written where the chart wrote it), and
|
|
4
|
+
* whether an occurrence plays its section's written lines straight
|
|
5
|
+
* through, so its grid can keep their repeat signs.
|
|
6
|
+
*/
|
|
7
|
+
import type { ChartParse, Line, PlayedBar } from "barmark";
|
|
8
|
+
import type { Occurrence } from "./plan.js";
|
|
9
|
+
export type BarsLine = Extract<Line, {
|
|
10
|
+
kind: "bars";
|
|
11
|
+
}>;
|
|
12
|
+
export type Written = {
|
|
13
|
+
/** Each played bar line, by its line number. */
|
|
14
|
+
lines: Map<number, BarsLine>;
|
|
15
|
+
/** Each played bar line's bar cells (slots and `%`, not marks or fermatas), by its line number. */
|
|
16
|
+
bars: Map<number, BarsLine["cells"]>;
|
|
17
|
+
/** The written number of each bar line's first bar. */
|
|
18
|
+
first: Map<number, number>;
|
|
19
|
+
/** Each section's played bar lines in written order, by its heading's line (-1 before the first heading). */
|
|
20
|
+
sections: Map<number, BarsLine[]>;
|
|
21
|
+
};
|
|
22
|
+
/** The bar lines the sheet's bars are played from, and where each section's are written. */
|
|
23
|
+
export declare function writtenOf(parse: ChartParse): Written;
|
|
24
|
+
/** A played bar's place in its written line, from 0. */
|
|
25
|
+
export declare const placeOf: (w: Written, bar: PlayedBar) => number;
|
|
26
|
+
/** Whether the chart wrote `%` for this bar. */
|
|
27
|
+
export declare const writtenSimile: (w: Written, bar: PlayedBar) => boolean;
|
|
28
|
+
/** The section's written lines, when the occurrence plays them straight through (spec 4.5); else null. */
|
|
29
|
+
export declare function straightLines(o: Occurrence, w: Written): BarsLine[] | null;
|
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
import { maxOf } from "./lists.js";
|
|
2
|
+
const isBar = (c) => c.kind === "slots" || c.kind === "simile";
|
|
3
|
+
/** The bar lines the sheet's bars are played from, and where each section's are written. */
|
|
4
|
+
export function writtenOf(parse) {
|
|
5
|
+
const first = new Map();
|
|
6
|
+
for (const b of parse.bars)
|
|
7
|
+
first.set(b.line, Math.min(first.get(b.line) ?? b.written, b.written));
|
|
8
|
+
const lines = new Map();
|
|
9
|
+
const bars = new Map();
|
|
10
|
+
const sections = new Map();
|
|
11
|
+
let heading = -1;
|
|
12
|
+
for (const l of parse.lines) {
|
|
13
|
+
if (l.kind === "section")
|
|
14
|
+
heading = l.line;
|
|
15
|
+
// A part's other lines (7.6) and a part's lines in other systems are not played from.
|
|
16
|
+
if (l.kind !== "bars" || !first.has(l.line))
|
|
17
|
+
continue;
|
|
18
|
+
lines.set(l.line, l);
|
|
19
|
+
bars.set(l.line, l.cells.filter(isBar));
|
|
20
|
+
const section = sections.get(heading) ?? [];
|
|
21
|
+
section.push(l);
|
|
22
|
+
sections.set(heading, section);
|
|
23
|
+
}
|
|
24
|
+
return { lines, bars, first, sections };
|
|
25
|
+
}
|
|
26
|
+
/** A played bar's place in its written line, from 0. */
|
|
27
|
+
export const placeOf = (w, bar) => bar.written - (w.first.get(bar.line) ?? 0);
|
|
28
|
+
/** Whether the chart wrote `%` for this bar. */
|
|
29
|
+
export const writtenSimile = (w, bar) => w.bars.get(bar.line)?.[placeOf(w, bar)]?.kind === "simile";
|
|
30
|
+
/** How many times a line or a repeat's block plays: `x N`, else once (an open `x ...` plays once). */
|
|
31
|
+
const times = (repeat, otherwise = 1) => typeof repeat === "number" ? repeat : repeat === null ? otherwise : 1;
|
|
32
|
+
/** A repeat's endings from line `k`: each ending's line and the lines it continues onto. */
|
|
33
|
+
function endingsFrom(lines, k) {
|
|
34
|
+
const out = [];
|
|
35
|
+
let j = k;
|
|
36
|
+
while (lines[j]?.ending) {
|
|
37
|
+
const ending = [lines[j]];
|
|
38
|
+
j++;
|
|
39
|
+
while (lines[j] && !lines[j]?.ending && lines[j]?.continues)
|
|
40
|
+
ending.push(lines[j++]);
|
|
41
|
+
out.push(ending);
|
|
42
|
+
}
|
|
43
|
+
return out;
|
|
44
|
+
}
|
|
45
|
+
/** Plays lines, each its own `x N` times but `closer`, whose count is its repeat's. */
|
|
46
|
+
function* play(block, closer) {
|
|
47
|
+
for (const l of block)
|
|
48
|
+
for (let n = l === closer ? 1 : times(l.repeat); n > 0; n--)
|
|
49
|
+
yield l;
|
|
50
|
+
}
|
|
51
|
+
/** Where the repeat opened at line `i` ends: its `:|`, or its first ending; -1 for neither. */
|
|
52
|
+
function repeatEnd(lines, i) {
|
|
53
|
+
for (let k = i; k < lines.length; k++)
|
|
54
|
+
if (lines[k]?.closes || (k > i && lines[k]?.ending))
|
|
55
|
+
return k;
|
|
56
|
+
return -1;
|
|
57
|
+
}
|
|
58
|
+
/** The repeat from line `i` to `k`: twice or `x N`, or once per ending's pass. */
|
|
59
|
+
function* playRepeat(lines, i, k) {
|
|
60
|
+
const end = lines[k];
|
|
61
|
+
if (!end.ending) {
|
|
62
|
+
const block = lines.slice(i, k + 1);
|
|
63
|
+
for (let n = times(end.repeat, 2); n > 0; n--)
|
|
64
|
+
yield* play(block, end);
|
|
65
|
+
return;
|
|
66
|
+
}
|
|
67
|
+
const endings = endingsFrom(lines, k);
|
|
68
|
+
const passes = maxOf(endings.flatMap((e) => e[0]?.ending ?? []));
|
|
69
|
+
const body = lines.slice(i, k);
|
|
70
|
+
for (let p = 1; p <= passes; p++)
|
|
71
|
+
yield* play([...body, ...(endings.find((e) => e[0]?.ending?.includes(p)) ?? [])]);
|
|
72
|
+
}
|
|
73
|
+
/** The line after a repeat from line `i` to `k`, its endings included. */
|
|
74
|
+
function afterRepeat(lines, k) {
|
|
75
|
+
return lines[k]?.ending ? k + endingsFrom(lines, k).flat().length : k + 1;
|
|
76
|
+
}
|
|
77
|
+
/**
|
|
78
|
+
* The lines a section plays when each is played its full count (grammar
|
|
79
|
+
* 5, 5.1), one at a time: a line `x N` times; a `|: :|` twice or its
|
|
80
|
+
* `x N`; endings by pass, the bars before the first ending on every pass.
|
|
81
|
+
* A generator, so a reader stops it when it has seen enough: a section
|
|
82
|
+
* first reached after a jump is not capped by the parser, and its counts
|
|
83
|
+
* may run to billions.
|
|
84
|
+
*/
|
|
85
|
+
function* fullPlay(lines) {
|
|
86
|
+
let i = 0;
|
|
87
|
+
while (i < lines.length) {
|
|
88
|
+
const k = lines[i]?.opens ? repeatEnd(lines, i) : -1;
|
|
89
|
+
if (k < 0)
|
|
90
|
+
yield* play(lines.slice(i, ++i));
|
|
91
|
+
else {
|
|
92
|
+
yield* playRepeat(lines, i, k);
|
|
93
|
+
i = afterRepeat(lines, k);
|
|
94
|
+
}
|
|
95
|
+
}
|
|
96
|
+
}
|
|
97
|
+
/** Whether the bars are the lines' bars in order, all of them: stops at the first difference or bar past the end. */
|
|
98
|
+
function playsAs(bars, lines, w) {
|
|
99
|
+
let i = 0;
|
|
100
|
+
for (const l of lines) {
|
|
101
|
+
const count = w.bars.get(l.line)?.length ?? 0;
|
|
102
|
+
for (let place = 0; place < count; place++, i++) {
|
|
103
|
+
const b = bars[i];
|
|
104
|
+
if (!b || b.line !== l.line || placeOf(w, b) !== place)
|
|
105
|
+
return false;
|
|
106
|
+
}
|
|
107
|
+
}
|
|
108
|
+
return i === bars.length;
|
|
109
|
+
}
|
|
110
|
+
/** The section's written lines, when the occurrence plays them straight through (spec 4.5); else null. */
|
|
111
|
+
export function straightLines(o, w) {
|
|
112
|
+
const lines = w.sections.get(o.source ?? -1) ?? [];
|
|
113
|
+
// ChordPro's volta names one pass (`|2`): an ending for several (`|1-3`) has none.
|
|
114
|
+
if (lines.some((l) => l.ending && l.ending.length !== 1))
|
|
115
|
+
return null;
|
|
116
|
+
return playsAs(o.bars, fullPlay(lines), w) ? lines : null;
|
|
117
|
+
}
|
package/dist/index.d.ts
ADDED
package/dist/index.js
ADDED
package/dist/version.js
ADDED
package/package.json
CHANGED
|
@@ -1 +1,48 @@
|
|
|
1
|
-
{
|
|
1
|
+
{
|
|
2
|
+
"name": "@barmark/lyricsheet",
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "Export a barmark chart as a ChordPro lyric sheet, and say what it could not carry.",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"sideEffects": false,
|
|
7
|
+
"exports": {
|
|
8
|
+
".": {
|
|
9
|
+
"types": "./dist/index.d.ts",
|
|
10
|
+
"import": "./dist/index.js"
|
|
11
|
+
}
|
|
12
|
+
},
|
|
13
|
+
"types": "./dist/index.d.ts",
|
|
14
|
+
"files": [
|
|
15
|
+
"dist",
|
|
16
|
+
"CHANGELOG.md"
|
|
17
|
+
],
|
|
18
|
+
"engines": {
|
|
19
|
+
"node": ">=20"
|
|
20
|
+
},
|
|
21
|
+
"keywords": [
|
|
22
|
+
"barmark",
|
|
23
|
+
"chord-chart",
|
|
24
|
+
"chords",
|
|
25
|
+
"music",
|
|
26
|
+
"lyrics",
|
|
27
|
+
"lyric-sheet"
|
|
28
|
+
],
|
|
29
|
+
"author": "Kevin Peckham",
|
|
30
|
+
"license": "MIT",
|
|
31
|
+
"homepage": "https://github.com/kevinpeckham/barmark/tree/main/packages/lyricsheet#readme",
|
|
32
|
+
"repository": {
|
|
33
|
+
"type": "git",
|
|
34
|
+
"url": "git+https://github.com/kevinpeckham/barmark.git",
|
|
35
|
+
"directory": "packages/lyricsheet"
|
|
36
|
+
},
|
|
37
|
+
"bugs": {
|
|
38
|
+
"url": "https://github.com/kevinpeckham/barmark/issues"
|
|
39
|
+
},
|
|
40
|
+
"dependencies": {
|
|
41
|
+
"@barmark/fretboard": "^0.1.2",
|
|
42
|
+
"barmark": "^0.25.0"
|
|
43
|
+
},
|
|
44
|
+
"scripts": {
|
|
45
|
+
"build": "rm -rf dist && tsc -p tsconfig.build.json",
|
|
46
|
+
"prepack": "bun run build"
|
|
47
|
+
}
|
|
48
|
+
}
|