Format:GBS
| 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-).