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. The Python import path is tada_render.

Install

pip install travel-animator

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

pip install "travel-animator[mcp]"

Requires Python 3.12 or newer. Rendering has further platform requirements; see 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.

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

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

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

   {
     "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

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.

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.

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.

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.

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 the assistant's reasoning for any ordinary tool call. 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.