Skip to content
Lightbridge

APC40 MkII Reference

The Akai APC40 MkII is currently the only MIDI controller with built-in profiles in Lightbridge. This page documents every CC and note assignment in those profiles, so APC40 owners can see exactly what each physical control does and so future maintainers can verify the protocol is correct.

If you don’t have an APC40, this reference is unlikely to be useful. The MIDI Controllers guide and the MIDI & Controllers concept cover how to work with other controllers.

Hardware overview

The APC40 MkII is a grid-based MIDI controller with:

  • 8 device knobs (top row) with ring LED feedback
  • 8 track knobs (above the faders) with ring LED feedback
  • 8 channel faders (one per track) plus master and crossfader
  • 5 × 8 pad grid (40 pads) with RGB note-color LED feedback
  • Transport buttons, scene launch buttons, tempo knob (not currently mapped)

Lightbridge initialises the APC40 into Mode 2 (host-controlled LEDs) at startup via a SysEx message. In this mode the host owns every LED — nothing lights up unless Lightbridge sends an explicit feedback message.

LED feedback protocol

Lightbridge sends LED feedback messages to the APC40 whenever a bound parameter changes value:

  • Knob ring LEDs — two CC messages per knob: a style CC selects the ring display mode (off, dot, volume bar, pan) and a value CC sets the position (0–127). The CC pairs are computed by makeRingLedMessage(knobIndex, value, mode) in APC40Protocol.ts.
  • Pad colours — a Note-On message with the velocity mapped to a colour from the APC40’s built-in palette. The mapping is done by hexToApcVelocity(hex), which finds the closest palette entry to a given CSS hex colour. Velocities used by the docs site live in APC_COLOR_MAP in APC40Protocol.ts.

The feedback is one-way: Lightbridge sends, the APC40 displays. There is no readback — Lightbridge has no way to know what colour is currently on a pad except by remembering what it last sent.

Why APC40 is the only built-in controller

It’s the controller the developers happen to use. There’s nothing about the codebase that prevents adding more — every other controller can be supported via a custom profile. The APC40 just happens to ship with three built-in profiles because that’s what the developers needed first.

If you want first-class built-in support for a different controller, the path is to:

  1. Build a custom profile in the Controller editor that mirrors the hardware’s grid layout.
  2. Add MIDI CC/note assignments to each element. (Currently a manual step — see the caution in the MIDI guide.)
  3. Once it’s working, the profile JSON can be added to builtInProfiles.ts so it loads automatically.