Tools reference

tdmcp exposes 102 tools organized into three layers plus the Obsidian vault integration. Build with the highest-level tool that fits and drop to a lower layer for fine control. Tools tagged read-only only inspect; mutates changes your project; destructive can delete or run arbitrary code.

This page is generated from the running tool registry, so it always matches the installed version.

Artist tools (Layer 1)

Describe the result you want; each tool builds and wires a whole network, auto-arranges it into a readable left→right layout, and — for the playable systems — exposes a control panel you can tweak, animate, preset or map to a controller.

create_feedback_network mutates

Build a feedback-based visual system: a seed feeds a loop that is transformed (blur/displace/etc.) and fed back each frame. Great for evolving, hypnotic visuals.

Parameter	Type	Required	Description
seed_type	noise | shape | image | video | webcam | glsl	no	(default: noise)
transformations	blur | displace | edge | level | hsv_adjust | transform | …[]	no	(default: blur,displace,level)
feedback_gain	number	no	(default: 0.95)
colors	string[]	no	Up to two hex colors to colorize the otherwise-grayscale output.
expose_controls	boolean	no	Expose a live 'Feedback' knob on the system container, bound to the loop's decay. (default: true)
parent_path	string	no	(default: /project1)

create_generative_art mutates

Create an evolving generative visual. reaction_diffusion/noise_landscape use validated recipes; strange_attractor, voronoi, and fractal render real GLSL; custom_glsl uses your shader; the rest fall back to animated noise.

Parameter	Type	Required	Description
technique	noise_landscape | reaction_diffusion | strange_attractor | l_system | cellular_automata | flow_field | …	yes
color_palette	string	no	Free-text palette hint (best-effort).
evolution_speed	number	no	(default: 1)
custom_glsl_code	string	no	Fragment shader (only for technique 'custom_glsl').
expose_controls	boolean	no	Expose a live 'Speed' knob (evolution speed) on the system container. (default: true)
parent_path	string	no	(default: /project1)

create_audio_reactive mutates

Build an audio analysis chain (spectrum + level + optional beat) and a spectrum visual driven by it. Each visual_style renders the spectrum its own way: glsl=horizontal bars, geometric=radial bars, particle=dot field, feedback=ring tunnel, instancing=LED grid.

Parameter	Type	Required	Description
audio_source	microphone | file | device_in | existing_chop	no	(default: microphone)
audio_file_path	string	no	Audio file path (audio_source='file').
existing_chop_path	string	no	Existing CHOP path (audio_source='existing_chop').
visual_style	geometric | particle | feedback | glsl | instancing	yes
frequency_bands	integer	no	Spectrum resolution: sets the Audio Spectrum CHOP output length (TouchDesigner clamps it to 128–4096 bins). Higher = finer spectrum. (default: 8)
beat_detection	boolean	no	(default: true)
expose_controls	boolean	no	Expose a live 'Sensitivity' knob (how strongly the audio drives the visual). (default: true)
parent_path	string	no	(default: /project1)

create_particle_system mutates

Build a particle system: an emitter feeds a particle SOP inside a Geometry COMP, rendered with a camera + light. Forces and render style are scaffolded for further tuning.

Parameter	Type	Required	Description
emitter_shape	point | line | circle | sphere | mesh | image	no	(default: sphere)
particle_count	integer	no	(default: 10000)
forces	gravity | noise | attract | repel | vortex | turbulence | …[]	no	(default: noise,gravity)
render_style	points | sprites | lines | trails | instanced_geo	no	(default: sprites)
lifetime	number	no	(default: 3)
expose_controls	boolean	no	Expose live Drag / Turbulence / Gravity / Lifetime knobs on the system container. (default: true)
parent_path	string	no	(default: /project1)

create_data_visualization mutates

Build a data-driven visualization: a data source feeds a CHOP that drives a chart TOP. Wire your real data into the created 'data' node.

Parameter	Type	Required	Description
data_source	table | file | chop	no	(default: table)
chart_style	bars | graph | points	no	(default: bars)
expose_controls	boolean	no	Expose a live 'Scale' knob that amplifies the data values feeding the chart. (default: true)
parent_path	string	no	(default: /project1)

apply_post_processing mutates

Chain post-processing effects (bloom, glitch, rgb_split, vignette, etc.) onto an existing TOP. Returns the processed output.

Parameter	Type	Required	Description
source_path	string	yes	Path of the TOP to post-process.
effects	bloom | chromatic_aberration | film_grain | vignette | color_grade | sharpen | …[]	yes	Effects to apply in order.
parent_path	string	no	(default: /project1)

setup_output mutates

Route a TOP to an output: a display window, NDI stream, Syphon/Spout, a recording, or Touch Out.

Parameter	Type	Required	Description
source_path	string	yes	Path of the final TOP to output.
output_type	window | ndi | syphon_spout | record | touch_out	no	(default: window)
resolution	720p | 1080p | 4K	no	(default: 1080p)
record_format	mp4 | mov | image_sequence	no
parent_path	string	no	(default: /project1)

get_preview read-only

Capture a TOP node as an inline image so you can see what was created.

Parameter	Type	Required	Description
node_path	string	yes	Path of the TOP node to capture.
width	integer	no	(default: 640)
height	integer	no	(default: 360)

plan_visual read-only

Turn a natural-language description of a visual you WANT into a build plan (which tool/recipe and nodes) — a dry run that creates nothing. Note: this does NOT inspect the current TouchDesigner project; to read existing nodes use get_td_nodes / get_td_topology / find_td_nodes.

Parameter	Type	Required	Description
description	string	yes	Natural-language description of the visual you want.

create_visual_system mutates

Create a complete visual system from a natural-language description. Classifies intent (audio-reactive, particle, feedback, reaction-diffusion, landscape, generative) and builds it in a self-contained COMP, then verifies and previews it.

Parameter	Type	Required	Description
description	string	yes	Natural-language description of the visual system.
parent_path	string	no	(default: /project1)
resolution	720p | 1080p | 4K | custom	no	Advisory target resolution. Recorded in the build note; the sub-builders use their own internal sizes and do not enforce this per-node. (default: 1080p)
target_fps	number	no	Advisory target frame rate (informational only — TD's real cook rate is a project-level setting, not set here). (default: 60)

extract_audio_features mutates

Build an audio-analysis chain that exposes ready-to-bind reactive channels — overall level plus bass/mid/treble band energies — on a Null CHOP. Unlike create_audio_reactive (which renders a spectrum visual), this produces the raw signals so you can drive ANY parameter: bind a node parameter to op('…/audio_features/features')['bass'] and it pulses with the music. A Sensitivity knob scales all channels. Source can be the live device (mic/line — may prompt for macOS permission), an audio file, a synthetic oscillator (for testing), or an existing CHOP.

Parameter	Type	Required	Description
source	device | file | oscillator | existing_chop	no	Audio source. 'device' = live microphone/line in (the real-world default; creating it may pop a one-time macOS microphone-permission dialog — click Allow). 'file' = an audio file. 'oscillator' = a synthetic tone, handy for testing without any device permission. 'existing_chop' = reuse a CHOP you already have. (default: device)
audio_file_path	string	no	Audio file path (source='file').
existing_chop_path	string	no	Path of an existing audio CHOP to analyze (source='existing_chop').
bass_hz	number	no	Low-pass cutoff for the bass band. (default: 200)
mid_hz	number	no	Band-pass centre for the mid band. (default: 1500)
treble_hz	number	no	High-pass cutoff for the treble band. (default: 4000)
expose_controls	boolean	no	Expose a live 'Sensitivity' knob (a gain over every feature channel). (default: true)
parent_path	string	no	(default: /project1)

create_motion_reactive mutates

Build a video-analysis chain that exposes ready-to-bind reactive channels — overall brightness plus frame-to-frame motion energy — on a Null CHOP. The camera counterpart to extract_audio_features: bind any parameter to op('…/motion_reactive/features')['motion'] and it responds to movement in front of the camera, or ['brightness'] to ambient light. A Sensitivity knob scales both. Source can be the live camera (may prompt for macOS permission), a movie file, an animated synthetic pattern (for testing without a camera), or an existing TOP. Optical flow is unavailable on macOS, so direction isn't exposed.

Parameter	Type	Required	Description
source	camera | file | synthetic | existing_top	no	Video source. 'camera' = live webcam/capture device (the real-world default; creating it may pop a one-time macOS camera-permission dialog — click Allow). 'file' = a movie file. 'synthetic' = an animated noise pattern, handy for testing without any device permission. 'existing_top' = analyze a TOP you already have. (default: camera)
movie_file_path	string	no	Movie file path (source='file').
existing_top_path	string	no	Path of an existing TOP to analyze (source='existing_top').
analysis_resolution	integer	no	The video is downsized to this square resolution before analysis — small keeps it cheap (the reactive values barely change with size). (default: 160)
expose_controls	boolean	no	Expose a live 'Sensitivity' knob (a gain over every feature channel). (default: true)
parent_path	string	no	(default: /project1)

create_multi_output mutates

Fan a master TOP across N projectors/displays: each output is a cropped slice (horizontal or vertical) resized to full projector resolution and ended on a Null, ready for setup_output. Set overlap for edge-blending — tiles widen into their neighbours and a GLSL feather fades the shared seams so physically-overlapping projectors blend smoothly. With as_windows, each tile also gets a borderless Window COMP offset across the desktop so it lands on its own display (left closed — open in Perform mode). The multi-projector counterpart to setup_output's single window.

Parameter	Type	Required	Description
source_path	string	yes	The master TOP to fan out across the projectors/displays.
count	integer	no	How many outputs to split the master into (one per projector/display). (default: 2)
layout	horizontal | vertical	no	Slice the master side-by-side (horizontal) or stacked (vertical). (default: horizontal)
overlap	number	no	Edge-blend: overlap each tile into its neighbor by this fraction of a tile's width, with a linear feather at the shared seams so physically-overlapping projectors blend smoothly (0 = abutting tiles, no blend). Try 0.1–0.3. (default: 0)
resolution	720p | 1080p | 4K	no	Per-output (per-projector) resolution. (default: 1080p)
as_windows	boolean	no	Also create a borderless Window COMP per tile, offset across the desktop so each lands on its own display. Left closed — open them in Perform mode when ready. (default: false)
parent_path	string	no	(default: /project1)

sync_external_clock mutates

Lock the project tempo to a live source so beat-synced visuals follow the music: a Bpm knob writes the global tempo (op('/').time.tempo), and a Tap pulse beat-matches by ear (averaging your taps into a BPM). Drives every Beat CHOP downstream — create_tempo_sync clocks and create_autopilot all follow. Dedicated MIDI-clock / Ableton-Link sync is a planned follow-up; for now match the DJ by tapping or dialing their BPM.

Parameter	Type	Required	Description
bpm	number	no	Starting tempo in BPM (match the DJ's displayed BPM, then fine-tune by tapping). (default: 120)
parent_path	string	no	(default: /project1)

create_tempo_sync mutates

Create a tempo clock (Beat CHOP driven by TouchDesigner's global tempo) exposing beat-synced channels on a Null CHOP: a per-beat 0→1 ramp, a pulse spike on each beat, integer beat/bar counters, and bpm. Bind any parameter to these to lock visuals to the beat. With emit_events on, it also broadcasts a beat event over the bridge WebSocket each beat, so tdmcp-agent watch and the AI can see the pulse live. Pair with extract_audio_features for full musical reactivity.

Parameter	Type	Required	Description
period	number	no	Beats per bar / beat period — how the ramp and bar channels divide the tempo. (default: 4)
emit_events	boolean	no	Also broadcast a beat event over the bridge WebSocket on every beat, so tdmcp-agent watch and the AI can react to beats live. (default: true)
expose_controls	boolean	no	Expose a live 'Period' knob to retune the beat division on the fly. (default: true)
parent_path	string	no	(default: /project1)

create_text_overlay mutates

Composite styled text over a visual (or on its own transparent background) — a Text TOP with font size, color, and alignment, optionally laid 'over' a source TOP through a Composite TOP, output as a Null. For lyrics, titles, song names, or credits in a set. Distinct from the vault's bind_vault_text (which data-syncs a Text DAT to a note); this is a finished visual layer ready for setup_output.

Parameter	Type	Required	Description
text	string	no	The text to display. (default: TEXT)
source_path	string	no	Optional TOP to composite the text over (e.g. a finished visual). Omit to get the text alone on a transparent background, ready to composite later.
font_size	number	no	Font size in pixels. (default: 64)
color	string	no	Text color as a hex string, e.g. '#ff3366'. (default: #ffffff)
align	left | center | right	no	Horizontal alignment. (default: center)
valign	top | center | bottom	no	Vertical alignment. (default: center)
resolution	720p | 1080p | 4K	no	(default: 1080p)
parent_path	string	no	(default: /project1)

create_autopilot mutates

Build a beat-driven auto-VJ: a Beat CHOP + a CHOP Execute DAT that, every N beats, either randomizes a target COMP's numeric controls (a hands-free drift, set by Amount) or cycles through its stored cues — so a set keeps evolving on its own. Live Active/Beats/Amount knobs let you pause or retune on stage. Reuses the tempo clock, randomize_controls and manage_cue mechanisms. Pair with a generated system (or a control panel) as the target.

Parameter	Type	Required	Description
comp_path	string	no	COMP the autopilot drives — its numeric custom controls (randomize mode) or its stored cues (cue mode). Usually a generated system container or a control panel. (default: /project1)
mode	randomize | cue	no	'randomize' nudges the COMP's numeric controls toward new random values each trigger (works on any COMP with controls). 'cue' cycles through the COMP's stored cues (needs cues from manage_cue). (default: randomize)
beats	integer	no	Fire an action every N beats (4 = once per bar at 4/4). (default: 4)
amount	number	no	(randomize) How far to move toward random each trigger: 1 = full scramble, low = gentle drift. (default: 0.5)
parent_path	string	no	Where to create the autopilot engine. (default: /project1)

create_layer_mixer mutates

Build a VJ-style layer mixer: combine source TOPs into one output. 'crossfade' makes an A/B Cross TOP with a Crossfade knob (the classic two-deck mix); any other blend mode composites the inputs (add, difference, hardlight, glow, …). Sources are pulled in via Select TOPs so they can live anywhere; with fewer than two, demo sources are created. Output is a Null ready for post-processing or setup_output.

Parameter	Type	Required	Description
inputs	string[]	no	Paths of source TOPs to mix (brought in via Select TOPs, so they can live in other containers). With fewer than 2, demo sources (noise + ramp) are created so you can see it working. (default: ``)
blend	crossfade | add | difference | hardlight | glow | lightercolor | …	no	'crossfade' = an A/B Cross TOP with a Crossfade knob; any other value composites all inputs with that blend mode. (default: crossfade)
expose_controls	boolean	no	Expose a live 'Crossfade' knob (crossfade mode only). (default: true)
parent_path	string	no	(default: /project1)

create_video_player mutates

Build a movie/clip player: one Movie File In TOP, or a playlist of clips fed through a Switch TOP with a Clip selector. Exposes live Play / Speed (and Clip) controls, output as a Null. Pass file paths, or none to get an empty player you point at a file in TD. For VJ clip playback — mix it with create_layer_mixer or make it react with bind_to_channel.

Parameter	Type	Required	Description
files	string[]	no	Movie file path(s). 0 = an empty player you can point at a file later; 1 = a single clip; 2+ = a playlist with a Switch TOP and a Clip selector. (default: ``)
expose_controls	boolean	no	Expose live Play / Speed (and Clip, for a playlist) controls. (default: true)
parent_path	string	no	(default: /project1)

create_3d_scene mutates

Build a renderable 3D scene: a Geometry COMP holding the chosen primitive (sphere/box/grid), a Camera, a Light, and a Render TOP, output as a Null — optionally instanced into a grid of instances copies via GPU instancing, with scale_variation for per-copy random sizes and spin for per-copy rotation over time. Exposes RotateY (whole-scene spin) and Zoom (camera distance) knobs. The starting point for 3D visuals — bind RotateY to a tempo ramp or an audio feature to make it move.

Parameter	Type	Required	Description
primitive	sphere | box | grid	no	Geometry to render. (default: sphere)
instances	integer	no	Copies to scatter via GPU instancing on a grid (1 = a single object). (default: 1)
spin	number	no	Per-instance spin around Y in degrees/sec (0 = still). Each copy rotates in place over time; needs instances > 1. (default: 0)
scale_variation	number	no	Per-instance size variation: 0 = all the same size, 1 = sizes range from 0 to full. Needs instances > 1. (default: 0)
expose_controls	boolean	no	Expose live RotateY (spin) and Zoom (camera distance) knobs. (default: true)
parent_path	string	no	(default: /project1)

create_projection_mapping mutates

Wrap a source TOP in a Corner Pin warp for projection mapping: drag the four corner handles to line the image up with a physical surface (wall, object, screen). The source comes in through a Select TOP so it can live anywhere; output is a Null ready for setup_output. The corner positions are parameters, so you can also drive or save them.

Parameter	Type	Required	Description
source_path	string	no	TOP to map (brought in via a Select TOP). Omit for a demo grid source.
parent_path	string	no	(default: /project1)

create_keyframe_animation mutates

Animate parameters along a keyframed curve synced to the timeline — structured motion beyond animate_parameter's LFO. Give time/value keyframes and the targets; an Execute DAT interpolates the curve each frame (linear or smooth easing) and loops it. Use it for choreographed moves (a build-up, a drop, a sweep) rather than continuous oscillation.

Parameter	Type	Required	Description
targets	string[]	yes	Parameters to animate, each written as 'nodePath.parName'.
keyframes	object[]	yes	Keyframes (time + value); the curve interpolates between them in order.
loop	boolean	no	Loop the animation; otherwise it holds the last value. (default: true)
easing	linear | smooth	no	Interpolation between keys: linear, or smooth (eased) for organic motion. (default: smooth)
parent_path	string	no	(default: /project1)

create_simulation mutates

Build a GPU simulation: 'reaction_diffusion' grows Gray-Scott patterns (via the validated recipe), while 'slime' and 'fluid' run a feedback loop displaced by an evolving noise flow field — drifting trails and advected smears. Exposes a Decay knob (trail persistence). For more procedural techniques (cellular automata, flow fields, strange attractors) see create_generative_art.

Parameter	Type	Required	Description
type	reaction_diffusion | slime | fluid	no	reaction_diffusion = Gray-Scott patterns (uses the validated recipe); slime = drifting decaying trails; fluid = advected smear. (default: reaction_diffusion)
speed	number	no	(slime/fluid) How fast the flow field evolves. (default: 1)
decay	number	no	(slime/fluid) Trail persistence — higher holds longer. (default: 0.96)
expose_controls	boolean	no	(default: true)
parent_path	string	no	(default: /project1)

list_recipes read-only

List the built-in recipe library — ready-made network templates (feedback tunnel, particle galaxy, reaction-diffusion, projection mapping, …) with their id, name, tags and difficulty. Offline. Apply one with apply_recipe.

Parameter	Type	Required	Description
tag	string	no	Optional tag/keyword to filter recipes by (matches tags or name).

apply_recipe mutates

Instantiate a built-in recipe by id (from list_recipes) inside a COMP — a tested, ready-made network you can build in one call, then tweak. Verifies and previews the result.

Parameter	Type	Required	Description
id	string	yes	Recipe id to build (see list_recipes).
parent_path	string	no	COMP to build the recipe inside. (default: /project1)

scaffold_show mutates

Create a starting skeleton for a live show: a container with a 'master' output Null (where your mix lands) and a 'tempo' beat clock for reactivity. A blank-canvas starting point — then add scenes, audio features, a layer mixer into master, cues and a control surface.

Parameter	Type	Required	Description
name	string	no	Name of the show container to create. (default: show)
parent_path	string	no	(default: /project1)

create_strobe mutates

Build a beat-syncable strobe / flash layer — a full-frame colour flash that pulses hard on/off, the signature live-VJ strobe effect. A square-wave LFO CHOP at the given Rate (Hz) drives a Level TOP's brightness so a Constant TOP (the flash colour, white by default) blinks; Duty sets the on-time fraction. With an input_path the flash is composited OVER that source (pulled in by a Select TOP, so it can live in another container); without one, the bare flash is output. Output is a Null TOP. Rate is free-running for v1 — bind the LFO's frequency to a beat CHOP later to lock it to the tempo.

Parameter	Type	Required	Description
rate_hz	number	no	Strobe rate in flashes per second (Hz) — the LFO CHOP square-wave frequency. (default: 8)
intensity	number	no	Brightness of the flash when it is on (0..1). Drives the Level TOP's brightness1. (default: 1)
color	string	no	Flash colour as a hex string ('#ffffff' = white, the classic strobe). Sets the Constant TOP's RGB. (default: #ffffff)
duty	number	no	On-time fraction of each cycle (0..1, 0.5 = even on/off). Mapped to the LFO CHOP's Bias, which rectangularises the square wave. (default: 0.5)
input_path	string	no	Optional absolute path of a source TOP to flash OVER. Pulled in via a Select TOP (TD wires don't cross containers) and composited under the flash. If omitted, the bare flash is output.
expose_controls	boolean	no	Expose live Rate / Intensity / Duty knobs bound to the right node parameters. (default: true)
parent_path	string	no	(default: /project1)

create_kaleidoscope mutates

Wrap a source in a kaleidoscope / radial-mirror symmetry effect — a signature VJ look. Folds the image into N identical mirrored wedges around a centre, with live Segments / Rotation / Zoom / Center controls. Pass input_path (an absolute TOP path) to kaleidoscope an existing visual, or omit it to generate a self-contained noise source that previews on its own. Output is a TOP.

Parameter	Type	Required	Description
segments	integer	no	Number of mirrored wedges (N-fold symmetry). 6 is the classic look; higher = finer. (default: 6)
rotation	number	no	Rotation of the whole kaleidoscope, in radians. Animate/bind this to spin it. (default: 0)
zoom	number	no	Zoom into the source — >1 magnifies the pattern, <1 pulls more of the source in. (default: 1)
center_x	number	no	Kaleidoscope centre X in normalized UV (0–1). 0.5 is the middle of the frame. (default: 0.5)
center_y	number	no	Kaleidoscope centre Y in normalized UV (0–1). 0.5 is the middle of the frame. (default: 0.5)
input_path	string	no	Absolute path of a source TOP to kaleidoscope. Brought in via a Select TOP (cross-container wiring silently no-ops). If omitted, a coloured noise source is generated so the network previews on its own.
expose_controls	boolean	no	Expose live Segments / Rotation / Zoom / Center X / Center Y knobs on the container. (default: true)
parent_path	string	no	(default: /project1)

create_glitch mutates

Build a glitch / corrupted-signal visual: RGB channel split, noise-driven blocky/slice displacement and horizontal band tearing over a source. With input_path it glitches an existing TOP (pulled in via a Select TOP); otherwise it uses a self-contained animated colour-noise source (no device permissions). Exposes Amount (master intensity — bind to audio/beat), Speed, RGBShift and BlockSize knobs. A signature live VJ look.

Parameter	Type	Required	Description
amount	number	no	Master glitch intensity (0..1). Scales both the block/slice displacement and the RGB channel split — 0 is a clean passthrough. Exposed as the 'Amount' knob and is the parameter to bind to audio/beat later. (default: 0.5)
speed	number	no	Animation speed of the noise that drives the blocky tearing (drives the noise's tz). (default: 1)
rgb_shift	number	no	Base per-channel horizontal offset in UV space (0..~0.1 is a useful range). Multiplied by Amount. (default: 0.02)
block_size	number	no	Scale of the displacement noise — smaller = larger, blockier tears; larger = finer grain. Sets the noise's period. (default: 8)
seed	number	no	Random seed for the displacement noise. (default: 1)
input_path	string	no	Absolute path of an existing TOP to glitch (e.g. '/project1/render/out1'). Pulled in via a Select TOP because wires cannot cross COMPs. If omitted, a self-contained animated colour-noise source is used so the system builds with zero device permissions (NOT a live webcam).
expose_controls	boolean	no	Expose live Amount/Speed/RGBShift/BlockSize knobs on the system container. (default: true)
parent_path	string	no	(default: /project1)

create_spectrum mutates

Build an FFT audio-spectrum analyzer that exposes N separate, ready-to-bind frequency-bin channels (band0..band{N-1}) on a Null CHOP. This is the per-band complement to extract_audio_features (which only gives overall level + bass/mid/treble): bind a row of parameters to op('…/spectrum/spectrum')['band0'], ['band1'], … to drive a bank of bars, or pick one frequency. A Sensitivity knob scales every band. Source can be the live device (mic/line — may prompt for macOS permission), an audio file, a synthetic oscillator (for testing), or an existing CHOP.

Parameter	Type	Required	Description
source	device | file | oscillator | existing_chop	no	Audio source. 'device' = live microphone/line in (the real-world default; creating it may pop a one-time macOS microphone-permission dialog — click Allow). 'file' = an audio file. 'oscillator' = a synthetic tone (white noise → energy in every band, handy for testing without any device permission). 'existing_chop' = reuse a CHOP you already have. (default: device)
audio_file_path	string	no	Audio file path (source='file').
existing_chop_path	string	no	Path of an existing audio CHOP to analyze (source='existing_chop').
bands	integer	no	Number of frequency bins to expose as separate, bindable channels (band0..band{N-1}). 16 or 32 is typical; higher = finer frequency resolution. (default: 16)
expose_controls	boolean	no	Expose a live 'Sensitivity' knob (a gain over every band channel). (default: true)
parent_path	string	no	(default: /project1)

detect_onsets mutates

Build a transient/onset detector that flags kick/snare/hi-hat hits in live audio and exposes a per-band pulse channel (a 0→1 spike on each hit) on a Null CHOP. Unlike create_tempo_sync (a fixed internal clock), this follows the ACTUAL audio: bind a parameter to op('…/onsets/onsets')['kick'] to flash or cut exactly on the kick drum. Each band is built from primitives (band filter → RMS energy → moving-baseline compare → threshold), so a Threshold knob tunes hit sensitivity and a Sensitivity knob scales the output. Source can be the live device (mic/line — may prompt for macOS permission), an audio file, a synthetic oscillator (for testing), or an existing CHOP. With emit_events on, it also broadcasts an onset event over the bridge WebSocket on each hit. The audio-following complement to create_tempo_sync.

Parameter	Type	Required	Description
source	device | file | oscillator | existing_chop	no	Audio source. 'device' = live microphone/line in (the real-world default; creating it may pop a one-time macOS microphone-permission dialog — click Allow). 'file' = an audio file. 'oscillator' = a synthetic tone, handy for testing without any device permission. 'existing_chop' = reuse a CHOP you already have. (default: device)
audio_file_path	string	no	Audio file path (source='file').
existing_chop_path	string	no	Path of an existing audio CHOP to analyze (source='existing_chop').
kick_hz	number	no	Low-pass cutoff (Hz) isolating the kick/bass-drum band. (default: 120)
snare_hz	number	no	Band-pass centre (Hz) isolating the snare/body band. (default: 1500)
hat_hz	number	no	High-pass cutoff (Hz) isolating the hi-hat/cymbal band. (default: 6000)
threshold	number	no	How far an instant's band energy must rise above its own moving baseline (in RMS units) to count as a hit. Band-RMS magnitudes are small (a steady tone reads ~0.002 live), so the default is 0.01 — the old 0.15 was unreachable and never fired. Lower = more sensitive; raise it if a loud track double-triggers. Tune live per source (needs real percussive audio to dial in). (default: 0.01)
emit_events	boolean	no	Also broadcast an onset event over the bridge WebSocket on every detected hit (with the band name), so tdmcp-agent watch and the AI can react to drum hits live. (default: false)
expose_controls	boolean	no	Expose live 'Sensitivity' (output gain) and 'Threshold' (hit sensitivity) knobs. (default: true)
parent_path	string	no	(default: /project1)

create_color_grade mutates

Build a colour-grading / LUT finishing stage over a source — the 'make the final output look graded' tool for VJ sets. A Level TOP applies lift/gamma/gain (brightness1 / gamma1 / contrast + black level), then an HSV Adjust TOP applies saturation + hue rotation; an optional LUT image file is loaded via a Movie File In TOP and fed into a Lookup TOP's second input to remap every colour. With an input_path the source is pulled in via a Select TOP (so it can live in another container); without one, a Ramp TOP test gradient is graded so it builds and previews standalone. Live Brightness / Gamma / Contrast / Saturation / Hue knobs are exposed. Output is a Null TOP.

Parameter	Type	Required	Description
brightness	number	no	Overall brightness / gain multiplier (1 = unchanged). Drives the Level TOP's brightness1 (this is the gain control — the param is brightness1, NOT gain). (default: 1)
gamma	number	no	Gamma / mid-tone curve (1 = linear, <1 brightens mids, >1 darkens mids). Drives the Level TOP's gamma1. (default: 1)
contrast	number	no	Contrast around mid-grey (1 = unchanged). Drives the Level TOP's contrast. (default: 1)
black_level	number	no	Lift the black point (0 = unchanged); raises the darkest pixels for a faded / filmic 'lift'. Drives the Level TOP's blacklevel. (default: 0)
saturation	number	no	Colour saturation multiplier (0 = greyscale, 1 = unchanged, >1 = punchier). Drives the HSV Adjust TOP's saturationmult. (default: 1)
hue	number	no	Hue rotation in degrees (0 = unchanged, 0..360 wraps the colour wheel). Drives the HSV Adjust TOP's hueoffset. (default: 0)
lut_path	string	no	Optional absolute path to a LUT image file (e.g. a 256x1 / 512x512 colour ramp). When given, a Movie File In TOP loads it and feeds the SECOND input of a Lookup TOP; the graded image is the first input, so each pixel is remapped through the LUT. Omit to skip LUT remapping.
input_path	string	no	Optional absolute path of the source TOP to grade. Pulled in via a Select TOP (TD wires don't cross containers). If omitted, a Ramp TOP test gradient is graded so the chain still builds and previews without any device or external source.
expose_controls	boolean	no	Expose live Brightness / Gamma / Contrast / Saturation / Hue knobs bound to the right node parameters. (default: true)
parent_path	string	no	(default: /project1)

import_model mutates

Import a 3D model file (.obj/.fbx/.usd) and render it to a TOP: a File In SOP reading model_path, fed into a Geometry COMP, with a Camera, a Light, and a Render TOP output as a Null. Omit model_path to fall back to a default primitive so the network still builds with no dependencies. Exposes RotateY (spin), Zoom (camera distance) and Scale knobs — the imported-model sibling of create_3d_scene.

Parameter	Type	Required	Description
model_path	string	no	Path to a 3D model file (.obj/.fbx/.usd) read by a File In SOP. Omit to fall back to a default primitive so the network still builds and previews with no file dependency.
rotate_y	number	no	Initial rotation of the model around Y in degrees (exposed as the RotateY knob). (default: 0)
zoom	number	no	Camera distance from the model along Z (exposed as the Zoom knob). (default: 5)
scale	number	no	Uniform scale applied to the model (1 = imported size). (default: 1)
expose_controls	boolean	no	Expose live RotateY (spin), Zoom (camera distance) and Scale knobs. (default: true)
parent_path	string	no	(default: /project1)

create_shader_lib mutates

Instantiate a curated, ready-to-run full-screen GLSL shader (tunnel, raymarch_sphere, fractal, metaballs, plasma) into a GLSL TOP with live Speed / Scale / Color controls. High-value VJ eye-candy; unlike create_glsl_shader it ships robust built-in shaders rather than taking arbitrary code.

Parameter	Type	Required	Description
shader	tunnel | raymarch_sphere | fractal | metaballs | plasma	no	Which curated built-in shader to instantiate. (default: tunnel)
speed	number	no	Animation speed multiplier (drives uTime). Exposed as a live 'Speed' control. (default: 1)
scale	number	no	Pattern scale/zoom multiplier (uScale). Exposed as a live 'Scale' control. (default: 1)
color	string	no	Base color as hex (e.g. '#33ccff'); parsed to 0..1 RGB and exposed as 'Color'.
resolution	object[]	no	Output resolution [width, height] of the GLSL TOP. (default: 1280,720)
expose_controls	boolean	no	Expose live Speed / Scale / Color controls on the system container. (default: true)
parent_path	string	no	(default: /project1)

create_video_synth mutates

Instantiate an analog video-synthesizer pattern (lissajous oscillator curve, moving interference fringes, or CRT scanline modulation) into a GLSL TOP with live Speed / FreqX / FreqY / Scale / Color controls. An oscillator/interference generator for VJ work — distinct from create_shader_lib's tunnel/raymarch/fractal/metaball looks.

Parameter	Type	Required	Description
mode	lissajous | interference | scanlines	no	Oscillator look: 'lissajous' (two-oscillator X/Y curve), 'interference' (moving sine fringes), or 'scanlines' (analog CRT scanline modulation). (default: lissajous)
speed	number	no	Animation speed multiplier (drives uTime). Exposed as a live 'Speed' control. (default: 1)
freq_x	number	no	X-axis oscillator frequency (uFreqX). Exposed as a live 'FreqX' control. (default: 3)
freq_y	number	no	Y-axis oscillator frequency (uFreqY). Exposed as a live 'FreqY' control. (default: 2)
scale	number	no	Pattern scale/zoom multiplier (uScale). Exposed as a live 'Scale' control. (default: 1)
color	string	no	Base color as hex (e.g. '#33ccff'); parsed to 0..1 RGB and exposed as 'Color'.
resolution	object[]	no	Output resolution [width, height] of the GLSL TOP. (default: 1280,720)
expose_controls	boolean	no	Expose live Speed / FreqX / FreqY / Scale / Color controls on the system container. (default: true)
parent_path	string	no	(default: /project1)

create_depth_silhouette mutates

Extract a silhouette / body mask from a depth or video source — a person's white outline on black you can composite, fill with colour, or use as a mask for reactive visuals (interactive installations / camera-reactive sets). The signal is smoothed (Blur TOP), keyed to a mask (Threshold TOP), optionally inverted (Level TOP) and optionally filled with a colour keyed through the mask (Constant + multiply Composite). Source defaults to a self-contained synthetic noise field so it builds and previews with ZERO device permissions; pick 'file' for a clip, or a 'kinect_azure'/'kinect'/'realsense' sensor for the live installation (may prompt for macOS permission). Exposes Threshold (bind to proximity/audio), Smooth, Invert (+ FillColor) and outputs a Null TOP.

Parameter	Type	Required	Description
source	synthetic | file | kinect_azure | kinect | realsense	no	Where the depth/luma signal comes from. 'synthetic' (the default) = a self-contained animated noise/ramp field that needs ZERO device permissions, so the network builds and previews immediately — use it to dial in the look. 'file' = a movie/image file (source_file_path). 'kinect_azure' | 'kinect' | 'realsense' = a live depth/IR sensor (the real installation source); creating it may pop a one-time macOS camera/depth-permission dialog — click Allow. (The depth-device op names are confirmed to exist; their per-device params still need live confirmation.) (default: synthetic)
source_file_path	string	no	Movie/image file path for source='file' (e.g. a pre-recorded depth or IR clip). Ignored for other sources.
threshold	number	no	Depth/luma cutoff (0..1) that separates the body from the background: pixels brighter than this become the white silhouette, the rest go black. The headline 'Threshold' knob and the parameter to bind to audio/beat/proximity later. (default: 0.5)
smooth	number	no	Edge smoothing — a Blur TOP filter size applied to the raw mask to round off jagged sensor edges before the silhouette is keyed. 0 = hard, aliased edges; higher = softer outline. (default: 0.5)
invert	boolean	no	Invert the mask (swap silhouette and background). Off = white body on black; on = black body on white. Drives a Level TOP's invert. (default: false)
fill_color	string	no	Optional hex colour ('#rrggbb') to fill the silhouette with instead of plain white — keyed through the mask via a Constant TOP composited (multiply) against it. Omit for a white-on-black mask.
expose_controls	boolean	no	Expose live Threshold / Smooth / Invert (+ FillColor) controls on the system container. (default: true)
parent_path	string	no	(default: /project1)

create_kinetic_text mutates

Build a self-contained animated / kinetic typography layer — a word or line that flashes, pulses, or slides, the signature live-VJ lyric-flash effect. A Text TOP renders the text; an LFO CHOP at the given Rate (Hz) drives the animation: 'flash' gates a Level TOP's alpha/opacity hard on/off (a square wave — the text vanishes between flashes rather than turning black, so it pops cleanly in and out over a background), 'pulse' drives a Transform TOP's scale plus a Level TOP alpha fade (a sine, the text breathes), and 'slide' scrolls the Transform TOP's translate-X. With an input_path the text is composited OVER that source (pulled in by a Select TOP, so it can live in another container); without one it animates on a transparent frame. Output is a Null TOP. Rate is free-running for v1 — bind the LFO's frequency to a beat CHOP (or a Trigger to a detect_onsets channel) to lock the flashes to the tempo.

Parameter	Type	Required	Description
text	string	no	The word or line to animate (the lyric flash). Rendered by a Text TOP. For multiple lines use \n. (default: DUQUESA)
mode	flash | pulse | slide	no	Animation style: 'flash' = hard on/off blink (a square LFO gates the alpha/opacity — the classic lyric-flash, the text vanishes between flashes rather than going black); 'pulse' = breathing scale-up + alpha fade driven by a sine LFO; 'slide' = the text scrolls horizontally across the frame. (default: flash)
size	number	no	Font size in pixels (drives the Text TOP's fontsizex / fontsizey). (default: 120)
color	string	no	Text colour as a hex string ('#ffffff' = white). Sets the Text TOP's fontcolorr/g/b. (default: #ffffff)
rate_hz	number	no	Animation rate in cycles per second (Hz) — the LFO frequency. Free-running for v1; bind it to a beat CHOP to fire on the actual beat. (default: 2)
input_path	string	no	Optional absolute path of a source TOP to lay the text OVER. Pulled in via a Select TOP (TD wires don't cross containers) and composited under the text. If omitted, the text animates on a transparent frame.
expose_controls	boolean	no	Expose live Text / Size / Color / Rate controls bound to the right node parameters. (default: true)
parent_path	string	no	(default: /project1)

create_waveform mutates

Build a time-domain audio waveform / oscilloscope — the actual audio signal scrolling left-to-right as a moving trace (the time-domain companion to create_spectrum's frequency bins and detect_onsets' transients). A Trail CHOP keeps a rolling buffer of recent samples (time_window seconds), a CHOP-to-SOP turns those samples into a real scope LINE (x=time, y=amplitude) rendered by a Geometry COMP through an orthographic Camera + Render TOP, and a Constant TOP tints the trace to the chosen colour. Unlike create_audio_reactive (which renders a spectrum), this shows the raw waveform. Source can be the live device (mic/line — may prompt for macOS permission), an audio file, a synthetic oscillator (for testing), or an existing CHOP. Output is a Null TOP. Scale is the vertical amplitude zoom; TimeWindow is the horizontal time span.

Parameter	Type	Required	Description
source	device | file | oscillator | existing_chop	no	Audio source. 'device' = live microphone/line in (the real-world default; creating it may pop a one-time macOS microphone-permission dialog — click Allow). 'file' = an audio file. 'oscillator' = a synthetic tone, handy for testing the scope without any device permission. 'existing_chop' = reuse a CHOP you already have. (default: device)
audio_file_path	string	no	Audio file path (source='file').
existing_chop_path	string	no	Path of an existing audio CHOP to scope (source='existing_chop').
color	string	no	Waveform colour as a hex string ('#00ff88' = classic phosphor green). Tints the rendered scope line via a Constant TOP multiplied over the Render TOP image. (default: #00ff88)
scale	number	no	Amplitude gain on the signal before it is drawn — the vertical zoom of the trace. Drives a Math CHOP's gain (1 = raw signal). (default: 1)
time_window	number	no	How much recent history the scrolling trace holds, in seconds — the horizontal time span. Drives the Trail CHOP's Window Length (wlength, units = seconds). (default: 1)
expose_controls	boolean	no	Expose live Color / Scale / TimeWindow controls bound to the right node parameters. (default: true)
parent_path	string	no	(default: /project1)

detect_pitch mutates

EXPERIMENTAL monophonic pitch tracker. Estimates the dominant musical pitch of live audio and exposes pitch_hz (frequency in Hz), note (MIDI note number), and confidence (peak magnitude) on a Null CHOP — bind a colour/parameter to op('…/pitch/pitch')['pitch_hz'] to drive visuals from a melody. Built entirely from stock CHOPs (the Pitch CHOP isn't createable in this build): an Audio Spectrum CHOP in 1-sample-per-Hz mode, trimmed to a [min_hz, max_hz] search band, then an Analyze CHOP argmax (highestpeakindex) whose index IS the frequency. A Threshold knob mutes the pitch when nothing is clearly playing and a Sensitivity knob scales the magnitude. Source can be the live device (mic/line — may prompt for macOS permission), an audio file, a synthetic sine oscillator (for testing), or an existing CHOP. Caveats: ~1 Hz resolution, no harmonic/octave correction, monophonic only — approximate and best tuned live.

Parameter	Type	Required	Description
source	device | file | oscillator | existing_chop	no	Audio source. 'device' = live microphone/line in (the real-world default; creating it may pop a one-time macOS microphone-permission dialog — click Allow). 'file' = an audio file. 'oscillator' = a synthetic tone (a SINE wave at a fixed frequency → a clean single peak, the ideal device-free test for pitch tracking). 'existing_chop' = reuse a CHOP you already have. (default: device)
audio_file_path	string	no	Audio file path (source='file').
existing_chop_path	string	no	Path of an existing audio CHOP to analyze (source='existing_chop').
min_hz	number	no	Bottom of the frequency search range (Hz). The dominant-bin search ignores everything below this, so sub-bass rumble / DC offset can't masquerade as the pitch. 80 Hz ≈ low male voice / bass guitar E. (default: 80)
max_hz	number	no	Top of the frequency search range (Hz). The search ignores everything above this. 2000 Hz comfortably covers the fundamental of most melodic instruments and voice; raise it for piccolo/whistle, lower it to reject high harmonics. (default: 2000)
expose_controls	boolean	no	Expose live 'Sensitivity' (magnitude gain) and 'Threshold' (minimum peak magnitude below which the pitch is treated as silence) knobs. (default: true)
parent_path	string	no	(default: /project1)

create_3d_audio_reactive mutates

Build a 3D scene that reacts to sound — the 3D counterpart of create_audio_reactive. An FFT spectrum chain feeds geometry: 'instanced_bars' renders a row of bands boxes/spheres whose individual heights track each frequency bin (a 3D spectrum bar-graph), while 'bass_pulse' swells a single primitive with the low-frequency energy. Includes a Camera, Light, and Render TOP, output as a Null TOP. Exposes Sensitivity (audio gain), Zoom (camera distance), and Spin (whole-scene rotation) knobs. Source can be the live device (mic/line — may prompt for macOS permission), an audio file, a synthetic oscillator (for testing), or an existing CHOP.

Parameter	Type	Required	Description
source	device | file | oscillator | existing_chop	no	Audio source. 'device' = live microphone/line in (the real-world default; creating it may pop a one-time macOS microphone-permission dialog — click Allow). 'file' = an audio file. 'oscillator' = a synthetic tone (white noise → energy in every band, handy for testing without any device permission). 'existing_chop' = reuse a CHOP you already have. (default: device)
audio_file_path	string	no	Audio file path (source='file').
existing_chop_path	string	no	Path of an existing audio CHOP to analyze (source='existing_chop').
mode	instanced_bars | bass_pulse	no	'instanced_bars' = a row of bands boxes/spheres, each one's height driven by one frequency bin (a 3D spectrum bar-graph). 'bass_pulse' = a single primitive that swells with the low-frequency energy (the guaranteed-visible fallback). (default: instanced_bars)
bands	integer	no	Number of bars in 'instanced_bars' mode — one per frequency bin. (default: 16)
primitive	box | sphere	no	Geometry rendered for each bar / the pulsing object. (default: box)
spin	number	no	Whole-scene rotation around Y in degrees/sec (0 = still). Spins the entire bar row / object over time. (default: 0)
expose_controls	boolean	no	Expose live Sensitivity (audio gain), Zoom (camera distance), and Spin knobs. (default: true)
parent_path	string	no	(default: /project1)

create_dome_output mutates

Remap a source TOP (treated as an equirectangular / panoramic master) into a square single-output dome master for planetarium fulldomes / 360 — the curved complement to create_multi_output's flat tiling. A Select TOP pulls the master in, a GLSL TOP warps it (fisheye: equirect → centred dome disc using fov; equirectangular: near-passthrough identity remap) via a shader held in a Text DAT, ending on a Null ready for setup_output. With expose_controls a Rotation knob spins the dome horizon. Note: this GLSL-remaps an existing source — a true cubemap render is the higher-fidelity follow-up.

Parameter	Type	Required	Description
source_path	string	yes	The master TOP to remap, treated as an equirectangular / panoramic source (the full 360°×180° latlong image the dome warps from).
projection	fisheye | equirectangular	no	fisheye: warp the equirectangular source into a centred dome disc (planetarium fulldome master). equirectangular: near-passthrough identity remap, so an already-equirect source still yields a valid output. (default: fisheye)
resolution	1024 | 2048 | 4096	no	Square dome-master resolution (width = height). (default: 2048)
fov	number	no	Fisheye coverage in degrees (the angular diameter the disc spans). 180 = full hemisphere (standard fulldome); larger over-fills, smaller zooms in. Used by the fisheye shader. (default: 180)
expose_controls	boolean	no	Expose a Rotation knob bound to the shader uniform that spins the dome horizon (degrees). (default: true)
parent_path	string	no	(default: /project1)

create_mesh_warp mutates

Map a source TOP onto a curved or irregular surface via a deformable textured grid — the curved-surface upgrade to create_projection_mapping's flat corner-pin, for domes, columns, and sculptures. Builds a Geometry COMP holding a grid that is bent into a dome (bulge), ripples (wave), half-cylinder (cylinder), or left flat, textured with the source through a Constant MAT, and rendered through an orthographic Camera + Light + Render TOP. Output is a Null ready for setup_output; exposes a Zoom knob.

Parameter	Type	Required	Description
source_path	string	yes	Path of the TOP to map onto the surface (brought in through a Select TOP).
rows	integer	no	Grid rows — more rows give a smoother curve but a heavier mesh. (default: 20)
cols	integer	no	Grid columns — more columns give a smoother curve but a heavier mesh. (default: 20)
warp	bulge | wave | cylinder | flat	no	Surface shape: bulge (dome), wave (ripples across X), cylinder (half-cylinder wrap), or flat (no deform). (default: bulge)
amount	number	no	Deformation strength (0 = flat, 1 = full bend). Ignored when warp is 'flat'. (default: 0.3)
expose_controls	boolean	no	Expose a live Zoom (camera distance) knob. (default: true)
parent_path	string	no	(default: /project1)

create_depth_displacement mutates

Push a flat plane into real 3D relief by a depth/luminance map: a subdivided grid whose vertices are offset along Z by a GLSL displacement material sampling the source's brightness, rendered with a camera + light so it reads as depth that shifts with the view. Unlike create_depth_silhouette (a flat 2D mask), this is true geometry — a 2.5D landscape. Source can be the live camera (may prompt for macOS permission), a movie file, an animated synthetic pattern (testable without a camera), or an existing TOP (e.g. a real depth map). subdivisions sets the relief resolution, depth the push amount, invert flips bright↔near. Exposes Depth and Zoom knobs — bind Depth to a tempo ramp or an audio feature to make the surface heave.

Parameter	Type	Required	Description
source	camera | file | synthetic | existing_top	no	Depth/luminance source that drives the relief. 'camera' = live webcam/capture device (creating it may pop a one-time macOS camera-permission dialog — click Allow). 'file' = a movie file. 'synthetic' = an animated noise pattern, so the relief moves and the chain is testable without any device permission (the default). 'existing_top' = displace by a TOP you already have (e.g. a real depth map). (default: synthetic)
movie_file_path	string	no	Movie file path (source='file').
existing_top_path	string	no	Path of an existing TOP to sample as the height map (source='existing_top').
subdivisions	integer	no	Grid resolution (rows = cols). Higher = finer relief and smoother displacement, but more vertices to push. 100 gives a 100×100 plane. (default: 100)
depth	number	no	Displacement amount along Z: how far bright (or dark, if inverted) pixels push the surface out of the plane. 0 = flat. (default: 1)
invert	boolean	no	Flip the height mapping. false = bright pixels push toward the camera (bright = near); true = dark pixels push toward the camera (dark = near). (default: false)
expose_controls	boolean	no	Expose live Depth (displacement amount) and Zoom (camera distance) knobs. (default: true)
parent_path	string	no	(default: /project1)

create_gpu_particle_field mutates

Build a high-count GPU particle / point field: position and velocity are simulated entirely on the GPU in two RGBA32float feedback-TOP loops (velocity integrates forces — noise/curl/gravity; position integrates velocity), then a Geometry COMP instances a tiny dot once per texel, reading XYZ from the position texture. Reaches counts (side², up to 512²≈262k) well beyond the CPU create_particle_system, flowing as curl-noise streams. Exposes PointSize and Zoom knobs. Optional reactivity energises the field live: 'audio' drives it from mic/line RMS, 'motion' from camera frame-difference energy (both bound to the velocity shader's uReact uniform).

Parameter	Type	Required	Description
side	integer	no	Edge of the square particle buffer; the field is side×side particles (count = side², e.g. 256 → 65 536). Each particle is one texel of the RGBA32float position/velocity buffers. (default: 256)
forces	noise | gravity | curl[]	no	In-shader forces added to velocity each frame: 'noise' (per-particle random drift), 'gravity' (constant -Y pull), 'curl' (divergence-free swirling). (default: noise)
reactivity	none | audio | motion	no	Optional external push that energises the field live, bound to the velocity shader's uReact uniform. 'none' (default) is fully self-contained. 'audio' drives it from mic/line RMS (Audio Device In → Analyze), 'motion' from camera frame-difference energy (Video Device In → mono → cache/difference → average). Either may pop a one-time macOS device-permission dialog — click Allow. (default: none)
point_size	number	no	Radius of each instanced dot (the sphere/circle SOP scale). (default: 0.02)
expose_controls	boolean	no	Expose live PointSize and Zoom (camera distance) knobs on the system container. (default: true)
parent_path	string	no	(default: /project1)

Building blocks & live control (Layer 2)

Mid-level tools for assembling, wiring, controlling, animating and storing networks — the pieces the Layer 1 generators are built from, exposed for fine control.

create_node_chain mutates

Create multiple nodes and (optionally) connect them in sequence. Returns all created paths; on failure it stops and reports partial progress without deleting anything.

Parameter	Type	Required	Description
parent_path	string	yes	Parent COMP to create the chain inside.
nodes	object[]	yes	Ordered list of nodes to create.
connect_sequentially	boolean	no	Wire output[0] → input[0] for each consecutive pair. (default: true)

connect_nodes mutates

Wire one node's output into another node's input. Uses the batch endpoint when available, with a Python fallback.

Parameter	Type	Required	Description
source_path	string	yes	Path of the source node (output side).
target_path	string	yes	Path of the target node (input side).
source_output	integer	no	(default: 0)
target_input	integer	no	(default: 0)

create_glsl_shader mutates

Create a GLSL TOP with a fragment shader (and optional vertex shader) supplied via Text DATs, with optional uniform binding and output resolution.

Parameter	Type	Required	Description
parent_path	string	yes	Parent COMP to create the GLSL TOP inside.
name	string	no	Name for the GLSL TOP (default 'glsl1').
fragment_shader	string	yes	GLSL fragment (pixel) shader source.
vertex_shader	string	no	Optional GLSL vertex shader source.
uniforms	object[]	no	Optional uniform declarations to best-effort bind on the GLSL TOP.
resolution	720p | 1080p | 4K | input	no	(default: input)

create_python_script mutates

Create a DAT (text/execute/script) preloaded with Python code.

Parameter	Type	Required	Description
parent_path	string	yes	Parent COMP to create the DAT inside.
name	string	no
code	string	yes	Python source to place in the DAT.
dat_type	text | execute | script	no	Kind of DAT: 'text' (plain), 'execute' (event hooks), or 'script' (table builder). (default: text)

set_parameters_batch mutates

Update parameters on multiple nodes in a single batch request. Each update reports its own success; a failure does not roll back the others.

Parameter	Type	Required	Description
updates	object[]	yes	List of { path, parameters } updates sent in one batch request (per-update results; not transactional — a failed update does not roll back the others).

create_container mutates

Create a self-contained COMP to hold a visual system.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP to create the container in. (default: /project1)
name	string	no
comp_type	container | base	no	'container' (2D panel COMP) or 'base' (generic COMP). (default: container)

create_control_panel mutates

Expose live controls on a COMP: append custom parameters (sliders, toggles, menus, RGB, pulse) and bind them to node parameters so the artist can drive a generated system in real time. Point comp_path at a system container and list the controls; use each control's bind_to to wire it to one or more 'nodePath.parName' targets.

Parameter	Type	Required	Description
comp_path	string	no	COMP that will receive the custom parameters — usually a generated system's container. (default: /project1)
page	string	no	Name of the custom-parameter page to add the controls to. (default: Controls)
controls	object[]	yes	The controls (knobs/sliders/toggles/menus) to expose.

create_control_surface mutates

Build a playable performance panel (a Container COMP of visual widgets) for live use, beyond the parameter dialog: vertical faders that drive parameters, and buttons that recall or morph to named cues (from manage_cue). Open the container in Perform/Panel mode for a touchable surface — faders move their parameters, cue buttons fire scenes (instantly or with a crossfade).

Parameter	Type	Required	Description
comp_path	string	no	Control COMP that holds the cues (manage_cue) and custom params. The surface is built inside it and its buttons fire that COMP's cues. (default: /project1)
name	string	no	Name of the panel container to build. (default: surface)
align	horizlr | verttb | gridcols | gridrows | none	no	How the panel lays out its widgets. (default: horizlr)
faders	object[]	no	Vertical faders, each driving a parameter. (default: ``)
cue_buttons	object[]	no	Buttons that recall or morph to named cues. (default: ``)

animate_parameter mutates

Drive one or more node parameters over time with an LFO (sine/triangle/ramp/square/pulse/random). Creates an LFO CHOP and binds each target so it oscillates between min and max with the given period — movement without manual keyframing.

Parameter	Type	Required	Description
targets	string[]	yes	Parameters to animate, each written as 'nodePath.parName' (e.g. '/project1/sys/blur1.size'). Each is switched to expression mode so it tracks the oscillator live.
waveform	sine | triangle | ramp | square | pulse | random	no	Oscillator shape. Every waveform sweeps the full min–max range. (default: sine)
min	number	no	Low end of the value sweep. (default: 0)
max	number	no	High end of the value sweep. (default: 1)
period_seconds	number	no	Seconds for one full cycle (lower = faster). (default: 4)
container_path	string	no	Where to create the LFO CHOP; defaults to the first target's parent network.
name	string	no	Name for the LFO CHOP. (default: lfo_anim)

bind_to_channel mutates

Drive one or more node parameters from a CHOP channel by expression — the link that makes a visual react. Point it at an audio_features channel (bass/mid/treble/level) or a tempo_sync channel (ramp/pulse/beat) with a scale and offset, and each target parameter tracks that signal live. This is how you wire extract_audio_features / create_tempo_sync into a visual system. Optionally add attack/release smoothing (in seconds) — or a single smooth time — to insert a Lag CHOP between the channel and the parameter so reactivity follows a clean envelope instead of flickering on raw audio (e.g. a fast attack + slow release for a punchy hit that decays smoothly).

Parameter	Type	Required	Description
targets	string[]	yes	Parameters to drive, each written as 'nodePath.parName' (e.g. '/project1/sys/transform1.scale'). Each is switched to expression mode so it tracks the channel live.
source_chop	string	yes	Path of the CHOP that carries the driving channel (e.g. an audio_features Null).
channel	string	yes	Channel name to read from the source CHOP (e.g. 'bass', 'level', 'ramp', 'pulse').
scale	number	no	Multiply the channel value (mapping gain). (default: 1)
offset	number	no	Add to the scaled value (mapping offset). (default: 0)
attack	number	no	Smoothing rise time in seconds — how slowly the bound value follows the channel UP. 0 = instant (no smoothing on the way up). A small attack with a larger release gives a snappy hit that decays smoothly (envelope follow).
release	number	no	Smoothing fall time in seconds — how slowly the bound value follows the channel DOWN. 0 = instant (no smoothing on the way down). Set release > attack to remove flicker while keeping transients punchy.
smooth	number	no	Convenience: symmetric smoothing time in seconds applied to BOTH rise and fall (sets attack=release=smooth). Use this for simple low-pass-style de-jitter; use attack/release separately for an envelope follower.
smoothing_container	string	no	Where to create the Select+Lag smoothing CHOPs when smoothing is active; defaults to the first target's parent network. Ignored when no smoothing is requested.

manage_presets mutates

Store, recall, list, or delete named snapshots of a COMP's parameter values — the live-performance preset system. Pair with create_control_panel: snapshot the knob positions and jump between looks. Snapshots are saved in the COMP's storage so they persist with the project.

Parameter	Type	Required	Description
action	store | recall | list | delete	yes	store a snapshot, recall one, list all, or delete one.
comp_path	string	no	COMP whose parameter values the preset captures — usually a control-panel container. (default: /project1)
name	string	no	Preset name (required for store/recall/delete).
params	string[]	no	Specific custom-parameter names to capture/restore. Defaults to every custom parameter on the COMP.

manage_checkpoint destructive

Store / restore / list / delete a full snapshot of a sub-network — an 'undo point' to take before risky live edits. A checkpoint captures every node's constant parameters, the wiring, and node positions. Restoring reapplies parameters, recreates nodes that were deleted since (with their wiring), and prunes nodes that were created since. Unlike manage_presets (custom-parameter looks for performance), this captures the whole network for safe experimentation.

Parameter	Type	Required	Description
action	store | restore | list | delete	yes	store a full snapshot of a sub-network, restore one, list all, or delete one. A checkpoint is an 'undo point' before risky live edits.
comp_path	string	no	Root COMP whose whole sub-network the checkpoint captures. (default: /project1)
name	string	no	Checkpoint name (required for store/restore/delete).
prune_created	boolean	no	(restore) Destroy nodes that were created after the checkpoint was stored. (default: true)
recreate_deleted	boolean	no	(restore) Recreate nodes that were deleted after the checkpoint (type + params + wiring, best-effort). (default: true)

manage_cue mutates

Live-performance scene system: store / recall / morph / list / delete named cues (snapshots of a COMP's custom-parameter values). Unlike manage_presets, a cue can be reached with a timed morph that crossfades every numeric control from the current look to the cue over N seconds (eased), via a small Execute DAT — so you can glide between looks on stage instead of hard-cutting. Recall and morph also take an optional quantize ('beat'/'bar') that defers the change to the next musical boundary (from the project tempo) so scene changes land on the downbeat. Build cues with create_control_panel, then jump or morph between them.

Parameter	Type	Required	Description
action	store | recall | morph | list | delete	yes	store a cue (snapshot of the COMP's custom params), recall it instantly, morph to it over time, list, or delete.
comp_path	string	no	COMP whose custom-parameter values the cue captures (a control-panel container). (default: /project1)
name	string	no	Cue name (required for store/recall/morph/delete).
duration	number	no	(morph) Crossfade time in seconds from the current look to the cue. (default: 2)
quantize	off | beat | bar	no	(recall/morph) Snap the scene change to the music. 'off' (the default) fires immediately. 'beat' defers the recall/morph until the next beat boundary; 'bar' until the next bar (measure) boundary — read from the project tempo (op('/').time.tempo) and time signature. The change is scheduled, not blocking.

manage_component mutates

Build a reusable component library: save any COMP as a .tox file, or load a .tox back into the project (as an independent copy, or a live-linked instance via linked). Paths are on the machine running TouchDesigner.

Parameter	Type	Required	Description
action	save | load	yes	save a COMP to a .tox file, or load a .tox into the project.
file_path	string	yes	Absolute path to the .tox file (e.g. '/Users/me/components/widget.tox').
comp_path	string	no	(save) The COMP to save as a reusable .tox component.
parent_path	string	no	(load) COMP to place the loaded component inside. (default: /project1)
linked	boolean	no	(load) Create a live-linked instance (externaltox) that re-reads the file on change, instead of an independent copy. (default: false)
name	string	no	(load, linked) Name for the linked COMP; defaults to the file name.
create_folders	boolean	no	(save) Create the parent folders if they do not exist. (default: false)

create_macro mutates

Add one macro knob (a 0–1 custom parameter) to a COMP that drives many parameters at once, each remapped into its own [min,max] range with an optional response curve — a one-to-many control for sweeping a whole look from a single fader. Targets are bound by expression so they track the macro live.

Parameter	Type	Required	Description
comp_path	string	no	COMP that will hold the macro knob (usually a control-panel container). (default: /project1)
name	string	yes	Macro control name, e.g. 'Energy' or 'Intensity'.
default	number	no	Initial macro value (0–1). (default: 0)
targets	object[]	yes	Parameters this macro drives, each remapped from the macro's 0–1 into [min,max].

randomize_controls mutates

Randomize a COMP's numeric custom parameters within their slider ranges — an instant new variation for live improvisation. amount blends toward random (1 = fully random, low values nudge the current look). Non-numeric controls (toggles, menus) are left untouched, so it is always safe to fire. Pair with manage_presets/manage_cue to snapshot a happy accident.

Parameter	Type	Required	Description
comp_path	string	no	COMP whose custom parameters to randomize (usually a control-panel container). (default: /project1)
params	string[]	no	Specific custom-parameter names to randomize. Defaults to every numeric one.
amount	number	no	How far to move toward a random value in range: 1 = fully random, 0.2 = a gentle nudge from the current value. Lets you improvise without losing the current look. (default: 1)
seed	integer	no	Optional RNG seed for repeatable results.

create_phone_remote mutates

Serve a mobile-friendly web panel from a Web Server DAT so you can control a COMP's numeric custom parameters from a phone — just open the URL, no app to install. Each parameter becomes a touch slider that writes back live. SECURITY: like the bridge, this listens on all interfaces and accepts writes with no auth, so use it only on a trusted network. Pair with create_control_panel (the params to expose) and manage_cue (snapshot looks you dial in from the phone).

Parameter	Type	Required	Description
comp_path	string	no	Control COMP whose numeric custom parameters the phone page exposes. (default: /project1)
port	integer	no	TCP port for the remote web server (keep it distinct from the bridge's 9980). (default: 9981)

create_external_io mutates

Bridge TouchDesigner to the outside world: OSC/MIDI input (a control surface — bind incoming channels straight to parameters), OSC/MIDI output (send a CHOP's channels back out for bidirectional feedback to lighting desks, other apps or hardware — pass source_path), DMX/Art-Net output for lighting (dmx_out for any DMX desk; artnet_out for network Art-Net/sACN pixel-mapping of LED strips & stage fixtures), RTMP output to live-stream a TOP to Twitch/YouTube/OBS (rtmp_out — NVIDIA GPU on Windows only), or NDI / Syphon-Spout video input. To discover which channel a control sends (a 'MIDI learn'), wiggle it and read the input CHOP with get_td_nodes, then bind_to that channel. Validate live where possible, but real signal needs the hardware/sender present.

Parameter	Type	Required	Description
kind	osc_in | midi_in | keyboard_in | gamepad_in | mouse_in | osc_out | …	yes	What to bridge: OSC/MIDI/keyboard/gamepad/mouse input (a control surface — bind channels to parameters), OSC/MIDI output (send a CHOP's channels back out for bidirectional feedback — pass source_path), DMX/Art-Net output for lighting (dmx_out is the general DMX desk; artnet_out is a network-only Art-Net/sACN preset for pixel-mapping LED strips & stage fixtures — both send a CHOP's 0-255 channels and need source_path), RTMP output to live-stream a TOP to Twitch/YouTube/OBS-ingest (rtmp_out — pass source_path = the TOP to stream and url; needs an NVIDIA GPU on Windows), or NDI / Syphon-Spout video input. (Window/recording/NDI/Syphon video outputs live in setup_output.)
parent_path	string	no	COMP to create the I/O operator in. (default: /project1)
name	string	no
port	integer	no	(osc_in) UDP port to listen on / (osc_out) port to send to. Defaults to 7000.
normalize	off | 0to1 | -1to1 | onoff	no	(midi_in) How to scale incoming MIDI values. (default: 0to1)
bind_to	object[]	no	(osc_in/midi_in) Map incoming channels to parameters. Each binding tolerates a channel that hasn't arrived yet (falls back to 0 instead of erroring).
source_path	string	no	(dmx_out/artnet_out/osc_out/midi_out) CHOP whose channel values are sent out, or (rtmp_out) the TOP to stream. Should live in the same COMP as parent_path so the wire/source connects.
interface	artnet | sacn | enttecusbpro | enttecusbpromk2 | serial | kinet	no	(dmx_out) DMX transport. (artnet_out forces a network protocol via net.) (default: artnet)
net	artnet | sacn	no	(artnet_out) Network DMX protocol: Art-Net or sACN (streaming ACN). Defaults to Art-Net.
universe	integer	no	(dmx_out/artnet_out) DMX universe. (default: 1)
net_address	string	no	(dmx_out/artnet_out) Target IP address for Art-Net / sACN.
url	string	no	(rtmp_out) Full RTMP destination as {service url}/{stream key}, e.g. 'rtmp://live.twitch.tv/app/live_xxx'. If omitted but stream_key is given, prefix with rtmp_base.
rtmp_base	string	no	(rtmp_out) Ingest base URL to combine with stream_key when url is not given (defaults to YouTube's primary ingest).
stream_key	string	no	(rtmp_out) Stream key, appended to rtmp_base as '{rtmp_base}/{stream_key}'.
fps	number	no	(rtmp_out) Frame rate to stream at. Defaults to 30.
active	boolean	no	(rtmp_out) Start streaming immediately. Defaults off so the artist can confirm the URL before going live.
source_name	string	no	(ndi_in/syphon_spout_in) Name of the NDI source or Spout sender to receive.

duplicate_network mutates

Copy a node or whole COMP (and its contents) to a new node, optionally into another parent.

Parameter	Type	Required	Description
source_path	string	yes	Path of the node/COMP to duplicate.
name	string	no	Name for the copy (auto-generated if omitted).
parent_path	string	no	Where to place the copy (defaults to the source's parent).

arrange_network mutates

Tidy an existing network: reposition a COMP's children into a readable left→right data-flow layout (sources on the left, output on the right). Use this to clean up nodes that are piled on top of each other. Set recursive to also arrange the contents of nested COMPs.

Parameter	Type	Required	Description
path	string	yes	COMP whose children to arrange, e.g. '/project1' or a container path.
recursive	boolean	no	Also arrange the nodes inside nested COMPs (each network is tidied on its own). (default: false)

create_panic mutates

Build a live-performance safety control — the 'oh no' button every VJ needs. Wraps a source in a small COMP with two instant kill switches: Blackout forces the output to black (a Level TOP's brightness1 driven to 0) and Freeze holds the last frame (a Cache TOP stops capturing, active → 0). With an input_path the source is pulled in by a Select TOP (so it can live in another container); without one a built-in Ramp TOP test source is used so it builds and previews standalone. Output is a Null TOP. Big Blackout / Freeze toggle buttons are exposed on the container so a performer can hit them instantly.

Parameter	Type	Required	Description
input_path	string	no	Optional absolute path of the live source TOP to protect. Pulled in via a Select TOP (TD wires can't cross containers, so it's referenced by path). If omitted, a built-in test source (Ramp TOP) is used so the panic COMP still builds and previews on its own.
blackout	boolean	no	Initial Blackout state. When on, the output is forced to black (Level TOP brightness1 = 0) — the instant kill switch. (default: false)
freeze	boolean	no	Initial Freeze state. When on, the last frame is held instead of passing the live input (Cache TOP stops capturing — active = 0). (default: false)
expose_controls	boolean	no	Expose big Blackout and Freeze toggle buttons on the container so a performer can hit them instantly. (default: true)
parent_path	string	no	(default: /project1)

create_clip_launcher mutates

Build an Ableton-style clip launcher: a grid panel (Container COMP) of clip buttons, one per named cue (from manage_cue), for fast hands-on scene switching during a live set. Open the container in Perform/Panel mode and tap a clip to fire its cue — instantly, or (with morph_time) crossfading to it over N seconds (eased, the same engine manage_cue uses). Store the cues with manage_cue / create_control_panel first.

Parameter	Type	Required	Description
comp_path	string	no	Control COMP that holds the cues (manage_cue) and custom params. The launcher panel is built inside it and its buttons fire that COMP's cues. (default: /project1)
name	string	no	Name of the launcher panel container to build. (default: launcher)
cues	string[]	yes	Cue names (stored with manage_cue) to lay out in the grid, in order. Each becomes a clip button labelled with its cue name.
rows	integer	no	Grid row count. Defaults so rows*cols covers all cues (derived from cues length).
cols	integer	no	Grid column count. Defaults to ceil(sqrt(cues)) when omitted (derived from cues length).
morph_time	number	no	0 = each button jumps instantly to its cue; >0 = every button crossfades to its cue over this many seconds (eased morph, same engine as manage_cue). (default: 0)

create_decks mutates

Build a DJ-style VJ mixer: deck A and deck B each pull in a source TOP (via a Select TOP, so sources can live anywhere) through a per-deck gain/opacity Level, and a master Crossfader (a Cross TOP, 0 = A, 1 = B) blends them, followed by a master FX Level and an output Null. Either deck falls back to a built-in test source (Noise for A, Ramp for B) so it builds standalone. Exposes live 'Crossfader' + per-deck 'GainA'/'GainB' knobs. Output is a Null ready for post-processing or setup_output.

Parameter	Type	Required	Description
deck_a	string	no	Absolute path of the source TOP for deck A (pulled in via a Select TOP, so it can live in another container). If omitted, a built-in test source (Noise TOP) is created so the mixer builds standalone.
deck_b	string	no	Absolute path of the source TOP for deck B (pulled in via a Select TOP). If omitted, a built-in test source (Ramp TOP) is created so the mixer builds standalone.
crossfade	number	no	Master crossfader position: 0 = full deck A, 1 = full deck B, 0.5 = even blend. (default: 0.5)
expose_controls	boolean	no	Expose live 'Crossfader' + per-deck 'GainA'/'GainB' knobs on the container so the mix is playable on arrival. (default: true)
parent_path	string	no	(default: /project1)

learn_control mutates

EXPERIMENTAL two-step 'MIDI learn'. Call once with mode:'snapshot' (controls at rest) to record every channel of an input CHOP (a midiin/oscin CHOP or a Null fed by one); then wiggle one hardware knob/fader and call again with mode:'bind' — it diffs against the snapshot, finds the channel that moved the most, and binds your target parameter to it by expression (with optional scale/offset). The snapshot is kept in the parent COMP's storage between the two calls. This is live/stateful: verify the matched channel in the report.

Parameter	Type	Required	Description
mode	snapshot | bind	yes	snapshot: record the current value of every channel of source_chop. bind: re-read source_chop, find the channel that moved the most since the snapshot, and bind target to it. Call snapshot first (controls at rest), wiggle one hardware control, then call bind.
source_chop	string	yes	Absolute path of the input CHOP carrying the hardware controls (e.g. a midiin/oscin CHOP or a Null fed by one).
target	string	no	Parameter to drive, written as 'nodePath.parName' (e.g. '/project1/sys/transform1.scale'). Required for mode:'bind'; switched to expression mode so it tracks the matched channel live.
scale	number	no	Multiply the matched channel value (mapping gain). (default: 1)
offset	number	no	Add to the scaled value (mapping offset). (default: 0)
min_delta	number	no	mode:'bind' minimum NORMALIZED movement (default 0.05). The winning channel's delta is normalized by max(|old|, |new|, epsilon) — a unit-free relative change — so a 0–127 MIDI CC and a 0–1 OSC float compare fairly. If the top channel moved less than this, nothing is bound and you're told to wiggle the control harder. Raise it to reject controller jitter; lower it for very small/slow knobs.
parent_path	string	no	COMP whose storage persists the snapshot between the snapshot and bind calls (defaults to /project1). (default: /project1)

Nodes, inspection & debugging (Layer 3)

Atomic node CRUD plus the inspection, analysis, rendering and escape-hatch tools. Read-only inspectors are safe to call freely; the Python escape hatches run code inside TouchDesigner.

get_td_info read-only

Health check + TouchDesigner server info. Returns TD/Python version and bridge status when connected, plus the embedded knowledge-base stats. Use this first to confirm the bridge is reachable.

No parameters.

create_td_node mutates

Create a single operator (node) inside a parent COMP. Validates the operator type against the knowledge base and warns (without blocking) on unknown types.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP path to create the node inside. (default: /project1)
type	string	yes	Operator type string, e.g. 'noiseTOP', 'feedbackTOP', 'nullTOP', 'constantCHOP'.
name	string	no	Optional node name (auto-generated if omitted).
parameters	object	no	Optional initial parameter overrides as key→value pairs.

delete_td_node destructive

Delete a single node by path. Destructive — only call this when the user explicitly asks to remove a node.

Parameter	Type	Required	Description
path	string	yes	Full path of the node to delete, e.g. '/project1/noise1'.

update_td_node_parameters mutates

Set one or more parameters on an existing node.

Parameter	Type	Required	Description
path	string	yes	Full path of the node whose parameters to update.
parameters	object	yes	Parameter overrides as key→value pairs, e.g. { period: 4, amplitude: 0.5 }.

get_td_nodes read-only

List the direct child nodes of a COMP. Defaults to a compact summary (count + type breakdown + sample paths); pass detail_level:"full" or path_only:true for the complete list, and pattern to filter by name.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP whose direct children should be listed. (default: /project1)
pattern	string	no	Case-insensitive filter on node name/path. Supports '' wildcards (e.g. 'text', 'noise').
path_only	boolean	no	Return only the list of node paths, dropping type/name. (default: false)
limit	integer	no	Cap the number of nodes returned.
detail_level	summary | full	no	'summary' (default) returns a count, a type breakdown and the first few paths; 'full' returns every node. Use 'full' (or path_only) when you need the complete list. (default: summary)

get_td_node_parameters read-only

Read the current parameters (and I/O) of a node. Pass keys to project specific parameters or omit_io:true to drop the inputs/outputs lists.

Parameter	Type	Required	Description
path	string	yes	Full path of the node to inspect.
keys	string[]	no	Only return these parameter names (case-sensitive). Omit to return all parameters.
omit_io	boolean	no	Drop the inputs/outputs lists from the result to save context. (default: false)

get_td_node_errors read-only

Check a node (or its whole sub-network) for cook/compile errors and warnings. Pass summary:true for grouped counts instead of the full list.

Parameter	Type	Required	Description
path	string	yes	Full path of the node (or network root) to check for errors.
recursive	boolean	no	If true, check the whole network under path; otherwise just that node. (default: false)
summary	boolean	no	Return only counts grouped by error type instead of the full error list. (default: false)

execute_python_script destructive

Escape hatch — run an arbitrary Python script inside the TouchDesigner process. Prefer the structured tools (find_td_nodes, get_td_node_parameters, update_td_node_parameters, summarize_td_errors, snapshot_td_graph, …); reach for this only when no structured tool can express the operation. Code runs in TD only, never on the local machine.

Parameter	Type	Required	Description
script	string	yes	Python source to execute inside TouchDesigner (runs in the TD process, not locally).
return_output	boolean	no	Capture stdout / the value of the last expression and return it. (default: true)

exec_node_method destructive

Escape hatch — invoke an arbitrary Python method on a node (operator). Prefer structured tools where one exists; use this for operations they don't cover (e.g. .cook(), .copy(), .destroy()).

Parameter	Type	Required	Description
path	string	yes	Full path of the node to call the method on.
method	string	yes	Method name to call, e.g. 'cook', 'par', 'destroy', 'copy'.
args	object[]	no	Positional arguments. (default: ``)
kwargs	object	no	Keyword arguments. (default: [object Object])

get_td_classes read-only

List TouchDesigner Python API classes from the embedded knowledge base (works offline). Optionally filter by name.

Parameter	Type	Required	Description
filter	string	no	Optional case-insensitive substring to filter class names by.

get_td_class_details read-only

Full documentation for one TouchDesigner Python class (members + methods) from the knowledge base.

Parameter	Type	Required	Description
class_name	string	yes	Python class name, e.g. 'OP', 'TOP', 'App', 'CHOP'.

get_module_help read-only

Human-readable help (description, members, method signatures) for a TouchDesigner Python class or module, from the knowledge base.

Parameter	Type	Required	Description
name	string	yes	Class or module name to get help for, e.g. 'OP', 'App', 'Project'.

get_td_performance read-only

Report cook times under a network (recursively by default, slowest node first) and warn about nodes that exceed the frame budget.

Parameter	Type	Required	Description
root_path	string	no	Network root to measure cook times under. (default: /project1)
target_fps	number	no	Frame-rate target used to flag slow nodes. (default: 60)
recursive	boolean	no	Measure every descendant (true, default) so cook time inside generated containers is counted, not just the root's direct children. (default: true)

get_td_topology read-only

Return the nodes and connections under a network root, flagging obvious structural issues.

Parameter	Type	Required	Description
root_path	string	no	Network root to map. (default: /project1)

find_td_nodes read-only

Search a network for nodes by name pattern and/or operator type. Recursive by default; pass path_only:true for a compact path list. Prefer this over get_td_nodes when you are looking for specific nodes.

Parameter	Type	Required	Description
parent_path	string	no	Where to search from. (default: /project1)
pattern	string	no	Case-insensitive name/path filter with '' wildcards (e.g. 'text', 'noise').
type	string	no	Case-insensitive operator-type substring (e.g. 'TOP', 'noise').
recursive	boolean	no	Search the whole sub-network (true) or only direct children (false). (default: true)
path_only	boolean	no	Return only matching paths. (default: false)
limit	integer	no	Max matches to return. (default: 50)

summarize_td_errors read-only

Collect errors across a network and cluster them by message, type, or parent container, with the worst-offending nodes and a suggested order to investigate. Use this instead of reading every node's errors one by one.

Parameter	Type	Required	Description
path	string	no	Network root to collect errors under. (default: /project1)
group_by	message | type | parent	no	How to cluster errors: by exact message, by error type, or by parent container (to find a common upstream cause). (default: message)

compare_td_nodes read-only

Diff the parameters of two nodes, returning only the values that differ (by default). Useful for aligning settings across similar operators.

Parameter	Type	Required	Description
path_a	string	yes	First node path.
path_b	string	yes	Second node path.
only_diff	boolean	no	Return only the parameters that differ (true) or also list the identical ones. (default: true)

snapshot_td_graph read-only

Capture a compact, serializable snapshot of a network — nodes, connections, structural issues, and optionally each node's parameters — for review, diffing, or documentation.

Parameter	Type	Required	Description
path	string	no	Network root to snapshot. (default: /project1)
include_params	boolean	no	Also fetch each node's parameters (one request per node; capped for large graphs). (default: false)

reload_bridge mutates

Hot-reload the bridge's Python inside the running TouchDesigner, so edits to the td/ modules take effect without reopening the project. Reimports every loaded mcp./utils. module in place and returns the list reloaded. Use after editing bridge code.

No parameters.

search_operators read-only

Search the embedded operator knowledge base (629 operators) by keyword — name, family or description — ranked by relevance, fully offline. Use it to discover the right operator before creating nodes instead of guessing a type (e.g. 'what sends DMX?', 'particle', 'corner pin'). Returns name, family and a one-line summary per hit. Pass semantic:true to re-rank by embedding similarity (needs an LLM endpoint; falls back to keyword).

Parameter	Type	Required	Description
query	string	yes	What you're looking for — words from a name, family, or description (e.g. 'blur edge', 'audio spectrum', 'instance geometry').
limit	integer	no	Max results to return. (default: 20)
semantic	boolean	no	Opt-in: re-rank keyword candidates by embedding similarity via the configured LLM endpoint (TDMCP_LLM_BASE_URL / _MODEL, Ollama by default). Better for fuzzy/conceptual queries. Falls back to keyword ranking if the endpoint is unavailable — the default (false) needs nothing. (default: false)

document_network read-only

Document an EXISTING network: read its nodes and connections and return a readable map — counts by operator family and type, plus a Mermaid flowchart of the data flow you can paste into docs. Unlike plan_visual (which plans from a description), this describes what's actually in the project. Use it to explain or hand off a patch.

Parameter	Type	Required	Description
path	string	no	Network root to document. (default: /project1)
recursive	boolean	no	Include all descendants (otherwise just the direct children). (default: false)

diff_snapshots read-only

Compare two network snapshots (from snapshot_td_graph) and return a readable diff: which nodes were added or removed, which connections changed, and which parameters changed (with before/after values). Snapshot before an edit and after to see exactly what changed, or to version a patch over time. Pure analysis — touches nothing in TouchDesigner.

Parameter	Type	Required	Description
before	object	yes	Earlier snapshot (from snapshot_td_graph, include_params for param diffs).
after	object	yes	Later snapshot to compare against.

optimize_performance mutates

Scan a network for cook-time bottlenecks and (optionally) fix them. By default it reports the slowest nodes with a concrete suggestion each. With apply:true it lowers the resolution of the flagged TOPs by scale to claw back GPU time. Run get_td_performance first if you just want the numbers; use this to act on them.

Parameter	Type	Required	Description
path	string	no	Network to analyze (recursively). (default: /project1)
threshold_ms	number	no	Flag nodes whose last cook took at least this many milliseconds. (default: 2)
apply	boolean	no	If true, actually lower the resolution of the flagged TOPs by scale. Default false = just report the bottlenecks and suggestions. (default: false)
scale	number	no	(apply) Resolution multiplier for flagged TOPs (0.5 = half on each axis). (default: 0.5)

render_output mutates

Save a TOP to an image file at its native, full resolution (PNG/JPG/EXR/TIFF by extension) — for exporting a finished frame, unlike get_preview which only transfers a small inline thumbnail. The file is written by TouchDesigner on the TD machine; pass an absolute path.

Parameter	Type	Required	Description
node_path	string	yes	Path of the TOP to render to a file.
file	string	yes	Output file path (written by TouchDesigner, so on the TD machine). Extension picks the format: .png/.jpg/.exr/.tiff. Use an absolute path.

record_movie mutates

Record a TOP to a movie file (.mov/.mp4) via a Movie File Out TOP — for exporting a clip or a loop, where render_output only saves a single frame. start begins recording (pass file, fps); pass seconds to auto-stop after a fixed length, or call stop to finish (stop also cleans up the recorder node). The file is written by TouchDesigner on the TD machine. For individual numbered frames, use render_output per frame.

Parameter	Type	Required	Description
action	start | stop	no	start recording the TOP to a file, or stop the current recording. (default: start)
node_path	string	yes	Path of the TOP to record.
file	string	no	(start) Output movie path on the TD machine, with a .mov or .mp4 extension. Absolute path recommended.
fps	number	no	(start) Frames per second. (default: 30)
seconds	number	no	(start) If set, auto-stop after this many seconds (records a fixed-length loop); otherwise record until you call stop.

Obsidian vault

Bridge an Obsidian vault (set TDMCP_VAULT_PATH) and TouchDesigner: keep recipes, shaders, setlists, presets, moodboards and a dated show diary in Markdown and move them in and out of your project.

scaffold_vault mutates

Populate the configured Obsidian vault with a starter layout and worked examples (a recipe, setlist, shader, and moodboard note) so you begin from a working vault instead of an empty folder. Skips existing files unless overwrite. Requires TDMCP_VAULT_PATH.

Parameter	Type	Required	Description
overwrite	boolean	no	Overwrite starter files that already exist (otherwise they're left untouched). (default: false)

save_recipe_to_vault mutates

Capture a COMP's network (nodes, parameters, wiring, text/script DAT bodies) as a reusable recipe note in the Obsidian vault (Recipes/<id>.md). list_recipes/apply_recipe then see it alongside the built-in recipes. Requires TDMCP_VAULT_PATH.

Parameter	Type	Required	Description
id	string	yes	Recipe id/slug; also the note filename written under Recipes/ in the vault.
comp_path	string	no	COMP whose direct children are captured as the recipe. (default: /project1)
name	string	no	Human-friendly title (defaults to the id).
description	string	no
tags	string[]	no
difficulty	beginner | intermediate | advanced	no
overwrite	boolean	no	Overwrite an existing recipe note with the same id. (default: false)

apply_shader_from_vault mutates

Read a shader note from the Obsidian vault (a glsl fragment block, optional glslvert vertex block, and optional uniforms/resolution/name frontmatter) and create a GLSL TOP from it. Requires TDMCP_VAULT_PATH.

Parameter	Type	Required	Description
note	string	yes	Shader note: a vault-relative path, or a name resolved against the Shaders/ folder.
parent_path	string	yes	Parent COMP to create the GLSL TOP inside.
name	string	no	Name for the GLSL TOP (defaults to the note's frontmatter name, else 'glsl1').

sync_presets_vault mutates

Export a COMP's manage_presets snapshots to a markdown note (diffable, shareable), or import a note's presets back into TD storage. Requires TDMCP_VAULT_PATH.

Parameter	Type	Required	Description
action	export | import	yes	export TD presets to a vault note, or import a note's presets back into TD.
comp_path	string	no	COMP whose presets live in storage (the manage_presets target). (default: /project1)
note	string	no	Vault note path (defaults to Presets/<comp>.md).

export_network_to_vault mutates

Document an existing TD network into an Obsidian note: a Mermaid flowchart plus [[wikilinks]] for every operator and connection, so the vault's graph view becomes a clickable map of the patch. Requires TDMCP_VAULT_PATH.

Parameter	Type	Required	Description
path	string	no	Network root to document. (default: /project1)
recursive	boolean	no	Include all descendants (otherwise just the direct children). (default: false)
note	string	no	Vault note path (defaults to Networks/<path>.md).

log_performance mutates

Capture a dated performance-journal entry in the vault: a network snapshot (node/connection counts + any errors) and an optional preview thumbnail, written to Performances/<date>-<title>.md. Build a diary of your shows. Requires TDMCP_VAULT_PATH.

Parameter	Type	Required	Description
title	string	no	Short title for the entry (e.g. venue or set name).
comp_path	string	no	Network to snapshot for the log. (default: /project1)
output_path	string	no	TOP to capture as the entry's thumbnail.
notes	string	no	Free-form notes: what played, what worked.
width	integer	no	(default: 640)
height	integer	no	(default: 360)

import_setlist mutates

Read a setlist note (frontmatter tracks: an array of recipe ids, or {title, recipe, preset, bpm, notes} objects) and build each track's recipe into the project — pre-staging a show's visuals. Recipes resolve against built-in and vault recipes. Use dry_run to validate first. Requires TDMCP_VAULT_PATH.

Parameter	Type	Required	Description
note	string	yes	Setlist note: a vault-relative path, or a name resolved against the Setlists/ folder.
parent_path	string	no	COMP to build each track's recipe inside. (default: /project1)
dry_run	boolean	no	Only resolve and report what would be built; do not touch TouchDesigner. (default: false)

bind_vault_text mutates

Create a Text DAT whose content is read from a vault note (and, with sync on, kept live as you edit the note in Obsidian) — turning the vault into the text/lyrics source for your visuals. Wire the DAT into a Text TOP to render it. Requires TDMCP_VAULT_PATH.

Parameter	Type	Required	Description
note	string	yes	Vault-relative note to read into TD (lyrics, poetry, any text content).
parent_path	string	yes	Parent COMP to create the Text DAT inside.
name	string	no	Name for the Text DAT (defaults to a slug of the note).
sync	boolean	no	Keep the DAT synced to the file, so edits in Obsidian show up live in TD. (default: true)

generate_from_moodboard mutates

Read a moodboard note (frontmatter technique/palette/colors/speed + a prose description) and create a matching generative system via create_generative_art. Best-effort: the palette is a hint. Requires TDMCP_VAULT_PATH.

Parameter	Type	Required	Description
note	string	yes	Moodboard note: a vault path, or a name resolved against the Moodboards/ folder.
parent_path	string	no	COMP to build the generative system in. (default: /project1)
technique	string	no	Override the technique (otherwise the note's technique frontmatter, else fractal).