Skip to main content
Version: Next 🚧

Installation

Install Murali Kit. That is the usual authoring path, and it pulls in a compatible engine:

python3 -m pip install murali-kit

Then:

from murali_engine import Scene
from murali_kit.themes import DarkTheme

scene = Scene()
scene.apply_theme(DarkTheme())
scene.preview()

Pinned versions:

python3 -m pip install murali-engine==0.3.0
python3 -m pip install murali-kit==0.3.0

murali-kit depends on murali-engine>=0.3.0,<0.4.0. Installing the engine alone does not install the kit.

What you get​

PackageImportRole
murali-kitmurali_kitThemes, named colors, teaching views, examples
murali-enginemurali_engineScene, primitives, timeline, preview, export

Python 3.10 or newer. A GPU-capable graphics environment for preview. ffmpeg if you want MP4 or GIF export. latex and dvisvgm only if you use Latex. Typst is embedded; it does not need a system install.

Prebuilt wheels​

murali-engine ships prebuilt wheels for:

  • macOS arm64 and x86_64
  • Linux x86_64 and aarch64
  • Windows x86_64

Those installs do not need a local Rust toolchain. Other platforms can still build from the source distribution if Rust 1.85+ is available.

Preview vs export​

Preview (scene.preview()):

  • needs a working graphics environment
  • does not require ffmpeg

Export:

  • scene.save_png(path) always writes a PNG
  • scene.export_video(path) uses ffmpeg to assemble MP4 or GIF
  • if ffmpeg is missing, Murali still writes frames and tells you where they landed

preview(), save_png(), export_video(), and export() consume the scene. Call one of them at the end of the script.

Local engine development​

Only if you are changing the engine itself, from a checkout of this repository:

uv sync
uv run pytest python/tests
uv run python python/examples/hello_shapes.py

Install uv first. It creates the local .venv, installs the locked development tools, builds the extension through maturin, and keeps the environment synchronized with pyproject.toml. After changing Rust binding code, rebuild the editable extension with uv run maturin develop --features python. End-user wheel installation does not require uv.

Kit examples live in the murali-kit repository. Develop against an adjacent engine checkout using that repository's uv development configuration.

Core Rust Engine​

Use this path when you are working on the runtime, not when you are writing new scenes. For Rust-authored animations on a frozen API, pin murali 0.2.4 and follow the 0.2.4 docs. Current crate versions keep Rust as the engine only.

You need Rust 1.85 or newer, cargo, and a graphics environment for preview.

[dependencies]
murali = "0.3.0"
anyhow = "1"
glam = "0.33"
git clone https://github.com/murali-engine/murali
cd murali
cargo run --example hello_shapes --release -- --preview

The published crate excludes examples/**. Reference examples are in the GitHub repository.

Some Rust APIs are feature-gated. The linear-algebra visual toolkit currently needs experimental:

[dependencies]
murali = { version = "0.3.0", features = ["experimental"] }
cargo run --features experimental --example linear_algebra_vectors

See Experimental Features and Your First Scene (Rust).

Project config​

Murali looks for a nearby murali.toml. A minimal config:

[preview]
fps = 60

[export]
fps = 60
width = 1920

Murali finds the project by walking upward to the nearest murali.toml. In Python, the search starts beside the executing script, so python3 /path/to/project/scenes/intro.py finds /path/to/project/murali.toml even when the current directory is elsewhere. Interactive Python and notebooks, which do not have a script path, search upward from the current working directory.

In a Python project, keep Murali's config beside the Python package manifest:

my-animation/
├── pyproject.toml
├── murali.toml
└── scenes/
    └── intro.py

width is the output width in pixels. Height follows the scene's landscape, portrait, or square video format. The repo includes murali.toml.example.