Generated by scripts/gen-tool-docs.ts; edit the registry instead of this page. Regenerate with npm run docs:gen (runs automatically before docs:build).

Tools reference

tdmcp exposes 497 tools organized into three layers, foundation primitives, library/packaging, CLI automation, AI session memory, and 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, overwrite, run code, or write package assets.

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

Foundation primitives

Low-level visual building blocks shared by higher-level importers and effects, exposed directly when you need precise control over the underlying mapping or shader network.

apply_glsl_top_mapping mutates

Build a self-contained GLSL TOP network from a pre-translated mapping (fragment + uniforms + channels + controls). Foundation primitive used by Shadertoy and ISF importers; also reachable directly for power users with a hand-translated fragment.

Parameter	Type	Required	Description
mapping	object	yes	Pre-built mapping (fragment + uniforms + channels + controls + provenance).
parent_path	string	no	Parent COMP path where the system container is created. (default: /project1)
name	string	no	Name of the container COMP created under parent_path. (default: glsl_mapping)
resolution	object[]	no	GLSL TOP output resolution [width, height]. (default: 1280,720)
pixel_format	rgba8 | rgba16 | rgba32	no	GLSL TOP pixel format. (default: rgba8)
expose_controls	boolean	no	If false, skip the control panel pass. (default: true)
capture_preview	boolean	no	Capture a preview image of the output TOP after the build. (default: true)

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. Creates a new baseCOMP under parent_path holding the seed, a Feedback TOP, a 'maximum' Composite, the transform chain, a Level decay node, an optional GLSL colorize pass, and a Null output (the Feedback TOP samples the Level node to close the loop). Great for evolving, hypnotic visuals. Exposes a live 'Feedback' decay knob. Returns a summary plus a JSON block with the container path, created node paths, the output path, exposed controls, any node errors, warnings, and an inline preview image. Use this for a general feedback look with a chosen seed type and an ordered chain of effects; for the specific infinite-zoom/rotate spiral (with Zoom/Rotate/HueShift/Decay knobs) use create_feedback_tunnel instead.

Parameter	Type	Required	Description
seed_type	noise | shape | image | video | webcam | glsl	no	What feeds the loop each frame: 'noise' (monochrome Noise TOP), 'shape' (Circle TOP), 'image'/'video' (Movie File In TOP), 'webcam' (Video Device In TOP — may prompt for camera permission), or 'glsl' (a generative shader). Default 'noise'. (default: noise)
transformations	blur | displace | edge | level | hsv_adjust | transform | …[]	no	TOP effects applied in order inside the loop each frame (blur, displace, edge, level, hsv_adjust, transform, mirror, tile, luma_blur). Default ['blur','displace','level']. (default: blur,displace,level)
feedback_gain	number	no	Loop decay multiplier (0–1) applied via a Level TOP's brightness1: how much of the fed-back frame survives each cycle. Higher = longer-lived, more saturated trails; default 0.95. (default: 0.95)
colors	string[]	no	Up to two hex colors ('#rrggbb') used to colorize the otherwise-grayscale output via a final GLSL gradient (one color = black→color, two = color0→color1). Omit to leave it grayscale.
expose_controls	boolean	no	When true (default), expose a live 'Feedback' knob on the system container, bound to the loop's decay. (default: true)
parent_path	string	no	Parent network where the feedback container is created (default '/project1'). (default: /project1)

create_generative_art mutates

Create an evolving generative visual. Creates a new baseCOMP under parent_path holding the generator (a recipe network, a GLSL TOP + Text DAT, or a noise chain) ending in a Null output. 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 (with a warning). Exposes a live 'Speed' knob (except for recipe-built techniques). Returns a summary plus a JSON block with the container path, created node paths, the output path, exposed controls, the technique, any node errors, warnings, and an inline preview image.

Parameter	Type	Required	Description
technique	noise_landscape | reaction_diffusion | strange_attractor | l_system | cellular_automata | flow_field | …	yes	Generative method. reaction_diffusion/noise_landscape build validated recipes; strange_attractor/voronoi/fractal render faithful inline GLSL; custom_glsl uses your shader (custom_glsl_code); l_system/cellular_automata/flow_field currently fall back to an animated-noise approximation (with a warning).
color_palette	string	no	Free-text palette hint recorded in the result; best-effort, not all techniques honor it.
evolution_speed	number	no	Animation speed multiplier on the time uniform driving the look (1 = nominal, higher = faster evolution). Exposed as the 'Speed' knob. (default: 1)
custom_glsl_code	string	no	Fragment shader source used only when technique='custom_glsl'; if omitted, a default plasma shader is used (with a warning).
expose_controls	boolean	no	When true (default), expose a live 'Speed' knob (evolution speed) on the system container. (default: true)
parent_path	string	no	Parent network where the generative container is created (default '/project1'). (default: /project1)

create_audio_reactive mutates

Build an audio analysis chain (spectrum + level + optional beat) and a spectrum visual driven by it. Creates a new baseCOMP under parent_path holding the audio source, an Audio Spectrum CHOP, an Analyze level, an optional Beat CHOP, a CHOP-to-TOP texture with a Sensitivity gain, the GLSL visual, and a Null output. Each visual_style renders the spectrum its own way: glsl=horizontal bars, geometric=radial bars, particle=dot field, feedback=ring tunnel, instancing=LED grid. Returns a summary plus a JSON block with the container path, created node paths, the output path, exposed controls, any node errors, warnings, and an inline preview image. This is the only audio tool that produces a built-in visual: use extract_audio_features for level/bass/mid/treble channels or create_spectrum for per-band channels (no visual), and bind_audio_reactive to wire those channels onto an existing COMP's knobs.

Parameter	Type	Required	Description
audio_source	microphone | file | device_in | existing_chop	no	Where audio comes from: 'microphone'/'device_in' create an Audio Device In CHOP, 'file' an Audio File In CHOP (set audio_file_path), 'existing_chop' reuses an audio CHOP you already have (set existing_chop_path). (default: microphone)
audio_file_path	string	no	Path to an audio file to play; used only when audio_source='file'.
existing_chop_path	string	no	Path of an existing audio CHOP to analyze; used only when audio_source='existing_chop'.
visual_style	geometric | particle | feedback | glsl | instancing	yes	How the spectrum is rendered: glsl=horizontal bars, geometric=radial bars, particle=dot field, feedback=ring tunnel, instancing=LED grid.
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	When true (default), add a Beat CHOP driven by the audio source for tempo/beat signals. (default: true)
expose_controls	boolean	no	When true (default), expose a live 'Sensitivity' knob controlling how strongly the audio drives the visual. (default: true)
parent_path	string	no	Parent network where the audio-reactive container is created (default '/project1'). (default: /project1)
transient_gate	boolean	no	When true, add a transient/onset channel to a new modulation Null CHOP (mod1) for binding to parameters. (default: false)
transient_threshold	number	no	Transient threshold (0–1); used only when transient_gate=true. (default: 0.3)
transient_hold_ms	number	no	Transient hold time in ms before decay; used only when transient_gate=true. (default: 120)
sidechain_duck	boolean	no	When true, add an inverted duck-envelope channel to the modulation Null CHOP (mod1). (default: false)
duck_depth	number	no	How deeply the duck pulls toward 0 at peak level (0–1). (default: 0.7)
duck_release_ms	number	no	Release time of the duck envelope in ms. (default: 350)

create_particle_system mutates

Build a CPU particle system: an emitter SOP feeds a Particle SOP inside a Geometry COMP, rendered with a camera + light. Creates a new baseCOMP under parent_path holding the Geometry COMP (emitter + particle SOP), a material, Camera, Light, Render TOP, and a Null output. Forces and render style are scaffolded for further tuning. Exposes live Drag / Turbulence / Gravity / Lifetime knobs. This is the simplest CPU emitter, born from a real SOP shape; pick a sibling instead when you need scale or specific motion: create_gpu_particle_field for much higher counts (GPU-simulated noise/curl/gravity drift, up to ~262k), create_particle_flock for boids/flocking behaviour, image_to_particles to reconstruct an image/video as points, create_pop_particle_system for TouchDesigner's native POP particle network. Returns a summary plus a JSON block with the container path, created node paths, the output path, exposed controls, any node errors, warnings (e.g. approximated forces or fallback render styles), and an inline preview image.

Parameter	Type	Required	Description
emitter_shape	point | line | circle | sphere | mesh | image	no	Source SOP particles are born from: point (Add SOP), line, circle, sphere, mesh (Box), or image (Grid). Default 'sphere' — its varied normals spray a full radial cloud; 'point' has no normals and stays a thin turbulence-driven stream. (default: sphere)
particle_count	integer	no	Target number of live particles at steady state; sets the Particle SOP birth rate (birth ≈ count / lifetime). Default 10000. (default: 10000)
forces	gravity | noise | attract | repel | vortex | turbulence | …[]	no	Forces applied to the sim, mapped to native Particle SOP params (gravity→external -Y, noise/turbulence→turbulence, drag→drag). attract/repel/vortex have no native equivalent and are approximated with turbulence (a warning is returned). Default ['noise','gravity']. (default: noise,gravity)
render_style	points | sprites | lines | trails | instanced_geo	no	How particles are drawn. 'sprites' uses a Point Sprite MAT, 'points' a Constant MAT; 'lines'/'trails'/'instanced_geo' currently fall back to point/sprite rendering (a warning is returned). Default 'sprites'. (default: sprites)
lifetime	number	no	Particle life span in seconds before it dies and is reborn. Default 3. (default: 3)
expose_controls	boolean	no	When true (default), expose live Drag / Turbulence / Gravity / Lifetime knobs on the system container. (default: true)
parent_path	string	no	Parent network where the particle-system container is created (default '/project1'). (default: /project1)

create_data_visualization mutates

Build a data-driven visualization: a data source feeds a CHOP that drives a chart TOP. Creates a new baseCOMP under parent_path holding a 'data' source operator (seeded with placeholder values), a DAT-to-CHOP / CHOP-to-TOP conversion, a Scale level, the chart visual, and a Null output. Wire your real data into the created 'data' node. Returns a summary plus a JSON block with the container path, created node paths, the output path, exposed controls, any node errors, warnings (including a reminder to wire real data), and an inline preview image.

Parameter	Type	Required	Description
data_source	table | file | chop	no	Kind of source operator to create: 'table' (Table DAT, pre-seeded with sample values), 'file' (File In DAT), or 'chop' (Constant CHOP). Wire your real data into the created 'data' node afterward. (default: table)
chart_style	bars | graph | points	no	Visual style. 'bars' renders a GLSL bar chart; 'graph' and 'points' currently render the data as a texture strip and add a warning that richer plotting needs customization. (default: bars)
expose_controls	boolean	no	When true (default), expose a live 'Scale' knob that amplifies the data values feeding the chart. (default: true)
parent_path	string	no	Parent network where the visualization container is created (default '/project1'). (default: /project1)

apply_post_processing mutates

Chain post-processing effects (bloom, glitch, rgb_split, vignette, etc.) onto an existing TOP, applied in the order given. Creates a new baseCOMP under parent_path that pulls the source in via a Select TOP, wires each effect (built-in TOPs or inline-GLSL passes) in series, and ends in a Null TOP. Returns a summary plus a JSON block with the container path, all created node paths, the output Null path, any node errors, warnings, and an inline preview image. Use create_color_grade or create_glitch instead when you want a single dedicated effect with its own exposed controls.

Parameter	Type	Required	Description
source_path	string	yes	Path of the existing TOP to post-process (e.g. '/project1/render1'); pulled in via a Select TOP so it may live in another container.
effects	bloom | chromatic_aberration | film_grain | vignette | color_grade | sharpen | …[]	yes	Effects to apply, chained in the order listed. Each is one of: bloom, chromatic_aberration, film_grain, vignette, color_grade, sharpen, blur, edge_detect, invert, threshold, posterize, glitch, rgb_split, scanlines, halftone, dither, crt, mirror, vhs, npr_oil, npr_pencil, npr_watercolor. The 3D-aware modes ssao / ssr / dof / motion_blur are recognized but redirect to the dedicated post_passes_3d tool (they need depth/normal/velocity AOVs that this chain doesn't have).
parent_path	string	no	Parent network where the effect-chain container is created (default '/project1'). (default: /project1)

setup_output mutates

Route a finished TOP to an output destination: a display window, NDI stream, Syphon/Spout, a recording, or Touch Out. Creates the matching output node ('<output_type>out') under parent_path; for a window it points the Window COMP's winop at the source and sets its size, and for the other types it bridges the source in through a Select TOP (TD wires can't cross COMP boundaries). Typically the LAST step after building a visual — feed it the output Null from a create* tool or a create_layer_mixer. Returns the created output node path, the output type, the source path, and any non-fatal warnings (e.g. if wiring or window config failed).

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	Destination: 'window' (a Window COMP display), 'ndi' (NDI Out TOP network stream), 'syphon_spout' (Syphon/Spout Out TOP for other apps), 'record' (Movie File Out TOP to disk), or 'touch_out' (Touch Out TOP to another TD instance). (default: window)
resolution	720p | 1080p | 4K	no	Window size for output_type='window' (720p=1280×720, 1080p=1920×1080, 4K=3840×2160); ignored by the other output types. (default: 1080p)
record_format	mp4 | mov | image_sequence	no	File format for output_type='record' (sets the Movie File Out TOP's type); ignored otherwise.
parent_path	string	no	Parent COMP path the output node (and any bridging Select TOP) is created inside. (default: /project1)

get_preview read-only

Capture a TOP node's current output as an inline PNG image so you can see what was created — read-only, it creates and modifies nothing. Returns the image (scaled to width×height) plus a caption with the node path and actual dimensions; only TOPs can be previewed (CHOP/SOP/etc. have no image). For a much cheaper check (is it alive / roughly what colour?) pass sample_grid=N to get an N×N grid of RGBA samples + per-channel stats as JSON instead of an image.

Parameter	Type	Required	Description
node_path	string	no	Path of the TOP node to capture. Required unless collecting a deferred job by job_id.
width	integer	no	Width of the captured preview image in pixels (1–4096; default 640). (default: 640)
height	integer	no	Height of the captured preview image in pixels (1–4096; default 360). (default: 360)
sample_grid	integer	no	When set (2–16), return a lightweight N×N grid of RGBA samples + per-channel min/max/mean as JSON instead of an image — 10–50× cheaper. Use this when you only need to know whether the output is alive / roughly what colour it is, not its spatial detail.
pre_pulses	object[]	no	Parameters to pulse in the SAME frame immediately before capturing — e.g. reset a feedback loop or fire a timer so a transient is actually visible. All targets are validated before any fires (all-or-nothing).
delay_frames	integer	no	Defer the capture by N frames (to catch an event that appears a few frames after a pulse). Returns a job_id + wait_ms instead of the image; call get_preview again with that job_id to collect the result.
job_id	string	no	Collect a previously deferred capture (from a delay_frames call) by its job_id.

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 delegates to the matching Layer-1 builder (or a tag-matched recipe), creating a self-contained COMP under parent_path, then verifies and previews it. Use plan_visual instead for a dry run that reports which tool/recipe would be chosen without building anything. Returns a note on how the description was interpreted plus the underlying builder's result (created nodes, exposed controls, and a preview image).

Parameter	Type	Required	Description
description	string	yes	Natural-language description of the visual system.
parent_path	string	no	Parent COMP path the generated visual-system container is created inside. (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. Use create_spectrum for N fine per-band channels instead of these four coarse bands, and pass this Null as the source_chop to bind_audio_reactive to make a whole COMP react.

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	Parent COMP path the self-contained 'audio_features' container is created inside. (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. Creates a new baseCOMP under parent_path holding the source, a downsized monochrome analysis chain, and a 'features' Null CHOP output. 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. Returns a summary plus a JSON block with the container path, created node paths, the features Null path, the channel names, exposed controls, any node errors, and warnings (no preview image — the output is a CHOP, not a TOP).

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	Path to a movie file to play as the source; used only when source='file'.
existing_top_path	string	no	Path of an existing TOP to analyze; used only when 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	When true (default), expose a live 'Sensitivity' knob (a gain over every feature channel). (default: true)
parent_path	string	no	Parent network where the motion-reactive container is created (default '/project1'). (default: /project1)

create_interactive_projection_mapping mutates

Build a synthetic-safe interactive projection mapping rig for a USB webcam plus projector: camera/synthetic/existing TOP input, frame-difference motion field, placeholder blob/post-it mask, cyan dot and magenta card visual TOPs, manual Corner Pin projection mapping, debug switch, live controls, and an out1 Null TOP. Defaults to source='camera' for installations, but source='synthetic' previews without camera permission. Returns output/debug paths and explicit warnings for camera, blob tracking, and physical calibration states.

Parameter	Type	Required	Description
name	string	no	Name for the generated interactive projection mapping Base COMP. (default: interactive_projection_mapping)
parent_path	string	no	Parent COMP where the interactive projection mapping system is created. (default: /project1)
source	camera | synthetic | existing_top	no	Input source: a USB camera, a self-animated synthetic TOP, or an existing TOP pulled through a Select TOP. (default: camera)
existing_top_path	string	no	Absolute TOP path required when source='existing_top'.
camera_index	integer	no	USB/webcam device index used when source='camera'. (default: 0)
fallback_to_synthetic	boolean	no	If camera creation fails, build a synthetic source so the rig remains previewable. (default: true)
interaction_mode	hybrid | motion_only | blob_markers	no	Interaction branch to prioritize. The first slice always keeps motion available. (default: hybrid)
analysis_resolution	integer	no	Square working resolution for cheap motion/blob analysis. (default: 256)
output_width	integer	no	Projection output width in pixels. (default: 1280)
output_height	integer	no	Projection output height in pixels. (default: 720)
particle_count	integer	no	Target count for the cyan dot field. This MVP uses it as visual density metadata. (default: 64)
card_count	integer	no	Target count for magenta card blocks. This MVP uses it as visual density metadata. (default: 5)
motion_sensitivity	number	no	Gain over the frame-difference motion field. (default: 4)
repel_radius	number	no	Normalized radius metadata for hand/motion repulsion. (default: 0.18)
trail_decay	number	no	Feedback persistence for visual trails. (default: 0.88)
blob_threshold	number	no	Threshold used by the placeholder blob/post-it mask branch. (default: 0.55)
max_blobs	integer	no	Maximum blob slots reserved for the later marker-tracking branch. (default: 8)
dot_color	string	no	Cyan dot color as #rrggbb. (default: #8ff4f2)
card_color	string	no	Magenta card color as #rrggbb. (default: #ff2f9a)
background_color	string	no	Dark projected background color as #rrggbb. (default: #05100e)
projection_brightness	number	no	Final Level TOP brightness before out1. (default: 0.85)
debug_view	final | camera | analysis | motion | blobs | calibration | …	no	Which branch the debug switch shows initially. (default: final)
expose_controls	boolean	no	Expose live controls for calibration/debug/performance tuning. (default: true)

create_kinect_wall_harp mutates

Build a synthetic-safe Kinect v2 / FreenectTD projected wall harp in an isolated Base COMP. The network can create a FreenectTOP depth path when explicitly enabled, listen to an external OSC Kinect bridge with source='osc_kinect', or build a synthetic fallback. It extracts left/right hand centroids, divides the projection into configurable musical zones, triggers short electronic plucks on zone entry, renders a denser vibrating curtain of projected strings, and exposes depth/mask/hands/audio plus bridge-status diagnostics. If FreenectTD or Kinect hardware is unavailable, the tool returns warnings instead of throwing, so the visual/audio/trigger chain can still be tested offline.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP path where the isolated kinect_wall_harp Base COMP is created. (default: /project1)
name	string	no	Name for the generated Base COMP under parent_path. (default: kinect_wall_harp)
source	freenect | synthetic | osc_kinect	no	Input source. 'freenect' tries the FreenectTD FreenectTOP Kinect v2 path; 'synthetic' builds a device-free wall-touch simulator; 'osc_kinect' listens for normalized Kinect hand points from an external OSC bridge. (default: freenect)
osc_port	integer	no	UDP port for OSC Kinect hand input when source='osc_kinect'. (default: 7400)
bridge_status_json	string	no	JSON status path written by scripts/kinect-wall-harp-bridge.mjs --status-json and read by the generated bridge_status DAT. (default: _workspace/kinect-wall-harp/bridge-status.json)
fallback_to_synthetic	boolean	no	When true, missing FreenectTD/Kinect hardware still creates a playable synthetic fallback with warnings. (default: true)
deactivate_existing_freenect	boolean	no	Deactivate existing FreenectTOP nodes under parent_path before starting the new Kinect source. Kinect v2 is a single-device path, so this avoids multiple active FreenectTD nodes competing for the same sensor. (default: true)
activate_freenect	boolean	no	Safety gate for actually creating/activating FreenectTOP. Default false because FreenectTD Kinect v2 initialization is unstable on the validated macOS setup; leave false for crash-safe synthetic fallback. (default: false)
output_width	integer	no	Width for generated debug and projected output TOPs. (default: 1280)
output_height	integer	no	Height for generated debug and projected output TOPs. (default: 720)
wall_depth_center	number	no	Normalized depth value representing the calibrated wall/touch plane. (default: 0.5)
touch_thickness	number	no	Accepted depth band around wall_depth_center. (default: 0.08)
depth_polarity	near | far	no	Which side of the wall-depth band should count as touch candidates. (default: near)
sensitivity	number	no	Blob threshold / cleanup aggressiveness for the wall-touch mask. (default: 0.65)
smoothing	number	no	Hand centroid smoothing amount used by the tracking Script CHOP. (default: 0.18)
crop_left	number	no	(default: 0)
crop_right	number	no	(default: 1)
crop_top	number	no	(default: 0)
crop_bottom	number	no	(default: 1)
input_mirror_x	boolean	no	Mirror normalized hand X after OSC input, before projector-space calibration. (default: false)
input_left	number	no	Raw normalized Kinect X that maps to the projector's left edge. (default: 0)
input_right	number	no	Raw normalized Kinect X that maps to the projector's right edge. (default: 1)
input_top	number	no	Raw normalized Kinect Y that maps to the projector's top edge. (default: 0)
input_bottom	number	no	Raw normalized Kinect Y that maps to the projector's bottom edge. (default: 1)
show_debug	boolean	no	When true, the visual Script TOP draws hand dots and zone guides. (default: false)
calibration_hold_ms	integer	no	Milliseconds a hand must remain stable on a calibration target before auto-capture. (default: 900)
string_count	integer	no	Number of musical trigger zones across the projected wall harp. (default: 16)
visual_line_count	integer	no	Number of visible projected laser lines. Can exceed string_count for curtain behavior. (default: 128)
curtain_spread	number	no	How many neighboring visual lines share vibration from each musical zone. (default: 3.2)
curtain_follow	number	no	How strongly nearby visual lines bend around tracked wall-touch hands. (default: 0.5)
cooldown_ms	integer	no	Per-string retrigger guard in milliseconds. (default: 150)
frequencies	number[]	no	Pluck frequencies for the musical trigger zones. (default: 130.81,146.83,164.81,196,220,246.94,261.63,293.66,329.63,392,440,493.88,523.25,587.33,659.25,783.99)
master_volume	number	no	Overall gain for the internal pluck Script CHOP. (default: 0.35)
audio_device	string	no	Optional Audio Device Out device name. Leave empty to keep TouchDesigner's default device. (default: ``)
audio_sample_rate	integer	no	Script CHOP audio sample rate. Set to 192000 when using UMC202HD at 192k. (default: 48000)
decay	number	no	Electronic pluck decay in seconds. (default: 0.45)
brightness	number	no	Very subtle harmonic color for the generated sine pluck tone. (default: 0.08)
reverb_mix	number	no	Wet reverb mix for the internal pluck synth. (default: 0.22)
reverb_decay	number	no	Feedback decay for the internal algorithmic reverb. (default: 0.68)
reverb_damping	number	no	High-frequency damping for the internal algorithmic reverb. (default: 0.45)
base_color	string	no	Idle projected string color as #RRGGBB. (default: #050505)
hit_color	string	no	Touched string color as #RRGGBB. (default: #FFB000)
background_level	number	no	Neutral projected background brightness; 0.0 leaves the wall unlit behind the laser lines. (default: 0)
glow	number	no	Visual glow multiplier for active strings. (default: 1.25)
vibration_amount	number	no	Maximum horizontal string vibration in pixels. (default: 18)
vibration_decay	number	no	Visual vibration decay in seconds. (default: 0.7)
expose_controls	boolean	no	Expose calibration, harp, audio, and visual controls on the generated COMP. (default: true)

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. Creates a new baseCOMP under parent_path holding the Select TOP, per-tile Crop (+ optional GLSL feather) and Null outputs, and optional Window COMPs. 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). Use setup_output instead for a single-window output; create_dome_output/create_cubemap_dome for curved/fulldome instead of flat tiling. Returns a summary plus a JSON block with the container path, created node paths, the first output path, the full list of output and window paths, and any node errors/warnings, with an inline preview image of the first tile.

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	Parent network where the multi-output container is created (default '/project1'). (default: /project1)

sync_external_clock mutates

Lock the project tempo to a live source so beat-synced visuals follow the music. mode picks the source: 'tap' (default) gives a Bpm knob + Tap pulse you dial/tap by ear; 'ableton_link' locks to an Ableton Link session on the network; 'midi_clock' derives BPM from incoming MIDI timing-clock (24 PPQN). All modes write the global tempo (op('/').time.tempo), so create_tempo_sync clocks and create_autopilot follow. The Link/MIDI modes are hardware-gated — without that source present the manual Bpm knob still drives the clock.

Parameter	Type	Required	Description
bpm	number	no	Starting tempo in BPM (match the DJ's displayed BPM, then fine-tune by tapping). (default: 120)
mode	tap | ableton_link | midi_clock	no	How the tempo is sourced. 'tap' (default): a Bpm knob + Tap pulse you dial/tap by ear. 'ableton_link': lock to an Ableton Link session on the network (an Ableton Link CHOP's tempo drives the clock). 'midi_clock': derive BPM from incoming MIDI timing-clock (24 PPQN). The Link/MIDI modes need that source present on the machine — without it they fall back to the manual Bpm knob. (default: tap)
parent_path	string	no	Parent COMP path the self-contained 'tempo_clock' container is created inside. (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	Parent COMP path the self-contained 'tempo_sync' container is created inside. (default: /project1)

create_text_overlay mutates

Composite styled STATIC 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. The text does not move: for a single word that flashes/pulses/slides use create_kinetic_text, and for multi-line scrolling tickers/credits rolls/typewriter reveals use create_text_crawl.

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	Output resolution of the Text TOP: '720p' (1280×720), '1080p' (1920×1080), or '4K' (3840×2160). (default: 1080p)
parent_path	string	no	Parent COMP path the self-contained 'text_overlay' container is created inside. (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. Creates a new baseCOMP under parent_path holding the Beat CHOP and the engine DAT; it modifies the target COMP at comp_path (its custom controls or stored cues) live at runtime. 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. Returns a summary plus a JSON block with the container path, created node paths, the target, mode, beats, amount, engine path, any node errors, and warnings (no preview image — the output is a CHOP engine, not a TOP).

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. Creates a new baseCOMP under parent_path. '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 (noise + ramp) are created. Output is a Null ready for post-processing or setup_output. Returns a summary plus a JSON block with the container path, created node paths, the source and output paths, exposed controls, any node errors, warnings, and an inline preview image.

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	When true (default), expose a live 'Crossfade' knob on the container (crossfade mode only). (default: true)
parent_path	string	no	Parent network where the mixer container is created (default '/project1'). (default: /project1)

create_video_player mutates

Build a movie/clip player inside a new 'video_player' container under parent_path: 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 TOP. Pass file paths, or none to get an empty player you point at a file in TD. Use create_video_synth instead when you want a procedurally generated (oscillator/CRT) image rather than playing a video file. Returns the created clip paths, the output Null path, and whether a playlist was built. 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	Parent COMP path the self-contained 'video_player' container is created inside. (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. Creates a new baseCOMP under parent_path holding all of these — 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. Use create_3d_audio_reactive instead when you want the geometry driven by sound, or create_pbr_scene for physically-based materials. Returns a summary plus a JSON block with the container path, created node paths, the geometry/camera/render/output paths, exposed controls, any node errors, warnings, and an inline preview image.

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	When true (default), expose live RotateY (spin) and Zoom (camera distance) knobs. (default: true)
parent_path	string	no	Parent network where the 3D-scene container is created (default '/project1'). (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	Parent COMP path the self-contained 'projection' container is created inside. (default: /project1)

projector_calibration_wizard mutates

Build a rehearsal-safe projector calibration network: generated grid/crosshair or selected source TOP, per-projector crop/corner-pin/level/output lanes, preview layout, notes, and brightness/gamma controls. Live projector alignment remains explicitly unverified until run on the physical outputs.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP path to build inside. (default: /project1)
name	string	no	Name for the generated calibration container. (default: projector_calibration)
source_path	string	no	Optional existing TOP to calibrate. Omit to generate a built-in grid/crosshair.
projectors	integer	no	Number of projector lanes to scaffold. (default: 1)
width	integer	no	Per-lane output width. (default: 1920)
height	integer	no	Per-lane output height. (default: 1080)
overlap	number	no	Normalized overlap reserved for soft-edge alignment notes. (default: 0.08)
include_corner_pin	boolean	no	Insert a Corner Pin TOP per projector lane for keystone alignment. (default: true)
expose_controls	boolean	no	Expose Brightness and Gamma controls on every projector lane. (default: true)

create_keyframe_animation mutates

Animate parameters along a keyframed curve synced to the timeline — structured motion beyond animate_parameter's LFO (use animate_parameter instead for continuous LFO oscillation). Give time/value keyframes and the targets; this creates a baseCOMP 'keyframe_anim' under parent_path containing an Execute DAT that interpolates the curve each frame (linear or smooth easing) and writes the value onto every target parameter, looping over the keyframe span (or holding the last value). Use it for choreographed moves (a build-up, a drop, a sweep). Returns a summary plus a JSON block with the container path, the Execute DAT (hook) path, the loop duration, the targets, and warnings (including any targets that did not resolve). Returns a friendly error if the keyframes do not span a positive duration.

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	Parent network where the keyframe-animation container (a baseCOMP) is created (default '/project1'). (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	(slime/fluid) Expose a live 'Decay' knob bound to the gain Level TOP. (default: true)
parent_path	string	no	Parent COMP path the self-contained simulation container is created inside. (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. Creates a new baseCOMP under parent_path, adds and wires every node the recipe declares, exposes its controls, then auto-layouts, verifies, and previews. Returns a summary plus a JSON block with the container path, all created node paths, the output path, the recipe id, exposed controls, any node errors, warnings, and an inline preview image. Returns a friendly error listing available ids if id is unknown.

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 new container under parent_path with a 'master' output Null (where your mix lands) and a 'tempo' beat clock for reactivity, but NO scenes or look. Use scaffold_genre instead when you want a genre-flavored start (tempo + a ready-made look + palette already wired in). Returns the container path plus the 'master' and 'tempo' node paths. 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	Parent COMP path the show container is created inside. (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	Parent COMP path the self-contained 'strobe' container is created inside. (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. Creates a new baseCOMP under parent_path holding the source, a single GLSL fold pass, and a Null output. 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. Returns a summary plus a JSON block with the container path, created node paths, the output path, exposed controls, any node errors, warnings, and an inline preview image.

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	When true (default), expose live Segments / Rotation / Zoom / Center X / Center Y knobs on the container. (default: true)
parent_path	string	no	Parent network where the kaleidoscope container is created (default '/project1'). (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. Creates a new baseCOMP under parent_path holding the source, a noise driver, a Displace TOP, a GLSL RGB-shift pass, and a Null output. 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. Returns a summary plus a JSON block with the container path, created node paths, the output path, exposed controls, any node errors, warnings, and an inline preview image. 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	When true (default), expose live Amount/Speed/RGBShift/BlockSize knobs on the system container. (default: true)
parent_path	string	no	Parent network where the glitch container is created (default '/project1'). (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. Use extract_audio_features when you want coarse level/bass/mid/treble bands instead of N fine bins, create_audio_reactive for a ready-made spectrum visual, and feed this Null into bind_audio_reactive to drive a COMP.

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	Parent COMP path the self-contained 'spectrum' container is created inside. (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	Parent COMP path the self-contained 'onsets' container is created inside. (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. Creates a new baseCOMP under parent_path holding the chain. 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. Returns a summary plus a JSON block with the container path, created node paths, the Level/HSV/output paths, exposed controls, any node errors, warnings, and an inline preview image. Use apply_post_processing instead to chain several distinct effects in series.

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	When true (default), expose live Brightness / Gamma / Contrast / Saturation / Hue knobs bound to the right node parameters. (default: true)
parent_path	string	no	Parent network where the color-grade container is created (default '/project1'). (default: /project1)

create_color_wheels mutates

Classic colour-grading wheels — three tinted Level TOPs run in series for shadows (lift, gamma-biased), midtones (gamma) and highlights (gain, brightness-biased), then a master Level TOP for global offset (blacklevel), then an HSV Adjust TOP for saturation. Each wheel is an [r,g,b] multiplier in 0..2 (1,1,1 = neutral). Builds a new baseCOMP under parent_path holding the chain; with source_path the upstream TOP is pulled in via a Select TOP, without one a Ramp TOP test gradient is graded so the chain previews standalone. Exposes per-channel LiftR/G/B, GammaR/G/B, GainR/G/B float knobs plus Offset and Saturation (live-bound to the underlying Level/HSV pars). Output is a Null TOP. Use create_color_grade for a simpler single-Level + HSV chain, or apply_post_processing to chain several distinct effects.

Parameter	Type	Required	Description
source_path	string	no	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 external source.
lift	object[]	no	Shadow tint (lift wheel) as [r,g,b] in 0..2. Multiplies R/G/B on a Level TOP whose gamma1 is biased high (~1.4) so the multiply lands in the darker tonal range. [1,1,1] = neutral. (default: 1,1,1)
gamma	object[]	no	Midtone tint (gamma wheel) as [r,g,b] in 0..2. Multiplies R/G/B on a mid-biased Level TOP. [1,1,1] = neutral. (default: 1,1,1)
gain	object[]	no	Highlight tint (gain wheel) as [r,g,b] in 0..2. Multiplies R/G/B on a Level TOP biased into highlights via brightness1. [1,1,1] = neutral. (default: 1,1,1)
offset	number	no	Global black-level offset (-1..1). Positive lifts the black point (faded/filmic look); negative crushes. Drives the master Level TOP's blacklevel. (default: 0)
saturation	number	no	Master saturation multiplier (1 = unchanged, 0 = greyscale). Drives the trailing HSV Adjust TOP's saturationmult. (default: 1)
expose_controls	boolean	no	When true (default), expose live per-channel float knobs LiftR/G/B, GammaR/G/B, GainR/G/B (0..2, 1 = neutral) plus Offset and Saturation. Three floats per wheel — instead of a single RGB swatch — because the shared control-panel builder cannot bind an rgb control to a parameter, so the swatch would be display-only. (default: true)
base_name	string	no	Optional base name for the container (defaults to 'color_wheels'). Final container path is <parent_path>/<base_name> with TD's auto-suffix.
parent_path	string	no	Parent network where the colour-wheels container is created (default '/project1'). (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	Parent COMP path the self-contained 'model' container is created inside. (default: /project1)

blender_scene_import mutates

Create a self-contained TouchDesigner render scaffold for a Blender scene or Blender-exported asset: File In SOP (or fallback primitive), Geometry COMP, PBR material, environment/key lights, Camera, Render TOP, and Null TOP output. Supports .blend/.fbx/.obj/.gltf/.glb/.usd/.usdz paths and warns when a .blend may need export from Blender first.

Parameter	Type	Required	Description
scene_path	string	no	Path to a Blender scene or exported model file (.blend/.fbx/.obj/.gltf/.glb/.usd/.usdz). Omit to create a renderable fallback primitive.
parent_path	string	no	Parent COMP path where the self-contained Blender import container is created. (default: /project1)
name	string	no	Name for the generated container under parent_path. (default: blender_scene)
import_scale	number	no	Uniform scale applied to the imported scene geometry. (default: 1)
rotate_y	number	no	Initial Y rotation of the imported scene in degrees. (default: 0)
camera_distance	number	no	Camera distance from the scene along Z. (default: 6)
material_mode	pbr | clay	no	pbr keeps metallic/roughness controls; clay uses a neutral matte material. (default: pbr)
base_color	object[]	no	RGB material base color, normalized 0..1. (default: 0.78,0.8,0.84)
metallic	number	no	PBR metallic amount. Ignored for material_mode=clay. (default: 0.15)
roughness	number	no	PBR roughness amount. (default: 0.45)
expose_controls	boolean	no	Expose RotateY, CameraDistance, Scale, Metallic, and Roughness controls. (default: true)

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	Parent COMP path the self-contained 'shader_lib_<shader>' container is created inside. (default: /project1)

create_shader_park mutates

Compile Shader Park JavaScript sculpture code with shader-park-core and instantiate it as a self-contained TouchDesigner GLSL MAT scene with live controls. Use the companion shader-park:tox script when you specifically want the official Shader Park .tox plugin workflow.

Parameter	Type	Required	Description
code	string	no	Shader Park sculpture code. Example: let size = input(); sphere(size);. The code is compiled with shader-park-core and stored in a Text DAT for editing. _(default: `setMaxIterations(96);
rotateY(time * 0.25);
color(vec3(0.2, 0.8, 1.0));
sphere(0.45);`)_
name	string	no	Name of the created baseCOMP container. (default: shader_park_sculpture)
uniform_values	object	no	Initial values for Shader Park input() uniforms by name, e.g. { "size": 0.55 }. (default: [object Object])
speed	number	no	Animation speed multiplier for the Shader Park time uniform. (default: 1)
scale	number	no	Initial _scale uniform value. (default: 1)
opacity	number	no	Initial opacity uniform value. (default: 1)
step_size	number	no	Initial Shader Park raymarch stepSize uniform value. (default: 0.85)
camera_z	number	no	Camera distance from the sculpture. (default: 4)
resolution	object[]	no	Render TOP resolution [width, height]. (default: 1280,720)
expose_controls	boolean	no	Expose Speed / Scale / Opacity / StepSize / CameraZ plus any float Shader Park inputs. (default: true)
parent_path	string	no	Parent COMP path for the new sculpture. (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, output as a Null TOP inside a new 'video_synth_<mode>' container under parent_path. An oscillator/interference generator for VJ work — distinct from create_shader_lib's tunnel/raymarch/fractal/metaball looks. Use create_video_player instead when you want to play a real movie file rather than generate a pattern. Returns the chosen mode, its parameters, and a preview of the output TOP.

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	Parent COMP path the self-contained 'video_synth_<mode>' container is created inside. (default: /project1)

create_detection_reactive mutates

Turn object/person detection into TouchDesigner control channels — with NO CUDA requirement. Two backends: 'websocket' subscribes to an external detector process that streams JSON detections over a WebSocket (runs on any machine/GPU, or none), and 'onnx' scaffolds a CPU Script CHOP that runs an .onnx model via onnxruntime inside TD. Either way the output is a Null CHOP carrying a stable contract — presence (0/1), count, and per-object normalized bboxes (obj1_x, obj1_y, obj1_w, obj1_h, obj1_score, …) — ready for bind_to_channel. (Detection idea inspired by TDYolo, MIT-licensed; no code copied.)

Parameter	Type	Required	Description
name	string	no	Base name for the container COMP. (default: detection)
parent_path	string	no	COMP to create the detection container in (default '/project1'). (default: /project1)
source	websocket | onnx	no	Detector backend. 'websocket' subscribes to an external detector process that streams JSON detections (no CUDA needed, runs anywhere). 'onnx' scaffolds a Script CHOP that runs an ONNX model via onnxruntime on the CPU inside TouchDesigner — you fill in the model path + inference. (default: websocket)
url	string	no	(websocket) URL of the external detector's WebSocket. It should send JSON objects like {"count": N, "objects": [{"x":..,"y":..,"w":..,"h":..,"score":..}]}. (default: ws://127.0.0.1:8765)
model_path	string | null	no	(onnx) Filesystem path to the .onnx model to load in the Script CHOP (CPU inference). (default: null)
input_top	string | null	no	(onnx) Absolute path of the TOP to read frames from for inference. Pulled via a Select TOP. (default: null)
max_objects	integer	no	Number of detected objects (bboxes) to expose as channels (obj1_x, obj1_y, …). (default: 4)
reconnect_seconds	number	no	(websocket) Auto-reconnect interval if the detector connection drops. (default: 2)

create_fixture_control mutates

Build a moving-head lighting rig with BOTH a DMX/Art-Net output chain AND a 3D visual previsualization. For each fixture: a Constant CHOP holds an 8-channel movingHead8 block (pan, tilt, dimmer, r, g, b, strobe, gobo, prefixed '<id>/…'), padded and merged into a dmxoutCHOP (interface, universe, netaddress, rate); and a Geometry COMP 'head' with a tube-cone beam whose pan→ry and tilt→rx rotation is expression-driven straight from that fixture's DMX pan/tilt channels (0-255 mapped across pan_range/tilt_range degrees), all rendered under one camera+light Render TOP. This adds the live 3D preview on top of what create_dmx_fixture_pipeline (DMX-out only) does. Bind individual channels later with bind_to_channel / animate_parameter on op('rig_out')['fix1/pan']; the previz updates automatically.

Parameter	Type	Required	Description
name	string	no	Base name for the container COMP. (default: fixture_rig)
parent_path	string	no	COMP to create the fixture rig container in (default '/project1'). (default: /project1)
host	string | null	no	Target IP for Art-Net / sACN (dmxoutCHOP netaddress). Null = leave default. (default: null)
universe	integer	no	DMX universe written to the dmxoutCHOP. (default: 1)
net	artnet | sacn	no	Network protocol — written to the dmxoutCHOP interface par. (default: artnet)
fps	number	no	DMX refresh rate (dmxoutCHOP rate). (default: 40)
pan_range	number	no	Physical pan sweep in degrees the fixture spans across DMX 0-255 (previz rotation). (default: 540)
tilt_range	number	no	Physical tilt sweep in degrees the fixture spans across DMX 0-255 (previz rotation). (default: 270)
beam_length	number	no	Length of the previz beam cone from the head (metres). (default: 8)
beam_angle	number	no	Half-angle of the previz beam cone (degrees) — narrow = spot, wide = wash. (default: 12)
fixtures	object[]	yes	Moving-head fixtures. Each becomes a DMX movingHead8 block + a 3D previz head+beam.

create_geo_visualization mutates

Turn GeoJSON (e.g. OpenStreetMap-derived) into a 3D city visualization. Reads Point / LineString / Polygon / Multi* features, projects lat/long via a Mercator projection normalized to a unit box, and builds a Script SOP that lays out point clouds for points and polylines for streets/building footprints — optionally extruded into 3D ribbon 'walls' using each feature's numeric 'height' property — all wrapped in a Geometry COMP under a camera+light Render TOP for instant preview. NOTE: OpenStreetMap map data is © OpenStreetMap contributors and licensed under the Open Database License (ODbL); you must attribute it when visualizing OSM-derived data.

Parameter	Type	Required	Description
name	string	no	Base name for the container COMP. (default: geo_viz)
parent_path	string	no	COMP to create the geo visualization container in (default '/project1'). (default: /project1)
geojson	object	yes	A GeoJSON FeatureCollection (or single Feature). Only geometry coordinates + an optional numeric 'height' property are read.
scale	number	no	World-units per projected unit. The projection is normalized to [-1,1] then scaled. (default: 100)
extrude	boolean	no	Extrude polygon/line features into 3D 'buildings' using each feature's 'height' property (default height when missing). (default: true)
default_height	number	no	Height (world units) for extruded features lacking a numeric 'height' property. (default: 0.1)

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). Creates a new baseCOMP under parent_path holding the source, Blur, Threshold, Level, optional Constant + Composite fill, and a Null output. 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. Use create_depth_displacement instead for true 3D relief geometry rather than a flat 2D mask. Returns a summary plus a JSON block with the container path, created node paths, the mask/output paths, exposed controls, any node errors, warnings, and an inline preview image.

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	When true (default), expose live Threshold / Smooth / Invert (+ FillColor) controls on the system container. (default: true)
parent_path	string	no	Parent network where the silhouette container is created (default '/project1'). (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. Creates a new baseCOMP under parent_path holding the Text TOP, the LFO, the per-mode Transform/Level nodes, an optional Composite, and a Null output. 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. 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. This is for a single animated word/line; for a static caption or title use create_text_overlay, and for multi-line scrolling tickers/credits rolls/typewriter reveals use create_text_crawl. Returns a summary plus a JSON block with the container path, created node paths, the text/lfo/output paths, exposed controls, any node errors, warnings, and an inline preview image.

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	When true (default), expose live Text / Size / Color / Rate controls bound to the right node parameters. (default: true)
parent_path	string	no	Parent network where the kinetic-text container is created (default '/project1'). (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	Parent COMP path the self-contained 'waveform' container is created inside. (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	Parent COMP path the self-contained 'pitch' container is created inside. (default: /project1)

create_3d_audio_reactive mutates

Build a 3D scene that reacts to sound — the 3D counterpart of create_audio_reactive (use that for a 2D spectrum visual instead). Creates a new baseCOMP under parent_path. 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. Returns a summary plus a JSON block with the container path, created node paths, the spectrum/geometry/camera/render/output paths, exposed controls, any node errors, warnings, and an inline preview image.

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	Path to an audio file to play; used only when source='file'.
existing_chop_path	string	no	Path of an existing audio CHOP to analyze; used only when 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	When true (default), expose live Sensitivity (audio gain), Zoom (camera distance), and Spin knobs. (default: true)
parent_path	string	no	Parent network where the scene container is created (default '/project1'). (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. Creates a new baseCOMP under parent_path holding the Select TOP, GLSL remap, and Null output. With expose_controls a Rotation knob spins the dome horizon. Note: this GLSL-remaps an existing flat source — use create_cubemap_dome instead for a true cube-map render (higher fidelity, no equirect pole-pinch/seam). Returns a summary plus a JSON block with the container path, created node paths, the output path, exposed controls, any node errors, warnings (including the cubemap-follow-up note), and an inline preview image.

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	When true (default), expose a Rotation knob bound to the shader uniform that spins the dome horizon (degrees). (default: true)
parent_path	string	no	Parent network where the dome-output container is created (default '/project1'). (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. Creates a new baseCOMP under parent_path holding all of these; output is a Null ready for setup_output; exposes a Zoom knob. Returns a summary plus a JSON block with the container path, created node paths, the output path, exposed controls, any node errors, warnings, and an inline preview image.

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	When true (default), expose a live Zoom (camera distance) knob. (default: true)
parent_path	string	no	Parent network where the mesh-warp container is created (default '/project1'). (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. Creates a new baseCOMP under parent_path holding the source, height map, Geometry COMP + GLSL displacement MAT, Camera, Light, Render TOP, and a Null output. Exposes Depth and Zoom knobs — bind Depth to a tempo ramp or an audio feature to make the surface heave. Returns a summary plus a JSON block with the container path, created node paths, the output path, exposed controls, any node errors, warnings, and an inline preview image.

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	Path to a movie file to play as the source; used only when source='file'.
existing_top_path	string	no	Path of an existing TOP to sample as the height map; used only when 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	When true (default), expose live Depth (displacement amount) and Zoom (camera distance) knobs. (default: true)
parent_path	string	no	Parent network where the displacement container is created (default '/project1'). (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. Creates a new baseCOMP under parent_path holding the velocity/position feedback loops, the instanced Geometry COMP, Camera, Light, and Render TOP ending in a Null output. Reaches counts (side², up to 512²≈262k) well beyond the CPU create_particle_system (use that for a simpler, lower-count CPU emitter). This is the general-purpose GPU drift field (noise/curl/gravity); pick a sibling instead for other motion: create_particle_flock for boids separation/alignment/cohesion, image_to_particles when particles should spring to the pixels of an image/video, create_pop_particle_system for TouchDesigner's native POP particle network. 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). Returns a summary plus a JSON block with the container path, created node paths, the particle count, the output path, exposed controls, any node errors, warnings, and an inline preview image.

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	When true (default), expose live PointSize and Zoom (camera distance) knobs on the system container. (default: true)
parent_path	string	no	Parent network where the particle-field container is created (default '/project1'). (default: /project1)

create_raymarch_scene mutates

Instantiate a self-contained GLSL TOP raymarcher (volumetric / signed-distance-field) — the 3D complement to create_shader_lib. Scenes: sphere_field (repeated spheres), menger (Menger-sponge fractal), tunnel (twisting tunnel). Exposes live CameraZ / Speed / StepCount / Intensity / ColorA / ColorB controls and previews the output TOP.

Parameter	Type	Required	Description
scene	sphere_field | menger | tunnel	no	Which SDF scene to ray-march: sphere_field, menger (sponge fractal), or tunnel. (default: sphere_field)
camera_z	number	no	Camera distance back from the origin (uCameraZ). Exposed as a live 'CameraZ' control. (default: 4)
speed	number	no	Animation speed multiplier (drives uTime). Exposed as a live 'Speed' control. (default: 1)
step_count	integer	no	Raymarch iterations (uSteps); higher = more detail/cost. Exposed as 'StepCount'. (default: 64)
intensity	number	no	Output brightness multiplier (uIntensity). Exposed as a live 'Intensity' control. (default: 1)
color_a	string	no	Near/primary colour as hex (e.g. '#33ccff'); parsed to 0..1 RGB, exposed as 'ColorA'.
color_b	string	no	Far/secondary colour as hex (e.g. '#ff2266'); parsed to 0..1 RGB, exposed as 'ColorB'.
resolution	object[]	no	Output resolution [width, height] of the GLSL TOP. (default: 1280,720)
expose_controls	boolean	no	Expose live CameraZ / Speed / StepCount / Intensity / ColorA / ColorB controls. (default: true)
parent_path	string	no	Parent COMP path the self-contained 'raymarch_scene_<scene>' container is created inside. (default: /project1)

create_raytk_scene mutates

Build the minimal renderable RayTK node graph (sphereSdf → raymarchRender3D → Null TOP) from RayTK's real ROP COMP masters, copied at runtime — the node-graph-native complement to create_raymarch_scene (which stays the lightweight, no-dependency GLSL path). Optional flags union a second SDF, insert an inline basicMat, and add an explicit lookAtCamera / pointLight. Requires the RayTK toolkit staged + loaded (manage_packages install raytk, then load the .tox); RayTK 0.46 requires TouchDesigner 2025.30770+. Fails forward with 'stage & load RayTK first' guidance when the library is absent.

Parameter	Type	Required	Description
sdf_primitive	sphereSdf | boxSdf | boxFrameSdf | torusSdf	no	Primary RayTK SDF primitive ROP to raymarch. One of sphereSdf, boxSdf, boxFrameSdf, torusSdf. These are RayTK 'sdf'-category COMP masters copied from the loaded library — not native TouchDesigner operators. (default: sphereSdf)
union_with	sphereSdf | boxSdf | boxFrameSdf | torusSdf	no	Optional second SDF primitive to combine with sdf_primitive via a RayTK simpleUnion (combine category). Omit for a single primitive. Example: sdf_primitive=sphereSdf + union_with=boxSdf yields a merged blob.
material	boolean	no	Insert a RayTK basicMat (material category) inline between the SDF/union chain and the renderer, so the surface gets a base color/shading instead of the renderer default. (default: false)
add_camera	boolean	no	Add a RayTK lookAtCamera (camera category) wired into the renderer's Camera input (connector index 1, 0-based). Default false uses the renderer's built-in camera — leave false for the minimal scene. (default: false)
add_light	boolean	no	Add a RayTK pointLight (light category) wired into the renderer's Light input (connector index 2, 0-based). Default false uses the renderer's built-in light — leave false for the minimal scene. (default: false)
name	string	no	Name of the container COMP created for the scene. Defaults to 'raytk_scene_<sdf_primitive>'.
parent_path	string	no	Parent COMP path the RayTK scene container is created inside. (default: /project1)

create_raytk_sdf_graph mutates

Build a RayTK SDF graph from copied RayTK ROP masters: primary SDF, optional secondary SDF through simpleUnion, optional basicMat, lookAtCamera, pointLight, raymarchRender3D, and a native Null TOP output. Requires RayTK to be staged with manage_packages install raytk and loaded from the staged .tox.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP path where the RayTK SDF graph container is created. (default: /project1)
name	string	no	Name of the container COMP created for the graph. (default: raytk_sdf_graph)
primary	sphereSdf | boxSdf | boxFrameSdf | torusSdf	no	Primary RayTK SDF primitive ROP copied from the loaded RayTK library. (default: sphereSdf)
secondary	sphereSdf | boxSdf | boxFrameSdf | torusSdf	no	Optional second RayTK SDF primitive, combined with primary by simpleUnion.
operation	none | simpleUnion	no	Combination operation. A provided secondary upgrades none to simpleUnion. (default: none)
material	boolean	no	Insert a RayTK basicMat between the SDF chain and renderer. (default: true)
camera	boolean	no	Add a RayTK lookAtCamera wired to renderer input 1. (default: true)
light	boolean	no	Add a RayTK pointLight wired to renderer input 2. (default: true)
render_resolution	object[]	no	RayTK renderer resolution [width, height]. Defaults to 1280x720 to avoid TouchDesigner Non-Commercial render-size warnings. (default: 1280,720)
output_name	string	no	Name of the native Null TOP receiving the renderer output. (default: out1)

create_iphone_depth_source mutates

Create a deterministic TouchDesigner scaffold for iPhone depth senders such as TDLidar, Record3D, or a generic NDI/OSC source. Builds live/video receiver TOPs, color_out, depth_preview, OSC sensor input, sensors_out, setup hints, and an optional point-cloud placeholder. This is a scaffold and returns warnings where sender-specific metric depth decoding must be validated live.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP to create the scaffold in. (default: /project1)
name	string	no	Name for the generated base COMP. (default: iphone_depth_source)
source	tdlidar | record3d | generic_ndi_osc	no	iPhone depth sender profile to document in setup hints. (default: tdlidar)
video_mode	ndi | syphon_spout | movie_file	no	Transport for the color/depth video stream. (default: ndi)
video_source_name	string	no	NDI source name or Syphon/Spout sender name when using a live video transport.
movie_file	string	no	Movie file path used when video_mode is movie_file.
osc_port	integer	no	UDP port for OSC sensor data from the iPhone app. (default: 9002)
sensor_prefix	string	no	OSC address prefix used to select phone sensor channels. (default: /iphone)
create_pointcloud_stub	boolean	no	Create a textDAT placeholder for app-specific point-cloud reconstruction notes. (default: true)
active	boolean	no	Start the live/video receiver immediately where the operator supports it. (default: false)

create_sam2_segmentation_bridge mutates

Build a TouchDesigner bridge surface for an external SAM2/FastSAM segmentation service. Creates source input, mask receiver, mask_out, matte_out, preview_out, and clear notes that no model is bundled.

Parameter	Type	Required	Description
parent_path	string	no	COMP that will receive the SAM2/FastSAM bridge container. (default: /project1)
name	string	no	Container name for the bridge under parent_path. (default: sam2_segmentation_bridge)
input_top_path	string	no	Optional source TOP path. When provided it is pulled into the container via a Select TOP.
bridge_mode	comfyui | websocket | ndi_mask | syphon_spout_mask | file_watch	no	External mask transport used by the SAM2/FastSAM service. (default: comfyui)
server_url	string	no	External SAM2/FastSAM service URL or WebSocket endpoint. (default: http://127.0.0.1:8188)
mask_source_name	string	no	NDI/Syphon/Spout sender name that publishes the segmentation mask.
watch_folder	string	no	Folder used by file_watch mode for externally rendered mask images.
prompt_mode	auto | point | box | text	no	Prompt style expected by the external SAM2/FastSAM service. (default: auto)
active	boolean	no	Start request/polling endpoints active. Default is off for artist validation. (default: false)

create_yolo_onnx_tracker mutates

Build a deterministic TouchDesigner scaffold for YOLO-style object tracking. Creates source input, backend receiver placeholder, detections DAT, stable tracks_out CHOP channels, annotated_out TOP, and setup notes. Live detection requires an external detector or validated TouchDesigner Python ONNX runtime.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP that will receive the YOLO/ONNX tracker container. (default: /project1)
name	string	no	Container name for the tracker scaffold under parent_path. (default: yolo_onnx_tracker)
input_top_path	string	no	Optional source TOP path pulled into the container through a Select TOP.
backend	external_websocket | onnx_script | ndi_detections | file_watch	no	Detection transport or runtime scaffold to build. (default: external_websocket)
server_url	string	no	External WebSocket detector URL used by external_websocket mode. (default: ws://127.0.0.1:8766)
model_path	string	no	ONNX model path documented by onnx_script mode.
class_filter	string[]	no	Optional class names the external detector or ONNX postprocess should keep. (default: ``)
max_objects	integer	no	Maximum tracked object slots exposed as stable CHOP channels. (default: 16)
confidence_threshold	number	no	Minimum detection confidence expected from the detector or postprocess. (default: 0.35)
active	boolean	no	Start live receiver operators active. Default is off until validation. (default: false)

create_nuitrack_body_bus mutates

Create a TouchDesigner scaffold for Nuitrack skeleton data over OSC, WebSocket, TCP JSON, or sample mode. Produces a stable body_bus CHOP contract and setup notes; live SDK/device calibration must be validated separately.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP where the Nuitrack body-bus container is created. (default: /project1)
name	string	no	Name of the generated baseCOMP. (default: nuitrack_body_bus)
source	osc | websocket | tcp_json | sample	no	Transport for Nuitrack skeleton data. (default: osc)
listen_port	integer	no	Local port for OSC/TCP skeleton input. (default: 7007)
server_url	string	no	WebSocket URL when source is websocket. (default: ws://127.0.0.1:8767)
joint_set	upper_body | full_body | hands	no	Joint subset to expose as normalized body channels. (default: full_body)
max_bodies	integer	no	Maximum tracked bodies exposed in the output CHOP contract. (default: 2)
channel_prefix	string	no	Prefix for output CHOP channels, e.g. body0_head_x. (default: body)
active	boolean	no	Start the transport active where supported. (default: false)

create_orbbec_depth_silhouette mutates

Create an Orbbec/Kinect-compatible depth silhouette scaffold with synthetic/file fallbacks, stable silhouette_out and depth_preview TOPs, and explicit hardware/SDK validation warnings.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the Orbbec silhouette. (default: /project1)
name	string	no	Generated baseCOMP name. (default: orbbec_depth_silhouette)
source	orbbec_top | kinect_azure_orbbec | file | synthetic	no	Depth source path. Synthetic is the offline-safe default. (default: synthetic)
source_top_path	string	no	Existing TOP path to select instead of creating a device/file source.
movie_file	string	no	Movie/depth file for source=file.
near_threshold	number	no	Near depth cutoff. (default: 0.2)
far_threshold	number	no	Far depth cutoff. (default: 0.8)
smooth	number	no	Blur size for mask smoothing. (default: 1.5)
invert	boolean	no	Invert the silhouette mask. (default: false)
active	boolean	no	Start device/file source active where supported. (default: false)

raytk_expr_graph_builder mutates

Build an editable RayTK ROP expression graph from a preset or explicit nodes/edges: copy RayTK masters live via pathsByOpType/category search, wire typed connectors, apply simple parameter values, lay out copied nodes deterministically, and expose the selected output through out1. Complements create_raytk_scene (minimal scene) and create_raytk_op (single ROP). Requires RayTK staged and loaded; offline tests validate payload/registration only, while live render/cook proof remains explicit.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP path to build inside. (default: /project1)
name	string	no	Name for the generated graph container. (default: raytk_expr_graph)
preset	sphere_union_box | torus_frame_union | material_study | custom	no	Starter graph to build when nodes are omitted. Use custom with explicit nodes/edges. (default: sphere_union_box)
nodes	object[]	no	Custom RayTK ROP graph nodes. Leave empty to use the selected preset. (default: ``)
edges	object[]	no	Custom graph edges. Preset edges are used when nodes are omitted. (default: ``)
output_node_id	string	no	Node id to expose through out1. Defaults to the renderer added or inferred by the tool.
add_renderer	boolean	no	Append raymarchRender3D when the graph has no output ROP. (default: true)
add_camera	boolean	no	Append lookAtCamera and wire it into renderer input 1 when a renderer exists. (default: true)
add_light	boolean	no	Append pointLight and wire it into renderer input 2 when a renderer exists. (default: true)
add_material	boolean	no	Append basicMat between the SDF/combine tail and renderer when absent. (default: true)
library_path	string	no	Optional explicit path to the loaded RayTK library COMP. Omit to probe pathsByOpType and known namespaces live.
capture_preview_image	boolean	no	Capture an inline preview from out1. RayTK shader compile may still be asynchronous. (default: true)

detect_tempo mutates

EXPERIMENTAL automatic tempo (BPM) detection WITHOUT manual tapping. Detects beat onsets in live audio (kick band → RMS energy → moving-baseline threshold, reusing detect_onsets' primitive), measures the time between beats, and reduces the recent inter-onset intervals to a stable tempo (median → BPM = 60/interval) exposed as a bpm channel on a Null CHOP — bind a parameter to op('…/detect_tempo/bpm')['bpm']. Complements sync_external_clock (which is tap-tempo) and detect_onsets (which flags hits but derives no tempo). With drive_tempo on, it writes the detected BPM to the global tempo (op('/').time.tempo) so every Beat CHOP — create_tempo_sync, create_autopilot — follows the music automatically. Source defaults to a synthetic gated tone (device capture can hang TD on a macOS permission modal); also accepts a file, an existing CHOP, or the live device. Caveats: time-dependent (reads 0 on a paused timeline), can lock to half/double time, and must be tuned live per source (Threshold + Smoothing knobs).

Parameter	Type	Required	Description
source	device | file | synthetic | existing	no	Audio source. Defaults to 'synthetic' (an internal gated tone at a known rate) because live device capture can hang TouchDesigner on a one-time macOS microphone-permission modal — same default rationale as extract_audio_features / detect_pitch. 'device' = live microphone/line in (creating it may pop that permission dialog — click Allow). 'file' = an audio file. 'existing' = reuse a CHOP you already have. (default: synthetic)
file	string	no	Audio file path (source='file').
audio_in	string	no	Path of an existing audio CHOP to analyze (source='existing').
sensitivity	number	no	Onset-detection sensitivity 0..1. Higher = lower threshold = more beats registered (and a faster, twitchier lock); lower = only strong transients count. It maps to the excess-over-baseline threshold the kick band must clear (band-RMS magnitudes are tiny, so the usable window is small — tune live per source). (default: 0.5)
min_bpm	number	no	Lower clamp on the reported tempo. Also rejects implausibly long gaps between beats (an interval longer than 60/min_bpm seconds is ignored, so a missed beat can't halve the tempo). (default: 60)
max_bpm	number	no	Upper clamp on the reported tempo. Also rejects too-short intervals (a double-trigger shorter than 60/max_bpm seconds is ignored, so a stray transient can't double the tempo). (default: 200)
drive_tempo	boolean	no	When true, the engine also writes the detected BPM to the project's global tempo (op('/').time.tempo), so every Beat CHOP downstream — create_tempo_sync, create_autopilot — follows the detected beat automatically (same write as sync_external_clock). (default: false)
expose_controls	boolean	no	Expose live 'Threshold' (onset sensitivity — lower fires on more beats) and 'Smoothing' (how many recent intervals the median locks over — higher = steadier, slower to react) knobs. (default: true)
name	string	no	Name for the generated system container. (default: detect_tempo)
parent_path	string	no	Parent COMP path the generated system container (see name) is created inside. (default: /project1)

create_pbr_scene mutates

Build a physically-based 3D scene: a Geometry COMP holding the chosen primitive (sphere/torus/box) shaded by a PBR MAT (base colour, metallic, roughness), lit by an Environment Light for image-based lighting (fed a Constant TOP of env_color so it works with no HDRI file) plus a key Light, framed by a Camera and rendered to a Null. Creates a new baseCOMP under parent_path holding the Environment Light + envmap Constant TOP, the PBR MAT, a Geometry COMP, a key Light, a Camera, a Render TOP, and a Null output. Use create_3d_scene instead for basic (non-PBR) shading or GPU instancing. Exposes Metallic, Roughness, BaseColor and Spin controls; set rotate to turn the object so its reflections move. Returns a summary plus a JSON block with the container path, created node paths, the material/lights/geometry/camera/render/output paths, exposed controls, any node errors, warnings, and an inline preview image.

Parameter	Type	Required	Description
shape	sphere | torus | box	no	Geometry to render with the PBR material. (default: sphere)
metallic	number	no	PBR metalness: 0 = dielectric (plastic/clay), 1 = metal. Bound to the Metallic knob. (default: 0.9)
roughness	number	no	PBR roughness: 0 = mirror-sharp reflections, 1 = fully diffuse/matte. Bound to the Roughness knob. (default: 0.3)
base_color	object[]	no	PBR base/albedo colour as [r,g,b] in 0..1 (light gray by default). Also seeds the BaseColor swatch. (default: 0.8,0.8,0.85)
env_color	object[]	no	Colour of the environment light used for image-based lighting, as [r,g,b] in 0..1 (soft white). With no HDRI this drives a Constant TOP fed into the Environment Light. (default: 0.9,0.95,1)
rotate	number	no	Continuous spin of the whole object around Y in degrees/sec (0 = still). Shows off the PBR reflections as the surface turns. (default: 0)
expose_controls	boolean	no	When true (default), expose live Metallic, Roughness, BaseColor and Spin controls. (default: true)
parent_path	string	no	Parent network where the PBR-scene container is created (default '/project1'). (default: /project1)

create_particle_flock mutates

Build a boids-style GPU particle flock: position and velocity are simulated entirely on the GPU in two RGBA32float feedback-TOP loops, where the velocity shader implements the three classic boids rules — separation, alignment, cohesion — by scanning a stencil of neighbouring texels in the agent texture (each texel is one agent), then renormalising toward a cruise speed. Positions drive TOP-instancing of a tiny dot once per agent. Creates a new baseCOMP under parent_path holding the velocity/position feedback loops, the instanced Geometry COMP, Camera, Light, and Render TOP ending in a Null output. The behavioural complement to create_gpu_particle_field (use that instead for curl-noise/gravity drift rather than flocking); also pick a sibling for other motion: image_to_particles to spring particles onto the pixels of an image/video, create_pop_particle_system for TouchDesigner's native POP particle network, create_particle_system for a simple CPU emitter. Exposes live Separation / Alignment / Cohesion / Speed knobs. Note: the flock only evolves while the TD timeline plays. Returns a summary plus a JSON block with the container path, created node paths, the agent count, the output path, exposed controls, any node errors, warnings, and an inline preview image.

Parameter	Type	Required	Description
count	integer	no	Edge of the square agent buffer; the flock is count×count agents (agents = count², e.g. 64 → 4096). Each agent is one texel of the RGBA32float position/velocity buffers. Capped at 256 (65 536 agents) because the per-agent neighbour scan cost grows with the texture. (default: 64)
separation	number	no	Boids separation weight: steer away from close neighbours (collision avoidance). (default: 1)
alignment	number	no	Boids alignment weight: steer toward the average heading of nearby neighbours. (default: 1)
cohesion	number	no	Boids cohesion weight: steer toward the centroid (average position) of neighbours. (default: 1)
speed	number	no	Cruise speed the velocity is renormalised toward each frame, so the school flies at a stable pace. (default: 1)
color	object[]	no	RGB colour (0..1) of the instanced dots — the colour of the school. (default: 0.4,0.8,1)
point_size	number	no	Radius of each instanced dot (the sphere SOP scale). (default: 0.02)
expose_controls	boolean	no	When true (default), expose live Separation / Alignment / Cohesion / Speed knobs on the system container. (default: true)
parent_path	string	no	Parent network where the flock container is created (default '/project1'). (default: /project1)

create_point_cloud mutates

Render a point cloud from a depth/luminance map (or a synthetic source): scatter a resolution×resolution grid of points and push each point's XYZ from the texture — X/Y from its grid position, Z from the map's brightness × depth_scale. Unlike create_depth_displacement (a continuous shaded mesh), this is a cloud of discrete dots. A GLSL TOP packs each point's position into one RGBA32float buffer, then a Geometry COMP TOP-instances a tiny sphere once per texel (reaching resolution², up to 512²≈262k points). Creates a new baseCOMP under parent_path holding the source, a monochrome heightmap, a GLSL position-pack buffer, the instanced Geometry COMP, Camera, Light, and Render TOP ending in a Null output. Source can be an animated synthetic pattern (testable without any device, the default), a movie file, the live camera (may prompt for macOS permission), or an existing TOP (e.g. a real depth map). Use create_depth_displacement instead for a continuous shaded mesh rather than discrete dots. Exposes DepthScale, PointSize, and Spin knobs — bind DepthScale to a tempo ramp or an audio feature to make the cloud heave. Returns a summary plus a JSON block with the container path, created node paths, the effective and requested source, the point count, the output path, exposed controls, any node errors, warnings, and an inline preview image.

Parameter	Type	Required	Description
source	synthetic | file | camera | existing	no	Texture whose brightness drives each point's depth (Z). 'synthetic' = an animated Noise pattern, so the cloud moves and the chain is testable without any device permission (the default). 'file' = a movie file. 'camera' = live webcam/capture device (creating it may pop a one-time macOS camera-permission dialog — click Allow). 'existing' = sample a TOP you already have (e.g. a real depth map). (default: synthetic)
file	string	no	Path to a movie file to play as the source; used only when source='file'.
existing	string	no	Path of an existing TOP to sample as the depth map; used only when source='existing' (falls back to synthetic noise with a warning if missing).
resolution	integer	no	Grid side: the cloud is resolution×resolution points (count = resolution², e.g. 128 → 16 384). One point per texel of the position buffer. Capped at 512 (262 144 points) to stay GPU-sane. (default: 128)
depth_scale	number	no	How far bright pixels push each point along +Z. 0 = a flat sheet; higher = a deeper relief. (default: 1)
point_size	number	no	Radius of each dot (the source sphere SOP scale). TOP-instancing applies translate only, so per-point size lives on the sphere, not on instance scale. (default: 0.02)
rotate	number	no	Whole-cloud spin around Y in degrees/sec (0 = still). (default: 0)
expose_controls	boolean	no	When true (default), expose live DepthScale, PointSize, and Spin knobs on the system container. (default: true)
parent_path	string	no	Parent network where the point-cloud container is created (default '/project1'). (default: /project1)

create_generative_audio mutates

SYNTHESIZE audio — generate sound rather than react to it. Builds an audio synthesis chain ending on a Null CHOP carrying the signal: 'oscillator' (a single tone, choose sine/triangle/sawtooth/square + frequency), 'fm' (two oscillators, one frequency-modulating the other for metallic/bell timbres), or 'noise' (a Noise CHOP shaped by a low-pass filter for textures). A Volume gain sets the level. Playback is opt-in: set to_device=true to route it to an Audio Device Out CHOP (default off, so the build stays silent and never prompts for audio hardware). Creates a new baseCOMP under parent_path holding the synth chain. The output Null feeds create_spectrum/create_waveform, bind_to_channel, or the speakers. Audio CHOPs are time-dependent — the signal is silent while the TD timeline is paused. Returns a summary plus a JSON block with the container path, created node paths, the audio Null path, the synth settings, the device-out path (if any), any node errors, and warnings (no preview image — the output is a CHOP, not a TOP).

Parameter	Type	Required	Description
synth	oscillator | fm | noise	no	Synthesis method. 'oscillator' = a single tone-generating Audio Oscillator CHOP. 'fm' = two oscillators where one modulates the other's frequency (classic FM, metallic/bell timbres). 'noise' = a Noise CHOP shaped by a low-pass Audio Filter (wind/hiss/percussive textures). (default: oscillator)
frequency	number	no	Carrier / oscillator base frequency in Hz (e.g. 220 = A3). (default: 220)
waveform	sine | triangle | sawtooth | square	no	Oscillator wave shape (ignored for the 'noise' synth). (default: sine)
fm_ratio	number	no	(fm) Modulator frequency as a multiple of the carrier (modulator = frequency × ratio). (default: 2)
fm_depth	number	no	(fm) Modulation depth — the peak frequency deviation in Hz applied to the carrier. (default: 100)
volume	number	no	Output level, 0..1 (a gain on the final signal). Start moderate to protect ears/speakers. (default: 0.5)
to_device	boolean	no	Play the synthesized audio out through an Audio Device Out CHOP. Default OFF (opt-in) so the build never opens audio hardware — keeping it silent-safe and avoiding the macOS audio-permission prompt. Turn on only when you actually want sound out the speakers. (default: false)
expose_controls	boolean	no	When true (default), expose live Frequency / Volume knobs (and FmRatio / FmDepth for the fm synth). (default: true)
parent_path	string	no	Parent network where the synth container is created (default '/project1'). (default: /project1)

create_cubemap_dome mutates

Render a true cube-map dome master — the higher-fidelity follow-up to create_dome_output (which only warps a flat equirectangular source). A 3D scene is rendered by a Render TOP in cube-map mode (rendermode 'cubemap', which outputs a real cube-map texture in one render — no separate Cube Map TOP), or an existing cube-map source is pulled in via a Select TOP; then a GLSL TOP samples that cube map by 3D direction (TD's built-in samplerCube sTDCubeInputs[0]) to produce a fisheye fulldome master or a full 360°×180° equirectangular image, ending on a Null ready for setup_output. Creates a new baseCOMP under parent_path (named by name) holding the cube-map source (or the test scene's Geometry/Camera/Light/Render TOP), GLSL remap, and Null output. Sampling a real cube map avoids the equirect pole-pinch/seam. With expose_controls, a live Fov knob sets fisheye coverage and a Rotation knob spins the dome horizon. Returns a summary plus a JSON block with the container path, created node paths, the cube-source/output paths, exposed controls, any node errors, warnings, and an inline preview image.

Parameter	Type	Required	Description
projection	fisheye | equirectangular	no	fisheye: sample the cube map into a centred dome disc (planetarium fulldome master). equirectangular: sweep the cube map into a full 360°×180° latlong image. (default: fisheye)
fov	number	no	Fisheye coverage in degrees (the angular diameter the disc spans). 180 = full hemisphere (standard fulldome); larger over-fills, smaller zooms in. Exposed as a live Fov knob; ignored for equirectangular. (default: 180)
source	string	no	Optional path to an existing TOP delivering a cube-map texture (e.g. a Render TOP in cube-map mode) to remap. When omitted, a simple test scene (sphere on a grid + camera + light) is rendered by a Render TOP in cube-map mode so the tool is self-contained.
resolution	1024 | 2048 | 4096	no	Square dome-master resolution (width = height). (default: 2048)
expose_controls	boolean	no	Expose a live Fov knob (and a Rotation knob that spins the dome horizon). (default: true)
name	string	no	Base name for the system container. (default: cubemap_dome)
parent_path	string	no	Parent network where the dome container is created (default '/project1'). (default: /project1)

scaffold_genre mutates

Create a genre-flavored starting network under parent_path — beyond scaffold_show's blank skeleton. Picks a tempo, look, and palette per genre: 'techno' (fast ~130 BPM clock + a hard strobe-y feedback look + dark palette), 'ambient' (slow ~70 BPM + a soft blurred-feedback look + warm palette), or 'installation' (no clock + a slow generative noise look + muted palette). Each builds a 'master' output Null and a genre look already wired into it, and (when a tempo applies) writes the project's global tempo (op('/').time.tempo). Use scaffold_show instead for an empty skeleton with no look or palette. Returns the container path, the master/tempo/look node paths, the BPM written, and the palette. Then add scenes, a layer mixer into master, cues, and a control surface.

Parameter	Type	Required	Description
genre	techno | ambient | installation	no	Genre preset selecting the tempo, look, and palette of the starting network. (default: techno)
bpm	number	no	Override the preset BPM (written to the global tempo). For 'installation' (no clock by default), supplying a bpm adds a beat clock at that tempo.
name	string	no	Name of the show container (default: '<genre>_show').
parent_path	string	no	Parent COMP path the show container is created inside. (default: /project1)

create_pose_tracking mutates

Set up full-body pose tracking — the foundation for body-reactive visuals (the camera/skeleton counterpart to extract_audio_features). Produces a canonical pose CHOP (33 MediaPipe landmarks as samples, channels tx/ty/tz/confidence) plus a 'keypoints' CHOP of ready-to-bind scalar channels (r_wrist_y, l_wrist_x, hips_x, hand_span, height, …). Source defaults to a self-contained SYNTHETIC animated pose so it builds and previews with no camera and no plugin; switch to 'mediapipe' (the free torinmb/mediapipe-touchdesigner plugin), 'osc', or an existing pose CHOP for the real performer. Smoothing and Mirror included. Feed the output into create_pose_skeleton or create_body_reactive.

Parameter	Type	Required	Description
source	synthetic | mediapipe | osc | existing_chop	no	Where the 33-landmark pose stream comes from. 'synthetic' (default) = a self-contained animated human pose that needs NO camera and NO plugin — use it to build and preview the look instantly. 'mediapipe' = the live CHOP from the free torinmb/mediapipe-touchdesigner plugin (point mediapipe_chop_path at its pose landmarks CHOP). 'osc' = landmarks arriving over OSC (osc_port). 'existing_chop' = a pose CHOP you already built (e.g. the output of create_pose_tracking). (default: synthetic)
mediapipe_chop_path	string	no	Path to the MediaPipe plugin's pose-landmarks CHOP (source='mediapipe'). The plugin emits 33 samples with tx/ty/tz channels.
osc_port	integer	no	UDP port the OSC In CHOP listens on (source='osc'). (default: 7000)
existing_chop_path	string	no	Path of an existing pose CHOP — 33 samples, tx/ty/tz channels (source='existing_chop').
smoothing	number	no	Temporal smoothing (0..0.95): each landmark is blended with its previous frame so jittery tracking glides instead of snapping. 0 = raw/instant; higher = smoother but laggier. Exposed as a live knob. (default: 0.08)
mirror	boolean	no	Flip the pose horizontally (negate tx) so a webcam feed reads like a mirror — the performer's right hand is on the right of the frame. Build-time; off by default. (default: false)
expose_controls	boolean	no	Expose a live 'Smoothing' knob (0 = raw). (default: true)
parent_path	string	no	Parent COMP path the self-contained 'pose_tracking' container is created inside. (default: /project1)

create_pose_skeleton mutates

Render a live stick-figure skeleton from full-body pose tracking — the classic MediaPipe body-tracking look: glowing lines connecting the 33 landmarks (shoulders, elbows, wrists, hips, knees, ankles) drawn by a Line MAT and rendered to a Null TOP you can composite or post-process. Source defaults to a SYNTHETIC animated pose so it builds and previews instantly with no camera and no plugin; switch to 'mediapipe' (the free torinmb plugin), 'osc', or an existing pose CHOP (e.g. from create_pose_tracking) for the real performer. Creates a new baseCOMP under parent_path holding the pose source, a Geometry COMP (a Script SOP that rebuilds points + bones each cook), a Line MAT, a Camera, a Render TOP, and a Null output. Use create_body_reactive instead for glowing dots/trails at the landmarks rather than a connected stick figure. Exposes LineColor / LineWidth / CamDistance. Returns a summary plus a JSON block with the container path, created node paths, the skeleton SOP and output paths, the bone count, exposed controls, any node errors, warnings, and an inline preview image.

Parameter	Type	Required	Description
source	synthetic | mediapipe | osc | existing_chop	no	Where the 33-landmark pose stream comes from. 'synthetic' (default) = a self-contained animated human pose that needs NO camera and NO plugin — use it to build and preview the look instantly. 'mediapipe' = the live CHOP from the free torinmb/mediapipe-touchdesigner plugin (point mediapipe_chop_path at its pose landmarks CHOP). 'osc' = landmarks arriving over OSC (osc_port). 'existing_chop' = a pose CHOP you already built (e.g. the output of create_pose_tracking). (default: synthetic)
mediapipe_chop_path	string	no	Path to the MediaPipe plugin's pose-landmarks CHOP (source='mediapipe'). The plugin emits 33 samples with tx/ty/tz channels.
osc_port	integer	no	UDP port the OSC In CHOP listens on (source='osc'). (default: 7000)
existing_chop_path	string	no	Path of an existing pose CHOP — 33 samples, tx/ty/tz channels (source='existing_chop').
line_color	string	no	Bone colour as hex ('#rrggbb'). Drives the Line MAT; default is bright cyan. (default: #33ffe6)
line_width	number	no	Bone thickness in pixels (Line MAT near width). Exposed as a live knob. (default: 3)
camera_distance	number	no	Camera distance on Z. Default frames a whole standing figure in 16:9; larger = further/smaller. Exposed as a live knob. (default: 4.6)
expose_controls	boolean	no	When true (default), expose live LineWidth / CamDistance knobs (+ a LineColor swatch). (default: true)
parent_path	string	no	Parent network where the pose-skeleton container is created (default '/project1'). (default: /project1)

create_body_bubbles mutates

Create a MediaPipe-ready interactive bubble installation over the live camera: a detected open palm emits soap-like bubbles, body and hand landmarks act as soft colliders that can bat or lift them, a visible body contour is rendered in the same output so the interaction reads clearly, bubbles stay inside the screen box, settle on the lower floor, and pop/fade after a configurable lifetime (default 30 seconds). By default it keeps the bubble count low and disables pose-wrist emission, so bubbles are created only by an open palm. Builds a self-contained Base COMP with a Script CHOP physics solver, Script SOP bubble outlines, Script SOP body contour, camera-background composite, Geometry/Render/Null TOP output, a frame cooker, and live controls for emission rate, gravity, drag, buoyancy, skeleton impulse, bubble repulsion, tracking smoothing, body radius, body contour, camera opacity, lifetime, and bounce. Provide hand_chop_path from setup_hand_tracking and body_chop_path from setup_body_tracking/create_pose_tracking for full interaction.

Parameter	Type	Required	Description
name	string	no	Name for the generated bubble-physics Base COMP. (default: body_bubbles)
parent_path	string	no	Parent COMP where the body-bubble system is created. (default: /project1)
hand_chop_path	string	no	Optional hand-tracking CHOP from setup_hand_tracking: 21 samples per hand with tx/ty/tz/confidence. Open palm emits bubbles.
body_chop_path	string	no	Optional body/pose CHOP from setup_body_tracking or create_pose_tracking: 33 samples with tx/ty/tz/confidence. Landmarks collide with bubbles.
camera_top_path	string	no	TOP to use as the visible camera background. The MediaPipe plugin exposes the live camera at /project1/MediaPipe/video. (default: /project1/MediaPipe/video)
show_camera_background	boolean	no	Composite the camera TOP behind the body contour and bubbles. (default: true)
hide_camera_tracking_overlays	boolean	no	When camera_top_path belongs to the MediaPipe plugin, turn off its built-in tracking overlays so only the clean camera appears behind this system. (default: true)
camera_opacity	number	no	Opacity for the camera background when show_camera_background is enabled. (default: 1)
bubble_count	integer	no	Maximum number of live/recyclable bubbles in the simulation. (default: 45)
lifetime_seconds	number	no	Seconds each bubble remains visible before popping and disappearing. (default: 30)
emit_on_open_palm	boolean	no	When true, emit only while an open palm is detected in hand_chop_path. (default: true)
fallback_to_pose_wrists	boolean	no	Optional fallback: when hand tracking has no landmarks, emit from pose wrist landmarks. Disabled by default so bubbles are created only by an open palm. (default: false)
show_body_contour	boolean	no	Render the tracked body as a visible contour in the same output as the bubbles, so collisions read as performer interaction. (default: true)
body_contour_width	number	no	Line width in pixels for the visible body contour overlay. (default: 4)
hand_emit_rate	number	no	Bubbles emitted per second while the palm is open. (default: 8)
palm_open_threshold	number	no	World-space average wrist-to-fingertip distance required to treat the hand as an open palm. (default: 0.08)
gravity	number	no	Downward acceleration in screen-space units per second squared. (default: 0.28)
body_radius	number	no	Collision radius around each tracked body/hand landmark, in screen-space units. (default: 0.11)
wall_bounce	number	no	Energy retained when bubbles hit the left/right/top screen bounds. (default: 0.68)
floor_bounce	number	no	Energy retained when bubbles hit the lower screen floor. (default: 0.12)
drag	number	no	Air drag applied to bubble velocity each second; higher settles faster. (default: 0.95)
buoyancy	number	no	Small upward force countering gravity; keep below gravity for weighted bubbles. (default: 0.04)
skeleton_impulse	number	no	How strongly moving body/hand landmarks transfer motion to bubbles. (default: 0.65)
bubble_repulsion	number	no	Soft collision force between bubbles so they do not collapse into one point. (default: 0.18)
tracking_smoothing	number	no	Temporal smoothing for body/hand colliders inside the bubble solver. (default: 0.55)
output_resolution	object[]	no	Render resolution [width, height] for the output TOP. (default: 1280,720)
expose_controls	boolean	no	Expose live EmitRate/Gravity/BodyRadius/Lifetime/Bounce controls on the container. (default: true)

create_body_reactive mutates

Build a body-reactive visual driven by full-body pose tracking: glowing marks that follow the 33 landmarks (head, hands, elbows, hips, knees, feet), rendered to a Null TOP. Creates a new baseCOMP under parent_path holding the pose source, a Geometry COMP (dots copied onto the landmark point cloud), a Camera, a Render TOP, and per-style post-processing. Styles: 'points' (crisp dots), 'glow' (bloomed dots), 'trails' (motion smears that follow the body). Source defaults to a SYNTHETIC animated pose so it builds and previews instantly with no camera and no plugin; switch to 'mediapipe' (the free torinmb plugin), 'osc', or an existing pose CHOP (e.g. from create_pose_tracking) for the real performer. The visual counterpart of create_audio_reactive, for the body instead of sound. Returns a summary plus a JSON block with the container path, created node paths, the output path, exposed controls, any node errors, warnings, and an inline preview image.

Parameter	Type	Required	Description
source	synthetic | mediapipe | osc | existing_chop	no	Where the 33-landmark pose stream comes from. 'synthetic' (default) = a self-contained animated human pose that needs NO camera and NO plugin — use it to build and preview the look instantly. 'mediapipe' = the live CHOP from the free torinmb/mediapipe-touchdesigner plugin (point mediapipe_chop_path at its pose landmarks CHOP). 'osc' = landmarks arriving over OSC (osc_port). 'existing_chop' = a pose CHOP you already built (e.g. the output of create_pose_tracking). (default: synthetic)
mediapipe_chop_path	string	no	Path to the MediaPipe plugin's pose-landmarks CHOP (source='mediapipe'). The plugin emits 33 samples with tx/ty/tz channels.
osc_port	integer	no	UDP port the OSC In CHOP listens on (source='osc'). (default: 7000)
existing_chop_path	string	no	Path of an existing pose CHOP — 33 samples, tx/ty/tz channels (source='existing_chop').
visual_style	glow | points | trails	no	Look of the body-reactive visual: 'points' = crisp dots at each landmark; 'glow' = dots with a bloom halo; 'trails' = dots that smear into motion trails as the body moves. (default: glow)
color	string	no	Dot colour as hex ('#rrggbb'). Drives the Constant MAT; default is hot magenta. (default: #ff40cc)
dot_size	number	no	Radius of each landmark dot (world units). Exposed as a live knob. (default: 0.03)
glow_amount	number	no	Bloom blur size for visual_style='glow' (Blur TOP size). Exposed as a live knob. (default: 16)
trail_decay	number	no	How much of the previous frame survives for visual_style='trails' (feedback opacity). Higher = longer trails. Exposed as a live knob. (default: 0.9)
expose_controls	boolean	no	When true (default), expose live DotSize (+ style-specific Glow/TrailDecay) knobs and a Color swatch. (default: true)
parent_path	string	no	Parent network where the body-reactive container is created (default '/project1'). (default: /project1)

create_hand_hologram mutates

Build a palm-anchored hologram visual driven by create_hand_gesture_bus. Defaults to a synthetic previewable holographic cube; open palm controls visibility, the float anchor keeps it above the palm, and opposite-hand pinch drives scale, glow, and optional futuristic synth/device audio.

Parameter	Type	Required	Description
source	synthetic | mediapipe | existing_chop	no	(default: synthetic)
parent_path	string	no	(default: /project1)
comp_name	string	no	(default: hand_hologram)
hand_chop_path	string	no
tox_path	string	no
preset	holo_cube | energy_orb | wireframe_hud | particle_core	no	(default: holo_cube)
color	string	no	(default: #54f4ff)
accent_color	string	no	(default: #b56cff)
size	number	no	(default: 1)
float_height	number	no	(default: 1.15)
transparency	number	no	(default: 0.46)
glow	number	no	(default: 22)
scanline_amount	number	no	(default: 0.35)
rotation_speed	number	no	(default: 0.42)
pinch_scale_amount	number	no	(default: 1.4)
audio_mode	none | synth | device_out	no	(default: none)
audio_device_hint	string	no	(default: UMC202HD)
input_top_path	string	no
resolution	object[]	no	(default: 1280,720)
expose_controls	boolean	no	(default: true)
capture_preview	boolean	no	(default: true)

setup_body_tracking mutates

One-shot body tracking from a webcam: loads the free mediapipe-touchdesigner ENGINE (install it first with tdmcp install mediapipe-touchdesigner) into your project, starts the timeline (the engine captures the webcam through an embedded browser that only runs while playing), reads its pose JSON DAT through an adapter that emits a 33-landmark pose CHOP, and builds a live skeleton so you only need to pick your webcam and enable Pose. If the engine isn't installed yet, it tells you how. Loading the engine will prompt for camera permission on macOS (click Allow).

Parameter	Type	Required	Description
tox_path	string	no	Path to the MediaPipe ENGINE .tox (MediaPipe.tox — the full tracker that captures the webcam, not the bare pose_tracking.tox processor). Defaults to the package staged by tdmcp install mediapipe-touchdesigner, falling back to the legacy ~/tdmcp-packages path.
parent_path	string	no	COMP to load the engine into. (default: /project1)
build_skeleton	boolean	no	Also build a pose-skeleton visual wired to the tracked body so you see it working. (default: true)

create_transition mutates

Build a parameterized A→B transition over a single 0–1 Progress knob — the executable core of VJ cutting. Creates a new baseCOMP under parent_path holding two sources (brought in via Select TOPs, or built-in contrasting test looks when omitted) and one of five transition styles: 'dissolve' (a Cross TOP crossfade), 'luma_wipe' (a Ramp-gradient-driven moving edge via GLSL), 'slide' (B pushes in from the right over A), 'zoom' (B scales in over A), or 'glitch_cut' (a hard A→B switch at 0.5 with a brief RGB-split tear). Progress 0 = full A, 1 = full B. Exposes live 'Progress' + 'Duration' knobs; drive Progress from manage_cue / bind_to_channel to run the transition on a beat or cue. Output is a Null ready for post-processing or setup_output. Returns a summary plus a JSON block with the container path, created node paths, the output path, exposed controls, any node errors, warnings, and an inline preview image.

Parameter	Type	Required	Description
name	string	no	Name for the transition system COMP. (default: transition)
parent_path	string	no	Where to build it. (default: /project1)
source_a	string	no	TOP path for the A (outgoing) look. Omitted → a built-in test source (Constant/ramp) so it previews standalone.
source_b	string	no	TOP path for the B (incoming) look. Omitted → a contrasting built-in test source.
style	dissolve | luma_wipe | slide | zoom | glitch_cut	no	Transition style: dissolve (crossfade), luma_wipe (gradient-driven edge), slide (B pushes A), zoom (B scales in), glitch_cut (RGB-shift hard cut). (default: dissolve)
progress	number	no	Initial transition position 0=full A, 1=full B (exposed as a live knob). (default: 0)
duration	number	no	Seconds for an auto Progress sweep when triggered (exposed as a knob; the knob can also be driven by manage_cue/bind_to_channel). (default: 2)
resolution	object[]	no	Output resolution [w,h]. (default: 1280,720)

create_live_source mutates

Build a self-contained source COMP that ingests an external feed — screen grab, NDI, Syphon/Spout, camera, or a video stream (RTSP/SRT/WebRTC) — normalizes it to a target resolution, and exposes a named Null TOP output ready for the mixer, decks, or post-fx chain. The default 'screen_grab' is zero-permission and safe to test anywhere. 'camera' (Video Device In) is opt-in: it can hang TouchDesigner on a macOS permission modal until the user clicks Allow. NDI, Syphon/Spout, and video_stream are platform- and license-gated (NDI requires the NDI Runtime; Syphon is macOS-only, Spout is Windows-only). Par names for the source/sender/URL are probed defensively so a name that differs between TD builds becomes a warning rather than a hard failure.

Parameter	Type	Required	Description
name	string	no	Name for the source system COMP. (default: live_source)
parent_path	string	no	Where to build it. (default: /project1)
kind	screen_grab | ndi | syphon_spout | camera | video_stream	no	Source kind. DEFAULT screen_grab — zero-permission, safe to test. 'camera' (Video Device In) can hang TD on a macOS permission modal, so it is opt-in. (default: screen_grab)
source_name	string	no	(ndi/syphon_spout) The sender/stream name to receive. (video_stream) the URL (RTSP/SRT/WebRTC). (camera) the device name. Omit for the first available / a sensible default.
resolution	object[]	no	Target resolution [w,h] (a Fit/Resolution stage normalizes the feed). (default: 1280,720)

create_layer_stack mutates

Build a VJ-style N-layer compositor: stack 2–8 source TOPs and composite them bottom-up, each layer with its own blend mode (over/add/multiply/screen/difference/lighten/darken) and opacity. Each layer is a Select TOP (or a built-in test source when omitted) → a Level TOP carrying opacity; layers above the base each get their own 2-input Composite TOP so blend modes are per-layer. Exposes a live control strip — per layer: Opacity (0–1), Blend (menu), Mute, Solo — and ends on a Null ready for post-processing or setup_output. Pass layers (bottom-first) for an explicit stack, or omit it to build count empty test layers. Returns a summary plus a JSON block with the container path, per-layer node paths, the output Null, exposed controls, node errors, warnings, and an inline preview image.

Parameter	Type	Required	Description
name	string	no	Name for the compositor COMP. (default: layer_stack)
parent_path	string	no	Where to build it. (default: /project1)
layers	object[]	no	Explicit layer stack (bottom-first). Omit to build count empty test layers.
count	integer	no	Number of layers when layers is omitted. (default: 4)
resolution	object[]	no	Output resolution [w,h]. (default: 1280,720)

create_media_bin mutates

Point at a folder on the TouchDesigner machine and build a clip BIN inside a new bin COMP: it scans the folder (filtered to the given extensions, capped at max_clips), creates one Movie File In TOP per file, feeds them through a Switch TOP, and ends on a Null TOP. Exposes Index (current clip), Next / Prev (pulse, wrapping), and Crossfade (seconds) controls — switching clips crossfades by ramping the Switch's fractional index (0s = hard cut). The folder is read inside TD (not the MCP server). If the folder is empty or missing you get an empty, pointable bin instead of an error. Use create_video_player for a hand-listed playlist; use create_media_bin to ingest a whole folder for clip-based VJing.

Parameter	Type	Required	Description
name	string	no	Name for the bin COMP. (default: media_bin)
parent_path	string	no	Where to build it. (default: /project1)
folder	string	yes	Folder on the TD machine to scan for clips/stills.
extensions	string[]	no	File extensions to include (lower-case, no dot). (default: mov,mp4,png,jpg,jpeg,tif,exr)
max_clips	integer	no	Cap how many files become Movie File In TOPs. (default: 16)
crossfade	number	no	Crossfade seconds when switching clips (0 = hard cut). (default: 0.5)
resolution	object[]	no	Output resolution [w,h]. (default: 1280,720)

create_keyer mutates

Composite a keyed performer, logo, or any source over a background visual — the green-screen / chroma-key / matte tool for installations and live camera work. Creates a self-contained baseCOMP under parent_path that holds the full chain: source (Select TOP or test card) → key stage → composite → Null TOP output. Three key_type modes: 'chroma' (Chroma Key TOP, keys on Hue/Sat/Val range — best for green/blue-screen), 'luma' (Level TOP threshold + Matte TOP — keys by brightness), 'rgb' (RGB Key TOP, keys on R/G/B channel ranges — best for a solid background colour). key_color sets the target colour to remove (chroma/rgb modes); tolerance widens the key range; softness feathers the edge. With a source the footage is pulled in via a Select TOP (so it can live in another container); without one, a constant green test card is used so the chain builds and previews standalone. With a background the composited result is placed over it; without one, a diagonal ramp is used. Tolerance/Softness/KeyColor controls are exposed on the container. Output is a Null TOP. Returns a summary with the container path, created node paths, exposed controls, any node errors, warnings, and an inline preview image.

Parameter	Type	Required	Description
name	string	no	Name for the keyer COMP. (default: keyer)
parent_path	string	no	Where to build it. (default: /project1)
source	string	no	TOP to pull the key FROM (e.g. a camera/live source). Omit → a built-in test source.
background	string	no	TOP to composite the keyed result OVER. Omit → a built-in test background.
key_type	chroma | luma | rgb	no	chroma: green/blue-screen (Chroma Key TOP, keys on Hue+Sat+Val range); luma: brightness key (Level TOP + Matte TOP, keys on luminance); rgb: key a specific RGB color (RGB Key TOP, keys on R/G/B channel ranges). (default: chroma)
key_color	string	no	(chroma/rgb) Hex color to key out. (default: #00ff00)
tolerance	number	no	Key tolerance/range. (default: 0.3)
softness	number	no	Edge softness/feather. (default: 0.1)
resolution	object[]	no	Output resolution [w,h]. (default: 1280,720)

create_datamosh mutates

Build a datamosh (broken-codec / time-echo / ghost-trail) visual effect network in one call. Three modes: 'feedback_echo' (classic datamosh — a Feedback TOP loop decays and re-composites each frame, creating ghost trails); 'frame_blend' (blends current and previous frames for a motion-blur smear); 'time_echo' (Time Machine TOP samples different time offsets per pixel for per-pixel delayed ghosting). All modes expose a Decay knob; set source to an existing TOP path or omit it for a built-in animated test source. Returns a container with a Null TOP output, exposed controls, and a live preview.

Parameter	Type	Required	Description
name	string	no	Name for the generated container COMP (default 'datamosh'). (default: datamosh)
parent_path	string	no	Parent COMP path where the datamosh container is created (default '/project1'). (default: /project1)
source	string	no	Path to an existing TOP to use as the mosh source. Omit to use a built-in animated Noise TOP so the loop cooks and previews even with the timeline paused.
mode	feedback_echo | frame_blend | time_echo	no	Which smear algorithm to build. 'feedback_echo': classic datamosh — the Feedback TOP layers the decayed previous frame over the new source, creating ghost trails. 'frame_blend': blends the current frame with a cached previous frame via a Level TOP opacity, creating a motion-blur smear. 'time_echo': delayed-frame ghosting via a Time Machine TOP driven by a displacement map (UNVERIFIED — falls back to feedback-delay if Time Machine is unavailable). (default: feedback_echo)
decay	number	no	How slowly the trail fades (0–1). Higher values = longer smear / more persistent ghost. Applied via levelTOP brightness1. Default 0.9. (default: 0.9)
displace	number	no	Pixel displacement of the fed-back frame each cycle (the 'mosh wobble'). Applied via displaceTOP displaceweight1 (falls back to displaceweight on older builds). 0 = no wobble. Default 0.0. (default: 0)
resolution	object[]	no	Output resolution [width, height] in pixels. Forced on the feedback loop to prevent flickering. Default [1280, 720]. (default: 1280,720)

create_displacement_warp mutates

Build a displacement-warp stage over a source — the 'heat-haze, liquid, audio-pushed pixels' tool for VJ sets. A Displace TOP warps the source image using a second image as a displacement map; the map is driven by one of three modulators: 'noise' (animated Perlin noise — smooth, continuous warp), 'second_top' (your own displacement map via a Select TOP), or 'audio' (audio FFT spectrum converted to a texture via CHOP-to-TOP, so the warp reacts to the music). Without a source the chain builds over a Ramp TOP test gradient and previews standalone. The Displace TOP's weight (displaceweight1) maps to the amount parameter; the Noise TOP translate speed maps to speed. Amount and Speed are exposed as live knobs. Output is a Null TOP. Returns a summary plus JSON with the container path, created node paths, controls, errors, warnings, and an inline preview image. Pairs with extract_audio_features for reactive warp and apply_post_processing to chain with other effects.

Parameter	Type	Required	Description
name	string	no	Name of the container COMP created under parent_path. (default: displacement_warp)
parent_path	string	no	Parent COMP path the self-contained displacement warp container is created inside. (default: /project1)
source	string	no	Absolute path of a TOP to warp (pulled in via a Select TOP so it can live anywhere in the network). Omit to use a built-in Ramp TOP test source so the chain builds and previews standalone.
modulator	noise | second_top | audio	no	What drives the displacement map. 'noise' (default): an animated Noise TOP whose translate and period are driven by time — produces smooth heat-haze / liquid warp. 'second_top': a Select TOP pointing at modulator_top (your own displacement map). 'audio': a CHOP-to-TOP conversion of audio FFT energy — pixels push in proportion to the audio spectrum. The audio modulator requires an audio device or audio file to be active in the project; without one it runs silently at zero energy. (default: noise)
modulator_top	string	no	(second_top mode only) Absolute path of a TOP to use as the displacement map. Required when modulator is 'second_top'; ignored otherwise.
amount	number	no	Displacement strength — maps to the Displace TOP's displaceweight1 parameter. 0 = no warp; 1 = full-range warp (can tear); 0.05–0.3 are typical VJ values. (default: 0.1)
speed	number	no	(noise mode) Animation speed of the noise modulator. Scales the time-driven translate on the Noise TOP — higher values produce faster, more turbulent warp. (default: 0.5)
resolution	object[]	no	Output resolution [width, height] in pixels. (default: 1280,720)

create_halftone mutates

Build a print/comic print-look effect: halftone dots, CMYK colour separation, ordered dithering, or posterized stepped colour — classic retro aesthetics in one GLSL pass. Creates a new baseCOMP under parent_path holding the source (or a self-contained noise source), a GLSL TOP with an inline shader implementing the chosen style, and a Null output. With source it stylises an existing TOP (pulled in via a Select TOP); without it uses a self-contained animated colour-noise source (no device permissions). Exposes Mix (blend original vs stylised), DotSize, and Angle knobs. Returns a summary plus a JSON block with the container path, created node paths, the output path, exposed controls, any node errors, warnings, and an inline preview image.

Parameter	Type	Required	Description
name	string	no	Base name for the created container. (default: halftone)
parent_path	string	no	Parent COMP path the halftone container is created inside. (default: /project1)
source	string	no	Absolute path of an existing TOP to stylise (e.g. '/project1/render1'). Pulled in via a Select TOP. If omitted, a self-contained animated colour-noise source is used (no device permissions).
style	dots | cmyk | dither | posterize	no	Print look to apply. dots: monochrome halftone dot grid; cmyk: 4-colour print separation with staggered screen angles; dither: 4×4 Bayer ordered dithering; posterize: stepped colour + luminance outline. (default: dots)
dot_size	number	no	Halftone cell size in pixels — sets the dot spacing for 'dots' and 'cmyk' styles. Larger = coarser, more visible dots. (default: 6)
angle	number	no	Screen angle in degrees for the dot grid ('dots'/'cmyk'). Classic print uses 15–45°. (default: 15)
mix	number	no	Blend between the original image (0) and the fully stylised output (1). Exposed as a knob for live tweaking. (default: 1)
resolution	object[]	no	Output resolution [width, height] in pixels. (default: 1280,720)

create_vector_lines mutates

Build a pulse-driven image-to-vector-lines system: capture a still frame from a synthetic, camera, file, or existing TOP source, prepare a monochrome mask, freeze it to a snapshot, trace it through a Trace SOP for editable vector geometry, generate a clean TOP line-art overlay, and composite it over the source. Phase 1 is intentionally not realtime: the artist presses the Vectorize pulse to update trace1/frozen_frame, keeping cook cost bounded. Source defaults to a static synthetic contour card so it previews without camera permissions or moving noise; camera is opt-in. Exposes Vectorize, Threshold, PreBlur, StepSize, Smooth/Fit/Border toggles, line color/width, opacity, overlay mode, and calibration knobs. Returns the container, source/prep/frozen/trace/vector/output paths, warnings for unverified Trace/snapshot details, and a preview.

Parameter	Type	Required	Description
name	string	no	Name for the vector-line system COMP. (default: vector_lines)
parent_path	string	no	Parent COMP where the system container is created. (default: /project1)
source	synthetic | camera | file | existing_top	no	Image source. 'synthetic' is the safe default; 'camera' is opt-in; 'file' reads movie_file_path; 'existing_top' pulls existing_top_path through a Select TOP. (default: synthetic)
existing_top_path	string	no	Existing TOP path used when source='existing_top'.
movie_file_path	string	no	Movie/image path used when source='file'.
camera_device	string	no	Optional camera device name for source='camera'.
mode	hybrid_foreground | foreground_mask | full_frame	no	Prep mode: foreground-oriented mask, mask-only, or full_frame edge/detail tracing. (default: hybrid_foreground)
analysis_resolution	object[]	no	Capture/trace resolution [width, height] that bounds vectorization cost. (default: 640,360)
threshold	number	no	Brightness/mask cutoff for the prep image and Trace SOP. (default: 0.45)
pre_blur	number	no	Blur amount before thresholding/tracing to remove camera noise. (default: 2)
invert	boolean	no	Invert the prepared mask before tracing. (default: false)
remove_borders	boolean	no	Remove dirty image borders in Trace SOP when supported. (default: true)
resample	boolean	no	Resample Trace SOP shapes to reduce excessive point density. (default: true)
step_size	number	no	Trace SOP resample step / simplification amount. (default: 4)
smooth_shapes	boolean	no	Smooth traced shapes to reduce sharp camera-noise corners. (default: true)
fit_curves	boolean	no	Fit Trace SOP output to Bezier curves; off by default until live-probed. (default: false)
line_color	string	no	Vector material color as '#rrggbb'. (default: #49dcb2)
line_width	number	no	Wireframe line width where supported by the material. (default: 2)
opacity	number	no	Opacity of the rendered vector overlay. (default: 0.9)
overlay_mode	over | add | screen | multiply	no	Composite TOP operand when show_source=true. (default: over)
show_source	boolean	no	Composite the source image under the vector layer when true. (default: true)
expose_controls	boolean	no	Expose the Vectorize pulse plus prep/look/calibration controls. (default: true)

create_feedback_tunnel mutates

Build a parameterized infinite-zoom/rotate feedback tunnel: a seed TOP is composited with its own fed-back, zoomed, rotated, and decayed frame each cook to produce a hypnotic inward-spiral tunnel. Four audio-bind-ready controls (Zoom, Rotate, HueShift, Decay) are exposed on the container for live performance. A built-in animated noise seed is used when no source TOP is given. The recipe-validated topology (noiseTOP → feedbackTOP + compositeTOP-maximum → transformTOP sx/sy → blurTOP → levelTOP brightness1/huerotate → nullTOP, loop closed by feedbackTOP.par.top) is created inside a new baseCOMP under parent_path. Returns a summary, the container + node paths, exposed controls, any node errors, and an inline preview image. This is the fixed zoom-and-rotate spiral preset; for a general feedback loop with a choice of seed type and an arbitrary ordered chain of effects (blur/displace/edge/…) use create_feedback_network instead.

Parameter	Type	Required	Description
name	string	no	(default: feedback_tunnel)
parent_path	string	no	Parent COMP path inside which the 'feedback_tunnel' container is created. (default: /project1)
source	string	no	Path to an existing TOP to use as the tunnel seed. Omit to generate a built-in animated noise seed.
zoom	number	no	Per-frame zoom factor applied to the fed-back frame (>1 = inward tunnel, e.g. 1.02). (default: 1.02)
rotate	number	no	Per-frame rotation in degrees added to the fed-back frame (positive = clockwise). (default: 2)
hue_shift	number	no	Per-frame hue rotation (0–1, wrapping). Applied via levelTOP huerotate. 0 = no shift. (default: 0)
decay	number	no	Trail persistence (0–1). Applied via levelTOP brightness1 each frame. Higher = longer-lived tunnel; default 0.95. (default: 0.95)
resolution	object[]	no	Output resolution [width, height] in pixels. Fixed resolution prevents feedback runaway. (default: 1280,720)

multipass_3d_depth mutates

Build a renderable 3D scene with depth cues that read on stage: a Geometry COMP holding the chosen primitive (sphere/box/torus/grid), a Camera, a Light, and a Render TOP beauty pass, output as a Null — like create_3d_scene but with an optional Screen-Space Ambient Occlusion (SSAO) pass for contact shadows, and an optional Depth TOP output. The SSAO TOP is wired directly after the Render TOP (it needs the depth buffer — no TOP between them) and combined with the color. When expose_depth is on, a Depth TOP resolves the same render into a depth map exposed as a second Null ('depth_out'); feed that path into create_depth_displacement or create_depth_silhouette with source='existing_top' for a synthetic depth-driven effect — no depth camera needed. Optionally GPU-instanced into a grid, with spin over time. Exposes Spin, Zoom, and (with SSAO) an Ssao toggle. Returns a summary plus a JSON block with the container path, created node paths, the render/output/depth paths, exposed controls, node errors, warnings, and an inline preview image.

Parameter	Type	Required	Description
name	string	no	Name of the self-contained container created under parent_path. (default: multipass_3d)
parent_path	string	no	Parent COMP path the multipass 3D container is created inside (default '/project1'). (default: /project1)
geometry	sphere | box | torus | grid	no	Primitive to render. (default: torus)
instances	integer	no	GPU-instanced copies scattered over a grid (1 = single). (default: 1)
ssao	boolean	no	Add a Screen-Space Ambient Occlusion pass for contact shadows/depth. (default: true)
expose_depth	boolean	no	Expose a Depth TOP output (feeds create_depth_displacement/silhouette synthetically). (default: true)
spin	number	no	Degrees/sec rotation. (default: 10)
resolution	object[]	no	Render resolution [width, height] in pixels. (default: 1280,720)

create_set_navigator mutates

Build a hands-light stage navigator (the QLab model) for stepping through an ordered scene/cue list: Next / Prev to move the pointer, Go to fire the current scene's cue on the target COMP, and an Index knob to jump directly. Optionally quantizes GO to the next beat. The navigator drives manage_cue recall on the target so cue morphs and beat-quantized changes all work. Use after building a control panel with manage_cue cues stored; then perform the show by hitting Next + Go instead of recalling by name.

Parameter	Type	Required	Description
name	string	no	Name of the navigator COMP to create. (default: set_navigator)
parent_path	string	no	Parent COMP path the navigator container is created inside. (default: /project1)
target	string	yes	The COMP whose cues this navigator steps through. Cues are recalled on it via manage_cue.
scenes	string[]	no	Ordered cue names to navigate. Omit or leave empty to read the target's existing cues. (default: ``)
go_on_beat	boolean	no	Quantize GO to the next beat (needs a tempo/beat source). (default: false)
resolution	object[]	no	Panel resolution [width, height] in pixels. (default: 1280,720)

create_pop_field mutates

Build a GPU point field using TouchDesigner's POP (Point OPerator) family — a generator POP (chosen by pattern: 'noise' scatters count points and displaces them with a Noise POP for a moving cloud, 'grid' a flat lattice, 'sphere' a shell), a Transform POP that spins the whole field over time, then a render path (POP to SOP → Geometry COMP → Render TOP) output as a Null TOP. Creates a new baseCOMP under parent_path holding all of these and exposes PointSize and Spin knobs. NOTE: POPs are flagged Experimental in this TD build and the POP render path is uncertain, so this tool is built fail-forward and probe-first — the POP chain and render wiring are best-effort (failures become warnings) while the output Null is always created, and the result's extra.unverified lists every POP op type and the render path attempted so you can live-validate. Returns a summary plus a JSON block with the container path, created node paths, generator/transform/render/output paths, exposed controls, node errors, warnings, the unverified probe record, and an inline preview image.

Parameter	Type	Required	Description
name	string	no	Name for the self-contained POP-field container created under parent_path. (default: pop_field)
parent_path	string	no	Parent COMP path the POP-field container is created inside (default '/project1'). (default: /project1)
count	integer	no	Approximate point count. Used directly for the 'noise' pattern; 'grid'/'sphere' approximate it via a rows×cols layout near this total. (default: 10000)
pattern	grid | noise | sphere	no	Point layout/source. 'noise' (default) = a Point Generator POP scatters count points which a Noise POP displaces into a moving cloud. 'grid' = a flat Grid POP lattice. 'sphere' = points on a Sphere POP shell. (default: noise)
point_size	number	no	Rendered point size (Render TOP point size), exposed as the live PointSize knob. (default: 2)
spin	number	no	Degrees/sec rotation of the whole field around Y (a Transform POP animates it over time), exposed as the live Spin knob. (default: 10)
resolution	object[]	no	Render resolution [width, height] of the Render TOP and the output Null TOP. (default: 1280,720)

create_pop_geometry mutates

Procedural Op Pattern (POP) geometry generator: build a SOP chain inside a Geometry COMP — primitive (box/sphere/tube/torus/grid/line/text) → Transform SOP (translate/rotate/scale) → optional Subdivide SOP → optional per-point Noise SOP displacement → Material SOP (Constant MAT) → Null SOP — then render through a Camera + Light + Render TOP to a Null TOP. Creates a new baseCOMP under parent_path. Exposes a RotateY control; NoiseAmount + NoisePeriod are exposed only when noise_amount > 0 (otherwise the Noise SOP is omitted and those knobs would be inert). Use build_sop_geometry for a fully declarative SOP chain without a render rig; use create_3d_scene for instanced primitives, create_pbr_scene for PBR shading.

Parameter	Type	Required	Description
primitive	box | sphere | tube | torus | grid | line | …	no	Base geometry primitive. Each maps to its stock SOP (boxSOP/sphereSOP/tubeSOP/torusSOP/gridSOP/lineSOP/textSOP). (default: box)
translate	object[]	no	Translation [tx,ty,tz] applied via a Transform SOP after the primitive. (default: 0,0,0)
rotate	object[]	no	Rotation [rx,ry,rz] in degrees applied via the same Transform SOP. (default: 0,0,0)
scale	object[]	no	Per-axis scale [sx,sy,sz] applied via the same Transform SOP. [1,1,1] = unchanged. (default: 1,1,1)
subdivisions	integer	no	Optional subdivision count. When > 0 a Subdivide SOP runs after the Transform SOP at this depth, then a per-point Noise SOP works on the denser mesh. (default: 0)
noise_amount	number	no	Displacement amount of the per-point Noise SOP (0 = bypassed; ~0.1..1 typical for organic warp). (default: 0)
noise_period	number	no	Spatial period of the displacement noise. Larger = wider/softer ripples; smaller = tighter detail. (default: 1)
text_string	string	no	When primitive is 'text', the string fed into the textSOP. Ignored for other primitives. (default: tdmcp)
expose_controls	boolean	no	When true (default), expose live knobs on the container: RotateY always, plus NoiseAmount + NoisePeriod only when noise_amount > 0 (otherwise the Noise SOP is omitted and exposing the knobs would be inert). (default: true)
base_name	string	no	Optional base name for the container (defaults to 'pop_geometry'). Final container path is <parent_path>/<base_name> with TD's auto-suffix.
parent_path	string	no	Parent network where the POP geometry container is created (default '/project1'). (default: /project1)

create_text_3d mutates

Build a self-contained 3D text scene: a Text SOP generates the glyph outlines, an Extrude SOP gives them depth (the depth parameter controls depthscale), and a Geometry COMP holds the pipeline with a Constant MAT for colour. A Camera, a Light, and a Render TOP complete the 3D render, output as a Null TOP. Optional continuous Y-axis spin (spin degrees/sec) is driven by a time expression on the Geometry COMP's ry parameter. Exposes Spin and Depth as live knobs. The classic signature look for title cards, lyric reveals, and 3D text drops — use create_kinetic_text instead for flat 2D animated text. Returns a summary plus a JSON block with the container path, created node paths, exposed controls, any node errors, warnings, and an inline preview image.

Parameter	Type	Required	Description
name	string	no	Base name for the self-contained container COMP (default 'text_3d'). (default: text_3d)
parent_path	string	no	Parent COMP path where the text-3D container is created (default '/project1'). (default: /project1)
text	string	no	The text to render in 3D. Use \n for multiple lines. (default: HELLO)
depth	number	no	Extrusion depth in geometry units (controls the Extrude SOP's depthscale). 0 = flat polygons, 0.2 = typical title-card look. (default: 0.2)
spin	number	no	Continuous Y-axis rotation in degrees per second (0 = static). Driven by an expression on the Geometry COMP's ry parameter. (default: 20)
color	string	no	Text material colour as a hex string ('#ffffff' = white). Sets the Constant MAT's colorr/g/b. (default: #ffffff)
resolution	object[]	no	Render TOP output resolution as [width, height] in pixels (default [1280, 720]). (default: 1280,720)

create_midi_note_reactive mutates

Build a MIDI note → per-note trigger/velocity chain that exposes bindable channels on a Null CHOP (note0…noteN-1). Unlike learn_control (which binds one CC), this creates a full note-event chain: midiinCHOP → eventCHOP (ADSR envelopes per note) → Null CHOP. Bind any parameter to op('…/notes_out')['note0'] and it pulses with each keypress. source='synthetic' (default) previews without hardware by generating a procedural note pattern — switch to source='device' when a MIDI keyboard is connected. The device path is HARDWARE-GATED (HELD FROM RELEASE until validated with real MIDI gear).

Parameter	Type	Required	Description
name	string	no	Name for the container COMP created inside parent_path. Must be a valid TD identifier. (default: midi_note_reactive)
parent_path	string	no	Parent COMP path the self-contained container is created inside. (default: /project1)
source	device | synthetic	no	device: a real MIDI In CHOP (hardware-gated; needs a MIDI keyboard/controller — HELD FROM RELEASE until validated with gear). synthetic: a Noise CHOP driving an Event CHOP so it previews without any hardware. Default is synthetic so the chain is immediately visible. (default: synthetic)
device_name	string	no	(device) MIDI device name to filter (e.g. 'Arturia MiniLab mkII'). When omitted the MIDI In CHOP listens on all devices.
notes	integer	no	How many note channels to expose (e.g. 12 = one octave, 128 = full keyboard). Each channel is named note0…noteN-1 on the output Null CHOP. (default: 12)

create_test_pattern mutates

Generate a projector calibration / alignment source — a standalone test-pattern network that every media server ships and tdmcp was missing. Builds a baseCOMP containing a GLSL TOP with a baked-in static pattern (grid, crosshair, SMPTE-ish color bars, horizontal ramp, or circle-grid), optional text/number overlay (for per-projector ID), and a Null TOP as the stable output handle. The shader is generated per pattern and baked into the payload — no custom uniforms or live bindings needed. Use the output as a routing source during projector alignment, LED mapping calibration, or camera registration. Pattern, resolution, divisions, overlay number/label, and colours are all configurable.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP path to build inside (e.g. '/project1'). The container is created here. (default: /project1)
name	string	no	Base name for the container COMP that wraps the pattern network. (default: test_pattern)
pattern	grid | crosshair | color_bars | ramp | circle_grid	no	Pattern type: grid = even line grid; crosshair = centred cross + corner marks; color_bars = vertical SMPTE-ish colour columns; ramp = smooth horizontal grey ramp; circle_grid = repeated concentric ring tiles. (default: grid)
width	integer	no	Output width in pixels (must be > 0; e.g. 1920, 2560, 3840). (default: 1920)
height	integer	no	Output height in pixels (must be > 0; e.g. 1080, 1440, 2160). (default: 1080)
divisions	integer	no	Number of grid cells across the frame for grid and circle_grid patterns (must be >= 1). Ignored by other patterns. (default: 16)
output_number	integer	no	Projector / output ID drawn as a large label in the lower-right corner (must be >= 0). 0 = no number. (default: 0)
label	string	no	Optional extra caption text overlaid bottom-right (e.g. 'LEFT', 'CAM 2'). Empty = none. (default: ``)
line_color	number[]	no	Pattern line colour as [R, G, B] in 0–1 range. Default is green [0, 1, 0]. (default: 0,1,0)
bg_color	number[]	no	Background colour as [R, G, B] in 0–1 range. Default is black [0, 0, 0]. (default: 0,0,0)

create_text_crawl mutates

Build a multi-line animated text crawl / ticker / credits roll / typewriter reveal inside a self-contained baseCOMP. Three modes: 'crawl_horizontal' = continuous left-scrolling ticker tape (news-ticker style); 'roll_vertical' = upward credits roll (use \n to separate lines); 'typewriter' = text is revealed character-by-character from left to right (EXPERIMENTAL — the substring expression on a textTOP text par is unverified across TD builds). A textTOP renders the content; a transformTOP animates position via an EXPRESSION parameter (crawl/roll modes) or the textTOP text par is set to a time-sliced substring expression (typewriter mode). The scroll wraps continuously (loop=true, default) so the text re-enters from the opposite edge. Outputs a nullTOP 'out' as a stable handle. Differs from create_kinetic_text (single-string flash/pulse/slide) and create_text_overlay (a static, non-moving caption/title); this tool handles multi-line copy, continuous scrolling, and character-reveal. Returns a JSON block with container path, output_top, text_top, transform_top, mode, line count, and any per-step warnings.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP where the text-crawl container is created (default '/project1'). (default: /project1)
name	string	no	Name for the baseCOMP container that holds the crawl network. (default: text_crawl)
text	string	yes	The text content to display. Use \n to separate multiple lines (e.g. for a ticker or credits roll). All lines are fed to a single Text TOP.
mode	crawl_horizontal | roll_vertical | typewriter	no	Animation style: 'crawl_horizontal' = text scrolls continuously left across the frame (ticker-tape); 'roll_vertical' = text rolls upward (credits roll); 'typewriter' = text is revealed one character at a time from left to right — EXPERIMENTAL (the substring expression on a textTOP par is UNVERIFIED across TD builds). (default: crawl_horizontal)
speed	number	no	Scroll speed as a fraction of the output resolution per second. 0.1 = the text travels one full screen-width per 10 s. Drives the Transform TOP position expression. (default: 0.1)
font_size	number	no	Font size in pixels (maps to the Text TOP's fontsizex parameter; fontsizey is set to the same value). (default: 48)
color	number[]	no	RGB text colour as three 0–1 floats, e.g. [1,1,1] = white. Sets fontcolorr/g/b on the Text TOP. (default: 1,1,1)
bg_alpha	number	no	Background alpha [0–1]. 0 = fully transparent background (text over black/transparent). The par name is probed: 'alphabg' is tried first, then 'bgalpha' — UNVERIFIED across TD builds. (default: 0)
width	integer	no	Output resolution width in pixels (sets resolutionw on the Text TOP). (default: 1920)
height	integer	no	Output resolution height in pixels (sets resolutionh on the Text TOP). (default: 1080)
loop	boolean	no	When true (default), the scroll position wraps so the text crawls/rolls continuously. When false, it plays once and stops at the end. (default: true)

create_blob_reactive mutates

Build a blob-position-tracking chain that drives parameters from the POSITIONS of multiple objects/hands in a camera (or a TOP) — the per-blob counterpart to create_motion_reactive's single aggregate motion value. Creates a container under parent_path with a Video Device In TOP (or a Select TOP pulling an existing TOP), a Monochrome + Threshold TOP to isolate bright blobs, a Blob Track operator assigning each blob a persistent slot, and a Script CHOP that normalizes the tracker's per-blob output into a deterministic 'blobs' Null CHOP with channels blob0_x, blob0_y, blob0_size, blob1_x, … Bind any parameter to op('…/blob_reactive/blobs')['blob0_x'] (or pass targets to bind by expression as value*scale+offset). Camera source may prompt for (and briefly hang on) a macOS camera-permission dialog. The Blob Track operator is a palette/CV op whose optype and channel naming vary by TD build — the chain is built fail-forward and warns (rather than failing) if it is unavailable, and the Script CHOP normalizes whatever channels the tracker emits. Returns a summary plus a JSON block with the container path, the blobs CHOP path, the tracked output TOP, the tracker type used, channel names, bound targets, and warnings.

Parameter	Type	Required	Description
parent_path	string	no	Parent network where the blob-reactive container is created (default '/project1'). (default: /project1)
name	string	no	Base name for the container COMP that holds the chain. (default: blob_reactive)
source	camera | top	no	Blob source. 'camera' = live webcam/capture device (the real-world default; creating it may pop a one-time macOS camera-permission dialog — click Allow, and note it can briefly hang TD at the modal). 'top' = analyze an existing TOP you name in source_top. (default: camera)
source_top	string	no	Path of an existing TOP to track blobs in; used only when source='top' (a Select TOP pulls it in so no cross-container wire is needed). (default: ``)
camera_index	integer	no	Which capture device to use when source='camera' (0 = the first/default camera). Maps to the Video Device In TOP's device index. (default: 0)
threshold	number	no	Luma threshold [0–1] for isolating blobs: pixels brighter than this are considered part of a blob. Lower catches dim/large blobs, higher only bright ones. Drives both the Threshold TOP mask and the blob tracker's own threshold. (default: 0.3)
max_blobs	integer	no	Maximum number of blobs to track simultaneously, each given a persistent slot/ID. (default: 5)
targets	object[]	no	Per-blob parameter bindings. Each entry binds one node parameter by expression to op('…/blobs')['blob<blob>_<axis>'] * scale + offset. Omit to just build the tracking chain and bind later. (default: ``)

compose_cue_list mutates

Turn a natural-language show description into a validated cue list (SetlistSchema, scenes[] variant). Uses the local LLM when configured, falls back to a deterministic grammar parser otherwise. Optionally chains into create_cue_sequencer.

Parameter	Type	Required	Description
description	string	yes	Natural-language show plan.
bpm	number	no	Show tempo. Defaults to 120 if neither bpm nor a parsed cue overrides.
bars	integer	no	Hint at total length in bars; LLM/grammar fits cues within.
style	techno | ambient | dnb | house | experimental | generic	no	Stylistic prior — biases default cue names + morph times. (default: generic)
title	string	no	Optional show/setlist title for the output title field.
apply	boolean	no	If true, also build a cue_sequencer rig from the produced setlist. (default: false)
containerName	string	no	When apply=true, passed through to create_cue_sequencer as name.
preferLlm	boolean	no	If false, skip the LLM and use the grammar parser directly. (default: true)

enhance_build mutates

Run score_build, ask the configured LLM for up to N allowlisted tool calls that would raise the weakest sub-scores, and optionally auto-apply them. autoApply mutates the project and is NOT idempotent (re-runs can stack effects). Allowlist: create_color_grade, apply_post_processing, create_feedback_network, create_feedback_tunnel, bind_to_channel, arrange_network. Returns before/after scores and a dispatch log.

Parameter	Type	Required	Description
scopePath	string	no	Network root to enhance. Forwarded to score_build. (default: /project1)
focusCriterion	palette | motion | complexity	no	When set, the planner targets only this axis. errors/perf are excluded (use summarize_td_errors / optimize_performance).
autoApply	boolean	no	When true, dispatches each proposed call against the allowlisted tools. Default is preview-only because dispatch mutates the TD project. (default: false)
maxProposals	integer	no	Cap on proposed (and applied) tool calls. Keeps blast radius small. (default: 3)
targetFps	number	no	Forwarded to score_build. (default: 60)
rescore	boolean	no	When autoApply=true, re-run score_build after dispatch and include after + delta. Ignored when autoApply=false. (default: true)

create_prob_sequencer mutates

Build a Markov-chain step sequencer. On each beat boundary the COMP transitions from the current state to a next state sampled from the per-state weighted-transition table. Outputs two CHOP channels: 'state' (current state index) and 'trigger' (pulse on state change). Generative sibling of create_euclidean_sequencer and create_beat_grid_sequencer — great for evolving, probabilistic rhythms and generative state machines. NOTE: beat-callback timing requires a live TD session with time.play=1.

Parameter	Type	Required	Description
name	string	no	Container COMP name. (default: prob_seq)
parent_path	string	no	Parent COMP path. (default: /project1)
bpm	number	no	Tempo written to Beat CHOP when no bpm_source is provided. (default: 120)
division	1/4 | 1/8 | 1/16	no	Beat subdivision (1/4→1, 1/8→2, 1/16→4 beats-per-measure). (default: 1/8)
states	object[]	yes	Markov states. Each state has a unique id, a weight (initial distribution), and a transitions map (keys = state ids, values ≥ 0).
startState	string	no	Initial state id. If omitted, sampled from state weights.
bpm_source	string	no	Path to an existing Beat CHOP / tempo source. Omit to build a new one.
seed	integer	no	If set, seeds Python random for reproducible runs.

create_two_way_surface mutates

Build a bidirectional OSC or MIDI control surface that drives TouchDesigner params from a controller AND echoes outgoing changes back to it (motor faders, RGB pads), with an oscillation guard so the device's own echo doesn't ping-pong. Each mapping pairs a device address with a TD parameter; a Script CHOP gates outbound sends by epsilon delta, rate limit, and a last_in cache. Exposes Bypass, Globaleps, Ratehz, Reseccache custom pars on the container.

Parameter	Type	Required	Description
name	string	no	Container name. (default: two_way_surface)
parent	string	no	Parent COMP path. (default: /)
protocol	osc | midi	no	Transport: 'osc' uses OSC In/Out CHOPs; 'midi' uses MIDI In/Out CHOPs. (default: osc)
host	string	no	OSC remote host (device IP) for outgoing messages. Ignored for MIDI. (default: 127.0.0.1)
port	integer	no	OSC remote port for outgoing messages. Ignored for MIDI. (default: 9000)
listenPort	integer	no	OSC local port for incoming messages. Ignored for MIDI. (default: 9001)
midiDevice	string	no	MIDI device name (required when protocol='midi').
mappings	object[]	yes	Per-control routing + guard config.
rateLimitHz	number	no	Outgoing send-rate cap (Hz). Outbound channels are throttled below this rate. (default: 60)

create_automation_lane mutates

Build a per-parameter automation lane that records a live parameter sweep into a circular buffer over N bars, then loops the recording back into the parameter on a bar-phase clock. Two modes: record (sample the target param every cook into a ring buffer) or loop (read the buffer back via Lookup CHOP bound to the target param). Re-calling with the same name and a different mode flips the state without rebuilding the network. Uses Beat CHOP → Select CHOP (rampbar) → Lookup CHOP playback, with COMP storage tracking mode/write_head/armed state. Returns a summary plus a JSON block with container path, mode, samples count, target, and any warnings.

Parameter	Type	Required	Description
name	string	yes	System container name, e.g. 'auto_lane_filter'
parent	string	no	Parent COMP path, defaults to '/'
targetParam	string	yes	OP path + param tuple, e.g. '/project1/filter1:cutoff'
bars	1 | 2 | 4 | 8	no	(default: 4)
bpm	number	no	(default: 120)
mode	record | loop	no	(default: record)

create_chroma_reactive mutates

[experimental] Builds a 12-channel pitch-class chroma vector (chroma_0..chroma_11) from an audio bus via FFT bin → pitch-class fold. Outputs a Null CHOP ready for bind_to_channel. Shares audioSource convention with create_transient_reactive / create_energy_reactive.

Parameter	Type	Required	Description
name	string	no	(default: chroma_reactive)
parent	string	no	(default: /)
audioSource	string	no	Optional path to an existing CHOP to use as audio input. If omitted, an internal Audio Device In CHOP is created (may prompt for macOS microphone permission).
fftSize	1024 | 2048 | 4096	no	FFT size for the Audio Spectrum CHOP. (default: 2048)
smoothing	number	no	Temporal smoothing on chroma vector (0 = raw, 1 = frozen). Maps to Filter CHOP width. (default: 0.7)

create_transient_reactive mutates

Layer-1 audio splitter: differences a fast and a slow envelope follower to expose two normalized 0..1 channels — 'transient' (percussive onsets) and 'sustain' (tonal floor) — on a Null CHOP at {comp}/out. Pair with bind_to_channel to drive visuals from percussion vs sustain independently. Custom-par page 'Tune' on the parent COMP exposes Sensitivity + per-envelope attack/release for live tweaking.

Parameter	Type	Required	Description
name	string	yes	Container COMP name (required).
parent	string	no	Parent path of the container COMP (must exist). (default: /)
audioSource	string	no	Optional CHOP path or shared audioBus Null CHOP path. When empty, an internal audioDeviceIn CHOP is used. (default: ``)
fastAttackMs	number	no	Fast envelope attack in ms — captures clicks/onsets. (default: 1)
fastReleaseMs	number	no	Fast envelope release in ms. (default: 20)
slowAttackMs	number	no	Slow envelope attack in ms — tonal floor. (default: 50)
slowReleaseMs	number	no	Slow envelope release in ms. (default: 200)
sensitivity	number	no	Gain applied to transient before clamp to 0..1. (default: 1)

create_energy_structure mutates

[experimental] Build a song-structure (build / drop / breakdown) edge detector COMP with adaptive thresholds. Listens to an existing audio CHOP (audioSource) or a freshly created Audio Device In, follows a long-window envelope, and runs a Script CHOP that maintains a rolling buffer (last windowSec seconds) to derive an adaptive mean (mu) and std (sigma). Emits a 5-channel Null CHOP out with: energy (smoothed RMS 0..1), state (0=breakdown, 1=build, 2=drop), and three 1-sample edge pulses build_edge / drop_edge / breakdown_edge. buildThreshold and dropThreshold are k-multipliers of sigma above mu (NOT absolute amplitudes), so the detector self-calibrates to the current mix loudness. Hysteresis (4 cooks above to step up, 30 below to fall back) stops chattering at thresholds. windowSec/Buildthreshold/Dropthreshold are exposed as custom params on the parent COMP so artists can tweak live. Default audio source builds an Audio Device In CHOP (may pop the macOS mic-permission dialog once — click Allow); pass audioSource to skip the device.

Parameter	Type	Required	Description
name	string	yes	Parent COMP name to create under parent.
parent	string	no	Parent path (default project root). (default: /)
audioSource	string	no	Optional existing CHOP path producing audio (e.g. an Audio Device In or Audio File In). If omitted, an Audio Device In is created inside the COMP as 'audioin'.
windowSec	number	no	Length of the rolling energy buffer (sec) used to compute adaptive mean/std. (default: 20)
buildThreshold	number	no	k_build: state becomes BUILD when energy > mu + k_build*sigma. (default: 0.7)
dropThreshold	number	no	k_drop: state becomes DROP when energy > mu + k_drop*sigma (must be > buildThreshold). (default: 0.85)

create_phone_gesture mutates

Stream a phone's IMU (tilt + gyro + shake) and multitouch into TouchDesigner as CHOP channels you can bind to anything. Builds a Web Server DAT page the phone opens (any browser, no app) and a Null CHOP exposing tilt_x/y/z, gyro_x/y/z, shake, touch0..3_x/y/active, clients. Composable with create_phone_remote on the same COMP (different port). SECURITY: listens on all interfaces with no auth — trusted networks only. iOS Safari needs HTTPS for motion permission; falls back to touch-only on plain HTTP.

Parameter	Type	Required	Description
name	string	no	Child operator base name inside parent. (default: phone_gesture)
parent	string	no	COMP that will host the Web Server DAT + Script CHOP. (default: /project1)
port	integer	no	TCP port for the gesture web server (distinct from bridge:9980 and phone_remote:9981). (default: 9982)
enableImu	boolean	no	Enable tilt_, gyro_, shake channels (iOS Safari requires HTTPS + permission tap). (default: true)
enableMultitouch	boolean	no	Enable touch0..3_x/y/active channels. (default: true)
shakeThreshold	number	no	Acceleration magnitude (m/s^2) above which shake fires. (default: 15)

moodboard_to_system mutates

Ingest 1..6 moodboard images and build a matching generative system in TouchDesigner. Uses the vision-capable local LLM when configured to extract palette + motion + generator pick (palette hint, generator from {audio_reactive, generative_art, particle_flock, feedback_tunnel, gpu_particle_field}, optional post-FX). Falls back to a deterministic style→generator grammar otherwise. Note: preview may read 0 on a paused timeline — press Play.

Parameter	Type	Required	Description
images	string[]	yes	Image paths (absolute or cwd-relative). Vault refs allowed when TDMCP_VAULT_PATH is set: e.g. 'Moodboards/foo.png'.
parent_path	string	no	COMP to build the generated subsystem in. (default: /project1)
style	auto | cinematic | minimal | glitch | organic | retro | …	no	Hint that biases generator + post-FX choice. (default: auto)
intensity	number	no	Drives evolution_speed / particle counts / feedback gain on the chosen generator. (default: 0.6)
includePostFx	boolean	no	Chain apply_post_processing with picked effects after the generator builds. (default: true)
generator	auto | audio_reactive | generative_art | particle_flock | feedback_tunnel | gpu_particle_field	no	Force a generator. 'auto' lets the LLM/grammar pick. (default: auto)
preferLlm	boolean	no	When false, skip the LLM entirely and use the deterministic grammar. (default: true)

audio_fingerprint_to_visual mutates

Sample a few seconds of audio inside TouchDesigner, compute a 4-feature fingerprint (tempo, spectral centroid, onset density, dynamic range), run a deterministic heuristic mapping to pick a matching Layer 1 generator (create_glitch / create_audio_reactive / create_kaleidoscope / create_feedback_tunnel / create_feedback_network / create_gpu_particle_field), and dispatch it with parameters tuned to the fingerprint. Default audio_source='synthetic' to avoid macOS mic-permission hangs. dry_run=true returns the chosen mapping without building. apply_top_op composites the result over an existing TOP.

Parameter	Type	Required	Description
audio_source	synthetic | file | device | existing_chop	no	Audio source for fingerprinting. Defaults to 'synthetic' (a gated tone at the global tempo) because 'device' can hang TD on a macOS mic-permission modal — same rationale as detect_tempo. (default: synthetic)
audio_file_path	string	no	Audio file path. Required when audio_source='file'.
existing_chop_path	string	no	Path of an existing audio CHOP. Required when audio_source='existing_chop'. Pulled in via Select CHOP (cross-container wires fail).
sample_sec	number	no	Sample window length in seconds the fingerprint is averaged over. (default: 4)
apply_top_op	string	no	Optional path of a TOP to composite the chosen generator's output over (via a compositeTOP('over') built in apply_top_op's parent).
parent_path	string	no	Parent COMP for the transient sampler and the dispatched generator. (default: /project1)
dry_run	boolean	no	When true: sample the audio, classify, and return the chosen mapping + params without instantiating the generator. (default: false)
force_family	auto | strobe_glitch | tunnel | kaleido | particle | ambient | …	no	Override the heuristic and force a family; params still tuned from the fingerprint. (default: auto)
expose_controls	boolean	no	Forwarded to the dispatched generator's expose_controls flag. (default: true)

create_engine_comp mutates

Drop a TouchDesigner Engine COMP that loads an external .tox in a separate TD subprocess — an independent crash domain with its own cook + (optionally) a second GPU thread, ideal for hosting heavy or unstable subgraphs. Sets the .tox file, optional reload pulse (re-pulls the .tox once), perform-mode override, and color-map toggle. The .tox's own outTOP/outCHOP/outSOP/outDAT operators surface as connectors on the Engine COMP for downstream wiring. Complements make_portable_tox (which produces the shippable .tox). Note: sub-process spin-up forks a TD process — the first cook can be multi-second on slow disks; that is not a hang. par.reload / par.usecolormap / par.performmode are guarded with hasattr so unverified par names degrade to warnings rather than throwing.

Parameter	Type	Required	Description
name	string	no	Node name for the new Engine COMP. (default: engine1)
parent_path	string	no	Parent COMP path the Engine COMP is created inside (default '/project1'). (default: /project1)
tox_path	string	yes	Path to the .tox file the sub-engine loads. Forward-slash recommended; absolute or project-relative.
reload	boolean	no	When true, pulse the Engine COMP's reload par so the .tox is re-pulled once at creation. (default: false)
use_color_map	boolean	no	Mirror the Engine COMP's color-map toggle (UNVERIFIED par name 'usecolormap' — guarded with hasattr). (default: false)
perform_mode	auto | on | off	no	'on' forces the sub-engine to cook in perform mode; 'off' forces it off; 'auto' leaves the par at its default. (UNVERIFIED par name 'performmode' — guarded with hasattr). (default: auto)

create_dmx_fixture_pipeline mutates

Build a DMX/Art-Net (or sACN) output chain from a fixture list. For each fixture (rgb, rgbw, par64, movingHead8, movingHead16) creates a Constant CHOP with one named, default-valued channel per DMX slot (prefixed '<id>/<channel>'), inserts pad Constant CHOPs to keep DMX-slot alignment, merges them all into one stream, and drives a dmxoutCHOP (interface, universe, netaddress, rate). Returns the container + a JSON report with paths, fixtures, total channels, exposed controls (Universe / Rate / Net Address), and warnings. Per-fixture sliders are NOT auto-exposed — bind individual channels later with bind_to_channel / animate_parameter on op('rig_out')['fix1/r'] etc.

Parameter	Type	Required	Description
name	string	no	Base name for the container COMP. (default: dmx_rig)
parent_path	string	no	COMP to create the DMX rig container in (default '/project1'). (default: /project1)
host	string | null	no	Target IP for Art-Net / sACN (maps to dmxoutCHOP netaddress). Null = leave default. (default: null)
universe	integer	no	DMX universe written to the dmxoutCHOP. (default: 1)
net	artnet | sacn	no	Network protocol — written to the dmxoutCHOP interface par. (default: artnet)
fps	number	no	DMX refresh rate (dmxoutCHOP rate). (default: 40)
fixtures	object[]	yes	Ordered list of fixtures (sorted by startChannel at build time).

create_growth_system mutates

Build an L-system / vine-growth generator: a Script SOP iterates a context-free rewriting grammar from axiom for generations steps, then walks the resulting string as a 3D turtle to draw a polyline tree. Recognised symbols: F (forward draw), f (forward no draw), + - (yaw ± branchAngle), & ^ (pitch), \ / (roll), [ ] (push/pop state). Other symbols are no-op constants (use X/A/B as grammar variables that expand but don't draw). Multiple rules sharing a from symbol trigger weighted-random stochastic selection (weight defaults to 1; seed controls the RNG). The polyline tree is thickened with a Tube SOP, recentred, and rendered. Complements create_particle_flock (boids) and create_gpu_particle_field (curl-noise) as the deterministic CPU-geometry idiom. Returns a summary plus a JSON block with the container path, output path, rules DAT path, exposed controls, errors, warnings, and an inline preview.

Parameter	Type	Required	Description
name	string	no	Container baseCOMP name. (default: growth_system)
parent	string	no	Parent network where the container is created. (default: /project1)
rules	object[]	no	Context-free rewriting rules. Multiple rules sharing the same from symbol trigger weighted-random stochastic choice (weight defaults to 1). (default: [object Object])
generations	integer	no	Rewrite iterations. Capped at 7 because string length grows ~k^n and freezes the SOP cook. (default: 4)
axiom	string	no	Initial string before rewriting. (default: F)
branchAngle	number	no	Turtle turn angle (degrees) for + / - / & / ^ / \ / / symbols. (default: 22.5)
step_length	number	no	World units per F stroke. (default: 0.15)
thickness	number	no	Tube SOP radius for the rendered branches. (default: 0.01)
color	object[]	no	Constant MAT colour (RGB, 0..1). (default: 0.5,0.9,0.4)
seed	integer	no	RNG seed for stochastic rule selection. (default: 1)
expose_controls	boolean	no	Expose Generations / BranchAngle / StepLength / Thickness on the container. (default: true)

import_shadertoy mutates

Build a GLSL TOP from a Shadertoy URL, ID, or pasted source. Wires iChannels (defaulting to noise placeholders), exposes Speed (and optional Mouse) controls, and captures a preview. First fetch on macOS may trigger an outgoing-connection permission prompt. Set TDMCP_SHADERTOY_KEY for reliable fetches; paste into raw_source to stay offline.

Parameter	Type	Required	Description
shader_id	string	no	Shadertoy 6-char ID, e.g. 'XsXXDn'.
url	string	no	Full Shadertoy URL: https://www.shadertoy.com/view/<id>.
raw_source	string	no	Pasted Shadertoy-style fragment (must contain mainImage). Offline-safe.
parent_path	string	no	(default: /project1)
name	string	no	(default: shadertoy)
resolution	object[]	no	(default: 1280,720)
pixel_format	rgba8 | rgba16 | rgba32	no	(default: rgba8)
channels	object[]	no	(default: ``)
expose_mouse_control	boolean	no	(default: false)
expose_speed_control	boolean	no	(default: true)
capture_preview	boolean	no	(default: true)
provenance_override	object	no

import_isf_shader mutates

Create a new TouchDesigner system container containing an ISF (.fs) shader as a GLSL TOP, companion DATs, and optional live controls. Accepts raw source, a local file path, or an http(s) URL; URL fetches are bounded by fetch_timeout_ms. Returns the container/GLSL/output paths, generated controls, provenance, warnings for inputs that need manual wiring, and an inline preview when capture_preview=true. Use create_glsl_shader for hand-written GLSL or import_shadertoy for Shadertoy sources.

Parameter	Type	Required	Description
source	string	yes	ISF (.fs) source: raw shader text, a local file path, or an http(s) URL.
source_kind	auto | raw | file | url	no	Override the source sniffer; 'raw' skips IO. (default: auto)
parent_path	string	no	Container parent COMP path. (default: /project1)
name	string	no	System container name (sanitized). Defaults to ISF DESCRIPTION or 'isf_shader'.
resolution	object[]	no	GLSL TOP output resolution [width, height]. (default: 1280,720)
pixel_format	rgba8 | rgba16 | rgba32	no	Pixel format for the generated GLSL TOP. (default: rgba8)
channel_overrides	object[]	no	Override default placeholder noise for ISF image/audio inputs. (default: ``)
control_defaults	object	no	Override the ISF DEFAULT for any input at build time. (default: [object Object])
expose_controls	boolean	no	Expose ISF inputs as live custom controls on the generated system container. (default: true)
capture_preview	boolean	no	Capture an inline preview after the shader is built; disable for faster headless runs. (default: true)
fetch_timeout_ms	integer	no	Timeout in milliseconds for URL sources; local files and raw source do not need network access. (default: 8000)

create_fluid_sim mutates

Build a real-time 2D fluid/ink/dye simulation (stable-fluids style: semi-Lagrangian advection + Jacobi pressure solve + gradient-subtract projection + dye advection) as a stack of GLSL TOPs in feedback loops inside a new baseCOMP under parent_path. Exposes artist-facing controls (dye color, injection radius/strength, viscosity, dissipation, pressure iterations, inject U/V) and optionally binds a CHOP at audio_path so audio drives the dye injection strength. With injection_mode='auto', a slow LFO drives the splat point so the sim shows life with no input. Returns a summary plus a JSON block with the container path, created node paths, the dye_out output path, exposed controls, any node errors, warnings, and an inline preview image.

Parameter	Type	Required	Description
resolution	256 | 512 | 1024	no	Sim grid resolution (square). 512 is safe on integrated GPUs. (default: 512)
dye_color	string	no	Injected dye color as a '#rrggbb' hex string. (default: #ff3a8c)
injection_radius	number	no	Radius of the dye/force splat in UV units (0.01–0.5). (default: 0.08)
injection_strength	number	no	Multiplier on dye + velocity splat per frame (0–2). (default: 1)
viscosity	number	no	Velocity dissipation per frame (0–1). Higher = thicker fluid. (default: 0)
dissipation	number	no	Dye decay per frame (0.9–1.0). <1 fades trails. (default: 0.995)
pressure_iterations	integer	no	Jacobi iterations per frame (1–60). Higher = more incompressible. (default: 20)
injection_mode	auto | mouse | audio | static	no	How the splat point/strength is driven. (default: auto)
audio_path	string	no	Optional CHOP path; channel 0 multiplies injection strength when set.
expose_controls	boolean	no	Auto-expose an artist-facing control panel on the container. (default: true)
parent_path	string	no	Parent network where the fluid_sim container is created. (default: /project1)

image_to_particles mutates

Turn any image (a file path or an existing TOP) into a GPU particle field: each particle's rest position is its pixel in the source and (by default) its colour is sampled from that pixel. A spring force pulls particles toward their rest pixel; an optional audio chain scatters them away and lets them spring back, producing the iconic 'image dissolves into points on the drop, then re-forms' VJ look. Builds a new baseCOMP holding a downsampled source TOP, a one-shot rest-position GLSL TOP, velocity + position feedback loops (RGBA32float), an instanced Geometry COMP, Render, and a Null output. This is the only particle tool seeded by image/video pixels (rest positions + per-pixel colour); pick a sibling instead when particles are NOT driven by an image: create_gpu_particle_field for a free noise/curl/gravity drift field, create_particle_flock for boids/flocking, create_pop_particle_system for TouchDesigner's native POP particle network, create_particle_system for a simple CPU emitter. Default source is TD's stock Banana.tif; default audio source is 'none' (image idles statically) — 'file' and 'device' are opt-in (the latter may pop the macOS mic-permission dialog). Returns a summary plus a JSON block with the container path, particle count, output path, exposed controls, node errors, warnings, and an inline preview image.

Parameter	Type	Required	Description
source	object	no	Image source: { kind:'file', path } loads a moviefileinTOP, { kind:'top', path } references an existing TOP. Default uses TD's stock Banana.tif from app.samplesFolder. (default: [object Object])
side	integer	no	Particle grid edge; count = side². 192 → 36 864 particles. The source TOP is resampled to side×side so each texel maps 1:1 to one particle. (default: 192)
particle_size	number	no	Radius of each instanced dot (TOP instancing applies translate only, so size lives on the source sphere SOP). (default: 0.015)
scatter_strength	number	no	Audio impulse magnitude. 0 = particles sit perfectly on the image. (default: 6)
spring_stiffness	number	no	Force pulling each particle toward its rest pixel. Higher snaps back faster. (default: 4)
damp	number	no	Per-frame velocity damping. (default: 0.92)
audio_source	none | file | device	no	Drives the scatter impulse. 'none' = image idles statically. 'file' = audiofileinCHOP (set audio_file). 'device' = audiodeviceinCHOP (opt-in; may pop the macOS mic-permission dialog). (default: none)
audio_file	string	no	Audio file path when audio_source='file'. (default: ``)
color_mode	image | mono | tint	no	'image' = particle colours sampled from source pixels (via instancecolorop). 'mono' = white points. 'tint' = single colour multiplied by luminance. (default: image)
tint_color	object[]	no	RGB used when color_mode='tint'. (default: 1,1,1)
expose_controls	boolean	no	When true, expose live PointSize / SpringStiff / ScatterStr / Damp / Zoom knobs. (default: true)
parent_path	string	no	Parent network where the container is created. (default: /project1)

create_dither mutates

Build a retro dither effect: ordered Bayer (2×2/4×4/8×8), checker, noise, or single-pass error-diffusion — quantising to a 2/4/16-colour palette. Supports mono, duotone (Game-Boy-green default), or RGB quantisation mode. Creates a new baseCOMP under parent_path holding the source (or a self-contained noise source), a GLSL TOP with an inline shader, and a Null output. Exposes Mix, Threshold, and Scale knobs for live tweaking. Returns a summary, node paths, exposed controls, and an inline preview image.

Parameter	Type	Required	Description
name	string	no	Base name for the created container. (default: dither)
parent_path	string	no	Parent COMP path the dither container is created inside. (default: /project1)
source	string	no	Absolute path of an existing TOP to dither (e.g. '/project1/movie1'). Pulled in via a Select TOP. If omitted, a self-contained animated colour-noise source is used (no device permissions).
pattern	bayer2 | bayer4 | bayer8 | checker | noise | error_diffusion	no	Threshold pattern. bayer2/4/8: ordered Bayer matrices (2×2/4×4/8×8); checker: alternating grid; noise: pseudo-random hash; error_diffusion: single-pass 3×3 neighbourhood approximation. (default: bayer4)
bits	1 | 2 | 4	no	Bit depth per channel: 1=2 levels, 2=4 levels, 4=16 levels. (default: 1)
palette_mode	mono | duotone | rgb	no	mono: luminance → low/high colour. duotone: same with hue tint. rgb: quantise each channel independently using bits. (default: duotone)
low_color	object[]	no	Off/dark palette colour [r,g,b] 0–1. Used in mono and duotone modes. (default: 0.05,0.06,0.1)
high_color	object[]	no	On/light palette colour [r,g,b] 0–1. Game-Boy-green default. (default: 0.85,0.95,0.8)
threshold	number	no	Threshold bias applied on top of the pattern. (default: 0.5)
scale	number	no	Pattern scale in pixels — larger = chunkier dither. (default: 1)
mix	number	no	Blend between original (0) and dithered output (1). Live-tweakable. (default: 1)
resolution	object[]	no	Output resolution [width, height] in pixels. (default: 1280,720)

create_jfa_voronoi mutates

Instantiate a self-contained Jump-Flooding-Algorithm Voronoi generator (stained-glass / cell pattern) as GLSL TOPs — seeds → jfa_init → K halving passes → color_pass → null. Exposes live PaletteMode / SeedCount / Speed / Jitter / EdgeThickness / EdgeColor / ColorA / ColorB controls and previews the output TOP. Pass count auto-derives from resolution (log2(max(w,h))); override with step_count.

Parameter	Type	Required	Description
seed_count	integer	no	Number of Voronoi seeds (4..512). Drives the seed TOP width (next pow-2). (default: 48)
speed	number	no	Animation speed multiplier driving uTime drift of seeds. Live 'Speed' control. (default: 0.25)
palette_mode	random | from_image | duotone	no	random = HSV per seed; duotone = mix(ColorA, ColorB); from_image = sample image. (default: random)
palette_image	string	no	Op path to a TOP sampled at seed UVs when palette_mode='from_image'. (default: ``)
edge_thickness	number	no	Cell border width in UV units (0..0.05). Live 'EdgeThickness' control. (default: 0.004)
edge_color	string	no	Border colour as hex (e.g. '#000000'). Live 'EdgeColor' RGB swatch. (default: #000000)
jitter	number	no	Per-seed drift amplitude (0 = static lattice). Live 'Jitter' control. (default: 0.6)
color_a	string	no	Duotone primary hex. Live 'ColorA' swatch. (default: #ff3366)
color_b	string	no	Duotone secondary hex. Live 'ColorB' swatch. (default: #33ccff)
resolution	object[]	no	Output resolution [width, height]; JFA pass count auto-derived from max axis. (default: 1280,720)
step_count	integer	no	Manual JFA pass count (0 = auto = ceil(log2(max(w,h)))). (default: 0)
expose_controls	boolean	no	Expose live PaletteMode/SeedCount/Speed/Jitter/EdgeThickness/EdgeColor/ColorA/ColorB. (default: true)
parent_path	string	no	Parent COMP path; container 'jfa_voronoi' is created inside. (default: /project1)

setup_tdableton mutates

Wire up an Ableton Live bridge inside a tdmcp-managed container. Auto mode probes for the official TDAbleton Palette COMP; if found, clones it and surfaces tempo/beat/track/device channels as binding-ready Null CHOPs. Falls back to a full OSC fabric (oscinCHOP + selectCHOP fan-out) if the Palette isn't available. Either branch exposes the same Null CHOP names at the container boundary so downstream bind_to_channel calls work regardless of which path was taken.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP to host the container (default '/project1'). (default: /project1)
name	string	no	Container baseCOMP name. (default: tdableton)
mode	auto | palette | osc	no	Bridge mode. 'auto' = probe palette then fall back to OSC. 'palette' = require Palette (warn on miss, still builds OSC fallback). 'osc' = skip palette probe entirely. (default: auto)
host	string	no	Ableton host IP for the OSC Out CHOP. (default: 127.0.0.1)
port_in	integer	no	UDP port TD listens on (Live → TD). (default: 9001)
port_out	integer	no	UDP port TD sends to (TD → Live). (default: 9000)
track_count	integer	no	Number of /live/track/<i>/volume channels to materialise as bind-ready Nulls. (default: 8)
expose_devices	boolean	no	If true, generate /live/track/<i>/device/<j>/parameter/<k> listener rows up to device_param_count. (default: false)
device_param_count	integer	no	Per-track device-param count to materialise (used only when expose_devices). (default: 0)
include_master	boolean	no	Add Null CHOPs for /live/master/volume and /live/master/crossfader. (default: true)
include_tempo	boolean	no	Add Null CHOPs for tempo, beat, and bar. (default: true)

create_chop_recorder mutates

Build a CHOP recorder/player container that captures a source CHOP's channels over a fixed window using a Trail CHOP, snapshots the trail into a Table DAT on Stop, and plays the take back via a Datto CHOP indexed by a Timer CHOP–driven Lookup CHOP, terminating on a Null CHOP ready for bind_to_channel. Re-entrant: re-running with the same name updates controls without rebuilding. The last take is persisted in comp.store so it survives a .toe reload. Large takes (nchan × samples > 250k) are saved to disk instead of stored in the .toe. Note: time-dependent playback reads 0 when the TD timeline is paused — that is expected behavior.

Parameter	Type	Required	Description
name	string	yes	Container name, e.g. 'chop_rec_hand'
parent	string	no	Parent COMP path, defaults to '/'
sourceChop	string	yes	Path to source CHOP, e.g. '/project1/null_audio'
lengthSeconds	number	no	Trail window + take duration in seconds (0.25–120) (default: 8)
takeName	string	no	Storage key for persisted take (default: take1)
loop	boolean	no	When true, timer cycles; when false, plays once then holds (default: true)
recordOnCreate	boolean	no	If true, sets Record=1 on creation so the trail begins filling immediately (default: false)
autoBind	string	no	Optional 'opPath:parName' to auto-bind the Null CHOP output channel

create_video_scopes mutates

Build a broadcast-style video engineering monitor with multiple scope panels: waveform (luma trace), RGB parade (per-channel traces), and vectorscope (UV chrominance scatter). Each panel renders as a CHOP-to-SOP scope line through an orthographic camera and Render TOP, composited into a single output TOP via layoutTOP. Companion to create_waveform (audio) and create_spectrum (audio frequency). Default source is a synthetic test pattern (no device permission needed); 'device' is opt-in for live camera. The histogram panel here is unsupported in TD 099 and silently skipped — for a working luminance/RGB histogram use the standalone create_histogram_scope instead.

Parameter	Type	Required	Description
source	existing_top | test_pattern | file | device	no	Video source. 'test_pattern' = synthetic Banana.tif (no permission needed). 'existing_top' = reuse a TOP you already have (provide existing_top_path). 'file' = a video/image file. 'device' = live camera (videodeviceinTOP) — may hang TD on a macOS permission modal. (default: test_pattern)
existing_top_path	string	no	Path of an existing TOP to scope (source='existing_top').
video_file_path	string	no	Video/image file path (source='file').
enable_waveform	boolean	no	Show the luminance waveform panel. (default: true)
enable_parade	boolean	no	Show the RGB parade panel. (default: true)
enable_vectorscope	boolean	no	Show the UV vectorscope panel. (default: true)
enable_histogram	boolean	no	Show the luma histogram panel. Currently unsupported — TD 099 has no histogramCHOP (only histogramPOP). Pass true is accepted but the panel is silently skipped; re-enable once analyzeTOP histogram mode is confirmed. (default: false)
layout	grid_2x2 | row | column	no	How enabled panels arrange in the output composite. (default: grid_2x2)
panel_resolution	integer	no	Each scope panel's square side in pixels. (default: 512)
output_resolution	object[]	no	Final composited TOP [width, height]. (default: 1024,1024)
trace_color	string	no	Phosphor colour for scope lines as a hex string. (default: #00ff88)
expose_controls	boolean	no	Bind live controls: Gain, TraceColor, panel-enable toggles. (default: true)
gain	number	no	Pre-scope luma gain — zooms the trace vertically (Level TOP brightness1). (default: 1)
parent_path	string	no	Parent COMP path; the scopes container is created as 'video_scopes' inside it. (default: /project1)

create_sdf_field mutates

Build a programmable signed-distance-field (SDF) raymarcher in TouchDesigner as a self-contained GLSL TOP. Compose a CSG tree of sphere / box / torus primitives with union / intersect / subtract boolean ops and optional smooth blending. Exposes live CameraZ / Speed / StepCount / Intensity / Rotate / ColorA / ColorB / Background controls and previews the output.

Parameter	Type	Required	Description
primitives	object[]	no	CSG tree of SDF primitives (max 16). First prim is always union (root). Each subsequent prim is combined with the running fold via its op. (default: [object Object])
camera_z	number	no	Camera distance from origin (uCameraZ). Live 'CameraZ' control. (default: 4)
camera_target	object[]	no	Look-at point baked as GLSL constant (not a live control). (default: 0,0,0)
speed	number	no	Animation speed multiplier (drives uTime). Live 'Speed' control. (default: 1)
step_count	integer	no	Raymarch iterations (uSteps); SDF CSG benefits from more steps. Live 'StepCount'. (default: 96)
intensity	number	no	Output brightness multiplier (uIntensity). Live 'Intensity' control. (default: 1)
light_direction	object[]	no	Light direction normalised in shader — baked as GLSL constant. (default: 0.6,0.8,0.4)
color_a	string	no	Near colour hex (e.g. '#33ccff'). Live RGB swatch 'ColorA'. (default: #33ccff)
color_b	string	no	Far colour hex (e.g. '#ff2266'). Live RGB swatch 'ColorB'. (default: #ff2266)
background	string	no	Background / miss colour hex. Live RGB swatch 'Background'. (default: #06080c)
rotate_scene	number	no	Y-axis rotation speed (radians/s applied to SDF space via uRotate * uTime). Live 'Rotate'. Reads 0 when TD timeline is paused. (default: 0)
resolution	object[]	no	Output resolution [width, height] of the GLSL TOP. (default: 1280,720)
expose_controls	boolean	no	Expose live CameraZ/Speed/StepCount/Intensity/Rotate/ColorA/ColorB/Background controls. (default: true)
parent_path	string	no	Parent COMP path the self-contained 'sdf_field' container is created inside. (default: /project1)

create_strange_attractor mutates

Build a strange-attractor deferred geometry generator: a Script CHOP integrates a chosen ODE system (Lorenz / Aizawa / Halvorsen) with configurable sub-steps and maintains a rolling ring buffer of trail_length points. A Script SOP converts the channels into one open polyline; an optional Tube SOP thickens it for shaded render inside a Geometry COMP + Camera + Light + Render TOP pipeline. Closing Roadmap Milestone 4. Complements create_growth_system (L-systems) and create_particle_flock (boids) as the deterministic CPU-geometry idiom. With TD timeline paused the integrator pauses too (time-dependent) — resume playback to continue. Returns a summary plus a JSON block with the container path, output path, exposed controls, errors, warnings, and an inline preview.

Parameter	Type	Required	Description
name	string	no	Container baseCOMP name. (default: strange_attractor)
parent	string	no	Parent network where the container is created. (default: /project1)
attractor	lorenz | aizawa | halvorsen	no	ODE system to integrate: lorenz (classic butterfly), aizawa, or halvorsen. (default: lorenz)
trail_length	integer	no	Points retained in the rolling ring buffer. Higher = longer ribbon, costlier SOP cook. (default: 4000)
steps_per_frame	integer	no	RK-style integration sub-steps per cook frame (controls speed and smoothness). (default: 6)
dt	number	no	Integrator time step. Smaller = smoother but slower trajectory. (default: 0.005)
seed	object[]	no	Initial state [x, y, z]. A tiny non-zero offset avoids the Lorenz fixed-point stall at the origin. (default: 0.1,0,0)
params	object	no	Override ODE constants. Lorenz: sigma, rho, beta. Aizawa: a, b, c, d, e, f. Halvorsen: a. Unknown keys are ignored.
thickness	number	no	Tube SOP radius. Set to 0 to render the raw polyline (no Tube SOP — lighter on GPU). (default: 0.015)
color	object[]	no	Constant MAT colour (RGB, 0..1). (default: 0.6,0.9,1)
bg_color	object[]	no	Render TOP background colour (RGB, 0..1). (default: 0.02,0.02,0.04)
auto_frame	boolean	no	Auto-position camera based on attractor bounding radius (deterministic; no live bound query). (default: true)
expose_controls	boolean	no	Expose StepsPerFrame / Dt / TrailLength / Thickness as custom parameters on the container. (default: true)

create_optical_flow mutates

Build a CPU motion-energy field from a video source (cheap drop-in for displacement / particle chains; NOT a real dense optical-flow solver). Output is a single-channel TOP: bright = motion, mid-grey = still, computed as gain × (current − previous luminance) + 0.5. In direction_from='edges' mode the result is multiplied by a Sobel edge map for a coarse where-is-motion-relative-to-edges estimate — still not a true dx/dy gradient flow. No CUDA, no external models — built entirely from stock TD TOPs: blurTOP (pre-blur), monochromeTOP, cacheTOP (previous-frame delay), compositeTOP subtract (frame diff), optional edgeTOP cross-multiply, mathTOP (sensitivity gain + 0.5 recenter), feedbackTOP+levelTOP (temporal smoothing). Defaults to TD's bundled Mosaic.mp4 test clip so the chain builds and previews standalone without a live camera (avoids macOS permission modal). Output is a nullTOP. Reads 0 when TD timeline is paused and the source is static — that is correct behavior. Returns a summary plus JSON with node paths, controls, warnings, and an inline preview image.

Parameter	Type	Required	Description
name	string	no	Name of the container COMP created under parent_path. (default: optical_flow)
parent_path	string	no	Parent COMP path the optical flow container is created inside. (default: /project1)
source	string	no	Absolute path of a TOP to analyze for motion (pulled in via selectTOP so it can live anywhere). Omit to use TD's bundled Mosaic.mp4 test clip so the chain previews standalone without a live camera (avoids macOS permission hang).
resolution	object[]	no	Output resolution [width, height] in pixels. Default is half-HD — CPU optical flow is bandwidth-bound; larger resolutions are slower. (default: 640,360)
sensitivity	number	no	Multiplier on the raw frame difference (before the 0.5 recenter). Higher values pick up subtler motion (and more noise). Maps to mathTOP gain. (default: 4)
smoothing	number	no	Temporal smoothing on the flow output (feedbackTOP cross-fade). 0 = raw per-frame flow (jittery); 1 = ghosted/laggy. (default: 0.6)
blur	number	no	Spatial pre-blur (pixels) on source before differencing — suppresses high-frequency camera noise. Maps to blurTOP size. (default: 2)
direction_from	diff | edges	no	'diff' (default, cheapest): scalar frame-difference luminance (temporal motion energy). 'edges': cross frame-diff with Sobel edgeTOP for a coarse where-is-motion-relative-to-edges estimate — more flow-like but still a scalar, not a dx/dy vector, and ~2× cost. (default: diff)

create_histogram_scope mutates

Build a luminance (and optional per-channel RGB) histogram video scope for any TOP. Computes the histogram on the GPU using a GLSL TOP (bins×1 output), samples into a CHOP, normalises, and renders through choptoSOP → renderTOP. Output is a single Null TOP ready for previews or bind_to_channel. Implements the roadmap Milestone 2 histogram scope panel as a standalone focused tool. This is the single-scope, working histogram (the one create_video_scopes can't render in TD 099); for a combined waveform/parade/vectorscope monitor use create_video_scopes.

Parameter	Type	Required	Description
source	existing_top | test_pattern | file | device	no	Video source. 'test_pattern' = synthetic Banana.tif (no permission needed). 'existing_top' = reuse a TOP you already have (provide existing_top_path). 'file' = a video/image file. 'device' = live camera — may hang TD on a macOS permission modal. (default: test_pattern)
existing_top_path	string	no	Path of an existing TOP to scope (source='existing_top').
video_file_path	string	no	Video/image file path (source='file').
mode	luma | rgb	no	Histogram mode. 'luma' = single luminance trace. 'rgb' = three overlaid per-channel traces. Note: rgb mode is informational only in v1 — ships as luma with rgb flag in extra. (default: luma)
bins	integer	no	Number of histogram bins (16..512). Drives the GLSL TOP output width. Changing after build requires a rebuild. (default: 64)
gain	number	no	Pre-scope brightness (Level TOP brightness1 parameter). (default: 1)
log_scale	boolean	no	Compress tall peaks with log(1+x) in the normalisation Math CHOP. Changing after build requires a rebuild. (default: false)
trace_color	string	no	Phosphor tint colour for luma mode as a hex string. Ignored when mode='rgb'. (default: #00ff88)
bar_style	bars | line	no	Reserved — informational only in v1. Both values currently emit the same choptoSOP-fed render (a thin vertical strip per bin); a true polyline 'line' mode is planned. Setting this changes the value recorded in extra but does not yet change the SOP topology. (default: bars)
resolution	object[]	no	Output Null TOP size [width, height]. (default: 1024,512)
expose_controls	boolean	no	Bind live controls: Gain, TraceColor (luma mode), LogScale (informational). (default: true)
parent_path	string	no	Parent COMP path; the histogram scope container is created as 'histogram_scope' inside it. (default: /project1)

create_safety_blackout_chain destructive

Build a live-show safety primitive at the very end of the master output chain: deterministic fade-to-black over a configurable time, optional emergency single-frame hard-cut, optional hotkey + external watchdog trigger, and symmetric fade-in recovery. All reactivity is parameter-driven (Speed + Lookup CHOP + Math/Logic CHOPs) — no Python runs at cook time, so the chain is ALLOW_EXEC=0-safe. Complements create_panic (per-source kill+freeze) by being the master-output dimmer with grace, recovery, and a watchdog hook. Returns the container, source, dim, emergency-gate, composite, and output node paths plus the trigger merge/target/speed/lookup nodes.

Parameter	Type	Required	Description
input_path	string	no	Absolute path of the master TOP to protect. Pulled in via a Select TOP (TD wires can't cross COMPs). If omitted, a Ramp TOP test source is used so the chain still builds + previews.
parent_path	string	no	Parent COMP the safety chain is built inside (default '/project1'). (default: /project1)
fade_seconds	number	no	Time the soft fade-to-black (and symmetric fade-in) takes. 0 = instant. (default: 1.5)
fade_curve	linear | ease_in | ease_out | ease_in_out | s_curve	no	Interpolation shape for the fade ramp, applied via a Lookup CHOP curve so the ramp is deterministic and Python-free at cook time. (default: ease_in_out)
initial_state	live | black | held	no	Boot state. 'live' = pass-through, 'black' = Blackout toggle on at load, 'held' = Hold toggle on (good for show open before first cue). (default: live)
arm_emergency_snap	boolean	no	Expose an Emergency momentary pulse that bypasses the fade and hard-cuts to black. (default: true)
hotkey	string | null	no	Keyboard In CHOP key spec that toggles Blackout (e.g. 'ctrl.b'). null/empty disables — hotkey is opt-in safe, requires a modifier. (default: ctrl.b)
watchdog_channel	string	no	Optional absolute CHOP path + channel ('node:channel') — when non-zero, forces Blackout on. Lets external monitors trigger blackout deterministically without Python.
recovery_mode	manual | auto_on_clear	no	When the watchdog returns to 0: 'manual' keeps it black until the artist clears it; 'auto_on_clear' fades back in. (default: manual)
show_safe_label	string | null	no	Optional caption baked into the black frame (Text TOP composited over the dimmed output). Empty/null = no caption. (default: SHOW SAFE)
expose_controls	boolean	no	Build the control panel with Blackout / Emergency / Fade Seconds / State LED. (default: true)

create_setlist_runner mutates

Layer-1 wall-clock setlist player for rehearsed VJ shows. Pass rows[] of (source TOP, duration_seconds, transition_seconds) and the tool builds a baseCOMP containing N Select TOPs (one per row), a Switch TOP, a Cross TOP for crossfaded boundaries (hard cut when transition_seconds=0), an optional NOW/NEXT/remaining Text TOP HUD composited over the program, a Timer CHOP + CHOP Execute engine that auto-advances rows on wall-clock time, and live custom params Play/Row/Skip/Prev/Loop/Defaulttransition for stage overrides. Output is a Null TOP at <parent>/<name>/out. Fills the gap between create_clip_launcher (manual grid) and create_cue_sequencer (musical bars).

Parameter	Type	Required	Description
rows	object[]	yes	Ordered setlist rows. Each row: { source, duration_seconds, transition_seconds }.
sources_map	object	no	Optional { logical → TOP path } to allow human-readable row sources like 'actA' instead of an absolute path. (default: [object Object])
default_transition	number	no	Fallback transition_seconds (in seconds) for rows that omit it. (default: 0.5)
loop	boolean	no	When the last row ends: wrap to row 0 (true) or stop (false). (default: true)
autostart	boolean	no	Start playing immediately on build. (default: true)
show_hud	boolean	no	Build the NOW/NEXT/remaining Text TOP HUD as a child output. (default: true)
name	string	no	Engine container name. (default: setlist)
parent_path	string	no	Parent COMP path where the engine COMP is created (e.g. '/project1'). (default: /project1)

create_show_failover mutates

Build a live-show watchdog: a Switch TOP (blend=1 cross-dissolve) between a primary source TOP (NDI/camera/Spout/Syphon path, or a synthetic noiseTOP when none is given) and an MP4 fallback (or a constantTOP when no file is given), driven by an Info CHOP + watchdog CHOP-Execute DAT that trips on cook stall (total_cooks delta stays flat for stall_ms) and, optionally, primary cook errors. A Filter CHOP smooths the integer Switch index into a fade_ms crossfade. Sticky-recover auto-returns to primary after recover_ms healthy; otherwise stays on fallback until Reset. Exposes Active / Stall_Ms / Fade_Ms / Sticky_Recover / Reset / Force_Fallback controls and a Null CHOP of status channels for bind_to_channel. Returns the container, output TOP, status CHOP, control names, and the operator paths.

Parameter	Type	Required	Description
primary_path	string	no	Absolute TD path to the primary source TOP (NDI/camera/Spout/Syphon/any TOP). Empty → builds a synthetic noiseTOP so the network is offline-safe. (default: ``)
fallback_file	string	no	Filesystem path to the fallback MP4 / still. Empty → a constantTOP (dark grey) is used as a safe fallback. (default: ``)
stall_ms	integer	no	Consecutive ms of zero cook progress before failover trips. (default: 500)
fade_ms	integer	no	Crossfade duration in ms (0 = hard cut). Drives the Filter CHOP that smooths the Switch TOP index. (default: 250)
sticky_recover	boolean	no	When true, auto-switch back to primary after recover_ms of healthy cooking. When false, stays on fallback until Reset is pressed. (default: false)
recover_ms	integer	no	Healthy duration before auto-recover (only used when sticky_recover=true). (default: 2000)
watch_errors	boolean	no	Also trip on primary cook errors (errors > 0), not just on stall. (default: true)
status_overlay	boolean	no	Composite a small LIVE/FALLBACK badge (textTOP + compTOP) into the output. (default: true)
parent_path	string	no	Where to create the show_failover system container. (default: /project1)

create_pose_reactive mutates

Body-pose binder parallel to bind_audio_reactive: take the 33-sample MediaPipe pose CHOP produced by setup_body_tracking and derive scalar reactive channels (right-hand height, arms openness, elbow angle, hand velocity, …) on a Null CHOP ready for bind_to_channel. Each channel is a Select→Math→Hold→Filter→Limit→Rename chain inside a fresh baseCOMP, all merged into one null_out. Supported metrics: y/x/z (1 landmark), distance/openness (2 landmarks), angle (3 — vertex middle), velocity (1, time-derivative). Optional bindings[] writes expression-mode binds directly onto target parameters (same shape as bind_to_channel; failures collected as warnings, not throws). Exposes a Reactive custom page with Smoothing/Intensity/Bypass/Gate_<name> knobs. Heads-up: MediaPipe's landmarks are 2D (z near-zero) — z/distance/angle/velocity are unreliable unless the adapter exposes worldLandmarks; the tool emits a warning when it detects a constant tz. Run setup_body_tracking first.

Parameter	Type	Required	Description
source_chop	string	yes	Path to the 33-sample MediaPipe pose CHOP (tx/ty/tz/confidence channels) — typically the Null produced by setup_body_tracking.
channels	object[]	yes	Reactive channels to derive. Landmark IDs cheat-sheet — 0 nose, 11 L-shoulder, 12 R-shoulder, 13 L-elbow, 14 R-elbow, 15 L-wrist, 16 R-wrist, 23 L-hip, 24 R-hip, 25 L-knee, 26 R-knee, 27 L-ankle, 28 R-ankle.
parent_path	string	no	Parent COMP path. (default: /project1)
container_name	string	no	Container baseCOMP name (created under parent_path). (default: pose_reactive)
bindings	object[]	no	Optional list of parameter paths to bind to the derived channels (expression-mode bind, like bind_audio_reactive).
smoothing	number	no	0=raw, 1=very smoothed (drives filter width). (default: 0.25)
intensity	number	no	Master reactivity scaler (0=off, 1=normal, 2=strong). (default: 1)
expose_controls	boolean	no	Append Smoothing/Intensity/Bypass/Gate_<name> knobs to the container. (default: true)

create_pose_controlnet_driver mutates

Render a canonical OpenPose-colored stick figure TOP (per-limb RGB lines + per-joint colored discs on a black background, default 512×512) from an existing pose CHOP produced by create_pose_tracking. The render is GPU-rasterized in a single GLSL TOP that samples the pose CHOP via a CHOP-to-TOP. Optionally auto-wires the output to a Syphon/Spout or NDI sender for a downstream Stable Diffusion / ComfyUI / StreamDiffusion ControlNet node. No model inference — this tool produces the driver conditioning image that ControlNet consumes.

Parameter	Type	Required	Description
source	existing_tracker | synthetic	no	Where the pose stream comes from. 'existing_tracker' reads a 33-sample pose CHOP at pose_chop_path. 'synthetic' auto-spins-up a synthetic Script CHOP inside this container for device-free preview. (default: existing_tracker)
pose_chop_path	string	no	Required when source='existing_tracker'. Absolute TD path to the canonical 33-sample pose CHOP (tx/ty/tz/confidence).
resolution	512 | 768 | 1024	no	Square render size. ControlNet SD1.5 wants 512; SDXL wants 768/1024. (default: 512)
joint_radius	number	no	Filled-disc radius (px) for each keypoint joint. Exposed as live JointRadius knob. (default: 6)
limb_thickness	number	no	Line thickness (px) for each limb. Exposed as live LimbThickness knob. (default: 8)
coordinate_space	normalized | world	no	How to map landmark tx/ty to pixel space. 'normalized' maps [-1,+1] to full square. 'world' recenters using hip_midpoint and auto-scales to body height. (default: normalized)
mirror	boolean	no	Flip horizontally (selfie cam vs. ControlNet expectation). (default: false)
confidence_gate	number	no	Skip drawing landmarks/limbs whose endpoint confidence falls below this. Exposed as live knob. (default: 0.3)
color_preset	openpose_coco | openpose_body25 | custom	no	Canonical OpenPose 18-keypoint COCO palette by default. (default: openpose_coco)
custom_limb_colors	object[][]	no	When color_preset='custom'. Length must equal 17 (limb count).
custom_joint_colors	object[][]	no	When color_preset='custom'. Length must equal 18 (joint count).
output_mode	internal | syphon_spout | ndi	no	When 'internal' stops at a Null TOP. When 'syphon_spout'/'ndi' adds an FM-01 external sender. (default: internal)
sender_name	string	no	Sender/source name advertised on the network when output_mode != 'internal'. (default: tdmcp_controlnet_pose)
expose_controls	boolean	no	Expose live JointRadius, LimbThickness, ConfidenceGate, Mirror knobs. (default: true)
parent_path	string	no	Parent network for the pose_controlnet_driver baseCOMP. (default: /project1)

create_ascii_render mutates

Turn any TOP into a character-grid ASCII render: quantise input luminance into a (W/cell × H/cell) grid, then look up each glyph from a monospace character atlas. Supports mono, source-color (per-cell tint), and two-color (lerp by luminance) modes. Phosphor-green default for the Severance / CRT terminal look. Creates a resolutionTOP (cells), textTOP (atlas), glslTOP, and nullTOP output inside a new baseCOMP. Exposes Mix, CellSize, and Charset controls.

Parameter	Type	Required	Description
name	string	no	Base name for the created container. (default: ascii)
parent_path	string	no	Parent COMP path the ASCII render container is created inside. (default: /project1)
source	string	no	Absolute path of an existing TOP to render as ASCII (e.g. '/project1/movie1'). If omitted, a self-contained animated colour-noise source is used (no device permissions).
charset	string	no	Dark→light glyph ramp. Min 2 chars, max 32. Leading spaces add more 'black' room. (default: .:-=+*#%@)
cell_size	integer	no	Pixel size of each character cell. min 4, max 64. (default: 16)
color_mode	mono | source-color | two-color	no	mono: fixed fg on bg; source-color: per-cell average tint; two-color: lerp(bg,fg) by luminance. (default: source-color)
fg_color	object[]	no	Foreground glyph colour [r,g,b] 0–1. Phosphor-green default. Used in mono/two-color. (default: 0.85,0.95,0.8)
bg_color	object[]	no	Background colour [r,g,b] 0–1. Used in all modes. (default: 0.02,0.03,0.04)
font	string	no	Monospace font fed to the atlas textTOP. (default: Courier New)
mix	number	no	Blend between original (0) and ASCII output (1). Live-tweakable. (default: 1)
resolution	object[]	no	Output resolution [width, height] in pixels. (default: 1280,720)

create_phrase_locked_cue_engine mutates

Build a DJ/VJ phrase-quantized cue-lock engine. Any incoming pulse CHOP (Button, MIDI In, OSC In, composeCueList trigger) is queued FIFO and fired on the next 1/2/4/8/16/32/64-bar phrase boundary derived from the global project tempo. Live controls: Active (on/off gate), PhraseLength (live retune), Flush (clear queue), QueueDepth (display). Mode 'next' fires on the first upcoming boundary; 'aligned' locks to the project-start phrase grid. Pairs with create_tempo_sync upstream and bind_to_channel / manage_cue downstream. Output is a 0/1 trigger Null CHOP at <container>/out.

Parameter	Type	Required	Description
pending_chop_path	string	yes	Path to a CHOP whose first channel is the 'pending cue' pulse. Every time it rises 0→1 a cue is enqueued; the gated trigger fires it on the next phrase boundary. Wire a Button COMP, OSC In CHOP, MIDI In CHOP, or composeCueList trigger into this channel.
phrase_length_bars	1 | 2 | 4 | 8 | 16 | 32 | 64	no	Phrase length in bars. 16 is the DJ/VJ standard for builds/drops. Restricted to powers of 2 (1/2/4/8/16/32/64) — the canonical phrase grid; arbitrary values break the modulo lock. (default: 16)
quantize_mode	next | aligned	no	'next' (default): fire on the NEXT bar where (bar % phrase_length == 0), which is the upcoming phrase downbeat. 'aligned': only fire at a phrase downbeat that is also bar 1 of the bar-1-anchored phrase grid (bar % phrase_length == 0 AND bar >= phrase_length) — strict alignment from project start. For most live use, 'next' is what you want. (default: next)
queue_capacity	integer	no	Max queued pending cues. Extra pulses while at capacity are dropped (warning logged in storage). (default: 8)
expose_controls	boolean	no	Expose live PhraseLength / Active / Flush / QueueDepth controls on the engine container. (default: true)
name	string	no	Engine container name. (default: phrase_lock)
parent_path	string	no	Parent COMP. Self-contained engine container is created here. (default: /project1)

create_pop_particle_system mutates

Build a complete POP particle simulation (particle_pop → feedback_pop → lookup_texture_pop → field_pop → null_pop) inside a new baseCOMP, wire a render rig (poptoSOP → geometryCOMP → renderTOP → nullTOP), and expose EmissionRate, Lifetime, FeedbackGain, and ForceTexture live controls. When force_texture_path is omitted, a noiseTOP is created inside the container as the default force source so the chain always cooks. Supports three output modes: 'particles' (particle render), 'field' (field_pop visualization), and 'composite' (compositeTOP add of both). POP chain creation is delegated to build_pop_chain (Layer 2); this tool adds only the render rig and control exposure. This is the only particle tool built on TouchDesigner's native POP operators (force-texture driven, with field/composite output modes); pick a sibling instead for non-POP paths: create_gpu_particle_field for a GPU noise/curl/gravity drift field, create_particle_flock for GPU boids/flocking, image_to_particles to reconstruct an image/video as points, create_particle_system for a simple CPU emitter. NOTE: POPs are Experimental — the result carries an unverified marker; live-validate.

Parameter	Type	Required	Description
name	string	no	Container basename created under parent_path. (default: pop_particle_system)
parent_path	string	no	Parent COMP path (default '/project1'). (default: /project1)
emission_rate	integer	no	Particle birth rate per second; mapped to particle_pop birthrate and exposed as EmissionRate knob. (default: 5000)
lifetime	number	no	Particle lifetime in seconds; mapped to particle_pop life/lifeexpect. Exposed as Lifetime knob. (default: 4)
force_texture_path	string	no	Existing TOP path to drive the force field via lookup_texture_pop.par.top. If omitted, a noiseTOP is created inside the container as the default force source.
feedback_gain	number	no	Feedback strength on feedback_pop (mapped to inputmul). Exposed as FeedbackGain knob. (default: 0.92)
output	particles | field | composite	no	Which TOP the output nullTOP mirrors. 'particles' = render of particle_pop chain; 'field' = rendered field_pop visualization; 'composite' = compositeTOP (add) of both. (default: particles)
resolution	object[]	no	Render TOP resolution [width, height]. (default: 1280,720)

create_pop_growth mutates

Build a POP-native reaction-diffusion / growth system inside a fresh baseCOMP. Three mode presets: 'dendritic' (sparse fibrous tendrils, low decay), 'coral' (dense outward accretion, mid decay, strong force), 'lichen' (patchy crust, high threshold emission clusters). A particle_pop emits points gated by a noise threshold; a noise_pop drives a force_pop vector field that biases their motion; a feedback_pop loop carries point state forward one cook so accumulation simulates organic growth. Output is a Null TOP via poptoSOP → geometryCOMP → renderTOP. POP chain delegated to buildPopChainScript. POPs are Experimental — par writes are fail-forward; result reports unverified op/par set. Warns when feedback_gain × (1 − decay) ≥ 1.0 (divergence risk).

Parameter	Type	Required	Description
mode	dendritic | coral | lichen	no	Preset selector — picks the default param bundle. 'dendritic': sparse fibrous tendrils; 'coral': dense outward accretion; 'lichen': patchy emission clusters. (default: dendritic)
name	string	no	Container baseCOMP name. (default: pop_growth)
parent_path	string	no	Parent COMP where the container is built. (default: /project1)
growth_rate	number	no	Particle birth rate per cook (drives particle_pop birth/rate par defensively). Overrides preset.
decay	number	no	Per-frame multiplier applied through the feedback loop (1 − decay retained). Overrides preset.
threshold	number	no	Emission gate: noise sample below threshold suppresses new births. Overrides preset.
feedback_gain	number	no	Scale of the feedback contribution mixed back into the active POP each frame; >1 risks divergence. Overrides preset.
force_scale	number	no	Amplitude of the noise-driven force_pop vector field. Overrides preset.
noise_freq	number	no	Spatial frequency of the noise_pop. Overrides preset.
seed	integer	no	RNG seed for the noise. (default: 1)
max_points	integer	no	Safety cap on particle count (passed defensively as numpoints/maxparticles). (default: 50000)
resolution	object[]	no	Render TOP + Null TOP resolution [width, height]. (default: 1280,720)
expose_controls	boolean	no	Expose GrowthRate / Decay / Threshold / FeedbackGain knobs on the container. (default: true)

create_pop_lines_pointcloud mutates

Plexus-style line-web visual built on the POP family. A POP point cloud (auto-generated or sourced) is fed to a Neighbor POP that fills a per-point Nebr array attribute with closest-neighbor indices. A Script SOP converts that index list into deduplicated line primitives, rendered as a Geometry COMP through a Render TOP to a Null TOP — the classic Plexus look without third-party plugins. auto_pattern: 'noise' (default) = pointgeneratorPOP + noisePOP; 'sphere' = spherePOP; 'grid' = gridPOP. count is hard-capped at 8192 (CPU O(N·k) line emission). color_mode: flat | by_distance (warm→cool gradient) | by_neighbor_count (isolation ramp). Exposes live controls: MaxDistance, MaxNeighbors, Spin, PointSize, LineAlpha. POPs are Experimental — par names and Nebr array-attribute survival through poptoSOP are probe-first unverified; result carries extra.unverified.

Parameter	Type	Required	Description
name	string	no	Container base name; final path uses TD auto-suffix. (default: pop_lines)
parent_path	string	no	Parent network for the system container. (default: /project1)
source_path	string	no	If set, must point to an existing POP/SOP that produces a point cloud. When omitted, a point cloud is auto-generated per auto_pattern.
auto_pattern	noise | sphere | grid	no	Used only when source_path is undefined. noise = pointgeneratorPOP + noisePOP; sphere = spherePOP; grid = gridPOP. (default: noise)
count	integer	no	Approx point count when auto-generating. Hard-capped at 8192 (line emission is O(N·k) on CPU). (default: 512)
max_distance	number	no	Radius (POP world units) the Neighbor POP searches for neighbors. Drives Plexus density. (default: 0.5)
max_neighbors	integer	no	Per-point neighbor cap (neighborPOP.maxneighbors). Higher = denser web. (default: 4)
max_lines	integer	no	Hard cap on emitted line primitives in the Script SOP (after dedupe). (default: 5000)
color_mode	flat | by_distance | by_neighbor_count	no	Drives Cd attribute on the SOP. flat = single color; by_distance = per-line gradient; by_neighbor_count = per-point ramp on isolation. (default: flat)
color	object[]	no	Line color used directly in flat mode, as warm endpoint in by_distance, as dense endpoint in by_neighbor_count. (default: 1,1,1)
line_alpha	number	no	Constant MAT alpha; < 1 lets lines additively glow. (default: 0.7)
spin	number	no	Y-axis degrees/sec spin of the whole field via Transform POP ry expression. (default: 10)
point_size	number	no	Optional point overlay size rendered in addition to lines. 0 hides points. (default: 1.5)
resolution	object[]	no	Render TOP resolution [width, height]. (default: 1280,720)
expose_controls	boolean	no	Skip control panel exposure when false. (default: true)

create_depth_pop_field mutates

Build a depth-driven GPU POP scatter field: consumes a depth/mask TOP and uses lookup_texture_pop to sample depth for displacement/scatter proxies (and optionally color). When depth_top_path is omitted, auto-spins-up a setup_segmentation MediaPipe chain inside the container and uses its mask Null TOP as the depth source. Scatter modes: 'displace' applies a uniform depth-scale proxy, 'emit' adds an emission-like jitter scatter proxy, 'both' does both. Forward-compatible: pass create_depth_from_2d (Depth Anything, W4) output as depth_top_path. NOTE: POPs are Experimental — op types and par names are fail-forward, probe on a live TD. Returns a JSON block with container path, depth source info, controls, warnings, and unverified probe record.

Parameter	Type	Required	Description
name	string	no	Name for the self-contained container created under parent_path. (default: depth_pop_field)
parent_path	string	no	Parent COMP path where the depth-pop-field container is created. (default: /project1)
depth_top_path	string	no	Absolute path of an existing depth/mask TOP (luminance = depth, bright = near by default). When omitted, the tool auto-spins-up a setup_segmentation chain inside the container and uses its mask Null TOP as the depth source. Future W4: pass create_depth_from_2d output here.
particle_density	integer	no	Approximate point count fed to pointgeneratorPOP.numpoints (100–500 000). (default: 20000)
scatter_mode	displace | emit | both	no	'displace' = uniform depth-scale proxy on the point cloud; 'emit' = emission-like scatter jitter around the sampled depth field; 'both' = depth-scale proxy + scatter jitter. True depth-weighted birth is unverified. (default: displace)
depth_scale	number	no	Multiplier on the depth-driven displacement amount along +Z for displace/both scatter modes. Exposed as DepthScale knob when that displacement proxy is active. (default: 1)
color_by_depth	boolean	no	When true, copies sampled RGBA into POP Color attribute via a second lookup_texture_pop (near = bright / far = dark). (default: true)
invert_depth	boolean	no	Treat dark as near instead of bright. Implemented via Level TOP invert on a proxy feed. (default: false)
point_size	number	no	Render TOP point size, exposed as PointSize knob. (default: 2)
spin	number	no	Y-rotation of the field in deg/sec, animated via transformPOP ry expression. Exposed as Spin knob. (default: 8)
resolution	object[]	no	Render TOP resolution [width, height]. (default: 1280,720)
expose_controls	boolean	no	Build the live artist knobs panel for the active depth field controls. (default: true)

create_stipple_pointcloud mutates

Density-weighted particle scatter rendered as discrete points — a stippled / halftone-engraving point cloud whose dot distribution follows the luminance of a source TOP. Brighter regions yield denser clusters. Three visual modes: bw_dots (constant colour stipple), colored_dots (sample source RGB at each point), random_jitter (adds noisePOP for organic hand-engraved scatter). Outputs a Render TOP through a Geometry COMP in points render mode. Sibling to create_pop_geometry (procedural SOP geo) and the rasterised create_dither / create_halftone tools (which stay in TOP space).

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP to create the container under. (default: /project1)
name	string	no	Base name for the system container (TD auto-suffixes). (default: stipple_pointcloud)
source_top_path	string	no	Absolute path of an existing TOP whose luminance drives density. When omitted, a rampTOP radial gradient is built as the source.
dot_size	number	no	Point primitive size in pixels (0.5..8, default 2). (default: 2)
density	integer	no	Total particle count (100..200000, default 20000). Drives maxparticles + birthrate. (default: 20000)
mode	bw_dots | colored_dots | random_jitter	no	Visual treatment: bw_dots (constant colour), colored_dots (sample source RGB per-point), random_jitter (adds noisePOP for organic scatter). (default: bw_dots)
color_mode	white_on_black | black_on_white | palette	no	Background/foreground choice for bw_dots and random_jitter. Ignored by colored_dots. (default: white_on_black)
palette_color	object[]	no	Foreground RGB tuple when color_mode=palette. Default warm parchment [0.95, 0.9, 0.7]. (default: 0.95,0.9,0.7)
jitter_amount	number	no	Per-point position noise scale for random_jitter mode (0..1, default 0.25). (default: 0.25)
resolution	object[]	no	Output Render TOP resolution [w, h]. Default [1280, 720]. (default: 1280,720)
expose_controls	boolean	no	When true, expose live DotSize, JitterAmount (random_jitter only), and CameraRotate controls. (default: true)

drive_streamdiffusion mutates

Wraps the community StreamDiffusionTD.tox (by dotsimulate) into a one-shot Layer 1 setup: locate the .tox via candidate-path discovery, drop it into a fresh baseCOMP, wire a camera/source TOP into its input, set the prompt/strength/cfg/seed custom pars, and optionally re-broadcast the output via Syphon/Spout or NDI. Returns a friendly error when the .tox is not installed. The result envelope includes validated_pars so downstream tools (create_ai_mirror) know which SD pars to bind a control panel to.

Parameter	Type	Required	Description
tox_path	string	no	Optional explicit absolute or project-relative override. When set, becomes the only candidate; standard discovery is skipped.
source_top_path	string	no	File system path to a video/image file to feed into the StreamDiffusionTD container (creates a moviefileinTOP). When omitted, a synthetic noise TOP is created for device-free preview.
prompt	string	no	Sets the Prompt custom par on the tox. (default: a vibrant neon cyberpunk portrait, ultra detailed)
strength	number	no	img2img denoising strength — sets Strength par. (default: 0.6)
cfg	number	no	Classifier-free guidance scale. Low CFG (1–2) is normal for StreamDiffusion/LCM. (default: 1.2)
seed	integer	no	Random seed. -1 = random per tox convention. (default: -1)
controlnet_weight	number	no	Sets Controlnetweight when the par is present in the tox build.
t_index	integer	no	Sets Tindex (denoise step list index) when present; omitted = tox default.
output_mode	internal | syphon_spout | ndi	no	internal = Null TOP only. syphon_spout / ndi = adds an FM-01 sender wired from out1. (default: internal)
output_name	string	no	Sender/source name when output_mode != 'internal'. (default: tdmcp_streamdiffusion)
parent_path	string	no	Parent network for the fresh streamdiffusion_driver baseCOMP. (default: /project1)
expose_controls	boolean	no	Reserved for v2 — the tox already surfaces its own UI; this field is accepted but not acted on in v1. (default: true)

setup_mediapipe_plugin mutates

Drop the torinmb mediapipe-touchdesigner ENGINE in one shot and enable any combination of face, hand, body, and segmentation pipelines. Use this instead of running setup_face_tracking + setup_hand_tracking + setup_body_tracking + setup_segmentation separately — those tools each re-load the engine, resulting in multiple competing MediaPipe COMPs fighting for the webcam. This tool loads the engine ONCE and toggles its Face/Hand/Body/Segmentation pars. IMPORTANT: there is NO stock TouchDesigner MediaPipe; all five mediapipe tools (this one + the four setup_*_tracking tools) rely on the free torinmb plugin — install it first with tdmcp install mediapipe-touchdesigner. Output paths for face/hand/body are DATs (JSON landmark streams from the plugin), not CHOPs — use a Script CHOP adapter to convert to numeric channels. The engine requires the TD timeline to be PLAYING (uses an embedded browser for webcam capture).

Parameter	Type	Required	Description
tox_path	string	no	Override path to the torinmb mediapipe-touchdesigner ENGINE .tox (MediaPipe.tox — the full tracker with webcam capture, NOT the bare pose_tracking.tox or hand_tracking.tox processors). Defaults to the package staged by tdmcp install mediapipe-touchdesigner.
parent_path	string	no	Existing COMP to load the engine into. (default: /project1)
enable_face	boolean	no	Enable the Face detection pipeline inside the engine. (default: false)
enable_hand	boolean	no	Enable the Hand tracking pipeline inside the engine. (default: true)
enable_body	boolean	no	Enable the Body/Pose tracking pipeline inside the engine. (default: true)
enable_segmentation	boolean	no	Enable the Segmentation pipeline (outputs a matte TOP; heavier GPU cost than the landmark pipelines). (default: false)
source_video_path	string	no	Optional path to a video file to use as input instead of the live webcam. The engine's Camera/Source/Videofile/File par is probed in that order and the first match is set.
container_name	string	no	Inner baseCOMP name. Matches the default used by setup_body_tracking / setup_hand_tracking so re-running is idempotent (the engine is reused, not duplicated). (default: MediaPipe)

create_depth_from_2d mutates

Wraps TDDepthAnything v2 (community TOX by IntentDev) to convert any 2D image/video TOP into a depth map TOP using Depth Anything v2 via NVIDIA TensorRT/ONNX — no Kinect or RealSense required. Given a source TOP path, drops the TOX into a fresh container, wires the source, exposes a depth Null TOP whose path can be fed directly into create_depth_displacement, create_depth_pop_field, or create_depth_silhouette. Requires the user to have installed TDDepthAnything.tox from https://github.com/IntentDev/TDDepthAnything and an NVIDIA GPU with CUDA + TensorRT pre-built weights (.engine/.onnx). NOT supported on macOS. First cook may take 30–60 s for engine compile. Returns container_path, dropped_tox_path, depth_top_path (the key output), source_top_path, output_resolution, model_variant, and warnings.

Parameter	Type	Required	Description
source_top_path	string	yes	Absolute TD path of the 2D source TOP (movieFileInTOP / videoDeviceInTOP / NDI-in / any cooked TOP). Required.
tox_path	string	no	Override path to TDDepthAnything.tox. When omitted, candidates are tried in order. Set this when the TOX lives outside ~/Documents/Derivative.
output_resolution	256 | 384 | 512 | 768 | 1024	no	Square inference resolution. Lower = faster, higher = sharper depth edges. Default 512 matches Depth Anything v2 sweet spot on a 30-series GPU. (default: 512)
model_variant	small | base | large	no	Depth Anything v2 model size. small = ~25 ms/frame on RTX 3070, large = ~80 ms but cleaner edges. The TOX must have the matching .engine/.onnx weight on disk. (default: small)
parent_path	string	no	Parent network for the depth_from_2d baseCOMP. (default: /project1)

create_gaussian_splat_scene mutates

Drops the community TDGS .tox by Anglerfish-graphics into a fresh baseCOMP, loads a .ply or .splat Gaussian Splat asset, optionally binds an existing cameraCOMP, and exposes a clean output renderTOP at 720p–2160p. Assets can be exported from Polycam, Postshot, Luma, or Nerfstudio. The wrapper connects to any existing tdmcp camera rig (create_camera_orbit, XY pads, MIDI). REQUIREMENTS: TDGS by Anglerfish-graphics installed (https://github.com/Anglerfish-Graphics/TDGS); TouchDesigner build ≥2023.30000; CUDA-capable NVIDIA GPU on Windows. macOS and AMD GPUs are not supported by TDGS — the tool returns a friendly error. VRAM: 720p≈2GB, 1080p≈4-6GB, 1440p≈12GB+, 2160p≈16GB+ (OOM crashes TD — no friendly error, start at 720p on a laptop). Returns container_path, dropped_tox_path, output_top_path, camera_path, warnings, and a preview image.

Parameter	Type	Required	Description
splat_asset_path	string	yes	Absolute path to a .ply or .splat Gaussian Splat asset. Export from Polycam, Postshot, Luma, or Nerfstudio.
tox_path	string	no	Optional explicit absolute path to TDGS.tox. When set, skips the standard candidate walk. Useful when TDGS lives in a non-standard packages directory.
camera_path	string	no	Absolute TD path to an existing cameraCOMP (e.g. one built by create_camera_orbit). When set, TDGS's camera reference par is bound to it. When unset, TDGS uses its internal default camera.
output_res	720p | 1080p | 1440p | 2160p	no	Output renderTOP resolution. 720p=1280×720, 1080p=1920×1080, 1440p=2560×1440, 2160p=3840×2160. WARNING: 1440p+ requires a discrete GPU with ≥12GB VRAM; 2160p will crash TD on OOM. Default 1080p. (default: 1080p)
container_name	string	no	Name of the outer baseCOMP created by createSystemContainer. (default: gaussian_splat_scene)
parent_path	string	no	Parent network for the baseCOMP (default '/project1'). (default: /project1)
expose_controls	boolean	no	When true (default), promotes SplatAssetPath, CameraRef, and OutputRes to the wrapper container as live knobs. (default: true)

create_ai_mirror mutates

Layer 1 COMBO: wires the canonical 2026 AI-mirror installation in one MCP call — camera (or synthetic / existing TOP) → StreamDiffusion (img2img live, delegated to drive_streamdiffusion) → Syphon/Spout/NDI/internal output → a prompt+strength+cfg control panel whose sliders and textDATs drive SD pars via .expr expressions. Panel only binds pars present in drive_streamdiffusion's validated_pars; missing pars are warned, not errored. Camera source on macOS triggers the OS permission dialog on first cook; fallback_to_synthetic keeps the rig alive when the camera is unavailable.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP. (default: /project1)
name	string	no	Container name. (default: ai_mirror)
source	camera | synthetic | existing_top	no	Input source: USB camera (hype default), self-animated synthetic TOP, or an existing TOP routed through a Select. (default: camera)
existing_top_path	string	no	Required when source='existing_top'.
camera_device_idx	integer	no	USB camera device index when source='camera'. (default: 0)
fallback_to_synthetic	boolean	no	If camera creation fails, build a synthetic noise source instead of aborting. (default: true)
prompt	string	no	Initial StreamDiffusion prompt. (default: ethereal water)
negative_prompt	string	no	Initial StreamDiffusion negative prompt. (default: blurry, low quality, deformed)
strength	number	no	img2img mix; surfaced in the panel. (default: 0.65)
cfg	number	no	Classifier-free guidance scale; SD sweet spot 1–2. (default: 1.4)
steps	integer	no	StreamDiffusion 1–4 step LCM. (default: 2)
seed	integer	no	-1 = random per frame. (default: -1)
output_mode	syphon_spout | ndi | internal	no	Output: syphon_spout (macOS/Windows showcase form), ndi (cross-host), or internal (no sender). (default: syphon_spout)
output_sender_name	string	no	Sender / NDI name. (default: ai_mirror)
expose_control_panel	boolean	no	Build the prompt+sliders panel and wire .expr expressions to SD pars. (default: true)
show_camera_preview	boolean	no	Add a small selectTOP preview of the camera inside the panel. (default: true)

create_slit_scan mutates

Build a slit-scan visual system: each row (or column) of the output samples a different past frame from a Cache TOP ring buffer, producing the classic 'time-as-space' stretched-time look (Floris Kaayk / Adam Magyar style). Creates a new baseCOMP under parent_path holding a source TOP, a Cache TOP ring buffer, a slit GLSL shader, and a Null output. When no source_top_path is given, a synthetic Noise TOP is used so the tool works headless / on CI without camera permission. Exposes a live 'Depth' knob. Note: GLSL compile is UNVERIFIED offline; cacheTOP 2D-array binding must be validated live in TouchDesigner. Memory cost at 1080p RGBA16 is ~depth × 32 MB; depth 600 ≈ 5 GB VRAM. Output freezes when the timeline is paused (cacheTOP stops recording — expected behaviour). Returns a summary plus a JSON block with the container path, created node paths, output path, exposed controls, warnings, and an inline preview image.

Parameter	Type	Required	Description
parent_path	string	no	Parent network where the slit-scan container is created (default '/project1'). (default: /project1)
name	string	no	Container name for the slit-scan system (default 'slit_scan'). (default: slit_scan)
source_top_path	string	no	Optional path to an existing TOP to scan (e.g. '/project1/videodevicein1'). When omitted a synthetic noiseTOP seed is created inside the container so the tool runs headless / on CI without camera permission.
cache_depth	integer	no	Number of frames stored in the Cache TOP ring buffer (1–600, default 60). Memory cost: ~depth × W × H × 16 B at RGBA16. At 1080p, 600 frames ≈ 5 GB VRAM. (default: 60)
axis	x | y	no	Screen axis that carries time. 'y' = each row is a different past frame; 'x' = each column (default 'y'). (default: y)
direction	+y | -y | +x | -x	no	Which end of the axis is 'now'. '+y' = bottom row is the latest frame, top is oldest; '-y' reverses it. Must be compatible with axis (default '+y'). (default: +y)
expose_controls	boolean	no	When true (default), expose a live 'Depth' knob on the container bound to cache.cachesize. (default: true)

create_chrome_blobs mutates

Builds a liquid-chrome / Y2K metaball generator: an animated Noise TOP (or external source) is blurred, thresholded into soft blobs, then a GLSL TOP renders a procedural environment-map chrome look (greyscale ramp + moving specular highlight) with 5 metal tints and 4 background modes. Creates a self-contained baseCOMP with Speed, Blob_Count, Metal_Color, and Background controls exposed on the container.

Parameter	Type	Required	Description
parent_path	string	no	Parent network where the chrome-blobs COMP is created (default '/project1'). (default: /project1)
name	string	no	Name for the system container COMP (default 'chrome_blobs'). (default: chrome_blobs)
source_top_path	string	no	Optional external TOP to use as the blob field (pulls in via Select TOP). When omitted, an animated Noise TOP generates the blobs.
count	integer	no	Logical blob count — drives noise harmonics + blur/threshold params (1–32, default 8). (default: 8)
speed	number	no	Noise animation speed — controls the absTime.seconds multiplier on noise TX/TZ (0–4, default 0.5). (default: 0.5)
metal_color	silver | gold | copper | chrome_blue | gunmetal	no	Chrome tint palette for the GLSL environment-map shader (default 'silver'). (default: silver)
background	black | white | studio | gradient	no	Background behind the chrome blobs — black, white, studio (soft radial), or gradient (vertical chrome studio) (default 'black'). (default: black)

create_vintage_lens mutates

Drape a vintage analog-film aesthetic over any TOP in one call. Chains barrel/pincushion lens distortion → chromatic aberration → vignette → film grain as four inline GLSL passes inside a new baseCOMP. Era presets (super8, vhs, 16mm, 80s_camcorder) load era-correct strength defaults; any per-param override wins. Returns a standard Layer 1 envelope with container path, node paths, output path, preview image, warnings, and the resolved strength values.

Parameter	Type	Required	Description
parent_path	string	no	Parent network where the vintage-lens container is created (default '/project1'). (default: /project1)
name	string	no	Name suffix for the baseCOMP (default 'vintage_lens'). (default: vintage_lens)
source_top_path	string	yes	Path of the existing TOP to grade (e.g. '/project1/render1').
era	super8 | vhs | 16mm | 80s_camcorder	no	Era preset that sets default strength values; per-param overrides win. (default: super8)
distortion_strength	number	no	Barrel-distortion coefficient (UV warped from center). Overrides preset.
ca_strength	number	no	RGB-split offset magnitude (radial from center). Overrides preset.
vignette_strength	number	no	Edge darkening amount; 0 disables. Overrides preset.
grain_amount	number	no	Per-pixel noise amplitude. Overrides preset.

create_reaction_diffusion mutates

Build a Gray-Scott reaction-diffusion GPU simulation as a ready-to-use visual system. Delegates to the built-in 'reaction_diffusion' recipe (seed GLSL TOP → feedbackTOP → simulation GLSL TOP → null output), then overlays caller-provided Gray-Scott parameters (Feed rate F, Kill rate K, diffusion coefficients Da/Db) as GLSL uniforms, patches the shader so da/db use the uniforms instead of hard-coded constants, and optionally chains a rampTOP + lookupTOP for a color LUT (coral / spots / stripes / mitosis presets). Exposes a control panel with sliders for F, K, Da, Db, resolution, and a palette menu. Output node is a nullTOP ready for downstream wiring. 'iterations>1' is unverified — effective value is 1 with a warning.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP path the reaction-diffusion container is created inside. (default: /project1)
name	string	no	Base name for the created container. (default: reaction_diffusion)
F	number	no	Gray-Scott feed rate (uniform uFeed). Controls how fast chemical A is replenished. Lower = sparser, more open patterns; higher = denser maze-like structures. (default: 0.055)
K	number	no	Gray-Scott kill rate (uniform uKill). Controls how fast chemical B is removed. Tune alongside F to shift between spots, stripes, and maze regimes. (default: 0.062)
Da	number	no	Diffusion rate of chemical A (uniform uDa). Default 1.0. Increasing slows pattern growth; the recipe default is 1.0. (default: 1)
Db	number	no	Diffusion rate of chemical B (uniform uDb). Default 0.5. Tuning relative to Da changes pattern sharpness. (default: 0.5)
iterations	integer	no	Simulation steps per rendered frame. UNVERIFIED — feedbackTOP has no native cookrate param; effective value is 1 with a warning if >1 is requested. Field retained for forward-compatibility. (default: 5)
palette	coral | spots | stripes | mitosis | none	no	Post-sim color LUT applied via a rampTOP + lookupTOP downstream of the GLSL simulation. 'coral' = deep-purple→magenta→cream→white; 'spots' = black→cyan→white; 'stripes' = indigo→green→yellow; 'mitosis' = blood-red→orange→bone-white; 'none' = raw simulation state (R=A, G=B). (default: coral)
resolution	integer	no	Square simulation grid size in pixels. Overrides seed1.resolutionw/h. Higher values produce finer detail at higher GPU cost. (default: 256)

create_pixel_sort mutates

Build a glitch-art pixel-sort effect that sorts pixels along rows or columns within luminance-thresholded regions, creating the signature Kim Asendorf–style horizontal/vertical streak aesthetic. Uses a multi-pass odd-even transposition sort over a glslTOP feedback chain. Sort key: luminance, hue, or saturation. Exposes Mix, Threshold, Iterations, Direction, and Reset for live tweaking. Defaults to a self-contained noiseTOP source when no input TOP is provided.

Parameter	Type	Required	Description
name	string	no	Base name for the created baseCOMP. (default: pixel_sort)
parent_path	string	no	Parent COMP path. The pixel-sort container is created inside this path. (default: /project1)
source_top_path	string	no	Absolute path to an existing TOP (e.g. '/project1/movie1'). Pulled in via a Select TOP. If omitted, a self-contained animated noiseTOP source is used (no device permissions).
threshold	number	no	Luminance gate [0..1]. Pixels with luminance >= threshold are sortable; others are locked in place. Live-tweakable. (default: 0.5)
axis	x | y	no	x = sort along rows (horizontal streaks), y = along columns (vertical streaks). (default: x)
sort_by	luminance | hue | saturation	no	Sort key: the channel the odd-even transposition sort compares on. (default: luminance)
direction	ascending | descending	no	descending puts bright/saturated pixels first — the canonical Asendorf look. Live-tweakable. (default: descending)
iterations	integer	no	Number of odd-even sort passes to run via the Feedback TOP. Higher = closer to fully sorted but heavier cook. Live-tweakable. (default: 64)
mix	number	no	Blend between original (0) and sorted output (1). Live-tweakable. (default: 1)
resolution	object[]	no	Output resolution [width, height] in pixels. (default: 1280,720)

create_volumetric_field mutates

Build a stacked-slice fake-volumetric noise field: smoke, nebula, ember, ice, toxic or mono palettes. Architecture: Simplex 3D noiseTOP → optional displace+blur → cacheTOP (depth = slice_count) → viewer glslTOP (Beer-Lambert accumulation across slices, baked palette) → nullTOP output. NOTE: this is a stacked-2D-slice approximation, NOT a raymarched volume. There is no per-pixel ray traversal or SDF. For a true raymarcher see the planned create_volumetric_raymarch (L-effort follow-up). Cook cost scales roughly linearly with slice_count × resolution. Default 16 slices is the safe sweet spot; drop to 4–8 on integrated GPUs. Returns a summary JSON with container path, created node paths, the output path, exposed controls, any node errors, warnings, and an inline preview image.

Parameter	Type	Required	Description
parent_path	string	no	Parent network where the volumetric_field baseCOMP is created. (default: /project1)
name	string	no	Container name (must start with a letter, alphanumeric + underscore). (default: volumetric_field)
density	number	no	How opaque/milky the field reads (0 = transparent, 1 = fully opaque). Maps to uDensity in the viewer shader. (default: 0.5)
turbulence	number	no	Noise evolution speed and swirl amplitude. Drives the displacement weight and noise period. 0 = flat/still field; skips the displace TOP. (default: 0.4)
color_map	smoke | nebula | ember | ice | toxic | mono	no	Palette baked into the viewer GLSL shader: smoke (grey haze), nebula (purple/magenta), ember (orange/red), ice (blue/cyan), toxic (green), mono (black→white). (default: smoke)
slice_count	integer	no	Number of 2D z-slices stacked into the pseudo-volume. Build-time only — changing it rewires the cache stack. Higher = smoother depth but heavier cook (linear cost). Default 16 is the safe sweet spot. (default: 16)
expose_controls	boolean	no	Expose Density, Turbulence and ColorMap knobs on the container. (default: true)

create_voxel_stack mutates

Isometric voxel-stack renderer driven by any TOP. Builds a single instanced Geometry COMP (boxSOP, N=cols·rows instances up to 256×256) with a CHOP chain sampling luminance for column height and per-instance color. Color modes: source_color (sample TOP directly), palette (Monument-Valley pastel ramp), height_ramp (same palette, height-based). Isometric ortho cam (rx=-35.264°, ry=45°) by default; perspective available. Exposes HeightScale, VoxelSize, and RotateY controls. If source_top_path is omitted, an animated noiseTOP drives the stack.

Parameter	Type	Required	Description
parent_path	string	no	Parent network where the voxel stack container is created. (default: /project1)
name	string	no	Base name for the container (defaults to 'voxel_stack').
source_top_path	string	no	Path to an existing TOP that drives heights and colors. If omitted, a built-in animated noiseTOP feeds the stack.
grid_size	object[]	no	Voxel grid cols × rows. Hard-capped at 256×256 (65k instances). (default: 32,32)
voxel_size	number	no	Cube edge length in world units; also the XZ spacing between voxels. (default: 0.5)
height_scale	number	no	Multiplier on luminance → Y translate. 0 = flat slab. (default: 8)
color_mode	source_color | palette | height_ramp	no	Per-instance color: sample source TOP directly (source_color), look up into a palette ramp (palette), or use a default pastel height ramp (height_ramp). (default: source_color)
palette	object[][]	no	Ramp endpoints as [r,g,b] tuples (2–8 stops). Used only when color_mode='palette'. Defaults to a Monument-Valley pastel 5-stop ramp.
output_resolution	object[]	no	Render TOP resolution [width, height]. (default: 1280,720)
camera_mode	isometric | perspective	no	Isometric uses ortho camera at rx=-35.264°, ry=45° (classic iso). Perspective uses a standard 35mm orbit cam. (default: isometric)
expose_controls	boolean	no	When true, expose HeightScale, RotateY, and VoxelSize knobs on the container. (default: true)

create_facade_mapping mutates

Build a multi-projector architectural facade rig: one source TOP fanned into N per-projector branches, each with Crop → Corner Pin keystone → edge-blend Ramp/Composite mask → Level brightness, plus per-projector Null outputs and a summary preview composite. Ships as a calibration skeleton; per-projector corners, color match, and (when 3D) camera transforms are left to live install alignment.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP where the facade mapping system is created. (default: /project1)
name	string	no	Name of the generated Base COMP. (default: facade_mapping)
source_top_path	string	no	Absolute TOP path to fan out; required when source_mode='existing_top'.
source_mode	existing_top | synthetic	no	Synthetic builds a self-animated noiseTOP so the rig previews without an upstream feed. (default: synthetic)
projector_count	integer	no	Number of projectors. Each projector gets its own branch and Null output. (default: 2)
blend_width	integer	no	Edge-blend overlap region in pixels (alpha gradient width on inner edges). (default: 192)
blend_layout	horizontal | vertical | grid	no	How projectors tile: horizontal row, vertical column, or near-square grid. (default: horizontal)
output_width	integer	no	Per-projector pixel width. (default: 1920)
output_height	integer	no	Per-projector pixel height. (default: 1080)
facade_geometry_path	string	no	Optional absolute SOP/COMP path to a 3D facade model. PARTIAL/UNVERIFIED: when provided, builds a per-projector cameraCOMP + renderTOP + geometryCOMP stub.
blend_curve	linear | gamma22 | smoothstep	no	Curve applied to the alpha gradient via Level gamma. (default: smoothstep)
expose_controls	boolean	no	Build a Control Panel with per-projector brightness + global blend width/curve. (default: true)
background_color	string	no	Background color as #rrggbb. (default: #000000)

create_step_repeat mutates

Tile a source TOP into a rows×cols brick/grid pattern with per-cell gap, position jitter, rotation jitter, and an optional brick/masonry half-tile row offset — all computed per-cell in a single GLSL TOP shader (stock TOPs only, no external files besides the optional source). Defaults to a built-in synthetic Noise TOP so the grid previews standalone on any install without a source (no external asset). Output is a nullTOP. Returns a summary plus JSON with node paths, live controls, warnings, and an inline preview image.

Parameter	Type	Required	Description
source_path	string	no	Absolute path of a TOP to tile (pulled in via selectTOP so it can live anywhere). Omit to use a built-in synthetic Noise TOP so the grid previews standalone on any install (no external asset needed).
rows	integer	no	Number of tile rows (vertical repeats). (default: 4)
cols	integer	no	Number of tile columns (horizontal repeats). (default: 4)
gap	number	no	Fractional inset per cell (0 = tiles touch, 0.5 = half the cell is gap). (default: 0.05)
jitter_pos	number	no	Per-cell random position offset, fraction of a cell. (default: 0)
jitter_rot	number	no	Per-cell random rotation, max radians. (default: 0)
brick_offset	boolean	no	Shift alternating rows by half a tile (brick/masonry layout). (default: false)
resolution	object[]	no	Output resolution [width, height] in pixels. (default: 1280,720)
parent_path	string	no	Parent COMP path the self-contained 'step_repeat' container is created inside. (default: /project1)

create_pointer_reactive mutates

Turn mouse/pointer position and click into a first-class creative seed. Builds a Mouse In CHOP → normalized u/v (0..1) + velocity (vu/vv) + button, exposed on a 'pointer' Null CHOP ready for binding: op('…/pointer_reactive/pointer')['u'] / ['v'] / ['button'] / ['vu'] / ['vv']. A Sensitivity knob gains every channel. By default also builds a small visible demo — a bright dot that follows the pointer and leaves a decaying trail over a feedback field — so you immediately see it working; set demo=false to build only the CHOP chain (no image, no preview). multitouch is reserved for a future Panel-COMP touch source; this build always uses Mouse In and reports the limitation as a warning when requested. Creates a new baseCOMP under parent_path. Returns a summary plus a JSON block with the container path, created node paths, the pointer Null path, channel names, exposed controls, any node errors, and warnings.

Parameter	Type	Required	Description
multitouch	boolean	no	When true, note that true multitouch needs a Panel COMP touch source; this build always uses Mouse In (single pointer) and reports the limitation as a warning. Kept for forward-compat — it does not change what gets built. (default: false)
demo	boolean	no	Also build a visible feedback-field demo the pointer pushes, so you see it working immediately (a bright dot that trails behind the mouse over a decaying feedback field). (default: true)
sensitivity	number	no	Gain applied to every pointer channel (u, v, velocity, button) before the output. (default: 1)
resolution	object[]	no	Output resolution [width, height] in pixels for the demo feedback field. (default: 1280,720)
parent_path	string	no	Parent network where the pointer-reactive container is created (default '/project1'). (default: /project1)

create_interaction_zones mutates

Define N rectangular zones over a camera / motion input; each zone fires when motion in that region crosses a threshold. Builds a stock-TOP chain — a motion-energy TOP (monochrome → previous-frame cache → difference), then per zone a cropTOP (region isolate) + analyzeTOP average + toptoCHOP, merged into one level CHOP, then a scriptCHOP that emits per zone a *_state channel (0/1 active) and a *_dwell channel (seconds continuously active). Ends on a 'zones' Null CHOP as the bind point — wire cues via bind_to_channel to op('…/interaction_zones/zones')['zone0_state']. Camera-only (no depth cam). Source is a TOP pulled via selectTOP, or a built-in synthetic animated Noise TOP when omitted (offline-safe, cooks clean on any install with no external asset). A live Threshold knob tunes sensitivity. Zones are normalized rects (x,y = top-left corner, w,h = size); the top-left image convention is mapped to TD's bottom-left uv origin. Returns a summary plus JSON with the container path, created node paths, the zones Null path, per-zone state/dwell channel names, the zone definitions, threshold, and warnings (no preview image — the output is a CHOP, not a TOP).

Parameter	Type	Required	Description
source_path	string	no	TOP to watch for motion (pulled via selectTOP). Omit for a built-in synthetic animated Noise TOP that cooks clean on any install (offline-safe, no external asset).
zones	object[]	no	Rectangular zones (normalized 0..1) to watch. (default: [object Object],[object Object])
threshold	number	no	Motion level above which a zone counts as active. (default: 0.05)
resolution	object[]	no	Analysis resolution [width, height] in pixels (cheap; motion detection is bandwidth-bound). (default: 640,360)
parent_path	string	no	Parent COMP the interaction-zones container is created inside (default '/project1'). (default: /project1)
name	string	no	Name of the container COMP created under parent_path. (default: interaction_zones)

lidar_floor_tracker mutates

Build a floor-occupancy tracker scaffold for synthetic rehearsal, Ouster TOP, Leuze ROD4 CHOP, or UDP point input. Produces a tracked_points CHOP plus a floor preview TOP; hardware modes default inactive and remain explicitly unverified until a real sensor is connected.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP path to build inside. (default: /project1)
name	string	no	Generated container name. (default: lidar_floor_tracker)
sensor	synthetic | ouster | leuze_rod4 | udp_points	no	Sensor scaffold to create. Hardware modes stay inactive by default. (default: synthetic)
sensor_address	string	no	IP address for Ouster/Leuze hardware modes.
port	integer	no	UDP/network input port. (default: 7502)
floor_width_m	number	no	Tracked floor width in meters. (default: 6)
floor_depth_m	number	no	Tracked floor depth in meters. (default: 4)
threshold	number	no	Occupancy threshold. (default: 0.35)
active	boolean	no	Enable live hardware input immediately. Defaults false for rehearsal safety. (default: false)
expose_controls	boolean	no	Expose Threshold and Scale controls. (default: true)

create_terrain mutates

Build a procedural heightmap landscape: an animated Noise TOP height field displaces a subdivided Grid SOP along Z in a GLSL vertex-displacement MAT (real 2.5D geometry, elevation-shaded from a low→high colour ramp), lit by a key Light, framed by a raised angled Camera, and rendered. Optionally adds a flat translucent water plane at water_level and a camera-distance fog fade into the sky/background colour. Distinct from create_visual_system's 'terrain' keyword (which only maps to a noise_landscape recipe) — this is a dedicated, fully parameterized terrain pipeline with its own displacement material, water, and fog. Creates a new baseCOMP under parent_path. Exposes Height, Drift, WaterLevel, and Zoom controls. Returns a summary plus a JSON block with the container path, created node paths, output path, exposed controls, node errors, warnings, and an inline preview image.

Parameter	Type	Required	Description
subdivisions	integer	no	Grid resolution (rows = cols). Higher = finer relief and smoother displacement, but more vertices to push. 160 gives a 160×160 plane. (default: 160)
height	number	no	Displacement amount along Z: how far bright pixels push the surface up. 0 = flat. (default: 0.6)
noise_period	number	no	Noise TOP period — larger = broader, smoother hills; smaller = tighter, rockier. (default: 2.4)
drift	number	no	Scroll speed of the noise height field along Z per second so the landscape slowly evolves. 0 = static terrain. Reads 0 when the TD timeline is paused. (default: 0.15)
low_color	object[]	no	Colour of the valleys / lowest elevation (RGB 0..1). (default: 0.06,0.12,0.05)
high_color	object[]	no	Colour of the peaks / highest elevation (RGB 0..1). (default: 0.85,0.82,0.7)
water	boolean	no	Add a flat translucent water plane at water_level cutting through the terrain. (default: true)
water_level	number	no	Z elevation of the water plane, in the same units as height. (default: 0.12)
water_color	object[]	no	Water plane colour (RGB 0..1). Rendered semi-transparent. (default: 0.05,0.22,0.35)
fog	boolean	no	Fade the far terrain into background by camera distance (volumetric-ish haze). (default: true)
background	object[]	no	Sky / background + fog colour (RGB 0..1). (default: 0.5,0.6,0.72)
expose_controls	boolean	no	When true (default), expose live Height / Drift / WaterLevel / Zoom controls. (default: true)
parent_path	string	no	Parent network where the terrain container is created (default '/project1'). (default: /project1)

create_asemic_writing mutates

Generate a page of procedural asemic writing — random-but-writing-like glyph strokes that flow left-to-right along stacked baselines but spell nothing. A Script SOP lays out rows × glyphs cells; each glyph is a short chain of strokes control points walking a noise-perturbed pen, with italic slant, per-stroke jitter, and occasional pen-lifts (lift_chance) that break marks apart. The polylines are thickened into tube ink strokes and rendered with an orthographic camera as calligraphic line art on a coloured page. Deterministic per seed. Genuinely distinct from create_growth_system (L-system branches) and create_vector_lines (image-traced contours). Creates a new baseCOMP under parent_path. Exposes Jitter, Slant, Thickness, and Seed controls. Returns a summary plus a JSON block with the container path, created node paths, output path, exposed controls, node errors, warnings, and an inline preview image.

Parameter	Type	Required	Description
rows	integer	no	Number of baselines (lines of writing) stacked top to bottom. (default: 8)
glyphs	integer	no	Glyphs per row, laid left to right along the baseline. (default: 14)
strokes	integer	no	Control points per glyph — more strokes = more elaborate, script-like marks. (default: 5)
jitter	number	no	How far the pen wanders vertically per stroke (fraction of the line height). 0 = flat dashes, 1 = wild scrawl. (default: 0.55)
slant	number	no	Italic slant applied to every glyph (x-shear per unit height). 0 = upright. (default: 0.12)
lift_chance	number	no	Probability the pen lifts (breaks the polyline) between adjacent strokes, giving disconnected marks. (default: 0.25)
thickness	number	no	Tube SOP radius for the rendered ink strokes. (default: 0.004)
ink_color	object[]	no	Stroke (ink) colour (RGB 0..1). (default: 0.9,0.9,0.92)
background	object[]	no	Page / background colour (RGB 0..1). (default: 0.06,0.05,0.07)
seed	integer	no	RNG seed — same seed reproduces the same page of writing. (default: 1)
parent_path	string	no	Parent network where the asemic-writing container is created (default '/project1'). (default: /project1)

create_sdf_text mutates

Raymarch a text string as a signed-distance-field 3D slab: a Text TOP renders the glyphs to a mask, and a GLSL TOP treats that mask as an extruded distance field (glyph coverage in XY, closed by two Z planes at ±depth/2) so the letters read as solid, lit, rim-highlit 3D volumes that can spin. Distinct from create_sdf_field (primitive CSG only, no text) and create_text_3d (mesh-extruded text SOP) — this is the raymarched distance-field text look. The mask→SDF is approximate (coverage-derived, no external font SDF atlas required) and eased by smoothing. Creates a new baseCOMP under parent_path. Exposes CameraZ/Speed/StepCount/Intensity/Rotate/Fill/Edge/Background controls and previews the output. Returns a summary plus a JSON block with node paths, exposed controls, node errors, warnings, and an inline preview image.

Parameter	Type	Required	Description
text	string	no	The string to raymarch as SDF text. (default: HELLO)
font	string	no	Font family for the Text TOP that seeds the glyph mask (must be installed in TD). (default: Arial)
bold	boolean	no	Render the seed text bold (thicker glyph coverage). (default: true)
depth	number	no	Extrusion thickness of the raymarched text slab along Z (uDepth). (default: 0.25)
smoothing	number	no	How sharply the mask coverage maps to the XY distance field. Lower = crisper edges, higher = softer/rounder. (default: 0.6)
camera_z	number	no	Camera distance from the text (uCameraZ). Live 'CameraZ' control. (default: 2.2)
rotate	number	no	Y-axis rotation speed of the text (radians/s via uRotate * uTime). Live 'Rotate'. Reads 0 when the TD timeline is paused. (default: 0)
speed	number	no	Animation time multiplier (drives uTime). Live 'Speed' control. (default: 1)
step_count	integer	no	Raymarch iterations (uSteps). Live 'StepCount'. (default: 80)
intensity	number	no	Output brightness multiplier (uIntensity). Live 'Intensity'. (default: 1)
fill_color	string	no	Letter body colour hex (e.g. '#ffd34d'). Live RGB swatch 'Fill'. (default: #ffd34d)
edge_color	string	no	Rim/edge highlight colour hex. Live RGB swatch 'Edge'. (default: #ff5c8a)
background	string	no	Background / miss colour hex. Live RGB swatch 'Background'. (default: #0a0a12)
light_direction	object[]	no	Light direction, normalised in shader — baked as GLSL constant. (default: 0.4,0.6,0.8)
resolution	object[]	no	Output resolution [width, height] of the GLSL TOP. (default: 1280,720)
expose_controls	boolean	no	Expose live CameraZ/Speed/StepCount/Intensity/Rotate/Fill/Edge/Background controls. (default: true)
parent_path	string	no	Parent COMP path the self-contained 'sdf_text' container is created inside. (default: /project1)

create_vertex_displacement_mat mutates

Build a true vertex-shader displacement material: a GLSL MAT whose vertex stage offsets each vertex along its normal by procedural 3D noise (uTime-animated) or by the luminance of a sampled TOP (texture_path), so the mesh is physically deformed on the GPU. Distinct from the TOP-space image warps create_depth_displacement / create_displacement_warp — those push 2D pixels; this pushes mesh vertices. Assign it to your own Geometry COMP via target_geo, or omit it to build a self-contained demo (subdivided sphere + camera + light + render + Null) so the material previews standalone. Creates a new baseCOMP under parent_path. Exposes Amount, Frequency, and Speed controls bound to the MAT. Returns a summary plus a JSON block with the container path, created node paths, the material path, the output path (demo only), exposed controls, node errors, warnings, and (demo only) an inline preview image.

Parameter	Type	Required	Description
target_geo	string	no	Absolute path of an existing Geometry COMP to assign the displacement MAT to. Omit to build a self-contained demo (subdivided sphere + camera + light + render) so the material previews standalone.
texture_path	string	no	Absolute path of a TOP whose luminance drives the displacement instead of procedural noise. Omit to use built-in 3D noise.
amount	number	no	Displacement distance along each vertex normal (uAmount). 0 = undeformed. (default: 0.25)
frequency	number	no	Spatial frequency of the procedural noise (ignored when texture_path is set). (default: 2.5)
speed	number	no	Animation speed of the noise field (uTime scroll, cycles/s). 0 = static. Reads 0 when the TD timeline is paused. (default: 0.3)
demo_subdivisions	integer	no	Demo sphere mesh resolution (only used when target_geo is omitted). (default: 140)
demo_color	object[]	no	Demo surface tint (RGB 0..1); shaded by facing + displacement. Demo only. (default: 0.6,0.75,0.95)
expose_controls	boolean	no	When true (default), expose live Amount / Frequency / Speed controls bound to the MAT. (default: true)
parent_path	string	no	Parent network where the container (holding the MAT and, for the demo, the render chain) is created. (default: /project1)

controlled_disorder_grid mutates

Generate a rows×cols grid of quads (or outlined cells) with a single order↔chaos disorder knob: 0 = a perfect grid, 1 = full chaos. The one knob scales per-cell position, rotation, and scale jitter together — each hashed from the cell index in a single GLSL TOP so the pattern is stable and reproducible (the classic generative-design 'controlled randomness' / Schotter study, no external source). Set outline: true for line cells. Creates a new baseCOMP under parent_path. Exposes the live Disorder knob plus CellColor/Background swatches. Returns a summary plus a JSON block with node paths, exposed controls, node errors, warnings, and an inline preview image.

Parameter	Type	Required	Description
rows	integer	no	Number of grid rows (top to bottom). (default: 20)
cols	integer	no	Number of grid columns (left to right). (default: 20)
disorder	number	no	The single order↔chaos knob. 0 = a perfect grid; 1 = full chaos. Scales all per-cell position/rotation/scale jitter together. (default: 0.35)
pos_jitter	number	no	Max per-cell position offset at disorder=1 (fraction of a cell). (default: 0.5)
rot_jitter	number	no	Max per-cell rotation at disorder=1 (radians). (default: 1.2)
scale_jitter	number	no	Max per-cell scale variation at disorder=1 (fraction). (default: 0.3)
fill	number	no	Cell size within its slot (0..1); leaves gutters between cells. (default: 0.7)
outline	boolean	no	Draw outlined cells instead of filled quads (classic Schotter look). (default: false)
line_width	number	no	Outline thickness (fraction of a cell); used only when outline=true. (default: 0.04)
cell_color	string	no	Cell / line colour hex (e.g. '#f2f2f2'). Live RGB swatch 'CellColor'. (default: #f2f2f2)
background	string	no	Background colour hex. Live RGB swatch 'Background'. (default: #101014)
resolution	object[]	no	Output resolution [width, height] of the GLSL TOP (square suits a grid). (default: 1080,1080)
expose_controls	boolean	no	Expose the live Disorder knob (and CellColor/Background swatches). (default: true)
parent_path	string	no	Parent COMP path the self-contained 'disorder_grid' container is created inside. (default: /project1)

create_blob_trace mutates

Trace the contour/outline of a blob or silhouette into vector line art: source → monochrome → blur → threshold (the blob mask, optionally inverted) → optional Edge (boundary-band only) → Trace SOP (mask-to-polyline) → wireframe render. This is the CONTOUR-TRACE complement to create_vector_lines (full image vectoriser) and export_sop_to_svg, and is distinct from create_blob_reactive (which tracks blob position/reactivity — it does not draw the outline). Source can be the live camera (may prompt for macOS permission), a movie file, an animated synthetic blob (testable without a camera), or an existing TOP. Creates a new baseCOMP under parent_path. Exposes Threshold, Blur, and LineWidth controls. Returns a summary plus a JSON block with the container path, created node paths, output path, exposed controls, node errors, warnings, and an inline preview image.

Parameter	Type	Required	Description
source	camera | file | synthetic | existing_top	no	Blob source. 'camera' = live webcam (may prompt for macOS camera permission). 'file' = a movie file (movie_file_path). 'synthetic' = an animated noise blob so the trace is testable with no device (the default). 'existing_top' = trace a TOP you already have (existing_top_path). (default: synthetic)
movie_file_path	string	no	Path to a movie file to trace; used only when source='file'.
existing_top_path	string	no	Path of an existing TOP to trace; used only when source='existing_top'.
threshold	number	no	Luminance cutoff that separates blob (foreground) from background. Live 'Threshold'. (default: 0.45)
invert	boolean	no	Invert the mask so dark regions become the traced blob instead of bright ones. (default: false)
pre_blur	number	no	Gaussian blur (pixels) before thresholding — smooths noisy edges into clean contours. Live 'Blur'. (default: 4)
edge_only	boolean	no	Run an Edge TOP before tracing so only the blob's boundary band is traced (hollow outline). (default: false)
line_width	number	no	Contour line width for the wireframe material. (default: 2)
line_color	object[]	no	Contour line colour (RGB 0..1). (default: 0.1,1,0.6)
background	object[]	no	Background colour behind the traced contour (RGB 0..1). (default: 0.02,0.02,0.03)
resolution	object[]	no	Output resolution [width, height]. (default: 1280,720)
expose_controls	boolean	no	When true (default), expose live Threshold, Blur, and LineWidth controls. (default: true)
parent_path	string	no	Parent network where the blob-trace container is created (default '/project1'). (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.

focus_network_editor mutates

Pan/zoom TouchDesigner's Network Editor to frame the given operators — a 'follow' move so the artist sees what the agent just built instead of hunting for it. UI-only: it points a Network Editor pane at the operators' parent, selects them, and homes on the selection with zoom. Changes nothing in the project graph.

Parameter	Type	Required	Description
paths	string[]	yes	Operator paths to frame in the Network Editor, e.g. the nodes you just created.
animate	boolean	no	Let TouchDesigner animate the pan/zoom to the operators (a 'follow' move). (default: true)

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 connector into another node's input connector inside TouchDesigner, creating a single link between two existing nodes. Uses the bridge's batch endpoint when available and falls back to a Python connect otherwise. Use create_node_chain instead when you are creating several new nodes and want them auto-wired in sequence. Returns the source and target paths, the connector indices used, and which method made the connection.

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	Which output connector of the source node to wire from (0-based; default 0). (default: 0)
target_input	integer	no	Which input connector of the target node to wire into (0-based; default 0). (default: 0)

create_glsl_shader mutates

Create a GLSL TOP under parent_path that renders a custom fragment shader (and optional vertex shader). The shader source is placed in companion Text DATs (<name>_frag and, if given, <name>_vert) and wired to the GLSL TOP's pixel/vertex parameters; numeric uniforms are best-effort bound on the Vectors page and the output resolution is set. Returns the GLSL TOP path, the fragment/vertex DAT paths, and any warnings (e.g. sampler2D uniforms or uniform binds that need manual wiring).

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	Output resolution: '720p' (1280x720), '1080p' (1920x1080), '4K' (3840x2160), or 'input' (default — inherit from the input TOP). (default: input)

create_python_script destructive

Create one DAT under parent_path preloaded with your Python code. dat_type chooses a Text DAT (plain code), an Execute DAT (event hooks like onFrameStart), or a Script DAT (table builder); for a Script DAT the code is written to its auto-created companion callbacks DAT, since the Script DAT's own text is read-only. Returns the created DAT's path. This only stores code as a node; use execute_python_script instead to run Python immediately against the live project.

Parameter	Type	Required	Description
parent_path	string	yes	Parent COMP to create the DAT inside.
name	string	no	Name for the new DAT; auto-generated when omitted.
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 one empty COMP under parent_path to hold a visual system, then tile it into the parent's network grid clear of existing siblings. comp_type picks a Container COMP (a 2D panel) or a generic Base COMP. Returns the created node's path, type, and name. Use a higher-level Layer 1 tool instead when you want a fully built, wired network rather than an empty shell.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP to create the container in. (default: /project1)
name	string	no	Name for the new COMP; TouchDesigner auto-generates one when omitted.
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.

auto_ui_from_params mutates

Generate a performable control panel from an existing node/COMP's primitive parameters. It reads source_path, infers sliders/toggles/text fields, appends them as custom parameters on comp_path (default source_path), and optionally binds each control back to the source parameter. Use when a generated component has useful parameters but no playable UI yet.

Parameter	Type	Required	Description
source_path	string	yes	Node or COMP whose parameters should become controls.
comp_path	string	no	COMP that receives the generated control panel. Defaults to source_path.
page	string	no	Custom-parameter page name for the controls. (default: Auto UI)
parameters	string[]	no	Only expose these parameter names. Omit to infer useful primitive parameters.
exclude	string[]	no	Parameter names to skip. (default: ``)
max_controls	integer	no	Maximum inferred controls when parameters is omitted. (default: 12)
bind	boolean	no	Bind generated controls back to source_path parameters. (default: true)

create_companion_surface mutates

Build a companion performance surface for an existing node/COMP: infer useful primitive parameters, add bound custom parameters, create a playable fader/cue panel, and optionally append a read-only preflight report. Use after generating a component that needs a human-facing control surface without hand-wiring every parameter.

Parameter	Type	Required	Description
source_path	string	yes	Node or COMP whose useful parameters should be surfaced.
comp_path	string	no	COMP that receives the custom parameters and panel. Defaults to source_path.
name	string	no	Name of the playable panel container to build. (default: companion_surface)
page	string	no	Custom-parameter page added by the auto UI pass. (default: Companion)
parameters	string[]	no	Only expose these source parameter names. Omit to infer primitive controls.
exclude	string[]	no	Source parameter names to skip. (default: ``)
max_controls	integer	no	Maximum inferred controls when parameters is omitted. (default: 8)
include_faders	boolean	no	Build a playable fader/toggle surface for numeric inferred controls. (default: true)
cue_buttons	object[]	no	Optional cue buttons to add to the playable surface. (default: ``)
include_preflight	boolean	no	Append a read-only show_preflight_report result for the companion COMP. (default: true)
target_fps	number	no	Frame-rate target for preflight. (default: 60)
bind	boolean	no	Bind generated custom parameters back to source_path parameters. (default: true)

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 destructive

Build a reusable component library by moving COMPs to/from .tox files on disk. Two actions: 'save' writes the COMP at comp_path to file_path as a .tox (overwriting any existing file, optionally creating parent folders) and returns the saved path and byte size; 'load' reads file_path back into parent_path, either as an independent copy or a live-linked instance (via linked) that re-reads the file on change, returning the loaded node's path, type, and child names. Paths are on the machine running TouchDesigner. Marked destructive because 'save' can overwrite an existing file.

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)

add_custom_parameters mutates

Append a custom-parameter page (knobs, sliders, toggles, menus, pulses, RGB, XYZ) to a COMP so a generated network becomes a tunable, reusable component. Point comp_path at the COMP and list the params; an existing parameter is skipped (reported as a warning), not overwritten. Pair with scaffold_extension for behavior and manage_component to save the result as a .tox.

Parameter	Type	Required	Description
comp_path	string	yes	The COMP to add custom parameters to.
page	string	no	Custom-parameter page name (auto-capitalized; created if missing). (default: Custom)
params	object[]	yes	The parameters (knobs/menus/toggles/pulses) to append.

scaffold_extension mutates

Give a COMP a Python extension class: create a Text DAT holding the class (with optional method stubs), wire it into an extension slot, optionally promote it (so members are callable directly on the COMP), and reinitialize. The other half of making a generated network reusable — pair with add_custom_parameters (knobs) and manage_component (save as .tox).

Parameter	Type	Required	Description
comp_path	string	yes	The COMP to give a Python extension class.
class_name	string	yes	Extension class name, e.g. 'WidgetExt' (capitalized to a valid identifier; must already be identifier-safe).
methods	string[]	no	Optional method-name stubs to add to the class (each takes only self).
promote	boolean	no	Promote the extension so its members are callable directly on the COMP (op.Method()). (default: true)
slot	integer	no	Extension slot (1–8) — a COMP can hold several extensions. (default: 1)

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), NDI / Syphon-Spout video input, or NDI / Syphon-Spout video output (ndi_out / syphon_spout_out — pass source_path = the TOP to send and an optional source_name for the NDI source / Spout sender name; flip active to start immediately). On Windows, Spout needs an NVIDIA or AMD GPU (no Intel).
parent_path	string	no	COMP to create the I/O operator in. (default: /project1)
name	string	no	Name for the I/O operator; auto-generated when omitted.
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 / video_device_out / ndi_out / syphon_spout_out) the TOP to send. 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/ndi_out/syphon_spout_out) Start sending immediately. Defaults off so the artist can confirm the destination/sender name first.
source_name	string	no	(ndi_in/syphon_spout_in/ndi_out/syphon_spout_out) Name of the NDI source or Spout sender to receive or send, or (video_device_out) the SDI/capture-card output device name. For outputs, defaults to the operator name when omitted.

connect_companion_surface mutates

Build an OSC Companion-style button surface inside TouchDesigner: an OSC In CHOP listens for button addresses, each button gets a Select CHOP and Null CHOP row, optional target parameters are expression-bound, and an OSC Out CHOP is configured for feedback. A mapping table records label/address/target/mode/feedback for later editing.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP where the companion surface baseCOMP is created. (default: /project1)
name	string	no	Name of the Companion OSC surface baseCOMP. (default: companion_surface)
listen_port	integer	no	Local OSC port for Companion/button input. (default: 9000)
feedback_host	string	no	Remote host that receives outgoing OSC feedback. (default: 127.0.0.1)
feedback_port	integer	no	Remote OSC port that receives outgoing feedback. (default: 9001)
buttons	object[]	no	Button mappings to create as Select CHOP -> Null CHOP rows. (default: ``)
create_mapping_dat	boolean	no	Create/populate a tableDAT listing label, address, target, mode, and feedback. (default: true)

connect_obs_recorder mutates

Create a TouchDesigner-side OBS control scaffold with obs-websocket v5 request templates, status/setup DATs, and optional NDI or Syphon/Spout TOP publishing for OBS capture. The optional OBS password is passed only to the bridge payload and is redacted from all returned reports.

Parameter	Type	Required	Description
parent_path	string	no	COMP that will receive the OBS recorder control scaffold. (default: /project1)
name	string	no	Container name for the OBS scaffold. (default: obs_recorder)
obs_url	string	no	OBS obs-websocket URL. OBS 28+ includes obs-websocket by default. (default: ws://127.0.0.1:4455)
password	string	no	Optional OBS websocket password. Never echoed in returned reports.
scene_name	string	no	Optional OBS scene name for scene switch requests.
source_top_path	string	no	Optional TD TOP to publish to OBS through NDI or Syphon/Spout.
output_mode	ndi | syphon_spout | none	no	How to expose source_top_path for OBS capture. (default: ndi)
recording_profile	rehearsal | stream | archive	no	Operator-facing recording profile label stored in the scaffold status. (default: rehearsal)
active	boolean	no	Start websocket/sender operators active immediately. Defaults off for setup. (default: false)

create_touchosc_layout mutates

Create a TouchOSC-oriented OSC mapping surface and JSON manifest DAT. This intentionally does not claim to generate TouchOSC .tosc documents.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the TouchOSC surface. (default: /project1)
name	string	no	Generated baseCOMP name. (default: touchosc_layout)
receive_port	integer	no	(default: 8000)
send_host	string	no	(default: 127.0.0.1)
send_port	integer	no	(default: 9000)
page_name	string	no	(default: tdmcp)
controls	object[]	no	TouchOSC-style controls to expose as OSC mapping rows. (default: ``)
create_manifest_dat	boolean	no	(default: true)

create_voice_prompt_pipeline mutates

Create a dry-run/approval-gated voice-to-prompt TouchDesigner scaffold for AI Party-style workflows. It never dispatches raw hardware effects; policy and operator approval remain authoritative.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the pipeline. (default: /project1)
name	string	no	Generated baseCOMP name. (default: voice_prompt_pipeline)
audio_source	microphone | file | external_text	no	(default: microphone)
audio_file	string	no
stt_mode	external_websocket | file_drop | manual_text	no	(default: manual_text)
llm_target	ai_party | comfyui_prompt | streamdiffusion_prompt | text_only	no	(default: text_only)
approval_mode	dry_run | approval_required	no	(default: dry_run)
server_url	string	no	(default: ws://127.0.0.1:8770)
active	boolean	no	(default: false)

connect_touchengine_notch mutates

Create a TouchEngine/Notch bridge scaffold with stable output TOP, control channels, NDI/Syphon fallback modes, and explicit licensing/runtime warnings.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the bridge scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: touchengine_notch)
mode	touchengine | notch_top | ndi_fallback | syphon_spout_fallback	no	(default: touchengine)
tox_or_block_path	string	no	TouchEngine tox/block path or Notch block path.
input_top_path	string	no	Optional TOP to feed into the engine/fallback.
output_name	string	no	Stable output Null TOP name. (default: notch_out)
control_channels	string[]	no	Named control channels to scaffold. (default: ``)
active	boolean	no	Start engine/fallback active where supported. (default: false)

connect_resolume_arena mutates

Create a Resolume Arena/Avenue OSC control scaffold with command maps, status DATs, and preview handoff notes. Runtime validation against Resolume remains explicit.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the Resolume scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: resolume_arena)
resolume_host	string	no	Resolume OSC host. (default: 127.0.0.1)
send_port	integer	no	(default: 7000)
receive_port	integer	no	(default: 7001)
composition_name	string	no	Label stored in status metadata. (default: composition)
deck_count	integer	no	(default: 1)
layer_count	integer	no	(default: 3)
clip_count	integer	no	(default: 8)
preview_mode	none | ndi | syphon_spout	no	(default: none)
active	boolean	no	Activate OSC operators immediately. (default: false)

connect_madmapper_surface mutates

Create a MadMapper OSC surface/media control scaffold with source handoff notes for Syphon/Spout or NDI.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the MadMapper scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: madmapper_surface)
madmapper_host	string	no	MadMapper OSC host. (default: 127.0.0.1)
send_port	integer	no	(default: 8010)
receive_port	integer	no	(default: 8011)
surface_count	integer	no	(default: 4)
media_count	integer	no	(default: 4)
source_top_path	string	no	Optional TD TOP intended for projection handoff.
handoff_mode	none | syphon_spout | ndi	no	(default: syphon_spout)
active	boolean	no	(default: false)

create_mocap_stream_bridge mutates

Create a generic OptiTrack/Rokoko/Axis Studio/VRPN-style mocap bus scaffold with joint and rigid-body mapping surfaces.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the mocap scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: mocap_stream_bridge)
source_mode	osc | websocket_json | tcp_json | vrpn | sample	no	(default: osc)
receive_port	integer	no	(default: 9002)
server_url	string	no	(default: ws://127.0.0.1:9002)
skeleton_count	integer	no	(default: 1)
rigid_body_count	integer	no	(default: 0)
coordinate_space	y_up | z_up | touchdesigner	no	(default: touchdesigner)
active	boolean	no	(default: false)

create_blender_scene_bridge mutates

Create a Blender-to-TouchDesigner scene handoff scaffold for file-watch, OSC, or WebSocket metadata workflows.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the Blender bridge. (default: /project1)
name	string	no	Generated baseCOMP name. (default: blender_scene_bridge)
handoff_mode	file_watch | websocket_json | osc	no	(default: file_watch)
watch_folder	string	no	(default: ./blender_exports)
server_url	string	no	(default: ws://127.0.0.1:8765)
receive_port	integer	no	(default: 8765)
asset_format	gltf | alembic | fbx | obj	no	(default: gltf)
sync_camera	boolean	no	(default: true)
sync_lights	boolean	no	(default: false)
active	boolean	no	(default: false)

create_unreal_livelink_bridge mutates

Create an Unreal Engine Live Link/OSC/NDI handoff scaffold with subject maps, event queue, and runtime setup warnings.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the Unreal bridge. (default: /project1)
name	string	no	Generated baseCOMP name. (default: unreal_livelink_bridge)
mode	livelink_osc | udp_json | ndi_preview | manual	no	(default: livelink_osc)
unreal_host	string	no	(default: 127.0.0.1)
send_port	integer	no	(default: 9000)
receive_port	integer	no	(default: 9001)
subject_name	string	no	(default: tdmcp_camera)
sync_camera	boolean	no	(default: true)
sync_transform	boolean	no	(default: true)
preview_mode	none | ndi	no	(default: ndi)
active	boolean	no	(default: false)

create_vcv_rack_bridge mutates

Create a VCV Rack OSC/MIDI/CV modulation bridge scaffold with channel mapping and setup notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the VCV scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: vcv_rack_bridge)
mode	osc | midi | cv_audio | manual	no	(default: osc)
rack_host	string	no	(default: 127.0.0.1)
send_port	integer	no	(default: 12000)
receive_port	integer	no	(default: 12001)
midi_device	string	no
channel_count	integer	no	(default: 8)
bipolar	boolean	no	(default: true)
active	boolean	no	(default: false)

connect_qlab_cue_stack mutates

Create a QLab OSC cue-stack scaffold with cue command maps, status, and rehearsal-focused setup notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the QLab scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: qlab_cue_stack)
qlab_host	string	no	QLab OSC host. (default: 127.0.0.1)
send_port	integer	no	(default: 53000)
receive_port	integer	no	(default: 53001)
workspace_id	string	no	Optional QLab workspace identifier/label.
cue_count	integer	no	(default: 16)
include_transport	boolean	no	Include GO/STOP/PAUSE/RESUME rows. (default: true)
active	boolean	no	Activate OSC operators immediately. (default: false)

connect_lighting_console_osc mutates

Create a safety-gated OSC command scaffold for grandMA3, ETC Eos, ChamSys, Avolites, or generic lighting consoles without sending direct DMX.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the lighting-console OSC scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: lighting_console_osc)
console_family	grandma3 | etc_eos | chamsys | avolites | generic_osc	no	(default: generic_osc)
console_host	string	no	(default: 127.0.0.1)
send_port	integer	no	(default: 8000)
receive_port	integer	no	(default: 8001)
cue_count	integer	no	(default: 16)
executor_count	integer	no	(default: 8)
safety_mode	dry_run | approval_required	no	(default: dry_run)
active	boolean	no	(default: false)

connect_max_msp_bridge mutates

Create a Max/MSP OSC bridge scaffold with parameter and audio-feature channel maps.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the Max/MSP scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: max_msp_bridge)
max_host	string	no	Max/MSP OSC host. (default: 127.0.0.1)
send_port	integer	no	(default: 7400)
receive_port	integer	no	(default: 7401)
namespace	string	no	OSC namespace prefix. (default: /tdmcp)
channel_count	integer	no	(default: 8)
include_audio_features	boolean	no	(default: true)
active	boolean	no	(default: false)

create_openxr_controller_bridge mutates

Create an OpenXR/SteamVR controller input scaffold for pose, trigger, grip, thumbstick, and button streams supplied by an external adapter.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the OpenXR scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: openxr_controller_bridge)
source_mode	osc | websocket_json | manual	no	(default: osc)
receive_port	integer	no	(default: 9050)
server_url	string	no	(default: ws://127.0.0.1:9050)
controller_count	integer	no	(default: 2)
coordinate_space	openxr | steamvr | touchdesigner	no	(default: touchdesigner)
active	boolean	no	(default: false)

connect_vmix_production mutates

Create a vMix HTTP/API production-control scaffold for input switching, overlays, recording, and streaming command templates.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the vMix scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: vmix_production)
vmix_host	string	no	(default: 127.0.0.1)
api_port	integer	no	(default: 8088)
input_count	integer	no	(default: 8)
overlay_count	integer	no	(default: 4)
include_record_stream	boolean	no	(default: true)
active	boolean	no	(default: false)

connect_casparcg_server mutates

Create a CasparCG AMCP/playout scaffold with channel/layer command templates and media manifest notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the CasparCG scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: casparcg_server)
caspar_host	string	no	(default: 127.0.0.1)
amcp_port	integer	no	(default: 5250)
channel_count	integer	no	(default: 1)
layer_count	integer	no	(default: 4)
media_root_hint	string	no	(default: media/)
active	boolean	no	(default: false)

connect_millumin_show mutates

Create a Millumin OSC layer, column, and dashboard control scaffold with command maps and setup notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the Millumin scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: millumin_show)
millumin_host	string	no	Millumin OSC host. (default: 127.0.0.1)
send_port	integer	no	(default: 5000)
receive_port	integer	no	(default: 5001)
layer_count	integer	no	(default: 4)
column_count	integer	no	(default: 8)
dashboard_page	string	no	(default: main)
active	boolean	no	(default: false)

connect_isadora_patch mutates

Create an Isadora OSC actor, watcher, and scene exchange scaffold with stable namespace mapping.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the Isadora scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: isadora_patch)
isadora_host	string	no	(default: 127.0.0.1)
send_port	integer	no	(default: 1234)
receive_port	integer	no	(default: 1235)
namespace	string	no	(default: /tdmcp)
scene_count	integer	no	(default: 4)
actor_count	integer	no	(default: 8)
watcher_count	integer	no	(default: 4)
active	boolean	no	(default: false)

connect_unity_osc_bridge mutates

Create a Unity OSC and preview handoff scaffold for object transforms, events, and NDI/Syphon notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the Unity bridge. (default: /project1)
name	string	no	Generated baseCOMP name. (default: unity_osc_bridge)
unity_host	string	no	(default: 127.0.0.1)
send_port	integer	no	(default: 9000)
receive_port	integer	no	(default: 9001)
namespace	string	no	(default: /tdmcp)
object_count	integer	no	(default: 8)
event_count	integer	no	(default: 8)
preview_mode	none | ndi | syphon_spout	no	(default: none)
active	boolean	no	(default: false)

connect_reaper_transport mutates

Create a REAPER OSC transport, track, and marker bridge scaffold with operator-approved recording templates.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the REAPER scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: reaper_transport)
reaper_host	string	no	(default: 127.0.0.1)
send_port	integer	no	(default: 8000)
receive_port	integer	no	(default: 9000)
project_name	string	no	(default: show)
track_count	integer	no	(default: 8)
marker_count	integer	no	(default: 8)
include_record	boolean	no	(default: false)
active	boolean	no	(default: false)

create_ndi_router_matrix mutates

Create a stable NDI source/output routing matrix scaffold without claiming live NDI discovery.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the NDI matrix. (default: /project1)
name	string	no	Generated baseCOMP name. (default: ndi_router_matrix)
source_count	integer	no	(default: 8)
output_count	integer	no	(default: 4)
include_preview	boolean	no	(default: true)
active	boolean	no	(default: false)

connect_webrtc_browser_input mutates

Create a browser/WebRTC input scaffold for webcam, screen, pointer, and sensor data supplied by an external signaling app.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the WebRTC scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: webrtc_browser_input)
signaling_url	string	no	(default: ws://127.0.0.1:8787)
room_id	string	no	(default: tdmcp)
input_mode	webcam | screen | pointer | sensors | mixed	no	(default: mixed)
include_data_channels	boolean	no	(default: true)
active	boolean	no	(default: false)

connect_spout_syphon_router mutates

Create a platform-gated Syphon/Spout texture-sharing router scaffold with route maps and explicit setup notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the router scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: spout_syphon_router)
mode	receive | send | roundtrip	no	(default: roundtrip)
source_name	string	no	Syphon/Spout sender to receive. (default: tdmcp_source)
output_name	string	no	Syphon/Spout sender name to publish. (default: tdmcp_output)
route_count	integer	no	(default: 4)
active	boolean	no	(default: false)

connect_blackmagic_atem mutates

Create a Blackmagic ATEM command-map scaffold with UDP transport placeholders, input maps, macro maps, and operator approval notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the ATEM scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: blackmagic_atem)
atem_host	string	no	Blackmagic ATEM switcher host. (default: 192.168.10.240)
send_port	integer	no	(default: 9910)
receive_port	integer	no	(default: 9911)
input_count	integer	no	(default: 8)
macro_count	integer	no	(default: 8)
include_cut_auto	boolean	no	(default: true)
active	boolean	no	(default: false)

connect_oscquery_namespace mutates

Create an OSCQuery HTTP namespace and OSC send/receive scaffold with action maps for live-control apps.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the OSCQuery scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: oscquery_namespace)
service_host	string	no	OSCQuery HTTP service host. (default: 127.0.0.1)
http_port	integer	no	(default: 5678)
osc_send_port	integer	no	(default: 9000)
osc_receive_port	integer	no	(default: 9001)
namespace_root	string	no	OSCQuery namespace root path. (default: /)
action_count	integer	no	(default: 8)
active	boolean	no	(default: false)

connect_mqtt_iot_bus mutates

Create an MQTT Client DAT bus scaffold for IoT sensors, installation telemetry, and policy-gated operator commands.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the MQTT scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: mqtt_iot_bus)
broker_host	string	no	MQTT broker host. (default: 127.0.0.1)
broker_port	integer	no	(default: 1883)
topic_root	string	no	Root MQTT topic for show data. (default: tdmcp/show)
topic_count	integer	no	(default: 8)
client_id	string	no	(default: tdmcp_touchdesigner)
qos	integer	no	(default: 0)
active	boolean	no	(default: false)

create_depthai_oak_pipeline mutates

Create a DepthAI/OAK camera scaffold with OAK Device, OAK Select TOP/CHOP placeholders, stream maps, and hardware-gated setup notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the OAK scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: depthai_oak_pipeline)
device_name	string	no	(default: oak)
stream_count	integer	no	(default: 3)
include_depth	boolean	no	(default: true)
include_tracking	boolean	no	(default: true)
active	boolean	no	(default: false)

connect_arkit_face_capture mutates

Create an ARKit Face Capture OSC scaffold with blendshape and head-transform maps for iPhone-driven facial performance.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the ARKit scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: arkit_face_capture)
receive_port	integer	no	(default: 11111)
face_count	integer	no	(default: 1)
blendshape_count	integer	no	(default: 52)
include_head_transform	boolean	no	(default: true)
active	boolean	no	(default: false)

connect_pangolin_beyond mutates

Create a safety-gated Pangolin Beyond laser-control scaffold with zone maps, cue maps, blackout notes, and no live-output claim.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the Pangolin scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: pangolin_beyond)
source_mode	sop | chop	no	(default: chop)
zone	string	no	(default: zone_1)
zone_count	integer	no	(default: 4)
cue_count	integer	no	(default: 8)
output_rate	number	no	(default: 30)
safety_blackout	boolean	no	(default: true)
active	boolean	no	(default: false)

create_hokuyo_lidar_bus mutates

Create a Hokuyo LiDAR scanner scaffold with hardware-gated CHOP setup, scan-zone maps, and calibration notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the Hokuyo scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: hokuyo_lidar_bus)
interface_mode	network | serial	no	(default: network)
net_address	string	no	(default: 192.168.0.10)
serial_port	string	no	(default: COM3)
scan_zones	integer	no	(default: 8)
start_step	integer	no	(default: 0)
end_step	integer	no	(default: 1080)
high_sensitivity	boolean	no	(default: false)
active	boolean	no	(default: false)

connect_supercollider_synth mutates

Create a SuperCollider OSC synth/bus bridge scaffold with explicit port maps and no code-evaluation behavior.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: supercollider_synth)
sc_host	string	no	(default: 127.0.0.1)
send_port	integer	no	(default: 57120)
receive_port	integer	no	(default: 57121)
synth_count	integer	no	(default: 4)
bus_count	integer	no	(default: 8)
active	boolean	no	(default: false)

connect_ableton_link_session mutates

Create an Ableton Link timing scaffold with beat/bar maps for tempo-locked visual systems.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the Link scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: ableton_link_session)
tempo_hint	number	no	(default: 120)
signature	integer	no	(default: 4)
export_bars	integer	no	(default: 8)
start_stop_sync	boolean	no	(default: false)
active	boolean	no	(default: false)

create_decklink_io_router mutates

Create a Blackmagic DeckLink video-device input/output router scaffold with route maps and hardware-gated safety notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the router scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: decklink_io_router)
input_device	string	no	(default: Blackmagic)
output_device	string	no	(default: Blackmagic)
signal_format	string	no	(default: 1080p5994)
route_count	integer	no	(default: 2)
active	boolean	no	(default: false)

connect_midi_mpe_controller mutates

Create an expressive MIDI MPE input/output scaffold with zone and expression maps for pressure, timbre, pitch bend, and note channels.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the MPE scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: midi_mpe_controller)
device_name	string	no	(default: MPE Controller)
lower_zone_channels	integer	no	(default: 15)
include_output	boolean	no	(default: false)
expression_count	integer	no	(default: 5)
active	boolean	no	(default: false)

connect_tidalcycles_livecoding mutates

Create a TidalCycles/SuperDirt OSC scaffold with pattern and orbit maps for live-coded audiovisual sets.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the Tidal scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: tidalcycles_livecoding)
tidal_host	string	no	TidalCycles/SuperDirt OSC host. (default: 127.0.0.1)
send_port	integer	no	(default: 57120)
receive_port	integer	no	(default: 6010)
orbit_count	integer	no	(default: 4)
pattern_count	integer	no	(default: 8)
active	boolean	no	(default: false)

connect_vdmx_workspace mutates

Create a VDMX OSC/Syphon workspace scaffold with layer, clip, preview, and setup maps.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the VDMX scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: vdmx_workspace)
vdmx_host	string	no	(default: 127.0.0.1)
send_port	integer	no	(default: 12345)
receive_port	integer	no	(default: 12346)
layer_count	integer	no	(default: 4)
clip_count	integer	no	(default: 16)
preview_mode	none | syphon_spout | ndi	no	(default: syphon_spout)
active	boolean	no	(default: false)

connect_disguise_stage mutates

Create a disguise/d3 HTTP and OSC show-control scaffold with timeline, layer, and approval maps.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the disguise scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: disguise_stage)
api_host	string	no	(default: 127.0.0.1)
api_port	integer	no	(default: 8080)
osc_port	integer	no	(default: 7400)
timeline_count	integer	no	(default: 4)
layer_count	integer	no	(default: 8)
active	boolean	no	(default: false)

create_azure_kinect_body_bus mutates

Create an Azure Kinect body/depth scaffold with Kinect Azure TOP/CHOP placeholders, stream maps, and calibration notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the Azure Kinect scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: azure_kinect_body_bus)
device_index	integer	no	(default: 0)
body_count	integer	no	(default: 2)
include_depth_top	boolean	no	(default: true)
include_color_top	boolean	no	(default: true)
active	boolean	no	(default: false)

create_zed_depth_bus mutates

Create a ZED camera depth/body/point-cloud scaffold with ZED TOP/CHOP/SOP placeholders and runtime-gated warnings.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the ZED scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: zed_depth_bus)
camera_index	integer	no	(default: 0)
stream_count	integer	no	(default: 3)
body_count	integer	no	(default: 1)
include_pointcloud	boolean	no	(default: true)
active	boolean	no	(default: false)

create_leap_motion_hand_bus mutates

Create a Leap Motion hand/gesture scaffold with CHOP/TOP placeholders, hand maps, gesture maps, and setup notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the Leap Motion scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: leap_motion_hand_bus)
hand_count	integer	no	(default: 2)
gesture_count	integer	no	(default: 6)
include_image_top	boolean	no	(default: false)
active	boolean	no	(default: false)

create_blacktrax_tracking_bus mutates

Create a BlackTrax tracking scaffold with receiver, trackable maps, zone maps, and calibration notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the BlackTrax scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: blacktrax_tracking_bus)
port	integer	no	(default: 24002)
trackable_count	integer	no	(default: 8)
zone_count	integer	no	(default: 4)
active	boolean	no	(default: false)

create_ncam_camera_tracking_bus mutates

Create an NCAM camera-tracking scaffold with pose, lens, video-preview, and calibration maps.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the NCAM scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: ncam_camera_tracking_bus)
port	integer	no	(default: 3880)
camera_count	integer	no	(default: 1)
lens_profile_count	integer	no	(default: 4)
include_video_top	boolean	no	(default: true)
active	boolean	no	(default: false)

create_ouster_lidar_bus mutates

Create an Ouster LiDAR scaffold with Ouster TOP, range selection, zone maps, and calibration notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the Ouster LiDAR scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: ouster_lidar_bus)
device_address	string	no	(default: 192.168.1.1)
lidar_port	integer	no	(default: 7502)
imu_port	integer	no	(default: 7503)
ring_count	integer	no	(default: 64)
zone_count	integer	no	(default: 6)
active	boolean	no	(default: false)

connect_tuio_touch_surface mutates

Create a TUIO touch-surface scaffold with TUIO DAT, optional raw OSC, cursor maps, and surface maps.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the TUIO surface scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: tuio_touch_surface)
listen_port	integer	no	(default: 3333)
surface_count	integer	no	(default: 2)
cursor_count	integer	no	(default: 10)
include_raw_osc	boolean	no	(default: true)
active	boolean	no	(default: false)

create_multitouch_panel_bus mutates

Create a Windows Multi Touch In DAT scaffold with panel maps, touch-slot maps, and platform notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the Multi Touch panel scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: multitouch_panel_bus)
panel_count	integer	no	(default: 4)
max_touches	integer	no	(default: 10)
mouse_as_touch	boolean	no	(default: false)
active	boolean	no	(default: false)

create_ltc_timecode_bridge mutates

Create an LTC receive/generate scaffold with LTC In/Out CHOP placeholders, cue maps, and routing notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the LTC timecode scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: ltc_timecode_bridge)
mode	receive | generate | receive_and_generate	no	(default: receive)
frame_rate	24 | 25 | 30 | 50 | 60 | 23.976 | …	no	(default: 30)
input_device	integer	no	(default: 0)
output_device	integer	no	(default: 0)
cue_count	integer	no	(default: 8)
active	boolean	no	(default: false)

create_optitrack_tracking_bus mutates

Create an OptiTrack/NatNet tracking scaffold with receiver, rigid-body maps, marker maps, and calibration notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the OptiTrack scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: optitrack_tracking_bus)
server_address	string	no	(default: 127.0.0.1)
command_port	integer	no	(default: 1510)
data_port	integer	no	(default: 1511)
rigid_body_count	integer	no	(default: 4)
marker_count	integer	no	(default: 16)
active	boolean	no	(default: false)

connect_video_stream_receiver mutates

Create a Video Stream In TOP scaffold for RTSP, HLS, SRT, or WebRTC ingest with stream maps and setup notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the Video Stream In scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: video_stream_receiver)
url	string	no	(default: rtsp://127.0.0.1:8554/live)
mode	rtsp | hls | srt | webrtc	no	(default: rtsp)
latency_ms	integer	no	(default: 250)
active	boolean	no	(default: false)

connect_websocket_control_bus mutates

Create a WebSocket DAT scaffold with command maps, message schema hints, status, and safety notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the WebSocket control scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: websocket_control_bus)
net_address	string	no	(default: 127.0.0.1)
port	integer	no	(default: 8080)
path	string	no	(default: /)
tls	boolean	no	(default: false)
command_count	integer	no	(default: 8)
active	boolean	no	(default: false)

connect_serial_device_bus mutates

Create a Serial DAT/CHOP scaffold for microcontrollers, sensors, and show-control devices with parse maps.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the serial device scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: serial_device_bus)
device	string	no	(default: COM1)
baud_rate	integer	no	(default: 115200)
message_count	integer	no	(default: 6)
include_chop	boolean	no	(default: true)
active	boolean	no	(default: false)

connect_udp_telemetry_bridge mutates

Create a UDP In/Out DAT scaffold for telemetry packets, replies, status maps, and diagnostics.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the UDP telemetry scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: udp_telemetry_bridge)
listen_port	integer	no	(default: 9000)
remote_address	string	no	(default: 127.0.0.1)
remote_port	integer	no	(default: 9001)
packet_count	integer	no	(default: 8)
active	boolean	no	(default: false)

create_artnet_discovery_panel mutates

Create an Art-Net DAT discovery scaffold with optional DMX In monitor, device maps, and universe maps.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the Art-Net discovery scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: artnet_discovery_panel)
net	integer	no	(default: 0)
subnet	integer	no	(default: 0)
universe_count	integer	no	(default: 4)
device_count	integer	no	(default: 8)
include_dmx_monitor	boolean	no	(default: true)
active	boolean	no	(default: false)

create_mpcdi_projection_mapper mutates

Create an MPCDI projection-calibration scaffold with MPCDI TOP/DAT, projector maps, region maps, and setup notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the MPCDI projection mapper scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: mpcdi_projection_mapper)
config_file	string	no	Path to the MPCDI calibration/config file. (default: ``)
projector_count	integer	no	(default: 2)
region_count	integer	no	(default: 4)
active	boolean	no	(default: false)

create_vioso_warp_panel mutates

Create a VIOSO projection-warp scaffold with VIOSO TOP, blend-zone maps, projector metadata, and setup notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the VIOSO warp scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: vioso_warp_panel)
config_file	string	no	Path to the VIOSO calibration/config file. (default: ``)
projector_index	integer	no	(default: 0)
blend_zone_count	integer	no	(default: 4)
active	boolean	no	(default: false)

create_direct_display_output mutates

Create a Direct Display Out TOP scaffold with monitor inventory, display maps, and inactive-by-default safety notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the Direct Display output scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: direct_display_output)
display_index	integer	no	(default: 0)
output_count	integer	no	(default: 1)
resolution_width	integer	no	(default: 1920)
resolution_height	integer	no	(default: 1080)
active	boolean	no	(default: false)

create_scalable_display_bus mutates

Create a Scalable Display TOP scaffold with display tile maps, status, and calibration setup notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the Scalable Display scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: scalable_display_bus)
config_file	string	no	Path to the Scalable Display configuration file. (default: ``)
display_count	integer	no	(default: 2)
canvas_width	integer	no	(default: 3840)
canvas_height	integer	no	(default: 1080)
active	boolean	no	(default: false)

create_window_output_matrix mutates

Create a Window COMP output matrix scaffold with window maps, source maps, status, and setup notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the Window output matrix scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: window_output_matrix)
window_count	integer	no	(default: 2)
resolution_width	integer	no	(default: 1920)
resolution_height	integer	no	(default: 1080)
perform_mode	boolean	no	(default: false)
active	boolean	no	(default: false)

create_monitor_layout_panel mutates

Create a Monitors DAT inventory scaffold with monitor maps, GPU maps, preflight checks, and setup notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the monitor layout scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: monitor_layout_panel)
monitor_count	integer	no	(default: 2)
gpu_count	integer	no	(default: 1)
include_direct_display_hint	boolean	no	(default: true)

create_realsense_depth_bus mutates

Create an Intel RealSense depth-camera scaffold with RealSense TOP, NDI, WebSocket adapter, or sample-source modes plus depth/color/point-cloud routing notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the RealSense depth scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: realsense_depth_bus)
source_mode	realsense_top | ndi_depth | websocket_json | sample	no	(default: realsense_top)
serial_number	string	no	Optional RealSense camera serial number. (default: ``)
ndi_source	string	no	NDI source name for depth input. (default: RealSense Depth)
server_url	string	no	Adapter WebSocket URL. (default: ws://127.0.0.1:9015)
resolution	640x480 | 848x480 | 1280x720	no	(default: 848x480)
include_color	boolean	no	(default: true)
include_pointcloud	boolean	no	(default: true)
active	boolean	no	(default: false)

create_livox_lidar_bus mutates

Create a Livox LiDAR adapter scaffold with UDP/WebSocket/file-replay ingest, point-stream schema, zone maps, and calibration notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the Livox scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: livox_lidar_bus)
adapter_mode	udp_json | websocket_json | file_replay	no	(default: udp_json)
device_address	string	no	Livox device or adapter host. (default: 192.168.1.50)
receive_port	integer	no	(default: 56000)
server_url	string	no	(default: ws://127.0.0.1:56000)
point_rate_hint	integer	no	(default: 240000)
zone_count	integer	no	(default: 8)
active	boolean	no	(default: false)

connect_xsens_mvn_mocap mutates

Create an Xsens MVN mocap scaffold with OSC/UDP/TCP ingest, actor/segment mapping, normalized skeleton tables, and coordinate-space notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the Xsens scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: xsens_mvn_mocap)
source_mode	mvn_osc | mvn_udp_json | mvn_tcp_json | sample	no	(default: mvn_osc)
receive_port	integer	no	(default: 9763)
server_host	string	no	(default: 127.0.0.1)
actor_count	integer	no	(default: 1)
segment_count	integer	no	(default: 23)
coordinate_space	mvn_y_up | z_up | touchdesigner	no	(default: mvn_y_up)
active	boolean	no	(default: false)

connect_houdini_engine_bridge mutates

Create a Houdini Engine/HDA/cache handoff scaffold with HDA manifests, parameter maps, cook-status ingest, and geometry cache notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the Houdini bridge. (default: /project1)
name	string	no	Generated baseCOMP name. (default: houdini_engine_bridge)
handoff_mode	file_watch | hda_parameters | websocket_json | udp_cook_status	no	(default: file_watch)
hda_file	string	no	(default: ./houdini/show_asset.hda)
cache_folder	string	no	(default: ./houdini/cache)
server_url	string	no	(default: ws://127.0.0.1:9876)
receive_port	integer	no	(default: 9876)
asset_format	bgeo | usd | alembic | obj	no	(default: bgeo)
parameter_count	integer	no	(default: 12)
active	boolean	no	(default: false)

connect_omniverse_usd_bridge mutates

Create an NVIDIA Omniverse/USD stage sync scaffold with Nucleus/stage metadata, layer maps, variant maps, and live-session notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the USD bridge. (default: /project1)
name	string	no	Generated baseCOMP name. (default: omniverse_usd_bridge)
nucleus_url	string	no	(default: omniverse://localhost/Projects/show)
stage_path	string	no	(default: ./usd/show_stage.usd)
sync_mode	usd_file_watch | nucleus_live | websocket_json | manual_export	no	(default: usd_file_watch)
server_url	string	no	(default: ws://127.0.0.1:8899)
layer_count	integer	no	(default: 4)
variant_count	integer	no	(default: 3)
active	boolean	no	(default: false)

connect_opcua_industrial_bus mutates

Create an OPC UA industrial telemetry scaffold with node maps, adapter ingest options, status tables, and read-only safety-policy notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the OPC UA scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: opcua_industrial_bus)
endpoint_url	string	no	(default: opc.tcp://127.0.0.1:4840)
adapter_http_url	string	no	(default: http://127.0.0.1:9084/opcua)
adapter_ws_url	string	no	(default: ws://127.0.0.1:9084/opcua)
adapter_udp_port	integer	no	(default: 9084)
namespace_index	integer	no	(default: 2)
node_count	integer	no	(default: 12)
poll_ms	integer	no	(default: 250)
adapter_mode	webclient_json | websocket_json | udp_json | manual	no	(default: manual)
security_policy	none | basic256sha256 | external_adapter	no	(default: external_adapter)
active	boolean	no	(default: false)

connect_replicate_prediction_bridge mutates

Create a Replicate-style prediction handoff scaffold with request templates, polling/webhook maps, output contracts, and credential-safety notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the Replicate scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: replicate_prediction_bridge)
endpoint_url	string	no	Prediction endpoint or local adapter URL. (default: https://api.replicate.com/v1/predictions)
model_ref	string	no	Model/version reference hint. (default: owner/model:version)
request_mode	webclient_json | webhook_adapter | manual	no	(default: webclient_json)
webhook_url	string	no	Optional webhook callback URL or adapter route. (default: ``)
poll_seconds	number	no	(default: 2)
output_mode	image | video | json	no	(default: image)
active	boolean	no	(default: false)

connect_a1111_webui_bridge mutates

Create an AUTOMATIC1111/Forge Stable Diffusion WebUI handoff scaffold with prompt slots, result maps, ControlNet hints, and adapter notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the WebUI scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: a1111_webui_bridge)
server_url	string	no	WebUI or adapter base URL. (default: http://127.0.0.1:7860)
endpoint_kind	txt2img | img2img | extras | controlnet	no	(default: txt2img)
output_folder	string	no	(default: ./generated/a1111)
prompt_slot_count	integer	no	(default: 6)
include_controlnet	boolean	no	(default: false)
active	boolean	no	(default: false)

connect_huggingface_inference_bridge mutates

Create a Hugging Face Inference Endpoint scaffold with task input maps, output contracts, token-env hints, and adapter notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the Hugging Face scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: huggingface_inference_bridge)
endpoint_url	string	no	(default: https://api-inference.huggingface.co/models/model-id)
task	text_to_image | image_to_image | audio_to_text | text_generation | embeddings	no	(default: text_to_image)
token_env_name	string	no	(default: HF_TOKEN)
input_slot_count	integer	no	(default: 4)
output_mode	image | audio | text | json	no	(default: image)
active	boolean	no	(default: false)

connect_whisper_transcription_bus mutates

Create a Whisper-compatible transcription scaffold with audio/file/chunk ingest, segment maps, status tables, and privacy notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the Whisper scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: whisper_transcription_bus)
source_mode	audio_file | audio_device | websocket_chunks | manual_drop	no	(default: audio_file)
audio_file	string	no	(default: ``)
server_url	string	no	(default: ws://127.0.0.1:9030)
language_hint	string	no	(default: auto)
segment_count	integer	no	(default: 12)
active	boolean	no	(default: false)

connect_rvc_voice_conversion_bus mutates

Create an RVC-style voice conversion scaffold with source audio, model maps, output contracts, latency notes, and consent warnings.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the RVC scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: rvc_voice_conversion_bus)
source_mode	audio_file | audio_device | websocket_chunks | manual	no	(default: audio_file)
audio_file	string	no	(default: ``)
model_path	string	no	(default: ./models/rvc/voice.pth)
index_path	string	no	(default: ./models/rvc/voice.index)
server_url	string	no	(default: ws://127.0.0.1:9040)
request_url	string	no	(default: http://127.0.0.1:9040/convert)
speaker_count	integer	no	(default: 4)
transpose_semitones	number	no	(default: 0)
active	boolean	no	(default: false)

connect_runway_video_bridge mutates

Create a Runway-style video generation handoff scaffold with prompt maps, input/result contracts, polling status, and adapter notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the Runway scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: runway_video_bridge)
endpoint_url	string	no	(default: https://api.runway.example/v1/jobs)
project_id	string	no	(default: show_project)
generation_mode	text_to_video | image_to_video | video_to_video | manual_export	no	(default: text_to_video)
input_clip_path	string	no	(default: ``)
output_folder	string	no	(default: ./generated/runway)
prompt_count	integer	no	(default: 4)
active	boolean	no	(default: false)

connect_kafka_event_bus mutates

Create a Kafka/Redpanda event-bus scaffold with adapter ingest, topic maps, schema hints, consumer group metadata, and policy-gated producer notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the Kafka scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: kafka_event_bus)
broker	string	no	Kafka/Redpanda broker hint. (default: 127.0.0.1:9092)
adapter_mode	websocket_json | udp_json | manual	no	(default: websocket_json)
server_url	string	no	External adapter URL. (default: ws://127.0.0.1:9050)
topic_root	string	no	Topic prefix for show events. (default: tdmcp.show)
topic_count	integer	no	(default: 8)
consumer_group	string	no	(default: tdmcp-touchdesigner)
schema_format	json | avro | protobuf	no	(default: json)
active	boolean	no	(default: false)

connect_redis_pubsub_bus mutates

Create a Redis Pub/Sub/Streams scaffold with adapter ingest, channel maps, keyspace safety notes, and read-first operations policy.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the Redis scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: redis_pubsub_bus)
redis_host	string	no	(default: 127.0.0.1)
redis_port	integer	no	(default: 6379)
adapter_mode	websocket_json | udp_json | manual	no	(default: websocket_json)
server_url	string	no	(default: ws://127.0.0.1:9051)
adapter_port	integer	no	(default: 9051)
channel_root	string	no	(default: tdmcp:show)
channel_count	integer	no	(default: 8)
database_index	integer	no	(default: 0)
stream_mode	pubsub | streams | both	no	(default: pubsub)
active	boolean	no	(default: false)

connect_influxdb_timeseries_bridge mutates

Create an InfluxDB telemetry scaffold with measurement maps, field maps, query/write adapter notes, and token-safety warnings.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the InfluxDB scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: influxdb_timeseries_bridge)
endpoint_url	string	no	(default: http://127.0.0.1:8086)
bucket	string	no	(default: show)
org	string	no	(default: tdmcp)
adapter_mode	webclient_json | websocket_json | manual	no	(default: webclient_json)
measurement_count	integer	no	(default: 6)
field_count	integer	no	(default: 8)
poll_seconds	number	no	(default: 5)
active	boolean	no	(default: false)

connect_prometheus_metrics_panel mutates

Create a Prometheus metrics scaffold with PromQL/client adapter notes, metric maps, alert routes, and operator-dashboard safety guidance.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the Prometheus scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: prometheus_metrics_panel)
endpoint_url	string	no	(default: http://127.0.0.1:9090)
job_name	string	no	(default: tdmcp-show)
adapter_mode	webclient_promql | websocket_json | manual	no	(default: webclient_promql)
metric_count	integer	no	(default: 12)
alert_count	integer	no	(default: 4)
scrape_interval_seconds	number	no	(default: 15)
active	boolean	no	(default: false)

connect_grafana_annotation_bridge mutates

Create a Grafana annotation/event-marker scaffold with dashboard, panel, tag, and annotation maps plus token-safety notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the Grafana scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: grafana_annotation_bridge)
base_url	string	no	(default: http://127.0.0.1:3000)
dashboard_uid	string	no	(default: show-dashboard)
adapter_mode	webclient_json | websocket_json | manual	no	(default: webclient_json)
panel_count	integer	no	(default: 6)
tag_count	integer	no	(default: 4)
active	boolean	no	(default: false)

connect_homeassistant_state_bus mutates

Create a Home Assistant state/service scaffold with REST/WebSocket adapter nodes, entity maps, service maps, and physical-action safety notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the Home Assistant scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: homeassistant_state_bus)
base_url	string	no	(default: http://homeassistant.local:8123)
adapter_mode	rest_json | websocket_json | manual	no	(default: websocket_json)
entity_domain	sensor | light | switch | media_player | climate	no	(default: sensor)
entity_count	integer	no	(default: 12)
service_count	integer	no	(default: 4)
area_count	integer	no	(default: 3)
active	boolean	no	(default: false)

connect_google_sheets_cue_table mutates

Create a Google Sheets cue-table scaffold with source adapter, cue rows, column validation, sync policy, and OAuth/writeback safety notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the Google Sheets cue-table scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: google_sheets_cue_table)
sheet_url	string	no	(default: https://docs.google.com/spreadsheets/d/show-cues)
worksheet_name	string	no	(default: cues)
adapter_mode	csv_export | webhook_json | manual	no	(default: csv_export)
adapter_url	string	no	(default: ws://127.0.0.1:9060)
cue_count	integer	no	(default: 16)
column_count	integer	no	(default: 8)
sync_direction	read_only | read_write_requests	no	(default: read_only)
active	boolean	no	(default: false)

connect_airtable_content_bus mutates

Create an Airtable content scaffold with record maps, field maps, sync policy, adapter source, and token/rate-limit safety notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the Airtable content-bus scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: airtable_content_bus)
base_id	string	no	(default: app_show_base)
table_name	string	no	(default: Show Content)
view_name	string	no	(default: Approved)
adapter_mode	rest_json | webhook_json | manual	no	(default: rest_json)
adapter_url	string	no	(default: http://127.0.0.1:9061/airtable)
record_count	integer	no	(default: 24)
field_count	integer	no	(default: 8)
sync_direction	read_only | approved_updates	no	(default: read_only)
active	boolean	no	(default: false)

connect_notion_show_rundown mutates

Create a Notion show-rundown scaffold with scene maps, property maps, approval policy, adapter source, and token-safety notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the Notion rundown scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: notion_show_rundown)
database_id	string	no	(default: notion_show_database)
rundown_label	string	no	(default: main_show)
adapter_mode	rest_json | webhook_json | manual	no	(default: rest_json)
adapter_url	string	no	(default: http://127.0.0.1:9062/notion)
scene_count	integer	no	(default: 12)
property_count	integer	no	(default: 8)
approval_required	boolean	no	(default: true)
active	boolean	no	(default: false)

connect_figma_design_tokens mutates

Create a Figma design-token scaffold with token rows, component-review rows, style preview metadata, adapter source, and access-token safety notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the Figma token scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: figma_design_tokens)
file_key	string	no	(default: figma_file_key)
team_label	string	no	(default: design_team)
adapter_mode	rest_json | webhook_json | manual	no	(default: rest_json)
adapter_url	string	no	(default: http://127.0.0.1:9063/figma)
token_format	style_dictionary | css_variables | json_tokens	no	(default: style_dictionary)
token_count	integer	no	(default: 32)
component_count	integer	no	(default: 8)
active	boolean	no	(default: false)

connect_slack_ops_bridge mutates

Create a Slack operator-alert scaffold with webhook/socket adapter, alert rows, approval-gated command rows, and token/signing safety notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the Slack ops scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: slack_ops_bridge)
workspace_label	string	no	(default: venue_workspace)
channel_name	string	no	(default: #show-ops)
adapter_mode	incoming_webhook | socket_mode | manual	no	(default: incoming_webhook)
adapter_url	string	no	(default: http://127.0.0.1:9064/slack)
socket_url	string	no	(default: ws://127.0.0.1:9064/slack)
alert_count	integer	no	(default: 8)
command_count	integer	no	(default: 4)
approval_required	boolean	no	(default: true)
active	boolean	no	(default: false)

connect_s3_media_bucket mutates

Create an S3-compatible media-bucket scaffold with manifest rows, cache policy, ingest status, adapter source, and credential/signing safety notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the S3 media bucket scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: s3_media_bucket)
provider	aws_s3 | minio | gcs | azure_blob	no	(default: aws_s3)
bucket	string	no	(default: show-media)
prefix	string	no	(default: approved/)
adapter_mode	manifest_json | websocket_json | manual	no	(default: manifest_json)
manifest_url	string	no	(default: http://127.0.0.1:9065/media-manifest.json)
asset_count	integer	no	(default: 32)
cache_policy	manual | on_start | periodic	no	(default: manual)
active	boolean	no	(default: false)

connect_calendar_schedule_bus mutates

Create a venue calendar scaffold with event rows, reminder maps, blackout windows, adapter source, and credential/privacy safety notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the calendar scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: calendar_schedule_bus)
provider	ics | google_calendar | outlook | caldav	no	(default: ics)
calendar_ref	string	no	(default: venue-show-calendar)
timezone	string	no	(default: UTC)
adapter_mode	ics_feed | webhook_json | manual	no	(default: ics_feed)
adapter_url	string	no	(default: http://127.0.0.1:9066/calendar.ics)
event_count	integer	no	(default: 16)
reminder_count	integer	no	(default: 4)
active	boolean	no	(default: false)

connect_ticketing_checkin_bus mutates

Create a ticketing/check-in scaffold with aggregate gate counts, ticket-tier maps, gate status, adapter source, and PII/token safety notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the ticketing scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: ticketing_checkin_bus)
provider	eventbrite | dice | shotgun | custom	no	(default: eventbrite)
event_id	string	no	(default: venue_event)
venue_zone	string	no	(default: front_gate)
adapter_mode	rest_json | websocket_json | manual	no	(default: rest_json)
adapter_url	string	no	(default: http://127.0.0.1:9067/ticketing)
expected_capacity	integer	no	(default: 1200)
ticket_tier_count	integer	no	(default: 4)
gate_count	integer	no	(default: 3)
active	boolean	no	(default: false)

connect_pos_sales_telemetry mutates

Create a POS aggregate-telemetry scaffold with sales metrics, revenue buckets, privacy policy, adapter source, and PCI/PII safety notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the POS scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: pos_sales_telemetry)
provider	square | stripe_terminal | toast | custom	no	(default: square)
store_label	string	no	(default: venue_bar)
adapter_mode	rest_json | webhook_json | manual	no	(default: rest_json)
adapter_url	string	no	(default: http://127.0.0.1:9068/pos)
aggregation_window	1m | 5m | 15m | 1h	no	(default: 5m)
metric_count	integer	no	(default: 8)
revenue_bucket_count	integer	no	(default: 6)
active	boolean	no	(default: false)

connect_weather_forecast_bus mutates

Create a weather forecast/station scaffold with forecast rows, sensor maps, alert maps, adapter source, and safety-policy notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the weather scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: weather_forecast_bus)
provider	openweather | weatherkit | nws | custom_station	no	(default: openweather)
location_label	string	no	(default: venue)
adapter_mode	rest_json | websocket_json | manual	no	(default: rest_json)
adapter_url	string	no	(default: http://127.0.0.1:9069/weather)
forecast_hour_count	integer	no	(default: 24)
sensor_count	integer	no	(default: 4)
alert_count	integer	no	(default: 3)
active	boolean	no	(default: false)

connect_gtfs_transit_feed mutates

Create a GTFS static/realtime transit scaffold with route maps, stop maps, arrival predictions, adapter source, and public-data notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the GTFS scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: gtfs_transit_feed)
agency_label	string	no	(default: local_transit)
feed_mode	gtfs_realtime | static_gtfs_snapshot | manual	no	(default: gtfs_realtime)
adapter_url	string	no	(default: http://127.0.0.1:9070/gtfs)
route_count	integer	no	(default: 8)
stop_count	integer	no	(default: 12)
prediction_count	integer	no	(default: 16)
active	boolean	no	(default: false)

connect_parking_occupancy_bus mutates

Create a parking/queue occupancy scaffold with zone occupancy, sensor maps, signage policy, adapter source, and privacy safety notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the parking scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: parking_occupancy_bus)
provider	camera_analytics | iot_counter | api_vendor | manual	no	(default: iot_counter)
lot_label	string	no	(default: main_lot)
adapter_mode	rest_json | websocket_json | manual	no	(default: rest_json)
adapter_url	string	no	(default: http://127.0.0.1:9071/parking)
zone_count	integer	no	(default: 6)
capacity	integer	no	(default: 500)
sensor_count	integer	no	(default: 12)
active	boolean	no	(default: false)

connect_map_tile_overlay mutates

Create a map-tile overlay scaffold with tile layer maps, viewport metadata, attribution rows, adapter source, and token/cache safety notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the map scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: map_tile_overlay)
provider	mapbox | maptiler | openstreetmap | custom_tiles	no	(default: openstreetmap)
style_id	string	no	(default: standard)
tile_url_template	string	no	(default: https://tile.openstreetmap.org/{z}/{x}/{y}.png)
center_lat	number	no	(default: 0)
center_lng	number	no	(default: 0)
zoom_level	integer	no	(default: 12)
layer_count	integer	no	(default: 4)
attribution_required	boolean	no	(default: true)
active	boolean	no	(default: false)

connect_geojson_feature_bus mutates

Create a GeoJSON feature scaffold with feature rows, property maps, style rules, adapter source, and projection/privacy notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the GeoJSON scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: geojson_feature_bus)
source_label	string	no	(default: geojson_source)
adapter_mode	file_watch | webclient_json | manual	no	(default: webclient_json)
adapter_url	string	no	(default: http://127.0.0.1:9072/features.geojson)
geometry_mode	points | lines | polygons | mixed	no	(default: mixed)
feature_count	integer	no	(default: 64)
property_count	integer	no	(default: 8)
style_rule_count	integer	no	(default: 6)
active	boolean	no	(default: false)

connect_gps_fleet_tracker mutates

Create a GPS/fleet tracking scaffold with sanitized asset rows, geofence maps, privacy policy, adapter source, and credential/privacy notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the GPS scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: gps_fleet_tracker)
provider	traccar | owntracks | mqtt_gps | custom	no	(default: traccar)
fleet_label	string	no	(default: venue_fleet)
adapter_mode	websocket_json | mqtt_json | manual	no	(default: websocket_json)
adapter_url	string	no	(default: ws://127.0.0.1:9073/gps)
tracked_asset_count	integer	no	(default: 12)
geofence_count	integer	no	(default: 4)
update_rate_hz	number	no	(default: 1)
active	boolean	no	(default: false)

connect_adsb_aircraft_bus mutates

Create an ADS-B aircraft scaffold with sanitized aircraft rows, altitude bands, track history metadata, adapter source, and feed/privacy notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the ADS-B scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: adsb_aircraft_bus)
provider	dump1090 | tar1090 | opensky_adapter | custom	no	(default: dump1090)
airspace_label	string	no	(default: venue_airspace)
adapter_mode	rest_json | websocket_json | manual	no	(default: rest_json)
adapter_url	string	no	(default: http://127.0.0.1:9074/aircraft)
aircraft_count	integer	no	(default: 32)
altitude_band_count	integer	no	(default: 6)
track_history_count	integer	no	(default: 24)
active	boolean	no	(default: false)

connect_ais_vessel_bus mutates

Create an AIS vessel scaffold with sanitized vessel rows, zone maps, route hints, adapter source, and receiver/privacy notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the AIS scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: ais_vessel_bus)
provider	ais_receiver | marine_traffic_adapter | aishub_adapter | custom	no	(default: ais_receiver)
waterway_label	string	no	(default: harbor)
adapter_mode	rest_json | websocket_json | manual	no	(default: websocket_json)
adapter_url	string	no	(default: ws://127.0.0.1:9075/ais)
vessel_count	integer	no	(default: 24)
zone_count	integer	no	(default: 4)
route_count	integer	no	(default: 6)
active	boolean	no	(default: false)

connect_public_alerts_bus mutates

Create a public-alert scaffold with advisory alert rows, severity maps, routing policy, adapter source, and safety/escalation notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the alert scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: public_alerts_bus)
provider	cap_feed | nws_alerts | municipal_rss | custom	no	(default: cap_feed)
region_label	string	no	(default: venue_region)
adapter_mode	rest_json | websocket_json | manual	no	(default: rest_json)
adapter_url	string	no	(default: http://127.0.0.1:9076/alerts)
alert_count	integer	no	(default: 8)
severity_count	integer	no	(default: 4)
route_count	integer	no	(default: 3)
active	boolean	no	(default: false)

connect_twitch_eventsub_bus mutates

Create a Twitch EventSub/chat scaffold with sanitized event rows, reward maps, moderation policy, adapter source, and OAuth/webhook safety notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the Twitch scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: twitch_eventsub_bus)
channel_login	string	no	(default: show_channel)
adapter_mode	webhook_json | websocket_json | manual	no	(default: websocket_json)
netaddress	string	no	(default: 127.0.0.1)
port	integer	no	(default: 9077)
webhook_url	string	no	(default: http://127.0.0.1:9077/twitch)
event_count	integer	no	(default: 12)
reward_count	integer	no	(default: 4)
moderation_level	display_only | filtered | approval_required	no	(default: filtered)
active	boolean	no	(default: false)

connect_youtube_live_chat_bus mutates

Create a YouTube Live Chat scaffold with sanitized message rows, Super Chat tiers, moderation policy, adapter source, and API/quota safety notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the YouTube scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: youtube_live_chat_bus)
channel_id	string	no	(default: youtube_channel)
live_chat_id	string	no	(default: live_chat)
adapter_mode	polling_json | websocket_json | manual	no	(default: polling_json)
adapter_url	string	no	(default: http://127.0.0.1:9078/youtube-chat)
message_count	integer	no	(default: 24)
super_chat_tier_count	integer	no	(default: 5)
moderation_level	display_only | filtered | approval_required	no	(default: filtered)
active	boolean	no	(default: false)

connect_discord_interaction_bus mutates

Create a Discord interaction scaffold with command rows, message rows, approval policy, adapter source, and bot-token/signature safety notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the Discord scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: discord_interaction_bus)
guild_label	string	no	(default: show_guild)
channel_label	string	no	(default: stage-chat)
adapter_mode	gateway_json | webhook_json | manual	no	(default: gateway_json)
adapter_url	string	no	(default: ws://127.0.0.1:9079/discord)
command_count	integer	no	(default: 6)
message_count	integer	no	(default: 16)
approval_required	boolean	no	(default: true)
active	boolean	no	(default: false)

connect_tiktok_live_events_bus mutates

Create a TikTok Live-style event scaffold with sanitized event rows, gift tiers, moderation policy, adapter source, and auth/client safety notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the TikTok scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: tiktok_live_events_bus)
creator_label	string	no	(default: show_creator)
adapter_mode	websocket_json | polling_json | manual	no	(default: websocket_json)
adapter_url	string	no	(default: ws://127.0.0.1:9080/tiktok-live)
event_count	integer	no	(default: 16)
gift_tier_count	integer	no	(default: 6)
moderation_level	display_only | filtered | approval_required	no	(default: filtered)
active	boolean	no	(default: false)

connect_matrix_room_bus mutates

Create a Matrix room scaffold with sanitized room events, reaction maps, approval policy, adapter source, and token/encryption safety notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the Matrix scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: matrix_room_bus)
homeserver_label	string	no	(default: matrix)
room_alias	string	no	(default: #show:example.org)
adapter_mode	sync_json | websocket_json | manual	no	(default: sync_json)
adapter_url	string	no	(default: http://127.0.0.1:9081/matrix)
room_event_count	integer	no	(default: 16)
reaction_count	integer	no	(default: 6)
approval_required	boolean	no	(default: true)
active	boolean	no	(default: false)

connect_rss_feed_bus mutates

Create an RSS/Atom/editorial feed scaffold with sanitized item rows, category maps, refresh policy, adapter source, and copyright/sanitization notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the RSS scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: rss_feed_bus)
feed_label	string	no	(default: editorial_feed)
adapter_mode	rss_atom | webhook_json | manual	no	(default: rss_atom)
adapter_url	string	no	(default: http://127.0.0.1:9082/feed.xml)
item_count	integer	no	(default: 24)
category_count	integer	no	(default: 6)
refresh_interval_sec	integer	no	(default: 300)
active	boolean	no	(default: false)

connect_rfid_badge_bus mutates

Create an RFID badge-reader scaffold with sanitized badge events, reader maps, privacy policy, adapter source, and access-control safety notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the RFID scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: rfid_badge_bus)
venue_label	string	no	(default: installation)
adapter_mode	websocket_json | http_json | manual	no	(default: websocket_json)
adapter_url	string	no	(default: ws://127.0.0.1:9083/rfid)
reader_count	integer	no	(default: 4)
badge_event_count	integer	no	(default: 24)
privacy_level	aggregate_only | pseudonymous | approval_required	no	(default: pseudonymous)
active	boolean	no	(default: false)

connect_nfc_tap_bus mutates

Create an NFC tap scaffold with sanitized tap events, station maps, consent policy, adapter source, and tag-privacy notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the NFC scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: nfc_tap_bus)
installation_label	string	no	(default: interactive_installation)
adapter_mode	websocket_json | http_json | manual	no	(default: websocket_json)
adapter_url	string	no	(default: ws://127.0.0.1:9084/nfc)
station_count	integer	no	(default: 6)
tap_event_count	integer	no	(default: 24)
consent_mode	opt_in_required | pseudonymous | aggregate_only	no	(default: opt_in_required)
active	boolean	no	(default: false)

connect_ble_beacon_bus mutates

Create a BLE beacon proximity scaffold with sanitized beacon rows, zone maps, smoothing policy, adapter source, and device-privacy notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the BLE scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: ble_beacon_bus)
site_label	string	no	(default: gallery_floor)
adapter_mode	websocket_json | http_json | manual	no	(default: websocket_json)
adapter_url	string	no	(default: ws://127.0.0.1:9085/ble)
scanner_count	integer	no	(default: 4)
beacon_count	integer	no	(default: 16)
zone_count	integer	no	(default: 6)
smoothing_window_sec	integer	no	(default: 15)
active	boolean	no	(default: false)

connect_uwb_anchor_bus mutates

Create a UWB RTLS scaffold with sanitized tag positions, anchor maps, spatial policy, adapter source, and tag-privacy notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the UWB scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: uwb_anchor_bus)
space_label	string	no	(default: tracked_space)
adapter_mode	websocket_json | http_json | manual	no	(default: websocket_json)
adapter_url	string	no	(default: ws://127.0.0.1:9086/uwb)
anchor_count	integer	no	(default: 8)
tag_count	integer	no	(default: 12)
zone_count	integer	no	(default: 4)
position_units	meters | centimeters | normalized	no	(default: meters)
active	boolean	no	(default: false)

connect_qr_scan_bus mutates

Create a QR scan scaffold with sanitized scan events, route maps, sanitization policy, adapter source, and token/URL safety notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the QR scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: qr_scan_bus)
campaign_label	string	no	(default: visitor_scan)
adapter_mode	websocket_json | http_json | manual	no	(default: http_json)
adapter_url	string	no	(default: http://127.0.0.1:9087/qr-scans)
scan_event_count	integer	no	(default: 24)
route_count	integer	no	(default: 6)
sanitization_level	route_only | pseudonymous | approval_required	no	(default: route_only)
active	boolean	no	(default: false)

connect_wifi_presence_bus mutates

Create a Wi-Fi presence scaffold with aggregate occupancy rows, dwell buckets, privacy policy, adapter source, and device-privacy notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the Wi-Fi scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: wifi_presence_bus)
site_label	string	no	(default: venue_floor)
adapter_mode	websocket_json | http_json | manual	no	(default: http_json)
adapter_url	string	no	(default: http://127.0.0.1:9088/wifi-presence)
zone_count	integer	no	(default: 6)
dwell_bucket_count	integer	no	(default: 4)
aggregate_window_sec	integer	no	(default: 60)
active	boolean	no	(default: false)

connect_people_counting_bus mutates

Create a people-counting scaffold with aggregate zone counts, sample windows, adapter source, and privacy policy notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the people-count bus. (default: /project1)
name	string	no	Generated baseCOMP name. (default: people_counting_bus)
venue_label	string	no	(default: venue)
adapter_mode	websocket_json | http_json | manual	no	(default: websocket_json)
adapter_url	string	no	(default: ws://127.0.0.1:9090/people-count)
zone_count	integer	no	(default: 6)
sample_count	integer	no	(default: 24)
privacy_level	aggregate_only | anonymous_tracks | approval_required	no	(default: aggregate_only)
active	boolean	no	(default: false)

connect_queue_length_bus mutates

Create a queue-length scaffold with aggregate queue metrics, sample windows, adapter source, and alert policy notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the queue scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: queue_length_bus)
queue_label	string	no	(default: main_queue)
adapter_mode	websocket_json | http_json | manual	no	(default: websocket_json)
adapter_url	string	no	(default: ws://127.0.0.1:9091/queue)
queue_count	integer	no	(default: 4)
sample_count	integer	no	(default: 24)
alert_threshold_people	integer	no	(default: 75)
active	boolean	no	(default: false)

connect_door_access_bus mutates

Create a door-access monitoring scaffold with sanitized door events, door maps, adapter source, and lock-control safety notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the door scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: door_access_bus)
venue_label	string	no	(default: venue)
adapter_mode	websocket_json | http_json | manual	no	(default: websocket_json)
adapter_url	string	no	(default: ws://127.0.0.1:9092/door-access)
door_count	integer	no	(default: 8)
event_count	integer	no	(default: 32)
policy_mode	monitor_only | approval_required | manual	no	(default: monitor_only)
active	boolean	no	(default: false)

connect_environmental_sensor_bus mutates

Create an environmental sensor scaffold with normalized readings, sensor maps, adapter source, and building-control safety notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for environment sensors. (default: /project1)
name	string	no	Generated baseCOMP name. (default: environmental_sensor_bus)
sensor_profile	co2_temp_humidity | air_quality | mixed | manual	no	(default: co2_temp_humidity)
adapter_mode	websocket_json | http_json | mqtt_json | manual	no	(default: http_json)
adapter_url	string	no	(default: http://127.0.0.1:9093/environment)
zone_count	integer	no	(default: 6)
sensor_count	integer	no	(default: 12)
active	boolean	no	(default: false)

connect_power_meter_bus mutates

Create a power-meter telemetry scaffold with read-only meter readings, circuit maps, adapter source, and electrical-control safety notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the power scaffold. (default: /project1)
name	string	no	Generated baseCOMP name. (default: power_meter_bus)
venue_label	string	no	(default: venue)
adapter_mode	websocket_json | http_json | manual	no	(default: http_json)
adapter_url	string	no	(default: http://127.0.0.1:9094/power)
meter_count	integer	no	(default: 4)
circuit_count	integer	no	(default: 12)
warning_kw	number	no	(default: 50)
active	boolean	no	(default: false)

connect_noise_level_bus mutates

Create a noise-level telemetry scaffold with aggregate decibel readings, sample windows, adapter source, and PA/safety policy notes.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for noise level data. (default: /project1)
name	string	no	Generated baseCOMP name. (default: noise_level_bus)
venue_label	string	no	(default: venue)
adapter_mode	websocket_json | http_json | manual	no	(default: websocket_json)
adapter_url	string	no	(default: ws://127.0.0.1:9095/noise)
zone_count	integer	no	(default: 4)
sample_count	integer	no	(default: 32)
weighting	dba | dbc | flat	no	(default: dba)
limit_db	number	no	(default: 95)
active	boolean	no	(default: false)

duplicate_network mutates

Copy a node or whole COMP (and all its contents) to a new node, placed in the source's parent or another parent_path. Returns the source path and the new copy's path. Use duplicate this way to clone a built network; use create_container instead when you just need a fresh empty COMP.

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. Only moves node positions — it never adds, deletes, or rewires nodes. Returns the COMP path and how many nodes were repositioned.

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)
include_docked	boolean	no	Move each node's docked DATs (e.g. GLSL *_pixel or callbacks DATs) with it by the same delta, like an interactive drag. Set false to reposition only the nodes themselves. (default: true)

create_panic destructive

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. Marked destructive because firing Blackout/Freeze disables the live output. Returns the container, the source/freeze/blackout/output node paths, and the initial toggle states.

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	Parent COMP the panic container is built inside (default '/project1'). (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)

clip_audio_transport mutates

Create a synchronized clip transport container: a Movie File In TOP video lane, optional Audio File In CHOP lane, Null outputs, deterministic layout, and Play/Loop/Speed controls bound across both lanes. Use it as a reusable building block before clip launchers, VJ decks, or stream/output chains.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP path where the transport container is created. (default: /project1)
name	string	no	Name of the transport container COMP to create. (default: clip_audio_transport)
movie_file	string	no	Optional movie file path for the Movie File In TOP.
audio_file	string	no	Optional audio file path for the Audio File In CHOP.
include_audio	boolean	no	Create an Audio File In CHOP transport lane alongside the movie lane. (default: true)
autoplay	boolean	no	Initial play state for movie/audio file inputs. (default: true)
loop	boolean	no	Initial loop state for movie/audio file inputs. (default: true)
speed	number	no	Initial playback speed. Negative values reverse where the operator supports it. (default: 1)
expose_controls	boolean	no	Expose Play, Loop and Speed custom parameters on the transport container. (default: true)

osc_router_matrix mutates

Create an offline-safe OSC control matrix: one Constant CHOP plus OSC Out CHOP per target, deterministic left-to-right layout, target-specific address prefixes, and a structured report of every emitted OSC address. Use it as the primitive for QLab, atemOSC/Companion, Resolume, VDMX, or any OSC-speaking show-control endpoint.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP to build the router in. (default: /project1)
name	string	no	Name of the router container COMP. (default: osc_router_matrix)
routes	object[]	yes	Routes/channels to create for every target.
targets	object[]	yes	OSC destinations. Each target gets a Constant CHOP and OSC Out CHOP.

qlab_osc_bridge mutates

Create a QLab OSC control bridge using the OSC router matrix primitive. It exposes /go, /stop, /panic, /pause, /resume, /reset and optional /cue/{number}/start routes to QLab's configurable OSC receive port, without requiring QLab to be running during build.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP to build the QLab OSC bridge in. (default: /project1)
name	string	no	Name of the bridge container COMP. (default: qlab_osc_bridge)
host	string	no	QLab machine IP or hostname. (default: 127.0.0.1)
port	integer	no	QLab OSC receive port. (default: 53000)
active	boolean	no	Start OSC sending immediately. (default: false)
cue_numbers	string[]	no	Optional QLab cue numbers to expose as /cue/{number}/start routes. (default: ``)

atem_switcher_control mutates

Create an OSC control preset for an ATEM switcher routed through atemOSC, Bitfocus Companion, or another OSC relay. This does not use the Blackmagic SDK directly; it builds an offline-safe TouchDesigner OSC matrix for cut/auto/FTB and program/preview input selection.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP to build the ATEM control preset in. (default: /project1)
name	string	no	Name of the ATEM control container COMP. (default: atem_switcher_control)
host	string	no	atemOSC, Companion, or OSC relay host/IP. (default: 127.0.0.1)
port	integer	no	OSC receive port for atemOSC/Companion/relay. (default: 3333)
inputs	integer	no	Switcher input count to expose. (default: 4)
active	boolean	no	Start OSC sending immediately. (default: false)

resolume_vdmx_output_chain mutates

Create an OSC control chain for driving Resolume, VDMX, or both from TouchDesigner. It builds target-specific OSC Out lanes with layer opacity, crossfader, speed, clip trigger, and blackout channels; use it beside video/NDI/Syphon output tools when an external VJ app handles playback or final compositing.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP to build the Resolume/VDMX control chain in. (default: /project1)
name	string	no	Name of the output-control container COMP. (default: resolume_vdmx_output_chain)
target	resolume | vdmx | both	no	Which OSC target preset(s) to create. (default: resolume)
host	string	no	Destination host for Resolume/VDMX OSC. (default: 127.0.0.1)
resolume_port	integer	no	Resolume OSC input port. (default: 7000)
vdmx_port	integer	no	VDMX OSC input port. (default: 8000)
active	boolean	no	Start OSC sending immediately. (default: false)

obs_stream_control mutates

Create an OBS WebSocket v5 control rig in TouchDesigner: websocketDAT connection, Constant CHOP command channels for stream/record/scene actions, and a chopExecute DAT that dispatches op:6 request payloads such as StartStream, StopStream, ToggleStream, StartRecord, StopRecord, ToggleRecord, and SetCurrentProgramScene. tdmcp never accepts or stores OBS passwords; if OBS authentication is enabled, complete Identify authentication manually in the generated obs_dispatch DAT.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP to build the OBS control rig in. (default: /project1)
name	string	no	Name of the created/reused baseCOMP. (default: obs_stream_control)
host	string	no	OBS WebSocket host/IP. (default: 127.0.0.1)
port	integer	no	OBS WebSocket port. (default: 4455)
use_tls	boolean	no	Use wss:// instead of ws://. (default: false)
auto_connect	boolean	no	Start the websocketDAT active immediately. Defaults false for show safety. (default: false)
include_recording	boolean	no	Also create StartRecord, StopRecord, and ToggleRecord controls. (default: true)
scenes	string[]	no	Optional OBS scene names. Each creates a scene_* control that sends SetCurrentProgramScene. (default: ``)
auth_required	boolean	no	Set true only as a reminder that OBS WebSocket authentication must be completed manually; tdmcp never stores an OBS password. (default: false)

notch_touchengine_bridge mutates

Build a guarded Notch TOP or Engine COMP/TouchEngine bridge scaffold with notes, output, and optional Notch play/speed controls. This does not validate a Notch license or target runtime; live validation remains explicit.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP path to build inside. (default: /project1)
name	string	no	Generated container name. (default: notch_touchengine_bridge)
mode	notch_top | engine_comp	no	Create a Notch TOP bridge or an Engine COMP TouchEngine bridge. (default: notch_top)
block_path	string	no	Notch .dfxdll block path for mode=notch_top.
tox_path	string	no	TouchEngine .tox path for mode=engine_comp.
width	integer	no	Notch TOP or placeholder output width. Ignored by mode=engine_comp. (default: 1920)
height	integer	no	Notch TOP or placeholder output height. Ignored by mode=engine_comp. (default: 1080)
active	boolean	no	Start the Notch TOP active. Ignored by mode=engine_comp. (default: false)
play	boolean	no	Start playback/cooking where supported. (default: false)
expose_controls	boolean	no	Expose Play and Speed controls where possible. (default: true)

create_decks mutates

Build a DJ-style VJ mixer. Without decks[], it preserves the legacy A/B Cross TOP mixer with GainA/GainB controls. With decks[], it builds a 2-8 deck mixer: every deck pulls a source TOP (or a test source) through gain and FX-send Level TOPs, decks 3+ blend into a running Cross TOP chain, a Switch TOP provides hard transition cuts, a final Cross TOP blends program vs cut, and an additive FX-send bus returns per-deck sends into the master. 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)
decks	object[]	no	Optional N-channel deck list. When supplied, create_decks builds a 2-8 deck mixer with per-deck gain, FX sends, a running blend chain, and a hard-cut switch bus.
cut_deck	integer	no	Zero-based deck index selected by the hard transition-cut bus in N-channel mode. (default: 0)
cut_mix	number	no	Blend between the continuous program mix and the hard transition-cut bus: 0 = program mix, 1 = cut bus. (default: 0)
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	Parent COMP the mixer container is built inside (default '/project1'). (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)

scaffold_vj_deck mutates

Compose a complete, playable VJ deck UI in one call: it builds a DJ-style A/B deck mixer (create_decks) with a crossfader, adds an on-screen fader control surface (create_control_surface) with crossfade + per-deck gain faders, and creates a midiinCHOP control surface (create_external_io) whose channels are bound to the same crossfader/gain parameters for hands-on MIDI control. Pass deck_a/deck_b source TOP paths (or omit for test sources), and an optional midi_map of channel→control bindings (defaults to ch1c1→crossfader, ch1c2→gain_a, ch1c3→gain_b). This is the deck-scaffold layer on top of the create_decks primitive — it wires the existing deck, surface, and I/O tools into one UI container.

Parameter	Type	Required	Description
name	string	no	Base name for the VJ-deck container COMP. (default: vj_deck)
parent_path	string	no	COMP the VJ deck is scaffolded inside (default '/project1'). (default: /project1)
deck_a	string	no	Absolute path of the source TOP for deck A. If omitted, a built-in test source is created.
deck_b	string	no	Absolute path of the source TOP for deck B. If omitted, a built-in test source is created.
crossfade	number	no	Initial crossfader position: 0 = full deck A, 1 = full deck B. (default: 0.5)
midi	boolean	no	Create a midiinCHOP control surface and bind its channels to the deck controls (MIDI-mappable VJ deck). (default: true)
midi_map	object[]	no	Explicit MIDI channel → control bindings. When omitted, a sensible default map (ch1c1→crossfader, ch1c2→gain_a, ch1c3→gain_b) is used.
faders	boolean	no	Add an on-screen fader control surface (crossfader + per-deck gain faders) inside the container. (default: true)

create_synesthesia_unreal_osc mutates

Build a named OSC-out preset map for driving Synesthesia or Unreal Engine from TouchDesigner. Picks a preset ('synesthesia' → prefix '/syn', port 6448; 'unreal' → prefix '/unreal', port 8000), builds a Constant CHOP with one named channel per control (channel name = '<prefix>/<control>' so an oscoutCHOP emits the exact address the target app expects), and wires it into an oscoutCHOP aimed at host:port. Override the control names, prefix, host, or port as needed. This is the preset layer on top of create_external_io osc_out — it fills in the address templates and default control set so the send 'just works' with the target app. Bind audio/analysis to the source channels (e.g. op('controls')['syn/Bass']) to make the receiving app react.

Parameter	Type	Required	Description
name	string	no	Base name for the container COMP. (default: osc_send)
parent_path	string	no	COMP to create the OSC-out chain in (default '/project1'). (default: /project1)
preset	synesthesia | unreal	no	Named OSC-out preset — sets the address prefix, default port, and default control names for Synesthesia or Unreal Engine. (default: synesthesia)
host	string	no	Destination IP the OSC messages are sent to (the machine running Synesthesia / Unreal). (default: 127.0.0.1)
port	integer | null	no	UDP port to send OSC to. Null uses the preset's default (Synesthesia 6448, Unreal 8000). (default: null)
controls	string[] | null	no	Override the preset's control names. Each becomes an OSC address '/<prefix>/<name>' and a channel on the source Constant CHOP you drive/bind. (default: null)
prefix	string | null	no	Override the preset's OSC address prefix (the part before the control name). Null uses the preset default (syn / unreal). (default: null)
active	boolean	no	Start sending immediately. Defaults off so you can confirm the destination host/port first. (default: false)

create_cue_sequencer mutates

Build a bar-quantized cue timeline: a Beat CHOP (on the global tempo) + a CHOP Execute DAT that, on each bar (or beat) boundary, advances through an ordered list of steps and recalls — or morphs over morph_seconds — that step's cue on a target COMP. The deterministic, musically-timed counterpart to create_autopilot (which is random/cyclic). Reuses manage_cue's stored cues and the same cue_morph engine, so store the target's cues with manage_cue first. Live Active / Step / BarsPerStep controls let you pause, jump, or retune on stage.

Parameter	Type	Required	Description
target	string	no	COMP whose stored cues (tdmcp_cues, from manage_cue) the sequencer recalls/morphs. Store the cues first. (default: /project1)
steps	object[]	yes	The ordered timeline: each step names a cue and how many bars/beats it holds before the next.
loop	boolean	no	When the last step finishes, wrap back to the first (true) or stop (false). (default: true)
quantize	bar | beat	no	Unit each step's count is measured in: 'bar' (× the project's beats-per-bar) or raw 'beat'. (default: bar)
morph_seconds	number	no	0 = snap to each cue instantly on its boundary; >0 = crossfade to it over this many seconds (via the same cue_morph engine manage_cue uses). (default: 0)
name	string	no	Name of the engine container built inside target. (default: cue_seq)
parent_path	string	no	Where to create the sequencer engine COMP. (default: /project1)

create_stage_dashboard mutates

Serve one unified live-performance cockpit from a Web Server DAT — a single responsive web page (phone + laptop) that combines a grid of cue-launch buttons (recall named cues from manage_cue on the target COMP), master faders bound to chosen parameters, a big PANIC button (toggles the target COMP's Blackout/Freeze safety pars, the create_panic mechanism), and a live readout strip (a beat indicator plus a VU bar reading an audio-features Null CHOP). Open the URL — no app to install — and the page POSTs every control change back to the server, which applies it. SECURITY: like the bridge and create_phone_remote, this listens on all interfaces and accepts writes with NO auth, so use it only on a trusted network. Store cues with manage_cue, expose params with create_control_panel, and run create_panic first so the Blackout/Freeze toggles exist.

Parameter	Type	Required	Description
target	string	no	Control COMP the dashboard is built inside. It holds the cues (manage_cue) and the Blackout/Freeze toggles (create_panic); cue buttons fire that COMP's cues and the panic button toggles its safety pars. (default: /project1)
port	integer	no	TCP port for the dashboard web server (keep it distinct from the bridge's 9980 and phone_remote's 9981). (default: 9990)
cues	string[]	no	Cue names (stored with manage_cue) to expose as launch buttons, in order. Each becomes a button that instantly recalls its cue on the target COMP. Empty omits the cue grid. (default: ``)
faders	object[]	no	Master faders, each a { label, par_path } that becomes a slider writing the parameter live. Empty omits the fader bank. (default: ``)
audio_features	string	no	Optional audio-features Null CHOP path for the readout strip's VU bar (first channel). When omitted the readout still renders (beat from the timeline, VU flat).
name	string	no	Name of the Web Server DAT (and its callbacks DAT) built inside the target COMP. (default: stage_dashboard)
layout	v1 | v2	no	Dashboard layout. 'v1' is the original (cues + faders + readout + panic). 'v2' adds stereo VU, BPM, cue timeline strip, FPS/cook overlay, and a sticky confirm-PANIC bar. Default 'v1' for backward compat. (default: v1)
tempo_channel	string	no	v2 only. Absolute path to a CHOP whose first channel is current BPM (e.g. a detect_tempo Null CHOP). Omitted = BPM widget hidden.
cue_times	object[]	no	v2 only. Cue start times (seconds from show start) from compose_cue_list, for the timeline strip's playhead. Empty = strip omitted, cue grid still shown. (default: ``)

create_palette mutates

Generate a reusable colour palette + gradient other tools can bind to. In 'harmony' mode it computes N swatches from a base hue and a colour-theory rule (complementary / analogous / triad / tetrad / monochrome); in 'from_source' mode it samples dominant colours from a source TOP. It builds a Ramp TOP gradient (key colours from a docked Table DAT) plus a Constant CHOP exposing each swatch as swatch{i}r/g/b channels — feed those into create_color_grade, generate_from_moodboard or bind_to_channel. Live BaseHue / Saturation / Value / Rule / Count controls are exposed on the parent. Builds standalone (a harmony palette needs no source).

Parameter	Type	Required	Description
mode	harmony | from_source	no	How swatches are derived: 'harmony' computes them from a base hue + a colour-theory rule (pure maths); 'from_source' samples dominant colours from a source TOP. (default: harmony)
base_hue	number	no	(harmony) Base hue on the colour wheel, 0..1 (0 = red, 0.333 = green, 0.666 = blue). (default: 0)
saturation	number	no	(harmony) Base saturation 0..1 (0 = grey, 1 = vivid). (default: 0.7)
value	number	no	(harmony) Base value / brightness 0..1. (default: 0.9)
rule	complementary | analogous | triad | tetrad | monochrome	no	(harmony) Colour-theory spread: complementary (base + opposite), analogous (neighbours), triad (3 evenly spaced), tetrad (4 evenly spaced), monochrome (one hue, varied brightness). (default: triad)
count	integer	no	Number of swatches to produce (1..13; capped because the swatch Constant CHOP holds 40 channels = 13 RGB swatches). (default: 5)
analogous_spread	number	no	(harmony, analogous rule) Hue step between neighbours, 0..0.5 (0.083 ≈ 30°). (default: 0.083)
source	string	no	(from_source) Absolute path of a TOP to sample dominant colours from. It is down-res'd to a tiny image and its pixels are read back; if missing/unreadable the palette falls back to a neutral greyscale ramp.
parent_path	string	no	COMP to build the Ramp TOP + swatch CHOP inside. (default: /project1)
name	string	no	Base name for the created nodes. (default: palette)
expose_controls	boolean	no	Add BaseHue / Saturation / Value / Rule / Count custom parameters to parent_path. (default: true)

create_data_source mutates

Ingest live external data onto a binding-ready channel/table — the input counterpart to create_data_visualization and bind_to_channel. 'json'/'csv' poll a URL with a Web Client DAT (and cook from a static sample of fields when no url is given, so it works offline); 'osc' listens on a UDP port; 'serial' reads a device. Numeric fields become channels on an output Null CHOP (named for each key) so other tools can bind to them; the raw text is exposed on a Null DAT. Live OSC/serial values only appear when a sender/device is present.

Parameter	Type	Required	Description
kind	json | csv | osc | serial	no	Where the data comes from: 'json' or 'csv' poll a URL with a Web Client DAT (or, with no url, cook from a static sample so it works offline), 'osc' listens for OSC messages on a UDP port, 'serial' reads a serial device. json/csv always cook; osc/serial only carry values once a sender/device is present. (default: json)
parent_path	string	no	COMP to build the data source inside. (default: /project1)
name	string	no	Base name for the created sub-network.
url	string	no	(json/csv) Endpoint the Web Client DAT fetches. When omitted the network still cooks from a static sample so other tools have channels to bind to.
port	integer	no	(osc) UDP port to listen on. Defaults to 7000.
device	string	no	(serial) Serial port, e.g. 'COM3' on Windows or '/dev/tty.usbserial' on macOS.
baud	integer	no	(serial) Baud rate. (default: 9600)
fields	string[]	no	Numeric keys to extract. Each becomes a channel on the output Null CHOP (named for the key) so create_data_visualization / bind_to_channel can bind to it, and a column in the offline sample table. (default: value)
poll_seconds	number	no	(json/csv) How often the Web Client DAT re-fetches the URL. (default: 1)
expose_controls	boolean	no	Surface live 'Active' and 'Poll' controls on the source operator. (default: true)

create_led_mapper mutates

Build a pixel-mapping chain from a source TOP to an LED fixture grid and DMX Out CHOP over Art-Net or sACN. The generated network resizes to width×height, samples one texel per fixture pixel, preserves RGB channels, and returns created node paths, channel count, warnings, and live Brightness/Universe controls on the parent COMP. It defaults to a moving Ramp test source so the chain can cook without input; real network output still requires a reachable fixture/node and should be verified before sending. Use create_dmx_fixture_pipeline for fixture patching and this tool when you specifically need image-to-pixel mapping.

Parameter	Type	Required	Description
source	string	no	TOP path whose image is mapped to the fixtures. If omitted, a built-in moving Ramp TOP test source is created so the chain cooks with no input.
width	integer	no	Pixels per row (columns). Each texel of the WxH grid drives one LED fixture. (default: 16)
height	integer	no	Rows of pixels. 1 = a single LED strip. (default: 1)
layout	horizontal | vertical | serpentine	no	Pixel wiring order along the strip/grid: horizontal (rows left-to-right), vertical (columns), or serpentine (alternate rows reversed — boustrophedon strips). (default: horizontal)
start_universe	integer	no	Art-Net / sACN universe of the first pixel. (default: 1)
start_channel	integer	no	DMX start channel (1-512) of the first pixel within the starting universe. (default: 1)
net	artnet | sacn	no	Network DMX protocol: Art-Net or sACN (streaming ACN). (default: artnet)
net_address	string	no	Target IP address for Art-Net / sACN. Defaults to the operator's own default.
fps	number	no	Output frame rate (DMX Out CHOP sample rate). (default: 30)
parent_path	string	no	COMP to build the pixel-map chain in. (default: /project1)
name	string	no	Base name for the created nodes.

batch_operations mutates

Run an ordered list of create / connect / setParam operations in one call (fail-forward, per-operation warnings; not transactional). Exposes the network builder as a general primitive — distinct from set_parameters_batch, which only sets parameters. Names created earlier can be referenced by later connect/setParam operations.

Parameter	Type	Required	Description
default_parent	string	no	Parent path for create operations that omit parent_path. (default: /project1)
operations	object[]	yes	Ordered list of create / connect / setParam operations. Runs in order, fail-forward: a failing operation becomes a warning and the rest still run (not transactional). Names created earlier can be referenced by later connect/setParam operations.

manage_annotation mutates

Self-document a network: create a titled annotation box, set an op's comment, list the annotations/comments in a network, or list the ops a box geometrically encloses. Makes generated networks legible.

Parameter	Type	Required	Description
action	create | comment | list | enclosed	yes	'create' a titled annotation box, 'comment' to set an op's comment, 'list' the annotations in a network, or 'enclosed' to list the ops a box geometrically encloses.
parent_path	string	no	(create/list) The network (COMP) to act in. (default: /project1)
text	string	no	(create) The title/text shown on the box; (comment) the comment string to set.
name	string	no	(create) Name for the annotation COMP (defaults to 'anno').
node_path	string	no	(comment) The op to comment on; (enclosed) the annotation box whose enclosed ops to list.
x	number	no	(create) Node-space X position for the box's left edge.
y	number	no	(create) Node-space Y position for the box's top edge.
w	number	no	(create) Node-space width of the box.
h	number	no	(create) Node-space height of the box.

set_perform_mode mutates

Toggle perform mode — the one switch the artist flips before going live. When enabled, tdmcp stores an advisory flag that tools can read before doing nonessential compute; the built-in guard currently suppresses auto preview captures. The flag is stored on the TD root op (op('/').store('tdmcp_perform_mode', ...)). Advisory: this does not stop the TD timeline or kill audio/video processing. Call with enabled=false after the show to resume normal operation.

Parameter	Type	Required	Description
enabled	boolean	yes	true to enter perform mode before a live show, false to leave it afterward. While perform mode is ON, tools that honor the advisory flag skip nonessential compute. The built-in guard currently suppresses auto preview captures; future tools can opt in by checking op('/').fetch('tdmcp_perform_mode', False) before doing expensive work. It does NOT stop the TD timeline or kill audio/video processing.

bind_audio_reactive mutates

Make a whole COMP react to the music in one call — the core VJ move. Point target at a COMP with numeric custom-parameter knobs and source_chop at an audio-feature CHOP (e.g. an extract_audio_features Null carrying level/bass/mid/treble), and each knob is switched to expression mode tracking an audio band. Omit mappings to auto-map knobs by name heuristic (bright/level/opacity→level, scale/size/zoom→bass, hue/color→treble, speed/rate/rot→mid; unrecognized knobs are skipped), or pass explicit param→channel bindings with per-binding scale/offset. By default appends a master 'Reactivity' float knob (0–2, default = intensity) that scales every binding so the artist can dial the whole network's reactivity from one control. Fail-forward: a missing source CHOP, an absent channel, or an already-bound parameter are warnings, not failures — only a missing/non-COMP target is fatal. This tool only WIRES an existing COMP to an existing CHOP, building no nodes: produce the feature CHOP with extract_audio_features (or create_spectrum) first, use create_audio_reactive when you want a whole new reactive network with its own visual, and bind_to_channel for finer single-parameter control.

Parameter	Type	Required	Description
target	string	yes	COMP whose numeric custom parameters (knobs) should react to the music.
source_chop	string	yes	CHOP carrying audio feature channels (e.g. an extract_audio_features Null). Expected channels: level, bass, mid, treble.
intensity	number	no	Master reactivity amount (0=off, 1=normal, 2=strong) — scales every binding. (default: 1)
mappings	object[]	no	Explicit param→channel bindings. Omit to auto-map the target COMP's numeric custom parameters by name heuristics.
add_master	boolean	no	Append a 'Reactivity' master float knob (0-2, default = intensity) on the target COMP that scales every binding. (default: true)

create_replicator mutates

Wire a Replicator COMP that clones a template COMP once per row of a Table DAT — TouchDesigner's idiomatic 'N copies from data' mechanism (menus, scoreboards, per-track decks, instanced panels). Resolves or creates the template COMP (omit template_path → a minimal container with a Text) and the driving Table DAT (omit table_path → a small example table; rows sets how many demo rows), creates the replicator under parent_path, points its driving-table and master parameters at them, sets the replication method to 'by table', and optionally drops an onReplicate callback DAT stub for per-clone setup. The Replicator's parameter names vary by TD build, so each is set probe-first and the report includes which parameter took plus the live parameter list. Then it pulses a re-replicate so the clones appear. Re-replicating is destructive to previously generated clones, which the replicator deletes and re-creates on cook.

Parameter	Type	Required	Description
parent_path	string	no	COMP to build the replicator inside. (default: /project1)
name	string	no	Name for the Replicator COMP. (default: replicator1)
template_path	string	no	Existing COMP to clone per row. Omit → create a minimal template COMP (a container with a Text).
table_path	string	no	Table DAT whose rows drive the clones. Omit → create a small example Table DAT.
rows	integer	no	When creating an example table, how many example rows (0 = a 3-row demo). (default: 0)
callback_stub	boolean	no	Generate an onReplicate callback DAT stub (per-clone setup hook). (default: true)

create_data_reactive mutates

Wire arbitrary external data (weather, follower count, sensor readings, OSC values) onto a COMP's custom numeric parameters — the data counterpart to bind_audio_reactive. Point target at a COMP with numeric custom-parameter knobs, source_chop at a live-data CHOP (e.g. a create_data_source Null), and provide explicit mappings (data channel → param name) each with an input range [in_min, in_max] and output range [out_min, out_max] so the data is correctly re-mapped to the parameter's visual range. Set smooth > 0 to insert a Lag CHOP (symmetric attack+release) so noisy or jittery data does not flicker the visuals. Fail-forward: a missing source CHOP or absent channel are warnings — only a missing/non-COMP target is fatal. Build the data CHOP first with create_data_source; use bind_to_channel for finer single-parameter control.

Parameter	Type	Required	Description
target	string	yes	COMP whose numeric custom parameters should react to the data.
source_chop	string	yes	CHOP carrying the live data channels (e.g. a create_data_source Null). Channels can be weather values, follower counts, sensor readings, etc.
mappings	object[]	yes	Explicit data→param mappings with per-mapping range remap. Data is rarely 0–1, so set in_min/in_max to the real data range for correct visual mapping.
smooth	number	no	Symmetric smoothing in seconds (Lag CHOP) applied to all channels so noisy data does not jitter visuals. 0 = no smoothing. (default: 0)

create_beat_grid_sequencer mutates

Build a programmable step-grid sequencer driven by a Beat CHOP on the global TD tempo: a Table DAT holds the per-step pattern (values or 1/0 flags), and a CHOP Execute DAT fires on every beat boundary, reads the current step (count % steps) from the table, and dispatches — action=param sets a custom parameter to the step value; action=cue recalls the cue for active steps (cues stored with manage_cue). The deterministic, repeating-rhythm instrument between create_autopilot (random drift) and create_cue_sequencer (linear list): program a strobe on beats 1+3, a hue shift on the bar, etc. Reprogramme the grid live by editing the step_table DAT. NOTE: beat-callback timing is UNVERIFIED offline — check op().time.play if steps don't fire when the TD timeline is paused.

Parameter	Type	Required	Description
name	string	no	Name for the sequencer COMP. (default: beat_grid)
parent_path	string	no	Parent COMP path to create the sequencer inside. (default: /project1)
target	string	yes	COMP whose parameter or cue each active step fires on a beat boundary.
steps	integer	no	Number of steps in the grid (e.g. 16 = one bar of 16th notes at 4/4). (default: 16)
action	param | cue	no	param: set a target custom-parameter value per active step; cue: recall a named cue per active step (cues stored with manage_cue). (default: param)
param	string	no	(action=param) The custom-parameter name on the target COMP to set on each active step.
pattern	number[]	no	Per-step values (action=param) or 1/0 active flags (action=cue); length should match 'steps'. Omit to auto-generate an example pattern. (default: ``)
bpm_source	string	no	Path to an existing Beat CHOP or tempo source. Omit to create a new Beat CHOP (on the global TD tempo).

rebuild_network destructive

Reconstruct a live network inside a COMP from a serialize_network spec — the REBUILD half of a git-diffable round-trip. Takes a JSON spec of nodes (name, operator type, parameters as constants/expressions/binds, inbound wires by name, optional x/y) and, in one pass, creates every node, applies its parameters and expressions, then wires inputs by resolving each from reference to the freshly created node. Fail-forward: an unknown operator type, missing parameter, or unresolved wire becomes a warning and the rest still build, so a partial reconstruction still returns useful results. Set clear_existing to delete the parent's current children first (destructive). Set auto_layout to auto-position every node by dependency (longest-path columns, left→right) from the spec's inputs graph, overriding any manual x/y. Returns the created node names, wire count, parameters set, and any warnings.

Parameter	Type	Required	Description
parent_path	string	yes	COMP to rebuild the network inside.
spec	object	yes	A serialize_network spec to reconstruct.
clear_existing	boolean	no	Delete existing children of parent_path first (destructive). (default: false)
auto_layout	boolean	no	Auto-position every node by dependency (longest-path columns, left→right) from the spec's inputs graph, overriding any per-node x/y. False (default) honors manual x/y only. (default: false)

create_envelope_follower mutates

EXPERIMENTAL — Build a reactive signal-shaping chain (attack/release envelope + threshold gate or sidechain ducking) from a CHOP channel, for 'pump the whole layer on every kick' or similar sidechain effects. Creates a container with: a Select CHOP isolating the source channel by absolute path (no cross-container wire), a Lag CHOP shaping the attack/release envelope, a Logic+Math CHOP threshold gate (gate mode: silence the output below threshold) or an inverted Math CHOP (duck mode: output dips to 0 on a hit, rises on silence — classic sidechain pumping), and a Null CHOP as the stable output handle. Optionally binds the shaped output to target parameters by expression. The gate threshold uses a Logic CHOP whose par names (convert/boundmin/boundmax) match detect_onsets — but these are UNVERIFIED across TD builds; gate reads near 0 at the 0.2 default with most sources — tune threshold live. Use bind_to_channel with attack/release for a simpler Lag-only envelope without a gate.

Parameter	Type	Required	Description
parent_path	string	no	Where to build the follower chain (a COMP path, e.g. '/project1'). (default: /project1)
name	string	no	Base name for the container COMP that holds the chain. (default: envelope_follower)
source_chop	string	yes	Path of the CHOP carrying the trigger channel (e.g. '/project1/audio/features' or an onset Null).
channel	string	yes	Channel name to follow from source_chop (e.g. 'bass', 'kick', 'level'). The Select CHOP isolates it by name.
attack	number	no	Envelope rise time in seconds — how quickly the output climbs after a hit (fast = punchy, e.g. 0.001–0.05). (default: 0.01)
release	number	no	Envelope fall time in seconds — how slowly the output decays after the signal drops (slow = smooth tail, e.g. 0.1–0.8). (default: 0.3)
threshold	number	no	Gate threshold [0–1]. Below this level the output is silenced (gate) or held at 1 (duck). Start low (0.05–0.2) and raise if false triggers occur. NOTE: gate thresholding uses a Logic CHOP whose par names may vary by TD build — EXPERIMENTAL. (default: 0.2)
mode	gate | duck	no	gate: pass the shaped envelope only while it is above threshold — silences the output when the signal is quiet. duck: sidechain/ducking — the output dips toward 0 on every hit and returns to 1 on silence (inverted gate, classic pumping compressor feel). (default: gate)
targets	string[]	no	Optional list of 'nodePath.parName' targets to bind to the shaped envelope output by expression. Omit to just build the chain (the Null CHOP output can be bound later with bind_to_channel). (default: ``)

create_midi_map mutates

HARDWARE-GATED SCAFFOLD. Build a MIDI controller preset for a supported device (apc_mini / launchpad / midi_mix / nanokontrol / generic): creates a midiinCHOP + a labeled bind Table DAT, and optionally auto-binds faders/knobs to a target COMP's numeric custom parameters. Explicit bindings can override or supplement the preset. CC/note numbers are best-effort from published MIDI charts and MUST be validated with real hardware — actual assignments depend on device firmware. This tool is HELD FROM RELEASE until hardware validation is complete. For one-at-a-time MIDI learn of a single control, use learn_control instead.

Parameter	Type	Required	Description
parent_path	string	no	COMP to create the MIDI map inside. (default: /project1)
name	string	no	Name for the MIDI In CHOP node created under parent_path. (default: midi_map)
device	apc_mini | launchpad | midi_mix | nanokontrol | generic	no	Controller preset. Each preset embeds a best-effort CC/note map for that device (UNVERIFIED — real numbers depend on firmware; validate with hardware). 'generic' builds a bare MIDI In + a template bind table with no preset. (default: nanokontrol)
target	string	no	COMP whose custom numeric params/cues the preset auto-binds faders/knobs onto. Faders bind to the first N float/int custom pars; pads look for matching cues. Auto-binding is best-effort and hardware-gated.
bindings	object[]	no	Explicit control→param/cue overrides. Applied after the preset auto-map. Omit to rely entirely on the device preset's default map. (default: ``)

create_modulators destructive

Build a bank of N BPM-synced LFOs in one self-contained container — each an oscillator (sine/triangle/saw/square or a random sample-&-hold) with its own rate-in-beats, output range and phase offset. Every rate locks to a tempo source (a create_tempo_sync Null, or TouchDesigner's global tempo) by expression, so the whole bank speeds up/slows down with the music and stays phase-continuous across tempo changes. All outputs land on one Null CHOP (mod_out) with one named channel per modulator, ready for bind_to_channel — the 'everything breathes' lever. Note: modulators are timeline-driven, so they only move while the timeline is playing. Re-running with an existing container name rebuilds it in place (clearing that container's children), so this tool is marked destructive and hidden from the safe profile.

Parameter	Type	Required	Description
name	string	no	Name of the self-contained modulator-bank container. (default: modulators)
parent_path	string	no	Parent COMP the 'modulators' container is created inside. (default: /project1)
modulators	object[]	yes	The modulators (LFOs) to build. Each becomes one named output channel on the bank's Null.
tempo_source	string	no	Path to an existing tempo Null/Beat CHOP carrying a 'bpm' channel (e.g. the Null from create_tempo_sync, '/project1/tempo_sync/tempo'). Omit to create a fresh Beat CHOP locked to TouchDesigner's global tempo inside the bank.
bpm_channel	string	no	Name of the BPM channel on the tempo source to lock rates to. (default: bpm)
expose_controls	boolean	no	Expose a live custom-parameter page on the bank: a master Rate multiplier and a master Depth (amplitude) scale, so you can speed up or flatten the whole bank from one knob during a show. (default: true)

create_look_bank mutates

A playable snapshot row: store N named 'looks' (snapshots of a control COMP's numeric/toggle/menu parameters) in a visible, editable Table DAT, with one momentary recall button per slot (snap or crossfade) plus a master A↔B morph knob that blends continuously between two chosen looks. Reuses manage_cue's morph engine (so a recall behaves exactly like a cue morph, with optional beat/bar quantize) and mirrors slots into the COMP's cues so they interoperate with manage_cue / create_control_surface. Pulses and strings are always skipped at capture. Build cues/params with create_control_panel first.

Parameter	Type	Required	Description
action	build | store | recall | set_ab | list | delete	no	build: create the look-bank container (Table DAT + A↔B morph knob + recall button row) on a control COMP. store: snapshot the COMP's current numeric look into a named slot. recall: jump or crossfade to a slot. set_ab: assign which two slots the A↔B knob blends, and optionally set the knob. list / delete slots. (default: build)
comp_path	string	no	Control COMP whose custom-parameter values the looks capture (a control-panel container, e.g. from create_control_panel). The look-bank widgets are built inside it; recall drives this COMP's params. (default: /project1)
name	string	no	Name of the look-bank panel container built inside comp_path. (default: look_bank)
slot	string	no	Slot name (required for store / recall / delete).
morph_seconds	number	no	(recall) 0 = snap instantly; >0 = crossfade to the slot over this many seconds (eased), via the cue morph engine. (default: 0)
quantize	off | beat | bar	no	(recall) Defer the snap/crossfade to the next musical boundary (project tempo), so look changes land on the downbeat. Mirrors manage_cue. (default: off)
slot_a	string	no	(set_ab) Slot the A↔B knob reads at value 0.
slot_b	string	no	(set_ab) Slot the A↔B knob reads at value 1.
ab	number	no	(set_ab) Optionally set the A↔B knob position now (0 = slot A, 1 = slot B, 0.5 = halfway). Omit to just (re)assign the slots.
include	string[]	no	(store) Restrict the snapshot to these custom-parameter names. Omit to capture every numeric/toggle/menu parameter (pulses and strings are always skipped).

create_sidechain_pump mutates

EXPERIMENTAL — One-call 'pump the whole rig on the kick': build a sidechain ducking envelope from a trigger CHOP channel and bind multiple target parameters to dip on every hit. Distinct from create_envelope_follower (which builds the chain + optional gate/duck mode with a threshold); this tool is the ergonomic multi-target pump with a single depth knob and a rest_value anchor — ideal for classic pumping compressor feel across many targets at once. Builds a container with: a Select CHOP isolating the source channel by absolute path (no cross-container wires), a Lag CHOP shaping attack/release, a Limit CHOP clamping to [0,1] (type=clamp/min/max, live-validated on TD 099 — guarded with warnings), and a Null CHOP 'pump' as the stable output handle. Each target gets the expression: rest_value * (1 - depth * op('<pump>')[chan0]). Per-target failures become warnings; fatal only if source_chop or parent COMP is missing.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP path where the sidechain pump container is created (e.g. '/project1'). (default: /project1)
name	string	no	Base name for the container COMP that holds the pump chain. (default: sidechain_pump)
source_chop	string	yes	Path of the trigger CHOP (e.g. an onset Null, kick-level CHOP, or audio feature output). This is the signal that drives the pump — high = dip.
channel	string	no	Channel name to follow from source_chop (e.g. 'level', 'kick', 'bass'). The Select CHOP isolates it by name. (default: level)
targets	string[]	no	List of 'nodePath.parName' pairs to bind to the pump output by expression. Each target dips toward rest*(1-depth) on a hit and returns to rest_value on silence. Omit to build the chain only (bind manually with bind_to_channel later). (default: ``)
depth	number	no	How hard the pump dips on a trigger hit [0–1]. 0 = no dip (targets stay at rest_value), 1 = full dip to zero. 0.7–0.9 is typical for a strong pumping compressor feel. (default: 0.8)
attack	number	no	Envelope rise time in seconds — how quickly the pump signal climbs after a hit (controls how snappy the initial dip is). Typical: 0.001–0.02. (default: 0.005)
release	number	no	Envelope fall time in seconds — how slowly the pump returns to silence after the trigger drops. Controls the 'pumping tail'. Typical: 0.1–0.6. (default: 0.25)
rest_value	number	no	The target parameter value at silence (no trigger). On a hit, the expression drives the target toward rest_value*(1-depth). Default 1.0 works for opacity/gain/level parameters. (default: 1)

create_band_router mutates

Split an audio signal into EQ bands and route each band to its own target parameter(s) — the musician-friendly 'bass -> this, highs -> that' patch. Builds a container with: a Select CHOP isolating the source audio by absolute path (no cross-container wire), N audiofilterCHOP band-pass slices tiling the spectrum in log-frequency space (the same audioFilter idiom extract_audio_features uses), an Analyze CHOP per band measuring its level via rmspower, a Merge + Lag smoothing the per-band envelope (release in seconds), and a Null 'bands_out' carrying one channel per band named band0..bandN-1 (band0 = lowest). Each target route binds a band's smoothed level to a parameter by expression (op('<bands_out>')['band<i>'] * scale + offset). The bands_out Null is also directly bind_to_channel-able for routes you add later. EXTENSION sibling of extract_audio_features (that one extracts named features; this one is the band-split + multi-target router). NOTE: the analyze 'rmspower' function value and the channel-rename pars are UNVERIFIED across TD builds — they are set in guarded tries with fallbacks (abs envelope / upstream channel names), and a single audiospectrumCHOP is the fallback if audiofilterCHOP is unavailable; per-item failures surface as warnings rather than failing the build.

Parameter	Type	Required	Description
parent_path	string	no	Where to build the band-router container (a COMP path, e.g. '/project1'). (default: /project1)
name	string	no	Base name for the container COMP that holds the EQ split + router. (default: band_router)
source_chop	string	yes	Path of the raw audio CHOP to split (e.g. an Audio Device In or Audio File In, '/project1/audiodevin1'). REQUIRED.
bands	integer	no	Number of EQ bands to split the signal into (e.g. 4 = sub / low / mid / high). The output Null carries one channel per band, named band0..bandN-1 (band0 = lowest). (default: 4)
targets	object[]	no	Optional band->parameter routes. Each binds one band's smoothed level to a parameter by expression (op('<bands_out>')['band<i>'] * scale + offset). Omit to just build the split (bind later with bind_to_channel against the bands_out Null). (default: ``)
smooth	number	no	Release/lag time in seconds applied to every band level — smooths the per-band envelope so reactivity follows a clean curve instead of flickering on raw audio (e.g. 0.05 punchy, 0.2 smooth). (default: 0.1)

create_xy_pad mutates

Build a draggable 2D (XY) gesture pad — a Container COMP whose pointer drag drives an x/y CHOP of normalized control channels, optionally remapped into ranges and bound by expression to target parameters (e.g. an effect's two main knobs). Add a 3rd (Z) axis via z_target to also get a slider. Open the container in Perform/Panel mode and drag inside it to scrub X/Y live. The pad reads its drag through a Panel CHOP; the u/v drag-channel names are probed at build time (they vary by TD build) and any mismatch is reported as a warning. Leave the axis targets empty to just expose the x/y channels and bind them later with bind_to_channel.

Parameter	Type	Required	Description
parent_path	string	no	COMP path that will hold the XY pad (e.g. '/project1'). (default: /project1)
name	string	no	Name of the container COMP built as the draggable pad. (default: xy_pad)
x_target	string	no	Optional 'nodePath.parName' driven by the X axis. Empty = just expose the x/y channels (bind later with bind_to_channel). (default: ``)
y_target	string	no	Optional 'nodePath.parName' driven by the Y axis. Empty = none. (default: ``)
z_target	string	no	Optional 'nodePath.parName' driven by a 3rd (Z) axis. When set, a slider is added (the pad has no native 3rd axis) and its value0 drives this target. (default: ``)
x_range	number[]	no	Output range [low, high] for X. The pad's normalized u (0..1) is remapped into it. (default: 0,1)
y_range	number[]	no	Output range [low, high] for Y. The pad's normalized v (0..1) is remapped into it. (default: 0,1)
z_range	number[]	no	Output range [low, high] for the optional Z slider (0..1 remapped into it). (default: 0,1)
label_x	string	no	Display label for the X axis (used in the summary). (default: X)
label_y	string	no	Display label for the Y axis (used in the summary). (default: Y)
size	integer	no	Pad size in pixels (square: width = height = size). (default: 400)

create_time_echo mutates

EXPERIMENTAL — Apply a per-pixel time effect to a source TOP: echo trails, slit-scan, or per-pixel time displacement (the 'time machine' melt/slice look). Builds a container COMP that selects the source by absolute path (no cross-container wire) and then, by mode: echo — a feedbackTOP (wired input + forced resolution so the loop is not black) blended over the live frame at opacity=feedback to leave fading ghost trails; slit_scan — a cacheTOP buffering frames and a time-machine TOP reading different rows from different points in time; time_displace — the same cache read back through a luminance gradient (displace_top or a built-in vertical ramp) so bright pixels show older frames. The time-machine read operator is PROBED LIVE (timeMachineTOP → cacheSelectTOP fallback) because the optype name varies by TD build; the feedback opacity par (opacity → fadeval) and cache-depth par (cachesize → maxframes) are also set defensively. Every par/connect failure is collected as a warning and the chain still returns its output Null — UNVERIFIED across TD builds; tune live. Ends with a Null TOP 'out'.

Parameter	Type	Required	Description
parent_path	string	no	Where to build the time-echo chain (a COMP path, e.g. '/project1'). (default: /project1)
name	string	no	Base name for the container COMP that holds the chain. (default: time_echo)
source_top	string	yes	Path of the input TOP to apply the time effect to (e.g. '/project1/moviefilein1' or a Null TOP). REQUIRED.
mode	echo | slit_scan | time_displace	no	echo: recursive feedback trails — each frame leaves a fading ghost (the classic 'echo trails' / time-blur look, driven by feedback). slit_scan: buffer N frames in a cache and read different rows from different points in time (rolling 'time slice' wipe). time_displace: per-pixel time offset driven by a gradient (displace_top) — bright pixels show older frames, dark show newer (the 'time_machine' melt/warp). slit_scan and time_displace both buffer frames in a cacheTOP and read them back with a time-machine TOP. (default: echo)
frames	integer	no	Buffer depth / cache size in frames for slit_scan and time_displace (how far back in time pixels can be pulled). Ignored in echo mode (feedback is recursive, not frame-indexed). Larger = longer time range but more GPU memory. (default: 60)
feedback	number	no	Echo trail strength [0–1] for echo mode — opacity of the fed-back previous frame blended over the current one. Higher = longer, more persistent trails (0.5 = balanced; 0.9+ = very smeary). Ignored in slit_scan / time_displace. (default: 0.5)
displace_top	string	no	time_displace mode only: path of a TOP whose luminance maps each pixel to a time offset (a gradient/ramp/noise — bright = further back in time). Omit to use a built-in vertical ramp (rampTOP) so the effect works out of the box. Ignored in echo / slit_scan. (default: ``)
resolution	number[]	no	Forced output resolution [width, height] in pixels. A fixed resolution is REQUIRED for the feedback path (echo mode) so the loop has a stable frame from cook 0 and does not stay black. (default: 1280,720)

create_capture_loop mutates

Build a bidirectional inter-app video bridge to another program (Resolume, OBS, MadMapper, a game engine…) in one container: receive an external feed IN and publish a TOP OUT at the same time. Picks the right operators per protocol — NDI (network, macOS & Windows), or Syphon (macOS) / Spout (Windows). direction 'in' only subscribes, 'out' only publishes, 'both' runs a full round-trip loop. The receive half is a receiver TOP → Null 'in_out'; the send half pulls source_top through a Select TOP into a publisher TOP. ANTI-FEEDBACK: the two halves are never wired together, so 'both' won't loop this app's own output back in. PLATFORM-GATED & largely UNVERIFIED-live: Spout needs Windows, Syphon needs macOS, and sender/receiver-name parameter names vary by TD build (probed at runtime) — the wrong platform or a real signal needs the actual sender present. This is the combined in+out version of create_live_source (in) and setup_output (out).

Parameter	Type	Required	Description
parent_path	string	no	COMP to build the capture-loop container in (e.g. '/project1'). (default: /project1)
name	string	no	Base name for the container COMP that holds the in/out bridge. (default: capture_loop)
protocol	spout | syphon | ndi	no	Inter-app video transport. ndi works on macOS & Windows (network). spout is Windows-only; syphon is macOS-only — both use the same Syphon/Spout TOPs in TouchDesigner (PLATFORM-GATED: the wrong platform fails to create the op, reported as a warning). (default: ndi)
direction	in | out | both	no	in: only receive an external feed. out: only publish a TOP. both: do both at once (a full round-trip loop to another app, e.g. send to Resolume and receive its output back). (default: both)
sender_name	string	no	(out) The public name THIS app publishes its feed under, so the other app can find it. Used for direction 'out'/'both'. (default: tdmcp_out)
receiver_name	string	no	(in) The name of the EXTERNAL sender to subscribe to. Empty = pick the first available sender on the network/machine. Used for direction 'in'/'both'. (default: ``)
source_top	string	no	(out) Path of the TOP to publish when direction includes 'out' (e.g. '/project1/final'). Empty together with an 'out' direction publishes nothing and is flagged as a warning. (default: ``)
resolution	number[]	no	Working resolution [w, h] applied to the receiver TOP (Output Resolution = Custom). The publisher inherits its input TOP's resolution. (default: 1280,720)

create_auto_montage mutates

Point at a folder and build a self-running clip montage: scans the folder for clips/stills, builds one Movie File In TOP per file feeding a Switch TOP (fractional-index crossfade) → Null TOP, and adds an auto-advance brain on top — a Beat CHOP (clock='beat' or 'bar' with division) or LFO CHOP (clock='interval') drives a CHOP-Execute DAT that picks the next clip per mode (sequential / random / shuffle-no-repeat / weighted) and animates the Switch index with a crossfade. Exposes Play / Index / Next / Prev / Crossfade / Bpm / Division / Mode / Seed custom pars on the container; emits a state_out Null CHOP so bind_to_channel can read clip_index/beat. Folder is read inside TD. Missing folder → empty pointable montage instead of error.

Parameter	Type	Required	Description
name	string	no	Container COMP name. (default: auto_montage)
parent_path	string	no	Where to build it. (default: /project1)
folder	string	yes	Folder on the TD machine to scan for clips/stills.
extensions	string[]	no	Allow-listed extensions (lower-case, no dot). (default: mov,mp4,png,jpg,jpeg,tif,exr)
max_clips	integer	no	Cap clip count. (default: 16)
resolution	object[]	no	Switch TOP output resolution [w,h]. (default: 1280,720)
mode	sequential | random | shuffle | weighted	no	Sequence policy: sequential, random, shuffle (no immediate repeat), weighted (per-clip Weight par). (default: shuffle)
clock	beat | bar | interval	no	Trigger source: beat/bar (Beat CHOP) or interval (LFO CHOP). (default: bar)
bpm	number	no	Tempo when clock=beat|bar. (default: 120)
division	integer	no	Advance every N beats (beat) or N bars (bar). (default: 4)
interval_s	number	no	Seconds between advances when clock=interval. (default: 4)
crossfade	number	no	Crossfade seconds (0 = hard cut). (default: 0.5)
autoplay	boolean	no	Start in playing state. (default: true)
seed	integer | null	no	If set, seeds the RNG (reproducible). (default: null)

create_euclidean_sequencer mutates

Build a Euclidean rhythm sequencer: given pulses evenly distributed across steps via Bjorklund's algorithm (with optional cyclic rotation), it writes the resulting on/off pattern to a Table DAT and fires one dispatch per active step on each beat boundary. The deterministic, mathematically-grounded sibling of create_beat_grid_sequencer — program rhythms by musical intent (e.g. E(3,8) tresillo, E(5,8) cinquillo, E(4,16) four-on-the-floor) rather than by hand-editing cells. Sweep the Pulses/Rotation custom parameters live and the table re-shapes in place. action=param sets a custom parameter to on_value/off_value per step; action=cue recalls a cue per active step (cues stored with manage_cue). NOTE: beat-callback timing is UNVERIFIED offline — check op().time.play if steps don't fire when the TD timeline is paused.

Parameter	Type	Required	Description
name	string	no	Name for the sequencer COMP. (default: euclidean)
parent_path	string	no	Parent COMP path to create the sequencer inside. (default: /project1)
target	string	yes	COMP whose parameter or cue each active step fires on a beat boundary.
steps	integer	no	Number of steps in the Euclidean grid. (default: 16)
pulses	integer	no	Number of active pulses distributed evenly across steps via Bjorklund's algorithm. Clamped to <= steps at build time. (default: 4)
rotation	integer	no	Cyclic rotation of the generated pattern (downbeat offset). (default: 0)
action	param | cue	no	param: set a target custom-parameter value per active step; cue: recall a named cue per active step (cues stored with manage_cue). (default: param)
param	string	no	(action=param) The custom-parameter name on the target COMP to set on each active step.
on_value	number	no	(action=param) Value written into the table cell for active steps. (default: 1)
off_value	number	no	(action=param) Value written into the table cell for inactive steps. (default: 0)
bpm_source	string	no	Path to an existing Beat CHOP or tempo source. Omit to create a new Beat CHOP (on the global TD tempo).

create_preset_morph mutates

Target-agnostic preset morph engine: snapshot any OP's animatable parameters into N named slots, then blend between them with a weight vector (or a single A↔B recall) through a Lag CHOP + Lookup curve, exposing the live blended values on a Null CHOP for bind_to_channel consumers. Unlike create_look_bank (which is scoped to a control COMP's custom pars with a 2-slot A↔B knob), this drives any OP and supports >2 simultaneous weights (normalized internally). Reuses manage_cue's MORPH_HOOK for beat/bar quantized recall. Note: Lag CHOP does not advance while the timeline is paused.

Parameter	Type	Required	Description
action	build | store | recall | set_weights | list | delete	no	build: create the morph container. store: snapshot the target's animatable parameters into a named slot. recall: snap or crossfade the target to one slot. set_weights: drive an N-way weighted blend across all stored slots (vector is clipped to >=0 and normalized). list / delete slots. (default: build)
parent_path	string	no	Parent COMP where the morph container is built. (default: /project1)
name	string	no	Name of the morph container (baseCOMP) created inside parent_path. (default: preset_morph)
target_path	string	no	The node whose parameters are snapshotted and driven (required for build/store). Any OP with animatable numeric/toggle/menu pars.
include	string[]	no	(store) Restrict the snapshot to these parameter names (tuplet names like 'tx', 'feedback'). Omit to capture every animatable numeric/toggle/menu parameter (pulses, strings, file refs are always skipped).
slot	string	no	Slot name (required for store / recall / delete).
weights	object	no	(set_weights) Map of slot-name -> weight. Negatives clipped to 0; the vector is normalized internally (sum -> 1) before lerp. Missing slots default to 0.
morph_seconds	number	no	(recall) 0 = snap; >0 = ease to slot over this many seconds via a Lag CHOP on the weight vector. Note: Lag CHOP does not advance while the timeline is paused. (default: 0)
quantize	off | beat | bar	no	(recall) Defer the snap/crossfade to the next musical boundary (project tempo). Mirrors manage_cue / create_look_bank. (default: off)
interpolation	linear | cosine | cubic	no	Interpolation curve applied to each parameter when crossfading. linear is a straight lerp; cosine/cubic shape the lagged weights through a Lookup CHOP curve. (default: linear)

create_scene_timeline mutates

Build a scrubbable show timeline: a single Timer-CHOP playhead drives ordered scenes that recall cues on a target COMP. Sits above create_cue_sequencer (beat-quantized) and create_scheduler (event-firing) as the show's master clock. Exposes Play/Pause/Stop/Seek/Rate/Loop/Active_Scene custom pars + a playhead Null CHOP (t_seconds, t_norm, scene_idx, scene_t). Consumes the foundation setlist schema: when setlist_path is given, each scene's setlist_slot is mirrored into tdmcp_scenes for downstream tools. Bars→seconds conversion uses BPM 120 + 4 beats-per-bar at build time (no auto-rescale on tempo change).

Parameter	Type	Required	Description
target	string	no	COMP that owns the cues (tdmcp_cues). Store scenes' cues first with manage_cue. (default: /project1)
scenes	object[]	yes	Ordered scene list (sorted by start at build time). Overlaps drive morphs.
units	seconds | bars	no	Input unit for start/duration/morph_in_seconds. 'bars' is converted to seconds at build time using BPM 120 + 4 beats-per-bar (no auto-rescale on tempo change). (default: seconds)
loop	boolean	no	End of last scene → wrap to 0. (default: true)
rate	number	no	Playback rate multiplier (Timer CHOP speed). Exposed as a live custom par. (default: 1)
autoplay	boolean	no	Pulse the Timer's start on cook when true. (default: false)
setlist_path	string	no	OPTIONAL path to a DAT holding the foundation-setlist JSON. When present, scene.setlist_slot is stored alongside each scene in tdmcp_scenes for downstream tools.
name	string	no	Engine COMP name. (default: scene_timeline)
parent_path	string	no	Parent path where the engine COMP lives. (default: /project1)

create_scheduler mutates

Build a Timer-CHOP scheduler COMP: one or more named timers (seconds or beats), each with an optional ordered segment list, sharing a Callbacks DAT that fires a cue/param/script action on onDone and onSegmentEnter. Atomic timer primitive that create_scene_timeline and other automation rides on. Reuses manage_cue's tdmcp_cues storage for the default 'cue' action - store target cues first with manage_cue.

Parameter	Type	Required	Description
timers	object[]	yes	One or more named timers built inside the scheduler COMP. Each becomes a Timer CHOP + segment Table DAT, all sharing one Callbacks DAT.
name	string	no	Name of the scheduler engine COMP (a containerCOMP) created inside parent_path. Re-running with the same name reuses it. (default: scheduler)
parent_path	string	no	Parent COMP path the scheduler COMP is created inside. (default: /project1)
action	cue | param | script	no	What the callbacks fire. 'cue': recall a cue (reuses manage_cue's tdmcp_cues). 'param': set target.par.param. 'script': artist-edited stub. (default: cue)
target	string	no	(action cue/param) COMP the callback acts on. For 'cue', store the cues first with manage_cue.
param	string	no	(action param) Custom-parameter name on target the callback sets.
on_done_value	number	no	(action param) Value written to target.par.param on onDone. (default: 1)
expose_controls	boolean	no	Append an Active toggle on the scheduler COMP, so a dashboard can pause callback dispatch live. (default: true)

create_glsl_material mutates

Create a GLSL MAT under parent_path for custom-shaded geometry. The pixel/vertex/(optional) geometry shader source is placed in companion Text DATs (<name>_pix/_vert/_geo) and wired to the GLSL MAT's pixel/vertex/geometry parameters; numeric uniforms are best-effort bound on the Vectors sequence and samplers on the Samplers sequence. Pixel shader must declare out vec4 fragColor;. Returns the GLSL MAT path, the DAT paths, and warnings for known TD GLSL footguns (missing fragColor, F1/F2 preamble collision, undeclared uTime, sampler bindings needing manual wiring). Artist assigns the MAT to a Geometry COMP via its material par.

Parameter	Type	Required	Description
parent_path	string	yes	Parent COMP to create the GLSL MAT + DATs inside.
name	string	no	Name for the GLSL MAT (default 'glsl_mat1').
pixel_shader	string	yes	GLSL pixel/fragment shader source. Must declare out vec4 fragColor;.
vertex_shader	string	no	Optional GLSL vertex shader source.
geometry_shader	string	no	Optional GLSL geometry shader source.
uniforms	object[]	no	Optional uniform declarations to best-effort bind on the GLSL MAT.
glsl_version	330 | 400 | 410 | 420 | 430 | 440 | …	no	GLSL Version par value. (default: 330)
two_sided	boolean	no	twoside par. (default: false)
lighting_space	world | camera	no	lightingspace par. (default: world)

scaffold_tool_generator mutates

Meta DX tool: scaffolds a new tdmcp tool file (xSchema + xImpl + registerX) and a matching offline msw unit test from a one-line idea. Returns the exact integration-hint (import line + array entry + layer index path) so the integrator can wire it without re-deciding shape. No TouchDesigner bridge call — pure local filesystem generator.

Parameter	Type	Required	Description
name	string	yes	snake_case tool name, e.g. 'create_smoke_field'
layer	layer1 | layer2 | layer3 | library | vault	no	Destination layer directory under src/tools/ (default: layer2)
surface	bridge | layer1_build | prompt | local_only	no	Scaffold template variant (default: bridge)
description	string	yes	One-line MCP tool description
repo_root	string	no	Repo root (default: process.cwd()); for tests use a tmpdir
overwrite	boolean	no	Overwrite existing file if true (default: false)

extend_data_source_fabric mutates

Adds extra transports to the data-source fabric beyond create_data_source: 'mqtt' subscribes to a broker, 'ws-binary' streams binary frames over a WebSocket, 'midi-mmc' listens for MIDI Machine Control transport bytes (play/stop/record/locate). Same downstream shape as create_data_source — a Null DAT for the raw text/bytes and a Null CHOP whose channels are ready for bind_to_channel / create_data_visualization.

Parameter	Type	Required	Description
transport	mqtt | ws-binary | midi-mmc	yes	Which transport branch to build. 'mqtt' subscribes to a broker, 'ws-binary' streams binary frames over a WebSocket, 'midi-mmc' listens for MIDI Machine Control transport bytes.
parent_path	string	no	COMP to build the sub-network inside. (default: /project1)
name	string	no	Base name for the created sub-network.
host	string	no	(mqtt/ws-binary) Broker or WebSocket host. Ignored by midi-mmc. (default: 127.0.0.1)
port	integer	no	(mqtt/ws-binary) TCP port. Defaults: mqtt=1883, ws-binary=9001.
topic	string	no	(mqtt) Subscription topic(s), comma-separated. (ws-binary) URL path, e.g. '/stream'.
username	string	no	(mqtt) Broker auth user.
password	string	no	(mqtt) Broker auth password.
tls	boolean	no	(mqtt/ws-binary) Use TLS — flips mqtts:// or wss://. (default: false)
device	string	no	(midi-mmc) MIDI input device name. Omit to use the first device.
frame_format	float32-le | int16-le | uint8	no	(ws-binary) How each frame's bytes decode into numeric samples. (default: float32-le)
channels	integer	no	(ws-binary) Number of numeric channels per frame to expose on the Null CHOP. (default: 4)
fields	string[]	no	(mqtt) JSON keys to extract from each message into the sample table → Null CHOP channels. (default: value)
expose_controls	boolean	no	Surface an 'Active' toggle (and a 'Reconnect' pulse for mqtt/ws-binary). (default: true)

build_chop_chain mutates

Declarative Layer-2 builder for an ordered CHOP processing chain. Pass an ops list (type + optional name + optional params); each op[i] is wired output 0 → input 0 of op[i+1] under parent (default /project1). Per-op create/param/connect failures become warnings (fail-forward) — a partial chain still returns useful info. Tip: end the chain in a nullCHOP to make it bind_to_channel-ready.

Parameter	Type	Required	Description
parent	string	no	Parent component path. Defaults to /project1. (default: /project1)
name	string	yes	Base name for the chain; used as a name prefix when ops omit name, and as the chain's reported id.
ops	object[]	yes	Ordered list of CHOPs. Each op[i] is wired output 0 → input 0 of op[i+1].

author_script_operator destructive

Scaffold a Script CHOP/DAT/SOP/TOP with a ready-to-edit onCook(scriptOp) stub and optional custom parameters. Creates the Script op plus its companion callbacks DAT, writes a per-family stub (chan/row/point/numpy) — or your on_cook_body — and appends Float/Toggle/Str custom pars inferred from each default's type. Returns {op_path, callbacks_path, params_added, warnings}. Note: Script ops only cook when something requests them, so a paused timeline + no downstream consumer means no cook (not a bug).

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP to create the Script op inside. (default: /project1)
name	string	no	Name for the Script op; TD auto-names when omitted.
family	CHOP | DAT | SOP | TOP	yes	Script op family — selects the operator type and the onCook stub signature.
custom_params	object[]	no	Custom parameters to append on the Script op's 'Custom' page. (default: ``)
on_cook_body	string	no	Optional body for onCook(scriptOp); injected verbatim. When omitted a per-family no-op stub is used.

create_shared_memory_bridge mutates

Create a Shared Memory In/Out TOP/CHOP for zero-copy IPC with another app on the same host (Notch, Unity, Unreal, custom tools). Pick direction ('in' to receive, 'out' to publish), kind (TOP for pixel buffers, CHOP for numeric channels), and a shmName that the peer must match exactly. After creating an Out variant, wire the producer TOP/CHOP into it with connect_nodes. When format.header=false the peer reads a raw headerless buffer — sizes must agree exactly or frames will garble. Some (direction, kind) combos are platform/build-dependent; the tool returns a friendly fatal if the optype isn't available.

Parameter	Type	Required	Description
direction	in | out	yes	'in' = receive from an external app; 'out' = publish to an external app.
kind	TOP | CHOP	yes	TOP = pixel buffer (RGBA frames); CHOP = numeric channels (control / audio-rate).
shmName	string	yes	Shared-memory segment name. Must match exactly on both sides. Two TDs using the same name will collide.
parent	string	no	COMP path to create the operator in. (default: /project1)
name	string	no	Operator name; auto-generated when omitted (e.g. shm_in / shm_out).
format	object	no	Optional format hints. Unknown / unsupported pars on this build become warnings.

build_sop_geometry mutates

Declarative Layer-2 builder for an ordered SOP geometry chain. Pass an ops list (type + optional name + optional params); each op[i] is wired output 0 → input 0 of op[i+1] under parent (default /project1). Per-op create/param/connect failures become warnings (fail-forward) — a partial chain still returns useful info. Tip: end the chain in a nullSOP for a stable handoff to Geometry COMPs, SOP-to-CHOP, or convertSOP. Use connect_nodes for multi-input fan-in (e.g. mergeSOP, copySOP template).

Parameter	Type	Required	Description
parent	string	no	Parent component path. Defaults to /project1. (default: /project1)
name	string	yes	Base name for the chain; used as a name prefix when ops omit name, and as the chain's reported id.
ops	object[]	yes	Ordered list of SOPs. Each op[i] is wired output 0 → input 0 of op[i+1].

sync_timecode mutates

Wire an external SMPTE/MTC/LTC/OSC timecode source into the TouchDesigner timeline. Creates the input op + Math CHOP normaliser + Null CHOP 'tc_out' (channels 'frame' and 'seconds'); optionally adds an Execute DAT that writes project.frame = tc_out['frame'] each cook so the timeline follows house clock. Requires the project to be playing — paused TD will not advance. LTC has no native TD decoder; the tool surfaces a warning and creates the audio input so the artist can attach an external decoder. MTC operator availability is build-dependent.

Parameter	Type	Required	Description
name	string	no	Name prefix for the timecode subsystem COMP (defaults to 'tc_in1').
parent	string	no	COMP to host the timecode subsystem in. (default: /project1)
source	mtc | ltc | osc	yes	Timecode transport: 'mtc' = MIDI Time Code (MIDI In), 'ltc' = Linear Time Code from audio (no native TD decoder — surfaces a warning), 'osc' = OSC In CHOP listening on host:port.
host	string	no	(osc) Bind interface; ignored for mtc/ltc. Defaults to '0.0.0.0'.
port	integer	no	(osc) UDP port (default 7000) or (mtc/ltc) device index (default 0). The device picker can hang on a macOS permission modal — keep the default unless you know the device.
osc_address	string	no	(osc) OSC address pattern carrying the timecode payload. Defaults to '/timecode'.
fps	number	no	Reference frame-rate for SMPTE→frame conversion (24/25/29.97/30).
drive_timeline	boolean	no	When true, an Execute DAT writes project.frame = tc_out['frame'] each cook. Requires the project to be playing — paused TD will not advance. (default: true)
cue_on_label	boolean	no	(osc) If the payload is a string matching a project cue name, call project.cue(name) instead of seeking. (default: false)

apply_lut mutates

Apply a colour Look-Up Table (LUT) to an existing TOP inside a self-contained baseCOMP. Prefers an OpenColorIO TOP for .cube/.3dl/.cc/.ccc files; falls back to a Movie File In + Lookup TOP for image LUTs or when OCIO is unavailable. A .cube file with no OCIO is parsed in Python into a Script TOP ramp. Exposes Strength and Bypass controls on a custom page. Pass source_path to grade an existing TOP, or omit it for a standalone preview on a grey Constant TOP.

Parameter	Type	Required	Description
lut_path	string	yes	Absolute path to the LUT file. Accepts .cube, .3dl, .cc, .ccc (routed to OpenColorIO when available, otherwise parsed in Python for .cube or loaded via Movie File In for image-format LUTs). PNG/EXR/etc. always use the Movie File In + Lookup TOP fallback.
source_path	string	no	Absolute TD path of the existing TOP to grade (e.g. '/project1/render1'). TD wires can't cross COMPs, so the source is pulled in via a Select TOP referencing the absolute path. When omitted, a Constant TOP (mid-grey, 1280×720) is created as a stand-in so the chain cooks and previews standalone.
ocio_config_path	string	no	Optional absolute path to an OCIO config file (.ocio). Only used when the OCIO branch is taken.
strength	number	no	Blend amount between source (0 = untouched) and graded output (1 = full LUT). Drives the Cross TOP crossfade parameter. (default: 1)
bypass	boolean	no	When true, forces the Cross TOP crossfade to 0 so the source passes through unchanged. Also exposed as a toggle on the custom page. (default: false)
prefer	auto | ocio | lookup	no	Branch selection. auto probes OpenColorIO availability at runtime and uses it for .cube/.3dl/.cc/.ccc files, falling back to the Lookup TOP path for images. ocio forces the OCIO branch. lookup forces the Movie File In + Lookup TOP path even when OCIO is available. (default: auto)
expose_controls	boolean	no	When true, appends custom-page parameters Strength (float 0..1) and Bypass (toggle) on the container COMP and binds them to the Cross TOP crossfade. (default: true)
parent_path	string	no	Parent COMP network where the LUT chain container is created. (default: /project1)
container_name	string	no	Base name for the container COMP (a numeric suffix is auto-applied by TD). (default: apply_lut)

create_npr_filter mutates

Apply a non-photorealistic painterly filter to an existing TOP. A generalized Kuwahara (sector-based local variance smoothing) runs in a single GLSL TOP and branches into three looks selected by mode: oil (flat color regions, preserved edges), pencil (graphite sketch via luminance × edge magnitude), or watercolor (quantized chroma + low-frequency bleed). Creates a Select TOP → GLSL TOP → Null TOP chain under parent_path and exposes Radius / Smoothness / Strength as custom parent params bound by expression for live tweaking. Returns the GLSL TOP path, the bind-ready output null path, the fragment DAT path, exposed controls, and an glsl_compile_verified flag (always false offline — verify post-cook with get_td_node_errors).

Parameter	Type	Required	Description
source_path	string	yes	Absolute path of an existing TOP to filter (e.g. '/project1/render1'). Pulled in via a Select TOP (no cross-COMP wire).
parent_path	string	no	Parent COMP path to create the glslTOP + textDAT + nullTOP inside. (default: /project1)
name	string	no	Base name for the glslTOP (textDAT becomes <name>_frag, output becomes <name>_out, source select becomes <name>_src). (default: npr1)
mode	oil | pencil | watercolor	no	Painterly look. oil: full Kuwahara → flat color regions with preserved edges. pencil: luminance + edge-mag → graphite sketch. watercolor: quantize chroma + low-freq bleed. (default: oil)
radius	number	no	Sampling radius in texels. Cost is O(radius² · sectors) — keep modest on 4K. (default: 4)
sectors	4 | 8	no	Number of generalized-Kuwahara sectors. 8 = smoother painterly; 4 = classic Kuwahara (cheaper). (default: 8)
smoothness	number	no	Blend between hard min-variance sector pick (0) and softmax-weighted average across sectors (1). Live control. (default: 0.5)
strength	number	no	Wet/dry mix between source (0) and filtered output (1). Live control. (default: 1)
resolution	input | 720p | 1080p | 4K	no	Output resolution: 'input' inherits from the source (default), or '720p' (1280x720), '1080p' (1920x1080), '4K' (3840x2160). (default: input)

post_passes_3d mutates

Compose a chain of 3D-aware post-processing passes (SSAO, SSR, DOF, motion blur) inside a new baseCOMP. Each pass is a glslTOP with companion textDAT that samples color + depth + (optional) normal/velocity AOVs from selectTOPs. Passes run in fixed order SSAO → SSR → DOF → MB and emit a final null TOP ('out1'). SSR is skipped with a warning when normal_top is empty; motion blur falls back to a directional blur when velocity_top is empty; if color_top points at a renderTOP and depth_top is empty, a sibling depthTOP is auto-created (best-effort). Returns container/output paths, the resolved AOV paths, the enabled passes, and any warnings.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the post-pass container. (default: /project1)
name	string	no	Name of the created baseCOMP container. (default: post_passes_3d)
color_top	string	yes	Absolute path of the beauty-pass TOP (Render TOP / Null TOP).
depth_top	string	no	Absolute path of the depth TOP. Empty = auto-derive from a sibling depthTOP when color is a renderTOP. (default: ``)
normal_top	string	no	Absolute path of the normal-AOV TOP. Empty = SSR is skipped (warning). (default: ``)
velocity_top	string	no	Absolute path of the velocity-AOV TOP. Empty = motion blur falls back to directional. (default: ``)
ssao_enable	boolean	no	(default: true)
ssao_radius	number	no	(default: 0.05)
ssao_intensity	number	no	(default: 1)
ssr_enable	boolean	no	(default: false)
ssr_intensity	number	no	(default: 0.5)
dof_enable	boolean	no	(default: false)
dof_focus	number	no	(default: 0.3)
dof_aperture	number	no	(default: 0.02)
motion_blur_enable	boolean	no	(default: false)
motion_blur_amount	number	no	(default: 0.3)
resolution	object[]	no	(default: 1280,720)

create_flow_abstraction mutates

Build a two-pass Kyprianidis-style flow abstraction: an edge-tangent-flow (ETF) bilateral smoother followed by a flow-based DoG (FDoG) line extractor — oil-painting smooth interiors with crisp coherent ink edges. Creates two glslTOPs + companion textDATs under parent_path, fed by a Select TOP from the source TOP and terminated by a Null TOP. Strength/Edge/Iterations are exposed as live parent-par-bound uniforms; blur radius, sigmas and tau are baked in at build time. Iterations boosts effective ETF strength in-shader (single-input pass, no ping-pong feedback).

Parameter	Type	Required	Description
parent_path	string	yes	Parent COMP path to create the two GLSL TOPs in.
name	string	no	Base name; nodes become <name>_etf, <name>_fdog, <name>_out, plus *_frag textDATs. (default: flow_abs)
source	string	yes	Absolute path of the input TOP to abstract (e.g. '/project1/movie1'). Pulled in via a Select TOP so cross-container wiring is safe.
strength	number	no	Bilateral smoothing strength (0=passthrough, 1=full ETF blur). (default: 0.8)
edge	number	no	FDoG edge gain — multiplier on the DoG response before thresholding. (default: 1)
iterations	integer	no	Number of ETF passes; higher values boost ETF strength via an in-shader uniform. No external feedback loop is created in this version. (default: 2)
blur_radius	integer	no	ETF bilateral kernel half-width in texels along the tangent (kernel ≈ 2*radius+1). (default: 3)
sigma_e	number	no	FDoG inner Gaussian sigma (texels). (default: 1)
sigma_r	number	no	FDoG outer Gaussian sigma — usually ≈ 1.6 * sigma_e. (default: 1.6)
tau	number	no	FDoG center-surround weight. (default: 0.99)
resolution	720p | 1080p | 4K | input	no	Output res; 'input' inherits. (default: input)

create_data_source_http_ws mutates

Advanced live-data ingest for HTTP polling and WebSocket streams — the richer-transport sibling of create_data_source. http_poll: webclientDAT driven by a timerCHOP so polling cadence is a real CHOP signal you can retune/sync; supports custom HTTP method, headers, and body. websocket: websocketDAT with auto-reconnect, persistent connection. Both: JSONPath-lite selectors ($.key, $.key.sub, $.arr[0].field — no wildcards/filters) map response fields to named channels on an output Null CHOP ready for bind_to_channel. Raw body exposed on a Null DAT. Use create_data_source for simple one-knob JSON/CSV polling; use this tool when you need real POST/headers, fine-cadence timer sync, or a WebSocket stream.

Parameter	Type	Required	Description
mode	http_poll | websocket	no	Transport. (default: http_poll)
parent_path	string	no	COMP to build inside. (default: /project1)
name	string	no	Base name for the created baseCOMP; defaults to data_src_<mode>.
url	string	yes	Endpoint URL. http(s)😕/ for http_poll; ws:// or wss:// for websocket. Note: webclientDAT runs inside TD (no browser CORS). wss:// with self-signed certs may silently fail (statusCode 0). JSONPath selector support: $.name, $.key.sub, $.arr[0].field — no wildcards or filters.
method	get | post | put | patch | delete	no	HTTP method. http_poll only; ignored for websocket. (default: get)
headers	object	no	Request headers (http_poll) or connect headers (websocket; best-effort, param may vary by TD build). (default: [object Object])
body	string	no	Request body. http_poll only; caller pre-serializes JSON.
selectors	object[]	yes	JSONPath-lite selectors. Each name becomes a Null CHOP channel and must be unique. path must start with $. Supported: $.key, $.key.sub, $.arr[0], $.arr[0].key. Non-numeric or missing values fall back to 0 with a warning.
poll_seconds	number	no	Polling interval in seconds. http_poll only; drives the timerCHOP cycle. (default: 1)
reconnect_seconds	number	no	Seconds between reconnect attempts. websocket only. (default: 2)
expose_controls	boolean	no	Surface live Active, Poll/Reconnect, and per-selector LastValue readouts. (default: true)
static_sample	object	no	Seed values keyed by selector name. Missing names default to 0.5.

setup_face_tracking mutates

One-shot face-landmark tracking from a webcam: loads the MediaPipe ENGINE (install first with tdmcp install mediapipe-touchdesigner), starts the timeline, and builds an adapter Script CHOP that emits a 468-sample (or 478 with iris) face-landmark CHOP (tx/ty/tz/confidence, centred on nose tip). Feeds directly into bind_to_channel and create_data_visualization.

Parameter	Type	Required	Description
tox_path	string	no	Path to the MediaPipe ENGINE .tox (MediaPipe.tox). Defaults to the package staged by tdmcp install mediapipe-touchdesigner, falling back to ~/tdmcp-packages.
parent_path	string	no	COMP to load the engine into. (default: /project1)
num_landmarks	468 | 478	no	468 = MediaPipe FaceMesh base; 478 adds iris landmarks (10 extra) when iris tracking is enabled in the engine. (default: 468)

setup_hand_tracking mutates

One-shot MediaPipe hand tracking from a webcam: loads the mediapipe-touchdesigner ENGINE (install with tdmcp install mediapipe-touchdesigner), starts the timeline, locates the engine's hand JSON DAT, and builds an adapter Script CHOP that converts the hand JSON into a canonical max_hands×21-landmark CHOP (channels: tx/ty/tz/confidence/handedness). Use coordinate_space='world' for gesture detection (3D, curled fingers separate in z). The output CHOP at <parent_path>/<adapter_name>/hand is ready for bind_to_channel or create_pose_skeleton. Shares the same engine as setup_body_tracking — both can run in the same project.

Parameter	Type	Required	Description
tox_path	string	no	Path to the MediaPipe ENGINE .tox (MediaPipe.tox). Defaults to the package staged by tdmcp install mediapipe-touchdesigner, falling back to ~/tdmcp-packages. The same engine is shared with setup_body_tracking.
parent_path	string	no	COMP to load the engine into. (default: /project1)
max_hands	integer	no	Maximum number of hands tracked (1 or 2). Output CHOP allocates max_hands*21 samples. (default: 2)
coordinate_space	world | image	no	'world' reads worldLandmarks (3D, meters, gesture-safe — curled fingers separate in z). 'image' reads normalised 2D landmarks, centred on the wrist. Use 'world' for gesture detection. (default: world)
adapter_name	string	no	baseCOMP name created under parent_path to house the hand Script CHOP. (default: mp_hand_adapter)

setup_segmentation mutates

One-shot selfie segmentation via the MediaPipe TouchDesigner engine (install with tdmcp install mediapipe-touchdesigner). Loads the engine, enables Selfie Segmentation, and builds an adapter COMP with a clean alpha-mask Null TOP (optionally inverted and/or feathered) plus an optional pre-keyed RGBA Null TOP (person on transparent). Wire the mask into create_keyer, create_depth_silhouette, or any matte-consuming tool. The engine reuses an existing MediaPipe op if already loaded (idempotent). Keep the TD timeline PLAYING so the embedded browser captures the webcam; click Allow if macOS prompts for camera permission.

Parameter	Type	Required	Description
tox_path	string	no	Path to the MediaPipe ENGINE .tox (MediaPipe.tox). Defaults to the package staged by tdmcp install mediapipe-touchdesigner, falling back to the legacy ~/tdmcp-packages path.
parent_path	string	no	COMP to load the engine into. Reuses the existing engine if MediaPipe already exists. (default: /project1)
model	general | landscape	no	Selfie-segmentation model variant. 'general' works at any orientation; 'landscape' is tuned for wide-angle scenes. (default: general)
smooth	boolean	no	Enable the engine's mask temporal smoothing parameter if present. (default: true)
publish_prekeyed	boolean	no	Also build a person_rgba Null TOP (camera × mask) so you can drop 'person on transparent' straight into a comp. (default: true)
invert_mask	boolean	no	Output 1 − mask (useful for background-only effects). Applied via a Level TOP on the mask branch. (default: false)
feather_px	integer	no	Soft-edge blur radius on the mask before publishing (Blur TOP). 0 = hard mask. (default: 2)
name	string	no	Adapter COMP name under parent_path. Defaults to 'mp_segmentation'.

create_hand_gesture_bus mutates

Create a TouchDesigner Base COMP that converts hand landmarks into a stable gesture-control Null CHOP for palm holograms, lasers, audio controls, and other hand-reactive visuals. It creates helper nodes under parent_path, returns the component/output paths and created-node report, and exposes debounced channels such as palm_open, float_x/y, palm_size, pinch_active, pinch_power, scale_target, light_gain, and audio_level. Use source='synthetic' for camera-free previews, source='mediapipe' to build/use setup_hand_tracking, or source='existing_chop' with hand_chop_path when a hand landmark CHOP already exists.

Parameter	Type	Required	Description
source	synthetic | mediapipe | existing_chop	no	Input source: synthetic preview data, a new MediaPipe adapter, or an existing hand CHOP. (default: synthetic)
parent_path	string	no	Parent COMP where the gesture-bus component and helper nodes are created. (default: /project1)
comp_name	string	no	Name for the created gesture-bus Base COMP under parent_path. (default: hand_gesture_bus)
hand_chop_path	string	no	Required only when source='existing_chop'; path to a CHOP with hand landmark channels.
tox_path	string	no	Optional MediaPipe adapter .tox path passed through when source='mediapipe'.
adapter_name	string	no	Name for the setup_hand_tracking adapter when source='mediapipe'. (default: mp_hand_adapter)
max_hands	integer	no	Number of hands to track or synthesize; the gesture bus supports one or two hands. (default: 2)
coordinate_space	world | image	no	Coordinate family expected from the hand source: normalized image space or world space. (default: world)
mirror	boolean	no	Mirror X coordinates for front-facing camera interaction and synthetic previews. (default: true)
smoothing	number	no	Slow smoothing factor for stable palm/float channels; higher values move more slowly. (default: 0.46)
fast_smoothing	number	no	Fast smoothing factor for responsive pinch/power channels; higher values move more slowly. (default: 0.82)
hold_seconds	number	no	Seconds a disappearing/open palm is held before channels fall back. (default: 0.16)
pinch_arm_seconds	number	no	Seconds pinch_active must remain close before it is considered armed. (default: 0.11)
pinch_close_dist	number	no	Thumb-index distance at or below which a pinch closes; must be less than pinch_open_dist. (default: 0.052)
pinch_open_dist	number	no	Thumb-index distance at or above which a pinch opens; must be greater than pinch_close_dist. (default: 0.125)
pinch_radius	number	no	Palm-local radius around the pinch point used to estimate pinch_power. (default: 0.155)
pinch_radius_scale	number	no	Multiplier applied to pinch_radius when converting distance into pinch_power. (default: 2.25)
pinch_threshold	number	no	Normalized pinch_power threshold used to expose binary pinch_active channels. (default: 0.38)
active_hand_lock	boolean	no	Keep the first active hand as the control hand until it is lost, reducing hand switching. (default: true)
expose_controls	boolean	no	Create custom parameters on the component for tuning smoothing, pinch, and lock behavior. (default: true)

create_hand_ableton_mapper mutates

Build a MediaPipe-hands to TDAbleton TDA_Mapper performance control network. It outputs map1=left pinch, map2=right pinch, map3=left wrist roll, map4=right wrist roll, creates a skeleton overlay with star joints plus the thumb-index line, and optionally relinks an existing TDA_Mapper to the generated mapper_send CHOP. Uses TDAbleton directly; AbletonMCP is not required.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP for the mapper network. (default: /project1)
container_name	string	no	baseCOMP created under parent_path. (default: hand_ableton_mapper)
hand_chop	string	no	Existing hand CHOP with tx/ty/tz/confidence/handedness/screen_x/screen_y. Defaults to setup_hand_tracking's adapter output.
ensure_hand_tracking	boolean	no	When hand_chop is omitted, run setup_hand_tracking first. (default: true)
tox_path	string	no	Optional MediaPipe.tox path forwarded to setup_hand_tracking.
adapter_name	string	no	Hand adapter name used by setup_hand_tracking. (default: mp_hand_adapter)
coordinate_space	world | image	no	Coordinate space forwarded to setup_hand_tracking; world is best for pinch distance. (default: world)
hand_count	integer	no	Number of hand slots. (default: 2)
closed_distance	number	no	Distance where thumb/index are treated as closed. (default: 0.025)
open_distance	number	no	Distance where thumb/index are treated as fully open. (default: 0.14)
smoothing	number	no	0=raw, 0.99=very slow smoothing. (default: 0.35)
min_confidence	number	no	Minimum landmark confidence to accept a hand slot. (default: 0.25)
invert_pinch	boolean	no	Invert map1/map2 pinch values. (default: false)
invert_wrist	boolean	no	Invert map3/map4 wrist-roll values. (default: false)
fallback_slots	boolean	no	If handedness is missing, treat slot 0 as left and slot 1 as right. (default: true)
mapper_path	string	no	Optional explicit TDA_Mapper path.
link_mapper	boolean	no	Try to set the TDA_Mapper Oscinputchop/Reorder/range parameters. (default: true)
create_overlay	boolean	no	Create a skeleton overlay TOP with star joints and a thumb-index line. (default: true)
line_width	number	no	Overlay line width. (default: 3)
star_size	number	no	Overlay star-joint size. (default: 0.018)

diagnose_tdableton_mapper mutates

Inspect a TouchDesigner TDAbleton mapper COMP and its source CHOP. Reports common mapper symptoms and can optionally repair Oscinputchop, Reorder, Bypass, and Min/Max parameters without requiring AbletonMCP or a live Ableton connection.

Parameter	Type	Required	Description
parent_path	string	no	Parent COMP/project used when auto-searching for a TDA_Mapper COMP. (default: /project1)
mapper_path	string	no	Optional explicit path to the TDAbleton TDA_Mapper COMP.
source_chop	string	no	CHOP expected to drive the TDAbleton mapper. (default: /project1/hand_ableton_mapper/mapper_send)
expected_reorder	string	no	Expected Reorder parameter value and required source channel list. (default: map1 map2 map3 map4)
repair	boolean	no	If true, apply best-effort mapper parameter repairs inside TouchDesigner. (default: false)

auto_repair_loop mutates

Driver: scan a subtree for cook errors, cluster them, route each cluster to the right fix (calls repair_network for structural/expression/flag issues; surfaces fix_shader / fix_reactivity as prompt hand-offs the agent must execute next turn), re-check, and iterate until clean, no-progress (stalled), or max_iterations (exhausted). Dry-run by default — one planning iteration, no writes. The loop CANNOT fix shaders or dead reactivity itself; it points the agent at them via recommended_prompts. Returns {status, iterations[], errors_before, errors_after, remaining[], recommended_prompts[], warnings}.

Parameter	Type	Required	Description
path	string	no	Root of the subtree to scan + repair. (default: /project1)
max_iterations	integer	no	Hard cap on outer iterations — each iteration = one scan + one route + one apply. (default: 3)
dry_run	boolean	no	When true (default), PLAN routes only (no writes). Propagated to repair_network; the loop runs exactly one iteration in dry-run mode. (default: true)
allowed_fixers	repair_network | fix_shader | fix_reactivity | summarize_td_errors[]	no	Subset of fixers the loop may route to. Drop 'repair_network' to make the loop advisory only (prompts + remaining, no writes). (default: repair_network,fix_shader,fix_reactivity,summarize_td_errors)
min_progress	integer	no	Convergence threshold — if an iteration clears fewer than this many errors, the loop stops (stalled). (default: 1)
include_warnings	boolean	no	When true, treat 'warning' severity errors as in-scope. Default ignores warnings (no-op until the bridge surfaces severity). (default: false)

build_pop_chain mutates

Declarative Layer-2 builder for an ordered POP (Point OPerator) chain. Pass a chain list of { type, name?, params?, extra_inputs? } entries; each chain[i] is wired output 0 → input 0 of chain[i+1] under parent (default /project1). Per-kind safe defaults are applied before user params; unknown par names become warnings (fail-forward). Multi-input POPs (merge, copy, feedback, proximity, switch, blend) accept extra_inputs paths wired into input 1, 2, …. POPs are Experimental — result carries unverified marker. Tip: end the chain in a null_pop for a stable handoff to Wave-3 render rigs.

Parameter	Type	Required	Description
parent	string	no	Parent COMP path (default '/project1'). Same semantic as build_chop_chain. (default: /project1)
name	string	yes	Base name; used as prefix for auto-named ops and as the chain id.
chain	object[]	yes	Ordered POP chain. chain[i] is wired output 0 → input 0 of chain[i+1]; extra_inputs of chain[i] are wired into input 1, 2, …

create_audio_glsl_uniforms mutates

Writes CHOP-reference expressions onto the seq.vec uniform slots of an existing glslTOP, so named channels (low/mid/high/rms etc.) drive shader uniforms every cook. Creates no operators — pure parameter binding. Idempotent and composable with create_glsl_shader.

Parameter	Type	Required	Description
target_glsl_path	string	yes	Path to an existing glslTOP whose seq.vec slots will be bound.
source_chop_path	string	yes	Path to the CHOP whose channels are read (must contain every chan listed in bindings).
bindings	object[]	yes	Channel → uniform/component map. Multiple entries can target the same slot (different components) to build a multi-component uniform.
expand_capacity	boolean	no	If true, grow g.seq.vec.numBlocks to fit the highest slot index. If false, an out-of-range slot is a hard error. (default: true)

connect_comfyui mutates

Bridge a running ComfyUI server: drops the TDComfyUI .tox if installed, otherwise builds a stock webclientDAT skeleton. The container exposes a Null TOP at <container>/out as the downstream output.

Parameter	Type	Required	Description
mode	auto | tox_drop | webclient	no	'auto' tries tox_drop first then falls back to webclient. Force one explicitly when you know which is installed. (default: auto)
parent_path	string	no	COMP that will receive the ComfyUI container. (default: /project1)
name	string	no	Container name; defaults to 'comfyui'.
tox_path	string	no	Explicit .tox path. When omitted, candidates are probed in order: olegchomp/TDComfyUI, JiSenHua/ComfyUI-TD.
server_url	string	no	ComfyUI server base URL — host:port of python main.py --listen. (default: http://127.0.0.1:8188)
workflow_json_path	string	no	Absolute path to a ComfyUI workflow JSON exported from the web UI (Save (API Format)). Required for webclient mode.
source_top_path	string	no	(webclient) TOP whose current frame is sent as the workflow input image via Syphon/Spout re-broadcast.
output_top_name	string	no	Name of the Null TOP exposed inside the container as the downstream output. (default: out)
output_mode	spout | syphon | ndi | file_watch	no	How the generated frame is pulled back into TD. 'file_watch' reloads ComfyUI's output folder via a movieFileInTOP. (default: syphon)
output_source_name	string	no	Spout sender / Syphon server / NDI source name to receive on. Must match the ComfyUI side. (default: ComfyUI)
watch_folder	string	no	(output_mode=file_watch) Folder ComfyUI writes outputs to. The movieFileInTOP cycles the newest file.
poll_interval_seconds	number	no	(webclient) How often to poll /history for completion. (default: 0.5)
active	boolean	no	Start polling / streaming immediately. Default off so the artist can sanity-check first. (default: false)

connect_daydream_cloud mutates

Create a Daydream cloud-hosted StreamDiffusion bridge in TD. A webclientDAT POSTs the encoded source TOP frame to Daydream's REST endpoint; the diffused result is pulled back via a Syphon/Spout/NDI receiver and exposed as a null TOP. API key is read from DAYDREAM_API_KEY in the TD process environment — never inlined. Live probe SKIPPED (requires Daydream account + outbound HTTPS).

Parameter	Type	Required	Description
parent_path	string	no	COMP to create the bridge sub-network in. (default: /project1)
name	string	no	Container name; defaults to daydream_cloud1.
source_top_path	string	yes	TOP whose frames are POSTed to Daydream.
server_url	string	no	Daydream inference endpoint. Override for self-hosted or staging. (default: https://api.daydream.live/v1/stream)
model_id	string	no	Daydream model slug. (default: streamdiffusion-v1)
prompt	string	no	Text prompt sent in the request body. (default: ``)
strength	number	no	Diffusion strength. (default: 0.7)
seed	integer	no	Optional seed.
fps	number	no	Outbound POST cadence; clamped 1–30 (cloud rate-limit guard). (default: 8)
output_mode	syphon | spout | ndi	no	Receiver TOP to instantiate for the relay output. (default: syphon)
output_source_name	string	no	NDI source / Syphon-Spout sender name to subscribe to. (default: daydream_out)
active	boolean	no	Start polling immediately (default off so artist can confirm API key is set). (default: false)
expose_controls	boolean	no	Add custom-page sliders (Prompt, Strength, FPS, Active). (default: true)

create_llm_chain mutates

Stand up a prompt → response LLM chain inside TouchDesigner as a self-contained baseCOMP. Two modes: webclient — stock chain using webclientDAT + textDATs + headers tableDAT that POSTs JSON to any OpenAI-compatible endpoint (OpenAI, Anthropic, Ollama, llama.cpp, LM Studio, OpenRouter). tox_drop — drops the dotsimulate LLM LOPs .tox and wires mirror DATs. Default provider=ollama (fully offline, no key). API keys are read from env inside TouchDesigner (os.environ) and written into a headers tableDAT — the MCP server never sees them. Returns container_path, prompt_dat_path, response_dat_path, status_chan (:busy), provider, model, endpoint_url, and missing_env when a key is needed but unset. Notes: webclientDAT uses reqmethod/url/includeheader (verified live TD 099); body content goes via body_builder textDAT + callbacks. Anthropic uses x-api-key header + anthropic-version, not Authorization; Ollama requires ollama serve running on 127.0.0.1:11434; dotsimulate TOX par names are UNVERIFIED.

Parameter	Type	Required	Description
mode	webclient | tox_drop	no	webclient: stock chain via webclientDAT — no extra dependencies, works with any OpenAI-compatible endpoint. tox_drop: drops the dotsimulate LLM LOPs .tox (requires the TOX installed locally). (default: webclient)
parent_path	string	no	COMP path to build inside. (default: /project1)
name	string	no	Inner baseCOMP name. Defaults to llm_<provider> (webclient) or llm_chain (tox_drop).
provider	openai | anthropic | ollama | custom	no	LLM provider. ollama default — works fully offline, no API key required. custom requires endpoint_url and model. (default: ollama)
endpoint_url	string	no	Override the endpoint URL. Required for provider=custom. Defaults: openai → https://api.openai.com/v1/chat/completions, anthropic → https://api.anthropic.com/v1/messages, ollama → http://127.0.0.1:11434/v1/chat/completions.
model	string	no	Model name. Required for provider=custom. Defaults: openai → gpt-4o-mini, anthropic → claude-sonnet-4-5, ollama → llama3.2.
system_prompt	string	no	Written into a hidden sys textDAT. (default: You are a concise creative assistant for a TouchDesigner live show.)
initial_prompt	string	no	Seeds the Prompt textDAT on creation.
max_tokens	integer	no	Maximum tokens in the response. (default: 512)
temperature	number	no	Sampling temperature [0–2]. (default: 0.7)
json_mode	boolean	no	Set response_format={type:json_object} for openai/ollama compatible endpoints. Ignored for anthropic. (default: false)
auto_request	boolean	no	If true, a datExecuteDAT fires webclient.request() whenever the prompt textDAT changes. Default false — caller drives. (default: false)
tox_path	string	no	Path to the dotsimulate LLM TOX. Required for mode=tox_drop. Also probes Library/LLM.tox and tox/LLM.tox.
expose_controls	boolean	no	Surface Send (Pulse), Model, Temperature, MaxTokens, Active, JsonMode, Provider on the wrapper. (default: true)

add_timecode_overlay mutates

Overlay a running HH:MM:SS:FF timecode (or a countdown) onto an input TOP as VISUAL pixels — a Text TOP whose text expression re-evaluates every frame, composited 'over' the source with a Composite TOP. Modes: clock (show time since project start — NOT the OS wall clock — as HH:MM:SS:FF), count_up (elapsed time since this overlay was built, from zero), count_down (counts down from target_seconds to 00:00:00:00 and clamps there). The formatter lives in a Text DAT module (mod('fmt').tc(...)) so it re-cooks live inside TD. FPS is probed live (me.time.rate -> project.cookRate -> 60 fallback) and reported. Distinct from sync_timecode, which syncs a CLOCK SIGNAL (no pixels) — this tool draws the timecode into the image. Ends with a Null TOP 'out'.

Parameter	Type	Required	Description
source_top	string	yes	Path of the input TOP to overlay the timecode onto (e.g. '/project1/moviefilein1'). REQUIRED.
mode	clock | count_up | count_down	no	clock: show total show time (since project start) as HH:MM:SS:FF. count_up: elapsed time since this overlay was built, from 00:00:00:00. count_down: counts down from target_seconds to 00:00:00:00 and clamps there. (default: count_up)
target_seconds	number	no	count_down only: seconds to count down from. Ignored in clock/count_up modes. (default: 60)
font_size	number	no	Timecode font size in pixels. (default: 48)
color	string	no	Timecode text color as a hex string, e.g. '#ff3366'. (default: #ffffff)
position	top_left | top_center | top_right | bottom_left | bottom_center | bottom_right	no	Where the timecode text is anchored over the source frame. (default: bottom_left)
parent_path	string	no	Where to build the overlay chain (a COMP path, e.g. '/project1'). (default: /project1)
name	string	no	Base name for the container COMP that holds the chain. (default: timecode_overlay)

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

Read-only health check + TouchDesigner server info. Returns {connected, endpoint, touchdesigner version info, knowledge-base stats, bridge_stale?} and changes nothing. Use this first to confirm the bridge is reachable; it succeeds even when TD is offline, reporting connected:false with the reason. Also warns when the running Python bridge is older than this build (a common gotcha — editing td/ doesn't reload the running bridge), pointing you at reload_bridge.

No parameters.

show_preflight_report read-only

Read-only pre-show check: bridge reachability, node errors, topology, cook-time budget, GPU/display topology and perform-mode status in one PASS/UNVERIFIED/WARN/FAIL report. Use before rehearsals or venue handoff to see what is safe, unverified, suspicious, or failing without mutating the project.

Parameter	Type	Required	Description
root_path	string	no	Network root to inspect before a show. (default: /project1)
target_fps	number	no	Frame-rate target for cook-time warnings. (default: 60)
recursive	boolean	no	Inspect nested nodes for topology/performance. (default: true)
include_displays	boolean	no	Include GPU/display/perform-mode checks. (default: true)
include_performance	boolean	no	Include network cook-time budget checks. (default: true)

create_raytk_op mutates

Copy a RayTK ROP master (SDF / camera / light / combine / material / render) into a network and optionally wire an existing op into one of its typed inputs, using the same COMP.copy primitive RayTK's own palette uses. Resolves the install-dependent master path live (RayTK's pathsByOpType lookup, or a category-folder search) — never hardcoded — so it requires the RayTK toolkit staged + loaded first (see manage_packages / the tdmcp://raytk/operators catalog). Complementary to the GLSL create_raymarch_scene: this instances RayTK's own operators instead of authoring a shader.

Parameter	Type	Required	Description
op_type	string	yes	RayTK operator name = the .tox master, e.g. 'sphereSdf', 'raymarchRender3D', 'lookAtCamera', 'pointLight', 'simpleUnion'. See the tdmcp://raytk/operators catalog resource.
category	string	no	Optional RayTK category folder hint to speed master resolution, e.g. 'sdf','output','camera','light','combine','material','filter'. Optional because resolution also works by op_type alone.
parent_path	string	no	Path of the parent COMP the new ROP is copied into. (default: /project1)
name	string	no	Optional node name for the new ROP. If omitted, TouchDesigner auto-uniques from the master name.
node_x	number	no	nodeCenterX placement of the new ROP. Omit to auto-place to the right of existing siblings (avoids stacking repeated ops at the origin).
node_y	number	no	nodeCenterY placement of the new ROP. Omit to auto-place (defaults to 0).
connect_from	string	no	Optional path of an existing operator to wire INTO this new op's input (source → new op). Omit for no wire; must be a non-empty path when present.
input_index	integer	no	0-based input connector index of the NEW op that connect_from wires into (matches TouchDesigner inputConnectors[]). For raymarchRender3D: 0=scene, 1=camera, 2=light. (default: 0)
library_path	string	no	Optional explicit path to the loaded RayTK library COMP (advanced). If omitted, the bridge probes for it — the runtime master path is install-dependent and must be read live, never hardcoded.

create_td_node mutates

Create a single bare operator (node) inside a parent COMP — nothing is wired or laid out. Validates the operator type against the knowledge base and warns (without blocking) on unknown types. Returns {node, warnings[]} for the created node. This is the atomic primitive: for a complete wired+arranged network prefer the higher-level Layer-1 create_* tools (e.g. create_audio_reactive, create_feedback_network).

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

DESTRUCTIVE by default: permanently remove one node from the project by path (a COMP also takes its children with it); this cannot be undone via the API. Prefer mode:'bypass' when you only want to disable a node — it turns the bypass flag on (reversible) instead of destroying it. Returns {deleted|bypassed, mode}. Only call delete mode 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'.
mode	delete | bypass	no	'delete' (default) destroys the node; 'bypass' is the safer, reversible middle ground — it turns the operator's bypass flag on instead of removing it, so the artist can re-enable it with one click. (default: delete)

update_td_node_parameters mutates

Modify an existing node by setting one or more of its parameters to constant values. The update is strict (not best-effort): an unknown parameter name fails the whole call atomically without changing anything, and a bad value (wrong type or out of range) returns an error naming which parameters applied and which failed. On success returns the updated {node}. To inspect valid parameter names/current values first use get_td_node_parameters; to make a parameter move over time use animate_parameter instead of a static value.

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

Read-only: list the DIRECT child nodes of one 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. Returns {count, by_type/sample or paths/nodes}. Use this to browse one level; use find_td_nodes to search recursively and by operator type, or get_td_topology when you also need the connections between nodes. Token economy: keep the default compact summary and scope with pattern; only request the full list when you truly need every path, and avoid re-listing a path you already inspected.

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-only: read the current parameters (and inputs/outputs) of one node. Returns {path, type, name, parameters, inputs, outputs}. Pass keys to project specific parameters or omit_io:true to drop the inputs/outputs lists. Use compare_td_nodes to diff two nodes' parameters at once. Token economy: pass keys to fetch only the parameters you care about and omit_io:true to drop inputs/outputs — a full parameter dump is large.

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)

read_parameter_modes read-only

Read-only: for each parameter of a node, report its mode (CONSTANT / EXPRESSION / EXPORT / BIND), its evaluated value, and its raw expression / bind-expression / export-source strings. Use this to faithfully serialize a network for round-trip editing, diffing, or debugging — the evaluated value alone hides which parameters are driven by expressions or exports. Set non_default_only to surface only the parameters that would be lost in a plain value copy.

Parameter	Type	Required	Description
path	string	yes	Full path of the node whose parameters to inspect.
keys	string[]	no	Only report these parameter names (case-sensitive). Omit for all parameters.
non_default_only	boolean	no	Only return parameters whose mode is not plain constant (i.e. expression/export/bind) — the ones that matter for a faithful round-trip. (default: false)

get_td_node_errors read-only

Read-only: check one node (or, with recursive:true, its whole sub-network) for cook/compile errors and warnings. Pass summary:true for grouped counts instead of the full list. Returns {total, errors[] or by_type}. For a large network prefer summarize_td_errors, which clusters errors by shared cause and points at the worst-offending nodes.

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

Read-only: list TouchDesigner Python API class names from the embedded knowledge base (works offline, never touches TD). Returns {classes[]} of name/displayName entries. Optionally filter by name. Use get_td_class_details or get_module_help to expand one class into its members and methods.

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

get_td_class_details read-only

Read-only: full STRUCTURED documentation for one TouchDesigner Python class (members + methods) from the embedded knowledge base (offline). Returns the class object, or {found:false, suggestions[]} of near-name matches if unknown. Use get_module_help instead when you want the same content as ready-to-read Markdown rather than structured JSON.

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

get_module_help read-only

Read-only: human-readable Markdown help (description, members, method signatures) for a TouchDesigner Python class or module, from the embedded knowledge base (offline). Returns formatted text, or {found:false, suggestions[]} of near-name matches if unknown. Use get_td_class_details instead when you need the same information as structured JSON to process in code.

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

Read-only: report cook times under a network (recursively by default, slowest node first) and warn about nodes that exceed the frame budget. Returns {targetFps, frameBudgetMs, totalCookMs, nodes[], warnings[]} and changes nothing. Use this to just measure; use optimize_performance when you want suggestions and the option to auto-shrink the slow TOPs.

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

Read-only: return the nodes AND the connections (wiring) under a network root, flagging obvious structural issues. Returns {nodeCount, connectionCount, issues[], topology}. Use this when you need how nodes are wired together; use get_td_nodes/find_td_nodes when you only need the node list without connections, or snapshot_td_graph when you also want each node's parameters captured for diffing. Token economy: point it at a specific network root rather than the project root, and leave recursion off unless you need nested networks.

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

find_td_nodes read-only

Read-only: search a network for nodes by name pattern and/or operator type, recursively by default. Returns {count, truncated, matches/paths}. Prefer this over get_td_nodes when you are looking for specific nodes anywhere in a sub-tree (get_td_nodes only lists one COMP's direct children); use get_td_topology when you also need the wiring between them.

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

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. Returns {total, groups[], suggestions[]}. Use this for network-wide triage instead of reading every node's errors one by one; use get_td_node_errors when you just want the raw error list for one node or sub-tree.

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

Read-only: diff the parameters of two nodes, returning only the values that differ (by default). Returns {type_match, differing_count, differing[], same_count}. Useful for aligning settings across similar operators; compares two live nodes, whereas diff_snapshots compares two whole-network snapshots over time.

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

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. Returns {nodeCount, connectionCount, issues[], nodes[], connections[]}. Set compact for a token-cheap whole-COMP read that hoists per-type default parameters and stores only each node's deltas. Feed two of these snapshots to diff_snapshots to see exactly what changed across an edit.

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)
compact	boolean	no	Token-cheap whole-COMP read: hoist each operator type's most-common parameter values into a shared typeDefaults map and store only each node's deltas from them (Embody-style read_tdn). Implies fetching parameters. Use for feeding a large network to an agent without paying for repeated identical values. (default: false)
include_parameter_modes	boolean	no	Also preserve TouchDesigner parameter modes/expressions/binds where available. Compact mode implies this so reactive expressions are not flattened to their current value. (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, exact name, tag/keyword, category, subcategory, parameter metadata, or TouchDesigner version compatibility — ranked by relevance, fully offline by default. 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, summary, facets and optional matching parameters. Pass semantic:true to re-rank fuzzy candidates by embedding similarity (needs an LLM endpoint; falls back to keyword). With parameter_search, matched Menu parameters include their menu options; results are stamped with a data_version (which TouchDesigner build the offline catalog reflects) and a stale_hint when the connected TD is on a different major. Token economy: use a specific query and a small limit; one focused search beats several broad ones.

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)
category	string	no	Optional operator family/category filter, e.g. TOP, CHOP, SOP, DAT, COMP, MAT, or POP.
subcategory	string	no	Optional subcategory filter, e.g. Generators, Filters, Audio, Network, Experimental.
type	fuzzy | exact | tag	no	Search mode: fuzzy searches names/summaries/keywords, exact searches only operator names/display names, tag searches tags and keywords. (default: fuzzy)
parameter_search	boolean	no	Also search operator parameter names, labels and descriptions; matching parameters are returned per hit. (default: false)
version	string	no	Optional stable TouchDesigner version filter, e.g. 099, 2019, 2020, 2021, 2022, 2023, or 2024. Operators with compatibility records added after the target version are excluded.

compare_operator_docs read-only

Read-only: compare two TouchDesigner operator types from the embedded offline knowledge base, including overview metadata plus shared and unique documented parameters. This compares operator documentation, not live node settings; use compare_td_nodes for live node parameter diffs.

Parameter	Type	Required	Description
operator_a	string	yes	First TouchDesigner operator name, display name, or slug.
operator_b	string	yes	Second TouchDesigner operator name, display name, or slug.
include_parameters	boolean	no	Include shared and unique parameter detail arrays in the structured result. (default: true)
parameter_limit	integer	no	Maximum parameter entries to return in each shared/unique parameter list. (default: 30)

get_operator_workflow_guide read-only

Read-only: return an embedded TouchDesigner operator workflow guide with common inputs, outputs, examples, and next-operator suggestions. For unknown operators, returns candidate guide ids instead of failing.

Parameter	Type	Required	Description
operator	string	yes	Operator name, display name, or slug to look up.
include_examples	boolean	no	Include Python examples, expressions, and generated usage patterns. (default: true)
next_limit	integer	no	Maximum number of next-operator suggestions to return. (default: 8)

suggest_operator_chain read-only

Read-only: suggest a small ordered TouchDesigner operator chain for a creative or technical goal from offline operator docs and workflow patterns. Returns connection hints and next tool hints; it does not create nodes.

Parameter	Type	Required	Description
goal	string	yes	Creative or technical goal for the operator chain.
family	string	no	Optional operator family/category preference, e.g. TOP, CHOP, SOP, DAT.
seed_operator	string	no	Optional starting operator name, display name, or slug.
max_steps	integer	no	Maximum number of operators to return in the suggested chain. (default: 5)

validate_operator_chain read-only

Read-only: validate an ordered TouchDesigner operator chain against embedded operator docs, documented connections, family/category filters, and optional TouchDesigner version compatibility. It does not create or modify TD nodes.

Parameter	Type	Required	Description
chain	string[]	yes	Ordered TouchDesigner operator names, display names, or slugs to validate.
family	string	no	Optional expected operator family/category, e.g. TOP, CHOP, SOP, DAT, or POP.
category	string	no	Alias for family; optional expected operator category.
target_version	string	no	Optional target TouchDesigner stable version, e.g. 099, 2023, or 2024.
require_documented_connections	boolean	no	When true, adjacent pairs must be documented by embedded connection guides. (default: false)

draft_recipe_from_operator_chain read-only

Read-only: convert an ordered TouchDesigner operator chain into a RecipeSchema draft without writing files or touching the TD bridge.

Parameter	Type	Required	Description
chain	string[]	yes	Ordered TouchDesigner operator names, display names, slugs, or optypes, e.g. ['Noise TOP', 'Level TOP', 'Null TOP'].
id	string	no	Optional recipe id. Generated when omitted.
name	string	no	Optional recipe display name. Generated when omitted.
description	string	no	Optional recipe description. A chain summary is generated when omitted. (default: ``)
tags	string[]	no	Optional recipe tags. (default: ``)
difficulty	beginner | intermediate | advanced	no	(default: intermediate)
td_version_min	string	no	(default: 2023)
family	string	no	Optional operator family/category constraint, e.g. TOP, CHOP, SOP, DAT.
strict	boolean	no	When true, unresolved operators or family mismatches return an isError result. (default: true)

get_technique_detail read-only

Read-only: inspect embedded TouchDesigner technique packs and individual techniques, with optional code snippets and setup/workflow details.

Parameter	Type	Required	Description
category	string	no	Technique pack category id or display name.
technique_id	string	no	Technique id or name inside the selected category.
include_code	boolean	no	Include code snippets in technique detail results. (default: false)
include_setup	boolean	no	Include setup/workflow guidance in technique detail results. (default: true)

draft_recipe_from_technique read-only

Read-only: convert an embedded TouchDesigner technique with GLSL source into a RecipeSchema draft without writing files or touching the TD bridge.

Parameter	Type	Required	Description
category	string	yes	Technique pack category id or display name.
technique_id	string	yes	Technique id or name inside the selected category.
id	string	no	Optional recipe id override.
name	string	no	Optional recipe display name override.
description	string	no	Optional recipe description override.
tags	string[]	no	Extra recipe tags to append. (default: ``)
difficulty	beginner | intermediate | advanced	no	Optional recipe difficulty override.
td_version_min	string	no	Minimum TouchDesigner version. (default: 2023)
include_glsl_code	boolean	no	Include technique GLSL source in the draft recipe's glsl_code block. (default: true)
strict	boolean	no	Return an error when the technique cannot be converted to a valid draft. (default: true)

draft_recipe_from_tutorial read-only

Read-only: extract a conservative operator chain from an embedded TouchDesigner tutorial and draft a RecipeSchema JSON without writing files or touching the TD bridge.

Parameter	Type	Required	Description
name	string	yes	Tutorial id or display name to draft from.
id	string	no	Optional recipe id override.
recipe_name	string	no	Optional recipe display name override.
description	string	no	Optional recipe description override.
family	string	no	Optional operator family/category constraint, e.g. TOP, CHOP, SOP, DAT.
max_steps	integer	no	Maximum operator references to keep from the tutorial. (default: 5)
tags	string[]	no	Extra recipe tags to append. (default: ``)
difficulty	beginner | intermediate | advanced	no	(default: intermediate)
td_version_min	string	no	(default: 2023)
strict	boolean	no	Return an isError result when no RecipeSchema-valid draft can be produced. (default: true)
include_glsl_code	boolean	no	Include a complete GLSL pixel-shader code block when a GLSL TOP tutorial provides one. (default: true)

get_tutorial read-only

Read-only: list embedded TouchDesigner tutorials, search tutorial metadata/content, or retrieve one by id/name. With include_content, the content is capped (~30K chars) and comes with a sections_available list; pass a section title to drill into just that part instead of pulling the whole document.

Parameter	Type	Required	Description
query	string	no	Optional search text to match against embedded tutorial metadata and content.
name	string	no	Optional tutorial id or name to retrieve.
include_content	boolean	no	When true, include tutorial content (capped, with a sections_available list) in returned entries. (default: false)
section	string	no	With include_content, drill into one section by title (from sections_available) instead of the intro overview — the cheap way to read a long tutorial.
limit	integer	no	Maximum tutorials to return for list and search modes. (default: 10)

search_python_api read-only

Read-only: search TouchDesigner Python API classes, methods and members from the embedded offline knowledge base. Supports class category filters and conservative stable-version compatibility filtering where compatibility metadata exists.

Parameter	Type	Required	Description
query	string	yes	Search query for TD Python classes, methods, or members.
search_in	all | classes | methods | members	no	Where to search: all, classes, methods, or members. (default: all)
category	string	no	Optional Python class category filter, e.g. General or Operator.
limit	integer	no	Max results per group. (default: 20)
version	string	no	Optional stable TouchDesigner version filter, e.g. 099, 2020, 2023, or 2024.

plan_td_version_migration read-only

Read-only: plan a TouchDesigner stable-version migration from offline release highlights plus operator and Python API compatibility records. Returns upgrade boundaries, focused compatibility deltas, and an operator checklist without touching TouchDesigner.

Parameter	Type	Required	Description
from_version	string	yes	Current TouchDesigner stable version, e.g. 099, 2023, or 2024.
to_version	string	no	Target TouchDesigner stable version. Defaults to the current stable release.
query	string	no	Optional project focus terms, e.g. web render, POP, script, DMX.
limit	integer	no	Maximum entries to return in each compatibility section. (default: 25)

search_touchdesigner_knowledge read-only

Read-only: search the embedded TouchDesigner knowledge router across operators, operator workflows, examples, versions, compatibility notes, technique packs, TD classes, and experimental build notes. Returns normalized results with resource URIs and tool hints for deeper lookups.

Parameter	Type	Required	Description
query	string	yes	Search text to route across TouchDesigner knowledge.
surface	all | operators | operator_workflows | operator_examples | versions | operator_compatibility | …	no	Knowledge surface to search: all, operators, operator_workflows, operator_examples, versions, operator_compatibility, python_api_compatibility, techniques, td_classes, or experimentals. (default: all)
limit	integer	no	Maximum number of results to return. (default: 10)

manage_packages destructive

Search, list, inspect, doctor, dry-run install, stage, and uninstall manifest-driven TouchDesigner community packages. Dry-run is the default. Installs stage packages under ~/.tdmcp/packages and only import into TouchDesigner when the bridge is reachable and the package has a safe .tox import path. This tool never runs third-party scripts, pip installs, model downloads, or external app setup.

Parameter	Type	Required	Description
action	search | list | info | doctor | install | uninstall | …	yes	Package-manager action to run.
package_id	string	no	Package id or alias, e.g. 'mediapipe', 'raytk', or 'shader-park-td'.
query	string	no	Search query for action='search'.
installed	boolean	no	For action='list', include installed state. (default: false)
dry_run	boolean	no	For action='install', plan safely without downloading or mutating by default. (default: true)
project_path	string	no	TouchDesigner project COMP for optional live import. (default: /project1)
name	string	no	Optional custom TD node name for live import.
pin	string	no	Optional Git ref/tag to stage instead of the manifest default.
yes	boolean	no	Allow replacement of existing staged files / TD package target when applicable. (default: false)
allow_python_deps	boolean	no	Acknowledge optional Python dependency guidance; does not run pip. (default: false)
allow_external	boolean	no	Acknowledge optional external dependency guidance; does not configure apps/services. (default: false)
packages_root	string	no	Advanced override for package state/cache root. Defaults to ~/.tdmcp/packages.

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 destructive

Scan a network for cook-time bottlenecks and report the slowest nodes with concrete suggestions. By default this is a read-only measurement; with apply=true it mutates flagged TOP resolutions by scale and returns the before/after sizes. Run get_td_performance when you only need metrics; use this tool when you want the bounded resolution change, and leave apply=false for a plan-only pass.

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.

export_render_preset mutates

Start/stop a movie export with named VJ/editorial presets (HAP, HAP Alpha, ProRes 422/4444, NotchLC, MP4 review) while reusing record_movie's Movie File Out TOP recorder. This records a TOP to a file written by TouchDesigner and documents the expected codec/extension/fps for downstream playback tools.

Parameter	Type	Required	Description
action	start | stop	no	Start or stop the preset recording pass. (default: start)
preset	hap | hap_alpha | prores_422 | prores_4444 | notchlc | mp4_review	no	Delivery preset to document and apply. (default: hap)
node_path	string	yes	Path of the TOP to record.
file	string	no	Output movie path on the TD machine. Required for action=start.
fps	number	no	Override the preset frame rate.
seconds	number	no	Optional fixed loop duration. Omit to record until a stop call.

check_operator_availability read-only

Reconcile the operator knowledge base against the RUNNING TouchDesigner's ground-truth creatable-optype list (GET /api/optypes). Flags which documented operators are actually creatable in this build vs deprecated/unavailable, and (optionally) which live optypes the knowledge base doesn't yet document. Pass a single operator name to check just that one. Survives TDMCP_BRIDGE_ALLOW_EXEC=0.

Parameter	Type	Required	Description
operator	string	no	Optional single operator name/optype to check (e.g. 'noiseTOP' or 'Noise TOP'). Omit to reconcile the whole knowledge base against the live TouchDesigner.
include_kb_gap	boolean	no	Also list creatable optypes the live TD exposes that the static knowledge base does not document (build/plugin drift). (default: false)

analyze_project read-only

Diagnose a network for cleanup: report likely-dead operators (zero wired outputs, unreferenced, not displayed), broken external-file dependencies (file parameters pointing at missing files), orphan COMPs, and a dependency map of which operators reference which. Read-only and conservative — every flagged item carries a human-readable reason. Complements plan_visual (which plans a build) and snapshot_td_graph (which dumps structure).

Parameter	Type	Required	Description
path	string	no	Network root to analyze (the COMP whose descendants are scanned). (default: /project1)
recursive	boolean	no	Recurse into child COMPs (true) or only inspect the root's direct children (false). (default: true)

generate_readme read-only

Produce a Markdown project document for any COMP or project: family/type counts, custom-parameter table, inputs/outputs, child inventory, external file dependencies, and an optional preview thumbnail of the output TOP. Use include_mermaid to add a Mermaid flowchart and max_nodes to cap large inventories. Returns the full Markdown on the structured channel under markdown.

Parameter	Type	Required	Description
path	string	no	Path of the project or COMP to document (e.g. /project1 or /project1/myComp). (default: /project1)
title	string	no	Document title. Defaults to the COMP name when omitted.
include_preview	boolean	no	Capture and embed a preview thumbnail of the output TOP as a base64 inline image. (default: true)
include_mermaid	boolean	no	Embed a Mermaid flowchart block in the ## Data flow section. Off by default to keep output compact. (default: false)
max_nodes	integer	no	Maximum child nodes to include in the Child inventory table. Nodes beyond this limit are omitted and a note is appended. Default 200. (default: 200)

edit_dat_content destructive

Surgically replace a substring inside a Text or Table DAT's .text. Without replace_all, requires exactly one match — 0 or >1 occurrences is an error, forcing the caller to add context or set replace_all. Use set_dat_content to overwrite an entire DAT's text in place; use this to make a targeted edit.

Parameter	Type	Required	Description
dat_path	string	yes	Absolute path to the Text or Table DAT to edit (e.g. '/project1/mytext1').
old_string	string	yes	Exact substring to find. Must match at least once. Empty strings are rejected.
new_string	string	yes	Replacement text. May be empty to delete the matched substring.
replace_all	boolean	no	When false (default), requires exactly one match — 0 or >1 occurrences is an error. Set true to replace every occurrence. (default: false)

set_dat_content destructive

Overwrite a Text or Table DAT's entire .text with new content. Unlike edit_dat_content (which makes a surgical find-and-replace), this replaces everything in one shot — use it to deploy a full script or template. Refuses to write empty/whitespace-only text unless confirm_wipe:true is passed, preventing silent data loss.

Parameter	Type	Required	Description
dat_path	string	yes	Absolute path to the Text or Table DAT whose content will be fully replaced (e.g. '/project1/mytext1').
text	string	yes	The full new contents of the DAT. Every existing character will be discarded; this string becomes the entire .text value.
confirm_wipe	boolean	no	Set true to allow writing empty or whitespace-only text, which clears the DAT. When false (default), the tool refuses to write blank content to prevent silent data loss. (default: false)

edit_shader_live_loop destructive

Edit a GLSL/Text DAT and immediately run the practical shader feedback loop: write or surgically replace source text, inspect the shader/output node for errors, and optionally capture a compact inline preview. Uses set_dat_content/edit_dat_content under the hood so DAT write guardrails stay consistent.

Parameter	Type	Required	Description
dat_path	string	yes	Absolute path to the GLSL/Text DAT to edit.
mode	set | replace	no	set overwrites the shader DAT; replace performs a surgical text replacement. (default: set)
shader_code	string	no	Full shader source. Required when mode is set.
old_string	string	no	Substring to find. Required when mode is replace.
new_string	string	no	Replacement text. Required when mode is replace.
replace_all	boolean	no	For replace mode, replace all matches instead of requiring exactly one match. (default: false)
error_path	string	no	Node to inspect for errors after the edit. Defaults to preview_path, then dat_path.
recursive_errors	boolean	no	If true, check errors recursively under error_path. (default: false)
include_preview	boolean	no	Capture a compact inline preview after editing when preview_path is supplied. (default: true)
preview_path	string	no	TOP path to preview after the shader edit, usually the GLSL TOP output or Null TOP.
preview_width	integer	no	Preview width. (default: 256)
preview_height	integer	no	Preview height. (default: 256)
preview_format	jpeg | png	no	Preview encoding. (default: jpeg)
jpeg_quality	integer	no	JPEG quality. (default: 75)
parent_depth	integer	no	Upstream depth for inline-preview error inspection. (default: 1)

set_parameter_expression mutates

Set one or more parameters on a node to an expression, bind expression, or constant value without needing the raw-Python escape hatch. Supports five modes: 'expression' (par.expr = ...), 'bind' (par.bindExpr = ...), 'constant' (par.val = ...), 'reset' (restore the parameter default via par.reset()), and 'unbind' (freeze the current evaluated value as a constant, dropping the driver). Multiple assignments are applied fail-forward — per-item failures accumulate as warnings so a partial batch still returns useful results. Batches using reset/unbind run through the exec path and require TDMCP_BRIDGE_ALLOW_EXEC=1. Use this instead of execute_python_script when TDMCP_RAW_PYTHON is off.

Parameter	Type	Required	Description
path	string	yes	Full path of the node whose parameters to set.
assignments	object[]	yes	One or more parameter assignments.

write_agent_guide mutates

Emit a project-local CLAUDE.md / AGENTS.md seeded with tdmcp operator conventions and TouchDesigner render-coordinate rules, so a future agent working on this project starts with the right mental model. A small dynamic header (project name, node count, top families) is prepended to a curated static body. Pass output_dir to also write the file to disk on the machine running TouchDesigner. The guide is always returned in the structured result.

Parameter	Type	Required	Description
filename	string	no	Name of the guide file to emit, e.g. CLAUDE.md or AGENTS.md. Defaults to CLAUDE.md. (default: CLAUDE.md)
output_dir	string	no	Absolute path on the machine running TouchDesigner where the guide file should be written. If omitted the guide is returned in the result but not written to disk.
path	string	no	TouchDesigner project/COMP path to summarise in the guide header, e.g. /project1. A one-line dynamic summary (node count + top families) is prepended to the static body. (default: /project1)

disconnect_nodes mutates

Remove one or more input wires from a node in TouchDesigner. By default removes every incoming wire into to_path; narrow the scope with from_path (only wires from that upstream node) and/or to_input (only that input slot index). Returns the list of removed wires (input index + upstream node path), a probe of the Connector API attributes seen at runtime, and any per-wire warnings. Fatal only when to_path is not found — partial removals with per-wire warnings still succeed. The inverse of connect_nodes.

Parameter	Type	Required	Description
to_path	string	yes	The downstream node to remove input wire(s) from.
from_path	string	no	Only remove wires coming from this upstream node. Omit to remove ALL input wires into to_path (scoped by to_input if given).
to_input	integer	no	Only clear this input index on to_path (0-based). Omit to clear all inputs.

get_td_node_flags read-only

Read-only: report each node's operator flags (bypass / render / display / lock / allowCooking / clone) plus index-aware input wiring, network position, color and comment — the signals that explain a black/blank output that a parameter dump hides. Scan one node or a subtree (recursive); set only_problems to surface just the ops whose flags or cook errors would suppress output. Returns structuredContent for code to process.

Parameter	Type	Required	Description
path	string	yes	Full path of the node to inspect, or the COMP whose children to scan when recursive is set.
recursive	boolean	no	Also scan the immediate children (depth 1) of path. Use this on a container to diagnose its whole network in one round-trip. (default: false)
only_problems	boolean	no	Return only nodes whose flags or cook errors would suppress output: bypass on, allowCooking off, or a cook error present. Conservative — display/render are reported but never used to filter (they default off on many visible ops). (default: false)
max_nodes	integer	no	Cap the number of nodes scanned during a recursive subtree walk. (default: 200)

get_node_state_runtime read-only

Read-only: inspect a single operator's runtime telemetry — cook time, cook count, last-cook frame, resolution (TOPs), channel/sample counts (CHOPs), GPU memory usage, cook errors, and optional Info CHOP channels via include_info_chop. Complements get_td_performance (which aggregates cook times across a network) by providing deep per-op detail for the 'why is it black / why is it slow' diagnostic loop. Returns {path, type, family, cook_time_ms, cook_count, last_cook_frame, resolution, num_chans, num_samples, gpu_memory, info_chop?, errors[], warnings[], extra}. Attribute names are flagged UNVERIFIED and vary by TD build; the extra map records which attrs were actually present for live confirmation.

Parameter	Type	Required	Description
path	string	yes	Full path of the operator to inspect (e.g. '/project1/noise1').
include_info_chop	boolean	no	When true, create a temporary Info CHOP beside the operator and sample its channels for deeper per-op telemetry. Fail-forward: unreadable Info CHOP data becomes warnings.

watch_node read-only

Read-only: sample one TouchDesigner operator over a short interval and return runtime state, readable parameter values, and CHOP channel values when available. Missing TD attributes/channels are reported as warnings instead of failing the watch. Returns {path, requested_samples, collected_samples, interval_ms, window_ms, warnings[], snapshots[]} where each snapshot has {sample_index, elapsed_ms, path, type, family, state, parameters, channels, warnings}.

Parameter	Type	Required	Description
path	string	yes	Full path of the operator to sample.
samples	integer	no	How many snapshots to collect. (default: 3)
interval_ms	integer	no	Delay between snapshots in milliseconds. (default: 100)
parameter_keys	string[]	no	Optional parameter-name allowlist. Omit to sample all readable parameters.
channel_keys	string[]	no	Optional channel-name allowlist for CHOP-like operators. Omit to sample all channels.

watch_parameter_changes mutates

Opt-in: subscribe to param.changed events for an operator's parameters. When a watched parameter's value changes in TouchDesigner (by a human or a script), the bridge broadcasts a {path, par, prev, value, frame} event on the TD event stream, forwarded to the MCP client as a logging notification. Use action='watch' to register (optionally scoped to named parameters), 'unwatch' to remove, and 'list' to see active watches. Events only arrive when the server's TD event stream is enabled (TDMCP_EVENTS); param.changed is treated as a high-frequency event (coalesced bridge-side so a slider drag can't flood). Survives TDMCP_BRIDGE_ALLOW_EXEC=0.

Parameter	Type	Required	Description
path	string	no	Operator path to watch for parameter changes, e.g. /project1/level1. Required for action='watch'/'unwatch'; omit for action='list'.
parameters	string[]	no	Optional list of parameter names to watch (e.g. ['opacity','level']). Omit to watch every parameter on the operator.
action	watch | unwatch | list	no	'watch' registers a subscription, 'unwatch' removes it (or just the named parameters), 'list' returns all active watches. (default: watch)

get_bridge_logs read-only

Read-only: collect recent cook errors and warnings from the running TouchDesigner project for debugging. Walks the operator tree under scope and gathers each operator's current cook errors and warnings (guaranteed). Also attempts a best-effort probe of textport/log DATs if they exist in the project. Use this when a script or cook fails and you need more context than the immediate error string — it surfaces the real Python traceback or operator cook errors without requiring a new REST endpoint. Returns {lines[], count, probe} where probe reports which log sources were reachable in this TD build.

Parameter	Type	Required	Description
scope	string	no	Network path to collect cook errors/warnings from (default whole project). Must be an existing operator path. (default: /)
max_lines	integer	no	Cap how many log lines to return (1–500). (default: 100)
include_cook_errors	boolean	no	Include current operator cook errors/warnings across the scope. (default: true)

inspect_op_extensions_storage read-only

Read-only: inspect what a COMP exposes — its Python storage dict (keys + values), its extension class descriptors (name, promoted flag, public members), and its custom-parameter definitions (page/name/style/default). Closes the inspect side of the reusable-component loop: use after scaffold_extension + add_custom_parameters to verify what was built, or call standalone to examine any COMP without resorting to raw Python. Returns structured data for agent code-path consumption. API names vary by TD build; the probe field records which attributes were reachable.

Parameter	Type	Required	Description
path	string	yes	COMP to inspect.
include_storage	boolean	no	Include the COMP's Python storage dict (keys + JSON-able values). (default: true)
include_extensions	boolean	no	Include extension classes + promoted members. (default: true)
include_custom_pars	boolean	no	Include custom-parameter definitions (page/name/style/default). (default: true)

serialize_network read-only

Read-only: serialize a COMP's immediate children into a git-diffable JSON spec — each node's name, op type, parameters (with mode + expression, not just the evaluated value), input wires by source node name, and position — plus best-effort custom-parameter definitions. This is the serialize half of a round-trip pair: feed the output spec to rebuild_network to reconstruct the subtree. Use it to snapshot a network as text you can diff across edits or commit to version control. Returns {root, nodes[], truncated?, warnings[]}.

Parameter	Type	Required	Description
path	string	yes	Root COMP whose children to serialize into a diffable spec.
max_nodes	integer	no	Cap nodes serialized. (default: 200)
include_custom_params	boolean	no	Include custom-parameter definitions (best-effort). (default: true)

bundle_dependencies destructive

Make a COMP self-contained: recursively scan its subtree for external file references (movie/image files, fonts, LUTs, externaltox links — reusing the collect_project_assets scan), COPY each existing asset into <out_dir>/assets/, rewrite each referencing parameter in the LIVE network to the copied relative path (assets/<file>), then save the COMP as a .tox beside its assets with a tdmcp-component manifest. The result is a folder you can move to another machine and open without broken links. Delta vs make_portable_tox (which saves the .tox only, leaving external assets behind) and collect_project_assets (which only reports refs). Rewriting mutates the live network — set rewrite_refs=false to copy-and-report without touching parameters.

Parameter	Type	Required	Description
comp_path	string	yes	Full path of the COMP subtree to bundle (assets are gathered recursively).
out_dir	string	yes	Local folder to write the self-contained package into (created if missing). The .tox and an assets/ subfolder land here.
name	string	no	Package/.tox stem. Defaults to the last path segment of comp_path.
rewrite_refs	boolean	no	When true, rewrite each referencing parameter in the LIVE network to the copied relative path (assets/<file>) BEFORE saving the .tox, so the saved component points at the bundled copies. When false, assets are copied but the network is left untouched (a report-and-copy pass). (default: true)
include_missing	boolean	no	If true, still record assets whose source file is missing on disk (they cannot be copied and their ref is not rewritten). If false, missing refs are skipped with a warning. (default: false)

collect_project_assets destructive

Scan a COMP subtree for every external file dependency (movie/image file pars, fonts, LUTs, externaltox links) and report each referenced file, the node+parameter that references it, and whether the file currently exists on disk. The TouchDesigner scan is read-only and copies/rewrites nothing in the network; when out_manifest is set, this tool writes that local JSON path and may overwrite an existing manifest. File-par detection uses par.style ('File'/'Folder') when readable, falling back to a suffix/exact name heuristic (file, fontfile, lut, externaltox, moviefile, imagefile) — both UNVERIFIED across TD builds; style_supported records whether par.style was available.

Parameter	Type	Required	Description
parent_path	string	no	Root of the COMP subtree to scan recursively for external file dependencies. (default: /project1)
out_manifest	string	no	Optional filesystem path to write the JSON asset manifest to. Empty string means do not write a file — just return the inventory. (default: ``)
include_missing_only	boolean	no	When true, only report assets whose referenced file does not exist on disk. (default: false)

project_documentation_site destructive

Compose a one-folder handoff/portfolio documentation PACKAGE for a network: a README.md (title, node count, per-family summary, how-to-load note), a topology.md with a Mermaid graph of the connections, and - when include_thumbnails is set - preview PNGs of output TOPs under thumbs/ linked from gallery.md, all written into out_dir. Unlike generate_readme (a single file), this assembles a small multi-file site folder for sharing or archiving a project.

Parameter	Type	Required	Description
parent_path	string	no	The network to document (project or COMP), e.g. /project1 or /project1/myComp. (default: /project1)
out_dir	string	yes	Folder to write the documentation package into (relative or absolute).
title	string	no	Document title. Defaults to the basename of parent_path when blank. (default: ``)
include_thumbnails	boolean	no	Capture preview PNGs of output TOPs into thumbs/ and link them in gallery.md. (default: false)
max_thumbnails	integer	no	Maximum number of output-TOP previews to capture when include_thumbnails is set. (default: 6)

caption_top read-only

Read-only: render a TOP's preview and return a plain-text description of it — the headless 'is the output alive?' primitive. Two paths: (a) a configured vision LLM endpoint when available, (b) a DETERMINISTIC luma/colour-histogram fallback decoded from the preview PNG pixels (always works, no model needed). Reports dominant colours, mean luma, near-black fraction, a coarse classification ('black'/'very dark'/'dark'/'bright'/'colorful'/'mid'), and a friendly caption. Returns {node_path, width, height, source:'vision'|'histogram', caption, stats{...}, warnings}. Use it after a build to confirm the network is actually rendering instead of a black frame. The vision path is currently inert (no vision field on the tool context) and falls back to the histogram.

Parameter	Type	Required	Description
node_path	string	yes	Path of the TOP to caption.
width	integer	no	Width to render the preview at before describing it. Smaller is faster. (default: 320)
height	integer	no	Height to render the preview at before describing it. Smaller is faster. (default: 180)
use_vision	boolean	no	Use the configured vision LLM endpoint when available; else fall back to a deterministic histogram description. (default: true)

repair_network destructive

Bounded, autonomous repair: scan cook errors under a subtree, classify each, and plan a safe fix, capped at max_steps so it can never run away. Defaults to dry_run (PLAN only, no changes). Set dry_run:false to apply the known-safe fixes — resetting a broken parameter expression to constant mode, and re-enabling a bypassed/display-off op — within the same bound; risky cases (DAT syntax errors, missing inputs, unclassified errors) are always PLAN-only. Re-checks errors after applying and stops at the bound or when errors clear. Returns {parent_path, dry_run, max_steps, errors_before, errors_after, steps[], remaining[], warnings, rolled_back}. Use it as the diagnostic 'try the obvious safe fixes' loop after a build; for raw triage use summarize_td_errors / get_td_node_errors instead.

Parameter	Type	Required	Description
parent_path	string	no	Root of the subtree to scan + repair. (default: /project1)
max_steps	integer	no	Hard cap on repair attempts — the bound that prevents runaway repair. (default: 3)
dry_run	boolean	no	When true (default), only PLAN fixes (no changes applied). Set false to apply within the bound. (default: true)

lint_recipe_library read-only

Offline semantic linter for recipes/*.json. Checks schema, id/filename match, duplicate node names, unknown operator types, dangling connections, bad parents, render-outside-geometryCOMP, missing parameter nodes, unresolved control bind_to, GLSL uniforms on non-GLSL hosts, and hygiene (tags/description/preview_description). Returns a structured report; never calls TouchDesigner.

Parameter	Type	Required	Description
recipe_id	string	no	If set, lint only this one recipe (matched by id); otherwise lint all.
severity	error | warn | info	no	Minimum severity to include in the result. (default: warn)
rules	schema | id_filename_match | duplicate_node_names | unknown_operator | dangling_connection | bad_parent | …[]	no	Subset of rule ids to run; default runs every rule.
fail_on	error | warn | never	no	Severity at which the tool returns isError (CLI maps to exit code). (default: error)

score_build read-only

Read-only: score a built network 0–100 on a fixed rubric (palette/motion/complexity/errors/perf) and return per-criterion sub-scores plus deterministic improvement suggestions. Optional LLM critique when llmCritique=true and ctx.llm is configured. Composes existing bridge endpoints — creates nothing.

Parameter	Type	Required	Description
scopePath	string	no	Network root to score. Defaults to /project1. (default: /project1)
criteria	palette | motion | complexity | errors | perf[]	no	Subset of rubric criteria to evaluate. Final score is the equal-weight mean of the selected ones. (default: palette,motion,complexity,errors,perf)
targetFps	number	no	FPS target used to derive the perf budget (same semantics as get_td_performance). (default: 60)
llmCritique	boolean	no	When true and ctx.llm is configured, attach a short paragraph of artist-readable critique. Best-effort: LLM failure never fails the tool. (default: false)
previewTopPath	string	no	Override the TOP sampled for palette/motion. Defaults to the first /scopePath/out* TOP, then any /scopePath/*_out TOP.

profile_cook_cost read-only

Read-only: sample cook times over a window (N samples × intervalMs) and rank hotspot nodes by p95 cook time. Use this to diagnose intermittent stalls that a single get_td_performance snapshot misses. Returns {path, samples, intervalMs, targetFps, frameBudgetMs, windowMs, hotspots[], warnings[]}.

Parameter	Type	Required	Description
scopePath	string	no	Network root to profile (recursive). (default: /project1)
samples	integer	no	How many snapshots to take across the window. (default: 30)
intervalMs	integer	no	Delay between snapshots in milliseconds (>= one frame at 60fps). (default: 100)
topN	integer	no	How many hotspots to return, ranked desc by p95. (default: 15)
targetFps	number	no	Forwarded to get_td_performance for the per-frame budget annotation. (default: 60)

control_timeline_transport mutates

Drive the TouchDesigner project timeline: play, pause, seek to a frame, jump to a named cue, or set playback rate. Returns the timeline state after the action so a copilot can verify the change took effect. NOTE: pausing will freeze any downstream motion/feedback/frame-diff chain — expected behaviour, not a bug.

Parameter	Type	Required	Description
action	play | pause | seek | cue | rate	yes	Transport verb: play — start playback; pause — stop playback; seek — jump to a frame; cue — jump to a named cue point; rate — set playback rate.
frame	integer	no	Target frame for seek (required when action='seek').
rate	number	no	Playback rate multiplier for rate (required when action='rate'). 1.0=normal, 0.5=half, 2.0=double.
cueName	string	no	Named cue point for cue (required when action='cue').

inspect_gpu_and_displays read-only

Read-only: returns the host GPU info (name, driver, VRAM), attached monitor topology (resolution, refresh rate, primary flag, position), and whether the project is in Perform Mode. Use to plan output mapping, dome rigs, and multi-display shows without leaving the chat. Offline-safe — returns { connected: false, reason } when TD is unreachable.

Parameter	Type	Required	Description
include	gpu | monitors | performMode[]	no	Subset of sections to read; omit for all three.

diagnose_hardware_environment read-only

Read-only: check whether TouchDesigner is reachable, whether display/projector topology matches expectations, and whether generated sensor/helper status DATs such as source_status or bridge_status are healthy. This is a room/hardware preflight for physical installations; it returns PASS/WARNING/FAIL/UNVERIFIED checks without mutating the TD project.

Parameter	Type	Required	Description
expected_min_monitors	integer	no	Optional minimum display/monitor count expected for the room/projector setup.
include	bridge | display | status_surfaces[]	no	Subset of hardware checks to run. Defaults to bridge + display, and also status_surfaces when status_paths is non-empty.
status_paths	string[]	no	Optional DAT paths containing generated status JSON, such as source_status or bridge_status. (default: ``)

manage_component_storage destructive

CRUD operations on a COMP operator's .storage dictionary. Actions: list (all keys+values), get (one key), set (write a key), delete (remove a key). No operators are created; the target COMP must already exist.

Parameter	Type	Required	Description
path	string	yes	Full path of the COMP whose storage dict to operate on.
action	list | get | set | delete	yes	'list' returns all keys+values; 'get' reads one key; 'set' writes one key; 'delete' removes one key.
key	string	no	Storage key. Required for get/set/delete; omit for list.
value	object	no	Value to store under 'key'. Required for set. Must be JSON-serialisable (string, number, bool, list, dict, null).

elicit_missing_args read-only

Use the schema + LLM to propose values for a tool call's missing required args.

Parameter	Type	Required	Description
tool_name	string	yes	Registered tdmcp tool name, e.g. 'create_audio_reactive'.
partial_args	object	no	Args already known. Missing required fields will be elicited. (default: [object Object])
context	string	no	Natural-language context the user gave (a chat message, prompt, etc.).
temperature	number	no	Sampling temperature for elicitation. Low by default for determinism. (default: 0.1)
max_fields	integer	no	Cap on how many missing required fields to elicit in one call. (default: 16)

extract_palette read-only

Sample dominant colors from a TOP by capturing its preview PNG and running deterministic k-means on the decoded RGB pixels. Returns {source_top, k, width, height, pixels_sampled, hex_colors[], swatches[{hex,rgb,weight}], warnings[]} sorted by dominance (most-frequent cluster first). Feeds AI grading prompts, create_palette, and design hand-offs. Read-only; no nodes are created or modified.

Parameter	Type	Required	Description
source_top	string	yes	Path of the TOP to sample colors from.
k	integer	no	Number of palette colors to extract (2..16). (default: 5)
width	integer	no	Width to render the preview at before sampling (smaller is faster). (default: 128)
height	integer	no	Height to render the preview at before sampling. (default: 72)

export_sop_to_svg destructive

Walk a SOP's primitives via the bridge and emit an SVG document of polylines (each primitive becomes one <polyline>). Projects to x/y (drops z), auto-fits viewBox, supports stroke/fill/scale/flip_y. Writes to disk when output_path is supplied and always returns the SVG string in the report. Pen-plotter / laser / print deliverable.

Parameter	Type	Required	Description
source_path	string	yes	SOP path to export (e.g. '/project1/geo1/circle1').
output_path	string	no	Filesystem path to write the SVG to. Absolute is recommended; relative paths are resolved against the server's current working directory. Omit to only return the SVG inline.
stroke_color	string	no	CSS color for polyline strokes (default black). Accepts hex, rgb()/rgba()/hsl()/hsla(), or a named colour; anything that could break out of an SVG attribute is rejected. (default: #000000)
stroke_width	number	no	Stroke width in SVG units. (default: 1)
fill_color	string	no	CSS color for fills (default 'none' — outlines only, plotter-style). Same allowlist as stroke_color. (default: none)
scale	number	no	Scale factor applied to SOP units (TD SOPs are typically [-1..1]). (default: 100)
flip_y	boolean	no	Flip Y so the SVG matches TD's viewport orientation. (default: true)

swap_operator destructive

Change an operator's TYPE while preserving its name, position, incoming + outgoing wires, and any parameters that exist on the new type. Snapshots wires + params, deletes the old node, creates a new node of new_type at the same parent/name/x/y, re-applies matching params (others go into dropped_parameters), and rewires connectors. Fail-forward: per-wire / per-param failures are reported as failed_inputs[] / failed_outputs[] / dropped_parameters[] rather than aborting. Returns {old_type, new_path, preserved_parameters, dropped_parameters, reconnected_inputs, reconnected_outputs, failed_inputs, failed_outputs, warnings}.

Parameter	Type	Required	Description
node_path	string	yes	Path of the node to swap (e.g. '/project1/noise1').
new_type	string	yes	New operator type, e.g. 'rampTOP', 'constantCHOP'.
preserve_parameters	boolean	no	Re-apply parameters that exist (by name) on the new type. (default: true)

copilot_vision read-only

Capture a TOP as a preview image and ask the configured multimodal LLM a question about it. Returns {source_top, question, width, height, answer, model?, stop_reason?, warnings[]}. Uses ctx.llm.complete() with a MultimodalMessage (text + image part). Requires an LLM backend (TDMCP_LLM_BASE_URL / MCP sampling); returns a friendly error otherwise. Different from caption_top, which is deterministic-by-default — this tool ALWAYS routes through the vision model with the artist's custom question.

Parameter	Type	Required	Description
source_top	string	yes	Path of the TOP to send to the vision LLM.
question	string	yes	Question or instruction about the image (e.g. 'what colors dominate?').
width	integer	no	Width to render the preview at before sending. (default: 640)
height	integer	no	Height to render the preview at before sending. (default: 360)
max_tokens	integer	no	Upper bound on response tokens. (default: 512)
system	string	no	Optional system instruction (defaults to a TouchDesigner vision-assistant prompt).

get_inline_preview read-only

Read-only one-shot inspection of a TOP: small base64 thumbnail (default 256² JPEG) + parent error sweep (BFS up parent_depth hops) + top-N changed-from-default parameters + cook stats. One call instead of chaining get_preview / get_td_node_errors / get_td_node_parameters when you just want to know 'is this op alive and healthy?'. Use get_preview/render_output for delivery-grade frames; this thumbnail is intentionally tiny + lossy.

Parameter	Type	Required	Description
path	string	yes	Full path of the TOP to inspect.
width	integer	no	Thumbnail width in pixels (16–1024). Capped — this is for snapshots, not delivery. (default: 256)
height	integer	no	Thumbnail height in pixels (16–1024). (default: 256)
format	jpeg | png	no	Thumbnail encoding. JPEG keeps the payload small (~8–20 KB at 256²); PNG when alpha matters. (default: jpeg)
jpeg_quality	integer	no	JPEG quality 1–100. Ignored when format is png. (default: 75)
parent_depth	integer	no	How many upstream hops to also check for errors. 0 = just path; 1 = path + direct inputs. (default: 1)
max_changed_params	integer	no	Top-N parameters whose value differs from the operator default, ranked alphabetic. 0 = skip. (default: 12)
include_full_params	boolean	no	If true, also include the full parameters object (mirrors get_td_node_parameters). (default: false)

compact_graph_digest read-only

Read-only: compress a TD subtree into a structured digest under max_tokens (default 500). Returns {header, nodeCount, connectionCount, primaryOutput, families{count,topTypes}, outputChain, errors{total,topGroups}, warnings, approxTokens}. Uses getNetworkTopology + getNetworkErrors — no new bridge work. Cheaper than get_td_topology / snapshot_td_graph for planning turns.

Parameter	Type	Required	Description
path	string	no	TD container/subtree path to digest. Defaults to /project1. (default: /project1)
max_tokens	integer	no	Hard ceiling on approximate output tokens (chars/4 heuristic). Default 500. (default: 500)
include_errors	boolean	no	Include top-3 grouped error keys. Off for purely structural turns. (default: true)
include_output_chain	boolean	no	Walk the primary output TOP upstream up to output_chain_depth. (default: true)
output_chain_depth	integer	no	How far upstream to walk from the output TOP. 6 fits typical tails. (default: 6)
family_top_types	integer	no	Per family, list up to N most-frequent operator types. 0 = counts only. (default: 3)

get_dat_content read-only

Read a Text or Table DAT with pagination so a large table cannot flood context. Returns total row/col counts, a header (table DATs), a sliced page (offset/limit), an optional stable head preview (preview_rows), and a row_range only on a partial read. Table DATs are split on tabs/newlines client-side — that split is lossy if a cell embeds a literal tab or newline (probe live before relying on it). Use edit_dat_content/set_dat_content to write.

Parameter	Type	Required	Description
dat_path	string	yes	Absolute path to the Text or Table DAT to read (e.g. '/project1/table1').
offset	integer	no	First data-row index to return (0-based). For a table DAT it indexes data rows (after the header when include_header is true); for a non-table Text DAT it indexes lines. (default: 0)
limit	integer	no	Max rows/lines to return. Capped so a large table never floods context. (default: 100)
preview_rows	integer	no	If > 0, ALSO return the first N rows regardless of offset — a stable head preview alongside a deep page. 0 disables the separate preview. (default: 0)
include_header	boolean	no	For table DATs, treat row 0 as a header: return it in header and make offset/limit index the data rows after it. Set false to treat every row as data. (default: true)

get_parameter_menu read-only

Read-only: for each menu parameter of a node, live-fetch the menu option values (menuNames — the machine values you set with par.val), their human-readable UI labels (menuLabels), and the currently selected value (current). Use this before setting a Menu / StrMenu parameter so you pick a valid option instead of guessing. Values come straight from the running TouchDesigner build, so they are authoritative and even include dynamically-populated menus (device lists, file menus) — an empty menuNames on a known-menu parameter means the menu has not populated yet (the node has not cooked / the device is not enumerated), not that there is no menu. Requires TDMCP_BRIDGE_ALLOW_EXEC=1; when raw exec is unavailable it falls back to the bundled catalog and attaches a stale-catalog warning.

Parameter	Type	Required	Description
path	string	yes	Full path of the node whose parameter menus to read.
keys	string[]	no	Only report these parameter names (case-sensitive). Omit for all menu parameters.
menu_only	boolean	no	Only return parameters that actually have a menu (Menu / StrMenu). Set false to see every parameter with its (usually empty) menu. (default: true)

Library & packaging

Local-first component, recipe and package tooling: browse libraries, inspect manifests, bundle/import recipes, package .tox components, refresh previews, and maintain a local marketplace index.

browse_library read-only

Browse built-in/vault recipes and optional local component packages. Read-only discovery step before instantiating a recipe (apply_recipe) or installing a package (install_library_package); returns the matching recipes and packages so an agent can pick one by name.

Parameter	Type	Required	Description
query	string	no
tags	string[]	no	(default: ``)
package_dir	string	no
include_recipes	boolean	no	(default: true)
include_packages	boolean	no	(default: true)

inspect_component_manifest read-only

Read and validate a tdmcp component/library manifest from a package folder or file. Read-only: use it to check a package's metadata, declared assets, and docs before install_library_package or make_portable_tox; reports validation problems instead of throwing.

Parameter	Type	Required	Description
path	string	yes

make_portable_tox destructive

Save one live TouchDesigner COMP as a portable .tox package on disk, then write a tdmcp-component manifest beside it and optionally copy docs/README files. Use this for packaging a finished component; use bundle_dependencies instead when external media must be collected and relinked. Requires a running bridge and writes/overwrites local files in out_dir; returns the saved .tox path, manifest path, README path, and warnings.

Parameter	Type	Required	Description
comp_path	string	yes	Absolute TouchDesigner COMP path to save, for example /project1/my_component.
out_dir	string	yes	Local output directory that will receive the .tox, manifest, README, and docs.
name	string	no	Optional filesystem-safe package stem; defaults to the COMP name from comp_path.
docs	string[]	no	Optional local documentation files to copy into out_dir/docs and reference in the manifest. (default: ``)
include_readme	boolean	no	Write a package README.md with node inventory, custom parameters, inputs/outputs, and external file references. (default: true)

export_recipe_bundle destructive

Write a portable JSON recipe bundle to out_file. When include_all=false, recipe_ids selects the entries; when include_all=true, the full local library is exported and recipe_ids is ignored. Unknown IDs are reported in missing rather than silently substituted. Use import_recipe_bundle to restore the bundle on another machine or publish_recipe_bundle when you need checksums/versioned handoff artifacts. This writes a local file and returns the bundle kind, version, timestamp, exported recipes, and missing IDs.

Parameter	Type	Required	Description
out_file	string	yes	Destination path for the portable recipe-bundle JSON file.
recipe_ids	string[]	no	Recipe IDs to export when include_all=false; unknown IDs are listed in missing. (default: ``)
include_all	boolean	no	Export the complete local recipe library when true; otherwise export recipe_ids only. (default: false)

publish_recipe_bundle destructive

Write a local, versioned recipe-bundle publish artifact for CI upload or handoff: <name>.recipes.json, tdmcp-recipe-publish.json, and tdmcp-checksums.json. Use recipe_ids for selected recipes or include_all=true for the whole library; overwrite=false protects existing artifacts. This is a filesystem write tool and returns artifact paths, checksum entries, included recipe count, and missing ids.

Parameter	Type	Required	Description
out_dir	string	yes	Local directory where the bundle JSON, publish manifest, and checksum manifest are written.
name	string	no	Filesystem-safe bundle name; becomes <name>.recipes.json after sanitization. (default: recipe-bundle)
version	string	no	Semantic version recorded in the tdmcp-recipe-publish manifest. (default: 0.1.0)
recipe_ids	string[]	no	Recipe ids to include when include_all is false; missing ids are reported in the bundle. (default: ``)
include_all	boolean	no	When true, publish every recipe in the loaded recipe library and ignore recipe_ids. (default: false)
overwrite	boolean	no	When false, fail if any output artifact already exists; set true to replace them. (default: false)

import_recipe_bundle destructive

Import recipes from a portable JSON bundle into a recipe directory. The inverse of export_recipe_bundle: each recipe is validated before it is written, so a malformed bundle fails loudly instead of corrupting the directory. Writes files (destructive).

Parameter	Type	Required	Description
bundle_file	string	yes
out_dir	string	yes
overwrite	boolean	no	(default: false)

validate_library_asset read-only

Check that a local library asset exists on disk and is referenced by an optional manifest. Read-only pre-flight for packaging: catches missing or unreferenced files before make_portable_tox / install_library_package and returns the specific problem rather than failing later.

Parameter	Type	Required	Description
path	string	yes
manifest_path	string	no

scaffold_recipe_template destructive

Write a minimal but valid recipe JSON template to disk as a starting point for a new recipe. Use it to bootstrap a hand-authored recipe that already passes RecipeSchema; fill in nodes/connections, then instantiate with apply_recipe. Writes a file (destructive).

Parameter	Type	Required	Description
out_file	string	yes
id	string	yes
name	string	yes
overwrite	boolean	no	(default: false)

attach_docs_as_assets destructive

Copy documentation files into a package and register them in its manifest's docs list. Use after make_portable_tox to bundle a README or usage notes with a component so they travel with it; writes into the package folder (destructive).

Parameter	Type	Required	Description
manifest_path	string	yes
docs	string[]	yes
asset_dir	string	no	(default: docs)

local_marketplace_index destructive

Scan a local package directory and write an index of installable tdmcp packages. Use it to make a folder of components browsable and installable as a simple local marketplace; the written index is what browse_library and install_library_package consume. Writes a file (destructive).

Parameter	Type	Required	Description
package_dir	string	yes
out_file	string	no

component_link_health read-only

Probe live COMPs in the running project for externaltox paths and report missing or broken linked component files. Read-only diagnostic: run it when externally-linked .tox components may have moved or gone stale, before relying on them in a build.

Parameter	Type	Required	Description
paths	string[]	no	(default: ``)
parent_path	string	no	(default: /project1)

refresh_asset_previews destructive

Capture fresh preview PNG assets from one or more live TOP nodes and write each target to its file_path. Use it to regenerate stale thumbnails after a network changes; pass targets as {node_path,file_path} plus optional width/height. Requires a running TouchDesigner bridge, overwrites image files, and returns written previews plus per-target warnings.

Parameter	Type	Required	Description
targets	object[]	yes	Preview capture jobs; each target maps one live TOP node to one local PNG file.
width	integer	no	Preview width in pixels requested from the bridge capture helper. (default: 640)
height	integer	no	Preview height in pixels requested from the bridge capture helper. (default: 360)

install_library_package destructive

Install a local tdmcp component package folder, .zip, .tox, or manifest into dest_dir/<packageName>. Use inspect_component_manifest first when validating an unknown package; use browse_library after install to discover it. This copies or extracts files on disk, refuses to replace an existing package unless overwrite=true, rejects symlinked directory trees, and returns the resolved source and destination paths.

Parameter	Type	Required	Description
source	string	yes	Local package folder, .zip, .tox, or manifest file.
dest_dir	string	yes	Local tdmcp package library directory; the package is installed under dest_dir/<packageName>.
overwrite	boolean	no	When false, fail if the destination package already exists; set true to replace it. (default: false)

diff_library_assets read-only

Offline deep diff of two saved library assets on disk (recipe JSONs, component manifests, or serialize-network spec JSONs). Reports added/removed keys and changed values (old to new); for recipes it also diffs nodes, per-node params, and connections. Does not touch TouchDesigner. Use diff_snapshots to compare two live TD graphs.

Parameter	Type	Required	Description
a_path	string	yes	First saved library asset on disk (recipe / component manifest / spec JSON).
b_path	string	yes	Second saved library asset to compare against the first (same kind).
mode	auto | recipe | manifest | json	no	How to interpret both files. 'auto' picks by parsing (recipe-aware if both validate against the recipe schema, otherwise a generic deep diff). 'recipe' forces recipe-aware diffing (node/param/connection level). 'manifest' uses the same generic deep object diff as 'json' but reports mode_used='manifest' for component-manifest callers. (default: auto)

export_externalized_tree destructive

Save a COMP as a git-diffable externalized .tox tree using TouchDesigner's 'save external' (COMP.saveExternalTox). Instead of one opaque binary, the component — and, with recurse=true, every descendant COMP — is written to its own .tox file on disk with its externaltox parameter pointed at that file, so a version-controlled project shows per-node diffs. Writes files under out_dir (destructive) and mutates the live COMP's externaltox pars. out_dir is passed to the TouchDesigner process, so it must be a path that process can write to.

Parameter	Type	Required	Description
comp_path	string	yes	Full path of the COMP to externalize (its .tox is written to out_dir/<name>.tox).
out_dir	string	yes	Local folder to write the externalized .tox tree into. Passed to TouchDesigner as the save target, so it must be reachable from the TD process's filesystem.
name	string	no	Root .tox stem. Defaults to the last path segment of comp_path.
recurse	boolean	no	When true, externalize every descendant COMP too (each becomes its own .tox file), so the whole subtree is git-diffable. When false, only the root COMP is externalized. (default: true)

import_recipe_from_url destructive

Fetch, validate, and import a recipe or recipe-bundle JSON from an HTTPS URL into a local recipes directory (host-allowlisted, size-capped).

Parameter	Type	Required	Description
url	string	yes	HTTPS URL of a recipe or recipe-bundle JSON (e.g. a git-raw link).
out_dir	string	yes	Recipe directory to write imported recipes into.
overwrite	boolean	no	Overwrite existing recipe files. (default: false)
max_bytes	integer	no	Maximum download size in bytes (default 1 MiB, hard cap 10 MiB). (default: 1048576)

export_palette_component destructive

Save a COMP as a .tox into TouchDesigner's native Palette folder so it appears in the Palette browser for drag-and-drop reuse.

Parameter	Type	Required	Description
comp_path	string	yes	Path to the COMP to export, e.g. /project1/base1
name	string	no	File stem for the .tox (default: the basename of comp_path)
category	string	no	Palette subfolder to group the component under (default: tdmcp)
palette_dir	string	no	Explicit palette folder to use. Empty resolves TouchDesigner's user palette folder live. (default: ``)

marketplace_index_seed destructive

Write a guarded starter marketplace index JSON with optional built-in seed entries and custom package entries. Use this before local_marketplace_index when planning a local package marketplace; overwrite=false protects existing index files.

Parameter	Type	Required	Description
out_file	string	yes	Path to the seed marketplace JSON file to write.
name	string	no	(default: tdmcp-local-marketplace)
entries	object[]	no	(default: ``)
include_builtin_starters	boolean	no	Include starter package ideas that can be replaced with real local package paths. (default: true)
overwrite	boolean	no	When false, fail if out_file already exists. (default: false)

provenance_stamp mutates

Writes a .provenance.json sidecar next to a saved artifact (tox, recipe note, recipe bundle, component bundle). Records the sha256 checksum, file size, mtime, source COMP path, originating tdmcp tool, toolchain versions, best-effort git metadata, author, tags, and freeform notes. Offline — no TD bridge required.

Parameter	Type	Required	Description
artifact_path	string	yes	Absolute or vault-resolved path to the file to stamp.
artifact_kind	tox | recipe_note | recipe_bundle | component_bundle | other	no	What kind of artifact this is — hint only, not validated. (default: other)
source	object	no	Where/what produced this artifact. (default: [object Object])
author	string	no	Author label. Defaults to TDMCP_AUTHOR env var then os.userInfo().username.
tags	string[]	no	Free-form tags for vault search. (default: ``)
notes	string	no	Short human note to attach to the sidecar.
extra	object	no	Tool-specific extras, e.g. {nodes:7, connections:9}. (default: [object Object])
overwrite	boolean	no	Replace an existing sidecar. Set false to refuse if one exists. (default: true)
include_git	boolean	no	Capture git commit/branch/dirty from the artifact's directory (best-effort). (default: true)

checksum_and_verify_pack mutates

Compute or verify SHA-256 checksums for tdmcp artifacts (.tox, .recipe.json, bundles). action=compute walks a path and writes a tdmcp-checksums.json manifest. action=verify re-hashes files and reports ok/mismatch/missing/extra. No TD bridge required.

Parameter	Type	Required	Description
action	compute | verify	yes
path	string	yes
manifest	object	no
manifest_out	string	no
include_globs	string[]	no	(default: ``)
exclude_globs	string[]	no	(default: **/tdmcp-checksums.json,**/.DS_Store,**/node_modules/**,**/.git/**)
follow_symlinks	boolean	no	(default: false)
max_file_bytes	integer	no	(default: 2147483648)
strict	boolean	no	(default: true)

curated_collection_pack mutates

Bundles a curated, hand-picked set of vault assets (recipes, components, looks, raw assets) into a single portable, shareable pack with provenance + integrity. action=pack gathers items into a <name>.pack/ directory tree with a JSON manifest and checksum manifest. action=unpack restores the tree, optionally verifying integrity. Fully offline — no TD bridge required.

Parameter	Type	Required	Description
action	pack | unpack	yes
name	string	yes	Pack identifier; becomes <name>.pack/ dir name.
out_dir	string	yes	Absolute dir where the pack is written (pack) or restored into (unpack).
pack_path	string	no	unpack only — path to existing <name>.pack/ or its pack.manifest.json.
items	object[]	no	pack only. Files to include. Empty is an error. (default: ``)
vault_path	string	no	Root for resolving relative items[].path. Falls back to TDMCP_VAULT_PATH env.
include_provenance	boolean	no	Copy .provenance.json sidecars if present; else synthesize via provenanceStamp. (default: true)
description	string	no	Free-form note baked into pack.manifest.json.
tags	string[]	no	Pack-level tags for search. (default: ``)
overwrite	boolean	no	Replace existing pack dir (pack) or existing files in out_dir (unpack). (default: false)
verify_on_unpack	boolean	no	unpack only — re-run checksumAndVerifyPack after copy and fail if not OK. (default: true)

component_changelog_trail mutates

Maintains an append-only per-component revision history as a JSONL trail (<component>.trail.jsonl) inside the Obsidian vault, next to the .tox and its provenance sidecar. Three actions: append a new revision entry (with optional sha256 of the .tox, changed-param list, author, and timestamp); read all entries back as JSON; export the trail as a human-readable markdown changelog note rendered into the vault. Offline — no TD bridge required. Pairs with save_component_to_vault and provenance_stamp.

Parameter	Type	Required	Description
componentPath	string	yes	Vault-relative path to the .tox file (e.g. 'Components/MyFx.tox'). The trail is stored as a sibling file '<componentPath>.trail.jsonl'.
action	append | read | export	no	append: add a new revision entry. read: return all entries as JSON. export: render the trail as a markdown changelog note next to the .tox. (default: read)
entry	object	no	Required when action='append'. Ignored for read/export.
includeSha	boolean	no	On append, hash the .tox bytes with sha256 and store it on the entry — lets you cross-reference with provenance_stamp's sidecar. (default: true)
exportNoteName	string	no	On export, the markdown filename (defaults to '<component>.CHANGELOG.md' next to the .tox).

generative_classics_pack destructive

Curated technique pack of canonical generative looks (feedback tunnel, audio spectrum, noise landscape, particle galaxy, reaction-diffusion, webcam glitch). list_only=true returns the technique cards plus the list of recipes the active library can satisfy; list_only=false also writes a portable bundle JSON (import_recipe_bundle-compatible) at install_path. Pure Node — no TouchDesigner bridge required.

Parameter	Type	Required	Description
list_only	boolean	no	When true (default), just list the technique cards + which are available; when false, also emit the portable bundle JSON. (default: true)
install_path	string	no	Where to write the bundle JSON when list_only=false. Defaults to 'recipes/generative_classics.pack.json' inside the cwd.
overwrite	boolean	no	When list_only=false: overwrite an existing bundle file at install_path. (default: false)

CLI automation

Tools that expose local CLI automation workflows, including recording and replaying repeatable TouchDesigner actions.

macro_recorder destructive

Record the sequence of MCP tool calls to a portable JSON macro file. Actions: start | stop | list | load. Replay ships separately as run_macro_script.

Parameter	Type	Required	Description
action	start | stop | list | load	yes
name	string	no
file	string	no
redactSensitive	boolean	no	(default: true)
allowUnsafeRecording	boolean	no	Required when redactSensitive=false because raw scripts/secrets may be persisted. (default: false)

run_macro_script mutates

Replay a MacroRecord JSON file by dispatching each entry through the in-process tool handlers. Use dryRun to plan without invoking, stopOnError to halt on first failure, argsOverrides to shallow-merge per-tool arg replacements, and allowRawPython to opt-in to raw-Python entries (still subject to the server-side ctx gate). Redacted args from a recording may fail at the tool boundary; do not un-redact.

Parameter	Type	Required	Description
macroPath	string	yes
dryRun	boolean	no	(default: false)
allowRawPython	boolean	no	(default: false)
stopOnError	boolean	no	(default: true)
argsOverrides	object	no

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 README plus example recipe, setlist, shader, and moodboard notes) so you begin from a working vault instead of an empty folder. WRITES Markdown files into the vault root and its subfolders; existing files are skipped unless overwrite:true. Run this once when first setting up a vault, before save_recipe_to_vault/import_setlist/etc. Returns the vault root path and the lists of files created vs skipped. Requires a configured 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 an existing COMP's network (child nodes, non-default parameters, wiring, and text/script DAT bodies) by reading TD, then WRITE it as a reusable recipe note in the Obsidian vault at Recipes/<id>.md; list_recipes/apply_recipe then see it alongside the built-in recipes. Use this to turn a patch you already built into a template — to instantiate a template instead, use apply_recipe. Refuses to overwrite an existing note unless overwrite:true. Returns the note path, recipe id, and node/connection counts. Requires a configured 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	One-line summary stored in the recipe note's frontmatter (defaults to empty).
tags	string[]	no	Free-form tags for searching/filtering the recipe later (defaults to none).
difficulty	beginner | intermediate | advanced	no	Skill-level label saved in the recipe metadata (defaults to 'intermediate').
overwrite	boolean	no	When false, refuse to replace an existing Recipes/<id>.md note; set true to overwrite it. (default: false)
preview_top	string	no	Output TOP to thumbnail for the recipe note (e.g. <comp_path>/out1). Defaults to the comp's first/last TOP child; omit a TOP entirely to skip the thumbnail.
thumbnail	boolean	no	Capture a preview PNG next to the recipe note and embed it. Set false to skip. (default: true)
auto_tag	boolean	no	When true, run the auto_tag_library_asset heuristic on the captured network and merge the suggested tags (union, deduped) into the recipe frontmatter before writing.

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 in TouchDesigner from it. Side effect is node creation in TD, not file writes. Use this to apply a shader you keep in the vault; to supply shader code inline instead, use create_glsl_shader. Returns the created GLSL TOP (same result as create_glsl_shader). Requires a configured 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

Bridge a COMP's manage_presets snapshots with the Obsidian vault. With action 'export' it READS TD storage and WRITES a Markdown note (diffable, shareable) under Presets/; with action 'import' it READS that note and WRITES the presets back into TD storage (merging by name). Returns the note path plus the affected preset names. Use this to version-control or share presets across machines; use manage_presets to capture/recall them live. Requires a configured 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

READ an existing TD network's topology and WRITE it as 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. The note (Networks/<path>.md by default) is fully rewritten on each call. Use this to persist a browsable map in the vault; use document_network to get the same documentation back as a tool result without touching the vault. Returns the note path and the node/connection counts (and whether output was truncated). Requires a configured 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

READ a snapshot of a TD network (node/connection counts plus any errors) and, optionally, a preview image of an output TOP, then WRITE a dated journal entry to Performances/<date>-<title>.md in the vault (the thumbnail is saved as a binary attachment). Use this to build a diary of your shows over time. Returns the note path, whether a thumbnail was saved, and the node/issue counts. Requires a configured 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	Thumbnail width in pixels for the captured output_path preview. (default: 640)
height	integer	no	Thumbnail height in pixels for the captured output_path preview. (default: 360)

import_setlist mutates

READ a setlist note (frontmatter tracks: an array of recipe ids or {title, recipe, preset, bpm, notes} objects, OR the newer scenes: an array of {id, cue, recipe, preset, steps, …} scene objects) and build each scene's recipe — CREATING the operators in TouchDesigner under parent_path — to pre-stage a show's visuals. Recipe ids resolve against both built-in and vault recipes; preset-only and cue-only scenes are skipped (recall them live via setlist_runner instead). Use dry_run:true to validate the note without touching TD. Returns the resolved note path and the lists of built vs skipped tracks. Requires a configured 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 in TouchDesigner whose file parameter points at a vault note, so the note's text loads into TD (and, with sync:true, stays live as you edit it in Obsidian) — turning the vault into the text/lyrics source for your visuals. Side effect is node creation in TD plus reading the note file; it does not write to the vault. Wire the DAT into a Text TOP to render it. Returns the DAT path, the resolved note, the absolute file path, and whether sync is on. Requires a configured 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 plus a prose description) and CREATE a matching generative system in TouchDesigner via create_generative_art. Side effect is node creation in TD, not file writes; the palette/mood is passed only as a best-effort color hint. Use this to seed a system from a vault moodboard; call create_generative_art directly to specify the technique and palette inline. Returns the created generative-art network (same result as create_generative_art). Requires a configured 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).

save_component_to_vault mutates

Save a live TouchDesigner COMP as a reusable .tox component file inside the Obsidian vault (at <folder>/<name>.tox) and write a companion markdown note with frontmatter, a description, and load instructions — completing the build→parameterize→script→package-to-library loop. The saved .tox can later be loaded back with manage_component (load action). Requires a configured TDMCP_VAULT_PATH. The target COMP must exist and be a COMP (not a non-COMP operator).

Parameter	Type	Required	Description
comp_path	string	yes	The COMP to package as a reusable .tox component.
name	string	no	Component name (defaults to the COMP's name). Used for the .tox filename and the note title.
folder	string	no	Vault subfolder for the .tox + note. (default: Components)
tags	string[]	no	Tags for the note frontmatter (for browse_vault_library). (default: ``)
description	string	no	A short description stored in the note.
preview_top	string	no	Output TOP to thumbnail for the component note (e.g. <comp_path>/out1). A COMP itself can't be captured (the preview endpoint renders TOPs), so the thumbnail is skipped unless you pass an explicit TOP path here.
thumbnail	boolean	no	Capture a preview PNG next to the component note and embed it. Set false to skip. (default: true)
auto_tag	boolean	no	When true, inspect the COMP's child nodes via the bridge and union the auto_tag_library_asset suggestions into the note frontmatter's tags.

browse_vault_library read-only

Read-only: list the vault's recipes, shaders, presets, components, and setlists with title, tags, and description so the agent can pick from the library without opening individual notes. Filter by category (kinds) and/or a substring query. Returns a flat items array and per-category counts. No TouchDesigner connection required — reads the local vault on disk. Requires a configured TDMCP_VAULT_PATH.

Parameter	Type	Required	Description
kinds	recipes | shaders | presets | components | setlists | all[]	no	Which library categories to list. 'all' lists every known category. (default: all)
query	string	no	Case-insensitive substring filter on note title/tags.

capture_to_vault mutates

Captures a preview still from a TOP and appends it to a dated gallery note in the Obsidian vault, building a visual look-book over time. Each call writes the PNG image under <gallery>/images/ and appends a new section to <gallery>/<note>.md (defaulting to today's date so all daily captures land in one note). Use this to document looks, reference frames, or build a browsable gallery of your session's visuals. Requires a configured TDMCP_VAULT_PATH.

Parameter	Type	Required	Description
node_path	string	yes	TOP to capture a still from.
gallery	string	no	Vault subfolder for the gallery note + images. (default: Gallery)
note	string	no	Gallery note name (defaults to today's date, so captures accumulate into one daily look-book).
caption	string	no	Caption for this capture.
width	integer	no	Capture width. (default: 640)
height	integer	no	Capture height. (default: 360)

export_setlist_to_vault mutates

Serialize the current cues stored on a COMP (manage_cue snapshots, keyed 'tdmcp_cues') into a setlist note in the Obsidian vault, so a live-built show can be round-tripped into the vault library as a git-diffable setlist. The note frontmatter tracks array matches what import_setlist expects — each cue becomes a track with its title and optional bpm, ready for a recipe id to be added by hand. Re-import the note later with import_setlist to rebuild the visuals. Requires a configured TDMCP_VAULT_PATH.

Parameter	Type	Required	Description
target	string	yes	COMP whose stored cues/scenes to export as a setlist.
note	string	yes	Setlist note name to write (e.g. 'Friday Set').
folder	string	no	Vault subfolder (match import_setlist's expected location). (default: Setlists)
include_tempo	boolean	no	Capture the project's global tempo into the note. (default: true)

generate_library_index mutates

Write one Markdown contact-sheet note of the whole vault library — recipes, shaders, presets, components, and setlists — as a grid of cards, each with its thumbnail (the <stem>.png sibling written by save_recipe_to_vault / save_component_to_vault), title, tags, and a copy-paste load snippet (e.g. apply_recipe id=…). No TouchDesigner connection required: it reads the local vault on disk and writes the index note. Filter by category (kinds) and/or a substring query. Requires a configured TDMCP_VAULT_PATH.

Parameter	Type	Required	Description
kinds	recipes | shaders | presets | components | setlists | all[]	no	Which library categories to include. 'all' = every category. (default: all)
output	string	no	Vault-relative path of the contact-sheet note to write. (default: Library Index.md)
include_thumbnails	boolean	no	Embed each asset's <stem>.png sibling when present; false = text-only. (default: true)
columns	integer	no	Cards per row in the contact-sheet grid. (default: 3)
query	string	no	Case-insensitive substring filter on title/tags.
overwrite	boolean	no	When false, refuse to overwrite an existing index note. (default: true)

auto_tag_library_asset mutates

Inspect a captured library asset (a vault recipe/component note, or a live TD COMP) and emit a suggested tag set, difficulty, and one-line description from a deterministic operator-family heuristic; with write:true, merge the suggestion into the note's frontmatter (preserving '*'-pinned user tags). Use this to backfill consistent tags across a library so browse_vault_library can find by category. Requires a configured TDMCP_VAULT_PATH; target='td_comp' additionally requires the bridge.

Parameter	Type	Required	Description
target	vault_note | td_comp	no	What to scan. 'vault_note' reads an existing note via the vault adapter; 'td_comp' captures a live COMP through the bridge. (default: vault_note)
note_path	string	no	Vault-relative path of the note to tag (e.g. 'Recipes/audio_pulse.md'). Required when target='vault_note'; optional for 'td_comp'.
comp_path	string	no	COMP path captured when target='td_comp'. (default: /project1)
category_hint	recipe | component | auto	no	Helps frontmatter shape; 'auto' infers from the note location (Recipes/* vs Components/*). (default: auto)
write	boolean	no	When false, returns the suggestion as a dry-run. When true, merges the suggestion into the note's frontmatter and rewrites it. (default: false)
overwrite_existing_tags	boolean	no	When false, union with existing frontmatter.tags. When true, replace them (user-pinned tags prefixed '*' are always kept). (default: false)
max_tags	integer	no	Hard cap on suggested tag count after ranking. (default: 8)
min_confidence	number	no	Drop suggestions whose score falls below this threshold. (default: 0.35)
include_difficulty	boolean	no	Emit a 'beginner'|'intermediate'|'advanced' estimate from node count + complexity. (default: true)
include_description	boolean	no	Generate a one-line description; only fills frontmatter.description when it is currently empty (never overwritten). (default: true)

recall_similar_work read-only

Read-only vault search: rank past memory notes by similarity to a new visual goal so the agent can reuse prior recipes, params, and prompts instead of rebuilding from scratch. Scores by query-token overlap with title/intent/prompt/tags/body, with optional tag and op boosts. Returns ranked hits with vault paths, score, matched terms, and an optional body snippet. Offline; requires TDMCP_VAULT_PATH.

Parameter	Type	Required	Description
query	string	yes	Free-text goal/prompt to compare past memory notes against.
tags	string[]	no	Optional tags that should boost matching notes (additive). Lowercased before match. (default: ``)
ops	string[]	no	Optional operator types you expect to use (e.g. audioAnalysisCHOP). Boosts notes whose 'ops' overlap. (default: ``)
limit	integer	no	Maximum number of hits to return after sorting. (default: 5)
min_score	number	no	Drop hits whose normalised score is below this threshold. (default: 0.1)
include_body_snippet	boolean	no	When true, return a ~240-char body excerpt around the best-matching line. (default: true)

style_memory mutates

READ or UPDATE the long-lived Memory/style.md note in the configured Obsidian vault — the artist's standing preferences across sessions (palettes, default energy, banned moves, favourite generators, naming/layout conventions, tags). mode='show' returns a compact one-line context string suitable for feeding an LLM, 'read' returns the full structured note, 'update' field-wise merges a patch (lists union+dedup, scalars overwrite) and bumps the updated date. Touches the vault only — no TouchDesigner side effects. Requires TDMCP_VAULT_PATH.

Parameter	Type	Required	Description
mode	show | read | update	no	show: short compact context string (cheap to feed an LLM). read: full structured note. update: field-wise merge a patch (palettes/banned/favorites union+dedup; scalars overwrite). (default: show)
patch	object	no	Patch applied when mode='update'. Ignored for show/read.

library_lineage_graph read-only

Read-only, offline tool that scans the vault library (Recipes, Shaders, Presets, Components, Setlists), extracts lineage frontmatter (parent_recipe, source_assets, remix_of, forked_from), and emits a lineage graph. Output as JSON (machine-consumable), Mermaid (paste into docs), or Graphviz DOT. No TouchDesigner connection required.

Parameter	Type	Required	Description
vault_path	string	no	Absolute path override; falls back to TDMCP_VAULT_PATH.
format	json | mermaid | dot	no	Output format. (default: json)
kinds	recipes | shaders | presets | components | setlists | all[]	no	Categories to scan. 'all' includes every category. (default: all)
cluster_by	none | style_tags | mood | author | difficulty	no	Grouping for Mermaid subgraph / DOT cluster. (default: style_tags)
include_orphans	boolean	no	When false, exclude nodes with no lineage edges. (default: true)
max_nodes	integer	no	Safety cap on nodes returned. (default: 500)

morph_pack mutates

Export an existing create_preset_morph container's slots ('looks') to a portable, sha256-verified JSON file in the Obsidian vault (action=pack), or re-hydrate a pack file back into a (newly built if missing) create_preset_morph container (action=unpack). Reuses the create_preset_morph engine — does not invent a new morph topology. Requires TDMCP_VAULT_PATH unless inline 'looks' are supplied on unpack.

Parameter	Type	Required	Description
action	pack | unpack	yes	pack: read an existing create_preset_morph container and serialise its slots to a vault JSON. unpack: re-hydrate a pack file into a (newly built if missing) create_preset_morph container, optionally rebinding to a new target.
name	string	yes	Pack name. Used as the JSON filename (<folder>/<name>.morphpack.json) and the morph container default name on unpack.
parent	string	no	(pack) Parent COMP holding the existing morph container (defaults to /project1, matches create_preset_morph). (unpack) Parent COMP where the container is (re)built. (default: /project1)
container	string	no	(pack) Name of the existing morph container inside parent to read from. Defaults to name. (unpack) Name to (re)build; defaults to name.
target_path	string	no	(unpack) Override the target_path stored in the pack provenance (use when the pack came from a different show file and the target's path is different here). Omit to reuse pack provenance.target_path.
looks	object[]	no	(unpack, advanced) Inline-supply the slot set instead of reading vaultPath. Mutually exclusive with vaultPath on unpack; ignored on pack.
vault_path	string	no	Vault-relative path to the pack file. Defaults to MorphPacks/&lt;name&gt;.morphpack.json. Resolved through Vault.resolve (cannot escape the vault root).
overwrite	boolean	no	(pack) Overwrite an existing pack file at vault_path. (default: false)
merge	replace | union	no	(unpack) replace: wipe presets and write only the pack's slots. union: keep existing slots and add/overwrite the pack's slots by id. (default: replace)

learn_conventions mutates

Read a TouchDesigner subtree under scope_path without changing TD, infer naming/colour/topology/parameter conventions, and write the result to the configured Obsidian vault. This is read-only on the TD side but mutates vault files: by default it writes Memory/conventions.md and may merge confident naming/layout signals into Memory/style.md. Set dry_run=true to inspect the extract without disk writes. Use learn_from_my_corpus when the source is already in the vault and load_session_profile when you only need to consume cached preferences. Requires TDMCP_VAULT_PATH and returns sampled conventions plus write flags.

Parameter	Type	Required	Description
scope_path	string	no	Root COMP whose subtree is sampled. Defaults to /project1. (default: /project1)
observe	naming | colors | topology | params[]	no	Which convention families to extract. (default: naming,colors,topology,params)
max_nodes	integer	no	Cap on nodes walked (BFS, depth-unlimited until cap). (default: 500)
min_support	integer	no	A pattern must appear at least this many times to be recorded. (default: 3)
dry_run	boolean	no	If true, return the extracted conventions but do NOT write the vault note. (default: false)
also_patch_style_memory	boolean	no	If a confident naming/layout signal is found, also merge it into Memory/style.md. (default: true)

merge_vaults destructive

Merge the contents of a source Obsidian vault into a target vault (defaulting to TDMCP_VAULT_PATH). Walks Recipes/, Shaders/, Presets/, Components/, Setlists/, and Memory/ folders. sha256-hashes each file pair and resolves conflicts with your chosen strategy: 'theirs' overwrites target, 'ours' keeps target, 'rename' writes a side-by-side copy, 'skip' logs and skips. dryRun=true plans without writing. Note: LF/CRLF differences count as conflicts.

Parameter	Type	Required	Description
sourceVaultPath	string	yes	Absolute path to the source vault.
targetVaultPath	string	no	Defaults to the configured TDMCP_VAULT_PATH.
strategy	theirs | ours | rename | skip	no	(default: rename)
kinds	recipes | shaders | presets | components | setlists | memory | …[]	no	(default: all)
dryRun	boolean	no	(default: false)

vault_repo_sync mutates

Read-mostly git wrapper for the configured Obsidian vault directory. Lets an artist see what's changed (status), fetch/fast-forward-only pull, push, or read recent history (log). Never auto-resolves conflicts. Never uses --force. Never invokes a shell. Conflicts are surfaced as structured data for manual resolution. Requires TDMCP_VAULT_PATH or the vault_path argument.

Parameter	Type	Required	Description
vault_path	string	no	Absolute path to the vault git repo. Defaults to the configured TDMCP_VAULT_PATH.
action	status | pull | push | log	no	status: staged/unstaged/untracked + ahead/behind counts. pull: fetch + ff-only merge; reports conflicts but never auto-resolves. push: push current branch to its upstream; reports rejections. log: last N commits on the current branch. (default: status)
remote	string	no	Remote name for pull/push. (default: origin)
branch	string	no	Branch for pull/push. Defaults to the currently checked-out branch.
limit	integer	no	Max commits returned by action:'log'. (default: 20)
timeout_ms	integer	no	Hard timeout for the git child process. (default: 30000)

variant_pack mutates

Generate N perturbed variants around an anchor parameter look and write the whole pack to the Obsidian vault as a morph_pack-compatible JSON. Probes the target COMP's customPars for slider ranges to clamp + integer-round per param, then perturbs each variant uniformly within ±delta_range × (normMax − normMin). The resulting file is consumed directly by morph_pack (action=unpack). Requires TDMCP_VAULT_PATH.

Parameter	Type	Required	Description
name	string	yes	Pack name. File defaults to MorphPacks/<name>.morphpack.json.
parent	string	no	Parent COMP recorded into provenance.container_path. (default: /project1)
comp_path	string	no	COMP whose customPars give slider ranges for clamping. Defaults to target_path else parent.
seed_look	object	yes	Anchor look: { paramName: number }. Names must be numeric custom pars on comp_path.
count	integer	no	Number of perturbed variants (1..64). (default: 8)
delta_range	number	no	Perturbation magnitude as fraction of each param's slider span. (default: 0.15)
seed	integer	no	RNG seed for repeatable packs.
variant_prefix	string	no	Slot id prefix. (default: ``)
include_seed	boolean	no	If true, slot v00 is the seed look itself. (default: true)
target_path	string	no	Recorded into provenance.target_path so morph_pack can unpack standalone.
interpolation	linear | cosine | cubic	no	Recorded into provenance. (default: linear)
vault_path	string	no	Override default MorphPacks/<name>.morphpack.json. Resolved via Vault.resolve.
overwrite	boolean	no	Allow replacing an existing pack file. (default: false)

learn_from_my_corpus mutates

Offline companion to learn_conventions: walks the Obsidian vault corpus (Recipes/, Components/, Looks/, Setlists/, Moodboards/) and distils palette, naming, recipe-shape, and param-default preferences into Memory/corpus_style.md (and optionally merges palettes/naming/favorite_generators into Memory/style.md). No TouchDesigner required — pure filesystem read. Requires TDMCP_VAULT_PATH (or pass vault_path).

Parameter	Type	Required	Description
vault_path	string	no	Optional vault root override; defaults to TDMCP_VAULT_PATH.
observe	palette | naming | recipe-style | param-defaults[]	no	Which families to extract; subsets keep the run cheap. (default: palette,naming,recipe-style,param-defaults)
min_support	integer	no	Minimum frequency for a pattern to be recorded. (default: 3)
top_k_palette	integer	no	How many most-frequent palettes to keep. (default: 5)
dry_run	boolean	no	If true, return findings but do NOT write vault notes. (default: false)
also_patch_style_memory	boolean	no	If confident, merge palettes/naming/favorite_generators into Memory/style.md. (default: true)

tag_and_search_library mutates

Faceted browse + tag editing over a vault library (Recipes/ + Components/ markdown notes). op='list' enumerates every asset and its tags; op='search' filters by free-text query and/or tags_any/tags_all set logic; op='tag' edits one asset's frontmatter tags (union or replace, always preserving '*'-pinned user tags); op='filter' returns assets matching a license_tier bucket (and optional SPDX license id). Pure vault I/O — no TouchDesigner bridge required. Requires TDMCP_VAULT_PATH.

Parameter	Type	Required	Description
op	tag | search | list | filter	no	Operation: 'tag' edits one asset; 'search'/'list' read across the library; 'filter' returns assets matching a license_tier (and optional license SPDX-id). (default: search)
asset_path	string	no	Vault-relative path to one asset note (e.g. 'Recipes/feedback_tunnel.md'). Required for op='tag'.
tags	string[]	no	op='tag': tags to apply. Tags prefixed '*' are preserved as user-pinned. (default: ``)
replace	boolean	no	op='tag': when true, replace existing tags (kept '*'-pinned); when false, union. (default: false)
query	string	no	op='search': free-text substring matched against id/name/description/tags (case-insensitive).
tags_any	string[]	no	op='search': match assets that carry at least one of these tags. (default: ``)
tags_all	string[]	no	op='search': match assets that carry every one of these tags. (default: ``)
folders	string[]	no	Vault subfolders to scan. Defaults to ['Recipes', 'Components']. (default: Recipes,Components)
limit	integer	no	Maximum number of matches to return. (default: 50)
license_tier	public-domain | permissive | copyleft | proprietary | unknown	no	op='filter': return only assets whose frontmatter license_tier equals this bucket.
license	string	no	op='filter' (optional refinement): also require frontmatter license to equal this SPDX-id (case-insensitive).

version_library_asset mutates

Apply a SemVer patch/minor/major bump to a vault recipe or component note, recording the change in a sidecar <asset>.versions.json (asset_path + current + history list with version/bump/note/timestamp) and writing the new version into the note's frontmatter version field. Pass read_only:true to inspect the sidecar without bumping. Pure vault I/O — no TouchDesigner bridge required. Requires TDMCP_VAULT_PATH.

Parameter	Type	Required	Description
asset_path	string	yes	Vault-relative path to the asset note (e.g. 'Recipes/feedback_tunnel.md' or 'Components/foo.md').
bump	patch | minor | major	no	SemVer bump kind. patch=0.0.X, minor=0.X.0 (resets patch), major=X.0.0 (resets minor+patch). (default: patch)
note	string	no	Short human note describing what changed in this version.
read_only	boolean	no	When true, do not bump — just read and return the current version + history (bump/note ignored). (default: false)
license	string	no	SPDX-id (e.g. 'MIT', 'CC-BY-4.0', 'LicenseRef-Custom'). Written to note frontmatter AND mirrored into the sidecar. Omit to leave the existing value untouched.
license_tier	public-domain | permissive | copyleft | proprietary | unknown	no	License bucket: public-domain | permissive | copyleft | proprietary | unknown. Mirrors into frontmatter + sidecar.

export_look_tox mutates

Save a COMP as a .tox inside <vault>/<folder>/<slug>.tox and write a sibling Markdown note (id/type=look + name + tags + assets + created + source_path). Defaults folder to Looks. The artist-publishing primitive for portable looks; integrates with browse_vault_library and tag_and_search_library via the note frontmatter. Requires TDMCP_VAULT_PATH and a running TouchDesigner bridge.

Parameter	Type	Required	Description
source_path	string	yes	COMP path to package (e.g. '/project1/myLook').
name	string	no	Look name (defaults to the COMP's name).
folder	string	no	Vault subfolder under TDMCP_VAULT_PATH. (default: Looks)
tags	string[]	no	Tags written to the note frontmatter. (default: ``)
description	string	no	Short human description for the note body.
assets	string[]	no	Vault-relative asset paths to record in the metadata sidecar. (default: ``)
license	string	no	SPDX-id of the look's license, e.g. 'MIT' or 'CC-BY-NC-4.0'. Stored in the sidecar note frontmatter.
license_tier	public-domain | permissive | copyleft | proprietary | unknown	no	License bucket so search/filter can group by trust level: public-domain | permissive | copyleft | proprietary | unknown.

tutorial_companion_pack mutates

Build a teaching/selling companion for a network: snapshot the COMP's topology, capture preview PNGs of its output TOPs, scaffold an N-step lesson plan in Markdown, and emit a documentary network snapshot. Writes into <vault>/<folder>/<slug>/ as tutorial.md + topology.json + network_snapshot.json + previews/*.png. The snapshot captures nodes + connections by TD path for reference only — it is not a RecipeSchema-compatible installable recipe. Composes existing read-only bridge calls — the artist edits the lesson body afterwards. Requires TDMCP_VAULT_PATH and a running TouchDesigner bridge.

Parameter	Type	Required	Description
source_comp	string	yes	COMP whose contents are the subject of the tutorial.
name	string	no	Pack name; defaults to the COMP's name.
folder	string	no	Vault subfolder for the pack. (default: Tutorials)
lesson_count	integer	no	Number of lesson steps to scaffold (1..20). (default: 5)
preview_width	integer	no	(default: 480)
preview_height	integer	no	(default: 270)
description	string	no	One-paragraph human description for the lesson.
tags	string[]	no	Tags written to the pack's frontmatter. (default: ``)

scaffold_recipe_from_network read-only

Inverse of apply_recipe: walk a COMP's child network in TouchDesigner and serialize it back to a draft RecipeSchema JSON (nodes + non-default parameters + connections + cross-references). Validates against RecipeSchema before returning. When write_path is set, writes pretty JSON to that vault-relative path; otherwise returns the recipe in structuredContent. Read-only with respect to TD — no operators are created or modified.

Parameter	Type	Required	Description
id	string	yes	Recipe id/slug. Also the default filename stem when write_path is set.
root_path	string	no	COMP whose direct children are serialized into the recipe. (default: /project1)
name	string	no	Human-friendly title (defaults to the id).
description	string	no	RecipeSchema description (defaults to empty). (default: ``)
tags	string[]	no	RecipeSchema tags. (default: ``)
difficulty	beginner | intermediate | advanced	no	RecipeSchema difficulty. (default: intermediate)
include_defaults	boolean	no	When true, keep every CONSTANT-mode parameter (verbose; useful for round-trip debugging). (default: false)
detect_cross_refs	boolean	no	When true, rewrite str params whose value matches a sibling node's name to the bare sibling name (the apply_recipe convention). (default: true)
write_path	string | null	no	Optional vault-relative path to write the recipe JSON to (e.g. Recipes/myrec.json). When null, the JSON is returned in structuredContent only. (default: null)
overwrite	boolean	no	Refuse to clobber an existing file unless true. (default: false)

AI session memory

Local session-memory helpers that let an agent load persistent taste, convention and recent-work context without re-running the heavier vault-learning tools every turn.

load_session_profile mutates

Reads ~/.tdmcp/session-profile.json (or a custom path) and returns a unified JSON snapshot that an agent should load at the start of every session. The profile caches the most recent outputs of style_memory, recall_similar_work, learn_conventions, and learn_from_my_corpus so the agent has the artist's preferences and past work at hand without running all four tools every time. If no file exists, a default skeleton is created and returned. Pass reset=true to overwrite with fresh defaults. The profile_path field in the returned object is always the resolved path that was read or written.

Parameter	Type	Required	Description
profile_path	string	no	Absolute path to the session-profile JSON file. Defaults to ~/.tdmcp/session-profile.json.
reset	boolean	no	If true, overwrite the existing profile with the built-in defaults and return them. (default: false)

narrate_set mutates

Persist the running narration of a live VJ/show set so decisions can be recalled afterwards. mode='append' adds a timestamped line (with optional section + cue) to a markdown session log (default ~/.tdmcp/narration-<date>.md); mode='recall' reads the log back (last tail lines). Pair with the auto_vj_director prompt: instead of narrating only in chat, call narrate_set on each major move so the set leaves a diary/setlist trail. Writes a local file (not read-only). Delta vs log_performance, which writes a one-shot network snapshot rather than an append-only decision log.

Parameter	Type	Required	Description
mode	append | recall	no	append: add a narration line to the running set log. recall: read back the log lines. (default: append)
line	string	no	The narration line to record (required for mode='append'), e.g. "holding through the build → cue 'drop' on the next bar".
section	string	no	Optional song section/phase this line belongs to, e.g. 'intro', 'drop', 'breakdown'.
cue	string	no	Optional cue name being fired/recalled, for cross-reference.
set_name	string	no	Session name; picks the log file ~/.tdmcp/narration-<set_name>.md. Defaults to today's date.
log_path	string	no	Explicit path to the narration log file, overriding set_name. Honors TDMCP_NARRATION_PATH otherwise.
tail	integer	no	For mode='recall': return at most the last N narration lines. (default: 50)

one_source_five_ways read-only

Turn one source node, asset, or package entry into five deterministic remix briefs: colorway, motion, texture, spatial reframe, and performance cue. Offline/read-only planning tool for agents before mutating TouchDesigner networks.

Parameter	Type	Required	Description
source_path	string	yes	TouchDesigner node path, asset id, file path, or package entry to remix.
source_summary	string	no	Optional description of the source's colors, motion, structure, or performance role.
goal	string	no	Creative objective for the five variants. (default: generate five distinct performance-ready variations)
intensity	subtle | balanced | extreme	no	How far the variants should diverge from the source. (default: balanced)
include_tool_steps	boolean	no	Include suggested tdmcp tool steps for each variant. (default: true)