Newton's Preposterous Miscalculation

    chordsong
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.3 • Public • Published

    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 name <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}, and will be printed in the form “title: 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]
    

    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 as comments in the html. Comments cannot be provided inline, and the comments line must start with //.

    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:

    example

    More examples can be found in the examples directory.

    Install

    npm i chordsong

    DownloadsWeekly Downloads

    14

    Version

    1.0.3

    License

    MIT

    Unpacked Size

    277 kB

    Total Files

    33

    Last publish

    Collaborators

    • juanelasisme