PrimoKKMK1Bridge
Custom Native Instruments Komplete Kontrol S-series MK1 (S25/S49/S61/S88) MIDI controller driver for macOS; bringing complete configurability (every button, knob and touch), basic NKS support and Reaper DAW integration to the no longer supported MIDI controller. PrimoKKMK1Bridge replaces the need for the Native Instruments drivers (NIHardwareAgent, NIHostIntegrationAgent) and Controller Editor.
It comes as two programs:
- The bridge (
PrimoKKMK1Bridge) talks to the keyboard and runs in the background - replaces the proprietary Native Instruments drivers.
- The editor (PrimoKKMK1Editor) is a Mac app for changing the assignments and settings of the keyboard, and for starting and stopping the bridge - replaces the Native Instruments Controller Editor.
PrimoKKMK1Editor contains an embedded PrimoKKMK1Bridge so there is no need to install anything else.
Using it: the user guide covers installing, setup, starting at
login, every mode and view, every default assignment, and the config file. The editor's Help menu opens it. Its
source is doc/GUIDE.md.
Tested on an S61 MK1 (firmware 72) with macOS 26 and REAPER 7.61.
How it works
On connect, the bridge sends the keyboard the same 3-byte HID "init" (a0 00 00) that NI's software and
DrivenByMoss send. That switches it from MIDI mode to native mode, where every button, knob touch and knob turn
is reported over USB HID, and the computer drives the lights and displays. The bridge turns those reports into
MIDI CCs, or in REAPER mode into OSC messages to REAPER. The keys and strips keep coming from the keyboard's own
MIDI port, and are merged into the bridge's port too. The protocol details are in doc/NOTES.md.
What's where
| Where | What |
|---|
| bridge/Sources/ | The bridge, one file per area: main.swift (command line, startup, restarts), Bridge*.swift (the keyboard's reports, lights, displays, REAPER mode, light guide), MIDIPorts.swift, OSC.swift, Reaper*.swift, Config.swift (every config key, its default and validation) |
| editor/Sources/ | The editor: the keyboard drawing, the inspector, the Settings page, the bridge switch, launching the bridge at login, and the REAPER script installer |
| reaper/ | A script for REAPER that sends the selected track's colour to the bridge, for the light guide |
| doc/ | The user guide (GUIDE.md) and its pictures, the user guide website's theme overrides and stylesheet (site/), the keyboard's protocol notes (NOTES.md), and which HID bit each button sets (BUTTON_MAP.md) |
| design/ | The spec for the Komplete Kontrol view |
| tools/ | HID and MIDI monitors, the capture tool, midisend, a stand-in REAPER for testing, and the scripts that stamp the version and draw the guide's pictures |
| device/ | Raw captures and recorded test runs |
Build and run
You need:
- macOS 14 or later
- Xcode, or Apple's Command Line Tools (
xcode-select --install). Tested with Xcode 27 (Swift 6.4).
Run the commands from the repository's top folder. Everything is built into build/, which git ignores.
The editor app, with the bridge inside it
editor/build.sh
open build/PrimoKKMK1Editor.app
editor/build.sh builds build/PrimoKKMK1Editor.app: the editor, its own copy of the bridge, the REAPER script,
and the app icon. It's signed for this Mac only (ad hoc), not notarized. In the editor, turn on the bridge switch
in the toolbar: the bridge then runs in the background and keeps running after you quit the editor. Saved
changes apply to a running bridge within a second or two.
After pulling changes, run editor/build.sh again. A running bridge isn't disturbed: turn it off and on in the
editor to run the new copy.
The app is built for this Mac's processor. editor/build.sh --arch universal builds one that also runs on the other
kind (Apple Silicon and Intel), at about twice the size; --arch arm64 or --arch x86_64 picks one. Whatever the
architecture, the editor and the bridge need macOS 14 or later.
The bridge on its own, in Terminal
bridge/build.sh
build/PrimoKKMK1Bridge --verbose
bridge/build.sh builds build/PrimoKKMK1Bridge; editor/build.sh doesn't, so run both after a bridge change if
you use this copy (for the replay tests below, say). --verbose prints every message the bridge sends; Ctrl-C
quits. Run one bridge at a time: the editor's switch also stops a bridge started this way.
Other options: --config FILE runs with another config file, --print-default-config prints every default,
--log-osc also prints what REAPER sends, and --version prints the version.
After building
- Config file:
~/Library/Application Support/PrimoStudios/PrimoKKMK1Bridge/PrimoKKMK1Bridge.json. The
bridge or the editor creates it with every default the first time; a new config starts in MIDI mode.
- REAPER: turn REAPER mode on in the editor's Settings page, and set up REAPER's OSC device as described in
Set up REAPER.
- The guide's pictures are drawn from the editor's own drawing: run
tools/render_guide_images.sh after
changing a default or the drawing.
The user guide website
The user guide is also a website, made with
MkDocs and its built-in theme from doc/GUIDE.md (see mkdocs.yml and doc/site/), and served by GitHub
Pages from the gh-pages branch. After changing the guide, preview the site, then publish it:
tools/build_site.sh serve
tools/build_site.sh deploy
여기까지가 README 앞부분입니다. 나머지는 원문에서 읽을 수 있습니다. README 전문 보기 ↗
