Beatoven

Compose hierarchical animation & simulation plans, generate full library-backed code, play it back, and inline-edit with .edit.

Beatoven turns a prompt into a playable AnimationObject:

• Imports full capability surfaces for GSAP, Anime.js, Motion, Theatre.js, Typed.js, Three.js, Lottie, Manim, MoviePy, Textual, Bevy, Unity, libGDX, and more
• SLM / cloud guided compose binds real library APIs (not a tiny subset) via heuristic, local Qwen, or OpenAI/Claude/Grok
• Builds a hierarchy plan: scene → acts → shots → layers → tracks → keyframes
• Supports draft → finalize and Deep Mode cinematic enhancement
• Returns runnable code (not stubs) plus a built-in web player
• anim.edit(...) / anim.deep(...) for inline revisions and capability-max enhancements
• Optional Hugging Face SLM (hardware-sized Qwen) or cloud providers when API keys are set

Install

From PyPI (recommended)

pip install beatoven pulls the full dependency stack — play (Pillow), video (MoviePy / imageio-ffmpeg), cloud clients (OpenAI + Anthropic), and local SLM (torch / transformers / accelerate / huggingface_hub):

pip install beatoven

pip install -U beatoven
beatoven --help
python -c "from beatoven import compose; print(compose('Type Hi', provider='heuristic').summary())"

pip install "beatoven[dev]"   # pytest, ruff, build, twine
pip install "beatoven[mcp]"   # MCP stdio server for Cursor / Claude Code

Package: https://pypi.org/project/beatoven/

From source (development)

git clone https://github.com/ehallford11714/beatoven.git
cd beatoven
python -m venv .venv
.\.venv\Scripts\pip install -e ".[dev]"
python -m pytest -q

Quick start

from beatoven import compose

anim = compose(
    "Type 'Beatoven' letter-by-letter, then drop a rubber ball in a Three.js room",
    languages=["javascript", "python"],
    provider="heuristic",  # or auto / local / openai / claude / grok
)

print(anim.plan.summary())
print(anim.code["javascript"][:400])

anim.play()  # opens browser player

anim.edit("make the title blue and stagger faster")
anim.edit(path="scene/act1/shot1/title", props={"text": "Beatoven Live"})
anim.export("out/index.html")

Draft + edit

anim = compose("Type 'Draft Scene' + bouncing ball", draft=True)
anim.edit("use Typed.js style typing; title color cyan")
anim.finalize()
anim.play()

Record suite (audio → STT library → typed playout)

Dedicated beatoven.record suite records microphone audio, transcribes with a chosen library (whisper / faster-whisper / openai / heuristic), then plays the text out via typed.js (or gsap/anime/motion):

from beatoven.record import RecordSuite, capture_and_play

capture_and_play(force_text="Hello from voice", playout="typed", out="out/from_voice.html")

suite = RecordSuite(transcriber="whisper", playout="typed")
suite.record(seconds=4)
suite.transcribe()
suite.playout(out="out/typed.html")

pip install "beatoven[record]" "beatoven[whisper]"
beatoven record capture --force-text "Demo" --playout typed --out out/from_voice.html
beatoven record libraries

Guide: docs/RECORD.md.

Video import / record + text overlay

Native beatoven.video module overlays typed text animations onto imported or recorded footage:

from beatoven import compose
from beatoven.video import VideoStudio

studio = VideoStudio.import_file("clip.mp4")
studio.overlay_text("Hello", out="out/hello.mp4", position="lower-third")

anim = compose("Type 'Live' + bouncing ball", provider="heuristic", export=False)
studio.overlay_animation(anim, out="out/live.mp4")

# Or in one compose call:
compose("Type 'Caption'", provider="heuristic", video="clip.mp4", out="out/caption.mp4")
# Webcam (needs: pip install beatoven[camera]):
compose("Type 'Rec'", provider="heuristic", record={"seconds": 4}, out="out/rec.mp4")

pip install "beatoven[camera]"   # opencv for webcam record
beatoven video overlay clip.mp4 --prompt "Type Hi" --out out/hi.mp4
beatoven video record --seconds 5 --out out/rec.mp4

Full guide: docs/VIDEO.md.

Output file types (gif / mp3 / html / …)

Pass the animation file type into compose — it sets plan.outputs and can write the file immediately:

anim = compose(
    "Type 'Beatoven' then bounce a ball",
    provider="heuristic",
    output="gif",                 # or filetype= / format=
    out="out/scene.gif",          # writes the file
)
print(anim.plan.outputs)          # ['gif']
print(anim.artifacts["export"])   # {'format': 'gif', 'path': ...}

# also: mp3, wav, html, mp4, png, jpg, svg, json, python, javascript, …
anim = compose("Type 'Hi' as html", provider="heuristic", filetype="html", out="out/index.html")

CLI:

beatoven compose --prompt "Type Hi" --output gif --export-file out/scene.gif
beatoven compose --prompt "Type Hi" --filetype mp3 --out out
beatoven export out/beat.json --out out/clip.gif --format gif

Grounded iterative satisfaction

Compose now verifies the plan/code against the prompt using a documentation contract (libraries, physics, engines, typing) and iteratively repairs gaps until the threshold is met (default on):

anim = compose(
    "Type 'Nova' then drop a rubber ball in a Babylon physics room",
    provider="heuristic",
    grounded=True,              # default
    max_ground_iters=3,
    satisfaction_threshold=0.85,
)
print(anim.verify().summary())  # [PASS] score=...
anim.ground(max_iters=2)        # force another grounded repair loop

Direct object playback (showWhenDone)

Playback is no longer HTML-only. You get a live Python / JS / IR player object:

anim = compose("Type 'Beatoven' then bounce a ball", provider="heuristic")

# Python player object — samples IR, shows native window when done
player = anim.play(runtime="python", show_when_done=True)
print(player.sample(1.0))

# JavaScript-facing object (dict) for hosts / notebooks
js = anim.to_js_object(show_when_done=True)
print(js["type"], js["duration"])

# Force classic HTML file preview
anim.play(runtime="web", object_playback=False, show_when_done=True)

Deep Mode + multicascade

Deep Mode expands capability coverage. Cascade runs multi-pass SLM/heuristic refinement (structure → physics → cinematography → detail → engine bind) for Babylon / Unity / Bevy / Three complex scenes:

anim = compose(
    "Babylon physics room with stacked boxes and a bouncing ball",
    provider="auto",
    cascade=True,
    cascade_passes=4,
)
print(anim.plan.enhancements["cascade"])
anim.play(runtime="python", show_when_done=True)

anim.deep("more cinematic camera and bloom")
anim.cascade("richer multi-body physics", passes=3)

Agents (MCP / Cursor / Claude Code)

Coding agents can call Beatoven directly via MCP tools or the in-process AgentHook (no SDK required):

pip install "beatoven[mcp]"
beatoven agents install          # writes .cursor/mcp.json + .mcp.json + skills
beatoven agents status
python -m beatoven.mcp --list-tools
# or: beatoven-mcp / beatoven mcp

from beatoven.connective import AgentHook

hook = AgentHook()
r = hook.call_tool("beatoven_compose", {"prompt": "Type 'Hi'", "provider": "heuristic"})
assert r["ok"]
print(hook.call_tool("beatoven_verify", {}))

Full setup: docs/MCP.md.

CLI

python -m beatoven compose --prompt "Type 'Hello' then bounce a ball" --lang javascript,python --play
python -m beatoven compose --prompt "..." --deep --play
python -m beatoven compose --prompt "Babylon physics stack" --cascade --cascade-passes 4 --play
python -m beatoven compose --prompt "..." --draft --out out
python -m beatoven edit out/beat.json --instruction "make the title blue and stagger faster"
python -m beatoven deep out/beat.json --instruction "cinematic bloom + dolly" --play
python -m beatoven cascade out/beat.json --passes 4 --play
python -m beatoven play out/beat.json --runtime python
python -m beatoven play out/beat.json --runtime web --html
python -m beatoven export out/beat.json --out out/clip.html
python -m beatoven catalog --domain text_ui
python -m beatoven probe
python -m beatoven mcp --list-tools
python -m beatoven agents install
python -m beatoven agents status

Providers

Environment: OPENAI_API_KEY, ANTHROPIC_API_KEY, XAI_API_KEY / GROK_API_KEY, BEATOVEN_LLM_API_KEY, BEATOVEN_LLM_BASE_URL, BEATOVEN_LLM_MODEL, BEATOVEN_PROVIDER, BEATOVEN_LOCAL_MODEL.

Documentation

Example prompts

See examples/prompts.md. Runnable scripts:

• examples/text_typing_web.py
• examples/draft_and_edit.py
• examples/threejs_physics_scene.py
• examples/deep_mode_demo.py

Layout

src/beatoven/     # library
  capabilities/   # full API surfaces per library
  generators/     # JS / Python / Rust / C# / Java
  runtime/        # play + export
  providers/      # heuristic / local / cloud
tests/
examples/
docs/             # tutorial, API, components, CLI, libraries

License

MIT