Skip to content

Streams and graph documents

What a stream's graph document holds, how Tato Studio, agents and your editor change it, input values and their types, several streams in a project, subgraphs, variables, and graph generators.

A stream is a graph document, streams/<name>.graph.json in its project: the nodes, the values each one holds, and the links between their ports. The runtime loads every graph document in the project as its own stream when it opens the project. Reading a document runs no code, though loading it asks your project’s interpreter to describe each node type it names, which imports that node’s module.

streams/main.graph.json
{
"asset": "0eaf9ee2-0f73-4154-a3f6-a99c261b850d",
"display_name": "Lobby wall",
"links": [
{
"source": { "node": "777c0dab-ae92-4df3-9d8f-bb1c4d4e98b6", "port": "video" },
"target": { "node": "02a2b427-bbc4-4d9f-a376-854af4fa8755", "port": "image" }
}
],
"nodes": [
{
"id": "777c0dab-ae92-4df3-9d8f-bb1c4d4e98b6",
"name": "camera",
"type": "tatolab.camera:CameraSource",
"input_values": { "device_id": "/dev/video2" }
},
{
"id": "02a2b427-bbc4-4d9f-a376-854af4fa8755",
"name": "blur",
"type": "imports/core-nodes/core_nodes.filters:Blur",
"input_values": { "radius": 0.02 },
"studio": { "position": [320, 80] }
}
]
}
Key
asset The stream’s UUID. With the project’s UUID, it makes the stream’s ID, so the ID survives renaming the file or moving the project.
display_name The name the stream is shown under. Without one, it’s the file name.
nodes[].id The node’s UUID, made by the runtime when it placed the node, and kept for good. Link ends name nodes by it.
nodes[].name A label, unique in the graph, cast to lowercase URL-safe characters (Front Camera becomes front-camera).
nodes[].type The node type’s import path, module:Name.
nodes[].input_values The value the node holds for each input, and each setting, by name. One it doesn’t name reads its declared default.
nodes[].studio How Tato Studio draws the node: its position, group, comment and colour. Nothing that runs reads it.
links Each link, from an output port to an input port, both in this stream.
clock The clock the stream runs on, when it isn’t real time: {"mode": "scaled", "scale": 0.5} or {"mode": "stepped", ...}.
groups, studio Labelled groups of nodes and canvas notes, for the next person who reads the graph. Nothing that runs reads them.

A document an older runtime wrote, with config and pins on its nodes, is read with both folded into input_values.

A type is named by its import path, resolved in the stream’s own interpreter:

  • nodes.crowd_counter:CrowdCounter: a module in the project.
  • tatolab.camera:CameraSource: a package installed in the project’s .venv. A package can also list its nodes under the tatolab.nodes entry point, so they appear in Studio’s search before a graph names one.
  • imports/core-nodes/core_nodes.filters:Blur: a node of an imported project, run from that import’s own folder. Every project imports the core nodes.
  • tatolab.stream:RecordsToChannels: one of the runtime’s built-in nodes.

There is no registration file and no build step. A project’s node types are listed from source, without running any of it, which is how Studio’s node search and agents find them.

Three ways change the same document:

  • In Tato Studio. Add a node, draw a link, set a value. Each edit goes to the runtime as one transaction: applied to the running stream, saved to the document, and recorded as one commit on the project’s history, .tatolab/history.git, which Undo walks back.
  • Through the runtime’s API, from an agent over MCP or with tatolab call: add_node, connect, disconnect, remove_node, set_node_input_value and more, or several at once in one transact, applied whole or refused whole. An edit can also be made live, to the running stream only, and not saved.
  • By hand. Edit the file and save. While tatolab dev runs, it reloads the project; otherwise tatolab reload does. A node you add by hand needs a UUID of its own for its id; uuidgen makes one.

A reload keeps the project’s playback. While the project’s node code and dependencies are as they were, it brings each stream’s graph to its document in place; otherwise it loads the stream again under the same ID. A document that fails to load records its stream failed, with the reason in the log, until a reload of the fixed document.

Every input has one type: a float, an integer, a boolean, a string, a menu, a colour, a vector, a rectangle, a transform, a texture, audio, encoded video or audio, a tensor, an asset, a trigger, a list, a bundle, or a type a module declares. Studio draws each input in its type’s colour, with its name.

An input with no link holds one value of its type, saved in input_values. A node’s settings, the fields of its config, are values the same way. Studio shows each value on the node and edits it in place: a float follows the pointer as you drag it. A value is checked before it’s set, and one of the wrong type, or outside the input’s range, is refused, never clamped. A value set on an input that a link feeds is kept, and takes over when the link goes.

From the command line, set_node_input_value sets one:

Terminal window
tatolab call set_node_input_value --params '{
"stream": "0eaf9ee2-0f73-4154-a3f6-a99c261b850d",
"node": "02a2b427-bbc4-4d9f-a376-854af4fa8755",
"input": "radius",
"value": 0.05
}'

stream is the stream’s asset, which tatolab streams shows under ASSET; node is the node’s id.

A setting can also be made an input of its own, so a link can drive it: Studio’s node menu does this, and the document lists it under the node’s exposed_config_fields.

Each graph document in streams/ is its own stream, and the project plays, pauses and stops them together. Create one in Studio with New stream…, or write a new document. A document you delete unloads its stream and forgets it.

A link’s two ends are always in one stream. Streams, in one project or several, on one machine or several, reach each other through a MoQ relay with the tatolab-moq gateway nodes. See Share between streams.

Select some nodes in Studio and collapse them into a subgraph: they’re saved as a new stream of the project, placed where they were, and each link that crossed the selection runs through a GraphInput or GraphOutput node, the subgraph’s ports. Every stream that places the subgraph takes an edit made inside it. A stream another stream places runs only where it’s placed.

A stream of an imported project is placed the same way, by reference: its nodes run from the import’s own folder.

SetVariable names one value, the output linked into it, and GetVariable reads it anywhere in the graph with no wire drawn across. A variable can also hold a node, which is how the MoQ gateway’s tracks name their gateway.

Function nodes can’t form a loop on their own: each evaluation would wait for itself. Close one through Previous Value, which hands on the number it was given at the last evaluation. Draw a link that would close a loop and the runtime adds one for you.

A graph generator is a Python function that builds part of a graph in code, for a part that’s easier to write than to draw: a bank of 16 identical channels, say.

nodes/bank.py
from tatolab.stream import StreamBuilder, graph_generator
from nodes.channel_strip import ChannelStrip
@graph_generator
def channel_bank(stream_builder: StreamBuilder, channels: int = 16) -> None:
for index in range(channels):
stream_builder.add(ChannelStrip, name=f"strip-{index}")

Placing it in a stream, from Studio’s node search or with import_graph_generator, runs it in the stream’s interpreter and stores what it built inside the graph document as a fragment: a node holding the nodes and links the generator made. The fragment is read-only, and runs flattened into the stream. Each time you save the generator’s module, tatolab dev runs it again and refreshes every fragment it made, each node keeping its UUID by name. Unlock a fragment to turn its nodes into plain nodes of the stream.

stream_builder.add(...), connect(...) and run_on_clock(...) are the generator’s API; see the Python SDK reference.