Gridgen is a visual calculator for guitar chords. It's capable of manipulating chords, inferring chord symbols, rendering chord grids to SVGs, and embedding SVGs in HTML documents. Here's an example output.
C 1 chord 6 8 1 + 5 10 5 + 3 9 3 + 2 12 7 x C 4 chord 5 8 1 + 4 10 5 + 3 9 7 x 2 10 3 + over d- over d- over d- over d- over d- over d- am
Gridgen content appears within HTML elements with the “gridgen” class. Each element's textContent is interpreted as a chord calculation expression, the result of which replaces that element in the document, to be styled with CSS. This User Guide is an example. Consult the source to see how it's constructed.
These chord manipulations and diagrams are based on the works of Ted Green.
Each Chord has a specified key and degree within that key. For example a G chord might have degree 1 in the key of G, degree 4 in the key of D, or degree 5 in the key of C. This is to ensure that manipulations on that chord are performed diatonically within its key.
Similarly, each Stop has a specified interval within its chord. For example, an E stop in a C chord would have interval 3. This is to ensure that chord symbols can be correctly inferred, even after chord manipulation. A C chord that marks an E♭ with an interval of 3 would be noted Cmi.
Here's a minimal example to get started. The expression F 4 chord 4 8 1 + 3 7 3 + 2 6 5 + produces F 4 chord 4 8 1 + 3 7 3 + 2 6 5 +
This is a postfix expression. Its evaluation uses a stack. It proceeds as follows:
F 4 chord is a chord constructor.
F and 4 are pushed onto the stack.chord operator pops those operands and pushes a new chord with degree 4 in the key of F.4 8 1 + is a dot stop.
4, 8, and 1 are pushed onto the stack. They represent the string, fret, and interval.+ operator pops the three operands from the stack, along with the chord remaining on the stack from the previous step. It adds a new stop to the chord, and pushes the resulting chord back onto the top of the stack.3 7 3 + is another dot stop operation, leaving a chord with two stops on the stack.
2 6 5 + is another dot stop operation, leaving a chord with three stops on the stack.
At the end of all of this, the chord remains on the stack. It is converted to an HTML element and inserted into the document.
chordC or B♭ and ‹degree› is the chord degree in the range 1 to 7. This is the fundamental constructor of Gridgen chords and all other operators operate on these.Gridgen only accepts keys with up to 7 flats, or 7 sharps. No key with double flats or double sharps in the signature is recognized. Even with this restriction, there are a few enharmonic keys.
| 1 | 2 | 3 | 4 | 5 | 6 | 7 | ||||
|---|---|---|---|---|---|---|---|---|---|---|
| C♯ | · · · | C♯ | D♯ | E♯ | F♯ | G♯ | A♯ | B♯ | = | D♭ |
| F♯ | · · · | F♯ | G♯ | A♯ | B | C♯ | D♯ | E♯ | = | G♭ |
| B | · · · | B | C♯ | D♯ | E | F♯ | G♯ | A♯ | = | C♭ |
| E | · · · | E | F♯ | G♯ | A | B | C♯ | D♯ | ||
| A | · · · | A | B | C♯ | D | E | F♯ | G♯ | ||
| D | · · · | D | E | F♯ | G | A | B | C♯ | ||
| G | · · · | G | A | B | C | D | E | F♯ | ||
| C | · · · | C | D | E | F | G | A | B | ||
| F | · · · | F | G | A | B♭ | C | D | E | ||
| B♭ | · · · | B♭ | C | D | E♭ | F | G | A | ||
| E♭ | · · · | E♭ | F | G | A♭ | B♭ | C | D | ||
| A♭ | · · · | A♭ | B♭ | C | D♭ | E♭ | F | G | ||
| D♭ | · · · | D♭ | E♭ | F | G♭ | A♭ | B♭ | C | = | C♯ |
| G♭ | · · · | G♭ | A♭ | B♭ | C♭ | D♭ | E♭ | F | = | F♯ |
| C♭ | · · · | C♭ | D♭ | E♭ | F♭ | G♭ | A♭ | B♭ | = | B |
These operators add attributes to chords. The most important of these attributes are the stops that define the notes of the chord. Greene notation uses five distinct symbols, the dot, X, square and diamond, to be played in that order. An open circle is an optional stop. (CC p.?)
The stop appears at the given ‹string› and ‹fret›. The stop's voice within the chord has ‹interval› in the range 1 to 7. These values are popped from the stack, and the ‹chord› operand is pushed back onto the stack after the attribute is set.
+x=^o_(+) or (x) or (=) or (^) or (o) or (_).Chord options determine how chords are displayed.
$*!#-af or am.The following operations replace the chord at the top of a stack with the result of a calculation based on that chord.
s+s-d+d-f+f-i+i-o+o-4+d+ d+ d+ s-.5-d- d- d- d- s+.It's possible for these operations to produce an “invalid” chord—a chord that uses negative fret numbers or non-existent strings. Such invalid chords are well-defined, and useful as temporary values. However, if they are displayed, they might appear impossible.
?Chord alignment operators take a sequence of chords, equalize their size, and align them visually.
afamThis is almost always desirable, as each unaligned grid is displayed with minimal size. As a group, they will appear visually inconsistent.
These operators enable the construction of arbitrary HTML entities and parent-child relationships. Most any HTML structure may be produced, but table structures are particularly useful. See the examples below.
( ‹· · ·› ‹tag› )( and ) and push a new HTML ‹tag› element containing them all. Given N operands, this operator leaves one Element with N children on the stack.[ ‹· · ·› ‹tag› ][ and ] and push a new HTML ‹tag› element containing each. Given N operands, this operator leaves N Elements with 1 child on the stack.class|:( 𝄆 span ) bar class.|( 𝄀 span ) bar class.:|( 𝄇 span ) bar class.These operators are similar to those of the Forth programming language.
dropdupeswapoverThe following is a list of gridgen examples. To see how each is defined, examine the HTML source of this document.
The . operator adds a stop with an arbitrary character label. This has countless uses. For example, it may be used to indicate the fingering of a scale. This being the web, all of Unicode is at your disposal here.
D 1 chord $ 6 2 3 1 . 6 3 4 2 . 6 5 5 4 . 5 2 6 1 . 5 4 7 3 . 5 5 1 4 . 4 2 2 1 . 4 4 3 3 . 4 5 4 4 . 3 2 5 1 . 3 4 6 3 . 2 2 7 1 . 2 3 1 2 . 2 5 2 4 . 1 2 3 1 . 1 3 4 2 . 1 5 5 4 . D 1 chord $ 6 2 3 🍏 . 6 3 4 🍎 . 6 5 5 🍊 . 5 2 6 🍋 . 5 4 7 🍋🟩 . 5 5 1 🍌 . 4 2 2 🍉 . 4 4 3 🍇 . 4 5 4 🍓 . 3 2 5 🫐 . 3 4 6 🍈 . 2 2 7 🍒 . 2 3 1 🍑 . 2 5 2 🥭 . 1 2 3 🍍 . 1 3 4 🥥 . 1 5 5 🥝 .
Greene frequently used slashes beneath the chord grid to indicate the number of beats that a chord is played (CC p.58). This can be accomplished using the ! operator.
F 4 chord 6 7 1 + 4 7 7 + 3 7 3 + 1 5 7 + 2 6 5 x 6 2 # 4 3 # 3 4 # 2 1 # 1 1 # // ! F 4 chord 6 6 1 + 4 6 7 + 3 6 3 + 2 5 5 + 6 2 # 4 3 # 3 4 # 2 1 # / ! F 3 chord 6 5 1 + 4 5 7 + 3 5 3 + 2 8 7 + 2 5 5 x 6 1 # 4 1 # 3 1 # 2 4 # // ! F 3 chord 6 4 1 + 4 4 7 + 3 4 3 + 2 4 5 + 6 1 # 4 1 # 3 1 # 2 1 # / ! F 2 chord 6 3 1 + 4 3 7 + 3 3 3 + 2 6 7 + 2 3 5 x 6 1 # 4 1 # 3 1 # 2 4 # // ! F 4 chord 6 8 2 (+) 4 8 1 + 3 7 3 + 2 6 5 + 6 3 # 4 4 # 3 2 # 2 1 # / ! F 1 chord 5 8 1 + 4 7 3 + 3 9 7 + 2 8 2 + 5 2 # 4 1 # 3 4 # 2 3 # /// ! af
Alternatively, bar markers can indicate full measures, and can imply beat count, They also provide the opportunity to add repeat markers. For example, here's the melody and accompaniment to the lyric “You say to-ma-to, I say to-mah-to.”
|: G 1 chord 6 3 1 + 4 5 1 + 3 4 3 + 2 5 6 + 1 3 1 + 2 5 6 x 6 1 # 4 3 # 3 2 # 2 4 # 1 1 # G 6 chord 5 7 1 + 4 5 3 + 3 7 7 + 2 7 2 + 2 7 2 x 2 5 1 = 5 2 # 4 1 # 3 3 # 2 4 # | G 2 chord 6 5 1 + 4 5 7 + 3 5 3 + 2 8 7 + 1 5 1 x 6 1 # 4 1 # 3 1 # 2 4 # 1 1 # G 5 chord 5 5 1 + 4 7 5 + 3 5 7 + 2 5 2 _ 2 7 3 + 1 7 6 + 1 7 6 x 5 1 # 4 2 # 3 1 # 2 3 # 1 4 # :| af
Overlaid stops appear when an elaboration or a melody reuses a chord tone. The “to-ma-to, to-mah-to” sequence just above is an example.
Order sometimes matters. Stops are displayed in the order they are added to a chord. Later stops are displayed topmost. Here's a grid showing each of the standard markers—dot, circle, X, square, and diamond—overlaid with each other standard marker. It should be clear that dot and X should appear on top, while square, diamond, and circle must appear on the bottom.
C 1 chord $ 5 3 1 + 4 3 1 o 3 3 1 x 2 3 1 = 1 3 1 ^ 5 4 1 + 4 4 1 o 3 4 1 x 2 4 1 = 1 4 1 ^ 6 4 1 + 5 4 1 + 4 4 1 + 3 4 1 + 2 4 1 + 1 4 1 + 5 5 1 + 4 5 1 o 3 5 1 x 2 5 1 = 1 5 1 ^ 6 5 1 o 5 5 1 o 4 5 1 o 3 5 1 o 2 5 1 o 1 5 1 o 5 6 1 + 4 6 1 o 3 6 1 x 2 6 1 = 1 6 1 ^ 6 6 1 x 5 6 1 x 4 6 1 x 3 6 1 x 2 6 1 x 1 6 1 x 5 7 1 + 4 7 1 o 3 7 1 x 2 7 1 = 1 7 1 ^ 6 7 1 = 5 7 1 = 4 7 1 = 3 7 1 = 2 7 1 = 1 7 1 = 5 8 1 + 4 8 1 o 3 8 1 x 2 8 1 = 1 8 1 ^ 6 8 1 ^ 5 8 1 ^ 4 8 1 ^ 3 8 1 ^ 2 8 1 ^ 1 8 1 ^
To produce larger or smaller grids, set the zoom CSS property on the container of the element with gridgen class.
C 1 chord 5 3 1 + 4 2 3 + 3 4 7 + 2 3 2 + dupe d+ dupe d+ dupe d+ dupe d+ dupe d+ dupe d+ dupe d+ am
Stops are defined as SVG elements with classes that indicate their musical meaning:
To use these, define a CSS class to apply to the Gridgen element or its container. Then use descendant combinators to select pitches, degrees, and intervals among that container's children. Note that the !important property is needed if local changes are to override the SVG's existing CSS. See the source of this document for examples.
Here's a chord scale with stops colored by interval.
C 1 chord 5 3 1 + 4 5 5 + 3 4 7 + 2 5 3 + dupe d+ dupe d+ dupe d+ dupe d+ dupe d+ dupe d+ dupe d+ am
Here's the same chord scale with stops colored by scale degree.
C 1 chord 5 3 1 + 4 5 5 + 3 4 7 + 2 5 3 + dupe d+ dupe d+ dupe d+ dupe d+ dupe d+ dupe d+ dupe d+ am
(MCP, p. 21) introduces several forms for diatonic chord scales based on first-inversion triads, and suggests the reader build diatonic chords from each of them. We can easily generate solutions to these exercises by specifying the initial form and extending the sequence with several dupe d+ operations.
Clearly, the blind extension of these forms takes us quickly into the high frets. That's part of the exercise. When displaying chord grids, we could use string transference (s+ and s-) or shift the octave (o+ and o-) to accommodate. There are many ways to use operators to make these comfortably playable.
( E 1 chord 6 4 3 + 4 2 1 + 3 4 5 + 2 5 1 + dupe d+ dupe d+ dupe d+ dupe d+ dupe d+ dupe d+ am span ) block class ( E 1 chord 5 11 3 + 3 9 1 + 2 12 5 + 1 12 1 + dupe d+ dupe d+ dupe d+ dupe d+ dupe d+ dupe d+ am span ) block class ( E 1 chord 6 4 3 + 3 4 5 + 2 5 1 + 1 4 3 + dupe d+ dupe d+ dupe d+ dupe d+ dupe d+ dupe d+ am span ) block class ( E 1 chord 6 4 3 + 3 4 5 + 2 5 1 + 1 7 5 + dupe d+ dupe d+ dupe d+ dupe d+ dupe d+ dupe d+ am span ) block class ( E 1 chord 6 4 3 + 4 2 1 + 3 4 5 + 1 4 3 + dupe d+ dupe d+ dupe d+ dupe d+ dupe d+ dupe d+ am span ) block class ( E 1 chord 6 4 3 + 5 2 5 + 4 2 1 + 3 4 5 + dupe d+ dupe d+ dupe d+ dupe d+ dupe d+ dupe d+ am span ) block class ( E 1 chord 5 11 3 + 4 9 5 + 3 9 1 + 2 12 5 + dupe d+ dupe d+ dupe d+ dupe d+ dupe d+ dupe d+ am span ) block class ( E 1 chord 4 6 3 + 3 4 5 + 2 5 1 + 1 7 5 + dupe d+ dupe d+ dupe d+ dupe d+ dupe d+ dupe d+ am span ) block class ( E 1 chord 6 4 3 + 4 6 3 + 3 4 5 + 2 5 1 + dupe d+ dupe d+ dupe d+ dupe d+ dupe d+ dupe d+ am span ) block class ( E 1 chord 5 11 3 + 3 13 3 + 2 12 5 + 1 12 1 + dupe d+ dupe d+ dupe d+ dupe d+ dupe d+ dupe d+ am span ) block class
The moving lines example (MCP, p. 21) works nicely as well, since decoration stops are preserved through chord operators.
E 1 chord 6 4 3 + 3 4 5 + 2 5 1 + 1 7 5 + 1 5 4 (x) 1 4 3 (=) dupe d+ dupe d+ dupe d+ dupe d+ dupe d+ dupe d+ am
(MCP, p. 23) Continues the chord scale exercise with diatonic 7th chords. Here are just a few.
( E 1 chord 6 0 1 + 5 2 5 + 4 1 7 + 3 1 3 + dupe d+ dupe d+ dupe d+ dupe d+ dupe d+ dupe d+ am span ) block class ( E 1 chord 5 7 1 + 4 9 5 + 3 8 7 + 2 9 3 + dupe d+ dupe d+ dupe d+ dupe d+ dupe d+ dupe d+ am span ) block class ( E 1 chord 4 2 1 + 3 4 5 + 2 4 7 + 1 4 3 + dupe d+ dupe d+ dupe d+ dupe d+ dupe d+ dupe d+ am span ) block class
While designed for use on chords, Gridgen is equally capable of handling scales. Here, the dupe d+ operator is used to generate the modes of the key of D. The am operator aligns them into positions.
D 1 chord 5 5 1 + 5 7 2 + 4 4 3 + 4 5 4 + 4 7 5 + 3 4 6 + 3 6 7 + 3 7 1 + dupe d+ dupe d+ dupe d+ dupe d+ dupe d+ dupe d+ dupe d+ am
And the af operator lays them out across the fretboard.
D 1 chord 5 5 1 + 5 7 2 + 4 4 3 + 4 5 4 + 4 7 5 + 3 4 6 + 3 6 7 + 3 7 1 + dupe d+ dupe d+ dupe d+ dupe d+ dupe d+ dupe d+ dupe d+ af
It's interesting to see the modes overlaid by the arpeggios.
D 1 chord 5 5 1 o 4 4 3 o 4 7 5 o 3 6 7 o 3 7 1 o 5 5 1 + 5 7 2 + 4 4 3 + 4 5 4 + 4 7 5 + 3 4 6 + 3 6 7 + 3 7 1 + dupe d+ dupe d+ dupe d+ dupe d+ dupe d+ dupe d+ dupe d+ am
(MCP, p. 49) discusses “The Diatonic Cycle of 4ths in Major Keys.” The first example there is straightforwardly reproduced by defining only the first two chords, Cma7 and Fma7. Subsequent chords are each generated by an over d- operation. Specifically, the initial two chords on the stack are separated by a fourth. Then, over duplicates the second element from the top of the stack, and d- moves that duplicate down one degree.
C 1 chord 6 8 1 + 5 10 5 + 3 9 3 + 2 12 7 x C 4 chord 5 8 1 + 4 10 5 + 3 9 7 x 2 10 3 + over d- over d- over d- over d- over d- over d- over d- over d- am
Note how the elaboration established by the initial two chords is maintained in generated chords.
(CC, p. 9) presents the concept of structured inversion as a formal way of enumerating chord voicings. The examples (CC, p. 10) are straightforwardly reproduced using the i+ operator.
C 3 chord 6 3 3 + 4 2 1 + 3 4 5 + dupe i+ dupe i+ af A 5 chord 6 7 5 + 4 6 3 + 3 7 7 + 2 5 1 + dupe i+ dupe i+ dupe i+ af
As noted, Chord Manipulation Operators can produce invalid chords that won't display properly. Validity can almost always be achieved using another chord manipulation operator, but determining when this is necessary can be a manual process. The ? operator can automate some of these fixes.
If a d- or i- operation shifts a chord off the end of the fretboard, then dupe o+ ? moves it up an octave. Specifically, this duplicates the chord, moves the duplicate up an octave, and selects either the original or the duplicate as needed. This way, the chord is only moved up an octave if necessary.
If a d+ or i+ shifts a chord up into the high frets, making it uncomfortable to play, then dupe o- swap ? moves it down an octave. Note that this is the reverse of the previous example. This operation prefers the duplicate (due to the swap), but only selects it if it's valid.
If both options are invalid, | will return the second one. A chain of | operators can be used to handle complex fixes.
Gridgen maintains a small dictionary of chord formulas that it uses to infer the chord symbol shown at the top of each grid.
Consider, F 5 chord 6 3 5 + 5 3 1 + 4 2 3 + 3 3 7 + 2 3 2 +. This chord is defined in the key of F with 5th degree. From this alone, Gridgen knows the root is C. So, it compares the stops added to the chord, (G C E B♭ D), with the notes of the C major scale. This gives the intervals (5 1 3 ♭7 2). Sorted, (1 2 3 5 ♭7) appears in the dictionary as a dominant 9 chord. But the bass note is G, not the root C, so Gridgen indicates this with slash notation.
Now consider, F 5 chord 5 3 1 + 4 2 3 + 3 3 7 + 2 3 2 +. This is the same chord, but it's missing the 5, and the formula (1 2 3 ♭7) is not in the dictionary. Gridgen knows that 5 is often omitted, and will insert a perfect 5th, or a major 3rd, in its effort to find a matching dictionary entry.
A chord symbol's title attribute contains its formula. This is displayed when the pointer hovers over the symbol.
Consider C 1 chord 6 8 1 + 5 4 2 +. That's a (1 ♭2) chord, and Gridgen doesn't know what to call it. The question mark indicates that inference has failed. This can happen in two ways:
_ operator to add invisible stops to fill in the gaps.If an expression is not displaying correctly, the process of evaluation can be dumped to the console log by adding the “debug” class to the “gridgen” element. Check the console now to see how F 4 chord 4 8 1 + 3 7 3 + 2 6 5 + gets turned into F 4 chord 4 8 1 + 3 7 3 + 2 6 5 +
This example demonstrates the ( ) and [ ] element operators with a non-trivial HTML structure.
( ( [ A 1 chord 6 5 1 + 5 4 3 + 4 2 5 +
dupe d+ dupe d+ dupe d+ am td ] tr )
( [ A 1 chord 4 7 1 + 3 6 3 + 2 5 5 +
dupe d+ dupe d+ dupe d+ am td ] tr ) table ) display class
The chord constructor and dupe d+ operator generate four chords. [ ... td ] wraps each chord in a table cell. ( ... tr ) wraps these four table cells in a table row. This is done twice, and ( ... table ) wraps these two table rows in a table. Finally, the display class is given to the table, which centers it on this page.
If necessary, text may be embedded directly within a Gridgen expression. The ( ) and [ ] element operators work here too. This example shows two separate four-chord sequences with text between them. But because it's a single expression, the af aligns all eight chords.
A 1 chord 6 5 1 + 5 4 3 + 4 2 5 + dupe d+ dupe d+ dupe d+
is one ( octave em ) lower than
A 1 chord 4 7 1 + 3 6 3 + 2 5 5 + dupe d+ dupe d+ dupe d+ af
A 1 chord 6 5 1 + 5 4 3 + 4 2 5 + dupe d+ dupe d+ dupe d+ is one ( octave em ) lower than A 1 chord 4 7 1 + 3 6 3 + 2 5 5 + dupe d+ dupe d+ dupe d+ af
If these two sequences were given as separate expressions, the alignment would apply to each separately.
Here's a demonstration of HTML structure using dupe. It highlights the difference between the ( ) and [ ] element operators.
( G 1 chord 4 5 1 + 3 4 3 + 2 3 5 + dupe d+ am span ) dupe produces
( G 1 chord 4 5 1 + 3 4 3 + 2 3 5 + dupe d+ am span ) dupe
[ G 1 chord 4 5 1 + 3 4 3 + 2 3 5 + dupe d+ am span ] dupe produces
[ G 1 chord 4 5 1 + 3 4 3 + 2 3 5 + dupe d+ am span ] dupe
In the first example, the ( ) operator receives two chords and wraps them both in a single span element. Then, dupe duplicates the span at the top of the stack, resulting in two sets of two chords.
In the second example, the [ ] operator receives two chords and wraps them each in its own span element. Then, dupe duplicates the span at the top of the stack, resulting in two of only the last chord.