PrimoKKMK1Bridge user guide¶

PrimoKKMK1Bridge makes a Native Instruments Komplete Kontrol S-series MK1 keyboard (S25, S49, S61, S88) fully usable on macOS without Native Instruments' software:

• every button, knob and touch sends MIDI on a virtual port, Primo Komplete Kontrol MK1
• the button lights and the nine displays are driven
• an optional REAPER mode turns the keyboard into a REAPER control surface

It comes as two programs:

• The bridge (PrimoKKMK1Bridge) talks to the keyboard and does the work. It runs in the background.
• The editor (Primo KK MK1 Control Editor) is a Mac app for changing what every control does. It starts and stops the bridge.

What you need¶

• A Komplete Kontrol S-series MK1 keyboard. Tested on an S61 MK1, firmware 72. The S25, S49 and S88 should work but haven't been tried.
• A Mac with macOS 14 or later, Apple Silicon or Intel. Each release has a download for Apple Silicon, and from version 1.1 a universal one that also runs on Intel Macs. On an Intel Mac with an earlier version, build it from source.
• For REAPER mode: REAPER (tested with 7.61).

Install¶

1. From the releases page, download PrimoKKMK1Editor-<version>-macOS-arm64.zip for an Apple Silicon Mac, or PrimoKKMK1Editor-<version>-macOS-universal.zip for an Intel Mac (it runs on either), and unzip it.
2. Move PrimoKKMK1Editor.app to your Applications folder. That's the recommended place: starting the bridge at login uses the app where it is. The bridge is inside the app, so there's nothing else to install.
3. The app is signed for local use only, not notarized by Apple, so macOS blocks it the first time. Either open it once and click Open Anyway in System Settings ▸ Privacy & Security, or run this in Terminal:

   xattr -dr com.apple.quarantine /Applications/PrimoKKMK1Editor.app

   Use the xattr command if you'll start the bridge at login: it clears the bridge inside the app too.

To build it yourself instead, see Build and run.

Getting started¶

1. Plug in the keyboard and open Primo KK MK1 Control Editor.
2. Turn on the bridge switch in the toolbar. The light next to it turns green, the keyboard's buttons light up, and the displays wake up.
3. In your DAW, use the MIDI input Primo Komplete Kontrol MK1. It carries the keys, the pitch and mod strips and every control, so one input is all a track needs.

Good to know:

• Don't give a track both ports. The keyboard's own port, KOMPLETE KONTROL S61 Port 1, still sends the keys too, so never give a track that and Primo Komplete Kontrol MK1, or All MIDI inputs: every note would arrive twice.
• The bridge keeps running when you quit the editor. Turn the switch off to stop it.
• After the bridge stops, the keyboard stays in native mode, with silent knobs, until you unplug and replug it or start the bridge again.
• The config file is created the first time you run the editor or the bridge, with every default: ~/Library/Application Support/PrimoStudios/PrimoKKMK1Bridge/PrimoKKMK1Bridge.json. A new config starts in MIDI mode. For REAPER, turn on Enabled under REAPER Mode on the editor's Settings page.

Start the bridge at login¶

To have the bridge start when you log in, without the editor, turn on Launch Bridge at Login under Login on the editor's Settings page. It applies right away, without saving, and starts the copy of the bridge inside the app where the app is now, so move the app to your Applications folder first. It takes effect at your next login; to start the bridge now too, use the bridge switch.

How it behaves:

• After a crash, it's started again.
• With the editor's switch, you can still turn it off. That's a normal quit, so it stays off until your next login, and the switch can turn it back on.
• Its output goes to ~/Library/Logs/PrimoKKMK1Bridge.log, the same log the editor's Show Log opens.
• If you move the app, the Settings page shows the copy it starts, with Use This App to switch to the one you're running.
• Turning it off stops it starting at your next login. A bridge it already started keeps going until you turn it off with the switch or log out.

Under the hood it's a LaunchAgent, ~/Library/LaunchAgents/com.primostudios.PrimoKKMK1Bridge.plist.

mkdir -p ~/Library/LaunchAgents ~/Library/Logs && cat > ~/Library/LaunchAgents/com.primostudios.PrimoKKMK1Bridge.plist <<EOF
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key><string>com.primostudios.PrimoKKMK1Bridge</string>
    <key>ProgramArguments</key>
    <array><string>/Applications/PrimoKKMK1Editor.app/Contents/MacOS/PrimoKKMK1Bridge</string></array>
    <key>RunAtLoad</key><true/>
    <key>KeepAlive</key><dict><key>SuccessfulExit</key><false/></dict>
    <key>ProcessType</key><string>Interactive</string>
    <key>StandardOutPath</key><string>$HOME/Library/Logs/PrimoKKMK1Bridge.log</string>
    <key>StandardErrorPath</key><string>$HOME/Library/Logs/PrimoKKMK1Bridge.log</string>
</dict>
</plist>
EOF

launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.primostudios.PrimoKKMK1Bridge.plist

launchctl bootout gui/$(id -u)/com.primostudios.PrimoKKMK1Bridge; rm ~/Library/LaunchAgents/com.primostudios.PrimoKKMK1Bridge.plist

The editor¶

The editor shows a drawing of the keyboard. Click a button, knob or strip, and the panel on the right shows what it does and lets you change it. Each control on the drawing is labelled with its current assignment, and a second line starting with ⇧ shows what it does with Shift held.

The pages, chosen in the toolbar, follow the mode you're in:

Settings has these sections. REAPER Views, Reaper Lightguide and Komplete Kontrol View appear only while REAPER mode is on.

Reset to Default Settings…, at the bottom, puts every setting and assignment back to its default, apart from REAPER mode. Nothing is written until you save.

Other things in the editor:

• Saving: Save (⌘S) writes the config file, and a running bridge picks it up within a second or two. Revert throws away unsaved edits. If a change can't work, the status bar says why and Save stays off.
• The bridge switch shows whether the bridge is running, however it was started, and starts or stops it. The same commands are in the Bridge menu, with Show Bridge Log and Show REAPER Track Colour Script.
• File ▸ Open Config… edits another config file for the session. Normally you don't need it.
• Help ▸ Primo KK MK1 Control Editor Help opens this guide.

MIDI mode¶

MIDI mode is the default. Every control sends a MIDI CC on Primo Komplete Kontrol MK1, channel 1, for MIDI learn in any DAW. Buttons send 127 when pressed and 0 when released; knobs send absolute values (0–127).

Shift layer. Holding Shift moves the buttons, knob turns and the Navigate knob turn to channel 2, so every control has a second assignment with the same CC numbers.

• Shift itself sends CC108 on channel 1.
• Knob touch and Navigate touch always use channel 1.
• A release goes out on the channel of its press, even if you let go of Shift first.

Lights from the DAW. The bridge also has a MIDI output called Primo Komplete Kontrol MK1. A CC sent there:

• lights its button (any value above 0) or dims it (0)
• on channel 2, sets the light shown while Shift is held
• for a knob, moves that knob's value, so it carries on from the DAW's value instead of jumping

The keys, pitch strip (pitch bend) and mod strip (CC1) work as always, and Octave − / + transpose the keys on the keyboard as well as sending their CCs. The CC of every control is in Default assignments.

REAPER mode¶

In REAPER mode the bridge talks to REAPER over OSC, REAPER's own control-surface protocol. The transport and editing buttons run REAPER commands, and the knobs work in three views. Instance steps through them: Mix → Track → Komplete Kontrol → Mix. The Instance light shows which view you're in: off in Mix, medium in Track, full in Komplete Kontrol.

Set up REAPER (once)¶

1. Turn on REAPER mode: on the editor's Settings page, turn on Enabled under REAPER Mode, and save.
2. In REAPER, go to Preferences ▸ Control/OSC/web ▸ Add, and choose Control surface mode OSC (Open Sound Control):
   • Device name: PrimoKKMK1Bridge, Pattern config: Default
   • Mode: Configure device IP + local port
   • Device port 9000, Device IP 127.0.0.1, Local listen port 8000. These match Device Port, Address and Local Listen Port under REAPER Mode on the editor's Settings page.
3. Preferences ▸ MIDI Devices: enable Primo Komplete Kontrol MK1 for input.
4. Komplete Kontrol track: set its MIDI input to Primo Komplete Kontrol MK1. It carries the keys, the strips and the Komplete Kontrol view's CCs. For tracks that should only get the keys, use the keyboard's own Port 1, so the bridge's CCs aren't recorded into their items.
5. Optional: to have the keys play whichever track you select, right-click a track's record-arm button and turn on Automatic record-arm when track selected.

Until REAPER answers, the displays read waiting for OSC from REAPER (and with the track colour script installed, the keys are purple). The same happens within a second of REAPER quitting, and the bridge picks REAPER up again a few seconds after you reopen it. That needs REAPER on the same Mac (the default address, 127.0.0.1): with REAPER on another computer, the bridge can't tell it quit.

When the bridge starts, it runs REAPER's Control surface: Refresh all surfaces action to get the whole project, since REAPER otherwise only sends values that changed. Your other control surfaces (MCU, FaderPort, HUI) are refreshed at the same moment.

Buttons in every view¶

The buttons do the same in all three views, apart from the Komplete Kontrol view's own CCs.

• Shift: a combination without a command of its own sends that button's CC on channel 2, as in MIDI mode.
• Navigate knob: turning it picks the previous or next track. In Mix view it also switches to Track view, so the knobs and displays show the track you pick. The Komplete Kontrol view stays as it is, so you can move between instrument tracks and keep their plugins on the knobs.
• Changing track: the displays show TRK with the track's number and name for 2 seconds (Track Name Display Duration in Settings), then the knob values. Touching a knob ends that early.
• Clicking a track in REAPER selects it on the keyboard too.

The full list of what each button does, alone and with Shift, is in REAPER mode defaults. One of them needs a note: REAPER doesn't report the record mode over OSC, so Shift + Loop (normal ↔ time-selection auto-punch) follows the last mode set from the keyboard. If you change the mode in REAPER, one extra press brings them back in step.

Mix view¶

The default view. The 8 knobs are the volumes of 8 tracks, and with Shift held, their pans.

The left display shows MIX and the tracks on the knobs, such as 9-16. Each knob's display shows the track's name, its volume and a bar. While Shift is held, the left display shows PAN, and each knob's display shows the track's pan (CENTER at the centre) with a bar from the middle. Knobs past the last track stay blank, and the master track isn't on the knobs. To reset a volume to 0 dB, select the track and use Shift + knob 1 in Track view.

Track view¶

The knobs control the selected track. A track you pick with the Navigate knob also becomes REAPER's only selected track, and REAPER scrolls to it.

Page ▶ shows the next 8 sends (page 2: sends 4–11, page 3: sends 12–16), and Page ◀ goes back. Only sends that are routed somewhere appear, in order, each with the track it feeds and its level.

The left display shows the track's name and TRK n, or the page, such as PAGE 2/2. The record-arm display also shows the monitoring (ON MON, off AUTO); while Shift is held it shows MONITOR.

Komplete Kontrol view¶

The knobs and eight navigation buttons send fixed CCs for Komplete Kontrol's NKS MIDI template, like Novation's Launchkey keyboards do. They go out on Primo Komplete Kontrol MK1, channel 1. The other buttons keep their REAPER jobs. Turning the Navigate knob picks the previous or next track and keeps you in this view; the track you pick also becomes REAPER's only selected track, and REAPER scrolls to it.

Komplete Kontrol's parameter names and values aren't available to the bridge, so it works like the Launchkey:

• Displays: the selected track's name over KONTROL on the left, and ENCODER 1–ENCODER 8 under the knobs, each with a bar of the value it last sent.
• Knob values: the bridge keeps one set of 8 knob values, starting at 64, for every page, track and preset.
• Jumps: a knob can jump the first time you turn it after a page or preset change, when its value doesn't match the parameter it now controls.

For Komplete Kontrol to receive the CCs, its track needs Primo Komplete Kontrol MK1 as input and must be record-armed or monitored.

Track colour on the keys¶

In REAPER mode, the keyboard's light guide (the lights above the keys) shows the selected track's colour on every key. Its settings are in the Reaper Lightguide section of the editor's Settings page.

• Brightness: 50% by default. The colour is corrected so a white track looks white rather than purple.
• No colour: a track without a colour of its own leaves the keys dark, and so does having no track selected.
• Turning it off: turn off Enable Lightguide.

Once the script is installed (below), the light guide also shows how the bridge is doing:

REAPER's OSC doesn't report track colours, so a small script inside REAPER sends them to the bridge as MIDI. Set it up once:

1. Install the script. On the editor's Settings page, under Reaper Lightguide, click Install… in the REAPER Integration row. It does two things:
   • copies PrimoKKMK1Bridge_TrackColor.lua into the Scripts/Primo Studios folder of REAPER's resource folder
   • adds a line to Scripts/__startup.lua, which REAPER runs every time it starts. An existing __startup.lua is backed up first and kept as it is; the line goes at the end.

The row also shows whether the script is installed. Once it is, the button is Uninstall… instead (see below). After an update of the app, Update… appears next to it to replace an older script; Repair… puts back a part that's missing. 2. Let REAPER send to the bridge. In Preferences ▸ Audio ▸ MIDI Outputs (MIDI Devices in older versions), enable Primo Komplete Kontrol MK1 as an output. Only the script uses it: tracks don't send there unless you route them to it. 3. Restart REAPER. The keys take the selected track's colour, and follow as you select other tracks or change a colour.

To install it by hand instead, reveal the script with Bridge ▸ Show REAPER Track Colour Script, then:

• copy it into REAPER's Scripts folder (Options ▸ Show REAPER resource path in explorer/finder)
• add this line to Scripts/__startup.lua, adjusting the path to where you put it:

  dofile(reaper.GetResourcePath() .. "/Scripts/PrimoKKMK1Bridge_TrackColor.lua")

The script sends the colour when the selection or a colour changes, and every 2 seconds, so a restarted bridge catches up. When REAPER quits, the keys go dark.

To remove it, click Uninstall… in the same place. It deletes the script, and the Primo Studios folder too if nothing else is in it, and takes the script's lines out of Scripts/__startup.lua (backing it up first). The rest of __startup.lua stays as it is, and so does the file itself, unless starting the script was all it did. A script that's already running stops when you restart REAPER. The MIDI output can then be turned off again in REAPER's preferences, if nothing else uses it.

Default assignments¶

These are the defaults a new config starts with. Change any of them in the editor.

In the pictures, the first line under each control is what it does, and a line starting with ⇧ is what it does with Shift held.

MIDI mode defaults¶

With Shift held, every button and knob turn sends the same CC on channel 2.

REAPER mode defaults¶

The numbers in brackets are REAPER's action command IDs. Any button can run any REAPER action: in the editor, pick Run a REAPER action by ID…, or Run a MIDI Editor action by ID… for actions from the MIDI Editor section of REAPER's Action List.

Komplete Kontrol view defaults¶

Lights and displays¶

The bridge drives the 21 button lights, the nine displays and the light guide. Octave − / + and the Navigate knob have no light.

The config file¶

Everything the editor changes lives in one file: ~/Library/Application Support/PrimoStudios/PrimoKKMK1Bridge/PrimoKKMK1Bridge.json.

• When it's created: the editor or the bridge creates it with every default if it's missing. To start over, delete it, or use Reset to Default Settings… on the editor's Settings page (it keeps REAPER mode as it is) and save.
• Saved changes apply by themselves: a running bridge checks the file every second and restarts with a new, valid version within a moment. In your DAW the MIDI port drops out briefly. A file it can't use is logged and ignored.
• Editing it by hand: every key is optional; anything left out keeps its default. Config keys below lists every key.
• From Terminal: PrimoKKMK1Bridge --config FILE runs the bridge with another file, and PrimoKKMK1Bridge --print-default-config prints every default. PrimoKKMK1Bridge --version shows the version, which is also in the editor's About box.

Config keys¶

Everything the editor sets, by key. PrimoKKMK1Bridge --print-default-config prints them all with their defaults.

The defaults for buttons, reaper.buttons and reaper.shiftButtons are the tables in Default assignments.

Relative knob modes suit endless knobs best, but your DAW has to be told which relative format to expect (in Ableton Live's MIDI map, for example, set the control's mode to the matching "Relative" type). absolute works with plain MIDI learn everywhere.

Troubleshooting¶

The keyboard without the bridge¶

When the bridge isn't running and the keyboard has been replugged, it's in its own MIDI mode, on its own port (KOMPLETE KONTROL S61 Port 1, channel 1). The displays stay blank.