{"id":13880724,"url":"https://github.com/martijnversluis/ChordSheetJS","last_synced_at":"2025-07-16T17:31:01.990Z","repository":{"id":28990870,"uuid":"32517596","full_name":"martijnversluis/ChordSheetJS","owner":"martijnversluis","description":"A JavaScript library for parsing and formatting chords and chord sheets","archived":false,"fork":false,"pushed_at":"2025-07-11T16:09:28.000Z","size":7304,"stargazers_count":362,"open_issues_count":14,"forks_count":55,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-07-11T17:54:18.956Z","etag":null,"topics":["chord-sheet","chordpro","chords","javascript","parsing","typescript"],"latest_commit_sha":null,"homepage":"https://martijnversluis.github.io/ChordSheetJS/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/martijnversluis.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"martijnversluis"}},"created_at":"2015-03-19T11:32:09.000Z","updated_at":"2025-07-11T16:09:31.000Z","dependencies_parsed_at":"2023-11-24T21:21:25.732Z","dependency_job_id":"eadb714b-30a4-4f40-b562-21971d896e64","html_url":"https://github.com/martijnversluis/ChordSheetJS","commit_stats":{"total_commits":786,"total_committers":10,"mean_commits":78.6,"dds":0.5254452926208651,"last_synced_commit":"ff908683b59e5177aba7549d0be6734169df2a43"},"previous_names":[],"tags_count":150,"template":false,"template_full_name":null,"purl":"pkg:github/martijnversluis/ChordSheetJS","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/martijnversluis%2FChordSheetJS","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/martijnversluis%2FChordSheetJS/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/martijnversluis%2FChordSheetJS/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/martijnversluis%2FChordSheetJS/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/martijnversluis","download_url":"https://codeload.github.com/martijnversluis/ChordSheetJS/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/martijnversluis%2FChordSheetJS/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265527544,"owners_count":23782480,"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":["chord-sheet","chordpro","chords","javascript","parsing","typescript"],"created_at":"2024-08-06T08:03:25.632Z","updated_at":"2025-07-16T17:31:01.984Z","avatar_url":"https://github.com/martijnversluis.png","language":"TypeScript","readme":"# ChordSheetJS [![Code Climate](https://codeclimate.com/github/martijnversluis/ChordSheetJS/badges/gpa.svg)](https://codeclimate.com/github/martijnversluis/ChordSheetJS) [![CI](https://github.com/martijnversluis/ChordSheetJS/actions/workflows/ci.yml/badge.svg)](https://github.com/martijnversluis/ChordSheetJS/actions/workflows/ci.yml?query=branch%3Amaster) [![Release](https://github.com/martijnversluis/ChordSheetJS/actions/workflows/release.yml/badge.svg)](https://github.com/martijnversluis/ChordSheetJS/actions/workflows/release.yml)\n\nA JavaScript library for parsing and formatting chord sheets\n\n**Contents**\n\n- [Installation](#installation)\n- [How to ...?](#how-to-)\n- [Try it online](https://martijnversluis.github.io/ChordFiddle/)\n- [Supported ChordPro directives](#supported-chordpro-directives)\n- [Project board](https://github.com/users/martijnversluis/projects/4/views/1)\n- [API docs](https://martijnversluis.github.io/ChordSheetJS/)\n- [Contributing](CONTRIBUTING.md)\n\n## Installation\n\n### Package managers\n\n`ChordSheetJS` is on npm, to install run:\n\n```bash\nnpm install chordsheetjs\n```\n\nLoad with `import`:\n\n```javascript\nimport ChordSheetJS from 'chordsheetjs';\n```\n\nor `require()`:\n\n```javascript\nvar ChordSheetJS = require('chordsheetjs').default;\n```\n\n### Standalone bundle file\n\nIf you're not using a build tool, you can download and use the `bundle.js` from the\n[latest release](https://github.com/martijnversluis/ChordSheetJS/releases/latest):\n\n```html\n\u003cscript src=\"bundle.js\"\u003e\u003c/script\u003e\n\u003cscript\u003e\n  // ChordSheetJS is available in global namespace now\n  const parser = new ChordSheetJS.ChordProParser();\n\u003c/script\u003e\n```\n\n## How to ...?\n\n### Parse chord sheet\n\n#### Regular chord sheets\n\n```javascript\nconst chordSheet = `\n       Am         C/G        F          C\nLet it be, let it be, let it be, let it be\nC                G              F  C/E Dm C\nWhisper words of wisdom, let it be`.substring(1);\n\nconst parser = new ChordSheetJS.ChordsOverWordsParser();\nconst song = parser.parse(chordSheet);\n```\n\n#### Ultimate Guitar chord sheets\n\n```javascript\nconst chordSheet = `\n[Chorus]\n       Am         C/G        F          C\nLet it be, let it be, let it be, let it be\nC                G              F  C/E Dm C\nWhisper words of wisdom, let it be`.substring(1);\n\nconst parser = new ChordSheetJS.UltimateGuitarParser();\nconst song = parser.parse(chordSheet);\n```\n\n#### Chord pro format\n\n```javascript\nconst chordSheet = `\n{title: Let it be}\n{subtitle: ChordSheetJS example version}\n\n{start_of_chorus: Chorus}\nLet it [Am]be, let it [C/G]be, let it [F]be, let it [C]be\n[C]Whisper words of [G]wisdom, let it [F]be [C/E] [Dm] [C]\n{end_of_chorus}`.substring(1);\n\nconst parser = new ChordSheetJS.ChordProParser();\nconst song = parser.parse(chordSheet);\n```\n\n### Display a parsed sheet\n\n#### Plain text format\n\n```javascript\nconst formatter = new ChordSheetJS.TextFormatter();\nconst disp = formatter.format(song);\n```\n\n#### HTML format\n\n##### Table-based layout\n\n```javascript\nconst formatter = new ChordSheetJS.HtmlTableFormatter();\nconst disp = formatter.format(song);\n```\n\n##### Div-based layout\n\n```javascript\nconst formatter = new ChordSheetJS.HtmlDivFormatter();\nconst disp = formatter.format(song);\n```\n\n#### Chord pro format\n\n```javascript\nconst formatter = new ChordSheetJS.ChordProFormatter();\nconst disp = formatter.format(song);\n```\n\n### Serialize/deserialize\n\nChord sheets (`Song`s) can be serialized to plain JavaScript objects, which can be converted to JSON, XML etc by\nthird-party libraries. The serialized object can also be deserialized back into a `Song`.\n\n```javascript\nconst serializedSong = new ChordSheetSerializer().serialize(song);\nconst deserialized = new ChordSheetSerializer().deserialize(serializedSong);\n```\n\n### Add styling\n\nThe HTML formatters (HtmlTableFormatter and HtmlDivFormatter) can provide basic CSS to help with styling the output:\n\n```javascript\nHtmlTableFormatter.cssString();\n// .paragraph {\n//   margin-bottom: 1em;\n// }\n\nHtmlTableFormatter.cssString('.chordSheetViewer');\n// .chordSheetViewer .paragraph {\n//   margin-bottom: 1em;\n// }\n\nHtmlTableFormatter.cssObject();\n// '.paragraph': {\n//   marginBottom: '1em'\n// }\n```\n\n### Parsing and modifying chords\n\n```javascript\nimport { Chord } from 'chordsheetjs';\n```\n\n#### Parse\n\n```javascript\nconst chord = Chord.parse('Ebsus4/Bb');\n```\n\nParse numeric chords (Nashville system):\n\n```javascript\nconst chord = Chord.parse('b1sus4/#3');\n```\n\n#### Display with #toString\n\nUse #toString() to convert the chord to a chord string (eg Dsus/F#)\n\n```javascript\nconst chord = Chord.parse('Ebsus4/Bb');\nchord.toString(); // --\u003e \"Ebsus4/Bb\"\n```\n\n#### Clone\n\n```javascript\nvar chord2 = chord.clone();\n```\n\n#### Normalize\n\nNormalizes keys B#, E#, Cb and Fb to C, F, B and E\n\n```javascript\nconst chord = Chord.parse('E#/B#');\nnormalizedChord = chord.normalize();\nnormalizedChord.toString(); // --\u003e \"F/C\"\n```\n\n#### ~~Switch modifier~~\n\n***Deprecated***\n\nConvert # to b and vice versa\n\n```javascript\nconst chord = parseChord('Eb/Bb');\nconst chord2 = chord.switchModifier();\nchord2.toString(); // --\u003e \"D#/A#\"\n```\n\n#### Use specific modifier\n\nSet the chord to a specific modifier (# or b)\n\n```javascript\nconst chord = Chord.parse('Eb/Bb');\nconst chord2 = chord.useModifier('#');\nchord2.toString(); // --\u003e \"D#/A#\"\n```\n\n```javascript\nconst chord = Chord.parse('Eb/Bb');\nconst chord2 = chord.useModifier('b');\nchord2.toString(); // --\u003e \"Eb/Bb\"\n```\n\n#### Transpose up\n\n```javascript\nconst chord = Chord.parse('Eb/Bb');\nconst chord2 = chord.transposeUp();\nchord2.toString(); // -\u003e \"E/B\"\n```\n\n#### Transpose down\n\n```javascript\nconst chord = Chord.parse('Eb/Bb');\nconst chord2 = chord.transposeDown();\nchord2.toString(); // -\u003e \"D/A\"\n```\n\n#### Transpose\n\n```javascript\nconst chord = Chord.parse('C/E');\nconst chord2 = chord.transpose(4);\nchord2.toString(); // -\u003e \"E/G#\"\n```\n\n```javascript\nconst chord = Chord.parse('C/E');\nconst chord2 = chord.transpose(-4);\nchord2.toString(); // -\u003e \"Ab/C\"\n```\n\n#### Convert numeric chord to chord symbol\n\n```javascript\nconst numericChord = Chord.parse('2/4');\nconst chordSymbol = numericChord.toChordSymbol('E');\nchordSymbol.toString(); // -\u003e \"F#/A\"\n```\n\n## Supported ChordPro directives\n\nAll directives are parsed and are added to `Song.metadata`. The list below indicates whether formatters actually\nuse those to change the generated output.\n\n:heavy_check_mark: = supported\n\n:clock2: = will be supported in a future version\n\n:heavy_multiplication_x: = currently no plans to support it in the near future\n\n### Meta-data directives\n\n| Directive        | Support            |\n|:---------------- |:------------------:|\n| title (short: t) | :heavy_check_mark: |\n| subtitle         | :heavy_check_mark: |\n| artist           | :heavy_check_mark: |\n| composer         | :heavy_check_mark: |\n| lyricist         | :heavy_check_mark: |\n| copyright        | :heavy_check_mark: |\n| album            | :heavy_check_mark: |\n| year             | :heavy_check_mark: |\n| key              | :heavy_check_mark: |\n| time             | :heavy_check_mark: |\n| tempo            | :heavy_check_mark: |\n| duration         | :heavy_check_mark: |\n| capo             | :heavy_check_mark: |\n| meta             | :heavy_check_mark: |\n\n### Formatting directives\n\n| Directive                  | Support                  |\n|:-------------------------- |:------------------------:|\n| comment (short: c)         | :heavy_check_mark:       |\n| comment_italic (short: ci) | :heavy_multiplication_x: |\n| comment_box (short: cb)    | :heavy_multiplication_x: |\n| chorus                     | :heavy_multiplication_x: |\n| image                      | :heavy_multiplication_x: |\n\n### Environment directives\n\n| Directive                    | Support            |\n|:---------------------------- |:------------------:|\n| start_of_chorus (short: soc) | :heavy_check_mark: |\n| end_of_chorus (short: eoc)   | :heavy_check_mark: |\n| start_of_verse               | :heavy_check_mark: |\n| end_of_verse                 | :heavy_check_mark: |\n| start_of_tab (short: sot)    | :heavy_check_mark: |\n| end_of_tab (short: eot)      | :heavy_check_mark: |\n| start_of_grid                | :heavy_check_mark: |\n| end_of_grid                  | :heavy_check_mark: |\n\n### Chord diagrams\n\n| Directive | Support            |\n|:--------- |:------------------:|\n| define    | :heavy_check_mark: |\n| chord     | :heavy_check_mark: |\n\n### Fonts, sizes and colours\n\n| Directive   | Support                  |\n|:----------- |:------------------------:|\n| textfont    | :heavy_check_mark:       |\n| textsize    | :heavy_check_mark:       |\n| textcolour  | :heavy_check_mark:       |\n| chordfont   | :heavy_check_mark:       |\n| chordsize   | :heavy_check_mark:       |\n| chordcolour | :heavy_check_mark:       |\n| tabfont     | :heavy_multiplication_x: |\n| tabsize     | :heavy_multiplication_x: |\n| tabcolour   | :heavy_multiplication_x: |\n\n### Output related directives\n\n| Directive                      | Support                  |\n|:------------------------------ |:------------------------:|\n| new_page (short: np)           | :heavy_multiplication_x: |\n| new_physical_page (short: npp) | :heavy_multiplication_x: |\n| column_break (short: cb)       | :heavy_multiplication_x: |\n| grid (short: g)                | :heavy_multiplication_x: |\n| no_grid (short: ng)            | :heavy_multiplication_x: |\n| titles                         | :heavy_multiplication_x: |\n| columns (short: col)           | :heavy_multiplication_x: |\n\n### Custom extensions\n\n| Directive | Support            |\n|:--------- |:------------------:|\n| x_        | :heavy_check_mark: |\n\n## API docs\n\nFor more information, see the [API docs](https://martijnversluis.github.io/ChordSheetJS/).\n","funding_links":["https://github.com/sponsors/martijnversluis"],"categories":["TypeScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmartijnversluis%2FChordSheetJS","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmartijnversluis%2FChordSheetJS","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmartijnversluis%2FChordSheetJS/lists"}