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 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.6.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
- * Render a sequence of fretted notes as an AlphaTeX string.
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 };