tonal-guitar 0.7.0 → 0.8.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +30 -0
- package/README.md +50 -5
- package/dist/index.d.mts +281 -104
- package/dist/index.d.ts +281 -104
- package/dist/index.js +2280 -394
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +2269 -394
- package/dist/index.mjs.map +1 -1
- package/docs/UPGRADING.md +144 -0
- package/docs/api/exercise-spec.md +346 -0
- package/docs/api/index.md +4 -2
- package/docs/api/keys.md +242 -0
- package/docs/api/lines.md +143 -4
- package/docs/api/output.md +3 -3
- package/docs/api/patterns.md +282 -3
- package/docs/api/placement.md +2 -0
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -7,6 +7,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|
|
7
7
|
|
|
8
8
|
## [Unreleased]
|
|
9
9
|
|
|
10
|
+
## [0.8.0] — 2026-11-19
|
|
11
|
+
|
|
12
|
+
### Changed (breaking)
|
|
13
|
+
|
|
14
|
+
[docs/UPGRADING.md](./docs/UPGRADING.md) says what to look for in your code and what to do about each of these, with the call before and after.
|
|
15
|
+
|
|
16
|
+
- **`connectSequences` joins two walks.** It kept its name and changed its meaning: `connectSequences({ notes, walk }, { notes, walk }, options?)` takes the two walks themselves, as lists of notes with the `WalkSpec` each was made with, and returns `{ bridge, next, kind, through }`: the notes to play between them, the second walk as it is played (whole, or less its first notes, so a turning note sounds once), whether the bridge carries the first walk on (`"extend"`) or goes the way the second walk goes (`"reach-back"`), and the note names a run went through. The options are `turn` (`"repeat"`, `"pivot"` or `"next"`, default `"next"`), `fill` (`"run"` or `"leap"`) and `through`. A bridge stops by the second walk's first note, and a run goes along the string through a scale or a chord, over frets neither walk plays. The old call, `connectSequences({ prev, next }, { dedupSeam, strategy })`, is read as a call with no notes: it returns `undefined` and does not throw. `undefined` is what `connectSequences` returns for any input it cannot read (a `direction` that is not one of `walk`'s four among them), so check for it before reading the result. `{ dedupSeam: false }` is `{ turn: "repeat" }`, and `{ dedupSeam: true }`, the old default, is `{ turn: "pivot" }`: the same notes are heard in each of the ten cases this library's examples compare, and not at every seam (about one in four of 10,000 generated pairs differs; see the upgrade notes). The types `ChainDirection`, `ConnectSequencesInput`, `ConnectorOptions`, `ConnectorStrategy` and `ConnectSequencesResult` are removed, so a TypeScript caller of the old form no longer compiles. The result is also `undefined` when a note at a joined seam has no finite `midi`, and when the notes of the two walks on the last note's string span more than 1,024 frets or are more than 1,025 different pitches.
|
|
17
|
+
- **`walk`'s default turn is named `"next"`.** `turn` is `"repeat" | "pivot" | "next"`, default `"next"`: `"next"` is the walk the 0.7.0 default `"no-repeat"` played, note for note, so a walk written without a `turn` plays what it played before. `"no-repeat"` is still read, as `"next"`, so a stored `Segment.walk` keeps its meaning, and `WalkSpec.turn` still takes it in TypeScript, deprecated; it is not in the `Turn` type, which `connectSequences` and `chain` take; `"pivot"` is new (below). Write `"next"`.
|
|
18
|
+
|
|
19
|
+
### Changed
|
|
20
|
+
|
|
21
|
+
- `walk` returns `[]` for a scale or an option that throws when it is read, and for a scale that is not an object. It used to throw.
|
|
22
|
+
|
|
23
|
+
### Added
|
|
24
|
+
|
|
25
|
+
- Key helpers: `orderKeys(keys, order, startKey?)` puts keys in fourths, fifths, half steps or as listed (`KeyOrder`: `"fourths"`, `"fifths"`, `"half-step"`, `"listed"`); `keyShift(from, to)` and `normalizeKeyShift(semitones)` give the distance between two keys as a whole number from -6 to 5; `spellTonic(pc, prefer, mode?)` names a pitch class with flats, with sharps or as the key with that tonic is written; `moveKeyBy(key, semitones)` moves a key name and keeps its form (`"A minor"` by 1 is `"Bb minor"`); `slideOffset(low, high, semitones, fretCount?)` is how far written material slides to stay on the neck. A key is a string `keySignatureOf` reads; each gives `undefined` for what is not a key and for a number that is not whole, and none throws. See [docs/api/keys.md](./docs/api/keys.md).
|
|
26
|
+
- `keyRun(parts, options?)` joins one part for each key into the segments of a line, with a gap between keys (`between`, `meter`) and the key's name above its first note (`label`). It gives `undefined` for a gap that does not fill a whole number of bars of its own meter (a rest of 3/2, 5/4, 1/3 or 1/7 in 4/4), since every key after it would start off the bar line. Types: `KeyRunPart`, `KeyRunOptions`.
|
|
27
|
+
- `chain(segments, options)` joins the segments of a line with a bridge segment at each turn, by the rule `connectSequences` applies, once at each seam (`ChainOptions`: `tuning`, `turn`, `fill`, `through`, `rhythm`). `Segment.bridge` (`"extend"` or `"reach-back"`) marks a segment `chain` added. It is a new optional field and the stored form stays `"tonal-guitar/line@1"`, which keeps `bridge` and which 0.7.0 reads without it; `lineIssues` reports a `bridge` that is not one of the two values, and one on a gap, as a `segment` issue. A bridge note on a fret neither segment plays is `{ string, fret, midi, pc }`, as `connectSequences` gives it. When a segment gives up its first steps at a turn, the first chord symbol and the first text on them move to the step that now comes first, unless it has its own; marks and fingering go with the notes. See [docs/api/lines.md](./docs/api/lines.md#chain).
|
|
28
|
+
- `fitSegments(segments, meter, options?)` is `fitToBars` for a pass of several segments, such as one `chain` made: the last note is held to the beat and the bar is filled once, for the whole pass. See [docs/api/lines.md](./docs/api/lines.md#fitsegments).
|
|
29
|
+
- `walk`: `turn: "pivot"` plays the turning note once and begins the way back on it (59 notes for the E shape of A major in thirds, up and down, where `"repeat"` plays 60 and `"next"` 58). `count` stops a walk after that many notes (a whole number from 1 to 4,096). `ends: "turn"` makes a walk turn at each end of the shape until `count` notes, and needs `count`. `after: { notes, shape? }` carries on from another walk: from the first position past the last note it played, the way it was going, or the other way when the shape has none left, so a line through changes needs no loop of the caller's own. `start` and `end: "root"` are refused with `after` and with `count` respectively. See [docs/api/patterns.md](./docs/api/patterns.md#walk).
|
|
30
|
+
- `Turn`, `Fill`, `JoinKind`, `WalkedNotes`, `BridgeNote`, `ConnectOptions` and `ConnectResult` types, for `walk` and `connectSequences`.
|
|
31
|
+
- `TabNote` (`{ string, fret, midi }`): what the note form of `toAlphaTeX`, `toAsciiTab` and `walk`'s `after.notes` read of a note. Their parameters now take `TabNote` lists where they took `FrettedNote` lists, so a list joined by `connectSequences` (`[...notes, ...result.bridge, ...result.next]`, where a bridge note can be a fret neither walk plays) goes straight in. Every call that compiled before still compiles.
|
|
32
|
+
- API pages: Keys (`docs/api/keys.md`) and Exercise spec (`docs/api/exercise-spec.md`), a `connectSequences` section on the Patterns page, `chain`, `fitSegments` and `bridge` on the Lines page, and what `nearestPlacement` answers when a caller asks for the "nearest" or "closest" shape on the Placement page.
|
|
33
|
+
|
|
34
|
+
### Experimental
|
|
35
|
+
|
|
36
|
+
These may change in any release, including in a way that stops a stored spec from being read; see [docs/api/exercise-spec.md](./docs/api/exercise-spec.md).
|
|
37
|
+
|
|
38
|
+
- `ExerciseSpec` (`"tonal-guitar/exercise@0"`): a whole exercise as one plain object, with `validateExerciseSpec(spec)`, which lists what is wrong with one (`ExerciseIssue`, `ExerciseIssueCode`) and needs no Tonal.js peer, and `buildExercise(spec, options?)`, which calls the pieces of the other pages in order (placement, `walk`, `applyRhythm`, `chain` when the spec joins its boxes with a bridge, `fitSegments`, `keyRun`) and returns `{ line, issues }`: all or nothing, so any issue leaves `line` `undefined` (`BuildExerciseOptions`, `ExerciseResult`). Besides shape and bounds, the check refuses a walk with `ends: "turn"` and no `count` or with `end: "root"` and a `count`, and a spec whose keys, boxes and turning walk's `count` ask for more than the 200,000 steps a line holds; and `buildExercise` refuses a position given by `number` with no `placement.system` in a key where more than one system has that number. A field the check does not know is an issue (`keys.lable is not a field of keys`), so a misspelled field is not dropped silently. A scale whose name begins with `minor` or `major` (`"minor pentatonic"`, `"major blues"`) is written with that key's signature, however the key is listed. Parts of the type: `ExerciseMaterial`, `ExercisePlacement`, `ExerciseTime`, `ExerciseKeys`.
|
|
39
|
+
|
|
10
40
|
## [0.7.0] — 2026-11-17
|
|
11
41
|
|
|
12
42
|
### Added
|
package/README.md
CHANGED
|
@@ -467,13 +467,55 @@ walk(scale, { motif: [1, 3], start: "lowest-root", end: "root" });
|
|
|
467
467
|
| ----------- | ------------------------------------------------------- | ------- |
|
|
468
468
|
| `motif` | `[1]` | Steps of one statement, 1-based from the statement's own position (0 or a negative number reaches back). An empty or unset motif is the plain walk |
|
|
469
469
|
| `direction` | `"up"` | `"up"`, `"down"`, `"up-down"` or `"down-up"` |
|
|
470
|
-
| `turn` | `"
|
|
470
|
+
| `turn` | `"next"` | At the turn of a walk that goes there and back: `"repeat"` plays the turning note twice, `"pivot"` once with the way back beginning on it, `"next"` once with the way back beginning on the next note |
|
|
471
471
|
| `start` | `"lowest"` going up first, `"highest"` going down first | `"lowest"`, `"lowest-root"`, `"highest"` or `"highest-root"` |
|
|
472
472
|
| `end` | `"where-it-stops"` | `"root"` appends the notes to the nearest root, the root included |
|
|
473
473
|
| `stride` | `1` | Positions the statement moves between statements |
|
|
474
474
|
| `index` | `"pitch-order"` | `"degree"` lays notes out by degree across octaves and leaves a hole where a degree has no note |
|
|
475
|
+
| `after` | none | `{ notes, shape? }`: carry on from another walk, from the first position past its last note, the way it was going. Not with `start` |
|
|
476
|
+
| `count` | none | Stop after this many notes, a whole number from 1 to 4,096 |
|
|
477
|
+
| `ends` | `"stop"` | At an end of the shape, `"turn"` turns and goes the other way until `count` notes; it needs `count` |
|
|
475
478
|
|
|
476
|
-
A leg ends when a statement does not fit. Going down plays the motif from each position and moves down, unlike `walkPattern`'s `"down"`. `walkShapeMotif(scale, [])` is now the plain walk. See [docs/api/patterns.md](./docs/api/patterns.md) for the details.
|
|
479
|
+
`"no-repeat"`, the name `"next"` had before `"pivot"` existed, is still read as `"next"`. A leg ends when a statement does not fit. Going down plays the motif from each position and moves down, unlike `walkPattern`'s `"down"`. `walkShapeMotif(scale, [])` is now the plain walk. See [docs/api/patterns.md](./docs/api/patterns.md) for the details.
|
|
480
|
+
|
|
481
|
+
#### `connectSequences(before: WalkedNotes, next: WalkedNotes, options?: ConnectOptions) => ConnectResult | undefined`
|
|
482
|
+
|
|
483
|
+
Joins two walks you already made: the notes to play between them, and the second walk as it is played, with its first notes left out where the turn would sound twice. Each argument is a walk's notes and the `WalkSpec` it was made with (its `direction` and `motif` are read). It plays neither walk, takes no tuning, never throws and changes nothing it is given.
|
|
484
|
+
|
|
485
|
+
```js
|
|
486
|
+
import { connectSequences, walk, get, buildFrettedScale } from "tonal-guitar";
|
|
487
|
+
|
|
488
|
+
const walked = (shape, spec) => ({
|
|
489
|
+
notes: walk(buildFrettedScale(get(shape), "A"), spec),
|
|
490
|
+
walk: spec,
|
|
491
|
+
});
|
|
492
|
+
|
|
493
|
+
// A major: the E shape in thirds going up, then the D shape in thirds coming down
|
|
494
|
+
const before = walked("E Shape", { motif: [1, 3], direction: "up" });
|
|
495
|
+
const next = walked("D Shape", { motif: [1, 3], direction: "down" });
|
|
496
|
+
|
|
497
|
+
const joined = connectSequences(before, next);
|
|
498
|
+
if (joined === undefined) throw new Error("the two walks could not be read");
|
|
499
|
+
const { bridge, next: rest, kind, through } = joined;
|
|
500
|
+
// kind => "extend"
|
|
501
|
+
// bridge => 5.1 9.1 7.1 10.1 (as fret.string: string 1 is the high E)
|
|
502
|
+
// rest => 28 notes: 9.1 10.2 7.1 9.2 ... (the D shape's walk less its first two notes)
|
|
503
|
+
// through => ["G#", "A", "B", "C#", "D", "E", "F#"]
|
|
504
|
+
```
|
|
505
|
+
|
|
506
|
+
Play `before.notes`, `bridge`, then `rest`. The options are `turn` (`"repeat"`, `"pivot"` or `"next"`, the default, as for `walk`), `fill` (`"run"`, the default, goes along the string through the scale; `"leap"` uses only the notes the two walks play) and `through` (the note names a run goes through). The result is `undefined` for input it cannot read, and a call in the form of 0.7.0 is such input. See [docs/api/patterns.md](./docs/api/patterns.md#connectsequences), and [docs/UPGRADING.md](./docs/UPGRADING.md) for what changed.
|
|
507
|
+
|
|
508
|
+
### Keys, chains and the exercise spec
|
|
509
|
+
|
|
510
|
+
**Keys.** `orderKeys`, `keyShift`, `normalizeKeyShift`, `spellTonic`, `moveKeyBy` and `slideOffset` answer the small questions of an exercise played through several keys: which key comes next (in fourths, fifths, half steps or as listed), how far one is from another (a whole number from -6 to 5), what to call a pitch class (flats, sharps or as the key is written), a key name moved by semitones, and how far written material slides to stay on the neck. A key is a string `keySignatureOf` reads (`"A minor"`, `"D dorian"`); each gives `undefined` for what is not a key and for a number that is not whole. See [docs/api/keys.md](./docs/api/keys.md).
|
|
511
|
+
|
|
512
|
+
**`keyRun(parts, options?)`** joins one part for each key (a key and its segments) into the segments of a line, with a gap between keys and the key's name above its first note. It does not move the notes: each key is placed from its shape. See [docs/api/keys.md](./docs/api/keys.md#keyrun).
|
|
513
|
+
|
|
514
|
+
**`chain(segments, options)`** joins the segments of a line with a bridge segment at each turn, by the rule `connectSequences` uses; `Segment.bridge` marks the segments it adds. See [docs/api/lines.md](./docs/api/lines.md#chain).
|
|
515
|
+
|
|
516
|
+
**`fitSegments(segments, meter, options?)`** is `fitToBars` for a pass of several segments, such as one `chain` made: the last note is held to the beat and the bar is filled once for the whole pass. See [docs/api/lines.md](./docs/api/lines.md#fitsegments).
|
|
517
|
+
|
|
518
|
+
**The exercise spec (experimental).** `ExerciseSpec` is a whole exercise as one plain object (what is played, where on the neck, how it is walked, in what time and through which keys); `validateExerciseSpec(spec)` lists what is wrong with one and `buildExercise(spec)` builds its `Line`. It may change in any release, including in a way that stops a stored spec from being read. See [docs/api/exercise-spec.md](./docs/api/exercise-spec.md).
|
|
477
519
|
|
|
478
520
|
### Sequences
|
|
479
521
|
|
|
@@ -551,7 +593,7 @@ parseScalePattern("5-8,5-7,5-7,5-7,5-8,5-8");
|
|
|
551
593
|
|
|
552
594
|
### Output Formatters
|
|
553
595
|
|
|
554
|
-
#### `toAlphaTeX(notes:
|
|
596
|
+
#### `toAlphaTeX(notes: TabNote[], options?: AlphaTexOptions) => string`
|
|
555
597
|
|
|
556
598
|
`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
599
|
|
|
@@ -592,7 +634,7 @@ keySignature("H"); // => undefined
|
|
|
592
634
|
|
|
593
635
|
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
636
|
|
|
595
|
-
#### `toAsciiTab(notes:
|
|
637
|
+
#### `toAsciiTab(notes: TabNote[], options?: AsciiTabOptions) => string`
|
|
596
638
|
|
|
597
639
|
Format notes as ASCII tablature:
|
|
598
640
|
|
|
@@ -882,9 +924,12 @@ The package exports these TypeScript interfaces:
|
|
|
882
924
|
- `InferenceProbe` — normalised internal probe used by the scoring core
|
|
883
925
|
- `ScoreBreakdown` — transparent per-term score breakdown on each `InferenceCandidate`
|
|
884
926
|
- `WalkOptions` — options for `walkPattern`
|
|
885
|
-
- `WalkSpec` — options for `walk`
|
|
927
|
+
- `WalkSpec`, `Turn` — options for `walk` and the three values of its `turn`
|
|
886
928
|
- `KeyMode`, `KeySignature` — the mode argument and the result of `keySignature`
|
|
887
929
|
- `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`
|
|
930
|
+
- `KeyOrder` — the `order` of `orderKeys`; `KeyRunPart`, `KeyRunOptions` — the parts and options of `keyRun` (see [docs/api/keys.md](./docs/api/keys.md))
|
|
931
|
+
- `WalkedNotes`, `ConnectOptions`, `ConnectResult`, `BridgeNote`, `Fill`, `JoinKind` — the arguments and result of `connectSequences`; `ChainOptions` — options of `chain`
|
|
932
|
+
- `ExerciseSpec`, `ExerciseMaterial`, `ExercisePlacement`, `ExerciseTime`, `ExerciseKeys`, `ExerciseIssue`, `ExerciseIssueCode`, `BuildExerciseOptions`, `ExerciseResult` — the experimental exercise spec (see [docs/api/exercise-spec.md](./docs/api/exercise-spec.md))
|
|
888
933
|
- `SequenceOptions` — options for `applySequence`
|
|
889
934
|
- `AlphaTexOptions` — options for `toAlphaTeX`
|
|
890
935
|
- `AsciiTabOptions` — options for `toAsciiTab`
|
package/dist/index.d.mts
CHANGED
|
@@ -191,6 +191,17 @@ declare function shapeById(id: string, options?: {
|
|
|
191
191
|
* Follows the ScaleType/ChordType registry pattern from Tonal.js.
|
|
192
192
|
*/
|
|
193
193
|
|
|
194
|
+
/**
|
|
195
|
+
* What the note form of `toAlphaTeX`, `toAsciiTab` and `walk`'s
|
|
196
|
+
* `after.notes` read of a note: where it is played, and its pitch. A
|
|
197
|
+
* `FrettedNote` is one, and so is every note of `connectSequences`' `bridge`
|
|
198
|
+
* and `next`, so a joined list goes straight into each.
|
|
199
|
+
*/
|
|
200
|
+
interface TabNote {
|
|
201
|
+
string: number;
|
|
202
|
+
fret: number;
|
|
203
|
+
midi: number;
|
|
204
|
+
}
|
|
194
205
|
/**
|
|
195
206
|
* One fretted note. A note can be asked four things, and each has one field
|
|
196
207
|
* (spec §1, decisions D-003); no existing field changes meaning:
|
|
@@ -1026,7 +1037,7 @@ declare function autoFingering(shape: Omit<ChordShape, "fingers" | "barres">, ro
|
|
|
1026
1037
|
barres: Barre[];
|
|
1027
1038
|
};
|
|
1028
1039
|
|
|
1029
|
-
declare const VERSION = "0.
|
|
1040
|
+
declare const VERSION = "0.8.0";
|
|
1030
1041
|
|
|
1031
1042
|
/**
|
|
1032
1043
|
* Shape visual/quality audit checks.
|
|
@@ -1555,6 +1566,12 @@ declare function walkShapeIntervals(scale: FrettedScale, intervalSize: number, o
|
|
|
1555
1566
|
*/
|
|
1556
1567
|
declare function walkPattern(scale: FrettedScale, pattern: number[], options?: WalkOptions): FrettedNote[];
|
|
1557
1568
|
|
|
1569
|
+
/**
|
|
1570
|
+
* What a walk does at a turn: `"repeat"` sounds the turning note twice,
|
|
1571
|
+
* `"pivot"` once with the way back beginning on it, `"next"` once with the
|
|
1572
|
+
* way back beginning on the next note.
|
|
1573
|
+
*/
|
|
1574
|
+
type Turn = "repeat" | "pivot" | "next";
|
|
1558
1575
|
/** Options of `walk` (spec §2). */
|
|
1559
1576
|
interface WalkSpec {
|
|
1560
1577
|
/**
|
|
@@ -1566,8 +1583,17 @@ interface WalkSpec {
|
|
|
1566
1583
|
motif?: number[];
|
|
1567
1584
|
/** Default "up". */
|
|
1568
1585
|
direction?: "up" | "down" | "up-down" | "down-up";
|
|
1569
|
-
/**
|
|
1570
|
-
|
|
1586
|
+
/**
|
|
1587
|
+
* At the turn of a walk that goes there and back, and at every turn of a
|
|
1588
|
+
* walk with `ends: "turn"`. Default "next". (In 0.7.0 and earlier the
|
|
1589
|
+
* values were "repeat" and "no-repeat", default "no-repeat".)
|
|
1590
|
+
*
|
|
1591
|
+
* `"no-repeat"` is the name `"next"` had in 0.7.0: still read, as `"next"`,
|
|
1592
|
+
* and deprecated (write `"next"`). A walk recorded with it comes back from
|
|
1593
|
+
* `normalizeLine` and `parseLine` as written. `Turn`, the turn of
|
|
1594
|
+
* `connectSequences` and `chain`, does not have it.
|
|
1595
|
+
*/
|
|
1596
|
+
turn?: Turn | "no-repeat";
|
|
1571
1597
|
/** Default "lowest" when the first leg goes up, "highest" when it goes down. */
|
|
1572
1598
|
start?: "lowest" | "lowest-root" | "highest" | "highest-root";
|
|
1573
1599
|
/** Default "where-it-stops". */
|
|
@@ -1580,6 +1606,19 @@ interface WalkSpec {
|
|
|
1580
1606
|
stride?: number;
|
|
1581
1607
|
/** Default "pitch-order". */
|
|
1582
1608
|
index?: "pitch-order" | "degree";
|
|
1609
|
+
/**
|
|
1610
|
+
* Carry on from another walk: the notes it played, in order, and the shape
|
|
1611
|
+
* it was walked on when the caller has it. Only each note's `midi` is read,
|
|
1612
|
+
* so a `TabNote` will do (a list joined by `connectSequences` included).
|
|
1613
|
+
*/
|
|
1614
|
+
after?: {
|
|
1615
|
+
notes: readonly TabNote[];
|
|
1616
|
+
shape?: FrettedScale;
|
|
1617
|
+
};
|
|
1618
|
+
/** Stop after this many notes. A whole number from 1 to 4096. */
|
|
1619
|
+
count?: number;
|
|
1620
|
+
/** At an end of the shape: stop, or turn and go the other way. Default "stop". "turn" needs `count`. */
|
|
1621
|
+
ends?: "stop" | "turn";
|
|
1583
1622
|
}
|
|
1584
1623
|
/**
|
|
1585
1624
|
* Walk a motif up, down or both through a scale (spec §2).
|
|
@@ -1596,6 +1635,13 @@ interface WalkSpec {
|
|
|
1596
1635
|
* walk can be `[]` when every statement touches one, and a walk with a root
|
|
1597
1636
|
* start begins on the first statement that is whole, which need not be on a
|
|
1598
1637
|
* root.
|
|
1638
|
+
*
|
|
1639
|
+
* At a turn (exercise-engine-keys spec 12.1) `"repeat"` begins the way back
|
|
1640
|
+
* on the turning note's own position, `"pivot"` does the same and leaves out
|
|
1641
|
+
* the first note the way back sounds, and `"next"` begins on the next
|
|
1642
|
+
* position. `count` stops the walk after that many notes; with
|
|
1643
|
+
* `ends: "turn"` the walk turns at each end until it has them (spec 12.2).
|
|
1644
|
+
* `after` starts the walk past the last note of another walk (spec 12.3).
|
|
1599
1645
|
*/
|
|
1600
1646
|
declare function walk(scale: FrettedScale, spec?: WalkSpec): FrettedNote[];
|
|
1601
1647
|
|
|
@@ -1668,104 +1714,6 @@ declare function applySequence(scale: FrettedScale, sequence: number[], options?
|
|
|
1668
1714
|
*/
|
|
1669
1715
|
declare function flattenSequence(passes: FrettedNote[][]): FrettedNote[];
|
|
1670
1716
|
|
|
1671
|
-
/**
|
|
1672
|
-
* Connector algorithm — bridges adjacent chain entries across CAGED or any
|
|
1673
|
-
* compatible scale shapes.
|
|
1674
|
-
*
|
|
1675
|
-
* This module sits in the "zero Tonal deps" dependency tier and imports only:
|
|
1676
|
-
* - `FrettedScale`, `FrettedNote` from `./shape` (types)
|
|
1677
|
-
* - `walkShapeMotif` from `./walker` (function)
|
|
1678
|
-
*/
|
|
1679
|
-
|
|
1680
|
-
type ChainDirection = "ascending" | "descending";
|
|
1681
|
-
interface ConnectSequencesInput {
|
|
1682
|
-
prev: {
|
|
1683
|
-
/** The full fretted scale the previous entry was walked over. */
|
|
1684
|
-
scale: FrettedScale;
|
|
1685
|
-
/** The actual last note prev emitted (time-order, not pitch-order). */
|
|
1686
|
-
lastNote: FrettedNote;
|
|
1687
|
-
/** Which way prev's motif was walked. */
|
|
1688
|
-
direction: ChainDirection;
|
|
1689
|
-
};
|
|
1690
|
-
next: {
|
|
1691
|
-
/** The full fretted scale the next entry will be walked over. */
|
|
1692
|
-
scale: FrettedScale;
|
|
1693
|
-
/** Motif used to walk next, e.g. [1] linear, [1,3] thirds, [1,2,3,4] groups. */
|
|
1694
|
-
motif: number[];
|
|
1695
|
-
/** Which way next's motif is being walked. */
|
|
1696
|
-
direction: ChainDirection;
|
|
1697
|
-
};
|
|
1698
|
-
}
|
|
1699
|
-
interface ConnectorOptions {
|
|
1700
|
-
/**
|
|
1701
|
-
* Connector strategy. Currently only `"auto"` is supported — the §3.1
|
|
1702
|
-
* truth table picks `"none"`, `"extend"`, or `"reach-back"`, and the
|
|
1703
|
-
* choice is reported back in `ConnectSequencesResult.strategy`. The
|
|
1704
|
-
* variant labels `"linear"` and `"motif-extend"` are reserved for future
|
|
1705
|
-
* releases and are intentionally absent from the type until implemented.
|
|
1706
|
-
*/
|
|
1707
|
-
strategy?: "auto";
|
|
1708
|
-
/**
|
|
1709
|
-
* Drop next's first note when it duplicates the physical position of the
|
|
1710
|
-
* connector's last note (or, in reach-back, of prev's last note).
|
|
1711
|
-
* Default: true.
|
|
1712
|
-
*/
|
|
1713
|
-
dedupSeam?: boolean;
|
|
1714
|
-
}
|
|
1715
|
-
type ConnectorStrategy = "none" | "extend" | "reach-back";
|
|
1716
|
-
interface ConnectSequencesResult {
|
|
1717
|
-
/** Bridge notes to play between prev's last and next's first. May be empty. */
|
|
1718
|
-
connector: FrettedNote[];
|
|
1719
|
-
/**
|
|
1720
|
-
* Notes to play for the next entry, post-connector. In "none" this is the
|
|
1721
|
-
* natural walk of next; in "extend" it's the natural walk minus the dedup'd
|
|
1722
|
-
* head; in "reach-back" it's a re-walk over the combined scale starting at
|
|
1723
|
-
* prev's seam.
|
|
1724
|
-
*/
|
|
1725
|
-
nextNotes: FrettedNote[];
|
|
1726
|
-
/** Strategy actually used (for debugging / lab UI display). */
|
|
1727
|
-
strategy: ConnectorStrategy;
|
|
1728
|
-
}
|
|
1729
|
-
/**
|
|
1730
|
-
* Given two adjacent chain entries, returns the bridge phrase that connects
|
|
1731
|
-
* them across the seam, so that exercises can chain across CAGED (or any
|
|
1732
|
-
* compatible) shapes and play as one continuous run.
|
|
1733
|
-
*
|
|
1734
|
-
* Output shape — `{ connector, nextNotes, strategy }`:
|
|
1735
|
-
*
|
|
1736
|
-
* - **`strategy: "none"`** — same-direction chains (asc→asc, desc→desc) and
|
|
1737
|
-
* degenerate inputs. `connector` is `[]`; `nextNotes` is the natural walk
|
|
1738
|
-
* of `next.scale` (or `[]` for degenerate inputs).
|
|
1739
|
-
*
|
|
1740
|
-
* - **`strategy: "extend"`** — direction reverses, next sits beyond prev in
|
|
1741
|
-
* the prev-walk direction (asc→desc with next higher, or desc→asc with
|
|
1742
|
-
* next lower). `connector` is a **same-string** pickup — motif periods
|
|
1743
|
-
* walked along `prev.lastNote.string` from the combined prev∪next scale,
|
|
1744
|
-
* in prev's direction, keeping pairs whose final note is past the seam.
|
|
1745
|
-
* `nextNotes` is the natural walk of `next.scale` with an overlap dedup
|
|
1746
|
-
* that drops the first pair when it duplicates the bridge's last pair.
|
|
1747
|
-
*
|
|
1748
|
-
* - **`strategy: "reach-back"`** — direction reverses, next sits "on the
|
|
1749
|
-
* wrong side" or overlaps prev (asc→desc with next not strictly higher,
|
|
1750
|
-
* or desc→asc with next not strictly lower). Same-string bridge as above,
|
|
1751
|
-
* but walked in `next.direction` and **inclusive** of the seam pitch —
|
|
1752
|
-
* the seam note anchors the new run (musical pivot). `nextNotes` and
|
|
1753
|
-
* overlap dedup work identically to `extend`.
|
|
1754
|
-
*
|
|
1755
|
-
* Both `extend` and `reach-back` now emit a non-empty `connector` in the
|
|
1756
|
-
* typical case. The pre-2026-05 contract returned `connector: []` for
|
|
1757
|
-
* reach-back; that semantics was superseded when lab integration testing
|
|
1758
|
-
* showed it didn't produce coherent bridges. See `connect.test.ts` and
|
|
1759
|
-
* `connect.examples.test.ts` for the worked scenarios.
|
|
1760
|
-
*
|
|
1761
|
-
* The function never throws. All degenerate inputs resolve to a graceful
|
|
1762
|
-
* return of `{ connector: [], nextNotes: [], strategy: "none" }`.
|
|
1763
|
-
*
|
|
1764
|
-
* @note AlphaTeX bar alignment for connector notes is out of MVP scope.
|
|
1765
|
-
* Bars re-flow automatically when connector notes are inserted.
|
|
1766
|
-
*/
|
|
1767
|
-
declare function connectSequences(input: ConnectSequencesInput, options?: ConnectorOptions): ConnectSequencesResult;
|
|
1768
|
-
|
|
1769
1717
|
/**
|
|
1770
1718
|
* Notation parsing and formatting for guitar.
|
|
1771
1719
|
*
|
|
@@ -1919,6 +1867,11 @@ interface Segment {
|
|
|
1919
1867
|
* its own: it is written in those of the segment it leads into (5.3).
|
|
1920
1868
|
*/
|
|
1921
1869
|
gap?: boolean;
|
|
1870
|
+
/**
|
|
1871
|
+
* Notes `chain` added between two walks. Not on a gap. A bridge has no
|
|
1872
|
+
* `from` and no `walk`.
|
|
1873
|
+
*/
|
|
1874
|
+
bridge?: "extend" | "reach-back";
|
|
1922
1875
|
}
|
|
1923
1876
|
interface Line {
|
|
1924
1877
|
/** Low string first, as everywhere in this library. */
|
|
@@ -2007,6 +1960,9 @@ declare function toAlphaTeX(line: Line, options?: LineTexOptions): string;
|
|
|
2007
1960
|
* An empty outer array (`[]`) takes the flat path and produces the same
|
|
2008
1961
|
* empty-ish output as before (R-5.2).
|
|
2009
1962
|
*
|
|
1963
|
+
* Each note is read for its `string` and `fret` only, so any `TabNote` will
|
|
1964
|
+
* do: a `FrettedNote`, or a note of `connectSequences`' `bridge` and `next`.
|
|
1965
|
+
*
|
|
2010
1966
|
* **Beat emission (grouped path):**
|
|
2011
1967
|
* - Group length 1 → `fret.string` (no parentheses, same as sequential).
|
|
2012
1968
|
* - Group length ≥ 2 → `(fret.string fret.string …)` (AlphaTeX simultaneous-beat
|
|
@@ -2018,7 +1974,7 @@ declare function toAlphaTeX(line: Line, options?: LineTexOptions): string;
|
|
|
2018
1974
|
* `notesPerBar`, `noteDurations`, and `rhythmPattern` all index by *beat (group)*,
|
|
2019
1975
|
* not by individual note. A single `rhythmPattern` entry applies to the whole strum.
|
|
2020
1976
|
*/
|
|
2021
|
-
declare function toAlphaTeX(notes:
|
|
1977
|
+
declare function toAlphaTeX(notes: TabNote[] | TabNote[][], options?: AlphaTexOptions): string;
|
|
2022
1978
|
|
|
2023
1979
|
interface AsciiTabOptions {
|
|
2024
1980
|
tuning?: string[];
|
|
@@ -2040,10 +1996,13 @@ interface AsciiTabOptions {
|
|
|
2040
1996
|
* `'-'.repeat(colWidth)`. Columns are joined with a `-` separator between them.
|
|
2041
1997
|
* An empty group emits all `-` cells of width 1.
|
|
2042
1998
|
*
|
|
1999
|
+
* Each note is read for its `string` and `fret` only, so any `TabNote` will
|
|
2000
|
+
* do: a `FrettedNote`, or a note of `connectSequences`' `bridge` and `next`.
|
|
2001
|
+
*
|
|
2043
2002
|
* **Backward compat:** flat input is normalised to singleton beats; for
|
|
2044
2003
|
* all-single-digit fret data this reproduces current output byte-for-byte (R-5.2).
|
|
2045
2004
|
*/
|
|
2046
|
-
declare function toAsciiTab(notes:
|
|
2005
|
+
declare function toAsciiTab(notes: TabNote[] | TabNote[][], options?: AsciiTabOptions): string;
|
|
2047
2006
|
|
|
2048
2007
|
type RhythmSlot = Dur | {
|
|
2049
2008
|
dur: Dur;
|
|
@@ -2154,6 +2113,16 @@ type Gap = "none" | {
|
|
|
2154
2113
|
* "none" and for anything invalid; never throws.
|
|
2155
2114
|
*/
|
|
2156
2115
|
declare function gapSegment(gap: Gap, meter: Meter): Segment | undefined;
|
|
2116
|
+
/**
|
|
2117
|
+
* A pass of several segments held and filled as `fitToBars` holds and fills
|
|
2118
|
+
* one list of steps, ended on the bar (spec 6). Each segment takes back the
|
|
2119
|
+
* steps at its own positions; the held note stays in the segment that holds
|
|
2120
|
+
* the last step and the added rests go on the last segment. `undefined` for
|
|
2121
|
+
* a meter that is not one, a segment that is not an object with a list of
|
|
2122
|
+
* steps, a gap segment, a segment with a meter of its own that is not
|
|
2123
|
+
* `meter`, and whatever `fitToBars` refuses for the same steps. Never throws.
|
|
2124
|
+
*/
|
|
2125
|
+
declare function fitSegments(segments: readonly Segment[], meter: Meter, options?: FitOptions): Segment[] | undefined;
|
|
2157
2126
|
|
|
2158
2127
|
/**
|
|
2159
2128
|
* A segment from a placement and the steps made of its notes (spec §6.3):
|
|
@@ -2248,6 +2217,214 @@ declare const MOTIFS: Readonly<{
|
|
|
2248
2217
|
}>;
|
|
2249
2218
|
type MotifId = keyof typeof MOTIFS;
|
|
2250
2219
|
|
|
2220
|
+
/** The order `orderKeys` puts keys in. */
|
|
2221
|
+
type KeyOrder = "fourths" | "fifths" | "half-step" | "listed";
|
|
2222
|
+
/** Keys in the order asked for, as the caller wrote them; `undefined` for input it cannot read. */
|
|
2223
|
+
declare function orderKeys(keys: readonly string[], order: KeyOrder, startKey?: string): string[] | undefined;
|
|
2224
|
+
/** A whole number of semitones folded to -6 to 5; `undefined` when it is not a whole number. */
|
|
2225
|
+
declare function normalizeKeyShift(semitones: number): number | undefined;
|
|
2226
|
+
/** The semitones from one key's tonic to another's, -6 to 5; `undefined` for a non-key. */
|
|
2227
|
+
declare function keyShift(from: string, to: string): number | undefined;
|
|
2228
|
+
/** A name for a pitch class: flats, sharps, or whichever the key's signature has fewer of. */
|
|
2229
|
+
declare function spellTonic(pc: number, prefer: "flats" | "sharps" | "key", mode?: KeyMode): string | undefined;
|
|
2230
|
+
/** A key name moved by semitones, in its own form ("Am" and 1 is "Bbm"). */
|
|
2231
|
+
declare function moveKeyBy(key: string, semitones: number): string | undefined;
|
|
2232
|
+
/** How far written material slides along the neck to move by `semitones` and stay on it. */
|
|
2233
|
+
declare function slideOffset(low: number, high: number, semitones: number, fretCount?: number): number | undefined;
|
|
2234
|
+
|
|
2235
|
+
/**
|
|
2236
|
+
* `keyRun`: per-key parts joined with gaps and labels (spec 4).
|
|
2237
|
+
*
|
|
2238
|
+
* This module is in the "zero Tonal deps" tier and imports only `./fit` and
|
|
2239
|
+
* `./line-layout` (values) and types from `./line`.
|
|
2240
|
+
*/
|
|
2241
|
+
|
|
2242
|
+
/** One key's segments. */
|
|
2243
|
+
interface KeyRunPart {
|
|
2244
|
+
key: string;
|
|
2245
|
+
segments: readonly Segment[];
|
|
2246
|
+
}
|
|
2247
|
+
interface KeyRunOptions {
|
|
2248
|
+
between?: Gap;
|
|
2249
|
+
meter?: Meter;
|
|
2250
|
+
label?: boolean;
|
|
2251
|
+
}
|
|
2252
|
+
/**
|
|
2253
|
+
* The parts joined into one list of segments, each segment a shallow copy
|
|
2254
|
+
* that gets its part's `key` when it has none; a gap between the parts and a
|
|
2255
|
+
* label on the first segment of each part when asked. `undefined` for input
|
|
2256
|
+
* it cannot read, and for a gap that does not fill a whole number of bars of
|
|
2257
|
+
* the meter `gapSegment` gives it (a rest of 3/2 or 5/4 in 4/4, or of 1/3 or
|
|
2258
|
+
* 1/7, which has no meter of its own), since every key after it would start
|
|
2259
|
+
* off the bar line; never throws and changes nothing it was given.
|
|
2260
|
+
*/
|
|
2261
|
+
declare function keyRun(parts: readonly KeyRunPart[], options?: KeyRunOptions): Segment[] | undefined;
|
|
2262
|
+
|
|
2263
|
+
type Fill = "run" | "leap";
|
|
2264
|
+
type JoinKind = "extend" | "reach-back";
|
|
2265
|
+
/** A walk as its caller made it, and how. */
|
|
2266
|
+
interface WalkedNotes {
|
|
2267
|
+
notes: readonly FrettedNote[];
|
|
2268
|
+
walk?: WalkSpec;
|
|
2269
|
+
}
|
|
2270
|
+
/** A note of one of the two walks, as given, or a fret between them that neither plays. */
|
|
2271
|
+
type BridgeNote = FrettedNote | {
|
|
2272
|
+
string: number;
|
|
2273
|
+
fret: number;
|
|
2274
|
+
midi: number;
|
|
2275
|
+
pc: string;
|
|
2276
|
+
};
|
|
2277
|
+
interface ConnectOptions {
|
|
2278
|
+
turn?: Turn;
|
|
2279
|
+
fill?: Fill;
|
|
2280
|
+
through?: readonly string[];
|
|
2281
|
+
}
|
|
2282
|
+
interface ConnectResult {
|
|
2283
|
+
bridge: BridgeNote[];
|
|
2284
|
+
next: FrettedNote[];
|
|
2285
|
+
through: string[];
|
|
2286
|
+
kind: JoinKind | "none";
|
|
2287
|
+
}
|
|
2288
|
+
/**
|
|
2289
|
+
* Two walks joined (spec 5): the notes to play between them, the next walk as
|
|
2290
|
+
* it is played (whole, or less its first notes at a turn), what a run went
|
|
2291
|
+
* through and the kind of bridge. It takes no tuning: each note carries its
|
|
2292
|
+
* `midi`. The two walks follow each other with nothing done when the last
|
|
2293
|
+
* leg before equals the first leg after, or either has no note (spec 5.2). `undefined` for
|
|
2294
|
+
* input it cannot read (spec 5.4): a walk that is not an object with a
|
|
2295
|
+
* `notes` list of notes with a whole-number string and fret, a `direction`
|
|
2296
|
+
* not of the four, options that are not an object with a known `turn` and
|
|
2297
|
+
* `fill` and 1 to 12 note names for `through`, or a note the rule needs
|
|
2298
|
+
* whose `midi` is not a finite number. Never throws; changes nothing given.
|
|
2299
|
+
*/
|
|
2300
|
+
declare function connectSequences(before: WalkedNotes, next: WalkedNotes, options?: ConnectOptions): ConnectResult | undefined;
|
|
2301
|
+
|
|
2302
|
+
interface ChainOptions {
|
|
2303
|
+
tuning: readonly string[];
|
|
2304
|
+
turn?: Turn;
|
|
2305
|
+
fill?: Fill;
|
|
2306
|
+
through?: readonly string[];
|
|
2307
|
+
rhythm?: Dur | RhythmCell;
|
|
2308
|
+
}
|
|
2309
|
+
/**
|
|
2310
|
+
* The segments joined (spec 5): a new list of the segments in order, with a
|
|
2311
|
+
* bridge segment at each seam that got one. A segment the rule left whole
|
|
2312
|
+
* comes back as the same object; one that gave up notes at the turn comes
|
|
2313
|
+
* back as a shallow copy with new `steps`. The first chord symbol and the
|
|
2314
|
+
* first text on the steps it gave up move to the step that now comes first
|
|
2315
|
+
* after them (a copy of it), unless that step has its own; their marks and
|
|
2316
|
+
* fingers go with them. A bridge note on a fret neither segment plays is
|
|
2317
|
+
* `{ string, fret, midi, pc }`, as `connectSequences` gives it. The seams are read left to right,
|
|
2318
|
+
* each on the segments as the seams before it left them. Two segments follow
|
|
2319
|
+
* each other with nothing done when either is a gap, has a section or a
|
|
2320
|
+
* repeat, when their meters, keys or tempos differ, when either has no `walk`
|
|
2321
|
+
* or a `direction` not of the four, when the last leg before is the first leg
|
|
2322
|
+
* after, when either has no sounding step, or when the last sounding step
|
|
2323
|
+
* before or the first after has more than one note (spec 5.2).
|
|
2324
|
+
*
|
|
2325
|
+
* `undefined` when `segments` is not a list of at most 200,000 objects with
|
|
2326
|
+
* `steps` lists, `options` is not an object, `tuning` is not 1 to 12 names
|
|
2327
|
+
* with an octave, `turn` or `fill` is not one of its values, `through` is
|
|
2328
|
+
* given and is not 1 to 12 note names, `rhythm` fails at a seam that gets a
|
|
2329
|
+
* bridge, a note's pitch cannot be read at a joined seam, or the result would
|
|
2330
|
+
* hold more than 200,000 steps. `chain` does not report what a run went
|
|
2331
|
+
* through: a host that shows it calls `connectSequences` on the same two
|
|
2332
|
+
* walks. Never throws; changes nothing given.
|
|
2333
|
+
*/
|
|
2334
|
+
declare function chain(segments: readonly Segment[], options: ChainOptions): Segment[] | undefined;
|
|
2335
|
+
|
|
2336
|
+
/**
|
|
2337
|
+
* @experimental A whole exercise as plain data.
|
|
2338
|
+
*/
|
|
2339
|
+
interface ExerciseSpec {
|
|
2340
|
+
$schema: "tonal-guitar/exercise@0";
|
|
2341
|
+
material: ExerciseMaterial;
|
|
2342
|
+
placement: ExercisePlacement;
|
|
2343
|
+
walk: Omit<WalkSpec, "after"> | Omit<WalkSpec, "after">[];
|
|
2344
|
+
time: ExerciseTime;
|
|
2345
|
+
keys: ExerciseKeys;
|
|
2346
|
+
}
|
|
2347
|
+
/** @experimental What is played. */
|
|
2348
|
+
type ExerciseMaterial = {
|
|
2349
|
+
kind: "scale";
|
|
2350
|
+
scaleType: string;
|
|
2351
|
+
} | {
|
|
2352
|
+
kind: "arpeggio";
|
|
2353
|
+
chordType: string;
|
|
2354
|
+
} | {
|
|
2355
|
+
kind: "shape";
|
|
2356
|
+
shapes: string[];
|
|
2357
|
+
};
|
|
2358
|
+
/** @experimental Where it is played. */
|
|
2359
|
+
interface ExercisePlacement {
|
|
2360
|
+
system?: string;
|
|
2361
|
+
positions?: PositionRequest[] | CagedPosition[];
|
|
2362
|
+
openStrings?: "keep" | "drop" | "raise";
|
|
2363
|
+
tuning?: string[];
|
|
2364
|
+
fretCount?: number;
|
|
2365
|
+
order?: "listed" | "lowest" | "nearest" | "nearest-previous";
|
|
2366
|
+
join?: "restart" | "bridge";
|
|
2367
|
+
turn?: Turn;
|
|
2368
|
+
fill?: Fill;
|
|
2369
|
+
through?: string[];
|
|
2370
|
+
}
|
|
2371
|
+
/** @experimental How it is played in time. */
|
|
2372
|
+
interface ExerciseTime {
|
|
2373
|
+
meter: Meter;
|
|
2374
|
+
rhythm: RhythmCellId | Dur | RhythmCell;
|
|
2375
|
+
feel?: Feel;
|
|
2376
|
+
tempo?: number;
|
|
2377
|
+
pass?: {
|
|
2378
|
+
holdLastNote?: boolean;
|
|
2379
|
+
fillBar?: boolean;
|
|
2380
|
+
};
|
|
2381
|
+
}
|
|
2382
|
+
/** @experimental Which keys, in what order. */
|
|
2383
|
+
interface ExerciseKeys {
|
|
2384
|
+
list: string[];
|
|
2385
|
+
order?: KeyOrder;
|
|
2386
|
+
start?: string;
|
|
2387
|
+
between?: Gap;
|
|
2388
|
+
label?: boolean;
|
|
2389
|
+
}
|
|
2390
|
+
/** @experimental What an issue is about. */
|
|
2391
|
+
type ExerciseIssueCode = "spec" | "schema" | "material" | "placement" | "walk" | "time" | "keys" | "key" | "rhythm" | "shape" | "box" | "notes" | "chain" | "fit" | "line";
|
|
2392
|
+
/** @experimental One thing wrong with a spec, or found while building it. */
|
|
2393
|
+
interface ExerciseIssue {
|
|
2394
|
+
code: ExerciseIssueCode;
|
|
2395
|
+
message: string;
|
|
2396
|
+
key?: number;
|
|
2397
|
+
part?: number;
|
|
2398
|
+
}
|
|
2399
|
+
/**
|
|
2400
|
+
* @experimental The issues in a spec's shape and bounds; `[]` when there are
|
|
2401
|
+
* none. Resolves no name, builds nothing, never throws. Each string is
|
|
2402
|
+
* checked for type and length before anything reads it, and the issues come
|
|
2403
|
+
* in the order of the type. A field it does not know is an issue of the
|
|
2404
|
+
* object it is in (a misspelled field would otherwise be dropped silently);
|
|
2405
|
+
* at most eight are named for one object.
|
|
2406
|
+
*/
|
|
2407
|
+
declare function validateExerciseSpec(spec: unknown): ExerciseIssue[];
|
|
2408
|
+
|
|
2409
|
+
/** @experimental Options of `buildExercise`. */
|
|
2410
|
+
interface BuildExerciseOptions {
|
|
2411
|
+
registry?: Registry;
|
|
2412
|
+
}
|
|
2413
|
+
/** @experimental A built line, or the issues that stopped it. */
|
|
2414
|
+
interface ExerciseResult {
|
|
2415
|
+
line: Line | undefined;
|
|
2416
|
+
issues: ExerciseIssue[];
|
|
2417
|
+
}
|
|
2418
|
+
/**
|
|
2419
|
+
* @experimental The line an exercise spec describes (spec 7.3), or the
|
|
2420
|
+
* issues that stopped it: all or nothing, so any issue gives `line:
|
|
2421
|
+
* undefined`. The issues of `validateExerciseSpec` come back unchanged;
|
|
2422
|
+
* after them, each stage that fails for a key adds an issue and the build
|
|
2423
|
+
* goes on to the next key, so every key's issues are listed. Never throws
|
|
2424
|
+
* and changes nothing it was given.
|
|
2425
|
+
*/
|
|
2426
|
+
declare function buildExercise(spec: ExerciseSpec, options?: BuildExerciseOptions): ExerciseResult;
|
|
2427
|
+
|
|
2251
2428
|
/**
|
|
2252
2429
|
* Arpeggio derivation and shape-scoring — pure tier (zero Tonal peer deps).
|
|
2253
2430
|
*
|
|
@@ -2981,4 +3158,4 @@ declare const SEQ_UP_DOWN: number[];
|
|
|
2981
3158
|
declare const SEQ_TRIAD_CLIMB: number[];
|
|
2982
3159
|
declare const SEQ_1357_DESC: number[];
|
|
2983
3160
|
|
|
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
|
|
3161
|
+
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 BridgeNote, type BuildExerciseOptions, 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 ChainOptions, type Changeset, type ChangesetChange, type ChangesetKind, type ChordGeometryDetails, type ChordScaleEntry, type ChordShape, type ChordShapeAuditResult, type ChordShapeFilter, type ConnectOptions, type ConnectResult, type ContainingScale, DADGAD, DEFAULT_SCALE_CORPUS, DESCENDING_THIRDS, DROP_D, type DiatonicChord, type Dur, type ExerciseIssue, type ExerciseIssueCode, type ExerciseKeys, type ExerciseMaterial, type ExercisePlacement, type ExerciseResult, type ExerciseSpec, type ExerciseTime, type Feel, type Fill, 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 JoinKind, type KeyAnalysis, type KeyMode, type KeyOrder, type KeyRunOptions, type KeyRunPart, 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 TabNote, type Tuplet, type Turn, type UpdateChange, VERSION, type VoicingFamily, type VoicingPatternDictionary, type WalkOptions, type WalkShapeOptions, type WalkSpec, type WalkedNotes, 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, buildExercise, buildFrettedScale, buildFromScale, cagedPositionFor, canPlay, chain, 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, fitSegments, fitToBars, flattenSequence, formatChordFrets, fourths, fretFor, fretboard, gapSegment, get, getMode, globalRegistry, gripBaseFret, grouping, idSlug, identifyChord, impliedStringSet, inferShapeContext, isDur, isModeCompatibleWithSystem, isMovable, isShapeCompatible, isShapeId, keyRun, keyShift, keySignature, keySignatureOf, lineBars, lineEquals, lineEvents, lineIssues, modeBuildRoot, modeShapes, moveKeyBy, multiplyDur, names, nearestPlacement, normalizeKeyShift, normalizeLine, noteAt, orderKeys, 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, slideOffset, slotForChordShape, spellTonic, stringIndex, stringNumber, subtractDur, sumDur, thirds, toAlphaTeX, toAsciiTab, validateExerciseSpec, visibleArpeggios, walk, walkPattern, walkShape, walkShapeIntervals, walkShapeMotif };
|