Metadata-Version: 2.4
Name: beatoven
Version: 0.9.0
Summary: Compose hierarchical animation/simulation plans, record+transcribe audio into typed text playout, overlay on video, and inline-edit AnimationObjects
Author: Ephraim Hallford
License: MIT
Project-URL: Homepage, https://github.com/ehallford11714/beatoven
Project-URL: Documentation, https://github.com/ehallford11714/beatoven/blob/main/docs/INDEX.md
Project-URL: Repository, https://github.com/ehallford11714/beatoven
Project-URL: Issues, https://github.com/ehallford11714/beatoven/issues
Keywords: animation,simulation,gsap,threejs,manim,blueprint,slm,hierarchy,video,overlay,record,transcription,whisper
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pillow>=10.0
Requires-Dist: moviepy>=1.0.3
Requires-Dist: imageio>=2.31
Requires-Dist: imageio-ffmpeg>=0.4
Requires-Dist: openai>=1.0
Requires-Dist: anthropic>=0.20
Requires-Dist: torch>=2.0
Requires-Dist: transformers>=4.36
Requires-Dist: accelerate>=0.27
Requires-Dist: huggingface_hub>=0.20
Provides-Extra: play
Requires-Dist: pillow>=10.0; extra == "play"
Provides-Extra: video
Requires-Dist: moviepy>=1.0.3; extra == "video"
Requires-Dist: imageio-ffmpeg>=0.4; extra == "video"
Requires-Dist: imageio>=2.31; extra == "video"
Provides-Extra: camera
Requires-Dist: opencv-python>=4.8; extra == "camera"
Provides-Extra: record
Requires-Dist: sounddevice>=0.4; extra == "record"
Requires-Dist: numpy>=1.24; extra == "record"
Provides-Extra: whisper
Requires-Dist: openai-whisper>=20231105; extra == "whisper"
Provides-Extra: faster-whisper
Requires-Dist: faster-whisper>=1.0; extra == "faster-whisper"
Provides-Extra: openai
Requires-Dist: openai>=1.0; extra == "openai"
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.20; extra == "anthropic"
Provides-Extra: local
Requires-Dist: torch>=2.0; extra == "local"
Requires-Dist: transformers>=4.36; extra == "local"
Requires-Dist: accelerate>=0.27; extra == "local"
Requires-Dist: huggingface_hub>=0.20; extra == "local"
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == "mcp"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Provides-Extra: all
Requires-Dist: beatoven[camera,dev,mcp,record]; extra == "all"
Dynamic: license-file

<p align="center">
  <img src="assets/beatoven-logo.png" alt="Beatoven — painting a portrait" width="220"/>
</p>

# Beatoven

[![PyPI](https://img.shields.io/pypi/v/beatoven.svg)](https://pypi.org/project/beatoven/)
[![Python](https://img.shields.io/pypi/pyversions/beatoven.svg)](https://pypi.org/project/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):

```powershell
pip install beatoven
```

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

```powershell
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/](https://pypi.org/project/beatoven/)

### From source (development)

```powershell
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

```python
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

```python
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):

```python
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")
```

```powershell
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](docs/RECORD.md).

### Video import / record + text overlay

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

```python
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")
```

```powershell
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](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:

```python
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:

```powershell
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):

```python
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:

```python
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:

```python
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):

```powershell
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
```

```python
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](docs/MCP.md).

## CLI

```powershell
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

| Value | Behavior |
|-------|----------|
| `auto` | Cloud if API key present → else local Qwen when configured → else heuristic |
| `openai` / `claude` / `grok` | Cloud APIs |
| `openai_compatible` | `BEATOVEN_LLM_BASE_URL` + key + model |
| `local` | On-device Qwen/HF sized via hardware probe |
| `heuristic` | Offline catalog + hierarchy planner |

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

| Doc | Description |
|-----|-------------|
| [docs/INDEX.md](docs/INDEX.md) | Docs home |
| [docs/TUTORIAL.md](docs/TUTORIAL.md) | Step-by-step tutorial |
| [docs/API.md](docs/API.md) | Public API reference |
| [docs/COMPONENTS.md](docs/COMPONENTS.md) | Every module explained |
| [docs/CLI.md](docs/CLI.md) | CLI reference |
| [docs/LIBRARIES.md](docs/LIBRARIES.md) | Capability pack catalog |
| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Pipeline & Deep Mode |

## Example prompts

See [`examples/prompts.md`](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
