fretboard-api
v0.7.1
Published
A kind of API for fretboard diagrams
Downloads
41
Readme
fretboard-api
Usage:
- Instantiate a Fretboard. The fretboard will define:
- number of strings
- tuning
- number of frets
- Place Shape on the Fretboard. A shape is a collection of played positions. This can be a chord, an interval, a scale, etc.
- Shapes can then be moved and transposed.
When moving a shape, the shape's form never changes. If the shape is moved to a different string, then the shape's intervals are changed depending on the tuning.
When transposing a shape, the shape's intervals never changes. If the shape is transposed to a different string, then the shape's frets are changed depending on the tuning.
- move: the shape form never changes; the intervals may change.
- transpose: the shape form may change; the intervals never change.
Assumptions
- Western tonal music with 12 semitones per octave.
Conventions
Naming:
interface with "Type" suffix.
Strings numbering
for the user
For the user: strings are numbered starting at 1 and from the lowest pitched to the highest pitched.
For a standard tuning, strings are 1=E, 2=A, 3=D, 4=G, 5=B, 6=E
for the coder (implementation)
Implementation: strings are in an 0-indexed array.
Frets numbering
Frets are numbered starting at 0 and from the head of the neck towards the bridge.
Fret number 0 is the nut, or the "zero fret" installed close the the nut on some guitars.
frets
and fingers
format
The canonical format is a two-dimensional array:
- 1st dimension are strings
- 2nd dimension are frets within a string
A muted string is represented by an empty frets array.
Example2:
C major scale:
[ [8, 10],
[7, 8, 10],
[7, 9, 10],
[7, 9, 10],
[8, 10]
[7, 8] ]
A7 chord:
[ [5], [], [5], [6], [5] [] ]
Allowed input formats:
Frets and fingers can be specified as strings or arrays. They will always be normalized as arrays.
X
or x
define a explicitely non-played (muted) string.
-
define a ignored string.
'0' denote a played open-string.
With only one played note per string:
"022100" --> [ [0], [2], [2], [1], [0], [0] ]
"5X565X" --> [ [5], [], [5], [6], [5] [] ]
space are allowed, useful for frets > 9:
"8 10 10 9 8 8" --> [8, 10, 10, 9, 8, 8]
When there are more than one played note per string, use a comma to separate the strings:
"24,124,134,134,24,12" --> [[2, 4], [1, 2, 4], [1, 3, 4], [1, 3, 4], [2, 4], [1, 2]]
"8 10, 7 8 10, 7 9 10, 7 9 10, 8 10, 7 8" --> [[8, 10], [7, 8, 10], [7, 9, 10], [7, 9, 10], [8, 10] [7, 8]]
Frets normalization
TODO: normalize relative to the root ? That is, some fret will be negative.
Examples:
one played note per string:
[8, 10, 10, 9, 8, 8] --> [[0], [2], [2], [1], [0], [0]]
more than one played note per string:
[[8, 10], [7, 8, 10], [7, 9, 10], [7, 9, 10], [8, 10] [7, 8]] --> [[2, 4], [1, 2, 4], [1, 3, 4], [1, 3, 4], [2, 4] [1, 2]]
root:
root: "0 1" --> {string: 0, fret: 1}
Chord
The mandatory attributes are name
and frets
:
{
name: "E major shape",
frets: "022100"
}
With all optional attributes:
{
name: "E major shape",
quality: "", // minor or lowercase m, or the symbols ° or + for diminished and augmented chords; quality is usually omitted for major chords
suffix: "", // all other characteristics
bass: "", // for slash chords --> is it possible to determine the bass automatically?
inversion: 0, // 0 for no inversion, 1 for first inversion, ... --> is it possible to determine the inversion automatically?
root: 5, // string number of the root note --> by default take the lowest pitched played string
CAGED: "E", // index of the pattern shape for this chord shape
frets: "022100", // X means string muted
fingers: "032100" // 0 means no finger on that string but the string should be played
}
- root: by default the lowest pitched played string will be considered as the root.
Scale
The mandatory attributes are name
and frets
:
{
name: "E shape major scale",
frets: "1 3, 0 1 3, 0 2 3, 0 2 3, 1 3, 0 1 3"
}
With all optional attributes:
{
name: "E shape major scale",
CAGED: "E",
frets: "1 3, 0 1 3, 0 2 3, 0 2 3, 1 3, 0 1 3",
fingers: "2 4, 1 2 4, 1 3 4, 1 3 4, 2 4, 1 2 4",
root: "0 1" // string index 0, fret 1 format: "<string> <fret>"
}
- root: by default the first played note on the lowest pitched played string will be considered as the root.
Free shape
{
name: "Minor pentatonic octave 1",
minor: true,
CAGED: "E",
frets: "0 3,0 2,0 2",
fingers: "1 4,1 3,1 3",
root: "1 0" // string 1, fret 0 format: "<string> <fret>"
// offset: 1, --> determined if lowest root has fret > 0
}
API
Conventions
Method parameters
The format is method(mandatoryParam1, mandatoryParam2, ... mandatoryParamN, {optionalParams})
All mandatory parameters are passed as normal parameters.
All optional parameters are passed as an object.
If the method does not require any mandatory parameter and only has optional parameters, than the method has only one object parameter.
Parameters order
When a method require both a string number and a fret number, then the order is always string, fret.
Tests
All tests:
yarn test
One specific test:
yarn test Fretboard.test.js
Resources:
- https://en.wikipedia.org/wiki/Guitar_tunings
- https://en.wikipedia.org/wiki/Stringed_instrument_tunings
- https://en.wikipedia.org/wiki/Scientific_pitch_notation