Metadata-Version: 2.5
Name: travel-animator
Version: 1.2.2
Summary: Render Travel Animator route animations to MP4, from the command line or an MCP server
Project-URL: Homepage, https://travelanimator.com
Project-URL: Documentation, https://github.com/Lascade-Co/travelanimator-mcp#readme
Project-URL: Issues, https://github.com/Lascade-Co/travelanimator-mcp/issues
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 :: 5 - Production/Stable
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

<!-- mcp-name: com.travelanimator/mcp -->
<!-- Required by the MCP registry to verify ownership of this PyPI package; must match
     `name` in travelanimator-mcp's server.json. Do not remove. -->

# travel-animator

Render Travel Animator route animations to MP4 on a computer instead of a phone —
the route drawing itself as it is travelled, a 3D vehicle following it, map labels,
country flags, and the distance badge and watermark the app draws on top.

Two ways to use it:

- **MCP server** — an AI assistant plans the route, chooses how the animation looks
  and renders it for you. The only path that goes from nothing to a finished video.
- **Command line** — `render-bundle` 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          # command line
pip install "travel-animator[mcp]"   # command line + MCP server
```

Python 3.12 or newer. Rendering also needs a platform wheel — see
[Rendering](#rendering).

## Use it from an AI assistant

Log in once. The assistant can do it in the conversation: it asks for the email
address on your Travel Animator account, calls `login`, and asks you to read back the
6-digit code the email contains (or paste the whole link) for `complete_login`. Or do
the same from a terminal:

```bash
uvx travel-animator login
```

Register the server with your client. For Claude Code:

```bash
claude mcp add travel-animator -e TADA_SOURCE=pypi -- uvx --from "travel-animator[mcp]@latest" travel-animator mcp
```

For Claude Desktop, or any other client that takes a JSON config:

```json
{
  "mcpServers": {
    "travel-animator": {
      "command": "uvx",
      "args": ["--from", "travel-animator[mcp]@latest", "travel-animator", "mcp"],
      "env": { "TADA_SOURCE": "pypi" }
    }
  }
}
```

`@latest` picks up the newest release on every launch. Drop it, or use a
pip-installed `travel-animator` as the command, to stay on a fixed version.

`TADA_SOURCE` records which set of instructions this config came from — here, this
page — so we can tell which of them are worth maintaining. It is optional and safe
to delete; it carries nothing about you or your routes.

Then describe the animation you want — the route, the vehicle, the map style, the
resolution. The assistant builds the project, reports progress while it renders, and
hands back the finished MP4.

If the server fails to start from a desktop app, give the command's absolute path
instead: apps launched from a GUI do not inherit your shell's `PATH`, and `which uvx`
prints it.

## Commands

```text
travel-animator login           # log in: magic link, or a bearer token for CI
travel-animator logout          # remove credentials stored on this machine
travel-animator analytics       # show, grant or revoke analytics consent
travel-animator render-bundle   # render a prepared bundle to MP4
travel-animator mcp             # run the MCP server (needs the mcp extra)
```

`login` uses the same account as the Travel Animator mobile app. **Logging in is not
the same as being able to render:** a free account can log in, browse the catalogues
and author a project, but only a premium account can render one.

Render bundles come from the Travel Animator service — this package renders them, it
does not create them. `travel-animator render-bundle --help` lists every flag.

When a newer release exists, a command upgrades itself to it after finishing and says
so on stderr; the new version applies to the next command. `TADA_AUTO_UPGRADE=0` keeps
the notice without installing, `TADA_UPDATE_CHECK=0` turns off both.

## Rendering

Everything other than rendering — logging in, running the MCP server, authoring a
project through it — needs only Python 3.12+ and this package.

Rendering needs a platform wheel. Those are published for Linux on x86-64 and arm64,
macOS on Apple silicon, and Windows on x64; any other platform, including Intel
macOS, gets a pure Python wheel that **cannot render frames**.

A platform wheel brings its own Java runtime, so there is nothing to install. It also
bundles a graphics driver on macOS and Windows; on Linux it uses the system's own
GLES driver, or Mesa for software rendering.

Rendering is not offline: the map's tiles, glyphs and sprites are fetched as frames
are drawn, then cached under `~/.cache/tada/render`. Everything else a render needs
comes from the bundle itself.

If a machine cannot render at all, the MCP server can fall back to a server-side
render — and it says so up front, before a project is built that the machine cannot
finish.

## Credits

Each rendered video costs one credit, whatever its length or resolution. The charge is
made by the render service when it prepares the video, so nothing is spent by a project
you build and never render, and re-rendering the same video within the hour is free.

`get_credit_balance` says how many are left, `list_credit_packages` what is on sale, and
`buy_credits` returns a Stripe link to open in a browser. Credits are added once payment
completes, so check the balance again afterwards rather than assuming. A render with an
empty wallet is refused before anything starts.

A credit is consumed once the render service has prepared the video, even if the render
then fails on your machine — a known limitation for now. The server retries a transient
renderer failure once on its own before reporting it, and refuses configurations it can
tell will not render (a duration below the route's minimum, an invalid setting) before
anything is charged.

## Analytics

Usage analytics are optional and **on by default**, and nothing at all is collected
outside the MCP server. Turning them off takes one command, takes effect immediately
— including in a server that is already running — and is remembered permanently. The
first interactive `login` says so on the terminal; it does not ask, because there is
nothing to answer.

```bash
travel-animator analytics status   # what is currently set, and what it covers
travel-animator analytics off      # turn it off, effective immediately and for good
travel-animator analytics on       # turn it back on
```

**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,
map and vehicle; the *number* of points in a route and the set of countries it
crosses.

**One free-text exception:** when an assistant asks for a tool this server does not
have, the description it writes of what it was trying to accomplish is collected with
that request (up to 2048 characters). The assistant writes that sentence about your
task, so it can quote what you asked for. It is collected because a server cannot
otherwise learn which capability it is missing, and it is sent *only* on that request
— never as a reason attached to an ordinary tool call. Like everything else here, it
is collected by default; `analytics off` stops it along with the rest.

**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,
and what a tool returned. These are excluded unconditionally, and consent does not
unlock them: a route records where somebody has actually been.

Analytics data is processed in the United States by 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, the output of
`travel-animator --version`, and your operating system. For an MCP problem, the failing
tool's `error_code` and the full `error_message` of `await_render` (which carries the
renderer's own diagnostic after `details:`) are the most useful details.

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, the flag artwork and the libraries inside the renderer are
third-party works 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.
