# Music Notation library An open-source library I built to turn small text blocks into music notation: chord diagrams for guitar and piano, keyboards, fretboards, chord charts, tabs and scores, strumming patterns, progressions and the circle of fifths, drawn as SVG and HTML. Every diagram plays, and copies as an image. 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 There are ten block languages: `chord`, `keyboard`, `fretboard`, `chords`, `strum`, `picking`, `progression`, `circle`, `tab` and `score`. Each block draws, plays, copies as an image and opens full screen. Colors follow the Obsidian theme, light and dark, and a block with a mistake shows a short message telling you what to write instead, with the source still visible. ### Chords and voicings - `chord` draws guitar chord diagrams with frets, fingers, barres, the position up the neck and the root marked. About 1,800 voicings are there by chord symbol alone. - Any common spelling works (`CΔ7`, `Cmin6`, `C7b9`…), and so do words (`F Sharp Minor 7`) and frets alone: the library names the chord, works out the fingers and shows the barre. - Piano chords come from a symbol or from exact pitches, with fingering, as inversions, open, shell or rootless voicings, with both hands. From one chord to the next, the voices move the way a pianist's would. - `voicings: all` draws every way to play a chord, one diagram per shape, the easiest first, up the neck, each fingered and named ("Open", "E shape", "Drop 2", "Hendrix chord"…). The shapes come from the chord's notes, not from a list, so any chord works, on any tuning up to 8 strings (the ukulele too). - You can narrow the voicings down by neck area, by the string the root is on, to three strings (triads), or to inversions. A shape with its highest strings muted counts as the same shape, so it's left out. - The first voicing of a chord is one you can strum: Bdim starts with x2343x, not x20x01. Jazz grips that mute the A string are the exception: the Hendrix grip for C7#9 (x3234x), m7b5, dim7 and 13 from the low E. - Named tunings: standard, Drop D, Drop C, B and A, Double Drop D, DADGAD, Open C and A, Whole step down and Modal C6. - With a capo, `sounds: title` names the chord you hear, then the shape you play: an Em shape with `capo: 3` is "Gm (Em shape)", with "Capo 3" under it. A `title:` you write wins. - Several diagrams fit in one block, separated by `---`, in a row or a grid. Each one can be vertical, horizontal, or mirrored for left-handed players. - Long titles ("F#m7b5, Drop 3 (strings 2-4, 6)") wrap onto two or three lines, so the necks of a row stay in line. - On phones and tablets, chord diagrams and fretboards are a third larger, so each string is easier to tap. - An empty block draws what the note's properties say, so a chord note never repeats its frets. Without `chord_symbol`, it uses `chord_root` and `chord_quality` ("A" and "Minor 7" give Am7, a root alone its major chord), which is what the [[Obsidian Starter Kit]]'s chord and arpeggio templates fill in. Arpeggio and strumming pattern notes draw from their properties too, on Obsidian Publish as in Music Practice. **Voicings**: `voicings: 6` of A, each shape named (Open, G shape, Open strings, Open bass, E shape). ![[Music Notation library - voicings.png]] **From properties**: a strumming pattern note's properties, and the empty `strum` block they draw. ![[Music Notation library - from properties.png]] ### Scales, triads and transitions - `keyboard` and `fretboard` show the notes of a scale, a chord or a list, on piano keys or a guitar neck in any tuning, labeled as note names, degrees or intervals (R, b3, 5…). - Modes work as scales (`C lydian`, `A blues`). A scale shows the notes that make a mode what it is, and compares with another scale. - On the neck, a scale draws one position at a time (pentatonic boxes, CAGED shapes, three notes per string), with a title ("G major, E shape"), or all of them, or every mode of a key in a row. - Arpeggios draw in their CAGED shapes on the neck, and on the keys. - `scales-for:` gives the scale that fits a song's chords. - `fingering: auto both` on a keyboard scale draws the right hand's standard fingering, then the left hand's an octave lower, for major, natural, harmonic and melodic minor. - `exercise: up-down` (or `up`, `down`) on a fretboard with one position draws the run as a tab under it, in 8ths, triplets or 16ths. With a capo, the tab counts frets from the capo, or from the nut with `frets-from: nut`. - 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. **Triads and transitions**: the three G triads on strings 1-3, and the easiest ways from C to Am. ![[Music Notation library - triads and transitions.png]] **Both hands' scale fingering**: `fingering: auto both` on G major, the right hand (1 2 3 1 2 3 4 1…), then the left hand an octave lower (5 4 3 2 1 3 2 1…). ![[Music Notation library - both hands fingering.png]] **Tab exercise**: the first A minor pentatonic box, up and down in triplets. ![[Music Notation library - tab exercise.png]] ### Rhythm, progressions and chord charts - `strum` draws a strumming pattern on a beat grid: the counts, an arrow per strum, accents, muted and ghost strums, chord changes. You write it the way you find it on the web (`D DU UDU`), straight, swung or shuffled, in 4/4, 3/4, 6/8 or 12/8. - `picking` draws a fingerpicking pattern as a small tab with the fingers and the counts. Write PIMA letters (`p` the bass, `p'` the alternate bass on the chord's fifth, `i m a` on strings 3, 2 and 1), string numbers, or a named pattern (`travis`, `alternate bass`, `1-2-3-4`). - `progression` takes roman numerals, Nashville numbers or chord names, and draws them in any key, with each chord's numeral, its function and a diagram, on guitar or piano. - With `key:` and `harmonize: triads` (or `sevenths`, `sus`, `power`) and no chords, a `progression` draws the chord on each degree of any 7-note scale. A degree with no chord of that kind is left out, and the block says so (D dorian has no sus chord on B). - Chord names follow the method books: Am(maj7) and `i(maj7)`, C+maj7 and `bIII+maj7`. Progressions also read `imaj7`, `imMaj7` and `bIIImaj7#5`. - `circle` draws the circle of fifths, with the key's chords tinted and numbered, in any mode. - `chords` draws a ChordPro chart (ChordPro is a plain-text format for songs): the chords above the lyrics, verse and chorus sections, comments. `{transpose: 2}` moves it, with every chord spelled for the new key, and `{diagrams}` adds the chord diagrams. - Bar lines `|` say how long a chart's chords last. The chords between two bar lines share the bar, and dots or slashes give each its beats (`| [G5]. . [D5]. [A5]. |` is two beats of G5, then one of D5 and one of A5). A bar with no chord holds the one before, and a bar of N.C. is silence. Without bar lines, a line plays one chord a bar. - `{simplify}` in a guitar chart draws an easier chord where a plainer chord of the same family is easier to play. Cmaj9 becomes Cmaj7, G5 becomes G and E9 becomes E7, while Am7 and F# stay, since nothing plainer is easier. The easier chords show above the lyrics, in the chords used row and in what the bar plays. - `{capo: auto}` says the chords are written as they sound, and finds the capo that turns the most of them into open shapes: Bb Eb F Gm gets "Capo 3" and draws G C D Em, the shapes to play, and the bar plays the chords as they sound. With `{simplify}` too, the capo is found for the easier chords. Both are for guitar charts only, and the source never changes: the chart draws a copy of the song. - The bar of a guitar chart gets a **Simplify** switch when a chord has an easier one. A click shows the easier chords and the switch reads **Simplified**; a second click brings back the chords as written. Nothing is stored, and a chart with `{simplify}` starts with the switch on. - Progressions and charts play in time: one chord a bar, with a click, a count-in and a loop, to practice the changes at tempo or solo over them. Each chord is strummed on the beats, once a bar, as an arpeggio, or to a strumming pattern, and the chord that plays lights up. **Progression in time**: ii V I vi in C, with the numerals, the diagrams and the bar that plays it. ![[Music Notation library - progression.png]] **A chord chart playing**: one chord a bar, the chord that plays lit. ![[Music Notation library - chart playing.png]] **Picking pattern**: alternate bass over C, G, Am and F, with the fingers and the counts under the tab. ![[Music Notation library - picking pattern.png]] **The chords of a scale**: A harmonic minor with `harmonize: sevenths`, from i(maj7) Am(maj7) to vii°7 G#dim7 (iiø7 Bm7b5, bIII+maj7 C+maj7, iv7 Dm7, V7 E7, bVImaj7 Fmaj7 in between), each with its guitar diagram, and the play bar under them. ![[Music Notation library - harmonize.png]] ### Tabs and scores - `tab` and `score` draw tablature and standard notation from alphaTex, a Guitar Pro or MusicXML file, or a plain-text tab you paste, drawn and played by [[AlphaTab|alphaTab]]. - The bar has Play, Stop, Loop, Metronome and Count-in, like the other bars. On a web page, it stays at the bottom of the screen while a long tab is on screen. - The tempo is in BPM: "− 60 BPM + · 71 %", the tempo the music plays at, with the speed in percent next to it. − and + step by 1 BPM, you can type a number, and the unit button switches to percent. The range is 25 to 150 % of the written tempo, and the BPM follows the score's tempo changes. - **Follow the music** (off by default) scrolls the page, or the pane, by the smallest step that shows the line that plays and the next one. A scroll by hand pauses it until the next Play. - `layout: line` puts the music on one line that scrolls sideways and follows the music: handy for a riff you loop. - `names: on` writes the name of every note above the tablature, for beginners who can't read a staff yet, with a chord's names stacked in string order. A Note names button turns them on and off. - In full screen, the music is drawn again at the width of the screen, so you see more bars on a line and several lines at once. The last line fills the width, a short score grows as long as it fits, and Follow the music is on. **Tabs and scores**: two bars of tab and standard notation, drawn by alphaTab, with the player bar. ![[Music Notation library - tab.png]] ### Playing - Diagrams sound like the instrument: guitar chords strum, piano chords sound together, scales go up and down. The notes light up as they play. - Every block has one play bar, under it. In a row of voicings or a scale's positions, the bar plays the diagram you clicked last (outlined, and named on the bar), and Play all in turn plays them all, a beat of silence apart (and again, with loop on). - The **Sound** menu on the bar lists "Guitar (steel)", "Guitar (nylon)", "Guitar (clean)", "Guitar (overdrive)" and "Piano", and shows what plays: the piano on a keyboard or a piano chord, else the block's guitar. A guitar picked there plays for the whole block until it's drawn again, before the block's `guitar:` line and the page's or the app's guitar. Nothing is stored. Going from a guitar to the piano, or back, redraws the whole block for the other instrument. Tabs and scores have no Sound menu: their tracks name their instruments. - Four guitars: `steel` (a steel-string acoustic, the default), `nylon` (a classical guitar), `clean` (a clean electric guitar) and `overdrive` (an overdriven electric guitar). A `guitar: nylon` line picks one for a block (`{guitar: nylon}` in a chart), and `acoustic`, `classical`, `electric` and `overdriven` work too. Chord diagrams, fretboards, strumming and picking patterns, progressions, the circle of fifths and charts play it; a piano stays a piano, and tabs and scores keep the instruments their tracks name. The nylon guitar is darker and fades sooner, and the overdriven one keeps its level while a chord rings. - Click a diagram to hear it and again to stop, or click a dot or a key to hear one note. In a progression, a click on a chord diagram plays that chord. On a focused diagram, Space or Enter plays and Escape stops. - Sliders show their value ("90 BPM", "12 ms"). - The volume is the app's setting, not a slider on each bar (in Music Practice, **Settings → Playback**; on Publish, `play: { volume }`), and a change is heard at once. - Everything you can click shows the hand cursor. **One play bar per block**: six C voicings, the first one selected (outlined, and named on the bar: "C, Open (1 of 6)"), with Play all in turn on the bar under them. ![[Music Notation library - One play bar per block.png]] ### Captions, note names and languages - `caption: fingering` writes how to play a chord under its diagram, in plain words: "Strum from the 5th string (A). Index on the D string, 2nd fret." It names barres, the thumb, muted and open strings and the capo, and piano chords get each hand's fingers. The words are text, so they wrap, and screen readers and search read them. - In tunings where two strings share a name, the captions and the transition tips name strings by number and note ("the 4th string (D)"), and a tuning written with flats keeps them ("the Gb string"). - In a `progression`, `caption: fingering` describes each chord in the voicing the progression picked; put it before the first `---` for every section. - `caption: formula` writes what a chord, a keyboard or a fretboard shows: "Am7 (A minor seventh): A C E G. Formula 1 b3 5 b7. Also written Amin7, Ami7, A-7." A scale adds its steps (W+H W W W+H W for the minor pentatonic), and `caption: fingering, formula` gives both. - `naming: solfege` (`{naming: solfege}` in a chart) shows Do Ré Mi Fa Sol La Si, with a space before the quality (`Ré m7`, `Sol 7/Si`); `naming: german` writes H for B and B for B♭. Dots, keys, string names, generated titles, charts, progressions, the circle, captions and screen readers all follow it, and the titles you write stay as written. - You can write notes in any of the three: `chord: Rém`, `scale: La mineur`, `notes: Do Mi Sol`, `H7`. Letters are read first, so `Do7` means D°7 unless the block has `naming: solfege` or the line has other solfège names. Tabs, scores and fingering sentences stay in letters. - The texts of the blocks are in English or French: the bars, the view switches, the playback choices, the messages and what screen readers read. On web pages, they follow the page's language. The French uses the words French-speaking guitarists and teachers use: a strumming pattern is a "rythmique", a scale box a "position". **Fingering in words**: A, F and D with `caption: fingering`, each with how to play it under the diagram ("Index bars the 1st fret, strings 1 to 6."). ![[Music Notation library - fingering in words.png]] **Formula captions**: Am7, Cmaj7 and G7 with `caption: formula`, and the play bar with the Copy as image button at its right end. ![[Music Notation library - formula captions.png]] **Solfège note names**: `naming: solfege` on a row of chords (Do, Ré m7, Sol, La m) and on a C major scale in its E shape, with the dots and the string names in solfège too. ![[Music Notation library - solfege note names.png]] ### Accessibility - `root-mark: shape` draws the root as a square dot (its finger or label inside), a square ring on an open string and a small square on its key, for readers who don't tell colors apart. Color is the default. - Every chord diagram, keyboard and fretboard has a description for screen readers: the fingering in words and where the root is, the keys, or the notes string by string. - The fallback accent and wrong-answer colors keep their contrast on dark pages. Themes that set their own colors keep them. **Root marks as shapes**: `root-mark: shape` on C, Am and F (square roots, fingers inside), on the first A minor pentatonic box, and on a D major keyboard (a small square on each D). Each bar ends with the Copy as image button. ![[Music Notation library - root marks as shapes.png]] ### Copy as image and full screen - The picture button at the right end of a bar copies a PNG of the selected diagram, with its title and captions, at twice the size, in the page's colors. Shift+click copies the whole block, and so does a click on a block with one diagram. With playback off, a block gets a small bar with only that button. Tab and score bars don't have it. - The Full screen button, after Copy as image, grows the block to the largest size that fits the screen, centered, with the bar at its usual size. A block too long to fit, such as a long chart, is shown up to 1.5 times larger and scrolls. The space bar plays and pauses there, and Escape takes you back to where you were. ### Sounds - Three engines play the music: `generaluser` ([[GeneralUser GS]], when the page names a folder of instrument files), `sonivox` (alphaTab's small bank, on pages with a tab or a score) and `light` (a built-in synthesizer, always there). The library tries them in that order, so a missing file never means silence. - A page picks an engine with `play: { engine }`, and a block asks for one with an `engine:` line. When the page can't give it, the next one plays, so the note stays portable. - Every engine has the four guitars. With GeneralUser GS, each guitar's file is read at its first use, so a page that plays only nylon never reads the steel-string file. A page picks its guitar with `play: { guitar: 'nylon' }`, and a block's `guitar:` line comes first. - Everything plays in a small room, light by default: chord diagrams, fretboards, keyboards, strumming and picking patterns, progressions, charts, tabs and scores, on every engine (the light synthesizer, the instrument files and alphaTab). A page or an app sets how loud the room is against the notes (`play: { reverb }`, 0 for none to 1) and how long it rings (`room`, from 0.2 seconds, a small room, to 3, a hall). The room is generated, so there's no audio file to download for it. - A soft ceiling sits between the music and the speakers. Loud passages, like an accented strum on six strings or several blocks playing at once, bend toward full volume, so the speakers never cut them flat. - The two electric guitars (`clean` and `overdrive`) can go through an amplifier, off by default: `play: { amp: { drive, cabinet } }`. The drive changes the tone and keeps the loudness, and `cabinet: true` adds a speaker cabinet's sound (less deep bass, less fizz, more mids). The acoustic guitars, the piano, tabs and scores never go through it. - `play: { dry: true }` leaves out the room, the ceiling and the amplifier, for a site or an app that adds its own effects. - The GeneralUser GS files come from the [[Music Notation Sounds library]], one small soundfont per instrument (a steel-string guitar is 112 KB, a grand piano 392 KB, where the whole bank is 30.82 MB), all at the same loudness. A score downloads only the instruments it plays, at the first Play. - The library has no built-in address for those files, so it doesn't depend on a CDN: apps pass the files, and web pages name their folder (`play: { instruments }`). The sounds package is an optional peer dependency. - On pages without tabs, a sample player plays chords, scales, strums and progressions without loading alphaTab (about 1 MB of script). A first guitar chord downloads about 115 KB. ### For apps - A pick layer turns a fretboard or a keyboard into something you answer on, for drills and quizzes ("find every G on string 5"): `pick: true` on `renderFretboard` or `renderKeyboard`, then `attachPick`. Every string at every fret, open strings too, and every piano key becomes a target. - A pick works by click or by keyboard (Tab, the arrows, Home and End, Space or Enter). The app gets the string, the fret, the note and the pitch, and marks the pick right or wrong on the drawing. With sound on, each pick plays its note, on guitar for a fretboard and on piano for a keyboard. The layer is off by default, so the blocks in your notes don't change. - Screen readers hear each target by its place ("String 5, fret 3"), never by its note, so a drill doesn't give the answer away. On touch screens, a tap stays on the drawing, and keyboards with a pick layer have black keys at least 24 px wide. - The [[Music Practice plugin for Obsidian|Music Practice plugin]] uses the pick layer for its note, chord and scale drills, and to enter a chord by clicking its frets or keys. - `toSvgString(el)` gives a standalone SVG of a diagram or a block, every style inlined, and `toPng(el)` a PNG, both with `theme: 'light' | 'dark'`. The playground has Download SVG and Download PNG. - Easier charts from code: `simplifyChord(symbol)` gives the plainer chords of a chord's family that are easier to play, the easiest first, and `easierChord` the first of them. `bestCapo(chords)` gives the capo that turns the most of a song's chords into open shapes, with the shapes to play, and `capoChoices` ranks every fret. `easierChart(song)` gives what `{simplify}` and `{capo: auto}` change in a song, without drawing it. `chartChords` and `renderChart` take a `simplify` option that comes before the song's own line. - Options: `language`, `volume` (on `renderTab` too), a default naming (it changes how names show, never how a block is read), `rootMark`, `copy: false` and the play option `guitar` (a guitar's name, or a function read at each play, so a guitar chosen in an app's settings is heard at the next Play). On Obsidian Publish, they go in `window.musicNotationOptions`. `volumeChanged()` applies a new volume at once, and a `PlayHandle` has `setVolume`. - `music-notation check` (through npx or bunx) checks the blocks of your Markdown files from the command line, on Windows too. **Pick layer**: a fretboard drill in Music Practice, "Find C on string 5". The wrong pick on fret 2 is crossed, and the right fret (3) is checked. ![[Music Notation library - pick layer.png]] ## Examples These are live: plain-text blocks in this note, drawn on this site by the library itself. Click a diagram to hear it, or press play on the bar under a block. The picture button at the end of each bar copies the diagram as an image. A guitar chord: the name, the frets, the fingers. ```chord A x02220 x01230 ``` Am7 with its formula written under it, and its root (the open A string) drawn as a square ring, which you can spot without telling the colors apart. ```chord Am7 caption: formula root-mark: shape ``` D dorian on a keyboard, with the degrees (the 6 is what makes it dorian). ```keyboard D dorian labels: degrees ``` The first A minor pentatonic box, with the intervals. ```fretboard scale: A minor pentatonic frets: 5-8 labels: intervals ``` A ii-V-I on piano with rootless voicings, the way jazz pianists play it: each chord moves as little as it can. ```progression ii7 V7 Imaj7 key: C instrument: piano voicing: rootless ``` Which scale fits a song's chords? For Dm, C and G, it's D dorian. ```fretboard scales-for: Dm C G frets: 0-5 ``` A strumming pattern with accents, ghost strums and muted chucks. ```strum D> (U) X U D> U X U chord: Am tempo: 100 title: Backbeat chuck ``` A chord chart moved up two half steps, with its chord diagrams (A, A7 and D). ```chords {title: Amazing Grace} {transpose: 2} {diagrams} [G]Amazing [G7]grace, how [C]sweet the [G]sound ``` The guide has every option and a gallery: https://dsebastien.github.io/music-notation/ The playground has examples for every block (tabs and scores too) and a Surprise me button, a play bar on every diagram, the note names in letters, solfège or German, Copy link to share a block, Copy as Markdown to paste it into a note, and Download SVG and Download PNG to keep it as an image: https://dsebastien.github.io/music-notation/playground.html The Sounds page plays the same music with each sound engine, side by side, so you can hear the difference before you pick one: https://dsebastien.github.io/music-notation/sounds.html ## Where it runs - In Obsidian, through the [[Music Practice plugin for Obsidian|Music Practice plugin]]. It draws the blocks in reading view and live preview, and new chord notes get their voicing and diagram. The blocks follow Obsidian's language there (French or English). - 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 blocks follow the page's language, and `language: 'fr'` or `'en'` in `window.musicNotationOptions` forces one. The same options name the folder of instrument sounds (`play: { instruments }`) and the guitar of the site (`play: { guitar }`). 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. The guide's Websites and apps page shows both: https://dsebastien.github.io/music-notation/websites-and-apps.html ## 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. The instrument sounds live in a separate package, the [[Music Notation Sounds library]]: one small soundfont per instrument, cut from [[GeneralUser GS]], so a page loads only the instruments it plays. Before the first release, a separate AI agent reviewed the code adversarially (i.e., it looked for ways to break it). Every build imports its own output the way a real project would, as a check before each release. ## Status It's on npm, and the source code is public on GitHub. The changelog lists what changed in each release: https://github.com/dsebastien/music-notation/blob/main/CHANGELOG.md ### Next ideas Importing MIDI files (#84), bass support, 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 Notation Sounds library]] - [[Music Practice plugin for Obsidian]] - [[Guitar (MoC)]] - [[Piano (MoC)]] - [[Music Theory (MoC)]] - [[Accessibility (a11y)]] - [[Obsidian Publish]]