Blocks

A block is a fenced code block. Its language picks what’s drawn: chord, keyboard, fretboard, chords, or tab and score (tabs and scores). Inside, one key: value per line; most blocks also accept a short first line without a key. chord, keyboard and fretboard blocks can hold several diagrams, drawn vertically or horizontally.

Chord

A guitar diagram, or a piano chord.

```chord
A x02220 x01230
```

A x02220 x01230

The short form is chord frets fingers, the chord as a symbol or in words (A Major x02220 x01230). The same chord with keys:

```chord
symbol: A
frets: x02220
fingers: x01230
title: A (open)
```

symbol: A
frets: x02220
fingers: x01230
title: A (open)

Key	Meaning
symbol	Chord symbol (A, F#m7, B♭, C/G, C6/9) or name in words (A Major, F Sharp Minor 7, C Major over G). Its root notes are highlighted. Also the title, unless title is set. A symbol the library doesn’t know still works with frets, without root marks.
frets	One per string, lowest string first. x = muted, 0 = open. Above fret 9, separate them: x-10-12-12-11-10.
fingers	One per string: 1–4, T (thumb); 0 or x = none. The same finger on the same fret draws a barre.
voicing	With only a symbol, the n-th voicing from the built-in database (1 = the most common).
position	The first fret shown; at most the lowest fretted note. Computed when absent.
tuning	For other tunings or instruments: Drop D, DADGAD, E2 A2 D3 G3, ukulele…
instrument	piano draws a keyboard.
pitches	Piano: A3 C#4 E4, or A C# E (stacked upwards from middle C).
fingering	Piano: one finger per key, low to high: 5-3-1. Shown on the keys (labels: notes shows note names instead).
title	The title shown above.
name	Also the title; when it reads as a chord (name: A, name: A Major), its root notes are highlighted too.
orientation	vertical (default for guitar) or horizontal; piano chords are horizontal by default. See orientation.
hand	left mirrors the diagram for left-handed players.
labels	Guitar: what the dots say: fingers (default), intervals (R, 3, 5, as triad charts show them), notes or none.
anchors, guides	Guitar: strings (1 = the highest) whose finger stays on its fret (a ring) or slides along the string (a dashed ring), as chord transitions mark them.

Without a symbol or name, the chord is recognized from its frets (in the block’s tuning) or pitches, and titled with what it found: frets: x02220 draws an A diagram. Common chords come first, so E4 G4 C5 reads as C/E. A chord the library doesn’t recognize says what to write instead.

A piano chord from its symbol is voiced in root position from middle C; a slash chord’s bass goes an octave below.

```chord
C/G
instrument: piano
fingering: 5-1-2-4
```

C/G
instrument: piano
fingering: 5-1-2-4

All the ways to play a chord

voicings: draws every playable way to play a guitar chord, easiest first, in a row. The library finds them from the chord’s notes, so it works for any chord, any tuning and up to 8 strings.

```chord
A Major
voicings: 6
```

A Major
voicings: 6

Narrow them down: C between frets 3 and 9, without open strings, four columns:

```chord
C
voicings: all
area: 3-9
open: no
columns: 4
```

C
voicings: all
area: 3-9
open: no
columns: 4

Key	Meaning
voicings	all (at most 32), or how many: the easiest first.
area	The frets the fretted notes stay within: 5-9 (0-3 starts at the nut), or open (frets 1–4).
root-string	The string the bass note is on, counted the way guitarists do: 1 is the highest string, 6 the lowest. 6 gives E-shape chords.
strings	The strings that may sound: 1-3 (the three highest), 2-4, or a list (1 2 3; strings apart, like 1 2 4, need gaps).
inversion	The chord’s note in the bass: 0 (root, the default), 1, 2, 3 (usually the third, fifth, seventh), or any.
stretch	yes: the hand may cover five frets instead of four.
open	no: no open strings.
gaps	yes: muted strings may sit between sounding ones (jazz shells).

tuning, orientation, hand, labels, columns and title work as in any row (title replaces the chord in each diagram’s title). frets, fingers, voicing, position and piano keys can’t be used with voicings:.

On a re-entrant tuning (a ukulele’s high G string), any chord note may be lowest unless inversion says otherwise, so the usual shapes (F 2010, G 0232) come first. On 7 or 8 strings, use one of gaps, stretch and a wide area at a time, and inversion: any with six strings or fewer: there are many more combinations to go through.

Each voicing must sound the root, the third (or the sus note), the seventh or sixth, altered notes and the highest extension; the perfect fifth and lower extensions may be left out. A slash chord keeps its bass lowest. Fingers are worked out: any finger can hold a note or barre a few strings on one fret, only the index can lie across strings fretted higher (a full barre), the finger numbers go up with the frets, and at most four fingers in all; the easiest way wins (a small index barre over the top strings, like F xx3211, counts as easy). Muted strings between sounding ones are left out unless gaps: yes.

Easiest first means: the open chords guitarists learn first (C, A, G, E, D, Am, Em, Dm, their sevenths, sus and add9 shapes), then fewer fingers, a smaller span, no full barre, reach or awkward fingering, the usual shapes (E- and A-shape barres, the CAGED shapes), all strings sounding (a muted high string costs more than a muted low one), no open string ringing inside a shape up the neck, lower on the neck. Each diagram is titled with the chord and its shape when it has a usual one.

voicing: 3 (singular) still picks the third voicing of the built-in database (see Examples).

Triads on string sets

Triads on three strings next to each other, in their three inversions, are how guitarists learn the neck. triads: draws a chord’s triads on a string set, up the neck, with R, 3 and 5 in the dots:

```chord
G
triads: 1-3
```

G
triads: 1-3

inversion: 0 (root position), 1 or 2 keeps one. With key:, the key’s seven triads in one inversion, moving up the neck, titled with their numerals:

```chord
key: C major
triads: 2-4
inversion: 1
```

key: C major
triads: 2-4
inversion: 1

Key	Meaning
triads	The string set: 1-3, 2-4, 3-5 or 4-6 (1 = the highest string).
inversion	0 (root position), 1, 2; all of them by default (one, root position by default, with a key).
key	G major, E minor: the key’s seven triads instead of one chord’s.
labels	intervals by default here; fingers or notes instead.

Triads need a three-note chord (major, minor, diminished, augmented, sus). The shapes stay within four frets. On a fretboard, strings: 1-3 shows a chord’s notes on those strings only.

Chord transitions

Changing chords cleanly is mostly about which voicing you pick and which fingers can stay down. from: and to: draw the chord you hold, then the next chord’s voicings the hand reaches most easily. Fingers that stay on their fret have a ring; fingers that slide along their string have a dashed ring.

```chord
from: C x32010
to: Am
```

from: C x32010
to: Am

count: 5 shows more. Without frets (from: C), the chord’s easiest voicing is held. For a whole progression, progression: picks the voicings that make it easiest overall, the shapes and the moves together:

```chord
progression: G D Em C
columns: 4
```

progression: G D Em C
columns: 4

Chords are separated by spaces, or by commas or bars when they’re written in words (progression: C, A Minor, F). The library also says what to do in plain words (transition in the API): “Keep your middle finger on the D string’s 2nd fret”, “Slide your ring finger along the B string from fret 2 to 3”.

Keyboard

A piano keyboard with the notes of a scale, a chord or a list.

```keyboard
D dorian
labels: degrees
```

D dorian
labels: degrees

Key	Meaning
scale	C major, A minor pentatonic, D dorian, E harmonic minor…
chord	Cmaj7, G7, F#m7b5…
notes	C E G (every octave), or C4 E4 G4 (those keys only).
range	Keys shown: C3-B4. Two octaves from middle C by default; whole octaves around exact notes.
labels	notes (default), degrees (a chord’s 1 3 5 7, a scale’s 1–7), intervals (R, b3, 5…), none.
title	The title shown above.
orientation	horizontal (default) or vertical: low notes at the bottom.
highlight, compare	See scales and modes.
fingering	For a scale: one finger per note of one octave from the root, 1 2 3 1 2 3 4 5.
modes	modes: C major: every mode of the scale, side by side.

The short first line is tried as a scale, then as notes with octaves (C4 is that key), then as a chord, then as a list of notes. The root is drawn in a second color.

Fretboard

A guitar (or any fretted instrument) neck with the notes of a scale, a chord or a list.

```fretboard
scale: A minor pentatonic
frets: 5-8
labels: intervals
```

scale: A minor pentatonic
frets: 5-8
labels: intervals

Key	Meaning
scale, chord, notes	As for keyboards.
frets	Frets shown: 5-8. 0-12 by default; from 0, open strings are shown left of the nut.
strings	Only the notes on these strings (1 = the highest): 1-3 shows triads on the top strings.
tuning	standard (default), Drop D, DADGAD, open G, open D, open E, half step down, bass, ukulele, or notes: DADGAD, E1 A1 D2 G2.
labels	notes (default), degrees, intervals, none.
title	The title shown above.
orientation	horizontal (default, the high string on top, as in tabs) or vertical (the nut on top, as a chord diagram).
hand	left mirrors the neck for left-handed players.
position, shape	One position of a scale instead of every note. See scales and modes.
highlight, compare, modes, positions	See scales and modes.

Scales and modes

Scales are written as a root and a name: A minor pentatonic, D dorian, E phrygian dominant. The usual names work as written too: Natural minor, Major pentatonic, Blues, Whole tone, in any case. A name without a root says so (“Add a root note: C lydian”).

Characteristic notes. Modes and blues scales mark the notes that set them apart in a third color: lydian #4, dorian 6, mixolydian b7, phrygian b2, locrian b5, aeolian b6, the blues b5. highlight: none turns it off, highlight: characteristic turns it on for any scale (harmonic minor 7, melodic minor 6 and 7…), and highlight: b5 7 marks the intervals you list.

```keyboard
C lydian
range: C4-B4
compare: major
```

C lydian
range: C4-B4
compare: major

Compare. compare: major (or compare: C major) outlines the notes that differ from the other scale and draws its notes missing here faint: above, C lydian against C major.

Positions. On a fretboard, position: draws one place on the neck instead of every note, and the frets shown follow it:

• 5-note scales: the five boxes, position: 1 to 5 (box 1 starts on the root on the low string).
• 7-note scales: the five CAGED positions, by number (position: 1 is the E shape) or by shape: shape: E (the root on the low string), then up the neck D, C, A, G.
• Every position is drawn in the lowest octave where all its notes fit on the neck (box 5 of A minor pentatonic at frets 2–5; E major box 1 at 11–14).
• shape: 3nps with position: 1 to 7: three notes per string, from that degree. Scales with no pentatonic inside (locrian, harmonic minor…) use it for their CAGED positions too.
• positions: all (or a list, positions: 1 3) draws the positions side by side; with shape: 3nps, the 3NPS ones.

```fretboard
labels: intervals
---
A minor pentatonic
position: 1
---
C major
shape: E
---
G major
shape: 3nps
```

labels: intervals
---
A minor pentatonic
position: 1
---
C major
shape: E
---
G major
shape: 3nps

All the modes of a key. modes: C major draws C ionian, D dorian, E phrygian… side by side, each with its characteristic note. Other keys in the block apply to every mode.

```keyboard
modes: C major
range: C4-B4
columns: 4
```

modes: C major
range: C4-B4
columns: 4

Fingering (keyboards): fingering: 1 2 3 1 2 3 4 5 puts one finger on each note of one octave, from the root.

Known scales: altered, augmented, bebop (major, minor, locrian), blues (minor, major, composite), chromatic, diminished, dorian (and #4, b2), double harmonic major, egyptian, enigmatic, flamenco, harmonic major, harmonic minor, hirajoshi, hungarian major and minor, in-sen, iwato, kumoijoshi, locrian (and #2, 6, major), lydian (and #9, augmented, dominant, minor), major, major pentatonic, melodic minor, minor, minor pentatonic, mixolydian (and b6), neapolitan major, oriental, pelog, persian, phrygian, phrygian dominant, prometheus, scriabin, spanish heptatonic, ultralocrian, whole tone, and more: every scale tonal knows.

From a note’s properties

An empty chord, fretboard or keyboard block can draw what the note’s properties say, so a note doesn’t repeat its frets or its scale in the body. Apps pass the note’s properties to the library (Music Practice does); on Obsidian Publish, see Publish. A block with content always draws its content.

Properties	Draws
chord_symbol, frets, fingers, position	A guitar chord (position from 1; 0 or empty: computed).
chord_symbol, pitches, fingering	A piano chord, when a tag has a piano segment (type/music/piano/chord).
scale_root, scale_type, shape	A scale on a fretboard; shape Box 2, CAGED E or 3NPS picks a position.
scale_root, scale_type, fingering_rh	A scale on a keyboard, with its fingering.

Several diagrams

Separate diagrams with a line of three dashes (---) to draw them side by side: a song’s chords, a progression, the positions of a scale. The row wraps on narrow screens.

```chord
G 320003 210003
---
C x32010 x32010
---
D xx0232 xx0132
---
Em 022000 023000
```

G 320003 210003
---
C x32010 x32010
---
D xx0232 xx0132
---
Em 022000 023000

Settings for every diagram go in a first part, before the first ---. It holds only shared keys: orientation, hand and labels for every block; instrument, tuning and range for chords; range for keyboards; tuning and frets for fretboards. A diagram’s own keys win over them (an empty key, like labels: alone, keeps the shared value). columns draws a grid with at most that many columns (1 to 12); on narrow screens it wraps rather than shrinking the diagrams. With columns, any other key in that part is refused by name.

```fretboard
frets: 5-8
labels: intervals
columns: 2
---
A minor pentatonic
---
title: A blues
scale: A blues
```

frets: 5-8
labels: intervals
columns: 2
---
A minor pentatonic
---
title: A blues
scale: A blues

A mistake in one diagram is shown in its place; the others still draw. A block holds at most 32 diagrams, each at most 12 strings or 88 keys. A block with only --- lines draws nothing, like an empty one. Chord charts (chords) don’t split: --- is text there.

Orientation and left-handed diagrams

orientation: horizontal turns a guitar chord sideways: the strings run across with the high string on top, as in tabs, and the nut is on the left.

```chord
orientation: horizontal
---
A x02220 x01230
---
Bm x24432 x13421
```

orientation: horizontal
---
A x02220 x01230
---
Bm x24432 x13421

orientation: vertical stands a fretboard up, with the nut on top and the low string on the left, like a chord diagram, and draws a keyboard with its low notes at the bottom.

```fretboard
A minor pentatonic
frets: 0-5
orientation: vertical
```

A minor pentatonic
frets: 0-5
orientation: vertical

hand: left mirrors guitar chords and fretboards for left-handed players: the low string on the right, the nut on the right. Keyboards are the same for both hands.

```chord
hand: left
---
A x02220 x01230
---
E 022100 023100
```

hand: left
---
A x02220 x01230
---
E 022100 023100

Text always stays upright. Apps using the library can set the default orientation per block and the hand (Music Practice has settings for them); on Obsidian Publish, see Publish.

Hear the diagrams

Apps that turn playback on (Music Practice does, and Obsidian Publish pages through publish.js) add a small bar at the bottom of chord, keyboard and fretboard diagrams, shown when the mouse is over them (a tap on touch screens):

• Play / stop: a chord strums from the low string up, then rings; a scale goes up and back down.
• Loop.
• Speed, when several notes play: the tempo of a scale, or the time between two strings of a strum.
• Volume, and sound: guitar or piano.

A click on a dot or a key plays that note. On web pages the sound is a small synthesizer computed in the browser (nothing to download); Music Practice plays a soundfont of recorded instruments.

Tabs and scores

tab and score blocks are written in alphaTex, drawn and played by alphaTab: tablature, standard notation, both, or a piano grand staff.

```tab
\title "Riff"
\tempo 100
.
:8 0.6 3.6 5.6 0.6 3.6 6.6 5.6 r | 0.6 3.6 5.6 3.6 0.6 r r r
```

\title "Riff"
\tempo 100
.
:8 0.6 3.6 5.6 0.6 3.6 6.6 5.6 r | 0.6 3.6 5.6 3.6 0.6 r r r

```score
staves: both
:4 (0.1 1.2 0.3 2.4 3.5).2 (3.1 0.2 0.3 0.4 2.5 3.6).2
```

staves: both
:4 (0.1 1.2 0.3 2.4 3.5).2 (3.1 0.2 0.3 0.4 2.5 3.6).2

Key	Meaning
staves	tab, score or both. tab blocks show tablature and score blocks notation by default.
file	A Guitar Pro (3–8), MusicXML or Capella file instead of alphaTex: file: [[Song.gp]] (the app finds it).
tracks	The tracks to show, from 1: tracks: 1 3.

These keys go on the first lines; the alphaTex follows. Under the music, a player bar (on hover): play / pause, stop, loop, metronome, count-in, speed (25–150%), volume and the time. A mistake in the alphaTex shows its line and column.

On web pages, the tab bundle loads alphaTab, its music font and its soundfont from jsDelivr, only on pages that have tab or score blocks.

Chords (ChordPro)

A chord chart: chords above the lyrics, in ChordPro format.

```chords
{title: Example}
{artist: Someone}
{key: G}
{capo: 2}

[G]Hello [D/F#]little [Em]world

{start_of_chorus}
[C]La la [G]la
{end_of_chorus}
```

{title: Example}
{artist: Someone}
{key: G}
{capo: 2}

[G]Hello [D/F#]little [Em]world

{start_of_chorus}
[C]La la [G]la
{end_of_chorus}

Supported:

• Song details: {title} ({t}), {subtitle} ({st}), {artist}, {key}, {capo}, {tempo}, {time}.
• Sections: verse, chorus, bridge ({start_of_verse}, {sov}, {soc}, {sob}…), with an optional label ({start_of_verse: Verse 2}); tab and grid sections are shown as written.
• Comments: {comment} ({c}), and lines starting with # are skipped.
• {transpose: 2}: chords and key move by that many semitones, spelled for the new key.
• Long lyric lines wrap on narrow screens.

Other directives are ignored.