Background

JotChord™️ is an application for creating number charts - sometimes called "Nashville Number System" or "NNS" for short.

Number charts are often handwritten, or created digitally using a word processor (like Microsoft Word of Google Docs) or drawing/illustration program (like Adobe Illustrator). There are also some specialized iPad apps for creating number charts. However, all of these methods have some drawbacks.

One of the main problems that JotChord™️ solves is reducing the amount of time and effort required to make PDF charts. It accomplishes this with the invention of ChordText™.

ChordText™ is a simple text format for authoring Nashville Number System chord sheets, that JotChord™️ can automatically format into a PDF. With ChordText™, musicians can focus on the structure and contents of the chart -- the promise of NNS! -- without having to worry about column layouts, or drawing symbols that are unique to NNS. With ChordText™, you can simply type chord numbers in plain text, enabling you to chart a song in minutes - often in as much time as it takes you to listen to the song once.

Like Tablature is to guitar notation, ChordText™ aspires to be to Nashville Notation.

ChordText™ Reference

The following reference explains the musical nuances that ChordText™ supports, and how JotChord™️ interprets and renders those nuances.

Overview of ChordText™

You can think of the structure of a number chart as represented in the following diagram:

├── Metadata:
│   ├── Title
│   ├── Key
│   ├── Tempo
│   ├── Meter
│   ├── Style
│   ├── Feel
|   ├── $customProperty
├── Section1:
│   ├── measures
│   │   ├── chords
│   │   │   ├── rhythms, articulations and other symbols
│   ├── comments
├── Section2:
...

A ChordText™ chart is a collection of:

• Metadata: things like the title of the song, the key it's in, the meter / time signature, the tempo, and some information about the artist, author, arranger, etc.
• Sections: things like the intro, verse, pre-chorus, chorus, outro, etc.

Metadata

While the main purpose of a number chart is to lay out the structure of a song, there are important details that a performer references, to put the song structure into the right context.

For example, a 1-chord can only be played if the Key of the song is known.

While number charts give the rhythm player the freedom to apply their creativity and feel to how the song is played, the player needs to know some basic parameters like the Meter (Time Signature) and Tempo.

Also, when you play a lot of number charts, it's helpful for each to have basic hygiene, like the song Title, the Artist, the Arranger, etc.

ChordText™ requires certain metadata to be declared before it will even render a chart. All of this information is currently rendered in the header of the PDF.

Optional metadata:

• Title: - followed by the name of the song - all alphanumeric characters are allowed, as are some common symbols

  Title: Need You Now
  

• Key: - followed by the letter of the key, and optional accidental (sharp or flat)

  Key: Bb
  

  Key: F#
  

• Tempo: - followed by a number representing the beats-per-minute (BPM)

  Tempo: 108
  

  For legibility, you may add "bpm" or "BPM" after the tempo number; JotChord™ will render it automatically if you omit it.

  Tempo: 108bpm
  

  JotChord™ automatically adds the tempo resolution (e.g., quarter-note, eighth-note) based on the meter, as follows:

  Meter denominator (bottom number)	Tempo resolution	Example(s)
  2	1/2 note	2/2 3/2
  4	1/4 note	2/4 4/4 6/4
  8	dotted 1/4 note	3/8 6/8 9/8 12/8

• Meter: - followed by a fraction representing the meter (e.g., 4/4 for common time)

  Meter: 12/8
  

  JotChord™ assumes 4/4 if the meter is not declared.

• Style: - followed by any text; use the shortest expression of the style, because the space allotted is small

  Style: Bossa nova
  

  If both Style: and Feel: metadata lines are provided, JotChord™ will display Style: and hide Feel:.

• Feel: - followed by a fraction representing the meter (e.g., 4/4 for common time)

  Feel: Swing
  

  JotChord™ will append the word "feel" to the end of the provided feel. In the above example, the chart will read "Swing feel" next to the meter designation.

  If both Style: and Feel: metadata lines are provided, JotChord™ will display Style: and hide Feel:.

Custom metadata:

• ${name}:, where {name} is replaced by a label containing any alphanumeric characters

  $Artist: The Beatles
  

  $Arranger: John Smith
  

  JotChord™ renders custom metadata attributes right-aligned in the header.

  NOTE: Currently, 1-3 custom metadata fields will render reasonably well; any more, and JotChord™ will attempt to squish them vertically to fit them in to the minimal space allotted for custom metadata.

Section headers

Song sections start with a header line, usually 2-3 upper-case letters, but may include lower case letters, numbers and some special characters (listed below):

IN:

-or-

V1:

• Section header names may include the following special characters:

  Character	Name
  -	Dash
  /	Forward-Slash
  ,	Comma
  .	Period
  ~	Tilde
  #	Octothorpe ("Hash" or "Number" sign)
  @	At symbol
  &	Ampersand
  *	Asterisk
  _	Underscore
  +	Plus
  |	Pipe

Song sections include a collection of:

• Descriptive comments: things like instructions for the performers ("Drums out" or "Build...")
• Measures: the basic unit representing the musical grid, governed by the song's meter (e.g., 4 quarter-note beats in 4/4).

Descriptive comments

In NNS, it's common to provide clarifying instruction to performers above the measures where the instructions apply.

In ChordText™, descriptive comments are represented in their own lines, starting with two forward-slash characters:

//this is a comment line

Measures

Measures are a collection of:

• Chords

In number charts, measures are separated by spaces.

In ChordText™, you can use any "whitespace" (spaces or tabs) to separate measures.

Any whitespace at the beginning and/or end of a measure line will be ignored by JotChord™️.

Tip: adding some whitespace to the beginning of a measure line ("indenting" the line) can make it easier to scan the ChordText™, differentiating section headers from measures. E.g.:

IN:
    1 1 4 5
VR:
    1 1 4 1
    5 5 4 1

A measure can have a single chord, or multiple chords.

Single-chord measures are easy: separate the chord numbers by one or more spaces or tabs.

Multi-chord measures are where ChordText™ introduces some new conventions. In NNS, grouping multiple chords in a measure is called a "split bar".

There are several ways to group chords together into a single measure:

1. Split bar with an underline
2. Split bar with parentheses
3. Uneven split bars - see ##tick marks##

Split bar with an underline

In NNS, two or more chord numbers that are underlined are considered a "split bar".

In ChordText™, you simply join two chords with an underscore character (_).

JotChord™️ will underline all chord numbers that are joined by an underscore character.

Examples:

• Two-chord split bars:

  1_6- 4_5
  

• A four-chord split bar:

  4_3-_2_1
  

Split bar with parentheses

In NNS, two or more chord numbers inside parentheses are also considered a "split bar".

In ChordText™, you simply type an open parenthesis "(" followed by a series of space-separated chord numbers, and then a closing parenthesis ")".

JotChord™️ will render split bars almost exactly as they were entered, with parentheses and chord numbers separated by space.

Examples:

• Two-chord split bars:

  (1 6-) (4 5)
  

• A four-chord split bar:

  (4 3- 2 1)
  

• Parentheses can also be used to indicate a temporary meter change, e.g. from 4/4 to a single 2/4 bar:

  1 4 5 (5..)
  1 1
  

Measure group separator

In number charts, a circle (•) can be placed between groups of measures, to allow for more measures on a single line, but still maintaining typical phrase grouping (e.g., 4 bar phrases).

In ChordText™, you can place an asterisk (*) between any chords in a measure line.

Example:

• A group of 4 measures, separated from another group of 4 measures:

  1 1 1 1 * 4 4 5 5
  

Chords

In NNS, chords are represented by numbers; more specifically, by arabic numerals (1,2,3,...).

You've likely heard phrases such as "the 1 chord" or "the 5 chord". Maybe you have studied some classical or jazz theory, and you're more accustomed to the roman numeral representation: I-chord or V-chord.

We won't go over the full explanation here, but the following should illustrate how it works. If this is new to you, there are plenty of online resources that explain the basics of NNS.

Diatonic chords

The natural ("diatonic") chords in C-Major are:

In ChordText™, you simply type the chord number. This number technically represents the scale degree on which a 3-note chord ("triad") is constructed.

Non-diatonic chords

For chords that are not in the tonal center of (or "diatonic to") the key of the song, you can alter the chord number (scale degree) with a flat or sharp before the {number}:

Chord qualities

By default, chords are Major in number charts. That is, a number by itself is a Major triad built on that number scale degree in the key of the song.

In NNS, you can alter the chord quality by adding a symbol after the chord number.

In ChordText™, this is notated as below, replacing {number} with the chord number:

Notes:

• The upcarat symbol (^) evokes a triangle, a common symbol in NNS that represents Major chord qualities, often used for Maj-7 chords, or to highlight that the diatonic chord would normally be minor.

  • JotChord™️ will render a triangle instead of the upcarat (^).
  • Alt: If you use upper-case "M" for Major chord qualities, JotChord™️ will render the "M".

• The dash symbol (-) is a common way to represent minor chords.

  • JotChord™️ will render a dash symbol (-).
  • Alt: If you use the lower-case "m" for minor chord qualities, JotChord™️ will render "m".

• The lower-case letter "o" evokes the superscript circle commonly used to represent a diminished chord.

  • JotChord™️ will render a superscript circle instead of the "o" character.
  • Alt: If you use the "dim" designation for a diminished chord quality, JotChord™️ will render "dim".

• The plus-sign (+) commonly denotes an augmented chord, although it is typically superscripted.

  • JotChord™️ will render a superscript plus-sign.
  • Alt: If you use the "aug" designation for an augmented chord quality, JotChord™️ will render "aug".

  Here is an example 8-bar progression with seven different chord qualities:

  7o  1   3^  6-
  4add9 #4+ 5sus4 1
  

All of these examples express basic 3-note chords ("triads").

No Chord - N.C., tacet or rest

A special-case version of a chord is X, denoting a tacet or rest. It is a more compact way to indicate No Chord (N.C.).

As in NNS, you can simply substitute an X anywhere you'd put a chord in ChordText™. This includes in split bars, surrounded by diamonds, and you can decorate it with pushes, tick marks and any other rhythm indicators.

• Whole measure rest:

  X
  

• Half-note rest:

  X_5
  

• In context:

  1 6- 5 X
  

Beyond triads - tetrads, extended and altered chords

Most musicians will be familiar with dominant-7th chords. This is technically a tetrad (i.e., a chord with 4 notes).

A dominant-7th chord is usually expressed in number charts as a chord number followed by a superscript number 7. You can think of the superscript number 7 as an exponent, as in grade school math.

ChordText™ supports any number of extended modifications to chords, with the following conventions:

General "exponent" form (**)

In ChordText™, the most general form for expressing a chord's exponent is as follows:

{number}**{exponent}

For example, if the 5-chord should be a dominant-7th chord, you would write:

5**7

Altered chord examples and shorthand forms

The modifications to a chord can be quite complex, and ChordText™ supports any modifications you can dream up. Rather than detail every possible rule, here are several examples, along with some convenient short-hand forms, where applicable:

As you can see, it is often convenient to use one of the shorthand representations. There are some rare times when a shorthand form cannot be used, thus the general "exponent" (**) form exists.

Sometimes, for legibility, it is better to use more explicit chord modifiers, like the last example that includes the parentheses and comma separating the alterations. JotChord™️ will attempt to render the chord as closely as possible to the way it was entered in ChordText™. If you add parentheses and commas, it will render those. If you omit them, it will omit them.

Slash chords (inversions)

In NNS, a slash chord represents a chord with a scale degree other than the root of the chord in the bass. This can be used to notate:

• Chord inversions - for example a first-inversion 1-chord would be expressed as:

  1/3
  

• Chords with passing tones in the bass - for example a 1-chord to a 6-minor-chord might have the bass pass through the 7th scale degree:

  1 1/7 6- 1/5
  

As you can see, in ChordText™, you simply write the chord with all of its symbols (quality, extensions and alterations), followed by a forward-slash symbol (/) and then the bass scale degree (a number 1 through 7).

As with the scale degree of the chord, the bass scale degree can also be altered for non-diatonic chords, e.g.: 3^/#5 represents a 3-major-chord over a sharp-5 bass (this happens to be the secondary dominant of the 6- chord).

Rhythms & Articulations

In NNS, there are several conventions for notating rhythms, including:

Diamonds

In NNS, a diamond shape around a chord indicates that it should be held for the duration of the measure.

In ChordText™, you surround the chord with less-than and greater-than symbols, as with this "diamond on the one":

<1>

Typically, diamonds are used to represent whole note chords, but they can also be used in split bars:

1_<4>

This represents two beats of a 1-chord (played with any rhythm), and then a half-note 4-chord.

You can wrap diamonds around any chord of any complexity, e.g.:

<1^7#5>

Pushes

In NNS, a less-than (<) or greater-than (>) symbol can be added above a chord number, to signify that the chord should be syncopated ("pushed") early or late, usually by an 8th note in a common meter like 4/4. Sometimes, these symbols are used interchangeably.

In ChordText™, these symbols are never used interchangeably. They behave as follows:

• Less-than (<): denotes pushing the chord earlier than written. JotChord™️ will render this slightly above and to the left of the chord number.
• Greater-than (>): denotes pushing the chord later than written. JotChord™️ will render this slightly above and to the right of the chord number.

These symbols are to be placed immediately following the chord and any chord modifiers (i.e., chord quality symbols and/or extended/altered chord tones), and before any spaces.

Here are some examples of how this would work in ChordText™:

• Early-push the 4-chord (e.g., by 1/8 in 4/4):

  1 4<
  

• Late-push several chords in a split bar:

  1 5>_4> 1 5>_4>
  

• Early-push a diamond chord:

  <5><
  

• Late-push a diamond chord:

  <5>>
  

NOTE: Pushes and tick marks occupy the same space. Use one or the other. If you need both, let us know!

Tick marks

In NNS, vertical "tick" lines are used to notate uneven split bars; that is, bars where the chords have uneven durations.

In ChordText™, a tick mark is represented with a period symbol (.) placed immediately following the chord and any chord modifiers (i.e., chord quality symbols and/or extended/altered chord tones), and before any spaces.

Example:

1..._4. 5 6-.5.4.3- 2-_5

NOTE: Pushes and tick marks occupy the same space. Use one or the other. If you need both, let us know!

Ties

In NNS, chords can be tied together with a curved line between them. This is borrowed from traditional music notation, and typically occurs when a chord at the end of a measure should carry over to the beginning of the next measure without being re-played. Most commonly, this is combined with diamond chords to indicate a chord that is held across multiple measures.

In ChordText™, a tie is indicated by an equals sign (=) placed immediately following the chord and any chord modifiers (i.e., chord quality symbols and/or extended/altered chord tones), and before any spaces.

Examples:

• Two whole-note (diamond) 1-chords tied together

  <1>= <1>
  

• A half-note 4-chord tied to the first beat of the next measure, giving a 2-3-3 beat subdivision

  1_<4>= 4.<5>...
  

Mutes / cut-offs / marcato

In NNS, chords can be marked with an inverted triangle to indicate that the chord should be played and then immediately muted or cut-off.

In ChordText™, a mute is indicated by an exclamation point (!) placed immediately following the chord and any chord modifiers (i.e., chord quality symbol and/or extended/altered chord tones), and before any spaces.

Examples:

• A mute on the downbeat of a measure

  1!
  

• Mutes on beats 1 and 3 of a 4/4 measure

  1!_1!
  

• Five James Brown hits

  5D9!_5D9!_5D9!_5D9! 5D9!
  

Fermatas ("bird eyes")

In NNS, borrowing again from traditional notation, a fermata (aka a "birds eye") indicates that a chord should be held for the duration of the remainder of the measure, and then some. How long a fermata is to be held is at the discretion of the player or ensemble, although it's common to double the duration.

In ChordText™, a fermata is indicated by a tilde character (~), placed immediately following the chord and any chord modifiers (i.e., chord quality symbols and/or extended/altered chord tones), and before any spaces.

<1>~

Meter changes (inline)

In NNS, as in traditional notation, the song's meter can change at any time.

In ChordText™, a meter change is indicated with square brackets ( [] ) surrounding a meter. As in the Meter metadata, the meter should have a number of beats (numerator), a forward-slash (/) and a number indicating the measure resolution (denominator). The **meter change can be placed anywhere on a measures line, except at the end. That is, a meter change should alway be followed by at least one chord (or X for no chord).

Here is a meter change to 3/8:

[3/8] 5

Here is a meter change to 3/8, followed by another meter change back to 6/8:

[3/8] 5 [6/8] 5

Another way to indicate a meter change inline is to use parentheses and tick marks around the bar to indicate a temporary change, as in this single 2/4 bar in a 4/4 song:

1 4 5 (5..)
1 1

Combining into complex rhythms

The above ChordText™ conventions can be combined to form fairly complex articulations of rhythm. This is one place where ChordText™ and JotChord™️'s handling of the rendering saves time. Anyone who has had to Insert Drawing in a Google Doc or Word document for every little detail--and then later revise the chart--will recognize how these simple symbolic conventions can add up to significant time savings.

Here's a common way you might see these used together:

IN:
    <1>= <1>!
VR:
    4   4   1   1
    4   4   5..._5sus4. 5_5D7
    4   4   1   1_1/7
    6-  <4>= <4>!
    1...1sus4. 1...1/3

Modulations

In NNS, it's common to notate a modulation or key change with the text "Mod", an arrow indicating the direction (up or down), and either the scale degree in the original key that becomes the new "1" chord, or the key itself (e.g., to G).

In ChordText™, indicate a modulation using the mod syntax. Indicate the direction up with a plus sign (+) or down with a minus/dash sign (-). Follow this with the number of half steps to modulate.

• Modulate up one whole step (two half-steps):

  mod+2
  

• Modulate down two whole steps (four half-steps):

  mod-4
  

JotChord™ handles these directives a few different ways.

• Key: If the chart has a key, JotChord™ will indicate the new key (letter name, e.g., Bb).
• Scale Degree / No Key: If the chart has no key, JotChord™ will indicate the scale degree that becomes the new "1" chord (e.g., "b3").
• Half Step: If the modulation interval is 1, JotChord™ will always say, "half step" instead of the key or scale degree.
• Whole Step: If the modulation interval is 2, JotChord™ will always say, "whole step" instead of the key or scale degree.

Freeform text

Comment lines

When you want to add freeform text and have it take up a whole line, you can use a comment line.

Examples:

• A double-forward-slash indicates the line is a comment

  //this is a comment line
  

• Provide instructions to performers with comments

  //Drums and bass enter
  

Inline comments

when you want to add freeform text, but have it displayed on the same lines as--before, between and after--chords, you can use an inline comment.

In ChordText™, you use a "slash-star" notation for inline comments. It looks like this: /*comment here*/

As you can see, you start the comment with /* and end it with */. These set the boundaries of the comment, and anything inside those boundaries are rendered in the PDF, including all whiespaces.

Additionally, JotChord™ will interpret an inline comment that starts directly after a chord (i.e., with no spaces separating the chord and the inline comment) as part of the chord/measure. The chart's column alignment will reflect this.

• Inline comments attached to chords

  1/*-crunchy*/
  

If you add spaces around the inline comment, JotChord™ will treat this as if it a separate measure. It's just a measure that doesn't have any chord numbers. The length of this comment will affect the column spacing for any other chords in that section.

• Inline comment instead of chords

  /*vamp*/ 1 /*cue is flam on beat 4*/
  

Song form

Number charts are read top-to-bottom, left-to-right.

Besides section headers that denote major blocks of the song form, it's also common to borrow some song form conventions from traditional notation, such as:

• Repeats
• Ending brackets
• Jumps
  • D.C or "Da capo"
  • D.S. or "Dal Segno"
  • To Coda

At this time, ChordText™ only supports Repeats. One reason is that it is usually clearer to write a chart linearly, and not require musicians -- who are often sightreading the chart -- to spot where they need to jump to and from. Another reason is that this is the early days of ChordText™, and we're eager to learn what conventions are most important to you.

Repeats

Repeat symbols designate sections that should be repeated.

Here is an example of 4 bars that are to be repeated once:

||: 1   4   4   1 :||

You'll recognize that the start and end repeat symbols look like how they are traditionally notated, just represented in plain text.

Repeat multiple times

In pop music, the same chord progression is often repeated multiple times. Sometimes this is written out long form. But sometimes it's clearer, and more compact, to indicate that a sequence of chords should be repeated multiple times.

By default, repeats should be repeated once; that is, played through twice (2x). If you expect a section to be played more than twice, you can indicate how many times as follows:

||: 1   4   4   1 :||{4}

With this example, JotChord™ will render (4x) above the ending repeat.

Note that the curly braces must be placed directly after the end repeat sign, and only whole numbers (integers) are allowed in the curly braces. (No decimals or fractions.) You may add an "x" or "X" for "times", but it's no necessary. JotChord™ will add it for you.

Multi-measure repeats

Multi-measure repeats are another NNS feature borrowed from traditional notation. They indicate that the performer should repeat the previous bar, or multiple previous bars.

In ChordText™, you notate that the previous bar should be repeated with the percent sign (%). To notate that multiple previous bars should be repeated, add more percent signs, up to 8 for an 8-bar repeat.

• Repeat the previous bar:

  %
  

• Repeat the previous 2 bars:

  %%
  

• Repeat the previous 4 bars

  %%%%
  

• Up to 8 bars

  %%%%%%%%
  

• In context:

  1 1 3- 3- %%%% %%%% 4 <4>
  

Putting it all together - an example chart

Example ChordText™

Here is an example chart for Need You Now by Lady A.

Title: Need You Now
Key: E
Meter: 4/4
Tempo: 108
$Artist: Lady A
$Chart: JotChord™

IN:
//Piano & Bass only                                                                                      Drums & Guitar in
<4>= <4>    <6->= <6-> *  4   4       6-  6-
V1:
4 4 6- 6- * 4 4 6- 6- * 4 4 6- 6- * 4 <4>
CH:
1 1 3- 3- * 1 1 3- 3- * 4 4 <4>
LN:
4 4 6- 6-
V2:
4 4 6- 6- * 4 4 6- 6- * 4 4 6- 6- * 4 <4>
CH:
1 1 3- 3- * 1 1 3- 3- * 4 4 4
BR:
||: 6-_5> 1<  4   5 :||
<4>= <4>  6-  <5>
CH:
1 1 3- 3- * 1 1 3- 3- * 4 4
OUT1:

||: 1 1 3- 3- :||{4}
OUT2:
//Fade on last repeat
||: <1>= <1>  <3->= <3-> :|| {4}

//Words and Music by Hillary Scott, Charles Kelley, Dave Haywood and Jost Kear.
//© 2009 EMI FORAY MUSIC, HILLARY DAWN SONGS, WARNER-TAMERLANE PUBLISHING CORP., RADIOBULLETSPUBLISHING, 
//   DWHAYWOOD MUSIC, YEAR OF THE DOG MUSIC and DARTH BUDDHA
//All Rights for HILLARY DAWN SONGS Controlled and Administered by EMI FORAY MUSICAll Rights for RADIOBULLETSPUBLISHING 
// and DWHAYWOOD MUSIC Administered by WARNER-TAMERLAND PUBLISHING CORP.

Example PDF by JotChord™

Here is the above example ChordText™ chart as a PDF generated by JotChord™.