Installing MIDI Captain MAX
How to install or update MIDI Captain MAX firmware on your PaintAudio MIDI Captain. Once MIDI Captain MAX is installed, all future updates happen inside the Config Editor — no scripts, no manual file copying.
First: Back Up!
Before doing any of this, if you haven't already, please back up your existing config and firmware to a safe place for recovery or to revert to OEM firmware:
- Mount the device to your computer. You may have to hold down Button 1 / KEY0 to force it to mount.
- Copy all contents of the device to a safe place on your computer.
What to Download
Everything is on the latest release page. Download either:
- The Config Editor installer for your OS:
.dmgfor macOS,.exeor.msifor Windows,.AppImage(portable) or.deb(Debian/Ubuntu) for Linux. The Config Editor includes the bundled firmware, so you don't need to download it separately, or - The
MIDI-Captain-MAX-<version>-complete.zippackage if you want the GUI and the firmware as separate packages.
For example, if you prefer the deploy script, or are on an unsupported OS, this package includes everything you need. (The GUI still includes the bundled firmware; the zip is just for convenience if you want to use the deploy script instead of the GUI installer.)
macOS: Install with Homebrew
If you use Homebrew, you can install the Config Editor without visiting the release page:
brew install --cask mc-music-workshop/tap/midi-captain-maxGet new versions with brew upgrade --cask midi-captain-max. This cask only carries stable releases.
To try betas and release candidates, install the beta cask instead. It gets every beta, release candidate and stable release (never alphas), so it also picks up the stable release once that ships:
brew install --cask mc-music-workshop/tap/midi-captain-max@betaThe two casks can't be installed together. To switch, uninstall one first: brew uninstall --cask midi-captain-max (or midi-captain-max@beta), then install the other.
Already Installed from the Download?
If you already installed the Config Editor from a .dmg, Homebrew refuses to install over it. Add --adopt so Homebrew takes over your existing copy instead:
brew install --cask --adopt mc-music-workshop/tap/midi-captain-max(Use midi-captain-max@beta instead if you want the beta cask.)
Adopting only works when your installed version matches the cask's version. If it doesn't, Homebrew stops with a "bundle version" error. When that happens, use --force instead to replace your copy with the cask's version:
brew install --cask --force mc-music-workshop/tap/midi-captain-maxEither way, your settings, saved configs and templates are kept. From then on, brew upgrade keeps the app up to date.
Updating the Config Editor
The Config Editor checks for a newer version each time it starts. When one is out, a banner at the top of the window says so; click Update & Restart and the app downloads the new version, installs it and reopens. Your settings, saved configs and templates are kept. Later hides the banner until the next start, and Check for Updates (next to the version number at the top) checks again whenever you like.

The app stays on the channel you installed: a stable version is offered stable releases only; a beta or release candidate is offered newer betas, release candidates and stable releases; an alpha is offered every newer release. This works the same however you installed the app, including with Homebrew: brew upgrade and the in-app update install the same file.
After updating the app, connect your pedal: if its firmware is now older than the app's, update the firmware too (see below).
Updating an Existing MIDI Captain MAX Install
- Connect your MIDI Captain via USB and power it on.
- The device may mount as
CIRCUITPYorMIDICAPTAIN. - If no drive appears, hold switch 1 / KEY0 while plugging in USB.
- The device may mount as
- Install and open the MIDI Captain MAX Config Editor.
- Scroll to the Firmware Installation section at the bottom of the app window.
- Click Install Firmware.
By default, the installer preserves your existing config.json. Enable Reset config.json to bundled defaults only if you want to overwrite your current settings with the default template.
The app will copy the firmware, reload the device, and update it in place.
When the Pedal Is Behind the Config Editor
Each Config Editor release ships with matching firmware. When you connect a pedal running older firmware, a notice at the top of the window says so, for example "Pedal firmware v1.14.0 is older than this editor (v1.15.0)". Until you update, settings for newer features can save without error and still do nothing on the pedal.

Click Update Firmware on the notice to run the same install as the Firmware Installation section; your config.json is kept. Dismiss hides the notice for that pedal and version. Saving to an out-of-date pedal also reminds you in the status bar.
A pedal running newer firmware than the Config Editor (for example after a development deploy) gets no notice.
First Run of the Config Editor
The first time you use the page-template feature (Edit Pages… → Save as template… / Add from template…), the editor creates Documents/MIDICaptainMAX/templates for your saved page templates. The save dialog and the template picker both point here by default.
Templates are plain JSON files, one page each — feel free to back them up, rename them in Finder/Explorer, or share them with other MIDI Captain users.
Saved configs work the same way: Save to File… and Load from File… point at Documents/MIDICaptainMAX/configs, which the editor creates the first time it needs it. See Saving and Loading Configs.
First Run on OEM Firmware
If your MIDI Captain is still running the factory Paint Audio firmware, the Config Editor may show OEM (no VERSION.txt file).
The deploy script is no longer required — the entire first install can be done from the Config Editor. The installer only needs to know your device type, and you tell it that by saving a config from the editor first:
- Hold Button 1 / KEY0 while plugging in USB to enter the OEM USB settings mode. A
MIDICAPTAINdrive should appear. - Open the Config Editor and select the device. Since there's no MAX
config.jsonon the drive yet, the editor opens with nothing loaded: click New Config… and pick your model. - Click Save to Device. Because the drive has no config to say what model it is, the editor asks you to confirm the model first.
- Scroll to the Firmware Installation section and click Install Firmware. For a first install, enable Reset config.json to bundled defaults so you start from the full default template for your device.
- If the button blocks with a CircuitPython version error, see the next section, then come back.
If the Config Editor shows a CircuitPython version error (2026-batch devices)
If the Config Editor refuses to install with a CircuitPython version error, your device is running a newer CircuitPython than this firmware supports — typical for 2026-batch Captains, which ship with CP 9.2.7. MIDI Captain MAX currently targets CP 7.3.1: the bundled libraries are mpy format v5 and boot.py uses CP 7-only APIs, so CP 8.0 and later silently break it. See #2 for the planned CP 9/10 migration and #132 for background.
Fix this first:
- In the Firmware Installation section, open Advanced / Recovery.
- Click Reflash CircuitPython 7.3.1. The editor sends a command over serial, reboots the device into its RP2040 bootloader, copies the bundled
.uf2, and waits forCIRCUITPYto remount — no physical button hold needed. - Once
CIRCUITPYremounts, continue with the first-install steps above (the device is already mounted; skip step 1).
Manual fallback — only if the GUI's automatic bootloader entry fails (device too broken to honour REPL commands, no CDC serial available): follow the manual bootloader entry guide to reach the RPI-RP2 bootloader drive, then copy the CP 7.3.1 .uf2 from the -complete.zip release asset onto it. The device reboots into CIRCUITPY automatically.
⚠️ Switch 1 / KEY0 does not enter the RP2040 bootloader. It only makes the running firmware expose the USB drive. To reach
RPI-RP2, use the Config Editor's reflash button or the recovery guide above.
Deploy script (alternative)
Prefer the command line, or on an OS the GUI doesn't support? The deploy script still performs a full first install:
- Hold Button 1 / KEY0 while plugging in USB to enter the OEM USB settings mode. A
MIDICAPTAINdrive should appear. - Download and extract
MIDI-Captain-MAX-<version>-complete.zipfrom the latest release. - Run the included deploy script once with your device type:
NOTE: only enter the desired device type, not the full list of options.
For example, if you have a Nano 4, run./deploy.sh --device nano4.- macOS / Linux:
./deploy.sh --device std10|mini6|nano4|duo2|one1 - Windows PowerShell:
.\deploy.ps1 -Device std10|mini6|nano4|duo2|one1 - Windows cmd (if PowerShell blocks unsigned scripts):
deploy.bat -Device std10|mini6|nano4|duo2|one1— invokesdeploy.ps1with a per-processExecutionPolicy Bypass; does not change any system policy.
- macOS / Linux:
- Reconnect the device and open the MIDI Captain MAX Config Editor.
- From then on, use the Firmware Installation section in the app for future updates.
Recovery
If anything goes wrong, it is fully recoverable:
- Mount the device (hold Button 1 / KEY0 while plugging in if needed).
- Erase the contents.
- Restore your backup, or re-run the first-install steps above.