# Music Notation library An open-source library I built to turn small text blocks into music notation: guitar chord diagrams, piano keyboards, fretboards and chord charts, drawn as SVG and HTML. You write a fenced code block in a note, and the library draws it, in [[Obsidian]], on [[Obsidian Publish]] or on any web page. The npm package is `@dsebastien/music-notation`. It's written in [[TypeScript]], built with [[Bun]], uses no framework, and is MIT licensed. ## Why I built it I'm learning [[Guitar (MoC)|guitar]] and [[Piano (MoC)|piano]] again, and I keep my chords, scales and songs as notes in Obsidian. I wanted the diagrams right next to those notes, rendered both in Obsidian and on my public notes site. And I wanted them to come from plain text that stays readable and diffable. The [[Music Practice plugin for Obsidian]] tracks my practice; this library draws the music. I kept it as a separate library (not inside the plugin) so that Obsidian Publish and other projects can use it too. ## What it does - `chord`: guitar chord diagrams with frets, fingers, barres, the position up the neck and the root of the chord marked, in any tuning. You can pick from about 1,800 voicings by chord symbol alone. It also draws piano chords from a symbol or from exact pitches, with fingering. - Every way to play a chord: `voicings: all` in a `chord` block draws every playable voicing of the chord, the easiest first (open chords, then E- and A-shape barres and the other CAGED shapes), each one fingered and named. You can narrow them down by neck area, by the string the root is on, to three strings (triads), or to inversions, on any tuning up to 8 strings (the ukulele too). Since 0.4.0. - `keyboard`: a piano keyboard showing the notes of a scale, a chord or a list, labeled as note names, degrees or intervals (R, b3, 5…). - `fretboard`: a guitar neck showing the notes of a scale, a chord or a list, in any tuning (standard, Drop D, DADGAD…). - `chords`: ChordPro chord charts (ChordPro is a plain-text format for songs), with the chords above the lyrics, verse and chorus sections, and comments. Add `{transpose: 2}` to transpose the chart, with every chord spelled for the new key. Colors follow the Obsidian theme, light and dark. If a block contains a mistake, you get a short message telling you what to write instead, and the source stays visible. ## Examples ````markdown ```chord A x02220 x01230 ``` ```keyboard D dorian labels: degrees ``` ```fretboard scale: A minor pentatonic frets: 5-8 labels: intervals ``` ```` The `chord` line reads as the chord symbol, then the frets, then the fingers. ## Where it runs - In Obsidian, through the [[Music Practice plugin for Obsidian|Music Practice plugin]], from version 0.2.0. It draws the blocks in reading view and live preview, and new chord notes get their voicing and diagram. - On Obsidian Publish, through a small script in `publish.js`. It loads a browser bundle from jsDelivr, and only on pages that contain notation blocks. The guide has the script and the setup steps: https://dsebastien.github.io/music-notation/publish.html - On any web page or JavaScript project, through npm. ## How it's built The [[Music Theory (MoC)|music theory]] comes from tonal and the guitar voicings from chords-db, both MIT licensed. I wrote my own ChordPro parser, because the existing ones are GPL and I wanted the library to stay MIT. Before the first release, a separate AI agent reviewed the code adversarially (i.e., it looked for ways to break it). It reported 20 findings, and I fixed all of them. One example: a malformed ChordPro line could freeze the page. There are 86 automated tests, and every build now imports its own output the way a real project would, after a Bun bug slipped a broken module into two releases. ## Status Version 0.4.0 (October 2026) ships the `chord`, `keyboard`, `fretboard` and `chords` blocks, plus the Publish bundle. Every common chord spelling draws (`CΔ7`, `Cmin6`, `C7b9`…), and modes work as scales (`C lydian`, `A blues`). Several diagrams fit in one block, separated by `---` (a song's chords in a row or a grid), and every diagram can be vertical or horizontal, or mirrored for left-handed players. The guide has live examples and a playground where you type a block and see it drawn. Chords can be written in words (`F Sharp Minor 7`) or just as frets, and the library names them. Scales show the notes that make a mode what it is, compare with another scale, and draw one position on the neck at a time (pentatonic boxes, CAGED shapes, three notes per string) or all of them, and every mode of a key in a row. An empty block can draw what a note's properties say, so a chord note never repeats its frets. Since 0.4.0, the library also works out every way to play a chord: `voicings: all` draws them all, the easiest first, each fingered and named (open, E- or A-shape barre, the CAGED shapes…). It finds them from the chord's notes, not from a list, so it works for any chord and any tuning, the ukulele included. A second adversarial review found 11 issues in the generator (the ukulele's usual chords missing, shapes that need a barre with another finger than the index); all fixed before the release. ![[Music Notation library - voicings.png]] Coming in version 0.5 (built, not released yet): triads on string sets (a chord's three inversions, or a key's seven triads, with R, 3 and 5 in the dots), chord transitions (the easiest way from one chord to the next, with the fingers that stay or slide marked and tips in plain words, and the smoothest voicings for a whole progression), a play bar on every diagram (chords strum, scales go up and down, a click plays a note), and tabs and scores drawn and played by [[AlphaTab|alphaTab]], with imports from Guitar Pro, MusicXML and pasted text tabs. ![[Music Notation library - triads and transitions.png]] ![[Music Notation library - tab.png]] Planned: - In 0.5: tabs and scores with playback (play, slow down, loop, metronome) through alphaTab, playing chords and scales, and imports from Guitar Pro, MusicXML, text tabs and chords-over-lyrics. - Next ideas: triads on string sets and the easiest way from one chord to the next (both built on the voicing generator), arpeggios. - Ideas on the issue tracker: capo, bass, strumming patterns, progressions in roman numerals, export as images, solfège note names, a web component for any website. ## References - Source code: https://github.com/dsebastien/music-notation - Guide: https://dsebastien.github.io/music-notation/ - Live examples: https://dsebastien.github.io/music-notation/examples.html - Playground: https://dsebastien.github.io/music-notation/playground.html - npm: https://www.npmjs.com/package/@dsebastien/music-notation ## Related - [[Music Practice plugin for Obsidian]] - [[Guitar (MoC)]] - [[Piano (MoC)]] - [[Music Theory (MoC)]] - [[Obsidian Publish]]