RetroPlug

A frontend for the SameBoy Game Boy and Mesen NES emulators, with a focus on music creation. It runs standalone and can be used as an audio plugin (CLAP / VST3 / VST2 / AU) in your favourite DAW!

Features

• Wraps SameBoy (Game Boy) and Mesen (NES)
• Runs standalone, or as a CLAP / VST3 / VST2 / AU plugin inside your DAW
• Full GameBoy MIDI support for mGB
• Syncs LSDj to your DAW, with Arduinoboy-style sync modes
• Multiple instances in a single window, linked with virtual Game Boy link cables
• Flexible audio and MIDI routing, including splitting a single system out to its individual sound channels

Download

Visit the releases page to download the latest version.

Installation

• Standalone: the standalone build is a single application that can be placed anywhere you'd like.
• Plugin: copy the plugin into your system's plugin folder, or wherever your DAW scans for plugins:
  • VST3: the platform VST3 folder (e.g. ~/.vst3 on Linux, ~/Library/Audio/Plug-Ins/VST3 on macOS, C:\Program Files\Common Files\VST3 on Windows)
  • VST2: the platform VST2 folder (e.g. ~/.vst on Linux, ~/Library/Audio/Plug-Ins/VST on macOS, C:\Program Files\Common Files\VST2 on Windows), or wherever your DAW is configured to scan
  • CLAP: the corresponding CLAP folder alongside it
  • AU (macOS only): ~/Library/Audio/Plug-Ins/Components

Usage

• Load a ROM by dragging it onto the window, or open the menu and choose Load.... A .sav sitting next to your ROM is loaded automatically.
• Open the menu with Escape (rebindable) to load ROMs, save your project, and configure everything. Arrow keys navigate, Enter activates, Escape backs out.
• mGB is built in - pick Load mGB (GB MIDI Synth) from the start menu and start throwing notes at it.
• Your project state is saved into your DAW project when you save. Battery SRAM can be auto-saved as well - see Settings - or written out manually from the System menu.
• For LSDj, an additional LSDj menu appears once an LSDj cart is detected, letting you set the sync mode (see LSDj Integration).
• Name your project under Project > Name - it's what the window title and the Recent list show. Leave it empty (the default) and the name follows the loaded instance instead: its sav and ROM.
• Nothing is lost silently. Quitting, or starting / loading another project, with unsaved work asks first and lists what is unsaved: the project file, and any cart whose battery differs from its .sav (naming the file it would write).

Multiple Instances

You can load several systems in a single window and work with them side by side - handy for running multiple copies of LSDj (linked with virtual link cables), or a mix of Game Boy and NES (currently not linkable). From an instance's menu:

• Add Instance - load another ROM into a new instance.
• Duplicate Instance - clone the active instance, state and all.
• Replace Instance - swap the active instance for a different ROM.
• Remove Instance - remove it from the project.

The Layout option (Auto / Row / Column / Grid) and Zoom control how instances are arranged and sized. Tab cycles between instances.

Link Groups

Game Boy instances can be wired together with virtual link cables via the Link Group option - set two or more instances to the same group to link them, the same way you'd connect real hardware.

Audio Routing

By default every instance is summed into a single stereo output. The Audio Routing option offers:

• Stereo - the default; mixes all instances down to one stereo pair.
• 2 Ch / Inst - each instance gets its own stereo pair (instance 1 → 1-2, instance 2 → 3-4, …).
• 1 Ch / Inst - each instance on its own mono channel.
• Channels (1 GB) - with a single Game Boy loaded, split it out to its individual sound channels on separate outputs.

MIDI Routing

By default every instance receives all MIDI on all channels. The MIDI Routing option offers:

• Send to All - the default; every instance receives everything.
• 4 Ch / Inst - four MIDI channels per instance (1-4 → instance 1, 5-8 → instance 2, …). Handy for splitting 16 channels across four mGB instances.
• 1 Ch / Inst - one channel per instance.
• Ch -> Inst - map channels straight onto instances.

LSDj Integration

When an LSDj cart is loaded, an LSDj menu appears with its sync options.

Each RetroPlug sync mode expects LSDj's own SYNC setting (on the PROJECT screen) to be set to match. The required LSDj setting is noted for each mode below.

Sync Modes

• Off - no sync; LSDj plays independently of your DAW. LSDj SYNC = OFF.
• MIDI Sync - LSDj receives MIDI clock from your DAW and plays in time with the transport. LSDj SYNC = MIDI.
• MIDI Sync (Arduinoboy) - like MIDI Sync, but only starts once a C-2 note is received, emulating the Arduinoboy variation. LSDj SYNC = LSDJ. Requires the Arduinoboy build of LSDj.
• MIDI Map - plays rows relative to incoming MIDI notes (C-0 is row 0, and so on). LSDj SYNC = MI.MAP.
• Keyboard / Keyboard MIDI - drive LSDj's keyboard input from your keyboard or from MIDI notes. LSDj SYNC = KEYBD.
• MIDI Passthrough - forwards raw MIDI messages straight to the cartridge over the link port (the same path mGB uses); no particular LSDj SYNC setting is needed.
• MIDI Out - LSDj drives the clock and sends its channel notes back out to your DAW as MIDI. LSDj SYNC = MI.OUT. Requires the Arduinoboy build of LSDj.
• Master Sync - LSDj self-clocks as the master and sends MIDI clock out to your DAW. LSDj SYNC = LSDJ.

Two extra controls sit alongside the mode:

• Tempo Divisor - divides the incoming clock for slower/faster sync ratios.
• Auto Start - presses Start for you when the DAW transport starts, so a SYNC=MIDI cart arms itself automatically.

Settings

The Settings menu covers:

• SRAM Auto-Save - Off, On Save, or Continuous.
• Default Zoom - the zoom applied to new projects.
• Keyboard Bindings / Gamepad Bindings - remap the Game Boy buttons and app actions (open menu, cycle instances). Bindings live in named profiles you can create, rename and delete, and both keyboard and gamepad are edited directly in the menu - no config files to hand-edit.
• Open Settings Folder - opens the folder holding your configuration.

Command Line

The build also produces retroplug-cli (in build/bin/), a self-contained command-line tool for rendering ROMs to audio without opening a DAW or the UI. It runs the same emulator cores as the plugin, so what you hear in a render matches what you hear in your project.

build/bin/retroplug-cli --help                 # list the available commands
build/bin/retroplug-cli render --help          # options for a command
build/bin/retroplug-cli render song.gbc        # LSDj: auto-length stereo mix -> song.wav

The render command boots a Game Boy (.gb / .gbc), NES (.nes) or GBA (.gba) ROM and writes its audio to a WAV file. For a saved LSDj song it presses Start so the song begins playing (pass --no-start to capture raw boot audio); mGB needs no such press, as it plays from incoming MIDI. A sibling <rom>.sav is loaded automatically if present. Highlights:

• Automatic length - with a loaded LSDj .sav the song length is detected if you have an HFF command at the end, and the render trimmed to it, or pin a fixed length with --duration 3s (ms / s / m).
• Per-channel stems - --split channels writes one WAV per sound channel (Game Boy: 4 stereo stems; NES: 5 mono core channels), and --split pins writes the NES analog output pins. The default --split mix writes a single mixed file.
• Song selection - --list-songs prints the saved songs in an LSDj .sav, and --song NAME / --song-index N render a chosen song from the save.
• Output control - --out <file>, --sample-rate <hz>, --bpm <n> with --transport for tempo-synced playback, and --no-start to capture raw boot audio.

Run retroplug-cli render --help for the full flag reference. The CLI can also run a JavaScript session file directly (retroplug-cli <session.js>) for scripted tests and analysis.

Building

build.sh (Linux/macOS) and build.bat (Windows) are the canonical entry points - they run the configure this project needs and build in parallel. You'll need CMake 3.14+, a C++20 compiler, and Node.js (for the UI bundle); the .devcontainer/Dockerfile has the full dependency list, or just open the repo in the devcontainer. RetroPlug is developed in a dev container so it is the recommended approach.

git clone --recursive <repo-url>
cd RetroPlug
pnpm install          # wires the deps/dpf.js link before the first configure
./build.sh            # or: cmake -S . -B build && cmake --build build -j$(nproc)

The built artifacts land in build/bin/ (standalone, .clap, .vst3, VST2, AU).

Acknowledgements

• SameBoy - accuracy-first Game Boy emulator
• Mesen - accuracy-first NES emulator
• DPF - the cross-platform audio-plugin framework (CLAP / VST3 / VST2 / AU / JACK)
• LVGL and lv_binding_js - the UI toolkit and its React/JS bindings
• mGB, LSDj, and [Arduinoboy](ht