The .gigchart file, in full

The envelope

{
  "format": "gigchart",     // always this literal
  "version": 6,             // current file version
  "savedAt": 1753228800000, // optional, ms epoch
  "song": { … }             // everything below
}

The smallest file that opens and renders:

{
  "format": "gigchart",
  "version": 6,
  "song": {
    "properties": { "title": "House of the Rising Sun", "artist": "Traditional" },
    "body": [
      "Am         C        D     F",
      "There is a house in New Orleans",
      "",
      "Am      C      D       F",
      "My mother was a tailor"
    ]
  }
}

version is the file format's version, not the song's. Write 5. Older files still load — the app migrates them — but new producers should emit the current shape. Unknown keys are ignored rather than rejected, so a file written against a later version still opens.

What song contains

properties — the song's identity

Free-text fields, all optional, all strings unless noted. These are the same values the ChordPro directives on the import page fill in — only the key spelling differs ({key: Am} here is originalKey).

Nothing here is printed just because it is set: the header prints what its title and subtitle templates ask for, and the info box prints the fields it is told to show. Setting album or copyright stores them for later without changing the page.

body — the chart itself

An array of lines: ["chord line", "lyric line", "", …]. One entry per line, no trailing newline, and an empty string separates stanzas. Two chord notations work, and they can be mixed:

• Chords above lyrics — a chord-only line whose columns sit over the syllable they change on, then its lyric line. Columns are what align, so this only works in a monospace font — which is exactly what GigCharts renders in.
• Inline — [Am]There is a [C]house. The renderer splits each such line into a chord row and a lyric row.

Stanzas, rows and gaps

Annotations don't point at characters; they point at stanzas, rows inside a stanza, and the gaps between stanzas. All three are 0-based and all three are counted the same way everywhere in the file:

stanza 0  ┌ row 0   Am         C        D     F        ← chord row
          │ row 1   There is a house in New Orleans  ← lyric row
          │ row 2   Am         C           E
          └ row 3   They call the Rising Sun
                                                     ← gapAfter 0
stanza 1  ┌ row 0   Am      C      D       F
          └ row 1   My mother was a tailor

• Stanza — a run of non-blank lines. Blank lines separate them; they aren't stanzas themselves.
• Row — a rendered row inside the stanza. A chord row and a lyric row are two rows, so in the usual chord-over-lyric chart the lyric rows are the odd indices (1, 3, 5…). A wrapped line adds rows. To skip the counting, add lineBasis: 'lyric' to a line/range target and line counts lyric lines only (0-based) — the app resolves it to the row on load.
• Gap — gapAfter: n is the boundary after stanza n; -1 is the space above the first stanza.

annotations — everything drawn over the music

A flat array. Each entry is one widget: what it is (kind), where it goes (target), and its own fields.

{
  "id": "a-cue-1",
  "kind": "cue",
  "text": "slower",
  "target": { "kind": "line", "stanza": 0, "line": 1 },
  "placement": "inline",
  "color": "#e23b3b"
}

Fields every annotation shares

Colors serialize as color — on annotations, on bar items and on voices. Leave a color out and the element follows the chart's theme, which is usually what you want.

Targets

Gap-scoped kinds — cue, road map, repeat-section mark, page break — are stored against a spacer once the app has loaded them. You don't have to build those: write { "kind": "gap", "gapAfter": n } and the app mints the spacer, gives it a sensible height, and rewrites the target on load.

The nine kinds

At most one section, repeat and capo per stanza — extras are dropped on load. Cues, marker groups and voices may stack freely.

The bar items of a road map or marker group

One of each

// A section spine over stanzas 1–2, in the left gutter
{ "id": "s1", "kind": "section", "text": "Verses 2–3",
  "target": { "kind": "span", "from": 1, "to": 2 },
  "placement": "left", "textDir": "left" }

// A two-line cue chip centered in the gap after stanza 1
{ "id": "c1", "kind": "cue", "text": "instrumental\nverse",
  "target": { "kind": "gap", "gapAfter": 1 },
  "placement": "inline", "color": "#1aa64b" }

// Play stanza 3 twice
{ "id": "r1", "kind": "repeat", "text": "2",
  "target": { "kind": "stanza", "stanza": 3 }, "placement": "inline" }

// Capo 5 from stanza 2 on
{ "id": "k1", "kind": "capo", "text": "5",
  "target": { "kind": "stanza", "stanza": 2 }, "placement": "above" }

// Two marker bars in the right gutter
{ "id": "m1", "kind": "markers",
  "target": { "kind": "stanza", "stanza": 1 },
  "placement": "right", "textDir": "left", "spacing": 1, "color": "#ef8a2b",
  "items": [ { "id": "b1", "label": "guitar", "repeat": 2 },
             { "id": "b2", "label": "shaker", "color": "#20b7d4" } ] }

// The arrangement, as a full-width block after the last stanza
{ "id": "rm1", "kind": "roadmap",
  "target": { "kind": "gap", "gapAfter": 3 },
  "align": "center", "roadmapWidth": "full", "color": "#7ac043",
  "items": [ { "id": "i1", "label": "Intro" },
             { "id": "i2", "label": "Verse", "repeat": 4 },
             { "id": "i3", "label": "Outro", "color": "#6c4bd1" } ] }

// "Repeat: Verse 1" in the gap after stanza 2, two rows tall
{ "id": "ch1", "kind": "recall",
  "target": { "kind": "gap", "gapAfter": 2 },
  "refStanza": 0, "placement": "inline", "reserveLines": 2 }

// Force a new page after stanza 1
{ "id": "pb1", "kind": "pagebreak", "target": { "kind": "gap", "gapAfter": 1 } }

spacers — vertical space as an object

A spacer is a block of empty rows at one boundary. It owns its height and hosts at most one gap-scoped annotation; several can stack at the same boundary. That's how a chart can have a three-row gap before the bridge, or a cue chip with room around it.

"spacers": [
  { "id": "sp-1", "after": -1, "reserveLines": 1 },  // above the first stanza
  { "id": "sp-2", "after": 0,  "reserveLines": 2 },  // a double gap after stanza 0
  { "id": "sp-3", "after": 1,  "reserveLines": 3 }   // hosts a 2-line cue chip
],
"annotations": [
  { "id": "c1", "kind": "cue", "text": "instrumental\nverse",
    "target": { "kind": "spacer", "spacerId": "sp-3" } }
]

• after — the boundary, numbered like gapAfter (-1 = above the first stanza).
• reserveLines — the block's height in body rows.
• hidden — kept in the file, reserving nothing.

voices — who sings what

A song owns its voices: name and color travel in the file, so the coloring survives on any machine. roster entries are { id, name, color }; annotations refer to them by voiceId. Use ids of the form v-001, v-002… (all is reserved for the built-in “All” voice).

"annotations": [
  // the whole second row of stanza 1 in Bea's color
  { "id": "v1", "kind": "voice", "voiceId": "v-001",
    "target": { "kind": "line", "stanza": 1, "line": 1 } },
  // just the first nine characters of row 3
  { "id": "v2", "kind": "voice", "voiceId": "v-002",
    "target": { "kind": "range", "stanza": 1, "line": 3, "from": 0, "to": 9 } }
],
"voices": {
  "roster": [
    { "id": "v-001", "name": "Bea",  "color": "#c45912" },
    { "id": "v-002", "name": "Atti", "color": "#2c5fd6" }
  ],
  "defaultVoiceId": null
}

defaultVoiceId is the song's default voice, or null. A range target's from/to are character columns in that row's text — count them in the line as you wrote it in body.

textStyles — italic and underline

Inline styling can't live in body — markup there would shift the monospace columns and pull the chords off their syllables. So it rides alongside, as character ranges over the body treated as one flat string (lines joined with \n, exactly as a text editor would count).

"textStyles": {
  "italic":    [[28, 59]],       // "There is a house in New Orleans"
  "underline": [[48, 59]],       // "New Orleans"
  "voice":     [[60, 84, "#c45912"]] // a raw color run (voices are better done as annotations)
}

i = italic, u = underline, v = colored runs. Ranges are half-open [start, end). They may cover chord rows too — usually you don't want that, so count carefully, or set styling in the app and save from there.

settings — how it is typeset

Grouped by function, and every group (and every key inside it) is optional. Omit a group and nothing about it changes.

"settings": {
  "typography": { "fontKey": "dejavu", "fontSizePt": 12, "layout": "vertical" },
  "header":     { "titleColor": "#2c5fd6" },
  "concert":    { "showConcert": true, "concertBoxMode": "page" }
}

Values are validated on load: an out-of-range enum falls back to a safe value instead of breaking the chart, and numeric ranges are clamped. So a wrong value doesn't destroy the file — it just quietly isn't what you asked for.

settings.page

Page geometry and the page-turn preview band. A chart carries its own page, so it opens the same size on any machine.

settings.typography

settings.labels

The printed wording of every prefixed field. House style — but it prints, so it travels with the song. Set any of them to '' to print the bare value.

settings.header

Title and subtitle are template-driven: each is an ordered list of { field } and { sep } tokens. An empty array means the default composition (title = artist – title).

settings.infoBox1

The meta box in the top corner. Each field shows only when the matching property has a value.

settings.bottomBox

settings.capo

The song-wide capo pill (the capo property is its value). Per-stanza capos are annotations instead.

settings.notation

settings.concert

The side column of concert-pitch chords, for a capo'd chart played with someone who isn't capo'd.

settings.annotations

palette — a color theme in the file

Optional, and only present when the song uses a custom theme (the four factory themes — Rainbow, Pastel, Muted, Grayscale — are not written into files). A palette is twelve editable swatches plus an assignment of each chart element to a swatch index.

"palette": {
  "id": "my-theme",
  "name": "My theme",
  "swatches": [ { "bg": "#e23b3b" }, { "bg": "#ef8a2b" }, … 12 in total … ],
  "assign": { "cue": 0, "section": 4, "roadmap": 3, "markers": 1 }
}

Assignable elements: title, subtitle, body, chord, capo, repeat, section, cue, markers, roadmap, pagebreak, chorus, concertbox, concertboxtitle, concertchords, infobox, bottombox, videolink, qr, pageturnborder, pageturnbg, pageturnnextborder, pageturnnextbg. Index 12 is the theme's rainbow swatch, valid only for elements with a solid fill.

Per-element colors on the chart are simpler to set directly (color on the annotation, titleColor in the header group) — reach for a palette only when you want a whole coordinated theme.

A complete song

Download the showcase file — one song using every element on this page: section spines, cues on a line and in a gap, a repeat bar, a per-stanza capo, a marker group, a road map, a chorus recall, line and word-range voices, inline styling, and every settings group. Open it in the app with Open file, take it apart, and copy what you need.

It's also the file this page was checked against: it was loaded into GigCharts and every element confirmed on the rendered page before any of this was written.

Rules of thumb

• Omit before guessing. An absent key means “use the default”. A wrong one means a chart that isn't what you meant.
• Start from the words. Get properties and body right, then add annotations. They anchor to stanzas and rows, so the body has to be settled first.
• Count stanzas from 0, and remember lyric rows are the odd row indices in a chords-above chart.
• Use gapAfter, not spacers, unless you specifically want an unusual gap height.
• Colors are color and hex. Leave them out to follow the theme.
• Page count is an outcome, not a setting. Font size, line spacing and page preset drive it; the final break depends on the render, so the author checks it in the app.
• Round-trip to be sure. Open the file in the app, adjust, then Save → .gigchart — what comes out is the canonical form of what you wrote.

Ready to hand one over? Build a one-click import link and the song opens straight in the studio.