td-api-reference

TouchDesigner Python API Reference

Always research TD features on the wiki before writing code. Assumptions about TD's Python API are frequently wrong.

• Wiki home: https://docs.derivative.ca/Main_Page
• OP Class: https://docs.derivative.ca/OP_Class
• COMP Class: https://docs.derivative.ca/COMP_Class
• Par Class: https://docs.derivative.ca/Par_Class
• Extensions: https://docs.derivative.ca/Extensions
• Cook cycle: https://docs.derivative.ca/Cook

Parameter Access Patterns

# CORRECT -- always use .eval() for the current runtime value:
value = op('geo1').par.tx.eval()

# WRONG -- .val only works in constant mode:
value = op('geo1').par.tx.val

# Setting values:
op('geo1').par.tx = 5
op('geo1').par.tx.val = 5  # CAUTION: silently switches to CONSTANT mode

# Menu parameters accept string name or index:
op('geo1').par.xord = 'trs'   # by name
op('geo1').par.xord = 5       # by index

# Type casting requires explicit .eval():
me.par.tx.eval().hex()  # CORRECT
me.par.tx.hex()         # WRONG

Creating Custom Parameters

All append* methods return a ParGroup (tuple-like), not a single Par -- always index with [0].

page = comp.appendCustomPage('Controls')
pg = page.appendFloat('Speed', label='Speed')  # Returns ParGroup
p = pg[0]                                       # Get the actual Par
p.default = 0.5
p.normMin = 0; p.normMax = 2    # Slider range
p.min = 0; p.clampMin = True    # Hard clamp
p.help = "Playback speed multiplier."  # Tooltip on hover
p.startSection = True           # Draw separator line above

# Other methods:
page.appendInt('Count')
page.appendToggle('Active')
page.appendStr('Label')
page.appendMenu('Mode')        # Creates EMPTY menu -- set .menuNames/.menuLabels separately
page.appendPulse('Reset')
page.appendRGB('Color')        # Creates Color1r, Color1g, Color1b
page.appendXYZ('Pos')          # Creates Pos1, Pos2, Pos3
page.appendOP('Target')
page.appendFile('Path')

# Post-creation properties:
p.help = "Tooltip text shown on hover"  # ALWAYS set this
p.startSection = True   # Draw separator line above this parameter
p.order = 11.5          # Insert between order 11 and 12
p.readOnly = True       # Display-only parameter

# Cleanup:
comp.destroyCustomPars()       # Remove ALL custom pars
par.Speed.destroy()            # Remove single custom par