Metadata-Version: 2.5
Name: travel-animator
Version: 0.2.0a9
Summary: Render Travel Animator route animations to MP4, from the command line or an MCP server
Project-URL: Homepage, https://travelanimator.com
Maintainer-email: Lascade <connect@travelanimator.com>
License: Proprietary: limited use licence; see tada_render/LICENSE in the installed package
License-File: tada_render/LICENSE
License-File: tada_render/THIRD-PARTY-NOTICES.md
Keywords: animation,map,mcp,mp4,opengl,renderer,route,travel-animator,video
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
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: numpy<3,>=2.5.1
Requires-Dist: pillow<13,>=12.3
Requires-Dist: protobuf<8,>=7.35.1
Requires-Dist: tqdm<5,>=4.68.4
Provides-Extra: mcp
Requires-Dist: jsonschema<5,>=4; extra == 'mcp'
Requires-Dist: mcp<2,>=1.29; extra == 'mcp'
Requires-Dist: posthog==7.38.6; extra == 'mcp'
Description-Content-Type: text/markdown

# travel-animator

`travel-animator` renders Travel Animator route animations to video away from the
phone — on a laptop, a workstation or a server. The output is an H.264 MP4 of the
animation the mobile app exports: the route drawn as it is travelled, a 3D vehicle
following it, map labels, country flags, and the distance badge and watermark the app
draws on top.

There are two ways to use it. An **MCP server** lets an AI assistant plan a route,
choose how the animation looks and render it for you — the only path here that goes
from nothing to a finished video. A **command-line renderer** turns an
already-prepared render bundle into an MP4, for pipelines that receive bundles from
elsewhere.

It is a companion to Lascade's Travel Animator service, so it needs an account, and
rendering needs a premium one. This is not open-source software; see
[Licence](#licence). The Python import path is `tada_render`.

## Install

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

For the MCP server, install the `mcp` extra, which keeps the MCP SDK out of the base
install:

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

Requires Python 3.12 or newer. Rendering has further platform requirements; see
[Requirements for rendering](#requirements-for-rendering).

## Quickstart: render from an AI assistant

1. Install the package with the `mcp` extra and log in from a terminal. The server
   cannot prompt you for credentials itself.

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

2. Register the server with your client. For Claude Code:

   ```bash
   claude mcp add travel-animator -- travel-animator mcp
   ```

   For Claude Desktop, or any other client that takes a JSON config
   (`claude_desktop_config.json`, in `~/Library/Application Support/Claude/` on macOS
   and `%APPDATA%\Claude\` on Windows):

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

   A client launched from a desktop GUI does not inherit your shell's `PATH`. If the
   server fails to start, give it the absolute path to the script instead; `which
   travel-animator` (or `where travel-animator` on Windows) prints it.

3. Describe the animation you want — the route, the vehicle, the map style, the
   resolution. The assistant authors the project, starts the render, reports progress
   while it runs, and returns the finished MP4.

Two of the server's tools are worth knowing by name. `auth_status` reports whether
this machine has a usable login and whether the account can render. `get_capabilities`
starts a real graphics context on the real machine, so an assistant can find out
whether this computer can render before building a project it cannot finish.

## Command line

```text
travel-animator login           # log in: interactive magic link, or store a bearer token
travel-animator logout          # remove locally stored credentials (this machine only)
travel-animator analytics       # show, grant or revoke usage-analytics consent (off by default)
travel-animator render-bundle   # render a prepared render bundle to MP4
travel-animator mcp             # run the stdio MCP server (needs the mcp extra)
```

### login and logout

`login` authenticates against the same account system as the Travel Animator mobile
app. On an interactive terminal with no argument it runs a magic-link flow — an email
address, then the 6-digit code sent to it. With a token as an argument, or a token
piped on stdin, it stores that bearer token directly, which is the form to use in CI.

Credentials are written to `~/.config/tada/credentials.json` (or
`$XDG_CONFIG_HOME/tada/credentials.json`), owner-only where the operating system
supports it. The location is the same on every platform; `%APPDATA%` is not used.

**Logging in is not the same as being able to render.** The render service accepts
premium accounts only. A free account can log in, browse the model and map catalogues
and author a project, but not render one. An interactive login tells you so as it
stores the credential.

`logout` removes what is stored on this machine. It does not revoke the session
server-side, so a credentials file copied elsewhere stays valid until it expires on
its own.

### render-bundle

A **render bundle** is an immutable tar holding a resolved configuration, a
precomputed frame plan, and every model, texture and piece of media the render
consumes. This package renders bundles; it does not create them. Bundles come from
the Travel Animator service — which is what the MCP server's render path requests —
or from Lascade's own server-side tooling. No command here produces one.

```bash
travel-animator render-bundle bundle.tar \
  -o video.mp4 \
  --attempt-dir ./attempt \
  --expected-sha256 "$(shasum -a 256 bundle.tar | cut -d' ' -f1)"
```

All three flags are required. `--attempt-dir` is scratch space the bundle is
extracted into; delete it afterwards. `--expected-sha256` authenticates the tar
before anything is extracted, and there is no way to skip it — use the digest
reported by whatever prepared the bundle. The shell substitution above only checks
the file against itself, which is handy by hand but proves nothing about origin.

`--encoder` defaults to `libx264`, which runs anywhere. Pass `--encoder h264_nvenc`
for NVIDIA hardware encoding; the choice is fail-closed, so NVENC never quietly
degrades to CPU encoding. `travel-animator render-bundle --help` lists every flag.

## Requirements for rendering

Everything other than rendering — logging in, running the MCP server, authoring a
project through it — needs only Python 3.12+ and this package's Python dependencies.
Rendering needs two more things, and a platform-tagged wheel carries both. Those
wheels are published for Linux on x86-64 and arm64, macOS on Apple silicon, and
Windows on x64; any other platform, including Intel macOS, installs the pure wheel
described below and cannot render.

- **A Java runtime.** Frames are drawn by a JVM subprocess, not by Python. A platform
  wheel bundles a trimmed Eclipse Temurin 21 runtime, so there is nothing to install
  and no system JDK is used.
- **A GLES 3.0 driver.** On macOS and Windows the wheel bundles ANGLE, which runs over
  Metal and Direct3D 11. On Linux it uses the system's own `libEGL`/`libGLESv2`, so a
  GPU driver — or Mesa, for software rendering — must be present. This is the usual
  thing to install on a bare server.

Encoding uses PyAV, which brings its own FFmpeg, so no system FFmpeg is required.

**The pure `py3-none-any` wheel carries no renderer and cannot produce frames.** It
fails with `renderer_unavailable`; everything else in the package still works.

### Rendering is not offline

A render reads its models and media from the bundle alone: a file the bundle does not
carry is a permanent `offline_cache_miss`, never a download. The basemap is the
exception — the map style's sprite sheet, glyphs, tile index and raster tiles are
fetched while rendering — so `render-bundle` fails on a machine with no connectivity.

Those basemap downloads are cached between renders, by default under
`${XDG_CACHE_HOME:-~/.cache}/tada/render`, pruned to 2 GiB before each render
(least-recently-used first). `--cache-dir` moves it, `--cache-max-bytes` changes the
budget, and `--no-cache` renders into throwaway scratch instead — leaving no disk
residue, at the cost of re-downloading every tile.

If a machine cannot render at all, the MCP server can fall back to a server-side
render; `render-bundle` on its own just fails. `get_capabilities` reports the problem
up front, before a project is built that this computer cannot finish.

## Analytics

Usage analytics are optional, opt-in, and off until you turn them on. Nothing is
collected before that, and nothing at all is collected outside the MCP server.

```bash
travel-animator analytics status   # what is currently set, and what it covers
travel-animator analytics on       # grant consent
travel-animator analytics off      # revoke it, effective immediately
```

The first interactive `login` asks once. Pressing Enter without answering declines,
and a decline is remembered rather than asked again.

**Collected:** which tools an assistant calls, in what order, how long they take and
whether they failed; render settings such as resolution, duration, animation style,
line style, map and vehicle; the *number* of points in a route and the set of
countries it crosses; how long preparation and rendering took, and whether they
succeeded.

**Never collected:** route coordinates, place labels, route annotations, file paths,
your media, the contents of any route you save or load, the names you give projects,
what a tool returned, and free-text intent. These are excluded unconditionally, and
consent does not unlock them: a route records where somebody has actually been.

Events are identified by the same opaque account id the render service already
records, and project identifiers are hashed on your machine under a salt that never
leaves it. Data is processed in the United States by PostHog, a third-party analytics
provider.

## Support

Questions, bug reports and feature requests go to <connect@travelanimator.com>.
Please include the command you ran, the error message it printed, and your operating
system. If you are reporting an MCP problem, the failing tool's `error_code` is the
most useful single detail.

More about Travel Animator: <https://travelanimator.com>.

## Licence

This is a limited use licence, not an open-source one. In short: you may install and
run `travel-animator` 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), the flag artwork (MIT) and — in a
platform-tagged wheel — the Eclipse Temurin runtime (GPLv2 with the Classpath
Exception), ANGLE, LWJGL, Skia/Skiko and the other libraries inside the renderer are
third-party works under their own licences, which that restriction does not touch.
Their notices and full licence texts, along with those of the Python packages pip
installs alongside this one, are in `tada_render/THIRD-PARTY-NOTICES.md`.

For redistribution or modification rights, contact Lascade.
