tonal-guitar 0.5.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 +48 -0
- package/LICENSE +21 -0
- package/README.md +53 -0
- package/dist/index.d.mts +992 -95
- package/dist/index.d.ts +992 -95
- package/dist/index.js +5428 -1321
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +5488 -1421
- package/dist/index.mjs.map +1 -1
- package/docs/UPGRADING.md +161 -0
- package/docs/api/arpeggios.md +487 -0
- package/docs/api/audit.md +240 -0
- package/docs/api/fretboard.md +122 -0
- package/docs/api/index.md +127 -0
- package/docs/api/integration.md +362 -0
- package/docs/api/lines.md +676 -0
- package/docs/api/output.md +439 -0
- package/docs/api/patterns.md +261 -0
- package/docs/api/placement.md +556 -0
- package/docs/api/sequences.md +208 -0
- package/docs/api/shapes.md +573 -0
- package/docs/api/transform.md +124 -0
- package/package.json +7 -6
package/CHANGELOG.md
CHANGED
|
@@ -7,6 +7,54 @@ 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
|
+
|
|
28
|
+
## [0.6.0] — 2026-11-17
|
|
29
|
+
|
|
30
|
+
### Added
|
|
31
|
+
|
|
32
|
+
- `ScaleShape.id` and `ChordShape.id` (inherited by `ArpeggioShape`): a permanent identity, separate from the display name. The 186 built-in shapes now carry an `id`, authored as a literal (`scale:caged:e-shape`, `chord:caged:e-shape-major`, `arpeggio:caged:e-shape-major`), so a result that returns a registered shape, such as an `inferShapeContext` candidate, shows the new field. A released id is never changed or reused.
|
|
33
|
+
- The ten CAGED scale boxes (`E Shape`, `Em Shape` and the rest) now carry `cagedPosition`, the letter in the name, so results that return one of them show the new field, and `scaleShapes.query({ cagedPosition })` finds them.
|
|
34
|
+
- `shapeId(kind, shape)`, `idSlug(text)`, `SHAPE_ID_ALIASES`, `resolveShapeIdAlias(id)` and the `ShapeKind` type: the id of a shape (its own `id`, else `kind:system:slug`), the slug formula (an empty slug for a value that is not a string, so neither throws), and the map from a retired id to its replacement (empty today).
|
|
35
|
+
- `isShapeId(value)`: whether a value may be a shape's id: 1 to 64 characters, each a lower-case letter, a digit, `:`, `.`, `_` or `-`. `createRegistry` leaves out a shape that carries an `id` outside that grammar (`invalid-shape`) and `npm run shapes:merge` refuses it; `add()` on the global registry does not check ids. A shape with no `id` whose name would make its id longer than 64 characters is refused when a changeset adds it or renames it to that name, and kept when it is already in the base. Every built-in id fits.
|
|
36
|
+
- `scaleShapes`: the scale registry as an object (`get`, `all`, `names`, `add`, `remove`, `removeAll`, `query`) over the same state as the module functions, which are unchanged. `scaleShapes.query` takes a `ScaleShapeFilter` (`system`, `quality`, `cagedPosition`, `chordType`, `tags`, `parentShape`). The filters of `chordShapes.query` and `arpeggioShapes.query` are exported as the `ChordShapeFilter` and `ArpeggioShapeFilter` types.
|
|
37
|
+
- `createRegistry(base?, changes?)`, `globalRegistry` and `shapeById(id, options?)`, with the `Registry`, `ShapeSet`, `ShapeRef`, `RegistrySource`, `RegistryIssue` and `RegistryIssueCode` types: the registry as an immutable value. A changeset applies whole or not at all, and a refused one is listed in `issues`, including the two reference rules of `shapes:merge` (`inbound-reference`, `overrides-target`), which are read on the shapes the changeset leaves. A shape the builders could not read is left out of a base, or refuses its changeset (`invalid-shape`); a base holds one shape of a name in each kind (a later one is left out as `name-collision`); a base or a list that cannot be read is listed as `invalid-base`; and no plain data in a stored base or changeset makes `createRegistry` throw. A shape a changeset adds with no `id` is stored with the formula's, as `shapes:merge` writes it. Within one changeset a name or an id cannot pass from one shape to another, and an id cannot be unset.
|
|
38
|
+
- A `registry` option on `resolveArpeggioForSlot`, `visibleArpeggios`, `parentBoxForChordShape`, `arpeggioFor`, `modeShapes` and `inferShapeContext` (`InferenceOptions.registry`). Without it, they read the global registry as before.
|
|
39
|
+
- `BuildOptions.fretCount`: the highest fret on the neck. Without it, builds are unchanged; a value that is not a whole number of 0 or more gives an empty result with the new `FrettedScaleReason` `"invalid-fret-count"`. `applyChordShape` with it leaves a string that has no fret without a finger, drops a barre above the neck, and on a grip the neck cut strings from keeps a barre only where it still holds a string.
|
|
40
|
+
- `place(shape, root, options?)`, the `Placement` type and `NoPlacement`: a shape in a key as one value, with `shapeId`, `tonic`, `buildRoot`, `lowFret`, `highFret`, `span`, `usesOpenStrings`, `complete`, `missing` and `built`. A tuning or a neck that drops notes shows in `complete` and `missing`. `kind` is the option, else what the shape's id begins with (`scale:` or `arpeggio:`), else `"arpeggio"` for a shape with a `chordType`. Also exported: `MissingNote`, `PlaceOptions`, `PlacementView` and `PlacementRestriction`.
|
|
41
|
+
- `placements(shapes, root, options?)` (`PlacementsOptions`): every shape placed at a root, chosen with `use` and `fretRange`, ordered lowest first or by a listed `order`, with `openStrings` set to `"keep"`, `"drop"` or `"raise"`.
|
|
42
|
+
- `nearestPlacement(candidates, to)`, `restrictPlacement(placement, restriction)` and `cagedPositionFor(scale, root)`: the box nearest a fret or another placement, part of a placement by strings, frets, root and octaves (each restriction applied is listed, in order, in `Placement.restrictions`), and the CAGED letter a set of notes forms around a root.
|
|
43
|
+
- `placeScale(scaleName, options)` and `scalePlacements(scaleName, options?)`: the box of a scale or mode by name, and every such box, each reporting both views (`views.tonic` and `views.parent`, each with a CAGED `letter` and a `number`) and askable by either, with `PositionRequest`, `PlaceScaleOptions` and `ScalePlacementsOptions`. On a neck too short for a box, the box keeps its letter and number and is marked incomplete; a box of which no note fits is left out, and `placeScale` asked for it answers `"shape-does-not-fit"`, not `"no-such-position"`. `FrettedNote.parentDegree` is set on the notes of such a box when the parent root differs from the tonic.
|
|
44
|
+
- `parentScale(scaleName)`: the scale a scale's family is named after, as `{ root, scaleType, scaleName }` (G major for A dorian, C major pentatonic for A minor pentatonic and for A minor blues).
|
|
45
|
+
- `diatonicChords(placement, options?)` and the `DiatonicChord` type: the chord on each degree of a seven-note box, with its numeral in both views, its `cagedPosition` and its arpeggio in the box; `sevenths: true` stacks sevenths. `undefined` for a box that is restricted or that the neck cut notes from.
|
|
46
|
+
- `FrettedScaleReason` gains `"invalid-fret-count"`, `"invalid-position"`, `"no-shape-for-scale"` and `"no-such-position"`.
|
|
47
|
+
- `relabelOffset(shape, targetIntervals)`: the semitones from a shape's root up to the tonic `relabelShape` chooses, or `undefined`. `RelabelOptions` gains `id`, which `relabelShape` and `addPassingTone` write to the result; an `id` on the source is never copied.
|
|
48
|
+
- `MODES`, `getMode`, `effectiveModeForSystem`, `isModeCompatibleWithSystem`, `modeBuildRoot` and the `ModeDef` type, moved from `packages/fretboard-ui` into the library. `modeBuildRoot` is `fretboard-ui`'s `parentRoot` under a new name (it returns the root a placement calls `buildRoot`); behaviour is otherwise unchanged, except that `MODES` and its entries are now frozen (`readonly Readonly<ModeDef>[]`). `fretboard-ui` re-exports them under the new names.
|
|
49
|
+
- `stringNumber(index, stringCount)` and `stringIndex(number, stringCount)`: convert between the library's 0-based string index (0 is the lowest) and an instrument's string number (1 is the highest).
|
|
50
|
+
- The API reference pages, `docs/api/`, ship in the npm package, at `node_modules/tonal-guitar/docs/api/`, so the README's links to them work from an installed copy. The links between the pages are relative paths now, where they were paths on a docs site.
|
|
51
|
+
- A `LICENSE` file with the text of the MIT licence. Every published version has declared `"license": "MIT"` in `package.json` and shipped no licence text; npm packs the file without it being named in `files`.
|
|
52
|
+
|
|
53
|
+
### Changed
|
|
54
|
+
|
|
55
|
+
- `add()` on a global registry (`add`, `scaleShapes.add`, `chordShapes.add`, `arpeggioShapes.add`) keeps the id of the shape it replaces. When the replaced shape has an authored `id`, the replacement has none, and the formula would give the replacement a different id (the 20 built-in arpeggios, or any built-in given a new `system`), the registry stores a copy that carries the old id and `add` returns that copy; the object passed in is not changed. In every other case `add` stores and returns its argument, as before.
|
|
56
|
+
- `shapes:merge` refuses an `update` that unsets `id`, an `id` that is given and is not a non-empty string, and a `src/data/shape-ids.json` that is not an object or whose `reserved` is not an array of strings. Its duplicate-id check now sees ids a data file derives at import time and shapes written with single-quoted strings.
|
|
57
|
+
|
|
10
58
|
## [0.5.0] — 2026-11-14
|
|
11
59
|
|
|
12
60
|
### Added
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Cory Leistikow
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
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.
|
|
@@ -64,6 +108,8 @@ See [CHANGELOG.md](./CHANGELOG.md) for full details, and [docs/UPGRADING.md](./d
|
|
|
64
108
|
|
|
65
109
|
## API
|
|
66
110
|
|
|
111
|
+
The reference pages are in [docs/api](./docs/api/index.md), one for each part of the library. They ship in the npm package, at `node_modules/tonal-guitar/docs/api/`.
|
|
112
|
+
|
|
67
113
|
For automated chord/scale shape correctness and quality checks, see [Audit](docs/api/audit.md).
|
|
68
114
|
|
|
69
115
|
### Tuning Constants
|
|
@@ -507,6 +553,8 @@ parseScalePattern("5-8,5-7,5-7,5-7,5-8,5-8");
|
|
|
507
553
|
|
|
508
554
|
#### `toAlphaTeX(notes: FrettedNote[], options?: AlphaTexOptions) => string`
|
|
509
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
|
+
|
|
510
558
|
Format notes as [AlphaTeX](https://www.alphatab.net/docs/alphatex/) notation:
|
|
511
559
|
|
|
512
560
|
```js
|
|
@@ -540,6 +588,10 @@ keySignature("D", "dorian"); // => { tonic: "C", mode: "major", accidentals: 0 }
|
|
|
540
588
|
keySignature("H"); // => undefined
|
|
541
589
|
```
|
|
542
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
|
+
|
|
543
595
|
#### `toAsciiTab(notes: FrettedNote[], options?: AsciiTabOptions) => string`
|
|
544
596
|
|
|
545
597
|
Format notes as ASCII tablature:
|
|
@@ -832,6 +884,7 @@ The package exports these TypeScript interfaces:
|
|
|
832
884
|
- `WalkOptions` — options for `walkPattern`
|
|
833
885
|
- `WalkSpec` — options for `walk`
|
|
834
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`
|
|
835
888
|
- `SequenceOptions` — options for `applySequence`
|
|
836
889
|
- `AlphaTexOptions` — options for `toAlphaTeX`
|
|
837
890
|
- `AsciiTabOptions` — options for `toAsciiTab`
|