tonal-guitar 0.6.0 → 0.7.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 +18 -0
- package/README.md +51 -0
- package/dist/index.d.mts +350 -3
- package/dist/index.d.ts +350 -3
- package/dist/index.js +2455 -173
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +2433 -173
- package/dist/index.mjs.map +1 -1
- package/docs/UPGRADING.md +83 -0
- package/docs/api/index.md +46 -1
- package/docs/api/lines.md +676 -0
- package/docs/api/output.md +209 -4
- package/docs/api/sequences.md +37 -0
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|
|
7
7
|
|
|
8
8
|
## [Unreleased]
|
|
9
9
|
|
|
10
|
+
## [0.7.0] — 2026-11-17
|
|
11
|
+
|
|
12
|
+
### Added
|
|
13
|
+
|
|
14
|
+
- Notes in time. `Dur` (`{ n, d }`, a fraction of a whole note) with `isDur`, `reduceDur`, `addDur`, `subtractDur`, `multiplyDur`, `compareDur` and `sumDur`: exact, in lowest terms, never a floating point sum. A `Step` is notes (`[]` is a rest; a note is a `StepNote`, which needs only a `string` and a `fret`, so a built `FrettedNote` and a hand-written `{ string: 0, fret: 3 }` both fit) with a `dur`, and optionally a `tuplet`, `tie`, `marks`, `finger`, `text` and `chord`; a `Segment` is steps from one placement (`from`, which is `{ shapeId, buildRoot, tonic, scaleType? }`, and `walk`) with an optional `label`, `meter`, `key`, `tempo`, `section`, `repeatStart`, `repeatEnd` and `gap`; a `Line` is a `tuning`, a `meter`, an optional `key`, `feel` and `tempo`, and `segments`. Exported types: `Dur`, `Meter`, `Tuplet`, `Feel`, `Mark`, `StepNote`, `Step`, `SegmentSource`, `Segment`, `Line`.
|
|
15
|
+
- `applyRhythm(notes, rhythm)` gives a walk's notes their lengths from one duration or a repeating cell of slots (rests, ties, tuplets), and `RHYTHM_CELLS` has eight common cells (`quarters`, `eighths`, `triplets`, `sixteenths`, `sixteenth-triplets`, `gallop`, `reverse-gallop`, `dotted-eighth-sixteenth`). Types: `RhythmSlot`, `RhythmCell`, `RhythmCellId`.
|
|
16
|
+
- `fitToBars(steps, meter, options?)` ends a list of steps on a beat (the last note is held to it) and fills its last bar with rests, and can cut steps at bar lines, leaving each mark on the part it belongs to, so the cut steps write the same tab (`FitOptions`, `FitResult`). `gapSegment(gap, meter)` is a segment of silence (`"none"`, `{ rest }` or `{ bars }`); a gap is written in the key and tempo of the segment it leads into. `segmentFrom(placement, steps, extra?)` makes a segment with `from` and, where it can be read, `key`. Type: `Gap`.
|
|
17
|
+
- `lineBars(line)` and `lineEvents(line)`: where the bar lines fall (`LineBar`) and when each sounding note starts and how long it lasts, with tied runs joined (`LineEvent`). `lineIssues(line)` lists everything that stops a line being written, with a code, a message that shows the value, and indexes (`LineIssue`, `LineIssueCode`). Among them are things alphaTab would show wrong without saying so: two chord symbols that differ only in letter case (`CM7` and `Cm7`), and a slide to the next note together with a slide out. A line has at most 200,000 steps, a step at most 12 notes and 16 marks; every read of a list stops at a bound. A step's `text` or `chord` and a segment's `label` or `section` has at most 1,000 characters, and a `key` at most 64: a longer one is a `text` or `key` issue that says to shorten it or, for a text, to split the exercise into more than one line. The fields of a segment's `from` have the same 1,000-character bound (a longer one is a `segment` issue), and a note's descriptive strings or a walk's option strings over it are left out of the stored form. A walk's `motif` of more than 64 numbers is left out of the stored form as well. A stored form too long to be a string is not written: `serializeLine` gives `undefined`, and when the strings alone pass 536,870,888 characters it does so without building the text. Within these bounds a line can still ask for a tab too long to return, which costs seconds before `""` comes back; the Lines page gives the measurements.
|
|
18
|
+
- `normalizeLine`, `lineEquals`, `serializeLine`, `parseLine` and `LINE_SCHEMA` (`"tonal-guitar/line@1"`): equality of two lines as data, and a stable JSON form, tagged under `$schema`, that parses back to the same line.
|
|
19
|
+
- `toAlphaTeX(line, options?)` writes a `Line`: a five-line header, then one bar per line in which every bar adds up. A step that crosses a bar line is cut and tied; a short bar has a meter of its own and is filled to the beat when it has to be; a segment's meter, key and tempo, section and repeats are written where they change; marks, fingering, pick strokes, tuplets, text and chord symbols are written, and a line with an issue writes `""`. `LineTexOptions` is the new options type (`title`, `staff`). The note form of `toAlphaTeX` is kept until 1.0 and its output is unchanged.
|
|
20
|
+
- `MOTIFS`: the motifs of eleven common drills (`linear`, `thirds`, `fourths`, `sixths`, `triads`, `sevenths`, `groups-3`, `groups-4`, `1235`, `up-and-back`, `triad-climb`) for `walk`'s `motif`, frozen. Type: `MotifId`.
|
|
21
|
+
- `keySignatureOf(key)`: the key signature for a key written as one string (`"A minor"`, `"D dorian"`), by the rule `toAlphaTeX`'s `key` already used; `undefined` for a string it cannot read.
|
|
22
|
+
- Docs: a Lines page (`docs/api/lines.md`), and the line form of `toAlphaTeX` on the Output page.
|
|
23
|
+
|
|
24
|
+
### Changed
|
|
25
|
+
|
|
26
|
+
- `toAlphaTeX` given an object that is not an array reads it as a line: it returns the tab when the object is a valid `Line` and `""` when it is not. Such a call used to throw (`TypeError: notes.map is not a function` for `{}`, a `Map` or a `Date`; `group.map is not a function` for a typed array with entries). An object with a `map` of its own that returned nothing did not throw: an empty typed array gave a tab with no notes, and now gives `""`. Arrays, `null`, strings and numbers behave as before, and the output for a list of notes is unchanged.
|
|
27
|
+
|
|
10
28
|
## [0.6.0] — 2026-11-17
|
|
11
29
|
|
|
12
30
|
### Added
|
package/README.md
CHANGED
|
@@ -52,6 +52,50 @@ console.log(toAsciiTab(notes));
|
|
|
52
52
|
console.log(toAlphaTeX(notes, { tempo: 100, duration: 8 }));
|
|
53
53
|
```
|
|
54
54
|
|
|
55
|
+
## Notes in time
|
|
56
|
+
|
|
57
|
+
A walk gives notes with no length. Give them lengths with `applyRhythm`, fit them to bars with `fitToBars`, and write the tab of a `Line` with `toAlphaTeX`:
|
|
58
|
+
|
|
59
|
+
```ts
|
|
60
|
+
import {
|
|
61
|
+
placeScale,
|
|
62
|
+
walk,
|
|
63
|
+
MOTIFS,
|
|
64
|
+
applyRhythm,
|
|
65
|
+
fitToBars,
|
|
66
|
+
segmentFrom,
|
|
67
|
+
toAlphaTeX,
|
|
68
|
+
STANDARD,
|
|
69
|
+
type Line,
|
|
70
|
+
} from "tonal-guitar";
|
|
71
|
+
|
|
72
|
+
// C major, CAGED E shape, thirds up and down, in eighth notes
|
|
73
|
+
const box = placeScale("C major", {
|
|
74
|
+
system: "caged",
|
|
75
|
+
position: { view: "tonic", letter: "E" },
|
|
76
|
+
});
|
|
77
|
+
const notes = walk(box, { motif: [...MOTIFS.thirds], direction: "up-down" });
|
|
78
|
+
const steps = applyRhythm(notes, { n: 1, d: 8 }) ?? []; // give each note an eighth
|
|
79
|
+
const fit = fitToBars(steps, [4, 4]); // fill the last bar with rests
|
|
80
|
+
if (!fit) throw new Error("the notes could not be fitted");
|
|
81
|
+
|
|
82
|
+
const line: Line = {
|
|
83
|
+
tuning: STANDARD,
|
|
84
|
+
meter: [4, 4],
|
|
85
|
+
segments: [segmentFrom(box, fit.steps, { label: "C major thirds" })],
|
|
86
|
+
};
|
|
87
|
+
console.log(toAlphaTeX(line, { title: "C major, E shape, thirds" }));
|
|
88
|
+
// => \title "C major, E shape, thirds"
|
|
89
|
+
// \tempo 120
|
|
90
|
+
// \track ("Guitar" "Gtr")
|
|
91
|
+
// \staff {tabs}
|
|
92
|
+
// \tuning (E4 B3 G3 D3 A2 E2)
|
|
93
|
+
// \ts (4 4) \ks C :8 7.6{txt "C major thirds"} 10.6 8.6 7.5 10.6 8.5 7.5 10.5 |
|
|
94
|
+
// ... eight bars in all: 58 notes and three quarter rests
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
A `Line` is plain data (`tuning`, `meter` and `segments` of `steps`); `lineIssues` lists what is wrong with one, `lineBars` and `lineEvents` say where the bars fall and when each note sounds, and `serializeLine` and `parseLine` store it. See [docs/api/lines.md](./docs/api/lines.md) and [docs/api/output.md](./docs/api/output.md).
|
|
98
|
+
|
|
55
99
|
## v0.2.0 Changes
|
|
56
100
|
|
|
57
101
|
- **`buildFromScale` pitch-correctness fix.** `buildFromScale` now relabels a shape into the requested scale's interval frame before building, so minor-tonic (and other non-major) scale names produce correct pitch content instead of silently building the shape's original (usually major) frame at the new tonic. See [buildFromScale](#tonaljs-integration) for the before/after example.
|
|
@@ -509,6 +553,8 @@ parseScalePattern("5-8,5-7,5-7,5-7,5-8,5-8");
|
|
|
509
553
|
|
|
510
554
|
#### `toAlphaTeX(notes: FrettedNote[], options?: AlphaTexOptions) => string`
|
|
511
555
|
|
|
556
|
+
`toAlphaTeX(line: Line, options?: LineTexOptions)` writes a `Line` (see [Notes in time](#notes-in-time)); the note form below is kept until 1.0 and its output does not change. A plain object that is not a valid line used to make it throw and now gives `""`.
|
|
557
|
+
|
|
512
558
|
Format notes as [AlphaTeX](https://www.alphatab.net/docs/alphatex/) notation:
|
|
513
559
|
|
|
514
560
|
```js
|
|
@@ -542,6 +588,10 @@ keySignature("D", "dorian"); // => { tonic: "C", mode: "major", accidentals: 0 }
|
|
|
542
588
|
keySignature("H"); // => undefined
|
|
543
589
|
```
|
|
544
590
|
|
|
591
|
+
#### `keySignatureOf(key: string) => KeySignature | undefined`
|
|
592
|
+
|
|
593
|
+
The same, for a key written as one string: `keySignatureOf("A minor")` is `{ tonic: "A", mode: "minor", accidentals: 0 }`, `keySignatureOf("D dorian")` is C major's, and `keySignatureOf("C blues")` is `undefined`.
|
|
594
|
+
|
|
545
595
|
#### `toAsciiTab(notes: FrettedNote[], options?: AsciiTabOptions) => string`
|
|
546
596
|
|
|
547
597
|
Format notes as ASCII tablature:
|
|
@@ -834,6 +884,7 @@ The package exports these TypeScript interfaces:
|
|
|
834
884
|
- `WalkOptions` — options for `walkPattern`
|
|
835
885
|
- `WalkSpec` — options for `walk`
|
|
836
886
|
- `KeyMode`, `KeySignature` — the mode argument and the result of `keySignature`
|
|
887
|
+
- `Dur`, `Meter`, `Tuplet`, `Feel`, `Mark`, `Step`, `SegmentSource`, `Segment`, `Line` — notes in time (see [docs/api/lines.md](./docs/api/lines.md)); `LineTexOptions`, `LineBar`, `LineEvent`, `LineIssue`, `LineIssueCode`, `RhythmSlot`, `RhythmCell`, `RhythmCellId`, `FitOptions`, `FitResult`, `Gap`, `MotifId`
|
|
837
888
|
- `SequenceOptions` — options for `applySequence`
|
|
838
889
|
- `AlphaTexOptions` — options for `toAlphaTeX`
|
|
839
890
|
- `AsciiTabOptions` — options for `toAsciiTab`
|
package/dist/index.d.mts
CHANGED
|
@@ -1026,7 +1026,7 @@ declare function autoFingering(shape: Omit<ChordShape, "fingers" | "barres">, ro
|
|
|
1026
1026
|
barres: Barre[];
|
|
1027
1027
|
};
|
|
1028
1028
|
|
|
1029
|
-
declare const VERSION = "0.
|
|
1029
|
+
declare const VERSION = "0.7.0";
|
|
1030
1030
|
|
|
1031
1031
|
/**
|
|
1032
1032
|
* Shape visual/quality audit checks.
|
|
@@ -1623,6 +1623,13 @@ interface KeySignature {
|
|
|
1623
1623
|
* gives `undefined`.
|
|
1624
1624
|
*/
|
|
1625
1625
|
declare function keySignature(tonic: string, mode?: KeyMode): KeySignature | undefined;
|
|
1626
|
+
/**
|
|
1627
|
+
* The key signature for a key string (spec §4): a tonic then an optional
|
|
1628
|
+
* mode, with or without a space ("A", "Am", "A minor", "F# major",
|
|
1629
|
+
* "D dorian"). `m` and `M` are case-sensitive; mode words are not. Anything
|
|
1630
|
+
* unreadable, and any non-string, is `undefined`.
|
|
1631
|
+
*/
|
|
1632
|
+
declare function keySignatureOf(key: string): KeySignature | undefined;
|
|
1626
1633
|
|
|
1627
1634
|
interface SequenceOptions {
|
|
1628
1635
|
incremental?: boolean;
|
|
@@ -1806,6 +1813,133 @@ declare function formatChordFrets(frets: (number | null)[]): string;
|
|
|
1806
1813
|
*/
|
|
1807
1814
|
declare function parseScalePattern(input: string): number[][];
|
|
1808
1815
|
|
|
1816
|
+
/** An exact duration, a fraction of a whole note: 1/8 is `{ n: 1, d: 8 }`. */
|
|
1817
|
+
interface Dur {
|
|
1818
|
+
n: number;
|
|
1819
|
+
d: number;
|
|
1820
|
+
}
|
|
1821
|
+
/** A duration: `n` a safe integer from 0, `d` a safe integer from 1. */
|
|
1822
|
+
declare function isDur(value: unknown): value is Dur;
|
|
1823
|
+
/** `a` in lowest terms; zero is `{ n: 0, d: 1 }`. */
|
|
1824
|
+
declare function reduceDur(a: Dur): Dur;
|
|
1825
|
+
/** `a + b`, exactly; the invalid duration when the sum does not fit. */
|
|
1826
|
+
declare function addDur(a: Dur, b: Dur): Dur;
|
|
1827
|
+
/** `a - b`, exactly; below zero is the invalid duration. */
|
|
1828
|
+
declare function subtractDur(a: Dur, b: Dur): Dur;
|
|
1829
|
+
/** `a` times a non-negative safe integer or another duration. */
|
|
1830
|
+
declare function multiplyDur(a: Dur, by: number | Dur): Dur;
|
|
1831
|
+
/** -1, 0 or 1; 0 when either is not a duration. */
|
|
1832
|
+
declare function compareDur(a: Dur, b: Dur): -1 | 0 | 1;
|
|
1833
|
+
/** The sum of a list; zero for an empty list. */
|
|
1834
|
+
declare function sumDur(list: readonly Dur[]): Dur;
|
|
1835
|
+
|
|
1836
|
+
/** Beats in a bar, and the note value that is one beat: [6, 8]. */
|
|
1837
|
+
type Meter = readonly [beats: number, unit: number];
|
|
1838
|
+
/** `count` notes in the time of `inTimeOf`: a triplet is { count: 3, inTimeOf: 2 }. */
|
|
1839
|
+
interface Tuplet {
|
|
1840
|
+
count: number;
|
|
1841
|
+
inTimeOf: number;
|
|
1842
|
+
}
|
|
1843
|
+
type Feel = "straight" | "swing8" | "shuffle8" | "swing16";
|
|
1844
|
+
type Mark = {
|
|
1845
|
+
kind: "bend";
|
|
1846
|
+
points: number[];
|
|
1847
|
+
} | {
|
|
1848
|
+
kind: "vibrato";
|
|
1849
|
+
} | {
|
|
1850
|
+
kind: "slide";
|
|
1851
|
+
to?: "next" | "in" | "out";
|
|
1852
|
+
} | {
|
|
1853
|
+
kind: "hammer" | "pull";
|
|
1854
|
+
} | {
|
|
1855
|
+
kind: "palm-mute" | "let-ring" | "accent" | "staccato";
|
|
1856
|
+
} | {
|
|
1857
|
+
kind: "pick";
|
|
1858
|
+
stroke: "down" | "up";
|
|
1859
|
+
};
|
|
1860
|
+
/**
|
|
1861
|
+
* A note of a step. A line needs only where the note is played; the rest of
|
|
1862
|
+
* what a `FrettedNote` says (its name, interval, degree, midi) is kept when it
|
|
1863
|
+
* is there and never asked for. Every `FrettedNote` is a `StepNote`, and
|
|
1864
|
+
* `{ string: 0, fret: 3 }` is one too.
|
|
1865
|
+
*/
|
|
1866
|
+
interface StepNote extends Partial<FrettedNote> {
|
|
1867
|
+
/** 0 is the lowest string. */
|
|
1868
|
+
string: number;
|
|
1869
|
+
fret: number;
|
|
1870
|
+
}
|
|
1871
|
+
interface Step {
|
|
1872
|
+
/** [] is a rest, one note a note, more a chord or double stop. */
|
|
1873
|
+
notes: StepNote[];
|
|
1874
|
+
/** The time the step takes, as a fraction of a whole note (D-003). */
|
|
1875
|
+
dur: Dur;
|
|
1876
|
+
/** How it is written when the default is not wanted (D-004). */
|
|
1877
|
+
tuplet?: Tuplet;
|
|
1878
|
+
/** Tied to the next step of the segment (D-015). */
|
|
1879
|
+
tie?: boolean;
|
|
1880
|
+
marks?: Mark[];
|
|
1881
|
+
/** Parallel to `notes`: 1 to 4, 0 for the thumb, null for none (D-017). */
|
|
1882
|
+
finger?: (number | null)[];
|
|
1883
|
+
/** Text above the step. */
|
|
1884
|
+
text?: string;
|
|
1885
|
+
/** A chord symbol above the step. */
|
|
1886
|
+
chord?: string;
|
|
1887
|
+
}
|
|
1888
|
+
/** The placement a segment's notes came from. */
|
|
1889
|
+
interface SegmentSource {
|
|
1890
|
+
shapeId: string;
|
|
1891
|
+
/** Where the shape was built (`Placement.buildRoot`). */
|
|
1892
|
+
buildRoot: string;
|
|
1893
|
+
/** The key (`Placement.tonic`). */
|
|
1894
|
+
tonic: string;
|
|
1895
|
+
/** The scale type, when known: "dorian", "minor pentatonic". */
|
|
1896
|
+
scaleType?: string;
|
|
1897
|
+
}
|
|
1898
|
+
interface Segment {
|
|
1899
|
+
/** Absent on a gap, and on notes that came from no placement. */
|
|
1900
|
+
from?: SegmentSource;
|
|
1901
|
+
walk?: WalkSpec;
|
|
1902
|
+
steps: Step[];
|
|
1903
|
+
/** Written above the segment's first step: "F", "E shape", "ii". */
|
|
1904
|
+
label?: string;
|
|
1905
|
+
/** Default: the line's. */
|
|
1906
|
+
meter?: Meter;
|
|
1907
|
+
/** Default: the line's. A tonic and an optional mode: "A minor". Not on a gap. */
|
|
1908
|
+
key?: string;
|
|
1909
|
+
/** Quarter notes per minute, for this segment only. Default: the line's. Not on a gap. */
|
|
1910
|
+
tempo?: number;
|
|
1911
|
+
/** A section marker on the segment's first bar. */
|
|
1912
|
+
section?: string;
|
|
1913
|
+
/** A repeat opens on the segment's first bar. */
|
|
1914
|
+
repeatStart?: boolean;
|
|
1915
|
+
/** A repeat closes on the segment's last bar; played this many times in all. */
|
|
1916
|
+
repeatEnd?: number;
|
|
1917
|
+
/**
|
|
1918
|
+
* A gap between two segments (`gapSegment`). A gap has no key or tempo of
|
|
1919
|
+
* its own: it is written in those of the segment it leads into (5.3).
|
|
1920
|
+
*/
|
|
1921
|
+
gap?: boolean;
|
|
1922
|
+
}
|
|
1923
|
+
interface Line {
|
|
1924
|
+
/** Low string first, as everywhere in this library. */
|
|
1925
|
+
tuning: string[];
|
|
1926
|
+
meter: Meter;
|
|
1927
|
+
/** Default "C". */
|
|
1928
|
+
key?: string;
|
|
1929
|
+
/** Default "straight". */
|
|
1930
|
+
feel?: Feel;
|
|
1931
|
+
/** Quarter notes per minute. Default 120. */
|
|
1932
|
+
tempo?: number;
|
|
1933
|
+
segments: Segment[];
|
|
1934
|
+
}
|
|
1935
|
+
|
|
1936
|
+
interface LineTexOptions {
|
|
1937
|
+
/** Default "Exercise". */
|
|
1938
|
+
title?: string;
|
|
1939
|
+
/** Default "tabs". */
|
|
1940
|
+
staff?: "tabs" | "score" | "score-tabs";
|
|
1941
|
+
}
|
|
1942
|
+
|
|
1809
1943
|
interface AlphaTexOptions {
|
|
1810
1944
|
title?: string;
|
|
1811
1945
|
tempo?: number;
|
|
@@ -1854,7 +1988,17 @@ interface AlphaTexOptions {
|
|
|
1854
1988
|
rhythmPattern?: number[];
|
|
1855
1989
|
}
|
|
1856
1990
|
/**
|
|
1857
|
-
*
|
|
1991
|
+
* Write a line as alphaTeX (line spec §9): a header, then one bar per line,
|
|
1992
|
+
* with the meter, key signature and tempo written on the bars where they
|
|
1993
|
+
* change. A line with any issue (`lineIssues`) writes `""`; a line with no
|
|
1994
|
+
* steps writes the header alone. Every bar it writes is exactly as long as
|
|
1995
|
+
* its meter.
|
|
1996
|
+
*/
|
|
1997
|
+
declare function toAlphaTeX(line: Line, options?: LineTexOptions): string;
|
|
1998
|
+
/**
|
|
1999
|
+
* Render a sequence of fretted notes as an AlphaTeX string. This is the note
|
|
2000
|
+
* form: it stays, unchanged, until 1.0. Notes in time (a `Line`) are written
|
|
2001
|
+
* by the other form of this function.
|
|
1858
2002
|
*
|
|
1859
2003
|
* **Input forms:**
|
|
1860
2004
|
* - `FrettedNote[]` — flat sequential notes (original behaviour, unchanged).
|
|
@@ -1901,6 +2045,209 @@ interface AsciiTabOptions {
|
|
|
1901
2045
|
*/
|
|
1902
2046
|
declare function toAsciiTab(notes: FrettedNote[] | FrettedNote[][], options?: AsciiTabOptions): string;
|
|
1903
2047
|
|
|
2048
|
+
type RhythmSlot = Dur | {
|
|
2049
|
+
dur: Dur;
|
|
2050
|
+
rest?: boolean;
|
|
2051
|
+
tie?: boolean;
|
|
2052
|
+
tuplet?: Tuplet;
|
|
2053
|
+
};
|
|
2054
|
+
type RhythmCell = readonly RhythmSlot[];
|
|
2055
|
+
/**
|
|
2056
|
+
* Give notes time (spec §6.1): a cell of slots goes round the groups of
|
|
2057
|
+
* notes. Rest slots at the counter become rest steps; the group takes the
|
|
2058
|
+
* slot at the counter, and the next ones while a slot is tied. `undefined`
|
|
2059
|
+
* for notes that are not a list or a rhythm that is not valid, and when the
|
|
2060
|
+
* notes, the cell or the steps they make are more than 200,000.
|
|
2061
|
+
*/
|
|
2062
|
+
declare function applyRhythm(notes: StepNote[] | StepNote[][], rhythm: Dur | RhythmCell): Step[] | undefined;
|
|
2063
|
+
/** Rhythm cells for `applyRhythm`. The object, each cell and each slot are frozen. */
|
|
2064
|
+
declare const RHYTHM_CELLS: Readonly<{
|
|
2065
|
+
readonly quarters: readonly [Readonly<{
|
|
2066
|
+
n: 1;
|
|
2067
|
+
d: 4;
|
|
2068
|
+
}>];
|
|
2069
|
+
readonly eighths: readonly [Readonly<{
|
|
2070
|
+
n: 1;
|
|
2071
|
+
d: 8;
|
|
2072
|
+
}>];
|
|
2073
|
+
readonly triplets: readonly [Readonly<{
|
|
2074
|
+
n: 1;
|
|
2075
|
+
d: 12;
|
|
2076
|
+
}>];
|
|
2077
|
+
readonly sixteenths: readonly [Readonly<{
|
|
2078
|
+
n: 1;
|
|
2079
|
+
d: 16;
|
|
2080
|
+
}>];
|
|
2081
|
+
readonly "sixteenth-triplets": readonly [Readonly<{
|
|
2082
|
+
n: 1;
|
|
2083
|
+
d: 24;
|
|
2084
|
+
}>];
|
|
2085
|
+
readonly gallop: readonly [Readonly<{
|
|
2086
|
+
n: 1;
|
|
2087
|
+
d: 8;
|
|
2088
|
+
}>, Readonly<{
|
|
2089
|
+
n: 1;
|
|
2090
|
+
d: 16;
|
|
2091
|
+
}>, Readonly<{
|
|
2092
|
+
n: 1;
|
|
2093
|
+
d: 16;
|
|
2094
|
+
}>];
|
|
2095
|
+
readonly "reverse-gallop": readonly [Readonly<{
|
|
2096
|
+
n: 1;
|
|
2097
|
+
d: 16;
|
|
2098
|
+
}>, Readonly<{
|
|
2099
|
+
n: 1;
|
|
2100
|
+
d: 16;
|
|
2101
|
+
}>, Readonly<{
|
|
2102
|
+
n: 1;
|
|
2103
|
+
d: 8;
|
|
2104
|
+
}>];
|
|
2105
|
+
readonly "dotted-eighth-sixteenth": readonly [Readonly<{
|
|
2106
|
+
n: 3;
|
|
2107
|
+
d: 16;
|
|
2108
|
+
}>, Readonly<{
|
|
2109
|
+
n: 1;
|
|
2110
|
+
d: 16;
|
|
2111
|
+
}>];
|
|
2112
|
+
}>;
|
|
2113
|
+
type RhythmCellId = keyof typeof RHYTHM_CELLS;
|
|
2114
|
+
|
|
2115
|
+
interface FitOptions {
|
|
2116
|
+
/** Default true. */
|
|
2117
|
+
holdLastNote?: boolean;
|
|
2118
|
+
/** Default true. */
|
|
2119
|
+
fillBar?: boolean;
|
|
2120
|
+
/** Default: steps are left whole and the writer ties them (D-007). */
|
|
2121
|
+
splitAcrossBarlines?: "tie" | "error";
|
|
2122
|
+
}
|
|
2123
|
+
interface FitResult {
|
|
2124
|
+
steps: Step[];
|
|
2125
|
+
/** Bars the steps take; a short last bar counts. */
|
|
2126
|
+
bars: number;
|
|
2127
|
+
/** The last step was lengthened. */
|
|
2128
|
+
held: boolean;
|
|
2129
|
+
/** Rest steps added at the end. */
|
|
2130
|
+
fillRests: number;
|
|
2131
|
+
/** Their total length. */
|
|
2132
|
+
fill: Dur;
|
|
2133
|
+
/** The length of `steps`. */
|
|
2134
|
+
dur: Dur;
|
|
2135
|
+
}
|
|
2136
|
+
/**
|
|
2137
|
+
* Makes a pass of steps end where a bar ends (spec section 6.2, D-010): holds
|
|
2138
|
+
* the last note to its beat, fills the bar with rests, and optionally cuts steps
|
|
2139
|
+
* at bar lines. Every step of a result can be written. The last note is not
|
|
2140
|
+
* held when the held note could not be written where it sits: in the parts
|
|
2141
|
+
* the bar lines cut it into, and whole as well unless the split is "tie".
|
|
2142
|
+
* `undefined` for invalid input, and when the rest that ends the beat or a
|
|
2143
|
+
* part of a cut step could not be written. Never throws.
|
|
2144
|
+
*/
|
|
2145
|
+
declare function fitToBars(steps: Step[], meter: Meter, options?: FitOptions): FitResult | undefined;
|
|
2146
|
+
type Gap = "none" | {
|
|
2147
|
+
rest: Dur;
|
|
2148
|
+
} | {
|
|
2149
|
+
bars: number;
|
|
2150
|
+
};
|
|
2151
|
+
/**
|
|
2152
|
+
* A segment of rests that sits between two segments (spec section 6.2, D-024):
|
|
2153
|
+
* `{ rest }` is one rest, `{ bars }` is that many whole bars. `undefined` for
|
|
2154
|
+
* "none" and for anything invalid; never throws.
|
|
2155
|
+
*/
|
|
2156
|
+
declare function gapSegment(gap: Gap, meter: Meter): Segment | undefined;
|
|
2157
|
+
|
|
2158
|
+
/**
|
|
2159
|
+
* A segment from a placement and the steps made of its notes (spec §6.3):
|
|
2160
|
+
* `from` names the placement, and `key` is the scale's own key when its name
|
|
2161
|
+
* can be read. An empty or unreadable placement leaves `from` out.
|
|
2162
|
+
*/
|
|
2163
|
+
declare function segmentFrom(placement: Placement, steps: Step[], extra?: Omit<Segment, "steps" | "from">): Segment;
|
|
2164
|
+
|
|
2165
|
+
interface LineBar {
|
|
2166
|
+
/** 0-based. */
|
|
2167
|
+
index: number;
|
|
2168
|
+
/** From the start of the line, in whole notes. */
|
|
2169
|
+
at: Dur;
|
|
2170
|
+
/** The bar's length, in whole notes. */
|
|
2171
|
+
dur: Dur;
|
|
2172
|
+
/** As written: a short bar has a meter of its own. */
|
|
2173
|
+
meter: Meter;
|
|
2174
|
+
/** The segment the bar's first piece belongs to. */
|
|
2175
|
+
segment: number;
|
|
2176
|
+
/** Every piece in the bar is from a segment with `gap: true`. */
|
|
2177
|
+
gap: boolean;
|
|
2178
|
+
}
|
|
2179
|
+
interface LineEvent {
|
|
2180
|
+
/** From the start of the line, in whole notes. */
|
|
2181
|
+
at: Dur;
|
|
2182
|
+
dur: Dur;
|
|
2183
|
+
/** The step's own note object, as given. */
|
|
2184
|
+
note: StepNote;
|
|
2185
|
+
segment: number;
|
|
2186
|
+
/** The step the note starts in. */
|
|
2187
|
+
step: number;
|
|
2188
|
+
}
|
|
2189
|
+
/** Where the bar lines fall (spec section 5.4); `undefined` when the line has an issue. */
|
|
2190
|
+
declare function lineBars(line: Line): LineBar[] | undefined;
|
|
2191
|
+
/**
|
|
2192
|
+
* One event per sounding note, ordered by onset then string (spec section 5.4);
|
|
2193
|
+
* `undefined` when the line has an issue.
|
|
2194
|
+
*/
|
|
2195
|
+
declare function lineEvents(line: Line): LineEvent[] | undefined;
|
|
2196
|
+
|
|
2197
|
+
type LineIssueCode = "line" | "tuning" | "meter" | "key" | "feel" | "tempo" | "segment" | "step" | "dur" | "tuplet" | "length" | "note" | "string" | "finger" | "mark" | "tie" | "text" | "repeat" | "bar";
|
|
2198
|
+
interface LineIssue {
|
|
2199
|
+
code: LineIssueCode;
|
|
2200
|
+
/** Plain words, naming the value that is wrong. */
|
|
2201
|
+
message: string;
|
|
2202
|
+
/** Indexes, when the issue is inside a segment, a step, a note. */
|
|
2203
|
+
segment?: number;
|
|
2204
|
+
step?: number;
|
|
2205
|
+
note?: number;
|
|
2206
|
+
}
|
|
2207
|
+
/**
|
|
2208
|
+
* Every problem that stops a line being written, in the order the line is read
|
|
2209
|
+
* (spec section 7): the line's own fields, then each segment's own fields, then
|
|
2210
|
+
* each of its steps' fields, then each note. Never throws.
|
|
2211
|
+
*/
|
|
2212
|
+
declare function lineIssues(line: unknown): LineIssue[];
|
|
2213
|
+
|
|
2214
|
+
declare const LINE_SCHEMA = "tonal-guitar/line@1";
|
|
2215
|
+
/**
|
|
2216
|
+
* The stable form of a line (spec §8): fields in a fixed order, defaults left
|
|
2217
|
+
* out, durations in lowest terms, nothing shared with the input.
|
|
2218
|
+
* `undefined` for a line with issues. Never throws.
|
|
2219
|
+
*/
|
|
2220
|
+
declare function normalizeLine(line: Line): Line | undefined;
|
|
2221
|
+
/** True when both lines are valid and have the same stable form. Never throws. */
|
|
2222
|
+
declare function lineEquals(a: Line, b: Line): boolean;
|
|
2223
|
+
/**
|
|
2224
|
+
* The line as JSON text, `$schema` first, no white space; `undefined` for a
|
|
2225
|
+
* line with issues, and for one whose stored form would be too long to be a
|
|
2226
|
+
* string. When the strings alone pass 536,870,888 characters, the longest
|
|
2227
|
+
* string Node makes, that is answered before the text is built: building it
|
|
2228
|
+
* first took gigabytes for a line of 200,000 twelve-note steps that shared
|
|
2229
|
+
* one long note name. Otherwise the text is built and the engine refuses it.
|
|
2230
|
+
*/
|
|
2231
|
+
declare function serializeLine(line: Line): string | undefined;
|
|
2232
|
+
/** The line a `serializeLine` text holds, normalized; `undefined` for anything else. Never throws. */
|
|
2233
|
+
declare function parseLine(text: string): Line | undefined;
|
|
2234
|
+
|
|
2235
|
+
/** Named scale-degree motifs, for `walk(scale, { motif: [...MOTIFS.thirds] })`. */
|
|
2236
|
+
declare const MOTIFS: Readonly<{
|
|
2237
|
+
readonly linear: readonly [1];
|
|
2238
|
+
readonly thirds: readonly [1, 3];
|
|
2239
|
+
readonly fourths: readonly [1, 4];
|
|
2240
|
+
readonly sixths: readonly [1, 6];
|
|
2241
|
+
readonly triads: readonly [1, 3, 5];
|
|
2242
|
+
readonly sevenths: readonly [1, 3, 5, 7];
|
|
2243
|
+
readonly "groups-3": readonly [1, 2, 3];
|
|
2244
|
+
readonly "groups-4": readonly [1, 2, 3, 4];
|
|
2245
|
+
readonly "1235": readonly [1, 2, 3, 5];
|
|
2246
|
+
readonly "up-and-back": readonly [1, 2, 3, 4, 3, 2];
|
|
2247
|
+
readonly "triad-climb": readonly [1, 3, 5, 3];
|
|
2248
|
+
}>;
|
|
2249
|
+
type MotifId = keyof typeof MOTIFS;
|
|
2250
|
+
|
|
1904
2251
|
/**
|
|
1905
2252
|
* Arpeggio derivation and shape-scoring — pure tier (zero Tonal peer deps).
|
|
1906
2253
|
*
|
|
@@ -2634,4 +2981,4 @@ declare const SEQ_UP_DOWN: number[];
|
|
|
2634
2981
|
declare const SEQ_TRIAD_CLIMB: number[];
|
|
2635
2982
|
declare const SEQ_1357_DESC: number[];
|
|
2636
2983
|
|
|
2637
|
-
export { ASCENDING_THIRDS, type AddArpeggioChange, type AddChange, type AddChordChange, type AddScaleChange, type AlphaTexOptions, type ArpeggioResolution, type ArpeggioShape, type ArpeggioShapeFilter, type ArpeggioSlot, type ArpeggioTier, type AsciiTabOptions, type AuditSeverity, type Barre, type BuildOptions, CHECK_BARRE_FRET_ORIGIN, CHECK_BUILD_LOSS, CHECK_CHORD_TONES_ONLY, CHECK_CONTAINS_CHORD_GRIP, CHECK_COVERS_CHORD, CHECK_FINGERING_COMPLETE, CHECK_FINGER_ZERO_ON_MOVABLE, CHECK_FRET_SPAN, CHECK_GEOMETRY_MISMATCH, CHECK_IDENTIFY_MISMATCH, CHECK_METADATA_COMPLETENESS, CHECK_NAME_UNIQUE, CHECK_OVERRIDES_TARGET, CHECK_POSITION_SPAN, CHECK_REPEATED_FINGER_NO_BARRE, CHECK_STRINGSET_MISMATCH, CHECK_TUNING_MISMATCH, CHORD_SCALE_RULE, CHORD_SCALE_RULE_VERSION, type CagedPosition, type ChainDirection, type Changeset, type ChangesetChange, type ChangesetKind, type ChordGeometryDetails, type ChordScaleEntry, type ChordShape, type ChordShapeAuditResult, type ChordShapeFilter, type ConnectSequencesInput, type ConnectSequencesResult, type ConnectorOptions, type ConnectorStrategy, type ContainingScale, DADGAD, DEFAULT_SCALE_CORPUS, DESCENDING_THIRDS, DROP_D, type DiatonicChord, type Fingering, type FretboardPosition, type FrettedNote, type FrettedScale, type FrettedScaleReason, type InferenceCandidate, type InferenceInput, type InferenceOptions, type InferenceProbe, type KeyAnalysis, type KeyMode, type KeySignature, MODES, type MissingNote, type ModeDef, type NameUniqueKind, type NameUniqueOptions, NoFrettedScale, NoPlacement, OPEN_G, type PassingToneOptions, type PlaceOptions, type PlaceScaleOptions, type Placement, type PlacementRestriction, type PlacementView, type PlacementsOptions, type PositionRequest, type Registry, type RegistryIssue, type RegistryIssueCode, type RegistrySource, type RelabelOptions, type RemoveChange, SEQ_1234_GROUP, SEQ_1235, SEQ_1357_DESC, SEQ_TRIAD_CLIMB, SEQ_UP_DOWN, SHAPE_ID_ALIASES, SHELL_DICTIONARY, STANDARD, STANDARD_7, STANDARD_8, type ScalePlacementsOptions, type ScaleShape, type ScaleShapeFilter, type ScalesContainingChordOptions, type ScalesContainingChordResult, type ScoreBreakdown, type SequenceOptions, type ShapeAuditIssue, type ShapeAuditOptions, type ShapeKind, type ShapeRef, type ShapeSet, type UpdateChange, VERSION, type VoicingFamily, type VoicingPatternDictionary, type WalkOptions, type WalkShapeOptions, type WalkSpec, absoluteBarreFret, add, addPassingTone, all, analyzeInKey, applyChordShape, applySequence, arpeggioFor, arpeggioFromScale, arpeggioFromShape, arpeggioShapes, arpeggioSlotKey, ascendingIntervals, ascendingLinear, auditAllShapes, auditAllShapesIntegration, auditArpeggioShape, auditArpeggioShapeIntegration, auditChordShape, auditChordShapeFull, auditChordShapeIntegration, auditScaleShape, autoFingering, buildFrettedScale, buildFromScale, cagedPositionFor, canPlay, checkBarreFretOrigin, checkChordBuildLoss, checkChordMetadataCompleteness, checkChordTonesOnly, checkContainsChordGrip, checkCoversChord, checkFingerZeroOnMovable, checkFingeringComplete, checkFretSpan, checkGeometryMismatch, checkIdentifierCollision, checkIdentifyMismatch, checkNameCollision, checkNameUnique, checkOverridesTarget, checkPositionSpan, checkRepeatedFingerNoBarre, checkScaleBuildLoss, checkScaleMetadataCompleteness, checkStringsetMismatch, checkTuningMismatch, chordShapeGeometry, chordShapes, connectSequences, createRegistry, descendingIntervals, descendingLinear, diatonicChords, displayRootFor, effectiveModeForSystem, exportIdentifierFor, filterChordTones, findFretInPosition, findNearestFret, findNote, flattenSequence, formatChordFrets, fourths, fretFor, fretboard, get, getMode, globalRegistry, gripBaseFret, grouping, idSlug, identifyChord, impliedStringSet, inferShapeContext, isModeCompatibleWithSystem, isMovable, isShapeCompatible, isShapeId, keySignature, modeBuildRoot, modeShapes, names, nearestPlacement, noteAt, parentBoxForChordShape, parentScale, parseChordFrets, parseScalePattern, place, placeScale, placements, playedStringSet, relabelOffset, relabelShape, relabelShapeToScale, relatedScales, remove, removeAll, resolveArpeggioForSlot, resolveShapeIdAlias, restrictPlacement, scalePlacements, scaleShapes, scaleTypeForChordType, scalesContainingChord, scoreShapeMatch, shapeById, shapeId, sixths, slotForChordShape, stringIndex, stringNumber, thirds, toAlphaTeX, toAsciiTab, visibleArpeggios, walk, walkPattern, walkShape, walkShapeIntervals, walkShapeMotif };
|
|
2984
|
+
export { ASCENDING_THIRDS, type AddArpeggioChange, type AddChange, type AddChordChange, type AddScaleChange, type AlphaTexOptions, type ArpeggioResolution, type ArpeggioShape, type ArpeggioShapeFilter, type ArpeggioSlot, type ArpeggioTier, type AsciiTabOptions, type AuditSeverity, type Barre, type BuildOptions, CHECK_BARRE_FRET_ORIGIN, CHECK_BUILD_LOSS, CHECK_CHORD_TONES_ONLY, CHECK_CONTAINS_CHORD_GRIP, CHECK_COVERS_CHORD, CHECK_FINGERING_COMPLETE, CHECK_FINGER_ZERO_ON_MOVABLE, CHECK_FRET_SPAN, CHECK_GEOMETRY_MISMATCH, CHECK_IDENTIFY_MISMATCH, CHECK_METADATA_COMPLETENESS, CHECK_NAME_UNIQUE, CHECK_OVERRIDES_TARGET, CHECK_POSITION_SPAN, CHECK_REPEATED_FINGER_NO_BARRE, CHECK_STRINGSET_MISMATCH, CHECK_TUNING_MISMATCH, CHORD_SCALE_RULE, CHORD_SCALE_RULE_VERSION, type CagedPosition, type ChainDirection, type Changeset, type ChangesetChange, type ChangesetKind, type ChordGeometryDetails, type ChordScaleEntry, type ChordShape, type ChordShapeAuditResult, type ChordShapeFilter, type ConnectSequencesInput, type ConnectSequencesResult, type ConnectorOptions, type ConnectorStrategy, type ContainingScale, DADGAD, DEFAULT_SCALE_CORPUS, DESCENDING_THIRDS, DROP_D, type DiatonicChord, type Dur, type Feel, type Fingering, type FitOptions, type FitResult, type FretboardPosition, type FrettedNote, type FrettedScale, type FrettedScaleReason, type Gap, type InferenceCandidate, type InferenceInput, type InferenceOptions, type InferenceProbe, type KeyAnalysis, type KeyMode, type KeySignature, LINE_SCHEMA, type Line, type LineBar, type LineEvent, type LineIssue, type LineIssueCode, type LineTexOptions, MODES, MOTIFS, type Mark, type Meter, type MissingNote, type ModeDef, type MotifId, type NameUniqueKind, type NameUniqueOptions, NoFrettedScale, NoPlacement, OPEN_G, type PassingToneOptions, type PlaceOptions, type PlaceScaleOptions, type Placement, type PlacementRestriction, type PlacementView, type PlacementsOptions, type PositionRequest, RHYTHM_CELLS, type Registry, type RegistryIssue, type RegistryIssueCode, type RegistrySource, type RelabelOptions, type RemoveChange, type RhythmCell, type RhythmCellId, type RhythmSlot, SEQ_1234_GROUP, SEQ_1235, SEQ_1357_DESC, SEQ_TRIAD_CLIMB, SEQ_UP_DOWN, SHAPE_ID_ALIASES, SHELL_DICTIONARY, STANDARD, STANDARD_7, STANDARD_8, type ScalePlacementsOptions, type ScaleShape, type ScaleShapeFilter, type ScalesContainingChordOptions, type ScalesContainingChordResult, type ScoreBreakdown, type Segment, type SegmentSource, type SequenceOptions, type ShapeAuditIssue, type ShapeAuditOptions, type ShapeKind, type ShapeRef, type ShapeSet, type Step, type StepNote, type Tuplet, type UpdateChange, VERSION, type VoicingFamily, type VoicingPatternDictionary, type WalkOptions, type WalkShapeOptions, type WalkSpec, absoluteBarreFret, add, addDur, addPassingTone, all, analyzeInKey, applyChordShape, applyRhythm, applySequence, arpeggioFor, arpeggioFromScale, arpeggioFromShape, arpeggioShapes, arpeggioSlotKey, ascendingIntervals, ascendingLinear, auditAllShapes, auditAllShapesIntegration, auditArpeggioShape, auditArpeggioShapeIntegration, auditChordShape, auditChordShapeFull, auditChordShapeIntegration, auditScaleShape, autoFingering, buildFrettedScale, buildFromScale, cagedPositionFor, canPlay, checkBarreFretOrigin, checkChordBuildLoss, checkChordMetadataCompleteness, checkChordTonesOnly, checkContainsChordGrip, checkCoversChord, checkFingerZeroOnMovable, checkFingeringComplete, checkFretSpan, checkGeometryMismatch, checkIdentifierCollision, checkIdentifyMismatch, checkNameCollision, checkNameUnique, checkOverridesTarget, checkPositionSpan, checkRepeatedFingerNoBarre, checkScaleBuildLoss, checkScaleMetadataCompleteness, checkStringsetMismatch, checkTuningMismatch, chordShapeGeometry, chordShapes, compareDur, connectSequences, createRegistry, descendingIntervals, descendingLinear, diatonicChords, displayRootFor, effectiveModeForSystem, exportIdentifierFor, filterChordTones, findFretInPosition, findNearestFret, findNote, fitToBars, flattenSequence, formatChordFrets, fourths, fretFor, fretboard, gapSegment, get, getMode, globalRegistry, gripBaseFret, grouping, idSlug, identifyChord, impliedStringSet, inferShapeContext, isDur, isModeCompatibleWithSystem, isMovable, isShapeCompatible, isShapeId, keySignature, keySignatureOf, lineBars, lineEquals, lineEvents, lineIssues, modeBuildRoot, modeShapes, multiplyDur, names, nearestPlacement, normalizeLine, noteAt, parentBoxForChordShape, parentScale, parseChordFrets, parseLine, parseScalePattern, place, placeScale, placements, playedStringSet, reduceDur, relabelOffset, relabelShape, relabelShapeToScale, relatedScales, remove, removeAll, resolveArpeggioForSlot, resolveShapeIdAlias, restrictPlacement, scalePlacements, scaleShapes, scaleTypeForChordType, scalesContainingChord, scoreShapeMatch, segmentFrom, serializeLine, shapeById, shapeId, sixths, slotForChordShape, stringIndex, stringNumber, subtractDur, sumDur, thirds, toAlphaTeX, toAsciiTab, visibleArpeggios, walk, walkPattern, walkShape, walkShapeIntervals, walkShapeMotif };
|