Jump to content
Setting up an AI agent? ReverseEngineering.wiki skill (works from the command line, no configuration): https://reverseengineering.wiki/skill/rewiki/SKILL.md · setup for every client, including MCP: https://reverseengineering.wiki/llms.txt · REWiki:Connect

Format:GBS

From ReverseEngineering.wiki
Format
On this wiki Facts · Code · Notes · Topics

Game Boy Sound System rip (.gbs): a 0x70-byte header starting 'GBS' 01 with track count, load/init/play addresses, stack pointer and timer fields, followed by the music code as ROM data for an SM83 player.

A GBS file packages the sound driver of a Platform:Game Boy game so a player can run it without the rest of the game: a 112-byte (0x70) header followed by the ROM image data starting at the load address. Players emulate the SM83 CPU and the sound hardware, call the init routine with the track number in register A, then call the play routine at the frame or timer rate.

Header

Offset Size Field
0x00 3 tag GBS
0x03 1 version (1)
0x04 1 number of songs
0x05 1 first song (1-based)
0x06 2 load address (little endian)
0x08 2 init address
0x0A 2 play address
0x0C 2 stack pointer
0x0E 1 timer modulo (TMA)
0x0F 1 timer control (TAC)
0x10 32 game title, 0x30: author, 0x50: copyright (NUL padded)

See Fact:GBS/struct/GBS header. Game_Music_Emu warns on a version other than 1, on timer-mode bits 0x78 set, and when a load/init/play address has a high byte above 0x7F or the load address is below 0x400. The code after the header is mapped as ROM from the load address in 16 KiB banks; Game_Music_Emu emulates MBC1-style bank switching writes and treats bank 0 as 1, with the bank number masked to 5 bits.

Playing

Init is called with A = song index (0-based in Game_Music_Emu's start_track_, the first-song header field being 1-based). If the timer-control bit 2 is clear the play routine runs at the 59.73 Hz frame rate (70224 cycles); if set it runs at the rate derived from TMA/TAC (bit 7 of the header's TAC doubles the speed). Unverified: the exact meaning of the TAC speed bit in the original GBS spec; test with a ROM whose header sets it.

Related

GSF (Game Boy Advance Sound Format) is a different container in the PSF family; it is not covered here. Unverified: that GSF follows the PSF layout (magic PSF 0x22, reserved/program size fields, zlib-compressed program, [TAG] block); check against the psf specification before relying on it.

Code & repositories

  • https://github.com/libgme/game-music-emu @ f68963b1de0633149b05732113d3c3113c6f63a1 · license: LGPL-2.1-or-later (declared by the contributor for the files used; GitHub reports LGPL-2.1 for the repository)
    Game_Music_Emu fork (LGPL-2.1+). gme/Gbs_Emu.h and Gbs_Emu.cpp define and load the GBS header.
    Tested on: source read, not run · checked 2026-10-19; last activity 2026-09-08; Note: the latest release ships binaries; the wiki links only the source, never the binaries

Evidence & references

Game_Music_Emu (libgme fork, LGPL-2.1+) at commit f68963b1de0633149b05732113d3c3113c6f63a1: gme/Gbs_Emu.h header_t (lines 17-33), gme/Gbs_Emu.cpp check_gbs_header and load_ (lines 108-131), set_bank (148-163), update_timer (165-).