Song Definition Format Reference | mari@macintosh.garden
So as you likely know, GH2 stores all song metadata in a file called songs.dta. This is a giant nest of arrays containing everything from song and artist names to VGS channel mappings to audio mixing settings to preview times and so on.
I have a more general-purpose tutorial on adding new songs to this file, but that's a pretty cursory look just so no one gets lost in a bunch of minutia. (Seriously, I had to go through three separate attempts at writing it because I kept getting lost—this page and the introduction to data array tutorials are what came of those.)
What I'm doing instead here is giving you an intentionally verbose song definition, marked up with comments so you get an idea of what everything in a song definition does. Some of this stuff, we only found out recently, amazingly. Either way, don't mind the rat's nest of parentheses. It's just the nature of the beast.
(soulsforsale ; Song shortname, referenced in campaign.dta and store.dta
(name "Souls for Sale (Circus Fire Scene)") ; Song name. Keep under 35 characters if possible or else it'll run off the edge of the setlist.
(artist "Ben Minnotte") ; Artist name.
(caption performed_by) ; Specifies caption to be used. If omitted, the game defaults to the "as made famous by" caption. New captions can be defined in locale.dta or locale_milo.dta. Simply set the string name in this array.
(song
(name songs/soulsforsale/soulsforsale) ; The path at which the game will look for the VGS file and the .voc file.
(tracks ((guitar 1) (rhythm 2))) ; The tracks array is tricky. It sets which channels are used for each playable instrument, and the game will also determine if the song is guitar-bass or lead-rhythm based on the presence of a rhythm array in this array. Any channels not specified in this array will be treated as background noise and always played. All channel mappings start at 0; This one is set for a three-channel VGS file where the band is the first channel, the lead guitar is the second channel, and the rhythm guitar is the third channel.
(pans (0.0 0.0 0.0)) ; Sets the panning of each channel if stereo sound is enabled. One float for each channel, with -1.0 meaning hard left and 1.0 meaning hard right. 0.0 is centered.
(vols (0.0 0.0 0.0)) ; Volumes of each respective channel in the VGS. These can't really boost, only duck. In other words, 0.0 is your maximum (the game will play the channel as-is), and if you set it to negative values, it'll make the channel quieter. It won't make the channel louder if set to positive values. All values are in decibels and specified as floats.
(cores (-1 1 1)) ; cores confused us for a long time, but essentially, whether that channel will be treated with audio effects when star power is activated. If you listen close when you activate in-game, the guitar will reverberate. This controls which channels will reverberate like that, -1 for no and 1 for yes. Harmonix only sets it on the guitar, presumably so the mix doesn't get unnecessarily swamped and it sounds like the drugs are kicking in.
(midi_file songs/soulsforsale/soulsforsale.mid) ; MIDI used, self-explanatory. This means you can actually have definitions that share audio but use different charts, if you wanted to have a demo chart and a final chart on the same disc, using the same audio to save space.
(hopo_threshold 170)) ; Optional. How far apart, in MIDI ticks, the the game will allow two notes and consider them HOPOs. This is mostly set to 250 for eighth note HOPOs on faster songs. The default in beatmatcher.dta is 170, so to preserve this chart's normal behavior, I've set it to that. You can omit it and your chart will use 170.
(song_coop ; Optional. Largely a duplicate of the normal song array, but used only when the song's loaded in co-op. This is mostly used if you have a lead-rhythm song where the normal singleplayer VGS has the player playing both lead and rhythm alternating (think Arterial Black) and a separate co-op VGS with both guitar parts separated. You'd set the co-op specific audio and channel mappings in this array and the singleplayer specific audio and mappings in the first array.
(name songs/soulsforsale/soulsforsale)
(tracks ((guitar 1) (rhythm 2)))
(pans (0.0 0.0 0.0))
(vols (0.0 0.0 0.0))
(cores (-1 1 1))
(midi_file songs/soulsforsale/soulsforsale.mid))
(anim_tempo kTempoMedium) ; For certain animations, notably the drummer, what looks good at a slow speed looks goofy at a faster speed. As a result, Harmonix included two sets of animations for certain models, and this array sets whether the slow/normal ones are used or the fast animations are used. kTempoMedium sets the former ones, kTempoFast sets the latter ones. Anything over 140BPM should use kTempoFast.
(preview 31478 46531) ; Preview times on the setlist in milliseconds. An infamous crash early in the scene's history involved replacing long songs with shorter ones and having the preview times seek for nonexistent audio. Thus, make sure your preview times are set properly. If you're lazy, you can just pick two points in the song in your head (say, between 50s and 1:10s) and set them as 50000 and 70000, respectively.
(quickplay ; Quickplay defaults for guitarist, guitar, and venue. If one of the specified defaults isn't unlocked on the player's save, it'll fall back to default characters set elsewhere that are unlocked. Which ones, I'm not sure at the moment. Be wary of this when setting Grim as the quickplay guitarist.
(character_outfit classic) ; Valid character outfits: punk1, punk2 (Johnny Napalm), alterna1, alterna2 (Judy Nails), glam1, glam2 (Izzy Sparks), goth1, goth2 (Pandora), metal1, metal2 (Axel Steel), rockabill1, rockabill2 (Eddie Knox), rock1, rock2 (Casey Lynch), deathmetal1, deathmetal2 (Lars Umlaut), classic (Clive Winston), funk1 (Xavier Stone), grim (Grim Ripper).
(guitar lespaul) ; The only ones guaranteed to show up are lespaul, sg, and flying_v, as these are always unlocked on every save. Check guitars.dta for a full listing if you're feeling brave, however.
(venue battle)) ; Only the first two venues are guaranteed to work, again, as they're always unlocked. Of course, for later tier songs, the later venues would also be unlocked, so have fun. Valid venues: battle (Battle of the Bands), small1 (Rat Cellar), small2 (Blackout Bar), big (RedOctane Club), theatre (Detroit Rock City Theater), fest (Warped Tour), arena (Harmonix Arena), stone (Stonehenge).
(practice_speeds (100 85 65 50)) ; Optional. The speeds, in percentage, that Full Speed, Slow, Slower, and Slowest respectively will use in Practice. By default, these are set to 100%, 85%, 65%, and 50%, and if omitted, your song will use these values.
(song_practice_1 ; Optional, and identical to the song array if specified. These settings will be used with practice mode at the Slow setting (85% or 90%).
(name songs/soulsforsale/soulsforsale_p85)
(tracks ((guitar 0) (rhythm 1)))
(pans (0.0 0.0))
(vols (0.0 0.0))
(cores (-1 -1))
(midi_file songs/soulsforsale/soulsforsale.mid))
(song_practice_2 ; Optional, and identical to the song array if specified. These settings will be used with practice mode at the Slower setting (65% or 75%).
(name songs/soulsforsale/soulsforsale_p65)
(tracks ((guitar 0) (rhythm 1)))
(pans (0.0 0.0))
(vols (0.0 0.0))
(cores (-1 -1))
(midi_file songs/soulsforsale/soulsforsale.mid))
(song_practice_3 ; Optional, and identical to the song array if specified. These settings will be used with practice mode at the Slowest setting (50% or 60%).
(name songs/soulsforsale/soulsforsale_p50)
(tracks ((guitar 0) (rhythm 1)))
(pans (0.0 0.0))
(vols (0.0 0.0))
(cores (-1 -1))
(midi_file songs/soulsforsale/soulsforsale.mid))
(band metal_drummer)) ; Optional. The band that'll appear onstage. By default if this is omitted, it'll be the drummer, as metal_drummer, bassist, as metal_bass, and male singer, as metal_singer. If you want a female singer, use female_singer, and if you want the keyboardist, use metal_keyboard. Keep in mind that the drummer will crash the game if he's set not to appear, and if you try to specify both the keyboardist and singer in this array, the singer will win out.