build the mapping
before you buy the hardware

Buying a controller is a bet on ergonomics you haven't tested. Prototyping it on glass first turns that bet into an experiment — and the mapping you build transfers to the metal unchanged.

TouchOSC's layout format is zlib-compressed XML. That single fact turns "click every control" into "run a script" — which is the difference between a hundred-control surface being practical and being a weekend you'll never get back.

# decompress → edit → recompress. that's the whole format.
import zlib
xml = zlib.decompress(open('layout.tosc','rb').read()).decode()
# ... transform xml ...
open('out.tosc','wb').write(zlib.compress(xml.encode(), 9))

Inside, every control is a <node> with a unique ID, a frame (x, y, w, h), and — if it sends MIDI — a <messages><midi> block:

<message>
  <type>CONTROLCHANGE</type>
  <channel>1</channel>
  <data1>10</data1>   <!-- the CC number -->
  <data2>0</data2>
</message>
<values>
  <value><type>CONSTANT</type>…</value>  <!-- channel  ← literal -->
  <value><type>INDEX</type>…</value>     <!-- data1    ← NOT the field! -->
  <value><type>VALUE</type>…</value>     <!-- data2    ← control position -->
</values>

editing without breaking it

The XML leans on <![CDATA[…]]> throughout. Python's built-in ElementTree throws CDATA away on re-serialisation, which is legal XML but a gamble on someone else's parser. Two safe routes: use lxml, or do string surgery on the decompressed text, anchoring each edit to the node's unique ID='…'. Parse with ElementTree to find things; edit the raw string to change them.

Control Change gives you 128 numbers per channel, and 16 channels. Big surfaces run out — but usually far later than people think, and almost never in the way they assume.

one channel per deck

The move that makes big surfaces trivial: give each deck its own MIDI channel and reuse identical CC numbers across them. Deck 3's mid EQ is CC 11 on channel 3, exactly as deck 1's mid EQ is CC 11 on channel 1.

You get four times the space, but the real win is cognitive — the surface becomes self-documenting, you learn one deck's map instead of four, and mapping decks 2–4 is mechanical repetition a script can do for you.

The surface below is a real four-deck djay Pro rig: 33 controls per deck across four vertical channel strips — EQ, filter, volume, stem isolation, FX, transport. Same CC numbers on every deck; only the channel changes.

keypaths shown for the selected deck ·

Once one deck is mapped by hand, the other three are a transformation. djay Pro stores its mappings as an Apple property list — which Python reads and writes natively.

import plistlib, copy

d = plistlib.load(open(path,'rb'))
tmpl = [e for e in d['controls'] if e['keyPath'].startswith('turntable1.')]

for chan, deck in [(2,2), (3,3), (4,4)]:
    for e in tmpl:
        n = copy.deepcopy(e)
        n['keyPath']    = f'turntable{deck}.' + e['keyPath'].split('.',1)[1]
        n['midiChannel'] = chan
        d['controls'].append(n)

Thirty-one hand assignments become ninety-three generated ones. buttonMode (hold vs toggle) and controlType ride along in the deep copy, so behaviour stays identical across decks — which hand-mapping reliably fails to achieve.

validate before you write

The failure mode that costs you a soundcheck is two controls landing on the same (channel, CC). Assert it away:

pairs = [(e['midiChannel'], e['midiData']) for e in d['controls']]
assert len(pairs) == len(set(pairs)), 'collision'

The surface above drives a hybrid rig: DJ software running four decks alongside a DAW running a loop bed, tempo-locked over Ableton Link, each feeding its own mixer channel.