Reference

When TDMap is in your project, a multi-functional button appears in the top-right corner of TouchDesigner's UI. It is the fastest way to open the app, queue parameters for mapping, and toggle Learn without reaching for the keyboard.

A button doesn't have to be a MIDI mapping. Flip its mode to Function in the inspector and it becomes an action button: tap it to reset, snapshot, randomize, switch banks, open an editor, etc. The same applies to a push-knob's push when it's set to Function. Most actions are one-line picks in a dropdown — pick the action, optionally pick what it operates on, done.

Picking what the action operates on

Actions that change a parameter need to know which parameter. Four ways to point at one — visible as tabs above the action:

• Hovered — whatever your mouse is over in TouchDesigner the moment you press the button. Great for "fix-it" buttons (reset, randomize, snapshot) that you point at things.
• Adjusted — the last parameter you twisted via MIDI. Lets one button always undo / randomize / re-default whatever you most recently touched.
• Knob — the push-knob's own assigned parameter. Only on push-knobs.
• Target — a fixed list of parameters you pin in advance. Two flavors, mixable in the same list:
  • Par target — drag a TD parameter onto the pill. Sticks to that exact parameter.
  • Control target — drag another card onto the pill (or click "+ Add Control Target"). Resolves to whatever that other control is currently driving — so renaming or reassigning the target control transparently changes what this button operates on. Same idea as Slot mode and Modify targets.

Actions iterate the whole list — point one Reset button at six targets to reset all of them with one press.

Things buttons can do

Everything below is a one-line pick in the inspector's Function dropdown. Where a function has variants, they show as a row of buttons right under the dropdown.

Set, reset, snapshot, randomize a parameter

All of these take a target — pick Hovered, Adjusted, Knob (push-knobs only), or Target (a pinned list of par or control targets — drag pars / cards onto the pill). See Picking what the action operates on above.

Navigate banks & open editors

Learn a new mapping

Fire your own code

Encoder-specific (push on a push-knob)

Open the gear icon in the toolbar to find these. All preferences persist across sessions in a single tdmap-prefs.json file next to your configs.

Defaults for new controls

Behavior

Feel

Workflow

Keyboard shortcuts

Handled in TouchDesigner via the Keyboard In CHOP — shortcuts work even when the TDMap panel isn't focused. Open Preferences → Keyboard Shortcuts to rebind. Combos persist in your global config.

On macOS, Cmd is treated as Ctrl for these combos (Ctrl+L → ⌘L). Shortcuts are suppressed while typing in a text field. The five built-in rows above can be cleared but not deleted; bank-switch rows are fully removable.

The TDMap component is shipped locked so its extension methods aren't directly accessible from outside callers. Locking serves two purposes: keeping users from accidentally breaking internals on a live show, and making the package less appetizing to AI-training scrapers that crawl public TouchDesigner tox files for code to ingest.

To keep the component scriptable anyway, TDMap exposes a small set of public methods over a public-interface Text DAT. Each non-blank, non-#-prefixed line is parsed as a method call and run against the COMP — one call per line, comments allowed, per-line errors logged to the Textport. Drive that DAT however you like: Python .text = ... assignment, a Replicator emitting rows, an external tox piping commands.

Setup: open the TDMap COMP's custom parameters, go to the Integration page, and pulse Create Public Ext Interface. That creates the Text DAT next to the COMP, ready to edit or drive from another script.

Execution triggers: the lines run automatically whenever the DAT's text changes, and also whenever the COMP's Runpublic custom parameter is pulsed. Use the pulse path when you want to re-fire the same lines without re-writing them — e.g. from a button, a CHOP event, or another script.

Arguments are parsed as Python literals from text — strings, numbers, booleans, lists, dicts, keyword args all work. You cannot pass live TouchDesigner objects (no op('/...') handles, no parameter refs, no module access — eval runs in a restricted scope). Pass a path as a string instead: write '/proj/synthA', not op('/proj/synthA'). If you need a value from elsewhere in TD, resolve it in your driving script first, then write the resulting literal into the DAT.

The intended pattern is to write into the Text DAT from a script rather than typing by hand — that way you compose lines once in real Python, with normal references and helpers, and only ship the final text to the DAT. For example, a DAT Execute attached to your project's state could push fresh navigation calls into TDMap whenever a scene change happens:

# In a script anywhere in your project
tdmap_input = op('/proj/tdmap_input')  # the Text DAT TDMap watches
synth_path = synth_comp.path  # resolve refs HERE, not in the DAT

tdmap_input.text = f'''
# Re-point all mappings at the new synth COMP
RetargetBanks('/proj/synthA', '{synth_path}', device='*', banks='*')
SelectDevice('knobs')
SelectBank(0)
'''.strip()

Example lines (what ends up in the DAT):

# Open a specific device + bank programmatically
SelectDevice('knobs')
SelectBank(2)

# Retarget mappings after renaming a COMP
RetargetBanks('/proj/synthA', '/proj/synthB', device='*', banks='*')

# Auto-load a stored layout on startup
SetDefaultGlobalConfig('live_set.json')

Methods