ScoreHero Wiki : GHFileFormatDetails

ScoreHero :: Forums :: HomePage :: Categories :: UserIndex :: PageIndex :: RecentChanges :: RecentlyCommented :: Login/Register

Guitar Hero MIDI and VGS File Details v1.3

by Mike Perry (mj-perry@insightbb.com)

October 13, 2006


1. Summary


The game related files used during each song consist of a multi-track audio file and a standard MIDI file containing event information that is processed in sync with audio playback. The audio files contain interleaved tracks for the lead guitar stream and the backing band stream. The MIDI files contain information about time signatures, tempos, guitar notes and other time based events. The audio track is used as the time base for processing the events contained in the MIDI file so that the event processing does not go out of sync with the audio.

2. ARK Files


All game content is contained in the ARK file Main_0.ARK. An ARK is a set of concatenated files very similar to a tar ball. The files contained in the ARK are not encrypted in any way. A separate header file describes the contents of the ark and provides a rudimentary means of looking up file entries using directory and file names.

3. ARK Header


The ARK header file contains information about each file contained in the ARK. Each file in the ARK has a corresponding file entry in the header file which specifies the file offset within the ARK and the file size. The ARK header file format is as follows:

Note: all numeric fields are 32-bit little endian format.

0x00: 0x03 0x00 0x00 0x00 (3, unknown, possibly major version)
0x04: 0x01 0x00 0x00 0x00 (1, unknown, possibly minor version)
0x08: 0x01 0x00 0x00 0x00 (1, unknown, possibly revision number)
0x0C: size of ARK file in bytes
0x10: size of string table in bytes
0x14: String Table (section1)
0x14 + sizeof(section1): Number of 32-bit string offsets in section2 (section2_size32)
0x14 + sizeof(section1) + 4: String pointers (section2)
0x14 + sizeof(section1) + 4 + sizeof(section2): Number of file entries in section3
0x14 + sizeof(section1) + 4 + sizeof(section2) + 4: File entries (section3)


Section1



Section1 is simply a string table containing null-terminated strings representing directory names and file names.

Section2



Section2 is an array of 32-bit values that are used as byte offsets into Section1 for obtaining strings corresponding to a directory name or file name. Example: if a 32-bit value in section2 is 0x1234000 and section1 starts at offset 0x18 then the corresponding string location is 0x12340000+0x18 = 0x12340018.

Section3



Section3 is an array of file entries. There is one file entry for every file contained in the ARK file. Each file entry consists of five 32-bit fields as follows:

offset 0x0: file offset within ARK file
offset 0x4: filename string ID
offset 0x8: directory string ID
offset 0xC: file size in bytes
offset 0x10: 0x00000000 (unknown, possibly specifies which ARK contains file if more than one ARK file is present)

Each file offset specifies the starting byte offset of the file with the ARK. The file size specifies the length of the file in bytes. The string IDs are used as indexes into section2 to obtain offsets to strings in section1.

File Lookup



In order to load a file by file name, the array of file entries in section3 must be traversed, working backwards from section3 to section2 to section1 in order to obtain the strings associated with each file entry. The obtained strings must be compared to the desired string constants. If they match, the appropriate file entry has been found. If they do not match, the remaining file entries must be processed until a match is found or all entries have been searched.


4. VGS Files


The audio file for each song is variant of VAG called VGS. The VGS format is similar to standard PS2 VAG audio files in that VGS files consist of a very simple header followed by sample data in the standard XA ADPCM format natively supported by the SPU2. Each VGS file used by GH1 contains four interleaved tracks. The first two tracks consist of left and right channel data for the backing band audio stream. The third and fourth tracks consist of left and right channel data for the lead guitar audio stream. The VGS header specifies the playback rate and the sample block count for each stream. In GH1, all four streams have the same number of sample blocks and are played back at 44100 Hz. Sample data immediately follows the header. Sample blocks for each track are interleaved in a round robin fashion to facilitate streaming with no seek penalty. The XA sample blocks can be decoded using standard XA decoding algorithms with the exception that looping is not supported. The VGS format uses the three flag bits to indicate the track number associated with each sample block. The benefit of this is not known because the sample blocks are always interleaved in the order [0,1,2,3,0,1,2,3,0,1,2,0,...,3].

Guitar Hero 2 uses VGS files with the same format as Guitar Hero. The difference is that GH2 uses separate VGS files for single player mode and co-op mode. The single player GH2 VGS file is identical to that of GH1. The co-op mode VGS file format is identical to the single player GH2 VGS file format except that there are six interleaved tracks instead of four. The first two tracks contain the left and right channel data for the vocals and backing band sans one of rhythm guitar or bass. The third and fourth tracks contain the left and right channel data for the lead guitar stream. The fifth and sixth tracks contain the left and right channel data for the second player instrument which is either bass or rhythm guitar depending on the particular song. Note that only one VGS file exists if the corresponding band has only two guitarists corresponding to the lead guitar and coop guitar parts. In this case the VGS file will contain separate streams for the band and two guitars.

VGS Header



The VGS header is 128 bytes in length. All numeric fields are 32-bit integers in little endian format.

0x0: 0x56 0x67 0x53 0x21 ("VgS!")
0x4: 0x02 0x00 0x00 0x00 (2, unknown, possibly version number)
0x8: Stream info, channel 0
0xC: Stream info, channel 1
0x10: Stream info, channel 2
0x14: Stream info, channel 3
0x18: Stream info, channel 4 (if present)
0x1C: Stream info, channel 5 (if present)
0x20 - 0x7F: zeroes
0x80: start of interleaved XA blocks

Stream info:

offset 0x0: sample rate (little endian, 32 bits)
offset 0x4: number of XA blocks in file (little endian, 32 bits)

Stream Mapping



GH1:

Stream 0: Band, left channel
Stream 1: Band, right channel
Stream 2: Lead guitar, left channel
Stream 3: Lead guitar, right channel

GH2:

Stream 0: Band, left channel
Stream 1: Band, right channel
Stream 2: Lead guitar, left channel
Stream 3: Lead guitar, right channel
Stream 4: Coop guitar, left channel
Stream 5: Coop guitar, right channel

Encoding Process



The simplest way to encode a VGS file is to re-encode WAV files as standard PSX VAG files and then write a utility program to take four to six VAG files and splice the data together with a generated header. Code for encoding VAG files is available via the web.

It is a good idea to normalize all audio files prior to encoding. If the normalized audio sounds quieter than the non-normalized audio then this is an indication that clipping will occur on the non-normalized audio and that the normalized audio will sound very quiet in the game due to AGC-like behavior in the SPU2 sound processing. This is usually due to loud vocals but could occur due to any mismatch in recording levels in combined tracks.

5. MIDI Files


Each song has a corresponding MIDI file containing event data to be processed during audio playback. These MIDI files are always type 1 MIDI files consisting of multiple tracks that are processed simultaneously using the same time base. The timestamps associated with each event are in units of delta pulses from the previous event. GH1 and GH2 appear to use a constant pulse rate of 480 pulses per quarter note in all MIDI files.

The tracks contained in the GH MIDI files are:

Track 0: Tempo and time signature events
Track 1: Lead guitar note events, gameplay related events and events for animating the singer mesh
Track 2: Hand animation events for animation the hands and fingers of the lead guitarist
Track 3: Trigger events (for controlling stage lighting and other effects?)
Track 4: Band animation events (e.g. "bass_off", "drum_allbeat")

The order of the tracks is not consistent between files. Track 0 is always the tempo map as is standard for type 1 MIDI files. Track 1 is always the "T1 GEMS" track containing the guitar note events. The triggers, hand map and band animation tracks may follow track 1 in any order.

The tracks contained in the GH2 MIDI files are:

Track 0: Tempo and time signature events
Track 1: Lead guitar note events (single player mode)
Track 2: Lead guitar note events (co-op mode)
Track 3: Rhythm/Bass note events (co-op mode)
Track 4: Animation events for singer
Track 5: Animation events for bassist
Track 6: Animation events for drummer
Track 7: Events for venue lighting and song section names
Track 8: Trigger events

Tempo track



Track 0 contains time signature and tempo events. The first event in this track is a Track Name event. The track name is a compact form of the song name, e.g. "breakingwheel" for The Breaking Wheel. Tempo and time signature events follow the Track Name event. The time signature events always have a denominator of four. It is unknown if the game treats time signatures with numerators greater than four as having denominators of eight such that a time signature of 6/4 is treated as 6/8. Tempo is always described relative to a beat unit of a quarter note so the interpretation of time signatures is only important when drawing the beat guidelines over the playfield and when calculating star power usage. Time signature events by defintiion always occur at measure boundaries. Tempo events may occur multiple times within a measure and on any pulse.

Lead guitar track (GH1)



Track 1 contains only events that affect gameplay. The exception to this rule is that Track 1 also contains events guiding the animation of the singer's mouth. Note-on and Note-off events are the only MIDI event types that are valid in this track other than the first event which is always a Track Name event with a track name of "T1 GEMS". Each gameplay event is allocated a MIDI note number where the note letter specifies the type of event and the note octave specifies the difficulty level to which the note applies. Each note event applies to a single difficulty level except for the vocal track events which apply to all difficulty levels. The note number mapping is as follows:

60: guitar note GREEN, easy (C)
61: guitar note RED, easy (C#)
62: guitar note YELLOW, easy (D)
63: guitar note BLUE, easy (D#)
64: guitar note ORANGE, easy (E)
67: star power group, easy (G)
69: player 1 section, easy (A)
70: player 2 section, easy (A#)
72: guitar note GREEN, medium (C)
73: guitar note RED, medium (C#)
74: guitar note YELLOW, medium (D)
75: guitar note BLUE, medium (D#)
76: guitar note ORANGE, medium (E)
79: star power group, medium (G)
81: player 1 section, medium (A)
82: player 2 section, medium (A#)
84: guitar note GREEN, hard (C)
85: guitar note RED, hard (C#)
86: guitar note YELLOW, hard (D)
87: guitar note BLUE, hard (D#)
88: guitar note ORANGE, hard (E)
91: star power group, hard (G)
93: player 1 section, hard (A)
94: player 2 section, hard (A#)
96: guitar note GREEN, expert (C)
97: guitar note RED, expert (C#)
98: guitar note YELLOW, expert (D)
99: guitar note BLUE, expert (D#)
100: guitar note ORANGE, expert (E)
103: star power group, expert (G)
105: player 1 section, expert (A)
106: player 2 section, expert (A#)
108: vocal track (C)

Star Power events



A star power group note-on event indicates the start of a star power group and a star power note-off event indicates the end of a star power group. Each note within the star power group is considered to be a star power note. Star power is awarded when the last note in the group is played which may be significantly earlier than when the star power group note-off event occurs.

Player Section events



A player section event acts as a toggle that activates and deactivates the two players in a given section of the song when playing multiplayer. A note-on event activates the selected player and a note-off event deactives the selected player. At least one of the two players will be active at any given time. Notes will only be rendered in the playfield for the currently selected players and the controller input will be ignored for deactivated players. Both players may be active at the same time in which case both players see the same notes on their respective playfields.

Vocal Track events


A single note number is allocated for the purposes of animating the mouth of the singer mesh. A note-on event specifies that the mouth should transition to the open position. A note-off event specifies that the mouth should transition to the closed position.

Guitar note events



Guitar note events make up the bulk of the events found in the first track. The guitar note event inforamtion is used to render the playfield, determine whether the player has played a note correctly and to calculate scoring. Due to the use of a midi guitar interface to capture performance data (or the use of an audio stream analysis tool to extract note delimiters), the process of calculating chord groupings and note durations is somewhat complex.

Every note has a duration measured in pulses. In the game, any note with a duration greater than or equal to an eighth note (240 pulses) is considered to be a sustained note that allows hold points to be awarded. Notes with durations less than 161 pulses are considered to be non-sustained notes that do not award sustain points. All valid non-sustained notes must have a corresponding note-off event that specifies the end of the note. Some files may contain note data which does not follow this rule. The game treats these notes as invalid and they are neither rendered nor processed. Note-off events are not required for sustained notes. The end of a sustained note is also implied by the note-on event of the next note-on event corresponding to a guitar note.

The smallest separation between notes found in GH1 is 30 pulses. If consecutive note-on events are separated by less than 30 pulses (or possibly less than 15 pulses), all of the notes are considered to be part of the same chord. Some files do contain chords where the note-on events are separated by one pulse. This must be taken into account when determining whether or not the controller button states are congruous with a correctly played or sustained chord.

Guitar note processing rules



1) Note-on events indicate the start of a guitar note
2) The end of a note is indicated by a corresponding note-off event or by another note-on event, both occurring at a non-zero number of pulses after the start of the first note-on event
3) The pulse duration of a note is determined by subtracting the timestamp of the note-on event from the corresponding endpoint event.
4) Notes with a pulse duration shorter than 240 pulses are considered to be non-sustained notes
5) Valid non-sustained notes must have a corresponding note-off event. If a note endpoint is a second note-on event and the duration of the note is less than 161 pulses, the game considers the note to be an invalid note and it is ignored for all purposes (as exhibited by Cheat on the Church)
5) If a player section note-off event occurs more than 15 (30?) pulses prior to the endpoint of a sustained note, the sustained note is ignored by the game for all purposes, even in single player mode (as exhibited in the solo of You Got Another Thing Comin')
6) At any given time stamp, note-off events will be placed before note-on events. Duplicate note-on and note-off events within the same timestamp are ignored for purposes of determining note endpoints. In this case, the term "duplicate" means a situation where a note-on or note-off event specifies the same note-number as a prior event occurring at the same timestamp.

Lead guitar track (GH2)



The format of the lead guitar track in GH2 is a superset of GH1 with the exception that the lead guitar track no longer contains a vocal track for animating the singer's mouth (note number 108) and the track name has been changed to "PART GUITAR". Additionally, instances of note number 110 (D) are now present. These notes tend to be quite sparse and very short in duration. The meaning of this new note number is not known. This track also contains note events that control the guitarists hand animations. These note events are equivalent to the note events that are stored in the separate ANIM track of GH1 midi files discussed later.

The track may also contain text events which control character animation states. The known states are:

[idle]: guitarist plays idle animation (e.g. Judy Nails hands-on-hips stance)
[play]: guitarist moves to playing stance
[solo_on]: solo animation state
[solo_off]: solo animation state off
[wail_on]: wail state on
[wail_off]: wail state off
[half_tempo]: unknown (possibly controls the speed of tempo driven animation states)
[normal_tempo]: unknown (possibly controls the speed of tempo driven animation states)
[map HandMap_Default]: default fret hand animation mapping
[map HandMap_DropD2]: drop D2 fret hand animation mapping
[map HandMap_NoChords]: fret hand animation mapping that guarantees no chords are formed

This track is only used in single player mode.

Lead guitar co-op track (GH2)



The format of the lead guitar co-op track is identical to the lead guitar track format. The only difference is the track name which is changed to "PART GUITAR COOP". This track is only used in co-op mode.

Rhythm/bass track (GH2)



The format of the rhythm/bass track is identical to the lead guitar track. The only difference is the track name which is changed to "PART RHYTHM" or "PART BASS" as appropriate. This track is only used in co-op mode.

Singer animation track (GH2)



This track contains text events that control the animation state of the band singer. The known animation states are:

[idle]: singer plays idle animation
[play]: singer plays active singing animation

The track name is "BAND SINGER".

Bassist animation track (GH2)



This track contains text events that control the animation state of the band bassist. If the co-op track is rhythm guitar, this track will also contain fret hand animation note data for the bassist in the same format as the lead guitar track. The known animation states are:

[idle]: bassist plays idle animation
[play]: bassist actively plays instrument

The track name is "BAND BASS". This track is not present if the co-op track is bass. If the track is not present then the bassist hand animation data will be obtained from the PART BASS track.

Drummer animation track (GH2)



This track contains text events that control the animation state of the band drummer. Note events controlling the drummer's snare hand are also present. The snare drum note events are specified using note number 36 (C). The known animation states are:

[idle]: drummer is idle
[play]: drummer is active
[normal_tempo]: drummer plays bass drum on first and third beats
[half_time]: drummer plays bass drum on first beat only
[double_time]: drummer plays bass drum in eighth note pattern
[allbeat]: drummer plays bass drum in quarter note pattern

Event track (GH1)



The event track contains meta events with strings that describe animation states that affect movement behavior of the various band members including the lead guitarist. The first event of the event track is always a Track Name event with a track name of "EVENTS". All subsquent events are meta events with strings specifying an animation state for one of the band members. The known animation states are:

Singer:

sing_off: singer is at rest
sing_on: singer moves around

Guitarist:

gtr_off: guitarist is at rest
gtr_on: guitarist moves around
solo_on: solo animation
solo_off: transition back to normal
wail_on: fast playing, holds guitar in different position, change of stance, etc
wail_off: transition back to normal

Bassist:

bass_off: bassist is at rest
bass_on: bassist moves around

Keyboardist:

keys_off: keyboardist is at rest
keys_on: keyboardist moves around

Drummer:

drum_off: drummer is at rest
drum_on: drummer moves around
drum_half: drum at rate that is half as fast as the beat
drum_double: drum in double time (twice as fast as the beat)
drum_normal: normal rock drum pattern (snare on every other beat?)
drum_allbeat: snare drum on all all beats

Markers:

chorus: start of chorus
verse: start of verse
solo: start of solo
end: end of song/track

Event track (GH2)



The contents of this track are text events describing lighting states and song section names. The known text events are:

[lighting ()]
[lighting (flare)]
[lighting (blackout)]
[music_start]
[section <SECTION>]
[verse]
[chorus]
[solo]
[end]

The [section] text event is used to mark the beginning of a specific section of the song for use in the practice mode of GH2. Each section text event contains a string of the form "[section <SECTION_NAME>]" where <SECTION_NAME> is a unique section id string such as "solo_1a", "verse_1", or "solo_3b".

Triggers track (GH1)



The contents of this track are not known. The first event is a Track Name event with a track name of "TRIGGERS". The remaining events are note-on and note-off events with note numbers of 60 and 61 being the only valid pitches. Presumably the events trigger the animation of venue objects. It is known that the speaker cones animate according to the data in this track.

Triggers track (GH2)



The contents of this track are not known. The first event is a Track Name event with a track name of "TRIGGERS". The remaining events are similar to the note events in the GH1 trigger track with the difference being that the note numbers have changed and have been greatly increased. The valid note numbers for GH2 trigger events are 24, 25, 26, 48, 49, 50 and 61. It is likely that 60 is also valid but the GH2 demo does not contain any trigger tracks using this note number.

Animation track (GH1)



This track contains events used to control the animation of the hands of the guitarist. The first event is a Track Name event with a track name of "ANIM". The remainder of the events are either meta events with strings specifying a stock animation state or note-on and note-off events specifying song specific animation behavior. Standard animation state strings include "HandMap_DropD2" and "HandMap_Default" which map the animation note events to specific fret hand animations. The note-on and note-off events control the position of the guitarist's fret hand above the guitar neck and the position and activity of the fret hand fingers. Valid note numbers range from 40 (E) to 57 (A).

The data in the animation track only controls the position of the fret hand above the neck. The finger positioning and finger movement is derived from the note events in the T1 GEMS track corresponding to expert difficulty. The mapping of note events to positions on the neck is normally a linear mapping with note 40 representing the highest possible playing position near the bridge and note 57 representing the lowest playing position near the nut. The only quirk in the animation logic is that the mapping of note numbers to neck positions appears to invert when switching from chords to single notes and vice versa. This can make it somewhat difficult to create accurate animation data, especially when a section of a song consists of single notes mixed together with chords. Fortunately, if there are no active note events in the animation track at the start of a note-on event in the expert track, the animation will occur at the last specified hand position or a default position if none was specified. The entire animation track can be empty and the hand animations will be perfect, albeit played at a default position over the neck near the seventh fret.

Animation track (GH2)



There is no separate track for the guitarist animation in GH2. The note data for animating the guitarist is included directly in the PART GUITAR and PART GUITAR COOP tracks. Similar animation data for the second player exists in the PART RHYTHM and PART BASS tracks. If the second guitar part is rhythm then animation for the bassist exists in the the BAND BASS track.

No testing has been done with GH2 regarding animation logic. The note numbers used for hand map animation appear identical to GH1. It may be the case, however, that the odd inversion of hand mapping (when moving from single note to chords) has been fixed. The animation data for bass in YYZ appears to indicate that the initial mapping for single notes is 40 = highest position over neck and 57 = lowest position over neck.

6. Revision History


October 13, 2006: Added ARK file format information.
October 12, 2006: Added GH2 and VGS format information.
October 7, 2006: Updated sustained note threshhold value.
August 6, 2006: First draft




Source


Information originally compiled and published by:
User_Riff Riff for ScoreHero on August 6th, 2006
Source - www.scorehero.com


Category: CategoryTechnical
 Comments [Hide comments/form]
Valid XHTML 1.0 Transitional :: Valid CSS :: Powered by WikkaWiki
Page was generated in 0.0558 seconds