Guitar Markdown Studio

# Guitar Markdown Studio (gms.exostic.com)

> Guitar Markdown Studio renders guitar lessons written in Markdown: tablatures, chord diagrams,
> fretboard scale diagrams, chord grids, lyrics with chords, strumming patterns, key charts,
> circle of fifths, tuner, and audio playback. The Markdown text is the only source of truth.
> This file is written for AI agents: read it, then write a complete `.md` lesson and hand the
> user a link that opens it in the editor.

The site at https://gms.exostic.com/ is a JavaScript application (two panes: Markdown on the
left, rendered lesson on the right, plus Web / Book / Poster view modes and print to PDF).
Fetching the HTML page tells you nothing about the syntax; everything you need is in this file.

## How to deliver a lesson to a user

Write the whole lesson as one Markdown document, then give the user ONE of these links:

1. `https://gms.exostic.com/?src=<URL of the .md file>` — the editor downloads the file.
   The URL must serve plain text with CORS allowed: a raw GitHub file
   (`https://raw.githubusercontent.com/...`), a GitHub Gist raw URL, or any public static host.
   A `https://github.com/<owner>/<repo>/blob/...` URL is accepted and converted automatically.
   Best option when you can create a file somewhere public: short link, editable later.
2. `https://gms.exostic.com/?b64=<base64 of the UTF-8 Markdown>` — no hosting needed.
   Standard or URL-safe base64 both work. Percent-encode `+`, `/` and `=` if you use standard
   base64 (or use URL-safe base64: `-` and `_`, padding optional). Links get long
   (roughly 1.4 × the document size) but work for lessons of a few kilobytes. Put the parameters
   after `#` rather than `?` for anything long: the fragment never reaches the server, so it escapes
   GitHub Pages' 8 KB query limit (HTTP 414 beyond); the app reads both forms.
3. `https://gms.exostic.com/#doc=<lz-string compressToEncodedURIComponent(markdown)>` (or `?doc=`) —
   what the app's own "Copier un lien de partage" produces (behind a short alias — the app's own
   Cloud Run shortener from services/shortlink when configured, else TinyURL); shortest self-contained link, needs the `lz-string` library.

Optional extra parameters, combinable with any of the above:

- `mode=web` (default, interactive, audio playback), `mode=book` (A4 pages), `mode=poster`
  (landscape, fit to page).
- `?enc=<base64url>` is a password-protected document (AES-256-GCM over the lz-string bytes, key from
  PBKDF2-SHA-256; layout: version byte, 16-byte salt, 12-byte IV, ciphertext); the app asks for the
  password. Produced when "Copier un lien de partage" or "Envoyer par e-mail…" is answered with a
  password (both ask first: "Sans mot de passe" / "Protéger"); an agent should use `?src=`
  or `?b64=` instead.
- `?state={"ids":["<Drive file id>"],"action":"open"}` is what Google Drive's "Open with" menu sends;
  the app asks for a Google sign-in and reads that file (scopes drive.file + drive.install).
- `view=only` hides the Markdown editor and shows the rendered lesson only.
- `edit=hide` hides the "edit" button in view-only mode; `print=hide` hides the print buttons.

Example: `https://gms.exostic.com/?src=https://raw.githubusercontent.com/me/lessons/main/am-pentatonic.md&mode=web&view=only`

If you cannot produce a link, give the user the full Markdown in a code block and tell them to
paste it into the left pane at https://gms.exostic.com/ (or save it as `.md` and use "Ouvrir").

## Document structure

A lesson = optional YAML front matter + standard Markdown (headings, paragraphs, lists, bold,
blockquotes, links, images) + fenced code blocks with special languages listed below.
Anything that is not a special block is ordinary Markdown. The UI language is French but the
lesson content can be in any language.

### Front matter

```markdown
---
title: Amazing Grace
artist: Traditional
difficulty: Beginner
tempo: 70 BPM
time: 3/4
capo: 0
tuning: Standard
key: G
transpose: 0
sound: acoustic
sounding: false
logo: https://example.com/logo.png
logo-position: left
qr: false
---
```

- `title`, `artist`, `difficulty`, `tempo`, `time`, `capo`, `tuning` are shown as badges under
  the title. Only `title` is really needed; add the others when relevant.
- `tempo`: `<number> BPM`. Drives audio playback (quarter notes) and the click-to-start metronome.
- `time`: time signature, e.g. `4/4`, `3/4`, `6/8`.
- `key`: song key (`G`, `Em`, `F# minor`, `Bb major`, French names like `Sol majeur` also work).
  Used to spell transposed chord names correctly (flats vs sharps).
- `transpose`: `+2`, `-3`… shifts every chord NAME in `chords`, `grid`, `song` blocks and tab
  annotations. Scale diagrams, key charts and the circle of fifths are never rewritten.
- `capo` + `sounding: true`: shows the sounding chord in parentheses, e.g. `Am (Cm)` with capo 3.
- `tuning`: `Standard`, `Drop D`, `DADGAD`, `Open G`, `Open D`, `Eb standard`, or an explicit
  low-to-high list `D A D G B e`. Used by scale diagrams, the tuner and audio playback.
- `samples`: `off` to play with the synthesized string instead of the sampled guitars (a sampled
  steel-string acoustic plus a General MIDI SoundFont, loaded in the background). `soundfont`: URL
  of another uncompressed `.sf2` bank played first; the app's banks fill in the programs it lacks.
- `sound`: instrument used by audio playback — `acoustic` (default), `electric` (clean electric
  guitar) or `distortion` (overdriven electric guitar). French words work too (`électrique`,
  `saturé`). Only affects the sound, never the notation.
- `logo`: URL of an image shown in the header (none by default). `logo-position: left` or centred.
- `qr: false` hides the header QR code (shown by default in Book/Poster modes).

### Tablature — ```tab

````markdown
```tab
    Em              C
e|------0-------|------0-------|
B|----0---0-----|----1---1-----|
G|--0-------0---|--0-------0---|
D|--------------|2-------------|
A|2-------------|3-------------|
E|0-------------|--------------|
```
````

- Six lines, high e to low E, each starting with the string name and `|`. Keep all six lines the
  same length and the bar lines `|` in the same columns.
- Notes in the same column on different strings are played together (chords).
  Each `|`-separated section is one bar.
- An optional line ABOVE the six strings holds chord names / annotations aligned to the column
  where they apply (like `Em` and `C` above).
- Techniques: `5h7` hammer-on, `7p5` pull-off, `5t12` tap, `5/7` slide up, `7\5` slide down,
  `8b10` bend to a written note, `8b` full bend, `8br` bend and release, `10r8` release onto the
  next note, `7~` vibrato, `x` muted note, `(5)` ghost note, `<12>` natural harmonic.
  Playback renders them (pitch glides, legato attacks, vibrato, bell-like harmonics).
- `grid: 8` on its own line inside the block forces the rhythm grid (cells per bar). Blocks are
  engraved by alphaTab from an alphaTex translation; rhythm comes from column spacing, so write
  bars with a character count that is a multiple of the intended subdivision (16 chars = 16ths).
- `tempo: 120`, `time: 3/4`, `tuning: Drop D`, `capo: 2` on their own lines inside the block give it
  its own playback and engraving settings (a song imported into a document with other settings).
- `staff: tab` / `staff: partition` / `staff: tab et partition` on its own line inside the block
  (or as a front matter key) chooses what is drawn: tablature, staff notation, or both.
- `sound: clean` (or `acoustic`, `distortion`) on its own line inside the block overrides the
  front matter `sound` for this block only — e.g. a clean intro in a distorted song.
- Rhythm is not quantised: note duration is inferred from the number of events in the bar.
  Space notes evenly and keep the same number of events per bar when possible.

### Standard notation — ```partition

A block may hold several groups of six string lines (each with its own chord line above): they
are read as consecutive bars, so a long song can be written four bars per line.
Same ASCII syntax as `tab`, rendered as a music staff instead of a tablature. Both are engraved by alphaTab.
Always assumes standard tuning.

### Chord diagrams — ```chords

````markdown
```chords
Em 022000
C  x32010
G  320003
D  xx0232
F  133211
```
````

One chord per line: name, spaces, then six characters from low E to high e.
`x` = muted string, `0` = open string, a digit = fret. Frets 10 and above are not supported as
single characters, so keep chord shapes below the 10th fret or describe them in a `tab` block.

### Fretboard scale diagram — ```scale

Named scale (notes are computed, root highlighted, legend added):

````markdown
```scale
scale: A minor pentatonic
position: 1
labels: notes
```
````

Arpeggio (chord tones coloured by degree: root, 3rd, 5th, 7th):

````markdown
```scale
arpeggio: Am7
frets: 3-8
```
````

Manual diagram (one line per string, frets separated by `|`):

````markdown
```scale
frets: 0-12
e: 0|3|[5,A]|8|10|12
B: 1|3|[5]|8|10
G: 0|2|[5]|7|9|12
```
````

- `scale: <root> <name>`. Names (English or French): `major`, `minor`, `minor pentatonic`,
  `major pentatonic`, `blues`, `major blues`, `harmonic minor`, `melodic minor`, `dorian`,
  `phrygian`, `lydian`, `mixolydian`, `locrian`, `chromatic`, `whole tone`.
- `arpeggio: <chord>` (e.g. `Am7`, `G`, `Cmaj7`, `E7`). Exclusive with `scale:`.
- `position: N`: 5-fret window starting on the N-th scale note found on the low string
  (position 1 starts on the lowest root). `frets: min-max` takes priority when both are present.
- `labels: notes | degrees | none` (default `notes` for a scale, `degrees` for an arpeggio).
- `tuning:` inside the block overrides the front matter tuning.
- Manual string lines: `5` plain dot, `5,A` dot with label, `[5]` or `[5,A]` highlighted dot.
  They can be mixed with `scale:` to override generated dots.

### Key chart — ```key

````markdown
```key G
```
````

````markdown
```key
key: F# minor
sevenths: true
```
````

Table of diatonic chords (degree, roman numeral, chord, notes, function), relative key,
key signature, and for minor keys the harmonic-minor dominant. `sevenths: true` adds 7th chords.

### Chord grid — ```grid

````markdown
```grid
key: G
||: I | V | vi | IV :|| x2
| ii7 | V7 | I | I |
```
````

- One bar per `|` cell. `||:` … `:||` are repeat signs, `xN` after the closing repeat = play N times.
- With a `key:` line, roman numerals (`I ii iii IV V vi vii°`, `bVII`, `V7`, `IVmaj7`…) are
  resolved to chord names, with the numeral shown small underneath. Plain chord names and
  numerals can be mixed. In a minor key the numerals refer to the natural minor scale
  (so in `Am`, `VII` is G and `VI` is F; `bVII` would give Gb). Lowercase = minor chord,
  `°`/`dim`, `ø`, `+`/`aug` set the quality, suffixes like `7`, `maj7`, `sus4` are kept.
- `G/B` = slash chord (bass note), shown split diagonally. Without a `key:` line, `/` keeps
  that meaning and cells are plain chord names: `| Em | C | G/B | D |`.

### Lyrics with chords — ```song

Inline chords right before the syllable:

````markdown
```song
[Em]Amazing [C]grace, how [G]sweet the [D]sound
That [Em]saved a [C]wretch like [G]me
```
````

Or chords on their own line, aligned in columns above the lyrics (both syntaxes can be mixed):

````markdown
```song
Bm                         F#7
On a dark desert highway   Cool wind in my hair
```
````

An empty line separates verses. A line containing only `---` starts a new column.

### Strumming pattern — ```rhythm

````markdown
```rhythm
B H | B h | H B | h B
```
````

Each `|`-separated group is one beat. `B` = down stroke, `H` = up stroke, lowercase = ghost
(muted) stroke, `-` = rest. Playable in a loop with the metronome in Web mode.

### Circle of fifths — ```circle

````markdown
```circle D
```
````

Major keys outside, relative minors inside. The given key and its neighbours are highlighted.
Without an argument the circle is neutral.

### Tuner — ```tuner

````markdown
```tuner
tuning: DADGAD
```
````

Web mode: six buttons that play each open string, and a "🎤 Accorder au micro" button that
listens to the microphone and shows the detected note, the offset in cents on a needle, and the
nearest string of the tuning with tune-up/down advice. Print modes: a string / note / frequency table.
Without `tuning:` the front matter tuning is used.

### Layout blocks (empty blocks, each alone on its line)

- ```` ```pagebreak ``` ```` page break.
- ```` ```columnbreak ``` ```` column break inside a columns section.
- ```` ```landscapebreak ``` ```` page break in Poster (landscape) mode. The Poster is composed in the
  Markdown: `landscapebreak` starts an A4 landscape page, `columnbreak` a column in the current
  page, and each column is shrunk to the page height (no marker: one page, one column). A page
  still overflowing at the smallest scale is reported in a toast. Book mode is unaffected.
- ```` ```columns ``` ```` … ```` ```column ``` ```` … ```` ```endcolumns ``` ```` multi-column
  section; `column` separates columns, `endcolumns` closes the section.
- ```` ```zoom 0.8 ``` ```` … ```` ```endzoom ``` ```` scales the content in between
  (factor 0.1 to 3, default 0.8). Handy to fit several chord diagrams on one row.

### Media

Standard Markdown images and links work. In Web mode a YouTube link or a link to an audio
file (`.mp3`, `.wav`, `.ogg`…) becomes an embedded player; in Book/Poster modes every link is
printed as a QR code.

### Google Drive

The site is an installable PWA (web manifest + service worker, offline-capable; Chrome shows an install icon,
"Fichier ▾ › Installer l'application" does the same). The "Fichier ▾" menu opens a document from Google Drive, saves it back to the same file or saves
it under another name; "Partager ▾" shares the Drive file with another Google account (reader or writer)
or opens the mail client (mailto, new tab) on a ready-made message with a short alias of the share link
(TinyURL, no key; full link when shortening fails and it fits, clipboard + "paste it" beyond that). Client-side OAuth only with the `drive.file` scope (the app sees only the
files it created or saved), the public OAuth client id, no API key or secret; nothing to write in
the Markdown.

### Importing Guitar Pro

The Import button also takes a Guitar Pro file (.gp3/.gp4/.gp5/.gpx/.gp): alphaTab parses it and
the app appends a new section (a heading with the song title, a note with its settings, then one
`tab` block per six-string track, bars wrapped by width (about 100 characters, at most four bars per line), with `staff: tab et partition` and its own `tempo:`, `time:`,
`tuning:`, `capo:`, `sound:` lines) at the end of the current document; an empty editor gets a
whole document with front matter instead. The "Guitar Pro" entry of the "+" insert menu inserts
the same blocks at the cursor. Rhythm is encoded in the column spacing, techniques in the ASCII
notation. Bass/percussion tracks, meter changes and secondary voices are dropped and reported;
with several usable tracks, a dialog asks which ones to import.

### Audio playback (Web mode)

A "▶ Écouter" button appears above `tab`, `partition`, `chords`, `grid` and `rhythm` blocks.
Tempo comes from `tempo`, meter from `time`, pitch from `tuning` and `capo`. Nothing is needed
in the Markdown to enable it. While a `tab`/`partition` block plays, the note or chord being
played turns pink on the engraving, the current bar is framed and a vertical cursor slides from one note to the next. Clicking a note plays it alone, parks a cursor there and selects that fret in the editor; while a
block plays the preview follows the current note (the editor does not move), and Space pauses/resumes (or restarts the last block);
the play button then starts from that cursor until playback reaches the end of the block. A speed selector next to each button (25/50/65/80/100 %) slows
that block down for practice; it is a reader-side setting, not something to write in the file.

## Writing good lessons

- Start with front matter (`title` at least, `tempo`, `time`, `key`, `tuning` when known).
- Use `##` headings to structure: goal, chords, technique, main riff / verse, exercises, tips.
- Put chord shapes in a `chords` block once, then use `grid` and `song` blocks for the form.
- For a song: `chords` → `rhythm` → `grid` (structure with repeats) → `song` (lyrics) →
  `tab` for the riff/intro/solo. Keep tab bars consistent and small (2 to 4 bars per block).
- For theory: `key` chart + `grid` with roman numerals + `scale` (named scale, several
  `position:` values) + `circle`. Explain in prose between the blocks.
- Do not put chord names inside `chords` diagrams above the 9th fret, do not mix `scale:` and
  `arpeggio:` in one block, do not forget `key:` when a grid uses roman numerals.
- Check every `tab` block has exactly six string lines with aligned `|` characters.

## Minimal complete example

````markdown
---
title: A minor pentatonic, position 1
difficulty: Beginner
tempo: 80 BPM
time: 4/4
key: Am
tuning: Standard
---

> **Goal:** learn the first box of the minor pentatonic scale and use it over a simple progression.

## The scale

```scale
scale: A minor pentatonic
position: 1
labels: degrees
```

## Backing progression

```grid
key: Am
||: i | VII | VI | V7 :|| x4
```

## Lick

```tab
e|--------------5--8--|--5-----------------|
B|--------5--8--------|-----8--5-----------|
G|--5--7--------------|-----------7--5-----|
D|--------------------|---------------7~---|
A|--------------------|--------------------|
E|--------------------|--------------------|
```

## Chords used

```chords
Am x02210
G  320003
F  133211
E7 020100
```
````

## Links

- Editor: https://gms.exostic.com/
- Source and full French documentation: https://github.com/exostic/guitar-markdown-studio-desktop