# ChordPro and chords over lyrics

Songstead reads text charts in two formats, and you can mix them in the same chart. Either way, Songstead stores the chart exactly as you wrote it and works out the chords each time it shows it.

## Chords over lyrics

Chords over lyrics is the format most websites use, including Ultimate Guitar. Each line of chords sits above the line of lyrics it goes with, and each chord is lined up over the syllable where it changes.

```
[Verse 1]
G              C          G
Amazing grace, how sweet the sound
                         D
That saved a wretch like me
```

Spacing matters in this format, because the column a chord sits in is where it falls in the lyric. A line of chords with no lyrics under it, like an intro, is kept as a line of chords.

## ChordPro

ChordPro puts each chord in square brackets inside the lyric, just before the syllable it falls on.

```
{start_of_verse: Verse 1}
[G]Amazing grace, how [C]sweet the [G]sound
That saved a wretch like [D]me
{end_of_verse}
```

ChordPro doesn't depend on spacing, so a chart stays correct in any font and at any width.

You can switch how either format is shown with **Chord Position** in [Appearance](https://songstead.app/docs/appearance.md): above the lyrics or inline with them.

## Section headers

A label in square brackets on a line of its own starts a section. Songstead shows it as a header and uses it to find its place in [Live Mode](https://songstead.app/docs/live-mode.md) and [autoscroll](https://songstead.app/docs/autoscroll.md).

```
[Intro]
[Verse 1]
[Chorus]
[Bridge]
```

Any label works, as long as it's the only thing in brackets on the line and isn't a chord name. A section called `[A]` would be read as an A chord, so call it `[Part A]` instead.

ChordPro's section directives work too: `{start_of_verse}`, `{start_of_chorus}`, `{start_of_bridge}`, `{start_of_tab}` and `{start_of_grid}`, each closed by its `end_of_` partner. A label after the colon, as in `{start_of_verse: Verse 2}`, becomes the header. Without one, the header is Verse, Chorus, Bridge, Tab or Grid.

## Directives

A directive is a ChordPro instruction in curly braces on its own line. These are the ones Songstead acts on:

| Directive | What it does |
| --- | --- |
| `{title: ...}`<br>`{t: ...}` | The song's title. Read into the song's details on import. |
| `{artist: ...}` | The artist. Read into the song's details on import. |
| `{tempo: ...}` | The tempo in beats per minute. Read into the song's details on import. |
| `{time: ...}` | The time signature, like `3/4`. Read into the song's details on import. |
| `{duration: ...}` | The song's length. Read into the song's details on import. |
| `{comment: ...}`<br>`{c: ...}` | A comment shown in the chart, like "Build" or "Drums only". |
| `{comment_italic: ...}`<br>`{ci: ...}` | A comment in italics. |
| `{comment_box: ...}`<br>`{cb: ...}` | A comment in a box. |
| `{key: ...}` | A key change partway through the song. Shown as a comment, and transposed with the rest of the chart. |
| `{copyright: ...}` | Shown at the bottom of the chart, such as a CCLI number. |
| `{start_of_chorus}`<br>`{soc}` | Starts a chorus. `{eoc}` ends it. |
| `{start_of_verse}`<br>`{sov}` | Starts a verse. `{eov}` ends it. |
| `{start_of_bridge}`<br>`{sob}` | Starts a bridge. `{eob}` ends it. |
| `{start_of_tab}`<br>`{sot}` | Starts a block of tab, kept exactly as written. `{eot}` ends it. |
| `{start_of_grid}`<br>`{sog}` | Starts a chord grid. `{eog}` ends it. |

Directives Songstead doesn't recognize are kept in the chart and not shown.

Comments can be hidden with **Display** in [Appearance](https://songstead.app/docs/appearance.md), which is useful when you want only chords and lyrics on screen.

[Annotations](https://songstead.app/docs/annotations.md) do a similar job without changing the chart. A comment is part of the chart's text, so everyone who opens the chart sees it. An annotation sits on top of the chart, on your personal layer or a group's layer. It works on PDF and image charts too, and it can be a drawing, a stamp or a recording as well as text.

## OnSong headers

A chart that starts with plain lines for the title and artist followed by lines like `Key: G` or `Tempo: 72`, the way OnSong writes them, is read as the same information as the matching directives.

## Chords Songstead understands

Songstead reads standard chord names, including sharps and flats, minor and major sevenths, suspended and added chords, extensions like 9, 11 and 13, altered chords, diminished and augmented chords, and slash chords like `G/B`. How they are drawn can be changed in [Chord display](https://songstead.app/docs/chord-display.md).