Onyx Music Game Toolkit (version 20240120)

By Michael Tolly

Onyx is a multipurpose build tool for rhythm games, particularly ones similar to the Guitar Hero and Rock Band series. It can import and export a wide variety of formats, move parts around, change song speed, fill in missing details, and assist with song authoring.

Many people have contributed code, research, and more to Onyx; see Help > Credits for details.

New versions and source at: https://github.com/mtolly/onyx/releases

Onyx is free software via the GNU General Public License v3; see Help > License or https://www.gnu.org/licenses/gpl-3.0.en.html

All original non-code assets such as graphics are licensed under Creative Commons Attribution-ShareAlike: https://creativecommons.org/licenses/by-sa/4.0/

Requirements

Onyx is currently compiled on:

It may work on previous versions (such as Windows 7) but this is not certain.

By default, an embedded copy of Magma v2 is used to generate RB3 or RB2 files. This requires the Visual C++ runtime, and if on Mac or Linux, Wine.

The Linux build is produced via an Ubuntu 16.04 Docker container, and should work on most any modern distribution. Older distributions might require additional installations:

Setup Instructions

Instructions for macOS

Follow these instructions to allow Onyx to run correctly on macOS.

  1. Extract the contents of the zip file, and move the Onyx app to the Applications folder, or wherever else you want to keep it.

  2. Run the following command in Terminal (replace the location if you moved it somewhere other than Applications)

    xattr -r -d com.apple.quarantine /Applications/Onyx.app

  3. The app should now run, but may have problems loading files due to permissions errors. To fix this, take a song file that is in a location such as your Downloads folder, and drag and drop it onto the “Load a song” button. This seems to tell macOS to give the app normal permissions to your user folders, so after that you should then also be able to use the open file dialog and batch mode to load songs.

Supported Input Formats

Onyx can import the following song formats:

Basic Usage

Onyx's core function is to “import” from one song format, and then “export” to another one. There are two methods you can use to do this:

Single Song Mode

To load a single song, click Load a song on the main console window, and select a file from the dialog box.

Note that folder-based formats may require particular files to be selected; for example, Clone Hero / Phase Shift songs can be imported by selecting the song.ini file, or notes.chart if there is no song.ini.

But, you can also simply drag and drop any file or folder onto the Load a song button. If given a folder, this will scan the contents for any recognized songs. If more than one song is found, a window will pop up letting you select which songs you want to import.

Once a song is open, you can make changes to metadata and instrument settings.

Then, use one of the target game tabs to start a conversion. Each tab has options specific to that game, as well as "slots" that correspond to the instruments supported by that game. For example, Rock Band 2 has four slots, for guitar, bass, drums, and vocals:

Depending on what instruments were present in the file you imported, you can reassign them to different slots in the new file you create. The selection from each dropdown refers to an instrument from the original imported file, which will be assigned to that slot when converting.

Finally, use one of the Create … buttons to start a conversion. Most game targets support a few different output formats. Most of these will ask you where to save a new file or folder; an exception is Guitar Hero 1 and 2, which have Add to PS2 ARK as Bonus Song. This will ask you for the location of a MAIN.HDR file, and then MAIN.HDR and MAIN.ARK will be directly modified with the new song files.

Batch Mode

To run a batch conversion, first click Batch process on the main console window. Then in the new window, select Add Song, and select a file from the dialog box. Or, just drag and drop files or folders into the empty panel.

Individual songs can be deleted by selecting a song and pressing the Delete key. They can also be moved up/down in the list with Ctrl + Up and Ctrl + Down (or Command + Up and Command + Down on Mac).

At the bottom of the panel are toggles for whether specific instruments should be imported. These can be helpful if unwanted instrument parts are causing compilation errors.

Then, switch to a target game tab. Some game-specific options are available, followed by Create … buttons. Each button has an associated Template box, which determines how newly created files and folders will be named. You can hover over one of these to see a list of supported %templates%. The folder button to the right allows you to select a folder, which will overwrite the folder part of the current template (so all created files will be in that folder). The farthest right button will reset the template to its default value.

Game-Specific Info

Rock Band 3

Supports creating a CON (Xbox 360), PKG (PS3), or Magma v2 project.

Rock Band 2

Supports creating a CON (Xbox 360) or PKG (PS3). Most options are similar to Rock Band 3.

Clone Hero & Phase Shift

Generates a song in the descended Frets on Fire format (song.ini, notes.mid, Ogg Vorbis or Opus audio). These should more-or-less work in the latest version of Clone Hero, the latest free version of Phase Shift, and the Steam version of Phase Shift. Songs may also work in Frets on Fire X, but this is not tested.

Songs can be output as a folder, a zip file containing a folder, or an SNG file (supported by newer versions of Clone Hero).

Go to Edit > Preferences to select between Ogg Vorbis and Opus audio. Opus is supported by newer versions of Clone Hero.

Due to how the conversion is implemented, some non-RB features such as Real Drums and Real Keys may not survive a PS-to-PS conversion. However Dance mode, other 5-fret charts such as PART RHYTHM, and Clone Hero 6-fret tracks should remain.

Guitar Hero & Guitar Hero II

Supports a few different formats for the Harmonix GH games on PS2 and Xbox 360:

PS2 songs have been tested with standard GH1/GH2, as well as Guitar Hero II Deluxe. Several extra features are also supported for Guitar Hero II Deluxe:

For PS2 GH2 output, practice mode audio generation can be toggled on/off. Disabling it saves some space, and a significant amount of conversion time. If disabled, practice mode will still work, just with no audio. If enabled, songs with no instrument stems will use the full track as their practice audio.

In batch mode, lead and coop parts are assigned automatically based on what parts are present.

To customize part assignment, use the “Load a song” mode.

Guitar Hero III

Creates custom DLC files for Guitar Hero III, for use on a jailbroken Xbox 360 (RGH or JTAG) or PlayStation 3.

Guitar Hero: Warriors of Rock

Creates DLC files for Guitar Hero: Warriors of Rock, for use on a jailbroken Xbox 360 (RGH or JTAG) or PlayStation 3.

Preview Tools

3D Preview

The Preview tab of a single-song window lets you view and listen to supported gameplay tracks in a full 3D graphical display. Currently 5-fret guitar/bass/keys (including tap/open notes), 4-lane drums (including cymbals), and Mania are supported, with more to come. Background images and videos from certain input formats are also supported.

By default, the preview targets 60 frames per second. You can configure this in Edit > Preferences. Antialiasing (MSAA and FXAA) can also be configured.

Gem models and textures created by Inventor211. Most textures, models, and shaders are customizable, inside the onyx-resources folder.

The file 3d-config.yml contains settings you may also want to edit.

Web Preview

This is an older preview method which generates a JavaScript (Canvas) chart preview app for web browsers. The resulting webpage can play the audio and display tracks in 2D “Beatmania” style.

Supports all Rock Band 3 instrument tracks, including Pro Guitar/Bass/Keys, as well as Clone Hero’s 6-fret (GHL) mode, 5-lane Drums, and PS Real Drums.

To generate a preview app, from a single song window, go to Utilities and click Build web preview, and select where to save the new folder. Or from batch mode, go to the Preview tab, and click Build web previews to generate a folder for each song according to the Template. You can run the app locally by opening index.html, or place the folder on a web server.

Colors used for drawing the display can be tweaked by editing the file customize.js. Images can be edited in the images folder, but many sizes are currently hardcoded, so only limited changes are possible.

Quick Convert

Quick Convert is an alternate tool that can perform several different kinds of processing/conversion on existing Rock Band format songs, without doing the normal import + export process. Some things it can do:

The following formats are supported as inputs:

And these are supported as outputs (depending on mode selection):

Drag supported input files in, and they should show up if songs are properly recognized. Then select an output mode, MIDI/milo transformation settings on the right-hand side, and use the output controls to begin processing.

Other tabs under the Quick Convert window:

Other Tools

Stars Calculator

The Stars tab on a single-song-view contains score cutoff calculators for Rock Band 3, Guitar Hero (1), and Guitar Hero 2 / 80s, with more games planned to come. Select the tracks you want to include, and star cutoffs will be computed.

MIDI/.chart Functions

MOGG/VGS/FSB Creator

Generates an unencrypted game audio file from a set of input audio files. Created MOGG files should work on Rock Band games, Guitar Hero II for Xbox 360, and newer games such as Audica, with a proper seek header. Created VGS files should work on the PS2 games GH1, GH2, and GH80s; I have not tested with PS2 Rock Band games.

The channels of all the input files, which can be WAV, OGG, MP3, or FLAC, will be merged into one multichannel file. As with the batch load screen, you can select a song row, and press Delete to remove it, Ctrl+Up to move it up in the list, or Ctrl+Down to move it down.

VGS files can be created with inputs of differing sample rates, but it is recommended that all your rates be multiples of a large common factor so that channels are interleaved in a regular pattern. MOGG files must have the same sample rate among all input files.

As a special case, if you provide a single OGG file and convert to MOGG, it will not be reencoded, but will go straight into the MOGG.

FSB3 files are used in Guitar Hero III and Rock Revolution, while FSB4 files are used in Guitar Hero World Tour and later games. Note that Guitar Hero FSB files also need to be encrypted in game-specific ways. FSB3 files have multiple stereo streams which are stored as separate files, while FSB4 merges all channels together into one multitrack stream.

Lipsync Generation

Use simple phonetic analysis to convert from a vocals chart to a lipsync file. Uses a dictionary to look up English lyrics, or spelling-based rules for German or Spanish lyrics. English supports these phonetic features at the moment:

Supports generating .voc files (used in GH2), as well as .milo_* files for later RB games.

There is also a MIDI track format for encoding lipsync information, which lets you make manual edits before converting the rest of the way to the animation files. The workflow is as follows:

  1. Turn vocal tracks into LIPSYNC* tracks for either RB3 or TBRB.

  2. Edit the text events to modify the animations. The meaning of text events is as follows:

    • [viseme_name N] moves linearly from weight N to this viseme’s next event

    • [viseme_name N hold] continues weight N until this viseme’s next event

    • [viseme_name N ease] moves from weight N to this viseme’s next event, using an “easeInExpo” transition function

  3. For TBRB, rename the tracks from LIPSYNC1, LIPSYNC2, etc. to one of LIPSYNC_JOHN, LIPSYNC_PAUL, LIPSYNC_GEORGE, or LIPSYNC_RINGO.

  4. Make or update a .milo_* file, and it will use the LIPSYNC tracks as input. Or, you can directly export .lipsync files, for later insertion into a .milo_* file

Lipsync Dry Vocals

Two options for generating audio files to give to Magma’s vocal animation generator.

.milo Unpack/Repack

Allows editing files inside the .milo archive format seen in more recent RB song files, which can contain lipsync, venue information (RB3 onward), and tweaks to character animation + vocal assignment.

Only the ObjectDir format (used in song files) is supported; other milos found on game discs will likely not work.

RB3 Song Cache ID Application

When a Rock Band custom song contains a symbol rather than a number in the song_id field, a (basically) random number is assigned by the game, and saved in the song cache file. This ID is used for associating songs with scores. If you regenerate the song cache file, new IDs will be assigned, and the scores will be disconnected.

This tool allows you to hardcode the random IDs back into the song files, replacing the symbol IDs that they originally had. Then, even if the song cache is regenerated from scratch, all scores will still be associated with their songs.

GH Song Cache Generation

This is a required step to load more than one custom song into Neversoft Guitar Hero games. The games load song metadata by finding the highest ID DLC package, and getting all metadata from that. Neversoft used this to avoid a lengthy song scan process that some of the Rock Band games had, by including all previous DLC information in each new DLC package that was released.

So, to load customs, we create a “cache” file which is just a DLC package containing only metadata and no songs. This cache package will have a higher ID than any custom or DLC (the cache ID is set to 2 billion, and customs will be between 1 and 2 billion). You must provide all custom songs as well as any official DLC (for WoR, including GH5 DLC is not necessary). Then, simply place this cache package next to your DLC and custom songs on your storage device.

You can also use previous cache files as an input to create new ones, so you don’t have to keep around already-processed customs on your computer.

To create a cache using official DLC for PlayStation 3, you’ll need to place the appropriate .RAP files in the onyx-resources/raps folder so the contents can be decrypted.

EFHIII's Autocharter

The core algorithm of the .midi to Clone Hero autochart tool by Edward Haas is used in Onyx for the following functions:

Rocksmith and Pro Guitar to 5-fret includes some extra logic for certain guitar articulations:

Command Line Interface

Onyx also comes with a command line interface that offers many of the same functions as the graphical interface, plus some additional lower-level tools.

Usage of the CLI is not documented here and is subject to change in the future, but running onyx --help will print possible commands, and then onyx (command) --help will print further instructions on a command.