vizreel

Animated charts for video, from a YAML file.

vizreel turns a short YAML spec into clean, animated chart clips (big numbers, line charts, bar charts and timelines) ready to drop into any video editor. Clips render with a transparent background by default, so they layer directly over your footage.

Status: 0.1.0, the first release. The spec format is version 1. See the changelog and the roadmap.

Why

Most chart tools are made for reports and dashboards. On video they look static and crowded, and animating them by hand in a motion graphics tool takes time for every chart.

vizreel is built for video from the start:

• Declarative. Describe the chart and its data in YAML. No code, no timeline editing.
• Made to be watched. Large type, one message per chart, a clear highlight moment, smooth eased motion, a clean final frame. See the design rules.
• Editor-ready. One clip per chart, transparent background, 1080p or 4K at 60 fps.
• Consistent. Colors, fonts and timing come from a theme, so every chart in a video matches.
• Easy to install. Pure Python. No LaTeX, no separate FFmpeg install.

Installation

Requirements: Python 3.11 or 3.12 on Windows or Linux. Other Python versions and macOS may work but are untested.

With uv (recommended), which puts the vizreel command on your PATH:

uv tool install vizreel
vizreel --version

With pip, in a virtual environment. On Windows, in PowerShell:

py -m venv .venv
.venv\Scripts\activate
python -m pip install vizreel
vizreel --version

If PowerShell says that running scripts is disabled, run Set-ExecutionPolicy -Scope CurrentUser RemoteSigned once and activate again. On Linux and macOS, activate with source .venv/bin/activate.

Quickstart

Create a spec from a template, then render it:

vizreel new stat -o chart.yaml
vizreel render chart.yaml --quality preview --still

out/
├── customers.mov    ← the clip, with a transparent background
└── customers.png    ← its last frame

Open chart.yaml, change the number and the label, and render again. Without --quality preview, the clip renders at full quality: 1080p at 60 fps unless the spec says otherwise.

Example

A spec can hold several charts; each renders to its own clip:

version: 1
meta:
  theme: default
  resolution: 1080p

charts:
  - id: peak-valuation
    type: stat
    value: 740000000
    label: Northwind's peak valuation
    number: { prefix: "$", compact: true }

  - id: offers
    type: bar
    title: Offers Northwind received
    bars:
      - { label: "Buyer A (2015)", value: 740000000 }
      - { label: "Buyer B (2016)", value: 70000000 }
      - { label: "Buyer C (2016)", value: 40000000 }
    number: { prefix: "$", compact: true }
    highlight: { label: "Buyer C (2016)" }

vizreel render charts.yaml

out/
├── peak-valuation.mov
└── offers.mov

Chart types

vizreel new TYPE prints a commented template for each. Every field is documented in the spec reference.

Usage

vizreel new line -o charts.yaml         # start from a commented template
vizreel validate charts.yaml            # check a spec and list every error
vizreel render charts.yaml              # render all charts to ./out
vizreel render charts.yaml --only offers --quality preview --still
vizreel schema -o vizreel.schema.json   # JSON Schema for editors and tools
vizreel themes list                     # built-in themes
vizreel theme check my-brand.yaml       # contrast and color vision checks for a theme

Using the clips in a video editor

mov clips (the default) keep a transparent background: place them on a track above your footage. They use the QuickTime Animation codec, which editors read but many media players, such as the Windows media player, cannot play. That is expected; open them in your editor.

webm clips also contain transparency, but not every editor reads it. Use --format mp4 when you do not need transparency: the chart is drawn on the theme's background color.

Themes

A theme sets colors, fonts, text sizes and motion timing for every chart. vizreel ships with two built-in themes, default (dark) and light, and you can write your own in YAML and point to it from your spec:

meta:
  theme: themes/my-brand.yaml

Start from examples/themes/example-brand.yaml, and run vizreel theme check on your theme to test its contrast and its colors for color vision deficiency. Every field is described in the theme reference.

Documentation

• Spec reference
• Theme reference
• Design rules
• Architecture
• Roadmap
• Changelog

Development

git clone https://github.com/efedalbay/vizreel.git
cd vizreel
uv sync
uv run pytest -m "not render"   # fast tests
uv run pytest -m render         # rendering tests

Contributing

Issues and pull requests are welcome. Before starting on a larger change, please open an issue to discuss it. New chart types follow the contract in the architecture document and the rules in the design document.

License

MIT

vizreel is built on Manim Community Edition. It bundles the Inter typeface by The Inter Project Authors, licensed under the SIL Open Font License 1.1 (see src/vizreel/assets/fonts/Inter-OFL.txt).