This guide explains how to set up a pipeline for creating executable game boy music on Linux: setting up the sequencer LSDj, wiring up a controller, and compiling your finished song into an executable .gb file with LSDpack.

Setting Up the Sequencer

LSDj runs as a Game Boy ROM, so you’ll need an emulator to run it on Linux. The recommended emulator is BGB, which runs well under Wine.

  1. Download the BGB Game Boy emulator (Windows build) and extract the zip.
  2. Download the LSDj ROM image and extract it.
  3. Install Wine: sudo apt install wine
  4. Open a terminal in the BGB folder and launch it: wine bgb.exe
  5. Right-click the emulator screen and select your LSDj ROM.

Reference Materials

Setting Up Controller Input

A USB SNES controller is a comfortable way to operate LSDj. If arrow keys don’t map correctly through Wine, you can remap them manually using AntiMicroX.

  1. Install AntiMicroX: sudo apt install antimicrox
  2. Launch it: antimicrox
  3. Map the controller buttons to match BGB’s default keyboard controls: | Controller Button | Keyboard Key | |—|—| | D-Pad Right | Arrow Right | | D-Pad Left | Arrow Left | | D-Pad Up | Arrow Up | | D-Pad Down | Arrow Down | | A | S | | B | A | | Start | Enter | | Select | Shift |
  4. Keep AntiMicroX running in one terminal while launching BGB from another.

Compiling Your Song to an Executable ROM

Once your song is finished in LSDj, you can record and compile it into a standalone .gb ROM using lsdpack and RGBDS.

Installing the Tools

  1. Install build dependencies and RGBDS (the Game Boy assembler/linker): 
    sudo apt install -y cmake build-essential git rgbds

    Note: If apt install rgbds fails or gives an outdated version, install it manually from github.com/gbdev/rgbds/releases. Ypu can also install CMake manually from the official binary distributions (Linux x86_64).

  2. Clone lsdpack: 
    git clone https://github.com/jkotlinski/lsdpack.git
cd lsdpack
  3. Configure and build: 
    cmake -B build -S .
cmake --build build

Converting Your Save File to a ROM

1. Save your song in LSDj. This produces a .sav file.

2. Prepare the song to stop. Every song must terminate cleanly — use the HFF command at the end of the song sequence in LSDj.

3. Record the song. Place your .sav and .gb (LSDj ROM) files in the same directory, then run:

./lsdpack.exe -g -d lsdj.gb

Flag explanations:

  • -g — GBS conversion mode; records each song into a separate numbered .s file (e.g. lsdj-1.s, lsdj-2.s)
  • -d — Record using emulated DMG (original Game Boy) instead of CGB (Game Boy Color)

    Important: Always use the -d flag. Recording with Game Boy Color mode will corrupt the song’s playback speed in the final ROM.

4. Assemble the components using RGBDS:

rgbasm -o boot.o boot.s
rgbasm -o player.o player.s
rgbasm -o lsdj-1.o lsdj-1.s

5. Link everything into a single ROM:

rgblink -o player.gb boot.o player.o lsdj-1.o

6. Fix the ROM header (required for the ROM to be valid):

rgbfix -v -m 0x19 -p 0xff player.gb

The result is player.gb — a self-contained Game Boy ROM that plays your song. Load it into BGB the same way you loaded the LSDj ROM to verify it works.