{"id":51171516,"url":"https://github.com/benjamindehli/microsampler-editor-librarian","last_synced_at":"2026-06-27T01:01:25.975Z","repository":{"id":362896103,"uuid":"1260674472","full_name":"benjamindehli/microsampler-editor-librarian","owner":"benjamindehli","description":"A modern editor/librarian for the Korg microSAMPLER","archived":false,"fork":false,"pushed_at":"2026-06-23T16:18:13.000Z","size":17438,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-06-23T17:24:36.968Z","etag":null,"topics":["editor","javascript","korg","korg-microsampler","librarian","microsampler","midi","music-production","python","sampler","sampler-editor","sysex","usb-midi","web-audio"],"latest_commit_sha":null,"homepage":"https://benjamindehli.github.io/microsampler-editor-librarian/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/benjamindehli.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"ko_fi":"benjamindehli","custom":"https://store.dehlimusikk.no/coffee"}},"created_at":"2026-06-05T18:45:05.000Z","updated_at":"2026-06-23T16:18:18.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/benjamindehli/microsampler-editor-librarian","commit_stats":null,"previous_names":["benjamindehli/micro-sampler-editor","benjamindehli/microsampler-editor-librarian"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/benjamindehli/microsampler-editor-librarian","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benjamindehli%2Fmicrosampler-editor-librarian","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benjamindehli%2Fmicrosampler-editor-librarian/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benjamindehli%2Fmicrosampler-editor-librarian/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benjamindehli%2Fmicrosampler-editor-librarian/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/benjamindehli","download_url":"https://codeload.github.com/benjamindehli/microsampler-editor-librarian/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benjamindehli%2Fmicrosampler-editor-librarian/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34838035,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-26T02:00:06.560Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["editor","javascript","korg","korg-microsampler","librarian","microsampler","midi","music-production","python","sampler","sampler-editor","sysex","usb-midi","web-audio"],"created_at":"2026-06-27T01:00:38.402Z","updated_at":"2026-06-27T01:01:25.941Z","avatar_url":"https://github.com/benjamindehli.png","language":"Python","funding_links":["https://ko-fi.com/benjamindehli","https://store.dehlimusikk.no/coffee"],"categories":[],"sub_categories":[],"readme":"# microSAMPLER Editor / Librarian\n\n![CI](https://github.com/benjamindehli/microsampler-editor-librarian/actions/workflows/ci.yml/badge.svg)\n\nA modern editor/librarian for the **Korg microSAMPLER**, replacing Korg's original 32-bit application (PPC/i386) that no longer runs on macOS 10.15+.\nThe hardware protocol was reverse-engineered from the original binary and verified against a real device.\nThis app covers everything the original did, plus a few things it didn't.\n\n![A Korg microSAMPLER in front of a laptop running the microSAMPLER Editor / Librarian](docs/assets/hardware/setup_792.jpg)\n\n📖 **[Full documentation \u0026 guide →](https://benjamindehli.github.io/microsampler-editor-librarian/)**\n\n## Features\n\n- **SAMPLES**:\n  - 36-slot bank overview\n  - Audition on the device (honors start/end points) with a playhead on the waveform\n  - On-screen keyboard mirroring the 36 pads — click to play, or tick **⌨ TYPE TO\n    PLAY** to play from your computer keyboard (Z/X shift octave). A **SAMPLE /\n    KEYBOARD** toggle switches between triggering one sample per key (empty keys\n    dimmed) and playing the selected sample pitched across the keyboard\n  - **MIDI IN** — play the device from a connected MIDI keyboard, with velocity,\n    pitch bend and sustain pedal (uses the browser's Web MIDI; honors the SAMPLE /\n    KEYBOARD mode)\n  - WAV download/upload (auto-resample to 48/24/12/6 kHz); drop several WAVs\n    onto the pads to bulk-fill consecutive slots\n  - Auto-slice — chop one long sample across consecutive pads, by equal pieces\n    or detected transients (great for drum breaks and loops)\n  - Audio tools on upload — normalize, gain, trim silence, fade in/out,\n    mono ↔ stereo (processed in-browser before transfer)\n  - Filter pads by name\n  - Live editing of all sample parameters\n  - Draggable START/END markers on the waveform (or type exact frame values),\n    with optional zero-crossing snap so trims don't click\n  - Editable original BPM (the sample tempo used for BPM-sync) — re-uploads the\n    sample to apply, keeping its audio and other settings\n  - Zoomable / pannable waveform (scroll to zoom, drag to pan) for\n    sample-accurate trimming\n  - Renaming banks and samples\n  - All samples preload on connect — and again when you switch banks on the\n    device (re-synced when you return to the app) — with progress shown, so the\n    memory meter is exact and waveforms are instant\n  - **FOLLOW** toggle (on by default) — the selection tracks the last sample\n    triggered on the device, whether you play it or a pattern does\n- **EFFECT**:\n  - All 22 effect types with their full parameter sets\n  - Hover any parameter to see its range and default\n  - The two assignable FX knobs (panel knob movements tracked live)\n  - Conditional parameter graying/swapping exactly like the hardware\n- **PATTERNS**:\n  - Receive all 16 patterns\n  - Mini piano-roll preview + play patterns on the device (per-pattern ▶)\n  - In-app **piano-roll editor** over both the sample-mode (pad) and\n    keyboard-mode (pitched) tracks:\n    - **Draw / Erase / Select** tools (the cursor changes to match), with\n      move/resize, drag-to-erase and a marquee for multi-select\n    - **Multi-select** (Shift/⌘-click), **undo/redo**, and **copy/paste** whose\n      clipboard persists across patterns (copy from one, paste into another)\n    - Per-note velocity shown as note brightness; arrow keys nudge or resize\n    - **Space** plays/stops the pattern on the device; clicking outside the\n      dialog saves and closes\n    - Set the bar count, grid snap and the keyboard track's sample, then save\n      back to the device (build a pattern from scratch on an empty slot, too)\n  - Import and Export MIDI files\n  - Remote record trigger (presses the device's [REC] over MIDI; watch the\n    device screen)\n- **UTILITY**:\n  - Full bank backup/restore (RAM or persistent user banks)\n  - Cherry-pick restore — copy a single sample out of a backup into any pad\n    of the current bank\n  - Remote sampling trigger (input select + [SAMPLING] over MIDI; no\n    device-state readback, so watch the device screen)\n- **Live two-way sync**:\n  - Panel edits on the device show up in the app instantly\n- **Master volume** slider for the device output, and a **panic** button\n  (all sound off / stop) for stuck notes\n- **12 accent themes** picked from a swatch dropdown — the whole interface\n  (buttons, LCD, waveform, keys) recolours to match\n- Remembers your last-open view across reloads\n- Tells you when a newer release is available (checks GitHub; dismissible)\n- **Library mode** (no hardware): import original Korg `.msmpl_bank` backups (or\n  this app's `.zip` backups), browse and play their samples in the browser,\n  export them as WAVs, and recover the recorded patterns as MIDI files — handy\n  for getting audio and sequences out of old backups\n\n## Requirements\n\n- macOS (tested), Linux (should work) or Windows (untested)\n- **Python 3.8+** — that's the only thing you install.\n  [pyusb](https://github.com/pyusb/pyusb) (BSD) and\n  [libusb](https://libusb.info/) (LGPL) are bundled in\n  [`native-tools/vendor/`](native-tools/vendor/), so there's no `pip` or\n  Homebrew step. (A system pyusb/libusb, if you have one installed, is used in\n  preference — the bundled copies are just a fallback. A newer system libusb,\n  e.g. `brew install libusb`, can be more robust across reconnects.)\n- Chrome/Chromium recommended (any modern should work)\n- A Korg microSAMPLER connected with USB\n\n## Run\n\nOpen the folder for your platform — **`macOS/`**, **`Linux/`**, or **`Windows/`**\n— and double-click **`microSAMPLER Editor Librarian`** (`.command` / `.sh` /\n`.bat`). It starts the bridge and opens the editor in your browser automatically.\n(Each folder also has a **`microSAMPLER Library`** launcher — see\n[Library mode](#library-mode-no-hardware) below.)\n\n- **macOS:** the launcher is unsigned, so the first run is blocked (\"unidentified\n  developer\"). Approve it once: right-click (Control-click) the launcher →\n  **Open** → **Open**. On newer macOS without an *Open* option, double-click once,\n  then **System Settings → Privacy \u0026 Security → Open Anyway**. (Or clear the\n  quarantine in a terminal: `xattr -dr com.apple.quarantine \"\u003cunzipped folder\u003e\"`.)\n- **Linux:** mark the `.sh` executable / \"Allow launching\" first, or run\n  `./'Linux/microSAMPLER Editor Librarian.sh'` from a terminal.\n- **Windows:** **experimental/untested** — the device's USB driver must first be\n  switched to WinUSB with [Zadig](https://zadig.akeo.ie/) so libusb can open it.\n\nmacOS and Linux ask for your password — root is required to claim the USB\ninterface from the OS MIDI driver.\n\n### Manual\n\n```bash\nsudo python3 native-tools/bridge.py   # macOS/Linux (root for USB)\npy -3 native-tools\\bridge.py          # Windows\n```\n\nThen open http://localhost:8765\n\n### UI development without hardware\n\n```bash\npython3 native-tools/bridge.py --mock\n```\n\n### Library mode (no hardware)\n\nTo browse and extract samples from bank backups with no microSAMPLER connected —\nfor example to recover audio from old `.msmpl_bank` files saved by Korg's\noriginal editor — run the bridge in library mode:\n\n```bash\npython3 native-tools/bridge.py --library\n```\n\nLibrary mode serves on **http://localhost:8766** — a separate port from the\ndevice bridge's 8765, so it never clashes with (or attaches to) a running device\nbridge.\nOr just double-click the **`microSAMPLER Library`** launcher in your platform's\nfolder (`macOS/`, `Linux/`, `Windows/`) — no password needed, since library mode\nnever touches USB.\nOpen the editor, go to **LIBRARY**, and use **OPEN BANK FILE…** to import a\n`.msmpl_bank` (original Korg) or a `.zip` (this app's) backup.\nYou can then play each sample in the browser, download individual WAVs, or grab\nthe whole bank as a ZIP of WAVs.\nIf the bank holds recorded patterns, they're listed below the pads — download\neach as a MIDI file, or all of them as a `.mid` ZIP.\n\nTo extract straight to WAVs from the command line, without the app:\n\n```bash\npython3 native-tools/msmpl_bank.py info    \"my bank.msmpl_bank\"   # list samples\npython3 native-tools/msmpl_bank.py extract \"my bank.msmpl_bank\"   # -\u003e WAVs + manifest\n```\n\nBank backups land in `native-tools/backups/` (gitignored, they're your data).\nNote that sample/parameter transfers target the device's **current bank (RAM)**; save on the device or restore to a user bank to persist.\n\n## Repository layout\n\n```text\nmacOS/ Linux/ Windows/        double-clickable launchers per OS — each has\n                              \"microSAMPLER Editor Librarian\" (device) and\n                              \"microSAMPLER Library\" (no-hardware librarian)\nweb-editor/                   the browser app (served by the bridge)\nnative-tools/                 Python bridge + CLI tools (libusb USB-MIDI):\n  bridge.py                     HTTP/SSE server the app talks to\n  download.py / upload.py       single-sample transfer CLIs\n  bank.py                       full-bank backup/restore CLI\n  msusb.py                      transport + diagnostics (inquiry/monitor/…)\n  protocol.py                   Korg SysEx/bulk protocol (offline self-test)\n  test_*.py                     offline regression suite (mock device)\ntools/re/                     reverse-engineering toolkit (needs the original\n                              Korg installer, not included) — regenerates\n                              web-editor/js/fxData.js etc.\ntools/make_app_icon.sh        give the launcher its icon (run once, macOS)\n```\n\n## Development\n\nSee [ARCHITECTURE.md](ARCHITECTURE.md) for how the bridge, browser app, and\ndevice fit together, and [CONTRIBUTING.md](CONTRIBUTING.md) to get started.\n\nRun the offline test suite (no hardware needed):\n\n```bash\ncd native-tools\npython3 protocol.py \u0026\u0026 python3 test_download.py \u0026\u0026 python3 test_upload.py \\\n  \u0026\u0026 python3 test_bank.py \u0026\u0026 python3 test_bridge.py\n```\n\nJavaScript unit tests for the pure modules (audio DSP + value encoders), via\nNode's built-in test runner (no deps):\n\n```bash\nnpm test        # node --test test/*.test.mjs\n```\n\nThe app needs **no build step** to develop or run — it's plain ES modules and per-component CSS served straight from `web-editor/`.\n\nEnd-to-end browser smoke (boots the mock bridge, drives the app headless, fails\non any page/console error or broken interaction):\n\n```bash\npip install playwright \u0026\u0026 playwright install chromium\npython3 e2e/smoke.py        # reuses a bridge already on the port, else starts a mock one\n```\n\n### Linting\n\nBug-focused linters (dev-only; not runtime dependencies) keep the no-build code\nhonest — they catch undefined names, unused imports, etc. CI runs both.\n\n```bash\n# Python (native-tools/ + tools/) — needs ruff (pip install ruff)\nruff check\n\n# JavaScript (web-editor/js/) — needs the dev deps (npm install)\nnpm run lint:js\n```\n\n## Build a release\n\nTo produce a lean, minified `dist/` for publishing (JS bundled + minified, CSS merged + minified, HTML comments stripped, dev/RE/test files excluded):\n\n```bash\nnpm install      # one dev-only dependency: esbuild (MIT)\nnpm run build    # -\u003e dist/\nsudo python3 dist/native-tools/bridge.py\n\nnpm run pack     # -\u003e dist/ + release/microsampler-editor-librarian-vX.Y.Z.zip\n```\n\n`dist/` mirrors the run layout (`web-editor/` + `native-tools/` + launcher) and runs exactly like the source.\n`esbuild` is build-time only — the app ships no runtime npm dependencies.\n\n`npm run pack` builds `dist/` and packages it into the release ZIP under `release/`,\nnamed to match the version (`\u003cname\u003e-vX.Y.Z.zip`) and the docs download link, with a\nsingle top-level folder and the launchers kept executable. Upload that ZIP to the\nGitHub release. The packer is plain Node (no `zip` binary needed).\n\nBumping the version with `npm version \u003cnew\u003e` automatically stamps it into the\ndocs download link and structured data (the `version` lifecycle runs\n`npm run stamp-version` and stages `docs/index.html` into the version commit), so\nthe **Download vX.Y.Z (ZIP)** button on the site always points at the matching\nrelease asset. Run `npm run stamp-version` manually if you bump the version some\nother way.\n\n### Cutting a release\n\n1. `npm version \u003cnew\u003e` (stamps the docs/bridge version, commits, tags `vX.Y.Z`).\n2. Push the commit and the tag.\n3. Publish a GitHub release for that tag (write the notes).\n\nPublishing triggers the **Release** workflow\n(`.github/workflows/release.yml`), which verifies the tag matches `package.json`,\nruns `npm run pack`, and attaches `microsampler-editor-librarian-vX.Y.Z.zip` to the\nrelease. (You can also run `npm run pack` locally and upload the ZIP from\n`release/` by hand.)\n\n## Disclaimer\n\nThis is an **independent, unofficial project**. It is not affiliated with, endorsed, sponsored, or supported by Korg Inc.\n*microSAMPLER* and *Korg* are trademarks of Korg Inc., used here only to identify the hardware this software interoperates with.\n\nThis repository contains **no Korg software, firmware, or other Korg copyrighted material**.\nThe 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).\n\n**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](LICENSE).\nThe 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.\nIt writes to the device's memory — **back up your bank** (UTILITY → BACKUP) before bulk operations, and never disconnect the device mid-transfer.\n\n---\n\n\u003cimg src=\"web-editor/assets/svg/DehliMusikkLogoInverse.svg\" alt=\"Dehli Musikk\" width=\"160\"\u003e\n\nMade by Benjamin Dehli / Dehli Musikk (not affiliated with Korg).\n\nLicensed under the [GNU GPL v3](LICENSE).\n\nmicroSAMPLER is a trademark of Korg Inc.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbenjamindehli%2Fmicrosampler-editor-librarian","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbenjamindehli%2Fmicrosampler-editor-librarian","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbenjamindehli%2Fmicrosampler-editor-librarian/lists"}