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

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

Deep Mode

Deep Mode expands capability usage across the full library surfaces, then enhances the hierarchy (lights, particles, camera dolly, bloom/grade, richer easings) via the active provider (heuristic offline, or SLM/cloud when configured):

anim = compose(
    "Type 'Beatoven' then drop a rubber ball in a Three.js room",
    provider="auto",   # uses cloud/local when keys/models available
    deep=True,
)
print(len(anim.plan.capability_usage), "capabilities bound")
anim.play()

# or enhance an existing animation
anim.deep("more cinematic camera and bloom")

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 "..." --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 play out/beat.json --runtime web
python -m beatoven export out/beat.json --out out/clip.html
python -m beatoven catalog --domain text_ui
python -m beatoven probe

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