Metadata-Version: 2.5
Name: tatolab-stream
Version: 0.68.92
Summary: The Python SDK for Tatolab streams. To get started, install the Tatolab app: see tatolab.com/docs/install
Project-URL: Homepage, https://tatolab.com
Project-URL: Documentation, https://tatolab.com/docs
Project-URL: Install, https://tatolab.com/docs/install
Project-URL: Source, https://github.com/tatolab/streamlib
Author-email: Jonathan Fontanez <fontanezj1@gmail.com>
License-Expression: BUSL-1.1
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# tatolab-stream

The Python SDK for [Tatolab](https://tatolab.com), which turns cameras, microphones, screens,
models and your own code into realtime streams that browsers, other streams and AI agents can
read.

> **Looking to get started? Install the Tatolab app first, not this package.**
> `tatolab-stream` is the library you write streams with. It doesn't run them: the Tatolab
> runtime on your machine does, and it comes with the app.
>
> - **macOS** (Apple silicon, macOS 26 or later):
>   `brew install --cask tatolab/tap/tatolab`, then `open -a Tatolab`
> - **Linux** (x86_64 with a Vulkan GPU):
>   `curl -fsSL https://get.tatolab.com/install.sh | sh`
>
> Then follow the [Quickstart](https://tatolab.com/docs/quickstart). `tatolab new` creates a
> project that already depends on this package, so you rarely `pip install` it yourself.

## What it is

A stream is an ordinary Python project. You write nodes as Python classes and connect them in a
function decorated `@graph_generator`:

```python
from tatolab.camera import CameraSource
from tatolab.stream import StreamBuilder, graph_generator

from nodes.halftone_lens_effect import HalftoneLensEffect


@graph_generator
def main(stream_builder: StreamBuilder) -> None:
    camera = stream_builder.add(CameraSource)
    effect = stream_builder.add(HalftoneLensEffect)
    stream_builder.connect(camera.output("video"), effect.input("video_from_upstream"))
```

`CameraSource` comes from the `tatolab-camera` module, a dependency the project adds like any
other. `tatolab dev` runs it in the runtime. Each node runs in its own process, so one slow node never
blocks another. Tato Studio's viewer shows any node's output on the machine, and the
`tatolab-moq` gateway nodes send one to a MoQ relay, where other streams and machines read it.

A generator may `add` another generator as it adds a node class, its keyword arguments the settings
the inner generator promotes. The inner graph is stored as a fragment, whose `GraphInput` and
`GraphOutput` nodes are its ports, and it runs flattened under its path of names (`look/soft/blur`).

This package holds the authoring API (`@graph_generator`, `@node.process`, `StreamBuilder`), typed classes for
every built-in node (the converters between the Image, Array, Channels and Records families), and
the protocols your nodes are handed at run time. It installs and imports without the runtime,
with complete type hints, so your editor, type checker and unit tests work on any machine.

## Add it to an existing project

```sh
uv add tatolab-stream
```

The runtime runs your nodes with the project's `.venv/bin/python`, so anything you install there
your nodes can import. See [Python SDK](https://tatolab.com/docs/install/python) for details.

Supports CPython 3.12 to 3.13 (not the free-threaded builds).

## Other packages

- [`tatolab-webrtc`](https://pypi.org/project/tatolab-webrtc/): WHIP publish and WHEP play nodes.
- `tatolab` on PyPI is a placeholder that installs nothing. Tatolab itself installs as an app,
  as above.

## Links

- [Documentation](https://tatolab.com/docs)
- [Install Tatolab](https://tatolab.com/docs/install)
- [Write a node](https://tatolab.com/docs/build/nodes)
- [Python API reference](https://tatolab.com/docs/reference/python-api)
- [Source](https://github.com/tatolab/streamlib)

Licensed under the [Business Source License 1.1](https://github.com/tatolab/streamlib/blob/main/LICENSE).
