Skip to content

Make nodes

Create a node in Tato Studio from the node template, write it in the Code view, place it in a stream, and change it while the stream plays.

When no node does what you need, make one. A node is a few lines of Python in the project’s folder, and Studio has everything to write it: a new file from a template, an editor with Python completions, and the project’s log under it.

In the Files view, press New node file and give the file a path in the project, such as nodes/invert.py. Studio creates it from the runtime’s node template and opens it in the Code view. The template is a working node, named after the file, that passes pictures through unchanged:

nodes/invert.py
from tatolab.stream import Image, Input, Output, RuntimeContextLimitedAccess, node
@node.meta(description="Hands on each frame it reads, unchanged.")
@node.process
class Invert:
video_in = Input(Image, description="The frames this node reads.")
video_out = Output(Image, description="Each frame read from `video_in`, unchanged.")
def process(self, ctx: RuntimeContextLimitedAccess) -> None:
frame = ctx.inputs.read(self.video_in)
if frame is None:
return
ctx.outputs.write(self.video_out, frame)

It’s already a node type of the project. Click the graph, press Tab, type its name, and place it; wire a picture into video_in and select it to see video_out in the Node visualizer.

  • @node.process makes it a process node: a class the runtime runs in a process of its own, with the project’s Python packages. By default the runtime calls process each time data arrives.
  • Input(Image) and Output(Image) are its pins. Their types become the pins’ types and colours on the card, and their descriptions show in Studio and to agents.
  • @node.meta gives it the description, and a category, that the Add node search and agents read.
  • process reads the newest frame and writes one out.

A node can also be a plain Python function, which the runtime compiles and runs without a process, or a Slang shader, which runs on the GPU once per pixel. Write a node covers all three, and everything a node can declare.

The Code view is a full editor: Python completions and errors from a language server that knows the tatolab.stream SDK, and ⌘S (Ctrl-S on Linux) to save. Open any file of the project with + at the top of the view, or from the Files view. Files that belong to a module you added are shown read only.

When you save a Python file, Studio reloads the open project, keeping it playing: each node of that file starts again with your change, and the rest of the stream carries on. If the file changed on disk while you were editing it, Studio says so and lets you load the version on disk or keep yours and save.

Give a node settings with a dataclass on its __init__, and each field shows in Properties, with its default and its description:

from dataclasses import dataclass
from typing import Annotated
@dataclass
class InvertConfig:
amount: Annotated[float, "How far to invert: 0 leaves the picture, 1 inverts it."] = 1.0

A node that defines configure(self, config) takes a new value while it plays; one that doesn’t takes it at the next play. Any setting can become a Graph Input, controlled from the Controls view: see Streams as compositions.

The project’s log runs under the editor: what the runtime says about each stream, each node’s log.info(...) records, and anything a node prints. When a node fails, or its process raises, its card says so in its own words, and the log has the rest. Fix the code and save, and the node runs again.

A node can import any Python package. Add the package to the project’s pyproject.toml, in the Code view or with uv add in a terminal, and the runtime brings the project’s environment up to date the next time it loads the project, as it does when you next save one of the project’s Python files. Packages that bring nodes of their own, like the first-party modules, are easier to add from the Marketplace.

A coding agent connected to the runtime can do all of this too: create the node file, write its code, place it and wire it, while you watch each step land in Studio. See Build with an agent.