Using the Toolkit

After you’ve created your MIDI, it can now be compiled with your audio.

Prerequisites

The following programs must be installed to your computer:

• FFMPEG – Link (Under Packages and Executable Files)
• .NET Desktop Runtime 8.0 – Link
• Onyx CLI (for compiling 360 and PS3 version)

FFMPEG

FFMPEG also needs to be added to your PATH environment. To do this, please follow these steps:

1. Open the start menu and search for “Environment Variables”, then select “Edit the system environment variables”.
2. In the System Properties window that appears, click the “Environment Variables” button.
3. In the Environment Variables window, under the “System variables” section, look for the variable named “Path” and select it, then click “Edit”.
4. In the Edit Environment Variable window, click “New” and then paste the full path to the directory that contains the FFmpeg executable to add to the Path.
5. Click “OK” on all the windows to save the changes. You will need to restart the Toolkit for the change to take effect.

Onyx

In order to compile 360 and PS3 packages, the command line version of Onyx will need to be downloaded. Please go to the Releases page of the Onyx app on GitHub and download the latest version of the command line toolkit:

After downloading the CLI version, extract the archive anywhere on your computer. After clicking compile when selecting either Xbox 360 or PS3 as your platform, you will have the chance to select that extracted folder:

Simply select your extracted folder and you should be good to go!

Metadata

The metadata tab is used to input the song’s information you see in-game:

• Title – The song’s title
• Artist Text – The little bit of text that displays in-between the title and artist. Currently only “By” and “As Made Famous By” are included. There is also an option to add your own
• Artist – The song’s artist
• Year – The year the song was recorded
• Cover Year – The year the song was covered (check the “Cover” box to enable this field)
• Cover Artist – The artist who covered the song (check the “Cover” box to enable this field)
• Genre – The genre of the song. Not available for GH3/A
• Checksum – A string of characters representing the song in-game. This should be a word representing the song using letters and numbers. It’s usually the song title lowercase and without spaces or other special characters.
  • If you do not make your own, one will be generated based on the song title
• Chart Author – The name of the person who authored this chart

If you are converting a Clone Hero song, you can import the metadata and audio file paths by clicking the “Import Data from Clone Hero” button. It will prompt you for the folder that contains the audio and MIDI files (.chart format is not yet supported). The fields that get populated depend on the game chosen (Importing a Clone Hero folder when selecting GH3 or GHA will not fill in the audio fields for GHWT, for example)

Audio

The audio tab is used to tell the compiler where all of your audio is. If you have separated tracks, you can fill them all in. You can either copy/paste the filepath, or click the button next to the input to select a file. Drag and drop is not yet supported in this version.

If you do not have audio for a particular part, leave it blank. If you do not have separate instruments at all, place your audio into the backing track.

If you do have separate audio files, you can add as many tracks as you want to the backing track list. They will all be combined into one track.

For GH3 and GHA, if your song has a Rhythm track instead of Bass, select the “P2 is Rhythm” box. This will update the program to show “Rhythm” instead and enable the “Separate Co-op Audio” checkbox. Enabling this will allow you to select separate audio for co-op mode. If you have a Rhythm part and the Guitar and Rhythm tracks are the same, this option is not needed.

The preview time lets you set the time in the audio used for the preview in the setlist. Preview Start determines where the preview starts.

You can either enter in the length of the preview as shown in the image, or you can click the “Set End Time” box and you can set the point in the song you wish the preview to end. You can switch back and forth between the two at any time, and the data is converted over.

You can also create your own preview track and add it to the project by checking the “Use Rendered Preview” button. This will not create a preview track and instead use the file provided in the “Preview” field.

Song Data

The song data tab lets you choose your game files to be included as well as set some in-game settings:

• MIDI File – The file path to your MIDI file
• Perf Override (Optional) – Provide a path to a .q file to add custom performance items into the final song PAK file (any performance entries generated due to the MIDI do not get overwritten, it only adds them)
• SKA Files (Optional) – Insert a file path to a folder containing all SKA files you wish to include in this custom.
• SKA Source – The game that the SKA files are made for. For most customs, this should stay on “Guitar Hero World Tour+/Blender Export”. You should only change it if you are using SKA files from GH3 or GHA in another custom.
• Venue Source – The game that lightshow and cameras were charted for. For example, if you charted a song for GH3, and want to also compile it for GHA, keep this field on GH3. It’ll convert the lights and cameras before compiling the PAK file.
• Song Script (Optional) – Provide a path to a .q file to add a custom song script file into the final song PAK file
• Count Off – The sound sample the game plays when the count-off note is encountered in the drums_notes array.
• Vocal Gender – The gender of the singer in the song. If set to None, there will not be a singer in this song.
• Volume – Adjust the volume of the guitar and backing tracks. This adjustment is made by the game itself and will not change how the compiler makes the audio. Make the value negative to decrease the volume, and positive to increase the volume.
  • Be careful with increasing the volume, as this can cause clipping.

GH3/GHA Exclusive options:

• Bassist – Select a bassist for the song. Note: Characters that do not appear in the selected game will get defaulted to the default bassist.
• Aerosmith – If Steven Tyler is selected as the vocalist, this field becomes active and will allow you to select the outfits for the Aerosmith avatars

GHWT+ Exclusive Options:

• Drum Kit: The samples that play when you hit the drums during freestyle sections in-game
• Vocal Scroll Speed: The speed at which the vocals chart plays. 1 is default.
• Vocal Tuning Cents: Adjust the pitch of the notes for vocals. If the song is not in a perfect pitched tuning, this number can be adjusted to accommodate. Range is from -50 to +50. If you feel you need to go beyond this range, please ensure the vocals notes are properly charted.
• Sustain Threshold: The threshold at which sustains start appearing. The number is the percentage of a quarter note. Default is 0.50, meaning that any note longer than 1/8^th (50% of ¼) will become a sustain.
  • The default value for GH5 and up is 0.45.
• Microphones: Enable the use of a microphone for the guitarist/bassist in-game (will still require a script call in the song’s performance array to make them show up)

Compile

The compile tab has a few compiler settings and is used to compile the song.

• HOPO threshold – The distance between two notes to make them a hammer-on/pull-off (HOPO). This compiler uses the Harmonix values for its calculations. Default is 170 and that means any note faster than an 8th note triplet (1/12th note) will become a HOPO. The NS value is for your information only and will be added to the songlist entry.
• HOPO Mode – The mode to use for Hammer Ons and Pull Offs. Each mode changes the logic of compilation slightly. Rock Band mode is the only functioning one at this time. Rock Band mode should be the default for most MIDIs you find or make, but if you are converting a song, it may be useful to change this setting.
  • Rock Band – This mode will calculate HOPOs based on the distance between each note, and then apply forcings, either on or off. If a chord and a single note follows containing any note of the chord and it’s within the HOPO threshold, this will NOT be a HOPO unless forced.
  • Moonscraper – This mode will calculate HOPOs based on the distance between each note, and then apply forcings, either on or off. If a chord and a single note follows containing any note of the chord and it’s within the HOPO threshold, this will be a HOPO unless forced off.
  • Guitar Hero 3 – This mode will calculate HOPOs based on the distance between each note. If a “force on” note exists on a note in the MIDI, it swaps the HOPO status. If a chord and a single note follows containing the lowest note of the chord, this will be a HOPO unless swapped. “Force off” notes are ignored.
  • Guitar Hero World Tour+ – This mode will NOT calculate HOPOs based on the distance between each note. Only notes that are forced on will become HOPOs.
• Beat Lines BPM – The tempo at which subdivisions of beat lines appear. Not supported for GH3. If these fields are disabled, they can be enabled in Settings.
• Platform – Choose which platform to compile for here. If compiling for 360 or PS3, the checksum that will be used will be shown as well.

WTDE Settings

This tab is only available when GHWT PC is selected and contains settings that only apply to WTDE:

• Game Icon: The icon that shows up next to the song in the setlist
• Game Category: The category that the song is sorted in when viewing the setlist
• Band: The QB key of the band configuration you’d like to apply for the song
• Skeletons: The skeletons to apply for each band member
• Use New Clips: Turn on to allow multiple clips playing at the same time in a song
• Modern Strobes: Turn on to enable GH5 and up logic for strobe lights in-game

How to Compile

After filling in all the tabs, hit Compile All. This will prompt you to save the project file. If this is your first compilation ever for GH3/A on PC, the program should also backup your qb.pak and qb.pab files. A message box should show up telling you this. You can restore your backups by going to the Toolkit folder. There will be a Backups folder containing them.

The toolkit should be compatible with any GHTCP modifications done to it. However, once you add a song with my toolkit, GHTCP will not let you access the game’s files anymore until you restore the backup.

To redo a chart, you can simple click “Compile Song” and it’ll just recreate the song PAK file.

When using “Compile All”, the button text will change to “Compiling…” when it is busy compiling the audio. Do not close the program at this time.

Performance/Scripts Override

The toolkit allows you to override (or add, in the case of performance) custom scripts via these two fields in the Song Data tab. Please download the templates here.

This section of the page will give you information on how to compile them properly.

Performance Override

Treat this file as a nameless performance array. You can create a file with just the struct entries and the compiler will be smart enough to wrap it in the song_performance array. As an example:

You can see that there is no qb key signalling the name of the array, nor are there array braces.

Items do not need to be in order, the compiler will sort it for you. Keep in mind that Band_PlayFacialAnim can also be added via MIDI by including it in the MIDI track of the avatar (please see the authoring guide here)

Scripts Override

This file allows you to place any song-specific scripts and have the song use them. This file also contains which loops the avatars play in-game. The template above contains male and female examples:

If you keep the names as “car_female_anim_struct” and “car_male_anim_struct”, the compiler will change them to work with the song automatically by adding the songname to these names.

If you need to add “_alt” structures for guitar-playing singers, you will need the full name of the qb key in that instance.

Importing Songs

As of the May 2024 build, you can now import songs using SGH files. Originally introduced with Guitar Hero Three Control Panel, these new SGH files allow you to share songs and convert them to any platform without reprocessing any audio

To get started, click on the “Import SGH Archive” button in the main screen of the toolkit:

Once loaded, you are greeted with this window:

Click on “Import SGH File” to choose any SGH file, both from GHTCP, or the new SGH files created by this toolkit (more on exporting later).

The songs inside the SGH file will show up in the list. By default, all songs checked. Any song that is checked will be included when you hit “Convert!”

For 360 and PS3, you must have Onyx set up (please see the Onyx section above), the program will guide you through the setup if it’s not configured. For these consoles, the LIVE or PKG file will show up in the same folder as the SGH file.

For PC, the songs will be added to GH3 automatically.

If there are a lot of songs in the SGH file, it may take some time to process. Please be patient if the program appears unresponsive.

Exporting Songs

A new feature in the song compiler is the ability to export songs to an SGH file to import with this toolkit. It can be found in the File toolbar menu:

This will go through the process of compiling your midi file and audio and create an SGH file in your compile folder (by default, this is the folder where your .ghproj file is located in). Once created it can be shared so others may play your customs as well!

Exporting currently only works for Guitar Hero 3.