build the mapping
before you buy the hardware

You can't tell how a controller will feel from a product page. Building the layout on a touchscreen first lets you find out before you spend anything, and the mapping you make carries straight over to the hardware.

TouchOSC's layout format is zlib-compressed XML. That means you can edit a hundred-control surface with a script, instead of clicking through every control by hand.

# 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 across 16 channels. Big surfaces can run out, though usually later than you'd expect.

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.