🎵 Chord Grid for Obsidian

Transform simple text notation into beautiful, professional chord charts with rhythmic notation—right inside your Obsidian notes.

🇫🇷 Version française | 📖 Full Documentation | 🐛 Report Bug

For this entry

```chordgrid
show% measure-num count pick
4/4 
| Em[4 88 4 88] | D[%] | % | Em[%] 
| Em[4 88] G[4 88] | C[4 88] G[4 88] | G[4 88 4 88] | C[4 88] G[4 88]
|2/4 G[4 -4] | 4/4 C[4 88 4 88] | % | G[%] 
| G[4 88] Em[4 88] | 2/4 G[4 88] | 4/4 D[4 88 88 88] | Em[%]
```

Get this result

---

What is Chord Grid?

The problem: Musicians need to share chord charts with precise rhythm information, but traditional notation software is heavy, rigid, and doesn't integrate with note-taking workflows.

The solution: Chord Grid lets you write chord progressions in a simple, intuitive text format and instantly renders them as clean, scalable SVG diagrams. Perfect for composers, teachers, students, and anyone documenting music in Obsidian.

Built for musicians who want the precision of musical notation with the simplicity of plain text.

---

✨ Key Features

• 🎼 Professional notation - Automatic beaming, ties, tuplets, and dotted notes
• ⚡ Lightning fast - Write chords as text, see results instantly
• 🎯 Precise rhythm - Support for complex time signatures (4/4, 6/8, 5/8, 7/8, 12/8...)
• 🔄 Repeat notation - Repeat signs, volta brackets, measure symbols (%)
• ✨ Transposition tool - Quickly transpose chord grid by using transpose:+/-
• 📚 Pedagogical tools - Optional counting numbers for rhythm learning
• 🎸 Guitar/Bass friendly - Pick strokes (↓↑) and finger strum patterns (Thumb, Hand)
• 📐 Smart layout - Automatic collision detection and element positioning
• 📱 Responsive - Scales beautifully on any screen size

---

🚀 Quick Start

Installation

1. Open Obsidian → Settings → Community plugins
2. Disable Safe Mode
3. Click Browse and search for "Chord Grid"
4. Click Install, then Enable

Your First Chord Chart Without Rhythm

Create a code block with the chordgrid language:

```chordgrid
4/4 | C | G | Am | F / G |
```

That's it! You just created your first chord chart.

---

Want to add a repeat bar? No worries!

```chordgrid
4/4 ||: C | G | Am | F / G :||
```

---

Now let's say we need to change the last measure to a different chord while keeping the previous ones:

```chordgrid
4/4 ||: C | G | Am |.1-3 F / G :||.4 Bb |
```

---

Now let's add this awesome rhythm strum pattern so we don't forget it!

```chordgrid
4/4 ||: C[8.16 88 4 168.] | G | Am |.1-3 F / G :||.4 Bb |
```

---

OK, not bad, but I'd really like to fit all the chords on the same line! You can use measures-per-line: to specify the number of measures per line

```chordgrid
measures-per-line:5
4/4 ||: C[8.16 88 4 168.] | G | Am |.1-3 F / G :||.4 Bb |
```

---

Ah yes! That's better, but as a guitarist, I'd like to see the pick strokes. Can I? Sure! Just use the pick keyword

```chordgrid
measures-per-line:5 pick
4/4 ||: C[8.16 88 4 168.] | G | Am |.1-3 F / G :||.4 Bb |
```

---

Nice! Now I'd like to apply this rhythm pattern to the following measures. I could copy/paste the rhythm pattern... or?

```chordgrid
measures-per-line:5 pick
4/4 ||: C[8.16 88 4 168.] | G[%] | Am[%] |.1-3 F / G :||.4 Bb[8.16 88 4 168.] |
```

---

Wow! Amazing! But now there's too much information in each measure. Can I make this cleaner? Yes, use show%

```chordgrid
measures-per-line:5 pick show%
4/4 ||: C[8.16 88 4 168.] | G[%] | Am[%] |.1-3 F / G :||.4 Bb[8.16 88 4 168.] |
```

---

Finally, I think I'll play this rhythm with fingers instead of a pick. Can I? Sure! Use finger instead of pick

```chordgrid
measures-per-line:5 finger show%
4/4 ||: C[8.16 88 4 168.] | G[%] | Am[%] |.1-3 F / G :||.4 Bb[8.16 88 4 168.] |
```

🎓 Advanced Features

Need more power? ChordGrid supports advanced notation:

• 🔢 Pedagogical counting - Add count directive for rhythm learning numbers
• 🎯 Pick/Finger patterns - Detailed stroke notation (pick/finger directives)
• 🎭 Tuplets - Triplets {8 8 8}3:2, quintuplets {16 16 16 16 16}5:4
• 🔄 Volta brackets - First/second endings 1.|2.
• 📐 Custom layouts - Control measures per line with measures-per-line:N
• 🎨 Stem direction - stems-up (default) or stems-down
• 🔍 Zoom control - Resize output with zoom:50%, zoom:75%, zoom:150%, etc.
• 🎼 Complex meters - Support for 5/8, 7/8, 11/8, and custom time signatures
• 📏 Empty measures - Repeat symbols % for quick notation

---

📖 Full Syntax

Time Signature

4/4, 3/4, 6/8, 12/8, etc.

Chords

Standard notation (e.g., Am, C, Gmaj7, Dm, F#m, Bb7, C/E).

Rhythm in brackets (note values)

• 1 = Whole note (ronde)
• 2 = Half note (blanche)
• 4 = Quarter note (noire)
• 8 = Eighth note (croche)
• 16 = Sixteenth note (double-croche)
• 32 = Thirty-second note (triple-croche)
• 64 = Sixty-fourth note (quadruple-croche)

Rests (Silences)

Add a - prefix before any note value to create a rest:

• -1 = Whole rest (pause)
• -2 = Half rest (demi-pause)
• -4 = Quarter rest (soupir)
• -8 = Eighth rest (demi-soupir)
• -16 = Sixteenth rest (quart de soupir)
• -32 = Thirty-second rest
• -64 = Sixty-fourth rest

  ````chordgrid
  C[4 -4 88 _16-161616]
  ```

BE CAREFUL

:warning: If you want to keep beams grouped by beat, pay attention to space placement. For example::warning:

  ```chordgrid
  C[4 88_] G[_88 4]
  ```

is different from

  ```chordgrid
  C[4 88_]G[_88 4]
  ```

Ties (Liaisons)

• Use underscore _ to create ties between notes
• _ after a note = note starts a tie (sends/emits)
• _ before a note = note receives a tie (receives/ends)
• Examples:
  • [88_ 4] = tie between last eighth note and quarter note
  • [2 4_ 88_] = tie from quarter to two eighths
  • C[2 4_ 88_] | [_8] = tie across measure boundary (last eighth of measure 1 tied to first eighth of measure 2)
  • {8_ 8_ 8}3 = all three notes of triplet tied together
  • 4_{8 8 8}3 = quarter note tied to first note of triplet
  • {8 8 8_}3 4 = last note of triplet tied to following quarter
  • | 4_ | {_8 8 8}3 | = cross-measure tie into tuplet

Stem Direction

Control the direction of note stems following musical notation standards

• stems-up or stem-up (default) - You'll probably never need to use this.

• stems-down or stem-down - Stems point downward

• Example:

  ```chordgrid
  stems-down
  4/4 | C[88 4 4 4] | G[4 4 2] |
  ```

Pick Stroke Markers

Display alternating down/up pick strokes above or below notes for rhythmic subdivision practice. You can use either pick, picks, or picks-auto

  ```chordgrid
  pick
  4/4 | C[88 4 4 4] | G[4 4 2] |
  ```

Zoom Control

Resize the entire chord grid output to fit your needs. Perfect for presentations, printing, or adjusting size in your notes.

• Syntax: zoom:XX% where XX is any number from 1 to 500
• zoom:50% - Reduce to half size (great for compact layouts)
• zoom:75% - Slightly smaller (better readability in dense notes)
• zoom:100% - Default size (or omit zoom directive)
• zoom:150% - Larger display (better for presentations or printing)
• zoom:200% - Double size

  ```chordgrid
  zoom:75%
  4/4 | C[4 4 4 4] | G[4 4 4 4] | Am[4 4 4 4] | F[4 4 4 4] |
  ```

You can combine zoom with other directives:

  ```chordgrid
  zoom:60% pick measures-per-line:4
  4/4 ||: C[8.16 88 4 168.] | G[%] | Am[%] | F[%] :|| 
  ```

Repeat measures content

Display repeated measures content using notation shortcuts

• % - Shorthand to repeat the previous measure's rhythm with the same chords
• Chord[%] - Repeat previous rhythm with a new chord

  ```chordgrid
  4/4 | Am[88 4 88 4] | % | Dm[%] | G[%]
  ```

You can shorten the repeated content even more by using the show% directive. It displays a visual repeat symbol (%) instead of rendering the full rhythm

  ```chordgrid
  show%
  4/4 | Am[88 4 88 4] | % | Dm[%] | G[%]
  ```

Volta brackets

Create first/second endings for repeated sections

• |.1-3 : Start volta bracket for repetitions 1, 2, and 3
• |.4 : Start volta bracket for repetition 4 (or any single number)
• |.1,2,3 : Alternative syntax using commas
• |. : Explicitly mark the end of a volta bracket (optional)
• Volta brackets automatically span until:
  • The next volta starts (e.g., |.1-3 ... :||.4)
  • A repeat start marker ||: is encountered
  • An explicit end marker |. is placed
• Visual appearance:
  • Closed brackets (before :||): bracket with hooks on both ends
  • Open brackets (after :||): bracket with hook on left only (ending/coda)

First example: volta 1-3 covers one measure, volta 4 covers one measure

```chordgrid
4/4 ||: C[4 4 4 4] |.1-3 G[4 4 4 4] :||.4 Am[4 4 4 4] ||
```

Second example: volta 1-3 covers two measures before :||, volta 4 extends to Am using |. marker

```chordgrid
4/4 ||: C[4 88_ 4 4] | % |.1-3 G[%] | % :||.4 G[4 4 4 4] |. Am[16168 81616 4 88] ||
```

Strike, percussive notation

You can use the x just after a note value to get a X note head instead of the classic slash notation.

```chordgrid
4/4 | Em[4 8x]G[8_4 4x] | D[4 8x]C[8_4 4x] 
```

Forced Pick/Finger Strokes (v2.2+)

Override automatic patterns by adding suffixes to note values:

Pick Mode - Force directions

Add d (down) or u (up) after any note value:

```chordgrid
pick
4/4 | C[8d8u8d8u 8d8u8d8u] | G[8u8u8d8d 8u8u8d8d] |
```

Finger Mode - Force symbols

Add finger symbols after note values:

• d or td = thumb down

• u or tu = thumb up

• hd = hand down

• hu = hand up

• md/mu = French notation (main down/up)

• pd/pu = French notation (pouce down/up)

  ```chordgrid
  finger:fr
  4/4 | C[4pd 4mu 4pd 4mu] | G[8md8mu8md8mu 8md8mu8md8mu] |
  ```
  

  

Interoperability

New in v2.2: You can use finger notation suffixes in pick mode! They will be automatically normalized to simple d/u:

```chordgrid
pick
7/8| D |4/4 G / C | D[4u 4u 8md8mu 4u] |
```

In this example, 8md8mu will be interpreted as 8d8u in pick mode. This allows you to switch between pick and finger modes without rewriting your notation!

Advanced Syntax Examples

Pattern	Effect
88	Two beamed eighths (same beat)
8 8	Two separate eighths (space splits beams)
4.	Dotted quarter ( = quarter + eighth )
16.32	Beamlet direction adapts (analyzer path)
4_ 88_ | [_8]	Tie across measure boundary
C[8]G[8]	Cross‑segment beaming if no space (analyzer)
C[8] G[8]	Space blocks beam
%	Repeat previous measure's chord AND rhythm
Chord[%]	Repeat ONLY rhythm with NEW chord
show%	Display visual repeat symbol instead of full rhythm
picks	Enable pick stroke rendering with automatic or forced subdivision
{888}3	Eighth note triplet (fully beamed)
{8 8 8}3	Eighth note triplet (separate flags)
{161616 161616}6	Sextuplet with multi-level beaming (2×3)
{8_ 8_ 8}3	Triplet with all notes tied together but no beaming ( look at spaces)
4_{8 8 8}3	Quarter note tied to first note of triplet
{8 8 8_}3 4	Last note of triplet tied to quarter
| 4_ | {_8 8 8}3 |	Cross-measure tie into tuplet
|.1-3	Start volta bracket for endings 1, 2, 3
|.	Explicitly mark end of volta bracket
|.1,2,3	Alternative comma syntax for volta
8x	This 8th note will have a X note head instead of standard slash

🛠️ Development

Building from Source

# Clone repository
git clone https://github.com/MathieuCGit/ChordGrid_for_Obsidian.git
cd ChordGrid_for_Obsidian

# Install dependencies
npm install

# Build plugin
npm run build

# Run tests
npm test

Project Structure

ChordGrid_for_Obsidian/
├── src/
│   ├── parser/          # Syntax parsing
│   ├── analyzer/        # Musical analysis (beams, counting)
│   ├── renderer/        # SVG rendering
│   └── models/          # Data structures
├── test/                # 46 test suites (315 tests)
├── documentation/       # Technical docs
└── README.md           # You are here!

---

🤝 Contributing

Contributions are welcome! Whether you're fixing bugs, adding features, or improving documentation:

1. 📖 Read the Contributing Guide
2. 🏗️ Check the Architecture Documentation
3. 🐛 Browse existing issues
4. 💬 Start a discussion

---

📝 License

This plugin is released under the GPL-3.0 License. See LICENSE for details.

---

🙏 Acknowledgments

Built with passion for the music and Obsidian communities.

Author: Mathieu CONAN

---

Enjoying Chord Grid? ⭐ Star the repository to show your support!