chordsong

ChordSong is a simple text format for the notation of lyrics with chords, and an application that renders it to portable HTML pages. The use of HTML is more portable and convenient for different devices.

The file format specification is based on ChordPro (for directives), and the “standard notation” used by users in many guitar chords websites, such as ultimateguitar.com, lacuerda.net, or Cifra Club. A new diagram notation is also defined with the goal of provide complete freedom to define barres' shapes.

Why creating this software?

I was tired of web pages where you write the chord name and you have a set of chord diagrams to select, but often you don't find the exact one. Moreover, there is no way to define the exact barres in the chord, and often the exact shape is key to follow the chords progression.

I wanted a fast and responsive design showing the exact chords and diagrams in any device. I also wanted to be able to do it offline.

Usage

First write your song with chords as explained in Format specification.

You can render the source file to HTML either with a command-line tool or programmatically.

Command line

Just use npx to invoke the latest version of chordsong with:

npx chordsong

Usage: chordsong [options] <inputfile>

Options:
  -v, --version              output the current version
  -o, --output <outputfile>  set the output file name. If omitted the output
                             filename is the input one with the extension
                             switched to .html
  -r, --render-mode <mode>   select default render mode. Either 'chordName' or
                             'diagram' (default: "chordName")
  -t, --theme <theme>        force using a user-provided theme instead of the
                             default one.  Generate a directory at 
                             ./themes/<theme> with files 00-fonts.css, 
                             01-theme.css, 02-diagram.css, and index.html. You
                             may take themes/default dir as reference.
                             (default: "default")
  -h, --help                 display help for command

Programmatically

Just import/require and use this module and invoke the chordsong function:

/**
 * Returns the rendered song
 * @param text - the source contents
 * @param renderMode - can be used to overwrite the directive render-mode. Either 'chordName' or 'diagram'
 * @param theme - The theme to use
 * @param html - whether to output a complete html page or return {title, content, css}
 * @returns either the complete rendered html page with css embedded, or {title, content, css}
 */
const chordsong = (text: string, renderMode: RenderMode = 'chordName', theme: string = 'default', html: boolean = true): string | { title: string, content: string, css: string}

Format specification

The structure of the source file is as follows:

• directives
• chord diagrams
• lyrics with chord names above

Directives

The rendered output can be modified with the following directives:

• title:: the song title
• artist: the song artist
• columns: either a fixed number of columns or the string auto (default), which creates columns until filling the viewport.
• render-mode: how chords are displayed above the lyrics:
  • diagram: render chord diagram.
  • chordName (default): render just the chord name.
• lyrics-font-size: html font size for lyrics. Default value is inherited (check theme css). Examples are: medium, large, xx-large, 22px.
• lyrics-font-color: font colour. Default value is inherited (check theme css). Examples: red, #ffa5a5.
• chords-font-size: html font size for chord names (in chordName render-mode). Default value is inherited (check theme css). Examples are: medium, large, xx-large, 22px.
• chords-font-color: font colour. Default value is inherited (check theme css). Examples: red, #ffa5a5.
• comments-font-size: html font size for comments. Default value is inherited (check theme css). Examples are: medium, large, xx-large, 22px.
• comments-font-color: font colour. Examples: red, #ffa5a5.
• show-chord-diagrams: true ca be used to show a div with all the chord diagrams. It is useful in combination with chordName render-mode. Default value is false.

Custom directives added in the source file as {directive-title: directive-contenc} will be printed in the form “directive-title: directive-content”. Content can contain html code. Examples could be:

{tempo: 4/4 110 bpm}
{capo: 1<sup>st</sup> fret}

A minimum example for a song that we want to print in diagram mode could be:

{title: Cryptonite}
{artist: Supermanny}
{render-mode: diagram}

Chord diagrams

It is recommended to provide fret diagrams for the chords. The format is: <chordName>[:<variant>]\[diagram\] There are two ways to define the fret diagram of a chord:

1. (Classic) From string frets. Just write the fret pressed at every string from the sixth (thickest) to the first one (thinnest). Use x for muted strings, and 0 for an open string. Barre shapes are automatically computed based on typical use. Examples:
   • barre F: 132211
   • E: 022100
   • Cm: x35543
   • A: x02220
2. From fingers and barres. Expected input is a /-separated list of <fret>:<strings>, with strings a comma-separated list of strings pressed at that fret or barres in the format <stringFrom>-<stringTo>, e.g. 1-6. This input method provides a way to exactly define the shape of barres. Examples:
   • barre F: 1:6-1/2:3/3:4,5
   • E: 0:1,2,6/1:3/2:4,5
   • Cm: 3:1-5/4:2/5:3,4
   • A (pressing the 4th and 3rd with the same finger): 0:1,5/2:3-4,2

The chords should appear in your source file as, for example:

F[132211]
F:1[x87565]
E[022100]
Cm[x35543]
A[0:1,5/2:3-4,2]

If you want to use one name in the source file and to print a (likely greater) name on the diagram, you can add the optional long name after a |. For example, you can define the chord as:

CM7|Cmaj7[x32000]

And then use the shortest CM7 as the chord name, although Cmaj7 will be printed in the diagram

Lyrics with chord names

Standard text with the lyrics and immediately above the chord names. We can also create just instrumental lines.

Comments can also be added to the text, and will be printed in the html.

Example:

// Guitar only
Em(add9)  Ebdim
Cmaj7(9)/E     Em7(-5)/A#
A7      D7/F#      G7/F
G7sus/F   Cmaj7  G7(b9) G7

// Vocals are coming
   Cmaj7:1              C/E
Eu sei que vou te amar,
    Ebdim        Dm7                   G13
Por toda a minha vida eu vou te amar,
   G7:1      Gm7                   D7/F#
Em cada despedida, eu vou te amar
           Fmaj7     Bb9(#11)
Desesperadamente, eu sei que vou te amar

Example source file

{title: Eu sei que vou te amar}
{artist: Vinícius de Moraes, Toquinho e Maria Creuza}
{tempo: 4/4 84 bpm}
{comment: <a href="https://www.youtube.com/watch?v=Lv8LJUBlF2o&list=RDLv8LJUBlF2o">youtube video</a>}
{render-mode: diagram}
{show-chord-diagrams: false}
{columns: auto}
{lyrics-font-size: large}
{lyrics-font-color: rgb(64,64,64)}
{chords-font-size: small}
{chords-font-color: #0000ff}
{comments-font-size: small}
{comments-font-color: rgb(128,128,128)}

A7[x02020]
A7:1[x0565x]
A7(b13)[x0566x]
Bb9(#11)[x10110]
Cmaj7[x32000]
Cmaj7:1[x35453]
Cmaj7(9)/E[2:4/3:5,3-1]
Csus9/F[1x001x]
C/E[x7558x]
D7/F#[2x021x]
D9[x5355x]
Dm7[x57565]
Ebdim[x67575]
Em7(-5)/A#[x1x030]
Em(add9)[074007]
Fmaj7[1x221x]
G13[353453]
G7[32300x]
G7:1[353433]
G7:2[3x343x]
G7(b13)[3x344x]
G7(b9)[32310x]
G7/F[1x000x]
G7sus/F[1x001x]
Gm7[353333]


Em(add9)  Ebdim
Cmaj7(9)/E     Em7(-5)/A#
A7      D7/F#      G7/F
G7sus/F   Cmaj7  G7(b9) G7


   Cmaj7:1              C/E
Eu sei que vou te amar,
    Ebdim        Dm7                   G13
Por toda a minha vida eu vou te amar,
   G7:1      Gm7                   D7/F#
Em cada despedida, eu vou te amar
           Fmaj7     Bb9(#11)
Desesperadamente, eu sei que vou te amar

  Em(add9) Ebdim Dm7   G13   G7:1     
E cada     verso meu será       
    Cmaj7(9)/E A7(b13)  A7:1
pra te       dizer
       D9
que eu sei que vou te amar
    G7(b13)      G7:2
Por toda a minha vida

   Cmaj7:1             C/E
Eu sei que vou chorar
  Ebdim         Dm7                G13
A cada ausência tua eu vou chorar
    G7:1       Gm7               D7/F#
Mas cada volta tua há de apagar
                    Fmaj7         Bb9(#11)
O que esta ausência tua me causou

   Em(add9)           Ebdim
Eu sei que vou sofrer
               Cmaj7(9)/E     Em7(-5)/A#
A eterna desventura de viver
    A7        D7/F#            G7/F
A espera de viver ao lado teu
    G7sus/F      Cmaj7  G7(b9) G7
Por toda a minha vida

-----

- De tudo, ao meu amor seria atento antes
- E com tal zelo, e sempre, e tanto
- Que mesmo em face do maior encanto
- Dele se encante mais meu pensamento

- Quero vivê-lo em cada vão momento
- E em seu louvor, hei de espalhar meu canto
- E rir meu riso e derramar meu pranto
- Ao seu pesar ou seu contentamento

- E assim quando mais tarde me procure,
- quem sabe, a morte
- A angústia de quem vive,
- e a solidão no fim de quem ama

- Eu possa me dizer do amor que tive
- Que não seja imortal, posto que é chama
- Mas que seja infinito
- enquanto dure

-----

   Em(add9)           Ebdim
Eu sei que vou sofrer
               Cmaj7(9)/E     Em7(-5)/A#
A eterna desventura de viver
    A7        D7/F#            G7/F
A espera de viver ao lado teu
    G7sus/F      Cmaj7  G7(b9) G7
Por toda a minha vida

The above file will be rendered as:

More examples can be found in the examples directory.