Skip to main content
GuitarGame_ChartFormats describes what games read, and what a program “should” or “may” do. This specification says what a valid file is, with Required and Recommended, and what a scanner does with each invalid form, so that every file reads the same everywhere. Where Clone Hero and YARG read a file differently, this specification follows one rule, and its pages give each game’s reading as an edge case. So many of the differences are of three kinds:
  • Rules: something GuitarGame_ChartFormats allows or recommends is required, recommended, deprecated or invalid here, or the reverse.
  • Corrections: GuitarGame_ChartFormats says a game does something it doesn’t, or no longer does.
  • Additions: this specification covers something GuitarGame_ChartFormats doesn’t.

​
Song folders

  • song.ini is required in every song folder: see Files in a song folder. GuitarGame_ChartFormats calls it common.
  • Only notes.chart and notes.mid are charts, in lowercase. A custom name, a [Y] or [F] suffix and .midi are invalid, since no game reads them. A folder with both charts uses notes.mid: see The chart.
  • Games find audio by its file name alone. [Song]’s MusicStream, GuitarStream and the other stream keys are ignored, and no game falls back on them: see Audio.
  • Every stem plays. A folder with drums and drums_1 plays both in Clone Hero and YARG; GuitarGame_ChartFormats says drums is ignored. A folder should hold only one of them.
  • preview and crowd audio are deprecated, and a folder holds one file for each audio name: see Deprecated.
  • Album art is recommended as album.png, at 512 by 512 pixels. Several background images are allowed, and a game shows one at random. video.webm is the recommended video. The cover, background and video keys of song.ini are read by YARG alone. See Art and video.
  • Additions: the .sng format, and the charting guidelines.

​
song.ini

  • [Song] doesn’t fill gaps in song.ini. When song.ini loads, a scanner takes the song’s text metadata from it alone, even for a key it leaves out. [Song]’s Offset, PreviewStart and PreviewEnd are read only when song.ini doesn’t set delay, preview_start_time or preview_end_time, and the two files must agree: see [Song]. GuitarGame_ChartFormats prefers song.ini key by key.
  • Deprecated keys: delay, hopo_frequency, eighthnote_hopo, multiplier_note, frets and track. end_events and hopofreq are ignored. pro_drum and star_power_note are older names, read only when the main key has no line. sustain_cutoff_threshold stays standard, though a new chart should leave it out. See Settings and Metadata.
  • Values are stricter: see Syntax. A blank value and -1 are invalid, and read as a missing key: to leave a value unset, leave its key out. A comment starts with ;, and # is invalid. No key takes a decimal number. Recommended: True and False for booleans, which are the only booleans in a .sng file.
  • delay with a decimal point is invalid, and read as seconds, as Clone Hero reads it: delay = 1.5 is 1500 milliseconds. See Settings.
  • year is the album’s year, and Year = "2002" is the recommended [Song] form. The , before it stays valid.
  • Additions: preview_end_time, part credits, explicit_lyrics, diff_keys_ghl, chord_snap_threshold, ignored_issues, the keys only YARG reads, and how style tags show.

​
.chart files

  • The layout is required, where GuitarGame_ChartFormats describes what readers accept: see Syntax. [Song] comes first and [SyncTrack] second. A section’s header, { and } each stand alone on a line. One space separates the parts of a line. Numbers have no sign. Names match in exact letter case. A section name appears once, and a scanner reads the first copy.
  • Ticks never go backwards in a section. GuitarGame_ChartFormats recommends it; Clone Hero refuses a file that breaks it.
  • A tempo marker and a time signature at tick 0 are recommended, not required. Without them, a chart plays at 120 BPM and 4/4 until its first marker, in every game: see The start of the chart.
  • Text events are written without square brackets in both formats, such as E section Intro, and brackets stay valid: see [Events].
  • end comes at least a beat after the last note, and a chart has at most one. See The end of the song.
  • prc_ section names are deprecated: write section.
  • Ignored: versus phrases, S 0 and S 1; H events; and the [Song] keys of older tools.
  • Additions: a flam, N 109, and range shifts, E ld_range_shift. Both extend the .chart format itself, where GuitarGame_ChartFormats advises a new file extension for any extension.
  • Additions: the byte order marks, the ISO-8859-1 fallback, and the white space a scanner trims, on Syntax, and the five steps of How notes resolve, with chord snapping.

​
Phrases

  • On 5-fret, S 64 at or after the coda is a Big Rock Ending, S 65 a tremolo lane and S 66 a trill lane, as notes 120, 126 and 127 are in a .mid file. GuitarGame_ChartFormats has lanes on drums only. See Phrases.
  • A lane covers its end tick, and lanes may overlap.
  • A .mid lane has four velocity tiers: 21 to 30 on every difficulty, 31 to 40 on Medium and up, 41 to 50 on Hard and up, and any other velocity on Expert alone. See Lanes.
  • A Big Rock Ending needs only note 120. Notes 121 to 124 are optional, and span the same ticks as 120. See Drum fills.
  • Solos read as star power only in a track with two or more solos and no star power note, on 6-fret too. multiplier_note is deprecated: see Solos.
  • Additions: every phrase covers a note, and one of length 0 covers the notes on its tick; what scanners do with overlapping phrases, nested solos and empty ones.

​
.mid files

  • A track has one name, a track name event as its first event at tick 0, in capitals: see Track names. Clone Hero names a track by its last name at tick 0, not its first. An instrument has at most one track, and with two, the first counts.
  • Text is FF 01, in UTF-8, in EVENTS and instrument tracks. GuitarGame_ChartFormats counts every meta event from FF 01 to FF 0F as text, which no reader does. Lyrics are FF 05, or FF 01: see Text.
  • Square brackets around text events are optional, and the recommended form has none, which reverses GuitarGame_ChartFormats’ advice. A range shift keeps its brackets. See EVENTS track.
  • Note pairing is new: at a shared tick, the note-off comes first. Overlapping notes of one number are invalid, and read as Clone Hero reads them.
  • Running status kept across meta and SysEx events is valid, since every reader keeps it. GuitarGame_ChartFormats calls it a fault.
  • The header’s track count must match the tracks, and a scanner reads every track anyway. GuitarGame_ChartFormats calls the count metadata only.
  • A Phase Shift SysEx event counts only at exactly 8 bytes: see The Phase Shift SysEx event.
  • A tap covers its end tick, as GuitarGame_ChartFormats says. YARG doesn’t tap a note there, so an exporter keeps notes off that tick: see Taps.
  • T1 GEMS and PART DRUM are deprecated, and the BEAT track is ignored.

​
Drums

  • A scanner decides the drum type in one fixed order, pro before 5-lane: see Drum types. pro_drums = False means the same as no key, and five_lane_drums = True with pro_drums = True is invalid, and reads as 5-lane.
  • A .mid tom marker makes a chart pro only when it covers a note: see Drum types.
  • Sustained notes don’t make a chart 5-lane in any game, and a drum note’s length has no effect.
  • Kicks have no accents or ghosts, in either format.
  • A double kick, N 32, is recommended only in ExpertDrums, and N 0 with N 32 at one tick is invalid.
  • The recommended disco flip spelling is mix 3 drums0d, without brackets. Other spellings read as Clone Hero reads them, and a missing configuration digit isn’t “no stems”. A dnoflip while a d flip is on is invalid, and easy and easynokick are ignored. See Disco flip.

​
Vocals

  • PART HARMn names are deprecated: write HARM1 to HARM3, in order. See Vocals and harmonies.
  • A phrase holds notes and lyrics through its end tick, unless the next phrase starts there.
  • Each 106 phrase matches a 105. Note 97 is ignored, and [range_shift] text is deprecated.
  • Only Clone Hero’s formatting tags go in angle brackets in a lyric, so <whistle> is invalid.

​
Hashes

GuitarGame_ChartFormats doesn’t cover hashes. This specification adds BTrack and TrackHash, SongHash, and the obsolete BTrack 20240320.

​
Not covered

This specification covers the song folders that Clone Hero and YARG play. GuitarGame_ChartFormats also documents Phase Shift, Rock Band, Guitar Hero 1 and 2, Frets on Fire X, Editor on Fire and DJ Hero, and the .mid tracks of pro guitar, pro keys, real drums and venue. A scanner ignores those tracks: see Ignored.