cdp-web.app

{
  "name": "get_patch",
  "kind": "answer",
  "impl": "imperative",
  "description": "Read the patch on the cdp-web canvas: name, tempo, every node with its parameter values, and the cables between them. Call this first to see what you and the user are looking at, and again after changes you did not make yourself. detail:'full' returns the raw cdp-web-patch JSON document (large) — only for saving or load_patch.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "detail": {
        "type": "string",
        "enum": [
          "summary",
          "full"
        ],
        "description": "'summary' (default) is a compact overview; 'full' is the raw patch JSON"
      }
    }
  }
}

{
  "name": "describe_node",
  "kind": "answer",
  "impl": "imperative",
  "description": "Inspect one node of the current patch by id: each parameter's current value, default and allowed range or choices, whether an envelope or cable drives it, plus the node's ports and connections. Use before set_params or connect to get exact parameter and port names.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string",
        "description": "Node id to describe (e.g. 'n3', from get_patch)"
      }
    },
    "required": [
      "id"
    ]
  }
}

{
  "name": "search_effects",
  "kind": "answer",
  "impl": "imperative",
  "description": "Search the catalog of ~250 CDP effects and sound generators by keyword over names, descriptions and categories. Returns ids for add_node and describe_effect. Use when choosing how to realise a sound-design idea; an empty query with a category browses that category.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "Keywords, e.g. 'stretch grain' — all must match"
      },
      "category": {
        "type": "string",
        "description": "Restrict to one category, e.g. 'Spectral'"
      },
      "limit": {
        "type": "number",
        "description": "Max results (default 10)"
      }
    }
  }
}

{
  "name": "describe_effect",
  "kind": "answer",
  "impl": "imperative",
  "description": "Full specification of one catalog effect or generator id: what it does, every parameter with range/choices/default, whether it can take an envelope, and any free-text data it accepts. Use before add_node or before set_params on a node of that type.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string",
        "description": "Effect or generator id from search_effects, e.g. 'blur.blur' or 'wave'"
      }
    },
    "required": [
      "id"
    ]
  }
}

{
  "name": "list_sounds",
  "kind": "answer",
  "impl": "imperative",
  "description": "List the audio set_source can load: the bundled demo sounds and the WAV files in the app's local audio store (with their keys). Use before set_source when you do not already know what to load.",
  "inputSchema": {
    "type": "object",
    "properties": {}
  }
}

{
  "name": "load_patch",
  "kind": "act",
  "impl": "imperative",
  "description": "Replace the whole patch with a cdp-web-patch v1 JSON document (as returned by get_patch detail:'full'), or start a fresh default patch when called without one. This discards the current canvas (the user can Edit ▸ Undo) — prefer add_node/connect/set_params for incremental edits. Returns the new patch summary.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "patch": {
        "type": "string",
        "description": "cdp-web-patch v1 document as a JSON string; omit to reset to the default Source → Output patch"
      }
    }
  }
}

{
  "name": "add_node",
  "kind": "act",
  "impl": "imperative",
  "description": "Add one node to the patch: type 'transform' with an effectId or 'generator' with a genId (ids from search_effects), or a plain 'source', 'output', 'pvocAnalyse', 'pvocResynth', 'pick' or 'gather'. The node appears on the canvas unconnected — cable it with connect. Returns the new node's id, ports and parameters.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "type": {
        "type": "string",
        "enum": [
          "transform",
          "generator",
          "source",
          "output",
          "pvocAnalyse",
          "pvocResynth",
          "pick",
          "gather"
        ],
        "description": "Kind of node to add"
      },
      "effectId": {
        "type": "string",
        "description": "Catalog effect id (type 'transform' only)"
      },
      "genId": {
        "type": "string",
        "description": "Catalog generator id (type 'generator' only)"
      }
    },
    "required": [
      "type"
    ]
  }
}

{
  "name": "connect",
  "kind": "act",
  "impl": "imperative",
  "description": "Cable from_node's output into to_node's input. Ports default to the out port and the first compatible input, so the two node ids usually suffice; name ports for multi-input nodes or 'param:<name>' envelope inputs. A failure explains why and how to fix a domain mismatch (e.g. insert a PVOC Analyse node).",
  "inputSchema": {
    "type": "object",
    "properties": {
      "from_node": {
        "type": "string",
        "description": "Node id whose output to take (e.g. 'n3', from get_patch)"
      },
      "from_port": {
        "type": "string",
        "description": "Output port name (default: the node's out port)"
      },
      "to_node": {
        "type": "string",
        "description": "Node id to feed into (e.g. 'n3', from get_patch)"
      },
      "to_port": {
        "type": "string",
        "description": "Input port name, e.g. 'in', 'in2', 'bank', 'param:freq' (default: first compatible input)"
      }
    },
    "required": [
      "from_node",
      "to_node"
    ]
  }
}

{
  "name": "disconnect",
  "kind": "act",
  "impl": "imperative",
  "description": "Remove the cable between two nodes, optionally narrowed by port names when several cables join them. An error lists the cables that do exist.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "from_node": {
        "type": "string",
        "description": "Node id at the cable's source end (e.g. 'n3', from get_patch)"
      },
      "from_port": {
        "type": "string",
        "description": "Output port name (optional)"
      },
      "to_node": {
        "type": "string",
        "description": "Node id at the cable's destination end (e.g. 'n3', from get_patch)"
      },
      "to_port": {
        "type": "string",
        "description": "Input port name (optional)"
      }
    },
    "required": [
      "from_node",
      "to_node"
    ]
  }
}

{
  "name": "delete_node",
  "kind": "transact",
  "impl": "imperative",
  "description": "Delete one node and its cables from the patch. The user can Edit ▸ Undo. The last Output node cannot be deleted.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string",
        "description": "Node id to delete (e.g. 'n3', from get_patch)"
      }
    },
    "required": [
      "id"
    ]
  }
}

{
  "name": "set_params",
  "kind": "act",
  "impl": "imperative",
  "description": "Set one or more parameter values on one node — the main editing tool. Values are applied through the node's own controls, so out-of-range values are clamped and the response reports what was actually applied. Optional data sets the node's free-text data (chord notes, click times…). Fails with the valid names if a parameter does not exist, or if an envelope or cable is driving it.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string",
        "description": "Node id to edit (e.g. 'n3', from get_patch)"
      },
      "params": {
        "type": "object",
        "description": "Map of parameter name → value; numbers for sliders, the choice value for discrete params",
        "additionalProperties": {
          "type": [
            "number",
            "string"
          ]
        }
      },
      "data": {
        "type": "string",
        "description": "Free-text data for nodes that take it (e.g. a Chord generator's notes)"
      }
    },
    "required": [
      "id"
    ]
  }
}

{
  "name": "set_source",
  "kind": "act",
  "impl": "imperative",
  "description": "Load audio into a Source node: a demo sound name from list_sounds (e.g. 'marimba'), a stored WAV key, or a WAV file URL to fetch (its server must allow CORS). Targets the first empty Source node unless node names one. Returns the loaded audio's duration, channels and sample rate.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "sound": {
        "type": "string",
        "description": "Demo sound name, stored WAV key, or WAV URL"
      },
      "node": {
        "type": "string",
        "description": "Source node id to load into (default: first empty Source)"
      }
    },
    "required": [
      "sound"
    ]
  }
}

{
  "name": "render",
  "kind": "act",
  "impl": "imperative",
  "description": "Run the patch through its Output node and report the rendered result's duration, channels and sample rate (never the audio bytes — the sound lives in the app). Set play:true to also start playback so the user hears it too. Waits for the CDP engine if it is still loading; fails if nothing feeds the Output node.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "play": {
        "type": "boolean",
        "description": "Start playback of the result in the app (default false)"
      }
    }
  }
}

{
  "name": "undo",
  "kind": "act",
  "impl": "imperative",
  "description": "Step the patch edit history: undo the most recent change, or redo one with redo:true. Returns the new patch summary and history position. Use after an edit that made things worse, or when the user asks to go back.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "redo": {
        "type": "boolean",
        "description": "Redo instead of undo (default false)"
      }
    }
  }
}