Tools for interacting with music data in GBA games that use the Engine Software replayer.

Overview

engine-software-gba-tools

CircleCI

A suite of tools for interacting with the XM-like music data found in certain Game Boy Advance games - specifically those that use the Engine Software replayer middleware.

Exporting music from games using these tools allows for much clearer audio than the original hardware was capable of producing. However, I do not want to see music exported with these tools described as 'accurate' or 'faithful', at least until such time as certain assumptions in the code have been verified.

Disclaimer: This project is not affiliated with Engine Software and is purely a reverse-engineering effort.

Overview of tools

xmprint

A basic debugging tool for viewing the contents of an XM file and verifying my understanding of the format.

Usage:

xmprint path/to/xm/file.xm

gbaprint

Prints the contents of a GBA music bank as text.

Usage:

gbaprint path/to/gba/rom.gba 0x123456

(where 0x123456 is the address of the music bank inside the rom)

gbafind

Searches for a GBA music bank inside a GBA rom.

Usage:

gbafind path/to/gba/rom.gba

gba2xm

Exports a GBA music bank as a series of XM files.

Usage:

gba2xm path/to/gba/rom.gba 0x123456

(where 0x123456 is the address of the music bank inside the rom)

Building

These tools are built using the Meson build system, which itself depends on Ninja.
Once you have both installed, the recommended commands are as follows:

meson setup build
cd build
meson compile

Music Bank structure

This is based primarily on static reverse-engineering of the binary storage format, along with some very light disassembly of the replayer code. I'm confident in the majority of it, but I am uncertain about some fields in the instrument structures.

Note: all offsets are relative to the start of the music bank.

pseudostruct envelope_point
{
	u16 x; // point position in time
	u16 y; // point value
}

pseudostruct envelope
{
	u8 pointCount;
	u8 maybeSustainPoint;
	u8 maybeLoopStartPoint;
	u8 maybeLoopEndPoint;

	envelope_point points[12];
}

pseudostruct instrument
{
	u32 sampleLength;
	u32 sampleLoopStart;
	u32 sampleLoopLength;
	u8 sampleVolume;
	u8 samplePanning;
	s8 sampleFinetune;
	s8 sampleRelativeNoteNumber;
	u16 volumeFadeout;
	u8 unknownBytes[2]; // probably just alignment padding
	envelope volumeEnvelope;
	envelope panningEnvelope;

	// signed 8-bit PCM, *not* delta-encoded
	s8 sampleData[sampleLength];

	// - align to 4-byte boundary -
}

pseudostruct row
{
	u8 bitmask[ceil((channelCount*5)/8)];
	u8 data[countSetBits(bitmask)];
}

pseudostruct pattern
{
	u16 rowCount;

	// - align to 4-byte boundary -

	u32 rowOffsets[rowCount];
}

pseudostruct song
{
	u8 channelCount;
	u8 songLength;
	u8 loopPoint;
	u8 patternCount;
	u8 tickrate;
	u8 tempo;

	// - align to 4-byte boundary -

	u8 patternOrder[songLength];

	// - align to 4-byte boundary -

	pattern patterns[patternCount];
}

pseudostruct musicbank
{
	// seems to always be 0x0121
	// possibly a version number of 1.21?
	u16 id;
	
	u8 instrumentCount;
	u8 songCount;

	u32 songOffsets[songCount];

	instrument instruments[instrumentCount];

	// after this point, parse data by seeking to offsets,
	// as the row data's length is unpredictable.

	u8 rowdata[???];

	song songs[songCount];
}

Row data compression

Row data follows the same 5-byte {note,inst,vol,effect,param} layout as XM, but uses a different packing structure in the ROM.

Each bit of bitmask corresponds to a column of the tracker. The first five bits correspond to the fields of the first channel, the next five bits correspond to the next channel, and so on. As such, the length of bitmask is channelCount * 5 bits, rounded up to the next whole byte.

Starting at bitmask[0] and reading from MSB to LSB, if the bit is set, read a byte from data and assign it to the corresponding field of the channel.

For example, here's a row from a 3-channel song.

bitmask: [0xc0, 0x30]
data: [0x2a, 0x04, 0x31, 0x0d]

Reading the bitmask a bit at a time, we get the following binary. The lone last bit is just padding and goes unused.

11000 00000 11000 0

This means data has note/inst data for the first and last channel. In a pseudo-tracker interface, that row might look like this:

| 2a 04 -- -- -- | -- -- -- -- -- | 31 0d -- -- -- |
Issues
  • Compiler Error

    Compiler Error

    When I do meson setup build I get the following

    C:\Users\T3K\Documents\engine-software-gba-tools-main\engine-software-gba-tools-main>meson setup build
    The Meson build system
    Version: 0.56.1
    Source dir: C:\Users\T3K\Documents\engine-software-gba-tools-main\engine-software-gba-tools-main
    Build dir: C:\Users\T3K\Documents\engine-software-gba-tools-main\engine-software-gba-tools-main\build
    Build type: native build
    Project name: engine-software-gba-tools
    Project version: 0.0.1
    
    meson.build:1:0: ERROR: Unknown compiler(s): ['icl', 'cl', 'c++', 'g++', 'clang++', 'clang-cl']
    The follow exceptions were encountered:
    Running "icl " gave "[WinError 2] The system cannot find the file specified"
    Running "cl /?" gave "[WinError 2] The system cannot find the file specified"
    Running "clang++ --version" gave "[WinError 2] The system cannot find the file specified"
    Running "clang-cl /?" gave "[WinError 2] The system cannot find the file specified"
    
    A full log can be found at C:\Users\T3K\Documents\engine-software-gba-tools-main\engine-software-gba-tools-main\build\meson-logs\meson-log.txt
    

    I am running this (as you could already tell) on Windows 10 with G++ installed

    opened by ItsT3K 0
Owner
Luna
Luna
Accurate C port of AHX's Amiga replayer

ahx2play Aims to be an accurate C port of AHX 2.3d-sp3's internal replayer. The project contains example code in the ahx2play folder on how to interfa

Olav Sørensen 9 May 30, 2022
Aims to be an accurate C port of Impulse Tracker 2.15's IT replayer (with selectable IT2 sound drivers)

it2play Aims to be an accurate C port of Impulse Tracker 2.15's IT replayer (with selectable IT2 sound drivers). This is a direct port of the original

Olav Sørensen 17 May 21, 2022
Minipops alternative firmware for Music Thing Modular Radio Music

RMoxy Minipops drummer alternative firmware for Music Thing Modular Radio Music module The repository for the Radio Music module by Tom Whitwell Kits

Johan Berglund 6 Apr 6, 2022
This is a tool for software engineers to view,record and analyse data(sensor data and module data) In the process of software development.

![Contributors][Huang Jianyu] Statement 由于工具源码在网上公开,除使用部分开源项目代码外,其余代码均来自我个人,工具本身不包含公司的知识产权,所有与公司有关的内容均从软件包中移除,软件发布遵循Apache协议,任何人均可下载进行修改使用,如使用过程中出现任何问

HuangJianyu 34 May 5, 2022
Coverett - C library for interacting with HLAPI devices of the OpenComputers II mod.

Coverett Coverett - C library for interacting with HLAPI devices of the OpenComputers II mod. Warning!!! The library is in alpha stage, so it can cont

Vladislav 8 May 6, 2022
A self-contained minimal library for interacting with Linux hot-plug events

libue Zero dependency minimal library for interacting with Linux hot-plug events. Installation Just drop the header file into your C project. Usage #i

QP Hou 20 Feb 10, 2022
A simple one header solution to interacting with Windows WMI in C++

?? WinWMI A simple one header solution to interacting with Windows WMI in C++ Usage Just #include "winwmi.hpp" in your code! Initialize To initialize

Konstantin 'cpz' L. 4 Jan 24, 2022
CS202 (2022 Winter) Project: Interacting with "emulated" hardware accelerators

CS202 (2022 Winter) Project: Interacting with "emulated" hardware accelerators Overview Hardware accelerators that implement specialized circuits for

Hung-Wei Tseng 4 Mar 21, 2022
Defold Engine integration with Yandex.Metrica to track your games on Yandex.Games.

Yandex.Metrica for Defold Yandex.Metrica is a free of charge web analytics tool for websites, that's the reason why we can use it for HTML5 games. Yan

Indiesoft LLC 6 Jan 20, 2022
MasterPlan is a project management software / visual idea board software. It attempts to be easy to use, lightweight, and fun.

MasterPlan is a customizeable graphical project management software for independent users or small teams. If you need to share plans across a whole co

SolarLune 405 Jun 23, 2022
Suckless-tools - My fork of suckless tools.

suckless-tools Here is my fork of suckless tools. I didn't include tabbed, i was using but not actively. I am using xfce4-terminal instead of st. Beca

null 2 Jan 7, 2022
The Vulkan Profiles Tools are a collection of tools delivered with the Vulkan SDK for Vulkan application developers to leverage Vulkan Profiles while developing a Vulkan application

Copyright © 2021-2022 LunarG, Inc. Vulkan Profiles Tools (BETA) The Vulkan Profiles Tools are a collection of tools delivered with the Vulkan SDK for

The Khronos Group 52 Jun 9, 2022
Tactile-Arcade-Games - Wrote a C program comprised of four separate games that run in a loop using the PSoC 5LP board and Cypress IDE.

Tactile-Arcade-Games - Wrote a C program comprised of four separate games that run in a loop using the PSoC 5LP board and Cypress IDE. Used two potentiometers, two ADCs to convert their voltages to digital values, a PWM to drive two servos, an 8x8 RGB LED matrix, 40 digital output pins and 8 power MOSFETS to control the matrix, and a character LCD display.

null 2 Dec 24, 2021
General repository for all software (emulators, dev tools, etc) related to Vircon32 but not running on console itself

Vircon32: Computer software This is a general repository containing source code related to Vircon32 implementation, this is, software that does NOT ru

Vircon32 5 Jun 14, 2022
A generic post-processing injector for games and video software.

ReShade This is a generic post-processing injector for games and video software. It exposes an automated way to access both frame color and depth info

null 2.6k Jun 27, 2022
Meta - static reflection tools for c++. i mostly use this with entt.

meta Static reflection tools for C++. I use it with EnTT but it can work with anything. The main features the library provides are: Registering types

Nikhilesh S 8 Jan 16, 2022
This Program Enables And Disables Hyper-V Hypervisor So You Can Use Other Virtualisation Tools Such As (VMware, VirtualBox) Simultaneously.

Hyper-V-Switch This Program Enables And Disables Hyper-V Hypervisor So You Can Use Other Virtualisation Tools Such As (VMware, VirtualBox) Simultaneou

RaynerSec 2 May 27, 2022
A laser cut Dreamcast Pop'n Music controller and integrated memory card using the Raspberry Pi Pico's Programmable IO

Dreamcast Pop'n Music Controller Using Raspbery Pi Pico (RP2040) Intro This is a homebrew controller for playing the Pop'n Music games on the Sega Dre

null 31 Jun 6, 2022
Minimalistic text-based 1-bit music tracker

1bitr 1bitr ("One Bitter" or "The Bitter One") is a minimalistic text-based music tracker. It only supports 1-bit audio playback and encourages users

Serge Zaitsev 54 Jun 6, 2022