| name | convert-chord-chart |
| description | Convert a standard chord chart (chords-over-lyrics text) into song2html format. Use when the user provides a chord chart, lyrics with chords above them, or asks to convert a song into song2html format. |
Convert Chord Chart to song2html
This skill teaches you how to convert a standard "chords-over-lyrics" text file into the song2html plain-text format.
Standard Chord Chart Input (typical formats)
Standard chord charts look like one of these:
Format A — Chords above lyrics (most common)
Amazing Grace
Key: G Tempo: 72 Time: 3/4
Author: John Newton
[Verse 1]
G C G
Amazing grace, how sweet the sound
G C G D
That saved a wretch like me
[Chorus]
C G D G
I once was lost, but now am found
G C G
Was blind, but now I see
Format B — Chords inline in brackets
Amazing Grace (G)
[Verse]
[G]Amazing [C]grace, how [G]sweet the sound
[G]That saved a [C]wretch like [G]me [D]
[Chorus]
[C]I once was [G]lost, but [D]now am [G]found
Format C — Nashville Number charts
Amazing Grace - Key of G
Verse: 1 4 1 5
Chorus: 4 1 5 1
V1: Amazing grace how sweet the sound / That saved a wretch like me
Ch: I once was lost but now am found / Was blind but now I see
Format D — Tab/chord sites (Ultimate Guitar, etc.)
[Intro] G
[Verse 1]
G C G
Amazing grace how sweet the sound
G C G D
That saved a wretch like me
Step-by-step Conversion Process
Step 1: Extract the title and key
Look for the song title and musical key. The key may appear:
- In parentheses after the title:
Song Name (G)
- On a "Key:" line
- In brackets:
[Key: G]
- Implied by the first chord
Write the title line:
Amazing Grace [G]
Step 2: Extract metadata
Gather author, tempo, time signature from the header area. Write as 2-space indented lines:
author: John Newton
tempo: 72
time: 3/4
Step 3: Extract chord progressions per section
For each section (verse, chorus, bridge, etc.), read the chord sequence in order of appearance. Deduplicate sections of the same type — Verse 1 and Verse 2 usually share the same chords.
From chords-over-lyrics like:
G C G
Amazing grace, how sweet the sound
G C G D
That saved a wretch like me
The chord progression is: G C G G C G D
But look for the repeating pattern. In a 3/4 song with 4 chords per line, this is likely: G C G D (one chord per measure). Use musical judgment — the progression for the section is usually 4–8 chords that cycle.
Write as 2-space indented definitions:
verse: G C G D
chorus: C G D G
Important rules:
- Section names are lowercase in chord definitions:
verse, chorus, bridge
- Multiple verses share one chord definition (matched by first word)
- If chords repeat with a pattern, use repetition:
(G C) x2 D G
Step 4: Write lyric sections with caret markers
This is the critical step. For each lyric section, place a ^ caret at the exact syllable where each chord change occurs.
Given chords-over-lyrics:
G C G D
Amazing grace, how sweet the sound
The chords align to specific syllables:
G → "Amazing" (start of line)C → "grace" (the comma area)G → "sweet"D → "sound"
Convert to:
^Amazing ^grace, how ^sweet the ^sound
Caret placement rules:
- Each
^ consumes the next chord from the section's chord progression
- Place
^ directly before the syllable/word where the chord sounds
- The
^ replaces the chord name — don't include the chord name in the lyrics
- Count your carets — they should match the number of chords in the progression (or the chords will cycle)
- If a chord sounds on empty space (no lyric), you can write
^ (caret then space)
Write under the Sections: header with 2-space indented names and 4-space indented lyrics:
Sections:
Verse 1:
^Amazing ^grace, how ^sweet the ^sound
^That saved a ^wretch like ^me
Chorus:
^I once was ^lost, but ^now am ^found
^Was blind, but ^now I ^see
Step 5: Add arrangements (optional)
If the chart specifies a song structure (e.g., V1 → C → V2 → C → Bridge → C), add:
Arrangements:
Full:
Verse 1
Chorus
Verse 2
Chorus
Bridge
Chorus
Complete Conversion Example
Input (standard chord chart):
How Great Thou Art
Key: Bb Time: 4/4 Tempo: 76
Writer: Carl Boberg
[Verse 1]
Bb Eb Bb
O Lord my God, when I in awesome wonder
Bb F Bb
Consider all the worlds Thy hands have made
[Verse 2]
Bb Eb Bb
I see the stars, I hear the rolling thunder
Bb F Bb
Thy power throughout the universe displayed
[Chorus]
Eb Bb F Bb
Then sings my soul, my Savior God to Thee
Eb Bb F Bb
How great Thou art, how great Thou art
Structure: V1, V2, Chorus, V1, V2, Chorus, Chorus
Output (song2html format):
How Great Thou Art [Bb]
author: Carl Boberg
tempo: 76
time: 4/4
verse: Bb Eb Bb Bb F Bb
chorus: Eb Bb F Bb Eb Bb F Bb
Sections:
Verse 1:
^O Lord my ^God, when I in ^awesome wonder
^Consider ^all the worlds Thy ^hands have made
Verse 2:
^I see the ^stars, I hear the ^rolling thunder
^Thy power ^throughout the ^universe displayed
Chorus:
^Then sings my ^soul, my Savior ^God to ^Thee
^How great Thou ^art, how great Thou ^art
Arrangements:
Full:
Verse 1
Verse 2
Chorus
Verse 1
Verse 2
Chorus
Chorus
Handling Tricky Cases
Chords that fall between words
If a chord sounds between two words, attach the caret to the word that follows:
Input: Am G C
She walks in beauty
Output: ^She walks ^in ^beauty
Chords on the same word (quick changes)
If two chords happen rapidly on one word, split it or attach to the nearest syllable:
Input: G C
Amazing
Output: ^Ama^zing
Lines with no chords
If a lyric line has no chords above it, write it without any carets:
This line has no chord changes
Instrumental sections
If a section has chords but no lyrics, you can either omit it or create empty caret lines:
Intro:
^ ^ ^ ^
Nashville Number conversion
If the original uses Nashville numbers, keep them — song2html supports them natively:
verse: 1 4 5 1
chorus: 4 5 6m 1
Different chords per verse
If Verse 1 and Verse 2 genuinely have different chord progressions (rare), define separate chord sections:
verse-1: G C D G
verse-2: Am C D G
Then name your lyric sections to match: Verse-1 1: and Verse-2 1:.
Workflow
- Read the input chord chart
- Identify title, key, metadata
- Identify all sections and their chord progressions
- For each section, align carets to where chords fall on lyrics
- Optionally define arrangements
- Use
song2html:validate_song to check for errors
- Use
song2html:write_song_file to save the result
- Optionally use
song2html:render_html to preview as HTML
