steelseries-live-scale/apex7-ableton-scale-lighting.md

SteelSeries Apex 7 × Ableton Live — Scale-Aware Key Lighting

Handoff brief for a Claude Code agent. Translated and structured from a planning conversation. Goal: build the tooling to highlight the notes of the currently selected Ableton scale on the physical keyboard's RGB backlight.

Project goal

Use the per-key RGB backlight of a SteelSeries Apex 7 to highlight, in real time, the keys that correspond to the notes of the scale currently selected in Ableton Live 12. The physical keyboard is fitted with transparent keycaps so the light reads clearly as note highlighting.

The full desired flow:

Live 12 (Live API: root_note + scale_intervals)
   → Max for Live device (computes the pitch classes in the scale)
   → Node for Max (POST JSON over HTTP)
   → GameSense server (127.0.0.1)
   → Apex 7 per-key RGB

Hardware notes

• Keyboard: SteelSeries Apex 7 — per-key RGB, MX-compatible (cross-stem) switches, so standard MX keycaps fit.
• Keycaps: transparent / "pudding" MX keycaps for light bleed. (Already swapped; not part of the software build.)
• Requires SteelSeries GG running in the background for GameSense to work.

Key ↔ note mapping (Ableton computer MIDI keyboard)

When Ableton's computer MIDI keyboard is enabled, one octave maps like a piano. White keys on the bottom row, black keys on the row above:

Note	Key	Note	Key
C	A	F#	T
C#	W	G	G
D	S	G#	Y
D#	E	A	H
E	D	A#	U
F	F	B	J
		C	K

Z / X = octave down/up, C / V = velocity down/up.

Pitch-class → key lookup (index 0–11):

0  C  -> A
1  C# -> W
2  D  -> S
3  D# -> E
4  E  -> D
5  F  -> F
6  F# -> T
7  G  -> G
8  G# -> Y
9  A  -> H
10 A# -> U
11 B  -> J
(12 C -> K, the octave key)

Reading the scale from Live 12

Live 12 exposes the global/selected scale on the Song object in the Live Object Model (LOM), accessible from Max for Live:

• root_note — root, integer 0–11 (0 = C … 11 = B)
• scale_intervals — list of ints, e.g. major = [0, 2, 4, 5, 7, 9, 11]
• scale_name — display name string
• scale_mode — whether scale mode is on

Compute the lit pitch classes:

lit = { (root_note + interval) % 12  for interval in scale_intervals }

Then map each pitch class to its QWERTY key via the table above.

Caveat: in Live 12 the scale is set per clip. Decide whether to observe the selected clip's scale or fix a global scale (existing "Scale Awareness" M4L packs can help enforce a global scale). Observe the relevant LOM property so the lighting updates when the scale changes.

Controlling the Apex 7 (SteelSeries GameSense SDK)

GameSense runs a local REST server. Flow:

1. Read the server port from coreProps.json:
   • Windows: %PROGRAMDATA%\SteelSeries\SteelSeries Engine 3\coreProps.json
   • macOS: /Library/Application Support/SteelSeries Engine 3/coreProps.json
   • The file gives an address like 127.0.0.1:<port>.
2. Register a game + event + handler, then POST event data to http://127.0.0.1:<port>/game_event (register via /game_metadata and /bind_game_event).
3. Per-key control options:
   • custom-zone-keys — address specific keys by USB HID usage code, with context-color to set their color at runtime.
   • bitmap mode — paint the whole keyboard at once (a 132-length array of [R,G,B], interpreted as a 22×6 grid mapped to nearest keys). Best for "dim background + bright scale keys" because it sets every key each update.

HID usage codes for the relevant letter keys (USB HID keyboard page):

A 0x04   S 0x16   D 0x07   F 0x09   G 0x0A   H 0x0B   J 0x0D   K 0x0E
W 0x1A   E 0x08   T 0x17   Y 0x1C   U 0x18

Caveat: as soon as a GameSense event arrives, the keyboard enters "GameSense mode" and other keys go dark unless you set them. Set a base color for all keys (bitmap mode handles this cleanly), then override the scale keys.

The bridge: Max for Live → GameSense

Cleanest option is Node for Max running inside the M4L device: it can read coreProps.json and issue the HTTP POSTs directly — no separate app needed.

Alternative: Max sends OSC/UDP to a small external Python/Node script that talks to GameSense.

Suggested build order

1. Standalone script (Node or Python) that talks to GameSense: register a game, light a hardcoded set of keys by HID code, set a dim background. Verify on hardware.
2. M4L device that reads root_note / scale_intervals from the LOM and prints the computed key set. Verify against the mapping table.
3. Wire the two together (Node for Max inside the device), observe the scale property so lighting updates live.
4. Polish: base color, highlight color, octave key, handle scale-mode off.

Open decisions for the user

• Platform: Windows or macOS (changes the coreProps.json path).
• Lighting style: bitmap (background + highlight) vs. just lighting the scale keys.
• Scale source: selected clip vs. enforced global scale.

References

• SteelSeries GameSense SDK (JSON handlers, per-key / bitmap lighting): https://github.com/SteelSeries/gamesense-sdk
• Live Object Model — Song (scale properties): https://docs.cycling74.com/apiref/lom/song/
• Controlling Live using Max for Live: https://help.ableton.com/hc/en-us/articles/5402681764242-Controlling-Live-using-Max-for-Live
• Keys and Scales in Live 12 FAQ: https://help.ableton.com/hc/en-us/articles/11425083250972-Keys-and-Scales-in-Live-12-FAQ