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

This is the beginning of the README. Read the rest at the original. Read the full README ↗