{"id":15621752,"url":"https://github.com/pirtleshell/fretboard","last_synced_at":"2025-04-28T14:08:39.525Z","repository":{"id":57241772,"uuid":"76882345","full_name":"pirtleshell/fretboard","owner":"pirtleshell","description":":guitar: Programatically handle the notes of fretted string instruments, like the guitar","archived":false,"fork":false,"pushed_at":"2016-12-19T17:28:17.000Z","size":8,"stargazers_count":14,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-28T14:08:33.671Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pirtleshell.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-12-19T17:24:24.000Z","updated_at":"2022-09-30T21:57:33.000Z","dependencies_parsed_at":"2022-09-07T23:13:23.305Z","dependency_job_id":null,"html_url":"https://github.com/pirtleshell/fretboard","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pirtleshell%2Ffretboard","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pirtleshell%2Ffretboard/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pirtleshell%2Ffretboard/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pirtleshell%2Ffretboard/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pirtleshell","download_url":"https://codeload.github.com/pirtleshell/fretboard/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251326839,"owners_count":21571636,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-03T09:51:44.427Z","updated_at":"2025-04-28T14:08:39.498Z","avatar_url":"https://github.com/pirtleshell.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# fretboard\n\n\u003e :guitar: Programatically handle the notes of fretted string instruments, like the guitar\n\n## Table of Contents\n\n- [Install](#install)\n- [Usage](#usage)\n\t- [Find Notes](#find-notes)\n\t- [Change tunings](#change-tunings)\n\t- [Find notes](#find-notes)\n- [API](#api)\n\t- [Fretboard Object](#fretboard-object)\n\t\t- [Properties](#properties)\n\t\t- [Methods](#methods)\n\t\t- [Array-like properties \u0026 methods](#array-like-properties-methods)\n\t\t- [Static Methods](#static-methods)\n\t- [MusicString Object](#musicstring-object)\n\t\t- [Properties](#properties)\n\t\t- [Methods](#methods)\n\t\t- [Array-like properties \u0026 methods](#array-like-properties-methods)\n\t- [MusicNote Object](#musicnote-object)\n\t\t- [Methods](#methods)\n- [License](#license)\n\n## Install\n\n```sh\n$ npm install --save fretboard\n```\n\nThe module has three classes, [Fretboard](#fretboard-object), [MusicString](#musicstring-object), [MusicNote](#musicnote-object), available as follows:\n\n```js\nvar Fretboard = require('fretboard');\nvar MusicString = Fretboard.MusicString;\nvar MusicNote = Fretboard.MusicNote;\n```\n\nA `Fretboard` is an array-like object of `MusicString`s, which are array-like objects of `MusicNote`s.\n\n## Usage\n\n```js\nvar Fretboard = require('fretboard');\n\nvar guitar = new Fretboard();\n// or, explicitly stating the default tuning and number of frets\nvar guitar = new Fretboard('EADGBE', 20);\n\n// or make your own arrangement of strings and frets\nvar ukulele = new Fretboard('GCEA', 15);\n```\n\nCompatible with all tunings available in  [string-tunings](https://github.com/PirtleShell/string-tunings). Build yourself a whole string orchestra!\n\n```js\nvar tunings = require('string-tunings');\nvar openG = new Fretboard(tunings.guitar.open.G),\n     bass = new Fretboard(tunings.bass.standard),\n mandolin = new Fretboard(tunings.mandolin.standard);\n```\n\n### Find Notes\n\nA [`Fretboard`](#fretboard-object) is a zero-indexed array-like object of [`MusicString`](#musicstring-object)s, which are array-like objects of [`MusicNote`](#musicnote-object)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.\n\n```js\n// 1st string, 5th fret should be an A\nguitar[0][5]\n//=\u003e MusicNote { note: 'A' }\n\nukulele[3][5].note\n//=\u003e 'D'\n```\n\n### Change tunings\n\nOn individual strings:\n\n```js\n// tune individual strings to a specific key\nguitar[5].tuneTo('D')\nguitar[5][0]\n//=\u003e MusicNote { note: 'D' }\n\n// or a specific number of half steps\nguitar[3].tune(-1)\nguitar[3].key\n//=\u003e 'F#'\n\n// Now the tuning is:\nguitar.tuning\n//=\u003e [ 'E', 'A', 'D', 'F#', 'B', 'D' ]\n```\n\nOn the whole fretboard:\n\n```js\n// Retune the whole guitar:\nguitar.retune('DADGbAD')\nguitar.tuning\n// flats are converted into sharps.\n//=\u003e [ 'D', 'A', 'D', 'F#', 'A', 'D' ]\n\n// or tune the whole guitar up or down a number of half steps\nguitar.tuneAll(5)\n//=\u003e [ 'G', 'D', 'G', 'B', 'D', 'G' ]\n```\n\n### Find notes\n\nRetrieve an array of fret numbers corresponding to the note.\n\nOn individual strings:\n```js\nvar guitar = new Fretboard('EADGBE', 24);\nguitar[0].find('E')\n//=\u003e [ 0, 12, 24 ]\n```\n\nOn the whole fretboard:\n```js\nguitar.find('E')\n//=\u003e [ [ 0, 12, 24 ],\n//     [ 7, 19 ],\n//     [ 2, 14 ],\n//     [ 9, 21 ],\n//     [ 5, 17 ],\n//     [ 0, 12, 24 ] ]\n```\n\n## API\n\n### Fretboard Object\n\nA `Fretboard` acts as an array of [`MusicString` Objects](#musicstring-object).\n\n#### Properties\n\n| Property     | Type          | Description                     |              Default              |\n|:-------------|:--------------|:--------------------------------|:---------------------------------:|\n| `tuning`     | Array\u003cstring\u003e | the keys of each of the strings | `[ 'E', 'A', 'D', 'G' 'B', 'E' ]` |\n| `numStrings` | integer       | the number of strings           |                `6`                |\n| `numFrets`   | integer       | the number of frets             |               `20`                |\n\n#### Methods\n\n##### `fretboard.find( note )`\n\nReturns 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`.\n\n ##### `fretboard.retune( tuningString )`\n\n Re-tunes the fretboard. Must be string of same length as number of strings. Also accepts array of notes.\n\nexample:\n```js\nvar bass = new Fretboard('EADG');\n\nbass.retune('BEAD')\nbass.tuning\n//=\u003e [ 'B', 'E', 'A', 'D' ]\n```\n\n##### `fretboard.tuneAll( steps )`\n\nTunes the fretboard up or down a given number of half-steps.\n\nexample:\n```js\nvar guitar = new Fretboard();\n\nguitar.tuneAll(-2)\nguitar.tuning\n//=\u003e [ 'D', 'G', 'C', 'F', 'A', 'D' ]\n\nguitar.tuneAll(2)\nguitar.tuning\n//=\u003e [ 'E', 'A', 'D', 'G' 'B', 'E' ]\n```\n\n#### Array-like properties \u0026 methods\n\nThese are provided to treat the `Fretboard` as an array of `MusicString`s.\n\n`fretboard.length \u003cinteger\u003e`: equivalent to `numStrings`\n\n`fretboard.forEach( function(element, index, strings) )`: an `Array.forEach` equivalent for the strings\n\n#### Static Methods\n\n##### `Fretboard.parseTuningString( tuningString )`\n\nParses a string of notes into an array of note names.\n\nexample:\n```js\nFretboard.parseTuningString('EADGBE')\n//=\u003e ['E', 'A', 'D', 'G' 'B', 'E']\n\nFretboard.parseTuningString('GCEA');\n//=\u003e ['G', 'C', 'E', 'A']\n\nFretboard.parseTuningString('DADF#AD')\n//=\u003e ['D', 'A', 'D', 'F#', 'A', 'D']\n```\n\n---------\n\n### MusicString Object\n\nA `MusicString` acts as an array of [`MusicNote` Objects](#musicnote-object).\n\n#### Properties\n| Property   | Type    | Description                 |    Default     |\n|:-----------|:--------|:----------------------------|:--------------:|\n| `key`      | String  | The note of the open string | Required input |\n| `numFrets` | integer | The number of frets         |       20       |\n\n#### Methods\n\n##### `musicString.find( note )`\n\nFinds all occurrences of a note. Returns an array of the fret numbers.\n\n##### `musicString.tuneTo( note )`\n\nTunes the whole string to a given key.\n\n##### `musicString.tune( steps )`\n\nTune the string up or down a given number of half-steps.\n\n\n#### Array-like properties \u0026 methods\n\nThese are provided to treat the `MusicString` as an array of `MusicNote`s.\n\n`musicString.length \u003cinteger\u003e`: equivalent to `numFrets`\n\n`musicString.forEach( function(element, index, strings) )`: an `Array.forEach` equivalent for the notes\n\n---------\n\n### MusicNote Object\n\nA `MusicNote` is an object with a `note` property and the following methods. Sharps (`#`) are preferred to flats (`b`), and flats will be translated accordingly.\n\n#### Methods\n\nNone of the methods affect the `note` value, and all of them have static counterparts.\n\n##### `musicNote.diff( note )`\n\nReturns 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.\n\n**Static version**: `MusicNote.diff(note, note)`\n\nexample:\n```js\nvar note = new MusicNote('A');below\nnote.diff('G#')\n//=\u003e 11\n\nnote = new MusicNote('G#');\nnote.diff('A')\n//=\u003e 1\n```\n\n##### `musicNote.tuned( steps )`\n\nReturns the pitch value of a note that is `steps` half-steps away.\n\n**Static version**: `MusicNote.tuned(note, steps)`\n\nexample:\n```js\nvar note = new MusicNote('A');\nnote.tuned(5)\n//=\u003e 'D'\nnote.tuned(-5)\n//=\u003e 'E'\n```\n\n##### `musicNote.up( steps )`\n\nReturns the pitch value of a note that is `steps` half-steps higher.\n\n**Static version**: `MusicNote.up(note, steps)`\n\n##### `musicNote.down( steps )`\n\nReturns the pitch value of a note that is `steps` half-steps lower.\n\n**Static version**: `MusicNote.down(note, steps)`\n\n##### `musicNote.flat()`\n\nReturns the pitch value of the note one half-step lower the note.\n\n**Static version**: `MusicNote.flat(note)`\n\n##### `musicNote.sharp()`\n\nReturns the pitch value of the note one half-step higher the note.\n\n**Static version**: `MusicNote.sharp(note)`\n\n\n## License\n\nMIT \u0026copy; 2016 [Robert Pirtle](https://pirtle.xyz/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpirtleshell%2Ffretboard","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpirtleshell%2Ffretboard","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpirtleshell%2Ffretboard/lists"}