---
title: "Streams and graph documents"
description: "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."
type: "docs-page"
url: "https://tatolab.com/docs/build/graphs"
site: "Tatolab"
section: "Build in code"
---

# 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.

> **Note**
>
> This page is the file behind a stream. To build one in Tato Studio, see [Build a graph](https://tatolab.com/docs/studio/graph) and [Streams as compositions](https://tatolab.com/docs/studio/streams).

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

```json title="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`.

## 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 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.

## 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_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.

## 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:

```sh
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

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](https://tatolab.com/docs/share/between-streams).

## 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

`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

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

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.

```python title="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](https://tatolab.com/docs/reference/python-api).
