Metadata-Version: 2.4
Name: travel-animator
Version: 0.2.0a1
Summary: TADA render engine: render an already-resolved bundle and run the CLI's safe subcommands
License: Proprietary -- limited use licence; see tada_render/LICENSE
Keywords: mcp,mp4,opengl,renderer,travel-animator,video
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Graphics :: 3D Rendering
Classifier: Topic :: Multimedia :: Video
Requires-Python: >=3.12
Requires-Dist: av<19,>=18
Requires-Dist: httpx<0.29,>=0.28.1
Requires-Dist: moderngl<6,>=5.12
Requires-Dist: numpy<3,>=2.5.1
Requires-Dist: pillow<13,>=12.3
Requires-Dist: protobuf<8,>=7.35.1
Requires-Dist: pygltflib<2,>=1.16.5
Requires-Dist: skia-python<145,>=144.0.post2
Requires-Dist: tqdm<5,>=4.68.4
Provides-Extra: mcp
Requires-Dist: mcp<2,>=1.29; extra == 'mcp'
Description-Content-Type: text/markdown

# travel-animator

`travel-animator` (PyPI name; the Python import path is `tada_render`) is the public
half of TADA, the off-device renderer for Travel Animator export configs. It
renders an already-resolved input (a "render bundle") to an H.264 MP4 with no
credentials and no private choreography code:

```text
render bundle (config.json + frame_plan.pb + cached assets/tiles) -> OpenGL/Skia render -> H.264 MP4
```

It ships the rendering pipeline, the encoder, an offline bundle reader, a
CLI, and an optional MCP server. It does **not** include the animation
choreography builder or the credentialed asset fetchers that turn a live
Travel Animator export into a render bundle in the first place — those stay
in the private `tada` package.

## Install

```bash
pip install travel-animator
```

Requirements: Python 3.12+, an OpenGL implementation (a GPU driver in
production, Mesa/llvmpipe for CPU-only use), and FFmpeg/PyAV's usual runtime
libraries.

For the MCP server, install the `mcp` extra:

```bash
pip install "travel-animator[mcp]"
```

The extra keeps the MCP SDK out of the base install (and out of the GPU
worker's dependency set — the renderer itself never imports it).

## CLI

Console script: `travel-animator`.

```text
travel-animator login           # interactive magic-link login, or store a bearer token
travel-animator logout          # remove locally stored credentials (local only; see below)
travel-animator render-bundle   # render a prepared, offline bundle to MP4
travel-animator mcp             # run the stdio MCP server (requires the `mcp` extra, below)
```

`login` authenticates against the same account system the Travel Animator
mobile app uses. With no argument on an interactive terminal it runs a
magic-link flow (email -> 6-digit code); with a token argument, `-`, or piped
stdin it stores a bearer token directly (for CI). Credentials are written to
`~/.config/tada/credentials.json` (or `$XDG_CONFIG_HOME/tada/credentials.json`)
with mode `0600`.

`logout` removes whatever is stored locally. There is currently no
server-side session revocation: a stolen credentials file remains valid at
the login service until it naturally expires. `logout` only stops *this*
machine from presenting it.

`render-bundle` renders a bundle produced by the private `tada prepare`
command (or an equivalent producer) with no network access. Its `--encoder`
default is `libx264` (CPU-only, works on any machine); a GPU worker with
NVIDIA hardware should pass `--encoder h264_nvenc` explicitly. Run
`travel-animator render-bundle --help` for the full flag reference.

`travel-animator` never imports the private `tada` package, so it works standalone
for every command above, including `render-bundle` (ADR 0007: the bundle
carries its own embedded frame plan, so no choreography code is needed to
play it back).

## MCP server

The `mcp` extra adds `travel-animator mcp`: a stdio MCP server that lets an agent
author a Travel Animator export config (build a route, tune the animation,
render a video) without the private `tada` package. (Earlier versions shipped
this as a standalone `tada-render-mcp` console script; it's now a subcommand
so future public CLI features don't each need their own binary — ADR 0009
amendment.) A typical MCP client configuration:

```json
{
  "mcpServers": {
    "travel-animator-mcp": {
      "command": "travel-animator",
      "args": ["mcp"]
    }
  }
}
```

Run `travel-animator login` in a terminal first — tools that need a credential
fail with a clear message telling you to do so, and `auth_status` lets an
agent check before it builds a trip it cannot render.

## Licence

`travel-animator` is published under a **limited use licence, not an open-source
licence**. In short: you may install and run it unmodified to prepare and
render Travel Animator content and to talk to Lascade's services. You may not
redistribute it, modify it, or build a competing service with it. The full
terms ship inside the package at `tada_render/LICENSE`.

The bundled fonts (SIL Open Font License 1.1) and flag artwork (MIT) are
third-party assets under their own licences, which that restriction does not
touch. Their notices and full licence texts are in
`tada_render/THIRD-PARTY-NOTICES.md`.

For redistribution or modification rights, contact Lascade.
