ChordSong is a simple text format for the notation of lyrics with guitar chords, and an application that renders them to portable HTML pages.
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.
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.
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
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}
The structure of the source file is as follows:
The rendered output can be modified with the following directives:
title:: the song titleartist: the song artistcolumns: 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}
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:
x for muted strings, and 0 for an open string. Barre shapes are automatically computed based on typical use.
Examples:
/-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:
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
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
{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.
FAQs
ChordSong is a simple text format for the notation of lyrics with guitar chords, and an application that renders them to portable HTML pages.
We found that chordsong demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Node.js will be enforcing stricter semver-major PR policies a month before major releases to enhance stability and ensure reliable release candidates.
Security News
Research
Socket's threat research team has detected five malicious npm packages targeting Roblox developers, deploying malware to steal credentials and personal data.
Security News
vlt introduced its new package manager and a serverless registry this week, innovating in a space where npm has stagnated.