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.
What a document holds
Section titled “What a document holds”{ "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.
Node types
Section titled “Node types”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 thetatolab.nodesentry 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.
Changing a stream
Section titled “Changing a stream”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_valueand more, or several at once in onetransact, applied whole or refused whole. An edit can also be madelive, to the running stream only, and not saved. - By hand. Edit the file and save. While
tatolab devruns, it reloads the project; otherwisetatolab reloaddoes. A node you add by hand needs a UUID of its own for itsid;uuidgenmakes 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.
Input values and their types
Section titled “Input values and their types”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:
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.
Several streams in a project
Section titled “Several streams in a project”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.
Subgraphs
Section titled “Subgraphs”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.
Variables
Section titled “Variables”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.
Loops of number nodes
Section titled “Loops of number nodes”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.
Graph generators
Section titled “Graph generators”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.
from tatolab.stream import StreamBuilder, graph_generator
from nodes.channel_strip import ChannelStrip
@graph_generatordef 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.