fretboard
🎸 Programatically handle the notes of fretted string instruments, like the guitar
Table of Contents
Install
$ npm install --save fretboard
The module has three classes, Fretboard, MusicString, MusicNote, available as follows:
var Fretboard = ;var MusicString = FretboardMusicString;var MusicNote = FretboardMusicNote;
A Fretboard
is an array-like object of MusicString
s, which are array-like objects of MusicNote
s.
Usage
var Fretboard = ; var guitar = ;// or, explicitly stating the default tuning and number of fretsvar guitar = 'EADGBE' 20; // or make your own arrangement of strings and fretsvar ukulele = 'GCEA' 15;
Compatible with all tunings available in string-tunings. Build yourself a whole string orchestra!
var tunings = ;var openG = tuningsguitaropenG bass = tuningsbassstandard mandolin = tuningsmandolinstandard;
Find Notes
A Fretboard
is a zero-indexed array-like object of MusicString
s, which are array-like objects of MusicNote
s. The 0th element of a string is the open note, and so the 1st element is the 1st fret, etc. Thus, the fretboard acts as a 2D array of note names.
// 1st string, 5th fret should be an Aguitar05//=> MusicNote { note: 'A' } ukulele35note//=> 'D'
Change tunings
On individual strings:
// tune individual strings to a specific keyguitar5guitar50//=> MusicNote { note: 'D' } // or a specific number of half stepsguitar3guitar3key//=> 'F#' // Now the tuning is:guitartuning//=> [ 'E', 'A', 'D', 'F#', 'B', 'D' ]
On the whole fretboard:
// Retune the whole guitar:guitarguitartuning// flats are converted into sharps.//=> [ 'D', 'A', 'D', 'F#', 'A', 'D' ] // or tune the whole guitar up or down a number of half stepsguitar//=> [ 'G', 'D', 'G', 'B', 'D', 'G' ]
Find notes
Retrieve an array of fret numbers corresponding to the note.
On individual strings:
var guitar = 'EADGBE' 24;guitar0//=> [ 0, 12, 24 ]
On the whole fretboard:
guitar//=> [ [ 0, 12, 24 ],// [ 7, 19 ],// [ 2, 14 ],// [ 9, 21 ],// [ 5, 17 ],// [ 0, 12, 24 ] ]
API
Fretboard Object
A Fretboard
acts as an array of MusicString
Objects.
Properties
Property | Type | Description | Default |
---|---|---|---|
tuning |
Array | the keys of each of the strings | [ 'E', 'A', 'D', 'G' 'B', 'E' ] |
numStrings |
integer | the number of strings | 6 |
numFrets |
integer | the number of frets | 20 |
Methods
fretboard.find( note )
Returns all occurrences of a note across the fretboard in a 2D array of fret numbers. For example, if the first occurrence of an A
occurs on the 1st string, 5th fret, fretboard.find('A')[0][0] = 5
.
##### fretboard.retune( tuningString )
Re-tunes the fretboard. Must be string of same length as number of strings. Also accepts array of notes.
example:
var bass = 'EADG'; bassbasstuning//=> [ 'B', 'E', 'A', 'D' ]
fretboard.tuneAll( steps )
Tunes the fretboard up or down a given number of half-steps.
example:
var guitar = ; guitarguitartuning//=> [ 'D', 'G', 'C', 'F', 'A', 'D' ] guitarguitartuning//=> [ 'E', 'A', 'D', 'G' 'B', 'E' ]
Array-like properties & methods
These are provided to treat the Fretboard
as an array of MusicString
s.
fretboard.length <integer>
: equivalent to numStrings
fretboard.forEach( function(element, index, strings) )
: an Array.forEach
equivalent for the strings
Static Methods
Fretboard.parseTuningString( tuningString )
Parses a string of notes into an array of note names.
example:
Fretboard//=> ['E', 'A', 'D', 'G' 'B', 'E'] Fretboard;//=> ['G', 'C', 'E', 'A'] Fretboard//=> ['D', 'A', 'D', 'F#', 'A', 'D']
MusicString Object
A MusicString
acts as an array of MusicNote
Objects.
Properties
Property | Type | Description | Default |
---|---|---|---|
key |
String | The note of the open string | Required input |
numFrets |
integer | The number of frets | 20 |
Methods
musicString.find( note )
Finds all occurrences of a note. Returns an array of the fret numbers.
musicString.tuneTo( note )
Tunes the whole string to a given key.
musicString.tune( steps )
Tune the string up or down a given number of half-steps.
Array-like properties & methods
These are provided to treat the MusicString
as an array of MusicNote
s.
musicString.length <integer>
: equivalent to numFrets
musicString.forEach( function(element, index, strings) )
: an Array.forEach
equivalent for the notes
MusicNote Object
A MusicNote
is an object with a note
property and the following methods. Sharps (#
) are preferred to flats (b
), and flats will be translated accordingly.
Methods
None of the methods affect the note
value, and all of them have static counterparts.
musicNote.diff( note )
Returns the number of half-steps between the current note and a given one. This is always positive, assuming the current note is lower in pitch.
Static version: MusicNote.diff(note, note)
example:
var note = 'A';belownote//=> 11 note = 'G#';note//=> 1
musicNote.tuned( steps )
Returns the pitch value of a note that is steps
half-steps away.
Static version: MusicNote.tuned(note, steps)
example:
var note = 'A';note//=> 'D'note//=> 'E'
musicNote.up( steps )
Returns the pitch value of a note that is steps
half-steps higher.
Static version: MusicNote.up(note, steps)
musicNote.down( steps )
Returns the pitch value of a note that is steps
half-steps lower.
Static version: MusicNote.down(note, steps)
musicNote.flat()
Returns the pitch value of the note one half-step lower the note.
Static version: MusicNote.flat(note)
musicNote.sharp()
Returns the pitch value of the note one half-step higher the note.
Static version: MusicNote.sharp(note)
License
MIT © 2016 Robert Pirtle