microSAMPLER Editor / Librarian

Editor/librarian for the Korg microSAMPLER. I originally made it because Korg's old 32-bit editor stopped working on newer versions of macOS.

The hardware protocol was reverse-engineered from the original binary and verified against a real device.

It should be able to do everything I used the original editor for, and it also adds a few features that weren't available there.

Full documentation & guide →

Also listed on KVR Audio.

Download

macOS (13+)

Signed and notarized apps you can install and run without using Terminal. Contains the full editor as a menu-bar app plus the hardware-free Library app.

• Apple Silicon
• Intel

Linux

The hardware-free Library app:

• AppImage
• tar.gz

The full editor runs via the launcher in the release ZIP.

Any platform

The latest release ZIP has launchers for macOS, Linux and Windows, needing only Python 3.

Features

• SAMPLES:
  • 36-slot bank overview
  • Audition on the device (honors start/end points) with a playhead on the waveform
  • On-screen keyboard mirroring the 36 pads. Click to play, or tick ⌨ TYPE TO PLAY to play from your computer keyboard (Z/X shift octave). A SAMPLE / KEYBOARD toggle switches between triggering one sample per key (empty keys dimmed) and playing the selected sample pitched across the keyboard
  • MIDI IN: play the device from a connected MIDI keyboard, with velocity, pitch bend and sustain pedal (uses the browser's Web MIDI, and honors the SAMPLE / KEYBOARD mode)
  • WAV download/upload (auto-resample to 48/24/12/6 kHz). Drop several WAVs onto the pads to bulk-fill consecutive slots
  • Auto-slice can split a long recording across consecutive pads, either by equal divisions or by detected transients (great for drum breaks and loops)
  • Upload processing includes normalize, gain, silence trimming, fades, and mono/stereo conversion (done in-browser before transfer)
  • Filter pads by name
  • Live editing of all sample parameters
  • Draggable START/END markers on the waveform (or type exact frame values), with optional zero-crossing snap so trims don't click
  • Editable original BPM (the sample tempo used for BPM-sync). Applying it re-uploads the sample, keeping its audio and other settings
  • The waveform view supports scroll-wheel zoom and click-drag panning, which makes it easier to line up trims on short drum hits or transients
    • Stereo samples show as two half-height lanes (left above right) so each channel reads on its own
  • Renaming banks and samples
  • All samples preload on connect, and again when you switch banks on the device (re-synced when you return to the app). Progress is shown, so the memory meter is exact and waveforms are instant
  • FOLLOW toggle (on by default): the selection tracks the last sample triggered on the device, whether you play it or a pattern does
• EFFECT:
  • All 22 effect types with their full parameter sets
  • Hover any parameter to see its range and default
  • The two assignable FX knobs (panel knob movements tracked live)
  • Conditional parameter graying/swapping exactly like the hardware
• PATTERNS:
  • Receive all 16 patterns
  • Mini piano-roll preview + play patterns on the device (per-pattern ▶)
  • In-app piano-roll editor over both the sample-mode (pad) and keyboard-mode (pitched) tracks:
    • Draw / Erase / Select tools (the cursor changes to match), with move/resize, drag-to-erase and a marquee for multi-select
    • Multi-select (Shift/⌘-click), undo/redo, and copy/paste whose clipboard persists across patterns (copy from one, paste into another)
    • Per-note velocity shown as note brightness. Arrow keys nudge or resize
    • Space plays/stops the pattern on the device. Clicking outside the dialog saves and closes
    • Set the bar count, grid snap and the keyboard track's sample, then save back to the device (build a pattern from scratch on an empty slot, too)
  • Import and Export MIDI files
  • Remote record trigger (presses the device's [REC] over MIDI, so watch the device screen)
• UTILITY:
  • Full bank backup/restore (RAM or persistent user banks)
  • Cherry-pick restore: copy a single sample out of a backup into any pad of the current bank
  • Remote sampling trigger (input select + [SAMPLING] over MIDI, with no device-state readback, so watch the device screen)
• Live two-way sync:
  • Panel edits on the device show up in the app instantly
• Master volume slider for the device output, and a panic button (all sound off / stop) for stuck notes
• 12 accent themes picked from a swatch dropdown. The whole interface (buttons, LCD, waveform, keys) recolours to match
• Remembers your last-open view across reloads
• Tells you when a newer release is available (checks GitHub, dismissible)
• Library mode (no hardware): import original Korg .msmpl_bank backups (or this app's .zip backups), browse and play their samples in the browser, export them as WAVs, and recover the recorded patterns as MIDI files. Useful if you have old .msmpl_bank backups and want to recover the samples or recorded patterns from them.

Requirements

The desktop apps above bundle everything (macOS 13+ / Linux x86-64). The requirements below apply to the classic ZIP + launchers:

• macOS (tested), Linux (should work) or Windows (untested)
• Python 3.8+ is the only thing you install.
  • pyusb (BSD) and libusb (LGPL) are bundled in src/native-tools/vendor/, so there's no pip or Homebrew step.
  • A system pyusb/libusb, if you have one installed, is used in preference, and the bundled copies are just a fallback.
  • A newer system libusb, e.g. brew install libusb, can be more robust across reconnects.
• Chrome/Chromium recommended, but any modern should work
• A Korg microSAMPLER connected with USB

Run

Installed the apps? Just open them. The Editor app puts a ♪ in the menu bar and opens the editor, and the Library app opens straight into the librarian.

Where's the sound? The editor plays everything on the microSAMPLER itself (pads, audition, the on-screen keyboard, patterns), so you hear it from the device's own outputs, not your computer's speakers. That way you hear exactly what the hardware sounds like, envelope and effects included. The Library app works without the device, so it plays samples through your computer instead.

The rest of this section is the classic ZIP way:

Open the folder for your platform (macOS/, Linux/, or Windows/) and double-click microSAMPLER Editor Librarian (.command / .sh / .bat). It starts the bridge and opens the editor in your browser automatically. Each folder also has a microSAMPLER Library launcher, see Library mode below.

• macOS:
  • The launcher is unsigned, so the first run is blocked ("unidentified developer").
  • Approve it once: right-click (Control-click) the launcher → Open → Open.
  • On newer macOS without an Open option, double-click once, then System Settings → Privacy & Security → Open Anyway. (Or clear the quarantine in a terminal: xattr -dr com.apple.quarantine "<unzipped folder>".)
• Linux:
  • Mark the .sh executable / "Allow launching" first, or run ./'Linux/microSAMPLER Editor Librarian.sh' from a terminal.
• Windows (experimental/untested):
  • The device's USB driver must first be switched to WinUSB with Zadig so libusb can open it.

macOS and Linux ask for your password, because root is required to claim the USB interface from the OS MIDI driver.

Manual

sudo python3 src/native-tools/bridge.py   # macOS/Linux (root for USB)
py -3 src/native-tools\bridge.py          # Windows

Then open http://localhost:8765

UI development without hardware

python3 src/native-tools/bridge.py --mock

Library mode (no hardware)

To browse and extract samples from bank backups with no microSAMPLER connected (for example to recover audio from old .msmpl_bank files saved by Korg's original editor), run the bridge in library mode:

python3 src/native-tools/bridge.py --library

Library mode serves on http://localhost:8766, a separate port from the device bridge's 8765, so it never clashes with (or attaches to) a running device bridge. Or just double-click the microSAMPLER Library launcher in your platform's folder (macOS/, Linux/, Windows/). No password is needed, since library mode never touches USB. Open the editor, go to LIBRARY, and use OPEN BANK FILE… to import a .msmpl_bank (original Korg) or a .zip (this app's) backup. You can then play each sample in the browser, download individual WAVs, or grab the whole bank as a ZIP of WAVs. If the bank holds recorded patterns, they're listed below the pads. Download each as a MIDI file, or all of them as a .mid ZIP.

To extract straight to WAVs from the command line, without the app:

python3 src/native-tools/msmpl_bank.py info    "my bank.msmpl_bank"   # list samples
python3 src/native-tools/msmpl_bank.py extract "my bank.msmpl_bank"   # -> WAVs + manifest

Bank backups land in src/native-tools/backups/ (gitignored, they're your data). Note that sample/parameter transfers target the device's current bank (RAM). Save on the device or restore to a user bank to persist.

Repository layout

src/                          application source (everything that ships)
  web-editor/                 the browser app (served by the bridge)
  native-tools/               Python bridge + CLI tools (libusb USB-MIDI):
    bridge.py                   HTTP/SSE server the app talks to
    download.py / upload.py     single-sample transfer CLIs
    bank.py                     full-bank backup/restore CLI
    msusb.py                    transport + diagnostics (inquiry/monitor/…)
    protocol.py                 Korg SysEx/bulk protocol (offline self-test)
    test_*.py                   offline regression suite (mock device)
  launchers/                  double-clickable launchers per OS (macOS/, Linux/,
                              Windows/), each with a device "Editor Librarian"
                              and a no-hardware "Library"
tools/                        dev + build + packaging (not shipped as the app):
  build.mjs / pack.mjs          minified dist/ + release ZIP
  re/                           reverse-engineering toolkit (needs the original
                                Korg installer, not included) — regenerates
                                src/web-editor/functions/fxData.js etc.
  bundle/                       the desktop apps: PyInstaller specs + entries,
                                the Swift menu-bar shell, DMG/AppImage/notarize
                                scripts (built by workflows/package.yml)
  make_app_icon.sh              give the launcher its icon (run once, macOS)
test/                         unit/ (node --test) + e2e/ (Playwright smoke)
docs/                         the documentation site (published to GitHub Pages)

The packaged ZIP is flattened for convenience: web-editor/, native-tools/, and the per-OS launcher folders sit at its top level, not under src/.

Development

See ARCHITECTURE.md for how the bridge, browser app, and device fit together, and CONTRIBUTING.md to get started.

Run the offline test suite (no hardware needed):

cd src/native-tools
python3 protocol.py                       # protocol self-test
for t in test_*.py; do python3 "$t"; done # every offline test (same as CI)

JavaScript unit tests for the pure modules (audio DSP + value encoders), via Node's built-in test runner (no deps):

npm test        # Node's built-in runner over test/unit/*.test.mjs

There isn't a frontend build step during development. The browser loads the ES modules directly from src/web-editor/.

End-to-end browser smoke (boots the mock bridge, drives the app headless, fails on any page/console error or broken interaction):

pip install playwright && playwright install chromium
python3 test/e2e/smoke.py        # reuses a bridge already on the port, else starts a mock one

Linting

Bug-focused linters (dev-only, not runtime dependencies) keep the no-build code honest. They catch undefined names, unused imports, etc. CI runs both.

# Python (src/native-tools/ + tools/) — needs ruff (pip install ruff)
ruff check

# JavaScript (src/web-editor/) — needs the dev deps (npm install)
npm run lint:js

Build a release

To create a smaller distribution build for releases (JS bundled + minified, CSS merged + minified, HTML comments stripped, dev/RE/test files excluded):

npm install      # one dev-only dependency: esbuild (MIT)
npm run build    # -> dist/
sudo python3 dist/native-tools/bridge.py

npm run pack     # -> dist/ + release/microsampler-editor-librarian-vX.Y.Z.zip

dist/ mirrors the run layout (web-editor/ + native-tools/ + launcher) and runs exactly like the source. esbuild is build-time only, so the app ships no runtime npm dependencies.

npm run pack builds dist/ and packages it into the release ZIP under release/, named to match the version (<name>-vX.Y.Z.zip) and the docs download link, with a single top-level folder and the launchers kept executable. Upload that ZIP to the GitHub release. The packer is plain Node (no zip binary needed).

Bumping the version with npm version <new> automatically stamps it into the docs download link and structured data (the version lifecycle runs npm run stamp-version and stages docs/index.html into the version commit), so the Download vX.Y.Z (ZIP) button on the site always points at the matching release asset. Run npm run stamp-version manually if you bump the version some other way.

Cutting a release

1. npm version <new> (stamps the docs/bridge version, commits, tags vX.Y.Z).
2. Push the commit and the tag.
3. Publish a GitHub release for that tag (write the notes).

Publishing triggers two workflows:

• Release: (.github/workflows/release.yml) attaches the source ZIP (microsampler-editor-librarian-vX.Y.Z.zip)
• Package apps: (.github/workflows/package.yml) builds, signs, notarizes and attaches the macOS DMGs and the Linux AppImage + tar.gz.

Both verify the tag matches package.json first.

Disclaimer

This is an independent, unofficial project. It is not affiliated with, endorsed, sponsored, or supported by Korg Inc. microSAMPLER and Korg are trademarks of Korg Inc., used here only to identify the hardware this software interoperates with.

This repository contains no Korg software, firmware, or other Korg copyrighted material. The communication protocol was independently reverse-engineered for the sole purpose of interoperability with hardware owned by the user (as permitted by, e.g., Directive 2009/24/EC art. 6 in the EU/EEA).

Use at your own risk. This software is provided “as is”, without warranty of any kind, as set out in sections 15–16 of the GNU GPL v3. The author accepts no responsibility or liability for any damage to your device, loss of samples, patterns or other data, or any other consequence of using this software. It writes to the device's memory, so back up your bank (UTILITY → BACKUP) before bulk operations, and never disconnect the device mid-transfer.

---

Made by Benjamin Dehli / Dehli Musikk (not affiliated with Korg).

Licensed under the GNU GPL v3.

microSAMPLER is a trademark of Korg Inc.