tonal-guitar 0.3.0 → 0.5.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 +132 -0
- package/README.md +118 -14
- package/dist/index.d.mts +326 -60
- package/dist/index.d.ts +326 -60
- package/dist/index.js +991 -179
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +985 -173
- package/dist/index.mjs.map +1 -1
- package/docs/UPGRADING.md +124 -0
- package/package.json +13 -3
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,132 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to this project will be documented in this file.
|
|
4
|
+
|
|
5
|
+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
6
|
+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
|
+
|
|
8
|
+
## [Unreleased]
|
|
9
|
+
|
|
10
|
+
## [0.5.0] — 2026-11-14
|
|
11
|
+
|
|
12
|
+
### Added
|
|
13
|
+
|
|
14
|
+
- `auditAllShapes` now also returns `arpeggio: Map<string, ShapeAuditIssue[]>`, the `auditArpeggioShape` result for every registered arpeggio shape, alongside `chord` and `scale`.
|
|
15
|
+
- The `NameUniqueKind` type (`"chord" | "scale" | "arpeggio"`, the `kind` parameter of `checkNameUnique`) is exported from the root barrel.
|
|
16
|
+
- `packages/shape-catalog`: `buildArpeggioCatalog(auditResult)` builds catalog entries (`kind: "arpeggio"`, `ArpeggioCatalogEntry`) for every registered arpeggio shape, with built geometry and audit issues. `buildCatalog` still returns only scale and chord entries, so the docs site is unchanged. `ShapeKind` now includes `"arpeggio"`.
|
|
17
|
+
- `packages/shape-library-ui`: `FilterBar` takes an optional `kinds` prop that selects which kind toggles to show (default Scale and Chord). The detail panel shows a minimal read-only view for arpeggio entries.
|
|
18
|
+
- Shape Workbench: the board has an Arpeggio kind that shows the 20 registered CAGED arpeggio seeds. The Editor can open, edit (note and root tools, metadata, checks) and save an arpeggio, and exports it as an `update` change that `npm run shapes:merge` applies to `src/data/caged-arpeggios.ts` (#212).
|
|
19
|
+
- `checkNameCollision` and `checkIdentifierCollision`, the name and export-identifier halves of `checkNameUnique`, are exported so callers can tell the two collisions apart without parsing `message`. They take the same options as `checkNameUnique` (now also exported as the `NameUniqueOptions` type). `checkIdentifierCollision` also accepts `options.identifier` to check an explicit identifier override instead of the one derived from `shape.name`. `checkNameUnique` is unchanged: it returns the two results concatenated.
|
|
20
|
+
- `walk(scale, spec?)` walks a motif up, down or both through a whole scale or arpeggio, from a chosen start to a chosen end. `WalkSpec` has `motif`, `direction` (`"up"`, `"down"`, `"up-down"`, `"down-up"`), `turn`, `start`, `end`, `stride` (how many positions the motif moves between statements) and `index` (`"pitch-order"` or `"degree"`, which leaves a hole where a degree has no note). `walk(scale)` equals `walkShape(scale)`; the motif drills (thirds, groups of 3 and 4, 1-2-3-5, root to root) are specs of `walk` (#225).
|
|
21
|
+
- `FrettedNote.chordStep` (on a derived arpeggio, the note's place among the chord's tones counted up in pitch from the chord's root; read it as `chordStep ?? degree`) and `FrettedNote.chordInterval` (the interval from the chord's root; read it as `chordInterval ?? interval`). `arpeggioFromScale` and `arpeggioFromShape` set both; `filterChordTones` sets `chordStep`. Steps rise with pitch for every chord: in Cmaj9 the D is step 2 and its `chordInterval` is `9M`. A slash chord is labelled from its root, not its bass.
|
|
22
|
+
- `FrettedScale.chordStepCount`: how many steps the material has in an octave. A derived arpeggio carries its chord's tone count, so `walk` by degree, `walkPattern` and `applySequence` leave a gap for a chord tone the parent scale lacks (Cm7 over C major keeps steps 1 and 3 of 4).
|
|
23
|
+
- `FrettedScale.reason` and the `FrettedScaleReason` type: every empty `FrettedScale` the library returns says why (`"invalid-root"`, `"shape-does-not-fit"`, `"unknown-scale"`, `"unknown-chord"`, `"shape-cannot-play-scale"`, `"no-chord-tones"`, `"empty-parent"`, `"no-arpeggio-shape"`).
|
|
24
|
+
- `canPlay(shape, scaleName)`: whether every note of a shape belongs to a scale once the shape is relabeled into it. It does not mean the shape covers the scale; `isShapeCompatible` is unchanged.
|
|
25
|
+
- `keySignature(tonic, mode?)` returns the key signature `toAlphaTeX` writes (`{ tonic, mode, accidentals }`), with the `KeySignature` and `KeyMode` types. `toAlphaTeX`'s `key` reads a tonic and an optional mode (`"Am"`, `"F# major"`, `"D dorian"`).
|
|
26
|
+
- `RelabelOptions` gains `cagedPosition` and `chordType`; `relabelShape` and `addPassingTone` copy `tags`, `tuning`, `notes` and, where the tonic does not move, `cagedPosition` and `chordType` from the source shape.
|
|
27
|
+
- Exported types: `WalkSpec`, `KeySignature`, `KeyMode`, `BuildOptions`, `FrettedScaleReason`, and the `AddChordChange`, `AddArpeggioChange` and `AddScaleChange` members of `AddChange`.
|
|
28
|
+
- `npm run typecheck` (`tsc --noEmit -p .`) type-checks the library and its tests; CI runs it after lint.
|
|
29
|
+
|
|
30
|
+
### Changed
|
|
31
|
+
|
|
32
|
+
- `auditScaleShape` and `auditArpeggioShape` now run `checkNameUnique` (`name-unique`) against the live scale/arpeggio registry, as `auditChordShape` already did for chords. A shape that is not the registered object but reuses a registered name, or derives the same export identifier, now gets an error. No registered shape is affected. To audit an edited copy of a registered shape, filter out `CHECK_NAME_UNIQUE` issues, as the workbench and `shapes:merge` do for updates, or call `checkNameUnique` yourself with `selfName`.
|
|
33
|
+
|
|
34
|
+
### Changed (breaking)
|
|
35
|
+
|
|
36
|
+
[docs/UPGRADING.md](./docs/UPGRADING.md) says what to look for in your code and what to do about each of these.
|
|
37
|
+
|
|
38
|
+
1. `applySequence` with the default `boundToShape` places passes on the shape's notes by degree: passes climb the shape and stop at its top, the default count is all that fit, and a pass that does not fit is not returned. Degrees are positions, so a leap past an octave is that leap. To keep the old wrapping layout, pass `boundToShape: false`; for a descending drill through a whole shape, use `walk` with `direction: "down"`.
|
|
39
|
+
2. `buildFromScale` returns the empty sentinel (`reason: "shape-cannot-play-scale"`) for a shape that cannot be relabeled into the scale, where it used to build the unrelabeled shape. Ask `canPlay(shape, scaleName)` first, or pick another shape.
|
|
40
|
+
3. `toAlphaTeX` without `notesPerBar` closes bars by duration, so each bar adds up to its time signature. Pass `notesPerBar` to keep the old count-based layout. (A tab with a duration alphaTab does not read, or a time signature that is not two positive integers, still closes by the old count.)
|
|
41
|
+
4. `toAlphaTeX`'s `key` is read as a tonic and an optional mode: minor keys are written as minor, a key with no signature is written as its enharmonic (`"G#"` as `Ab`), lower-case tonics are written upper-case, and a key with a mode word or a space (`"F# major"`, `"D dorian"`) is read where it used to be written as `C`. Call `keySignature(tonic, mode)` to see the key that will be written.
|
|
42
|
+
5. `walkShapeMotif(scale, [])` returns the plain walk, equal to `walkShape(scale)`, where it used to return `[]`. Guard for an empty motif yourself if you relied on `[]`.
|
|
43
|
+
6. `walkPattern` on an arpeggio derived from a scale counts chord tones (`chordStep`: the chord's tones in rising order of pitch from its root), not the parent scale's degrees, and wraps at the chord's tone count; for `filterChordTones` the count follows the order of the intervals passed in. `applySequence` with `boundToShape: false`, which is `walkPattern` once per pass, makes that many passes by default. List the intervals from the chord's root in rising order of pitch, and renumber patterns that assumed parent-scale degrees.
|
|
44
|
+
7. `arpeggioFromScale`, `arpeggioFromShape` and `filterChordTones` return copies of the parent's notes with `chordStep` (and `chordInterval`), not the same objects, and the result carries `chordStepCount`. Compare notes by value, not by identity.
|
|
45
|
+
8. `relabelShape` and `addPassingTone` results carry more fields (`tags`, `tuning`, `notes`, and `cagedPosition` and `chordType` where they apply). Code that compared a result to a literal with `toEqual` should expect them.
|
|
46
|
+
9. Empty `FrettedScale` results carry `reason` (those of `arpeggioFor` included), so they no longer deep-equal `NoFrettedScale`. Test `.empty`, not equality.
|
|
47
|
+
10. `AddChange` is a union discriminated by `kind` (`AddChordChange`, `AddArpeggioChange`, `AddScaleChange`). This is a type change only; the changeset JSON is unchanged. Narrow on `kind` where you read `change.shape`.
|
|
48
|
+
|
|
49
|
+
### Removed
|
|
50
|
+
|
|
51
|
+
- `sourceGripBaseFret(shape, sourceFrets)`: its `shape` parameter was never used and the result is exactly `gripBaseFret(sourceFrets)`. Call `gripBaseFret(sourceFrets)` instead.
|
|
52
|
+
|
|
53
|
+
### Fixed
|
|
54
|
+
|
|
55
|
+
- `parentBoxForChordShape` no longer rejects 6-string boxes on 7- and 8-string tunings; it now skips only boxes with more strings than the tuning, matching `buildFrettedScale`'s string offset. This fixes `arpeggioFor`'s derived tier, which returned empty on extended tunings (#195).
|
|
56
|
+
- `scaleTypeForChordType` no longer returns `Object.prototype` members for chord types like `"toString"`, `"constructor"` or `"__proto__"`; it only matches `CHORD_SCALE_RULE`'s own keys and returns `undefined` otherwise. `CHORD_SCALE_RULE` itself is unchanged and still mutable.
|
|
57
|
+
- `buildFromScale` no longer returns the notes of the wrong scale: a shape that cannot play the scale (for example `E Shape` with `"C harmonic minor"`, `"C melodic minor"`, `"C minor pentatonic"` or `"C whole tone"`) used to build with the shape's own intervals under the scale's name (#225).
|
|
58
|
+
- `toAlphaTeX` bars add up: without `notesPerBar`, each bar holds exactly its time signature's length (thirty sixteenths in 4/4 are two bars, not four half-empty ones), and a beat that does not fit closes the bar short (#225).
|
|
59
|
+
- `toAlphaTeX` keys: a minor key (`"Am"`) or a key with a space or a mode word (`"F# major"`, `"D dorian"`) was written as `C`, and a tonic with no key signature (`"G#"`, `"D#"`, `"A#"`) was written as given, so alphaTab rejected the tab. Every key is now written as a signature alphaTab reads (#225).
|
|
60
|
+
- `walkShapeMotif(scale, [])` returned `[]` instead of the plain walk (#225).
|
|
61
|
+
- A scale or chord name that is a member of `Object.prototype` (`"constructor"`, `"C __proto__"`, `"Cconstructor"`) made `buildFromScale`, `relabelShapeToScale`, `isShapeCompatible`, `modeShapes`, `arpeggioFromScale` and (through a hand-made scale's `scaleType`) `relatedScales` throw. It is now an unknown name: an empty result with `reason: "unknown-scale"` or `"unknown-chord"`, `false`, `undefined` or `[]` (#225).
|
|
62
|
+
- `walkPattern` on an arpeggio derived from a scale counted the parent scale's degrees instead of chord tones, so `[1, 2, 3, 4]` on a seventh-chord arpeggio did not play the four chord tones (#225).
|
|
63
|
+
- `applyChordShape` no longer returns a degenerate barre on a tuning with fewer strings than the shape. A barre that lies entirely on strings the tuning doesn't have is now dropped, where before it was clamped to a one-string `{ fromString: last, toString: last }` barre on the tuning's last string. Barres that only partly overhang are still clamped (#204).
|
|
64
|
+
|
|
65
|
+
## [0.4.0] — 2026-09-30
|
|
66
|
+
|
|
67
|
+
### Added
|
|
68
|
+
|
|
69
|
+
- **Built-in CAGED arpeggio seeds** (#58). `src/data/caged-arpeggios.ts` (generator-managed: `shapes-merge` owned blocks, so later edits go through `npm run shapes:merge` changesets) registers the first 20 `arpeggioShapes` entries: one arpeggio per (quality, CAGED letter) pair, for Major, Minor, maj7 and m7 across all five positions (C, A, G, E, D). They are named `"<Letter> Shape <Quality> Arpeggio"`, e.g. `"E Shape Minor Arpeggio"` or `"C Shape maj7 Arpeggio"`.
|
|
70
|
+
- Each seed is the chord tones of its parent CAGED box: the major box for Major and maj7, the minor box for Minor and m7. The seed records that box in `parentShape`.
|
|
71
|
+
- Each seed carries `cagedPosition`, `chordType` and `tags` (`["caged", "triad"]` or `["caged", "seventh"]`), so `arpeggioShapes.query({ cagedPosition: "E" })` returns that position's Major, Minor, maj7 and m7 arpeggios.
|
|
72
|
+
- Where a matching grip exists, `chordShape` links the seed to it, and `arpeggioFor`/`resolveArpeggioForSlot` resolve it at tier `"core"` instead of `"derived"`. The C/G 7th seeds have no `chordShape` because no C/G 7th grips are registered.
|
|
73
|
+
- Every seed passes `auditArpeggioShape` and `auditArpeggioShapeIntegration` cleanly.
|
|
74
|
+
- `scripts/shapes-merge.mjs` count marker `arpeggio-shape-total`, which tracks the registered arpeggio total in `src/data/data.test.ts`.
|
|
75
|
+
- **Blues scale boxes (#56).** 10 new registered `ScaleShape`s in `src/data/blues.ts`, all `system: "pentatonic"`: `"Blues Box 1 Minor"` … `"Blues Box 5 Minor"` (`quality: "minor-blues"`, the minor pentatonic boxes plus the b5) and `"Blues Box 1 Major"` … `"Blues Box 5 Major"` (`quality: "major-blues"`, the same geometry relabeled via `relabelShape` so the passing tone reads as the b3). Box 1 of each quality is `featured`. They work with Tonal's `"blues"` / `"minor blues"` / `"major blues"` scale names in `buildFromScale`, `modeShapes`, `isShapeCompatible` and `relatedScales`, and pass `auditScaleShape` at every root. The scale-shape registry grows from 27 to 37 entries.
|
|
76
|
+
- `addPassingTone(shape, tone, options?)` (`src/transform.ts`) — adds a chromatic passing tone to any scale shape. The tone goes on the same string one fret above every note a semitone below it; tones inside the shape's pitch range are always kept (even with a one-fret stretch), while a tone that would become a new edge note is kept only if it fits in the existing fret span. `PassingToneOptions` extends `RelabelOptions` with `tuning` (default `STANDARD`). The registered blues boxes are derived with it, so registered and generated blues boxes always agree.
|
|
77
|
+
- `packages/shape-catalog`: `relatedScaleNameFor` maps the `minor-blues` / `major-blues` qualities to Tonal scale names.
|
|
78
|
+
|
|
79
|
+
### Changed
|
|
80
|
+
|
|
81
|
+
- The 7th-chord CAGED grips in `src/data/caged-chords-7th.ts` (E/A/D × `maj7`/`m7`/`7`, E/A × `m7b5`) now set `cagedPosition`, taken from the letter in the shape name. As a result, `chordShapes.query({ cagedPosition })` now also returns these 11 grips, where before it returned only the triad grips.
|
|
82
|
+
- `arpeggioShapes` is no longer empty after importing the root barrel. Code that assumed an empty registry, such as tests that add fixtures to a slot, should call `arpeggioShapes.removeAll()` first or use a slot the seeds don't occupy.
|
|
83
|
+
- `src/transform.ts` now imports `./build` (for `addPassingTone`'s fret geometry), so it — and `src/data/blues.ts` / the other data files that call it at import time — depend on the required `@tonaljs/note` peer as well as `@tonaljs/interval`. Still no optional-peer imports.
|
|
84
|
+
- `scripts/shapes-merge.mjs`: `blues` is on the computed-file deny list (its shapes are derived, not authored).
|
|
85
|
+
- **`Barre.fret` offsets are now root-invariant (breaking for `gripBaseFret`; #192).** `gripBaseFret` — and therefore `sourceGripBaseFret`, `applyChordShape`'s resolved `barres`, and `autoFingering`'s seeded `barres` — now takes the minimum over **all played** frets, open strings (`0`) included, instead of excluding open strings. Built grips transpose rigidly, so the base now moves by exactly the transposition interval and a stored offset resolves to the same finger position at every root. Previously every registered chord shape with barres resolved to the wrong fret at one or more roots: movable shapes at the root where part of the grip lands on the nut (e.g. `"G Shape Minor"` at G, `"A Shape m6"` at A, every E/A form at E/A), open shapes at every root other than their `canonicalRoot`.
|
|
86
|
+
- No data change for movable shapes — their offsets were already correct under the new base.
|
|
87
|
+
- The 20 `src/data/open-chords.ts` open shapes with barres were re-expressed against the nut-inclusive base (e.g. `"A Major Open"` `x02220`: offset `0` → `2`; `"C Sus2 Open"`: `0` → `3`). Custom shapes authored with offsets measured from the old base need the same adjustment wherever their grip includes an open string; `checkBarreFretOrigin` now reports them with the corrected offset.
|
|
88
|
+
- `checkBarreFretOrigin` (`barre-fret-origin`) gains a rule that the resolved barre fret matches the grip: strings under the barre carrying the barre's finger must sit at that fret, and no played string under it may sit lower. Its `span` is now measured from the new base (highest played fret − `gripBaseFret`).
|
|
89
|
+
|
|
90
|
+
## [0.3.0] — 2026-09-10
|
|
91
|
+
|
|
92
|
+
### Added
|
|
93
|
+
|
|
94
|
+
- `CHORD_TYPE_TABLE` — a canonical, side-effect-free `as const` table (`src/chord-types.ts`) with one row per `chordType` key the chord-shape registry indexes (25 rows). Each row carries `id` (the registry key, verbatim), `tonalCanonical` (`ChordType.get(id).aliases[0]`), `label` (human label for pickers), `glyph` (lead-sheet suffix) and `intervals` (Tonal's compound-interval vocabulary). Exported from the root barrel alongside `CHORD_TYPE_KEYS` (the same keys as a literal tuple) and the `ChordTypeEntry` / `ChordTypeRow` / `ChordTypeKey` types.
|
|
95
|
+
- `tonal-guitar/chord-types` — a new **pure** package subpath (`exports["./chord-types"]`, its own tsup entry) exposing only the table. Importing it registers **zero** shapes and pulls in neither Tonal nor `src/data/*`, so a consumer that wants the chord vocabulary does not pay for the 132-shape registry or drag it into its own module graph. `src/chord-types.test.ts` enforces the purity contract both statically (the module's source has no imports at all) and at runtime (importing it leaves `chordShapes.all()` empty). A `typesVersions` entry accompanies the `exports` entry so the subpath's types also resolve for consumers on TypeScript's node10 resolver (`"moduleResolution": "node"`), which ignores `exports`; `scripts/check-dts.mjs` runs TypeScript's own resolver against a throwaway consumer after every build and fails if the subpath stops resolving under node10, nodenext or bundler.
|
|
96
|
+
- `aug7` deliberately has no row: it is the same Tonal chord as `7#5` (`1P 3M 5A 7m`), and the registry — an exact-string index with no alias resolution — registers `7#5` only. Callers holding `aug7` should map it onto the `7#5` row.
|
|
97
|
+
- Three rows have a `tonalCanonical` that differs from their `id`, which is why a consumer that canonicalises through Tonal before querying the registry finds nothing for them without a bridge: `add9` → `Madd9`, `6/9` → `6add9`, `mMaj7` → `m/ma7`.
|
|
98
|
+
|
|
99
|
+
### Changed
|
|
100
|
+
|
|
101
|
+
- **Jazz shell voicings — reduced and renamed (breaking).** `src/data/jazz-shells.ts` now registers 8 `chordShapes` entries (one **E-root** and one **A-root** shell per chord type — `maj7`, `m7`, `7`, `m7b5`) instead of the previous 16 (every combination of 2 string sets × 2 voice orderings per chord type). Shape names are public `chordShapes` lookup keys, so this is a breaking rename/removal for any consumer keying off the old names:
|
|
102
|
+
- Old `"Shell <type> R37 123"` (string set `[1,2,3]`, R-3-7 ordering) → new `"Shell <type> A-root"` (same voicing, renamed).
|
|
103
|
+
- Old `"Shell <type> R37 012"`, `"Shell <type> R73 012"`, and `"Shell <type> R73 123"` are removed — no longer registered.
|
|
104
|
+
- New `"Shell <type> E-root"` is a new voicing (string set `[0,2,3]`, R-7-3 ordering — skips the A string), not a rename of any previously-registered shell.
|
|
105
|
+
- Applies to all four chord types, e.g. `"Shell maj7 R37 012"` → removed, `"Shell maj7 R37 123"` → `"Shell maj7 A-root"`, `"Shell maj7 R73 012"`/`"Shell maj7 R73 123"` → removed, `"Shell maj7 E-root"` → new.
|
|
106
|
+
- **Built-in chord data is typed against the table.** Every `ChordShape` constant in `src/data/open-chords.ts`, `caged-chords.ts`, `caged-chords-minor.ts`, `caged-chords-7th.ts` and `extended-chords.ts` is now declared as a file-local `RegisteredChordShape = ChordShape & { chordType: ChordTypeKey }`, and `src/data/jazz-shells.ts` pins its shell dictionary to the same key union — so a typo or an unvoiceable quality in the shipped data is a compile error. `ChordShape.chordType` in `src/shape.ts` is unchanged (`string | undefined`), so external `chordShapes.add()` callers are unaffected.
|
|
107
|
+
- `scripts/shapes-merge.mjs` accepts either the base `ChordShape`/`ScaleShape`/`ArpeggioShape` annotation or a `Registered*` narrowing alias when parsing `src/data/*.ts` declarations. Generated blocks are still emitted with the base annotation.
|
|
108
|
+
- `scripts/check-dts.mjs` verifies the `chord-types` declaration output alongside the root barrel's, with the same stub-emit guard.
|
|
109
|
+
|
|
110
|
+
## [0.2.0] — 2026-08-02
|
|
111
|
+
|
|
112
|
+
### Added
|
|
113
|
+
|
|
114
|
+
- `relabelShape(shape: ScaleShape, targetIntervals: string[], options?: RelabelOptions) => ScaleShape | undefined` — new pure-tier primitive (`src/transform.ts`) that rewrites a `ScaleShape`'s per-string interval labels into a different, rotation-compatible interval frame (e.g. relabeling a major-frame CAGED shape into its natural-minor labeling). Geometry is unchanged; returns a new shape (no mutation) or `undefined` when no valid relabeling exists.
|
|
115
|
+
- `relabelShapeToScale(shape: ScaleShape, scaleName: string, options?: RelabelOptions) => ScaleShape | undefined` — integration-tier wrapper that resolves `scaleName` via Tonal's `Scale.get()` and delegates to `relabelShape`.
|
|
116
|
+
- `RelabelOptions` type (`name?`, `quality?`, `parentShape?`) exported alongside `relabelShape`.
|
|
117
|
+
- `ScaleShape.quality?: string` and `ScaleShape.parentShape?: string` — new optional fields. `quality` tags a shape's interval-frame quality (e.g. `"minor"`, `"minor-pentatonic"`); `parentShape` names the source shape a relabeled entry was derived from. Both are `undefined` on hand-authored major-frame source shapes.
|
|
118
|
+
- 10 new registered `ScaleShape` entries, derived via `relabelShape` at import time (`src/data/caged-scales-minor.ts`, `src/data/pentatonic-minor.ts`):
|
|
119
|
+
- Minor CAGED: `"Dm Shape"` (from `"E Shape"`), `"Cm Shape"` (from `"D Shape"`), `"Am Shape"` (from `"C Shape"`), `"Gm Shape"` (from `"A Shape"`), `"Em Shape"` (from `"G Shape"`).
|
|
120
|
+
- Minor pentatonic: `"Pentatonic Box 1 Minor"` through `"Pentatonic Box 5 Minor"` (from the corresponding major `"Pentatonic Box N"`).
|
|
121
|
+
- Each derived entry shares its parent's fretboard geometry; only interval labels, `rootString`, and `quality`/`parentShape` metadata differ.
|
|
122
|
+
- `scalesContainingChord(chord: string, options?: ScalesContainingChordOptions) => ScalesContainingChordResult` — new integration-tier function (`src/integration.ts`) that finds scales containing a chord's tones. Resolves `chord` via Tonal's `Chord.get()`, sweeps 12 chromatic roots x `DEFAULT_SCALE_CORPUS`, and keeps candidates whose pitch-class set is a (tolerant) superset of the chord's, partitioned into `rootAnchored` and `otherRoots` and ranked by fit. Never throws — an unresolvable or empty chord returns empty groups.
|
|
123
|
+
- `DEFAULT_SCALE_CORPUS: readonly string[]` — the fixed 11-entry scale-type corpus swept by `scalesContainingChord` (major, dorian, phrygian, lydian, mixolydian, aeolian, locrian, harmonic minor, melodic minor, major pentatonic, minor pentatonic).
|
|
124
|
+
- `ContainingScale`, `ScalesContainingChordResult`, `ScalesContainingChordOptions` types exported alongside `scalesContainingChord`.
|
|
125
|
+
- `ScaleShape.featured?: boolean` and `ChordShape.featured?: boolean` — new optional fields marking the curated, canonical/representative shape per group (e.g. per `(system, quality)` for scales, per `chordType` for chords) for catalog/UI display purposes. Curated registry data only — not audit-derived, and intentionally not required or checked by `checkScaleMetadataCompleteness`/`checkChordMetadataCompleteness`.
|
|
126
|
+
|
|
127
|
+
### Changed
|
|
128
|
+
|
|
129
|
+
- **`buildFromScale` — pitch-correctness fix (behavior change).** `buildFromScale` now relabels `shape` into the requested scale's interval frame (via `relabelShape`) before building. Previously, `buildFromScale(shape, scaleName)` applied the shape's original (usually major) interval frame directly at the scale's tonic, so e.g. `buildFromScale(get("E Shape"), "A minor")` silently produced **A-major pitch classes** mislabeled `scaleType: "aeolian"` — wrong notes, not merely wrong labels. As of this release the same call produces correct A-natural-minor pitch classes (`A=1P`, `C=3m`, `E=5P`). If a shape is not rotation-compatible with the requested scale, `relabelShape` returns `undefined` and `buildFromScale` falls back to building the original shape as-is (its pre-fix behavior), so no previously-working call regresses to an empty result. Calls where the shape already matches the scale's frame (e.g. `buildFromScale(get("E Shape"), "C major")`) are unaffected.
|
|
130
|
+
- **`scalesContainingChord` — sweep performance.** The default-corpus sweep now reads from a lazily-precomputed module-scope table of resolved scale candidates (chroma sets and root chromas computed once) instead of re-resolving 12 roots × 11 scale types per call, and the ranking comparator no longer re-derives root chromas per comparison. ~8.5× faster per call; behavior, ranking order, and the public API are unchanged.
|
|
131
|
+
- **`isShapeCompatible` — chroma-set semantics (behavior change).** Compatibility is now computed by reducing both the shape's and the scale's interval frames to pitch-class chroma sets (0–11) and checking subset coverage, instead of comparing raw interval strings. This is an enharmonic-robustness fix (e.g. `4A` vs `5d` spellings across Tonal scale types), **not** a relative-major/minor loosening — a major-frame shape remains incompatible with a minor scale name, since anchoring it at the minor tonic would still produce the wrong pitch classes. `modeShapes` (built on `isShapeCompatible`) inherits this change; minor-tonic queries (e.g. `modeShapes("A minor")`, unfiltered) now return the 10 new registered minor-quality entries where they previously returned none.
|
|
132
|
+
|
package/README.md
CHANGED
|
@@ -60,11 +60,11 @@ console.log(toAlphaTeX(notes, { tempo: 100, duration: 8 }));
|
|
|
60
60
|
- **New `ScaleShape` fields:** optional `quality` and `parentShape`, set on shapes derived via `relabelShape`.
|
|
61
61
|
- **10 new registered entries:** 5 minor CAGED scale shapes and 5 minor pentatonic boxes — see [Minor-Quality Entries](#minor-quality-entries).
|
|
62
62
|
|
|
63
|
-
See [CHANGELOG.md](./CHANGELOG.md) for full details.
|
|
63
|
+
See [CHANGELOG.md](./CHANGELOG.md) for full details, and [docs/UPGRADING.md](./docs/UPGRADING.md) for what an existing caller has to change in each release. Both files ship in the npm package, at `node_modules/tonal-guitar/CHANGELOG.md` and `node_modules/tonal-guitar/docs/UPGRADING.md`.
|
|
64
64
|
|
|
65
65
|
## API
|
|
66
66
|
|
|
67
|
-
For automated chord/scale shape correctness and quality checks, see [Audit](docs/api/audit.md)
|
|
67
|
+
For automated chord/scale shape correctness and quality checks, see [Audit](docs/api/audit.md).
|
|
68
68
|
|
|
69
69
|
### Tuning Constants
|
|
70
70
|
|
|
@@ -137,7 +137,7 @@ fretboard(STANDARD, [0, 4]); // every note on strings 0-5, frets 0-4
|
|
|
137
137
|
|
|
138
138
|
### Shape Registry
|
|
139
139
|
|
|
140
|
-
Built-in shapes are registered at import time: CAGED scale shapes (5), CAGED chord shapes (5), 3NPS patterns (7), pentatonic boxes (5) -- plus (v0.2.0) 5 minor CAGED scale shapes and 5 minor pentatonic boxes, derived from the major-frame shapes via `relabelShape`. See [Minor-Quality Entries](#minor-quality-entries) below.
|
|
140
|
+
Built-in shapes are registered at import time: CAGED scale shapes (5), CAGED chord shapes (5), 3NPS patterns (7), pentatonic boxes (5) -- plus (v0.2.0) 5 minor CAGED scale shapes and 5 minor pentatonic boxes, derived from the major-frame shapes via `relabelShape`, and 5 minor + 5 major blues boxes, derived via `addPassingTone`. See [Minor-Quality Entries](#minor-quality-entries) and [Blues Boxes](#blues-boxes) below.
|
|
141
141
|
|
|
142
142
|
#### `get(name: string) => ScaleShape | undefined`
|
|
143
143
|
|
|
@@ -214,8 +214,10 @@ Each `FrettedNote` contains:
|
|
|
214
214
|
- `degree` — 1-based degree (scaleIndex + 1)
|
|
215
215
|
- `intervalNumber` — numeric part of interval (e.g. 3 for `"3M"`)
|
|
216
216
|
- `midi` — MIDI number
|
|
217
|
+
- `chordStep` — optional; on an arpeggio derived from a scale, the note's place among the chord's tones counted up in pitch from the chord's root (1 is the root). Read it as `chordStep ?? degree`
|
|
218
|
+
- `chordInterval` — optional; the interval from the chord's root on a derived arpeggio. Read it as `chordInterval ?? interval`
|
|
217
219
|
|
|
218
|
-
Returns a `FrettedScale` with `empty: true` for invalid inputs.
|
|
220
|
+
Returns a `FrettedScale` with `empty: true` for invalid inputs. An empty result carries a `reason` (`FrettedScaleReason`): `buildFrettedScale` gives `"invalid-root"` when the root is not a note name and `"shape-does-not-fit"` when no anchor fret places the shape. Test `.empty`, not equality with `NoFrettedScale`. `buildFrettedScale` takes a fourth argument `options?: BuildOptions` (`allowOpenStrings`, default `true`); `BuildOptions` is exported.
|
|
219
221
|
|
|
220
222
|
#### `applyChordShape(shape: ChordShape, root: string, tuning?: string[]) => Fingering`
|
|
221
223
|
|
|
@@ -236,7 +238,7 @@ const chord = applyChordShape(chordShapes.get("E Shape"), "A");
|
|
|
236
238
|
|
|
237
239
|
#### `relabelShape(shape: ScaleShape, targetIntervals: string[], options?: RelabelOptions) => ScaleShape | undefined`
|
|
238
240
|
|
|
239
|
-
Pure-tier primitive that rewrites a shape's per-string interval labels into a different, rotation-compatible interval frame (e.g. turning a major-frame CAGED shape into its natural-minor labeling). Geometry (which string/fret each note lands on) is unchanged -- only `strings` labels, `rootString`, `name`, `quality`, and `parentShape` change. Returns a new `ScaleShape` (the input is never mutated), or `undefined` when no valid relabeling exists (e.g. relabeling a 7-note shape into a 5-note pentatonic frame).
|
|
241
|
+
Pure-tier primitive that rewrites a shape's per-string interval labels into a different, rotation-compatible interval frame (e.g. turning a major-frame CAGED shape into its natural-minor labeling). Geometry (which string/fret each note lands on) is unchanged -- only `strings` labels, `rootString`, `name`, `quality`, and `parentShape` change. Returns a new `ScaleShape` (the input is never mutated), or `undefined` when no valid relabeling exists (e.g. relabeling a 7-note shape into a 5-note pentatonic frame). The source's `tags`, `tuning` and `notes` are copied to the result. Its `cagedPosition` and `chordType` are copied only when the relabel keeps the tonic where it was; `featured` and `overrides` are never copied. See [docs/api/transform.md](./docs/api/transform.md).
|
|
240
242
|
|
|
241
243
|
```js
|
|
242
244
|
import { relabelShape, get } from "tonal-guitar";
|
|
@@ -254,6 +256,8 @@ interface RelabelOptions {
|
|
|
254
256
|
name?: string; // override the derived name (default: input shape.name)
|
|
255
257
|
quality?: string; // value written to result.quality
|
|
256
258
|
parentShape?: string; // value written to result.parentShape (default: shape.name)
|
|
259
|
+
cagedPosition?: CagedPosition; // value written to result.cagedPosition (wins over the source's)
|
|
260
|
+
chordType?: string; // value written to result.chordType (wins over the source's)
|
|
257
261
|
}
|
|
258
262
|
```
|
|
259
263
|
|
|
@@ -292,6 +296,40 @@ buildFrettedScale(get("G Shape"), "C").notes;
|
|
|
292
296
|
buildFrettedScale(get("Em Shape"), "A").notes; // same {string, fret} pairs, A=1P, C=3m
|
|
293
297
|
```
|
|
294
298
|
|
|
299
|
+
### Blues Boxes
|
|
300
|
+
|
|
301
|
+
#### `addPassingTone(shape: ScaleShape, tone: string, options?: PassingToneOptions) => ScaleShape | undefined`
|
|
302
|
+
|
|
303
|
+
Adds a chromatic passing tone to any scale shape -- e.g. the b5 (`"5d"`) that turns a minor pentatonic box into a minor blues box, the b3 (`"3m"`) that turns a major pentatonic box into a major blues box, or a `"7M"` on a mixolydian shape for bebop dominant.
|
|
304
|
+
|
|
305
|
+
Placement rule: the tone goes on the same string, one fret above every note a semitone below it (the b5 sits right above each 4P). Tones inside the shape's existing pitch range are always kept, even if they need a one-fret stretch; a tone that would become the shape's new highest note is kept only if it fits within the existing fret span. Fret geometry is evaluated in `options.tuning` (default `STANDARD`). Returns `undefined` for an invalid tone, a shape that doesn't build, or when nothing can be placed (no semitone-below neighbor, or the pitch is already present).
|
|
306
|
+
|
|
307
|
+
```js
|
|
308
|
+
import { addPassingTone, get } from "tonal-guitar";
|
|
309
|
+
|
|
310
|
+
const blues = addPassingTone(get("Em Shape"), "5d", { name: "Em Blues", quality: "minor-blues" });
|
|
311
|
+
|
|
312
|
+
interface PassingToneOptions {
|
|
313
|
+
name?: string; // override the result name (default: shape.name)
|
|
314
|
+
quality?: string; // value written to result.quality
|
|
315
|
+
parentShape?: string; // value written to result.parentShape (default: shape.name)
|
|
316
|
+
tuning?: string[]; // tuning for the stretch rule (default: STANDARD)
|
|
317
|
+
}
|
|
318
|
+
```
|
|
319
|
+
|
|
320
|
+
Registered blues boxes (all `system: "pentatonic"`, box numbers shared with the pentatonic boxes):
|
|
321
|
+
|
|
322
|
+
| Registered name | Derived from | `quality` | b5 frets in A minor blues |
|
|
323
|
+
| --- | --- | --- | --- |
|
|
324
|
+
| `"Blues Box 1 Minor"` | `"Pentatonic Box 1 Minor"` + `5d` | `"minor-blues"` | A:6, G:8 |
|
|
325
|
+
| `"Blues Box 2 Minor"` | `"Pentatonic Box 2 Minor"` + `5d` | `"minor-blues"` | low E:11, G:8 |
|
|
326
|
+
| `"Blues Box 3 Minor"` | `"Pentatonic Box 3 Minor"` + `5d` | `"minor-blues"` | low E:11, D:13, high E:11 |
|
|
327
|
+
| `"Blues Box 4 Minor"` | `"Pentatonic Box 4 Minor"` + `5d` | `"minor-blues"` | D:13, B:16 |
|
|
328
|
+
| `"Blues Box 5 Minor"` | `"Pentatonic Box 5 Minor"` + `5d` | `"minor-blues"` | A:6, B:4 |
|
|
329
|
+
| `"Blues Box N Major"` | `"Blues Box N Minor"` relabeled | `"major-blues"` | same frets (C major blues = A minor blues) |
|
|
330
|
+
|
|
331
|
+
They work with Tonal's scale names: `buildFromScale(get("Blues Box 1 Minor"), "E blues")` (`"blues"` is Tonal's alias for `"minor blues"`), `modeShapes("A blues")`, `isShapeCompatible(shape, "C major blues")`, and `relatedScales` (minor blues ↔ relative major blues).
|
|
332
|
+
|
|
295
333
|
### Pattern Generators
|
|
296
334
|
|
|
297
335
|
All generators return `number[]` degree sequences.
|
|
@@ -359,6 +397,38 @@ Options:
|
|
|
359
397
|
|
|
360
398
|
Auto-direction compares consecutive pattern degrees: `[1,3,5,7]` ascends, then `[7,6,5,4,3,2,1]` descends. The walker picks the right octave at each step.
|
|
361
399
|
|
|
400
|
+
`"down"` takes each note below the last; it does not play a mirrored motif. On the C major `E Shape` scale, `walkPattern(scale, [1, 3], { direction: "down" })` is `C5 E4`. On an arpeggio derived from a scale, notes are counted by `chordStep ?? degree`, so `[1, 2, 3, 4]` on `arpeggioFromScale(scale, "Cmaj7")` is `C3 E3 G3 B3`.
|
|
401
|
+
|
|
402
|
+
#### `walk(scale: FrettedScale, spec?: WalkSpec) => FrettedNote[]`
|
|
403
|
+
|
|
404
|
+
Walk a motif up, down or both through a whole scale or arpeggio, starting and ending where you say. Returns the scale's own notes; never mutates the scale and never throws (an invalid option gives `[]`).
|
|
405
|
+
|
|
406
|
+
```js
|
|
407
|
+
// C major in the E Shape: B2 C3 D3 E3 F3 G3 A3 B3 C4 D4 E4 F4 G4 A4 B4 C5 D5
|
|
408
|
+
const scale = buildFrettedScale(get("E Shape"), "C");
|
|
409
|
+
|
|
410
|
+
walk(scale, { motif: [1, 3] });
|
|
411
|
+
// => B2 D3 C3 E3 D3 F3 ... A4 C5 B4 D5 (30 notes)
|
|
412
|
+
|
|
413
|
+
walk(scale, { motif: [1, 3], direction: "down" });
|
|
414
|
+
// => D5 B4 C5 A4 B4 G4 ... E3 C3 D3 B2 (30 notes)
|
|
415
|
+
|
|
416
|
+
walk(scale, { motif: [1, 3], start: "lowest-root", end: "root" });
|
|
417
|
+
// => C3 E3 D3 F3 ... A4 C5 B4 D5 C5 (29 notes)
|
|
418
|
+
```
|
|
419
|
+
|
|
420
|
+
| Option | Default | Meaning |
|
|
421
|
+
| ----------- | ------------------------------------------------------- | ------- |
|
|
422
|
+
| `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 |
|
|
423
|
+
| `direction` | `"up"` | `"up"`, `"down"`, `"up-down"` or `"down-up"` |
|
|
424
|
+
| `turn` | `"no-repeat"` | At the turn of a two-leg walk, `"repeat"` plays the turning note twice |
|
|
425
|
+
| `start` | `"lowest"` going up first, `"highest"` going down first | `"lowest"`, `"lowest-root"`, `"highest"` or `"highest-root"` |
|
|
426
|
+
| `end` | `"where-it-stops"` | `"root"` appends the notes to the nearest root, the root included |
|
|
427
|
+
| `stride` | `1` | Positions the statement moves between statements |
|
|
428
|
+
| `index` | `"pitch-order"` | `"degree"` lays notes out by degree across octaves and leaves a hole where a degree has no note |
|
|
429
|
+
|
|
430
|
+
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.
|
|
431
|
+
|
|
362
432
|
### Sequences
|
|
363
433
|
|
|
364
434
|
#### `applySequence(scale: FrettedScale, sequence: number[], options?: SequenceOptions) => FrettedNote[][]`
|
|
@@ -379,6 +449,8 @@ Options:
|
|
|
379
449
|
- `startDegree` — starting degree (default: `1`)
|
|
380
450
|
- `passes` — max number of passes (default: all that fit)
|
|
381
451
|
|
|
452
|
+
With `boundToShape: true`, passes climb the shape and stop at its top: the first pass that needs a note the shape lacks ends the sequence. On the C major `E Shape` scale, `applySequence(scale, SEQ_1235, { incremental: true })` is 12 passes, from `C3 D3 E3 G3` to `G4 A4 B4 D5`. A sequence that begins by going down starts at the top of the shape, so it has little room: `DESCENDING_THIRDS` with `incremental: true` is two passes. For a descending drill through the whole shape use `walk` with `direction: "down"`. `boundToShape: false` wraps degrees into the next octave instead (seven passes for `SEQ_1235` on that scale).
|
|
453
|
+
|
|
382
454
|
#### `flattenSequence(passes: FrettedNote[][]) => FrettedNote[]`
|
|
383
455
|
|
|
384
456
|
Flatten multi-pass results into a single array:
|
|
@@ -451,12 +523,23 @@ Options:
|
|
|
451
523
|
- `tempo` — BPM (default: `120`)
|
|
452
524
|
- `duration` — default note duration: `4`, `8`, `16` (default: `8`)
|
|
453
525
|
- `tuning` — override tuning (default: `STANDARD`)
|
|
454
|
-
- `key` —
|
|
455
|
-
- `timeSignature` — e.g. `[4, 4]`
|
|
456
|
-
- `notesPerBar` —
|
|
526
|
+
- `key` — a tonic and an optional mode, with or without a space: `"A"`, `"Am"`, `"A minor"`, `"F# major"`, `"D dorian"` (default: `"C"`). Minor keys are written as minor (`\ks Aminor`), other modes as their relative major, a tonic with no key signature as its enharmonic (`"G#"` is `\ks Ab`); a key that cannot be read is written as `C`
|
|
527
|
+
- `timeSignature` — meter, e.g. `[4, 4]` (default `[4, 4]`)
|
|
528
|
+
- `notesPerBar` — beats per bar. When omitted, a bar closes when its durations exactly fill the time signature: a beat that does not fit the space left closes the bar short, and a beat longer than a bar sits alone in its bar. When given, a bar closes every `notesPerBar` beats
|
|
457
529
|
- `noteDurations` — per-note duration array
|
|
458
530
|
- `rhythmPattern` — repeating duration cycle, e.g. `[8, 8, 16, 16]`
|
|
459
531
|
|
|
532
|
+
#### `keySignature(tonic: string, mode?: KeyMode) => KeySignature | undefined`
|
|
533
|
+
|
|
534
|
+
The key signature `toAlphaTeX` writes for a tonic and a mode: `{ tonic, mode: "major" | "minor", accidentals }` with `accidentals` from -7 to 7. Minor and aeolian are minor; every other mode is its relative major. Returns `undefined` for an unreadable tonic or mode. No Tonal dependency.
|
|
535
|
+
|
|
536
|
+
```js
|
|
537
|
+
keySignature("A", "minor"); // => { tonic: "A", mode: "minor", accidentals: 0 }
|
|
538
|
+
keySignature("G#"); // => { tonic: "Ab", mode: "major", accidentals: -4 }
|
|
539
|
+
keySignature("D", "dorian"); // => { tonic: "C", mode: "major", accidentals: 0 }
|
|
540
|
+
keySignature("H"); // => undefined
|
|
541
|
+
```
|
|
542
|
+
|
|
460
543
|
#### `toAsciiTab(notes: FrettedNote[], options?: AsciiTabOptions) => string`
|
|
461
544
|
|
|
462
545
|
Format notes as ASCII tablature:
|
|
@@ -490,7 +573,7 @@ const am7 = arpeggioFromShape(get("G Shape"), "Am7", "C");
|
|
|
490
573
|
// Each note's .interval is in the C-major (parent) frame, e.g. "6M" for A
|
|
491
574
|
```
|
|
492
575
|
|
|
493
|
-
The returned notes carry their **parent-scale** `interval` and `degree` fields unchanged — the chord name determines which pitch classes are kept, but the notes still report their position within the parent scale.
|
|
576
|
+
The returned notes carry their **parent-scale** `interval` and `degree` fields unchanged — the chord name determines which pitch classes are kept, but the notes still report their position within the parent scale. They also carry `chordStep` (the note's place among the chord's tones counted up in pitch from the chord's root, 1 is the root) and `chordInterval` (the interval from the chord's root): for Am7 in C major the A has `interval: "6M"`, `chordStep: 1`, `chordInterval: "1P"`. The result carries `chordStepCount`, the number of tones in the chord. The notes are copies of the parent's, not the same objects. An empty result has a `reason`: `"empty-parent"`, `"unknown-chord"` or `"no-chord-tones"`.
|
|
494
577
|
|
|
495
578
|
#### `arpeggioFromScale(parent: FrettedScale, chordName: string) => FrettedScale`
|
|
496
579
|
|
|
@@ -510,7 +593,7 @@ arpeggioFromScale(cMajor, "m7"); // tonic = "C"
|
|
|
510
593
|
|
|
511
594
|
#### `filterChordTones(scale: FrettedScale, intervals: string[]) => FrettedScale`
|
|
512
595
|
|
|
513
|
-
Low-level parent-frame filter. Retains notes whose `interval` field (relative to the parent root) is in the provided set. Use this when you have already translated intervals to the parent frame, or when you want zero Tonal dependencies:
|
|
596
|
+
Low-level parent-frame filter. Retains notes whose `interval` field (relative to the parent root) is in the provided set. List the intervals from the chord's root in rising order of pitch: each kept note is a copy with `chordStep` set to the 1-based place of its `interval` in the list, and the result's `chordStepCount` is the number of intervals listed (no `chordInterval` is set). Use this when you have already translated intervals to the parent frame, or when you want zero Tonal dependencies:
|
|
514
597
|
|
|
515
598
|
```js
|
|
516
599
|
import { filterChordTones, buildFrettedScale, get } from "tonal-guitar";
|
|
@@ -581,7 +664,7 @@ scale.scaleName; // => "A major"
|
|
|
581
664
|
buildFromScale(get("Pentatonic Box 1"), "A minor pentatonic");
|
|
582
665
|
```
|
|
583
666
|
|
|
584
|
-
> **v0.2.0 behavior change (pitch-correctness fix).** `buildFromScale` now relabels `shape` into `scaleName`'s interval frame (via `relabelShape`) before building. Previously, `buildFromScale(get("E Shape"), "A minor")` applied the major-frame shape as-is at the "A" tonic, silently producing **A-major pitch classes** tagged `scaleType: "aeolian"`. As of v0.2.0 the same call produces correct A-natural-minor notes (`A=1P`, `C=3m`, `E=5P`) in the relabeled geometry. If the shape can't be relabeled into the requested frame, `
|
|
667
|
+
> **v0.2.0 behavior change (pitch-correctness fix).** `buildFromScale` now relabels `shape` into `scaleName`'s interval frame (via `relabelShape`) before building. Previously, `buildFromScale(get("E Shape"), "A minor")` applied the major-frame shape as-is at the "A" tonic, silently producing **A-major pitch classes** tagged `scaleType: "aeolian"`. As of v0.2.0 the same call produces correct A-natural-minor notes (`A=1P`, `C=3m`, `E=5P`) in the relabeled geometry. If the shape can't be relabeled into the requested frame, `buildFromScale` returns the empty sentinel with `reason: "shape-cannot-play-scale"` (it never builds the unrelabeled shape). See [Shape Relabeling](#shape-relabeling) above.
|
|
585
668
|
|
|
586
669
|
```js
|
|
587
670
|
// v0.2.0: minor tonics now produce correct pitch content --
|
|
@@ -593,13 +676,30 @@ const aMinor = buildFromScale(get("E Shape"), "A minor");
|
|
|
593
676
|
aMinor.notes.find((n) => n.pc === "C").interval; // => "3m"
|
|
594
677
|
```
|
|
595
678
|
|
|
679
|
+
Every non-empty result has `relabeled: true`. An empty result carries a `reason`: `"unknown-scale"` (the name is unknown or has no tonic), `"shape-cannot-play-scale"`, or the build's own reason.
|
|
680
|
+
|
|
681
|
+
```js
|
|
682
|
+
buildFromScale(get("E Shape"), "C harmonic minor").reason; // => "shape-cannot-play-scale"
|
|
683
|
+
```
|
|
684
|
+
|
|
685
|
+
#### `canPlay(shape: ScaleShape, scaleName: string) => boolean`
|
|
686
|
+
|
|
687
|
+
Whether every note of `shape` belongs to the scale once the shape is relabeled into the scale's frame. `false` for an unknown scale name; a scale type with no tonic (`"dorian"`) is accepted. It means the shape's notes all belong to the scale, not that the shape covers the scale. It differs from `isShapeCompatible`, which compares the shape's own labels without relabeling.
|
|
688
|
+
|
|
689
|
+
```js
|
|
690
|
+
canPlay(get("E Shape"), "C major"); // => true
|
|
691
|
+
canPlay(get("E Shape"), "A minor"); // => true (isShapeCompatible says false)
|
|
692
|
+
canPlay(get("E Shape"), "C harmonic minor"); // => false
|
|
693
|
+
canPlay(get("E Shape"), "C nonsense"); // => false
|
|
694
|
+
```
|
|
695
|
+
|
|
596
696
|
#### `relabelShapeToScale(shape: ScaleShape, scaleName: string, options?: RelabelOptions) => ScaleShape | undefined`
|
|
597
697
|
|
|
598
698
|
Integration-tier wrapper over the pure `relabelShape` primitive (see [Shape Relabeling](#shape-relabeling)): resolves `scaleName` via Tonal's `Scale.get()` and relabels `shape` into that scale's interval frame. Enharmonic spelling is inherited from the target scale's own intervals.
|
|
599
699
|
|
|
600
700
|
```js
|
|
601
701
|
relabelShapeToScale(get("G Shape"), "A minor", { name: "Em Shape", quality: "minor", parentShape: "G Shape" });
|
|
602
|
-
//
|
|
702
|
+
// the registered get("Em Shape"), apart from `featured`, which a relabel never carries
|
|
603
703
|
|
|
604
704
|
relabelShapeToScale(get("E Shape"), "bogus scale"); // => undefined
|
|
605
705
|
```
|
|
@@ -713,10 +813,12 @@ modeShapes("A dorian");
|
|
|
713
813
|
The package exports these TypeScript interfaces:
|
|
714
814
|
|
|
715
815
|
- `FrettedNote` — a note on the fretboard with position, pitch, and interval info
|
|
716
|
-
- `FrettedScale` — a scale applied to the fretboard (with `empty` sentinel pattern)
|
|
816
|
+
- `FrettedScale` — a scale applied to the fretboard (with `empty` sentinel pattern; an empty result carries a `reason`)
|
|
817
|
+
- `FrettedScaleReason` — why a `FrettedScale` is empty (`"invalid-root"`, `"shape-does-not-fit"`, `"unknown-scale"`, `"unknown-chord"`, `"shape-cannot-play-scale"`, `"no-chord-tones"`, `"empty-parent"`, `"no-arpeggio-shape"`)
|
|
818
|
+
- `BuildOptions` — options of `buildFrettedScale` (`allowOpenStrings`)
|
|
717
819
|
- `ScaleShape` — a scale shape definition (intervals per string, plus optional `quality`/`parentShape` metadata set on entries derived via `relabelShape`)
|
|
718
820
|
- `ChordShape` — a chord voicing definition (one interval per string + fingerings + optional harmonic metadata)
|
|
719
|
-
- `RelabelOptions` — options for `relabelShape`/`relabelShapeToScale` (`name`, `quality`, `parentShape`)
|
|
821
|
+
- `RelabelOptions` — options for `relabelShape`/`relabelShapeToScale` (`name`, `quality`, `parentShape`, `cagedPosition`, `chordType`)
|
|
720
822
|
- `Barre` — barre chord finger placement
|
|
721
823
|
- `Fingering` — chord shape applied to a specific root
|
|
722
824
|
- `FretboardPosition` — absolute position on the fretboard (string, fret, note, midi)
|
|
@@ -728,6 +830,8 @@ The package exports these TypeScript interfaces:
|
|
|
728
830
|
- `InferenceProbe` — normalised internal probe used by the scoring core
|
|
729
831
|
- `ScoreBreakdown` — transparent per-term score breakdown on each `InferenceCandidate`
|
|
730
832
|
- `WalkOptions` — options for `walkPattern`
|
|
833
|
+
- `WalkSpec` — options for `walk`
|
|
834
|
+
- `KeyMode`, `KeySignature` — the mode argument and the result of `keySignature`
|
|
731
835
|
- `SequenceOptions` — options for `applySequence`
|
|
732
836
|
- `AlphaTexOptions` — options for `toAlphaTeX`
|
|
733
837
|
- `AsciiTabOptions` — options for `toAsciiTab`
|