# 🎡 Chord Grid for Obsidian [![Version](https://img.shields.io/badge/version-2.2.0-blue.svg)](https://github.com/MathieuCGit/ChordGrid_for_Obsidian/releases) [![License](https://img.shields.io/badge/license-GPL--3.0-green.svg)](./LICENSE) [![Tests](https://img.shields.io/badge/tests-536%20passing-brightgreen.svg)](#) > **Transform simple text notation into beautiful, professional chord charts with rhythmic notationβ€”right inside your Obsidian notes.** [πŸ‡«πŸ‡· Version franΓ§aise](./README_[Fr].md) | [πŸ“– Full Documentation](./documentation/) | [πŸ› Report Bug](https://github.com/MathieuCGit/ChordGrid_for_Obsidian/issues) **For this entry** ````markdown ```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** image --- ## 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: ````markdown ```chordgrid 4/4 | C | G | Am | F / G | ``` ```` image That's it! You just created your first chord chart. --- Want to add a repeat bar? No worries! ````markdown ```chordgrid 4/4 ||: C | G | Am | F / G :|| ``` ```` image --- Now let's say we need to change the last measure to a different chord while keeping the previous ones: ````markdown ```chordgrid 4/4 ||: C | G | Am |.1-3 F / G :||.4 Bb | ``` ```` image --- Now let's add this awesome rhythm strum pattern so we don't forget it! ````markdown ```chordgrid 4/4 ||: C[8.16 88 4 168.] | G | Am |.1-3 F / G :||.4 Bb | ``` ```` image --- 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 ````markdown ```chordgrid measures-per-line:5 4/4 ||: C[8.16 88 4 168.] | G | Am |.1-3 F / G :||.4 Bb | ``` ```` image --- 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 ````markdown ```chordgrid measures-per-line:5 pick 4/4 ||: C[8.16 88 4 168.] | G | Am |.1-3 F / G :||.4 Bb | ``` ```` image --- Nice! Now I'd like to apply this rhythm pattern to the following measures. I could copy/paste the rhythm pattern... or? ````markdown ```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.] | ``` ```` image --- Wow! Amazing! But now there's too much information in each measure. Can I make this cleaner? Yes, use `show%` ````markdown ```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.] | ``` ```` image --- Finally, I think I'll play this rhythm with fingers instead of a pick. Can I? **Sure!** Use `finger` instead of `pick` ````markdown ```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.] | ``` ```` image ## πŸŽ“ 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 ````markdown ````chordgrid C[4 -4 88 _16-161616] ``` ```` image #### BE CAREFUL :warning: **If you want to keep beams grouped by beat, pay attention to space placement. For example:**:warning: ````markdown ```chordgrid C[4 88_] G[_88 4] ``` ```` image is different from ````markdown ```chordgrid C[4 88_]G[_88 4] ``` ```` image ### 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: ````markdown ```chordgrid stems-down 4/4 | C[88 4 4 4] | G[4 4 2] | ``` ```` image ### 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` ````markdown ```chordgrid pick 4/4 | C[88 4 4 4] | G[4 4 2] | ``` ```` image ### 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 ````markdown ```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: ````markdown ```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 ````markdown ```chordgrid 4/4 | Am[88 4 88 4] | % | Dm[%] | G[%] ``` ```` image 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 ````markdown ```chordgrid show% 4/4 | Am[88 4 88 4] | % | Dm[%] | G[%] ``` ```` image ### 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 ````markdown ```chordgrid 4/4 ||: C[4 4 4 4] |.1-3 G[4 4 4 4] :||.4 Am[4 4 4 4] || ``` ```` image Second example: volta 1-3 covers two measures before `:||`, volta 4 extends to Am using `|.` marker ````markdown ```chordgrid 4/4 ||: C[4 88_ 4 4] | % |.1-3 G[%] | % :||.4 G[4 4 4 4] |. Am[16168 81616 4 88] || ``` ```` image ### 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. ````markdown ```chordgrid 4/4 | Em[4 8x]G[8_4 4x] | D[4 8x]C[8_4 4x] ``` ```` image ### 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: ````markdown ```chordgrid pick 4/4 | C[8d8u8d8u 8d8u8d8u] | G[8u8u8d8d 8u8u8d8d] | ``` ```` image #### 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) ````markdown ```chordgrid finger:fr 4/4 | C[4pd 4mu 4pd 4mu] | G[8md8mu8md8mu 8md8mu8md8mu] | ``` ```` image #### Interoperability **New in v2.2:** You can use finger notation suffixes in pick mode! They will be automatically normalized to simple d/u: ````markdown ```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! image #### 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 ```bash # 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](./documentation/CONTRIBUTING.md) 2. πŸ—οΈ Check the [Architecture Documentation](./documentation/ARCHITECTURE.md) 3. πŸ› Browse [existing issues](https://github.com/MathieuCGit/ChordGrid_for_Obsidian/issues) 4. πŸ’¬ Start a [discussion](https://github.com/MathieuCGit/ChordGrid_for_Obsidian/discussions) --- ## πŸ“ License This plugin is released under the **GPL-3.0 License**. See [LICENSE](./LICENSE) for details. --- ## πŸ™ Acknowledgments Built with passion for the music and Obsidian communities. **Author:** [Mathieu CONAN](https://github.com/MathieuCGit) --- **Enjoying Chord Grid?** ⭐ Star the repository to show your support!