HKUSTDial/DataMagic

AI-powered data-to-video generation. Upload a table, get a narrated animated data story.

📚 What is DataMagic?

DataMagic is an open‑source toolkit that lets you turn tabular data (CSV, Excel, etc.) into short, animated video stories. It ships with a library of 139 “recipe cards” – each card describes a specific visual effect (e.g., a ranking reveal, a map‑based comparison, a character‑driven walkthrough) together with:

an animated preview,
the declarative source code that generates the effect, and
sample data.

A datamagic Skill (a set of prompts and helper scripts) lets a programming agent (e.g., a LLM‑powered code‑assistant) automatically:

Pick a suitable recipe for your data,
Fill the template with your own numbers, labels, colors, and assets,
Render the video, and
Verify the output.

The project is backed by two peer‑reviewed papers (IEEE VIS 2026 and VLDB 2026 Demo) and an online demo site where you can upload a spreadsheet and get a finished video in seconds.

🛠️ Core components

Component	What it does	Where to find it
Recipe cards	Declarative specifications of a visual narrative (animation timeline, chart type, narration cues).	`cards/recipes/` and the web gallery https://datamagic.chat/cards/
Template source code	Re‑usable scripts (Python/JS) that read a CSV, map fields to visual elements, and drive the rendering engine.	Linked from each card; also in `cards/`
datamagic Skill	Prompt library + small utilities that let a code‑generating agent locate the right template, substitute data, and run the renderer.	`skills/datamagic/`
Online system	Hosted service that orchestrates the whole pipeline (data upload → recipe recommendation → video generation).	https://datamagic.chat/
Research docs	Descriptions of the underlying pipeline (DVSpec), evaluation, and citation info.	`docs/`

🚀 How to use it (quick‑start)

Clone the repo

git clone https://github.com/HKUSTDial/DataMagic.git
cd DataMagic

Pick a recipe – browse the web gallery or the local cards/recipes/ folder. Click Copy implementation command to get a one‑line instruction.
Run the agent – paste the command into your favourite LLM‑powered coding assistant (e.g., OpenAI ChatGPT with function‑calling, Claude, or a locally hosted model). Provide your CSV and any custom styling notes.
Render – the skill will locate the template, inject your data, call the rendering backend, and output an MP4 plus the edited source files.
Iterate – ask the agent to tweak timing, colors, subtitles, or replace assets; the workflow is fully repeatable.

A 72‑second demo (coffee‑shop sales) shows the whole loop from search → recipe → command → generated video.

🎯 Who should care?

Audience	Why it matters
Content creators / social media managers	Produce eye‑catching data videos without learning animation software.
Data analysts / researchers	Turn static tables into narrative visualizations that can be shared in presentations or papers.
AI/ML developers	Example of declarative multi‑agent orchestration – a concrete use‑case for LLMs that generate and run code.
Educators	Ready‑made templates for teaching statistics, economics, or geography with animated storytelling.

📖 Documentation & community

Web gallery & live editor – https://datamagic.chat/cards/ (preview, edit, download source).
Skill guide – skills/datamagic/README.md (installation, prompt format, troubleshooting).
Full‑story workflow – skills/datamagic/rules/full-story-workflow.md (combining multiple cards into a coherent narrative).
Research papers – IEEE VIS 2026 and VLDB 2026 links in the README.
Community – WeChat groups (QR codes in the repo) for sharing creations and getting support.

⭐️ Quick take‑away

DataMagic is a real, research‑backed platform that bridges data analysis and video production through declarative recipe cards and LLM‑driven code orchestration. It’s useful for anyone who wants to automate the creation of data‑driven video stories, and the repo provides all the templates, agent‑skill prompts, and documentation needed to get started.