Metadata-Version: 2.4
Name: bee-one
Version: 1.0.0
Summary: Bee One Animation Studio: turn stories into 1980s-style cartoons via MCP and an HTML5 canvas stage
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: fastapi>=0.110
Requires-Dist: uvicorn[standard]>=0.29
Requires-Dist: mcp>=1.9
Requires-Dist: pydantic>=2.7
Requires-Dist: httpx>=0.27

# 🎬 Bee One Animation Studio

Turn any story — a novel excerpt, a training dialog, a corporate policy, a
bedtime story — into a playable **1980s Saturday-morning cartoon**, rendered
live in your browser with real character voices.

Bee One is a single local Python app that serves three things on one port:

| What | Where |
|---|---|
| The **stage** (HTML5 canvas web app) | `http://localhost:8888` |
| The **MCP server** for your LLM agent | `http://localhost:8888/mcp` |
| A human-readable director's guide | `http://localhost:8888/guide` |

Your LLM agent (Claude Desktop, Claude Code, Cursor, etc.) connects over MCP,
reads the authoring guide, turns your story into a JSON *action script*,
validates it, and pushes it straight onto the stage.

## Install & run

```bash
pip install -e .
bee-one            # optionally: bee-one --port 9000
```

Open `http://localhost:8888` in **Chrome or Edge** (they ship the natural
"Online/Neural" voices) and click **START STAGE** — the click is what grants
the browser permission for sound and speech.

## Connect an LLM client

**Streamable HTTP (recommended)** — add an MCP server with URL
`http://localhost:8888/mcp`. For example, in Google Antigravity
(`agy`), edit `~/.gemini/config/mcp_config.json`:

```json
{
  "mcpServers": {
    "bee-one": {
      "url": "http://localhost:8888/mcp"
    }
  }
}
```

then restart the server list with `/mcp` inside `agy`. (The key —
`"bee-one"` here — is the name your client shows for the tools.)

**stdio (fallback)** — for clients that can't do HTTP MCP: command `bee-one`,
args `["--stdio"]`. Your *client* launches this and talks JSON-RPC over its
stdin — running it by hand in a terminal just waits forever. It relays scripts
to the running `bee-one` web server, so start that first.

Then just ask your agent:

> Here's a short story: … Turn it into a cartoon on my Bee One stage.

## MCP tools

| Tool | Purpose |
|---|---|
| `get_authoring_guide()` | Director's guide: workflow, full schema vocabulary, directing tips, complete example |
| `get_capabilities()` | Machine-readable registry: backgrounds, actor options, gestures, effects, sfx, stage geometry |
| `validate_script(script_json)` | Validate without playing; returns precise, fixable errors |
| `play_script(script_json)` | Validate and play on the connected stage |
| `get_stage_status()` | Is a browser stage connected? What played last? |

The schema is defined once in `src/bee_one/schema.py` (Pydantic) and the guide
is generated from the same registry the engine implements — docs can't drift
from reality.

## What the engine can do

- **Cel-look rendering**: flat fills, chunky ink outlines, limited retro
  palette, characters animated **on twos** (12 fps poses at 60 fps playback),
  iris-wipe scene transitions, title cards, optional CRT scanline overlay.
- **Three rig types**: parameterized people (skin/build/hair/hat/glasses,
  8 expressions, 10 gestures, held items, real walk/run/sneak cycles with
  bending knees), robots (treads, claw arms, LED equalizer mouth), and cars
  (5 styles, wheels that actually roll, exhaust, night headlights).
- **Six layered backgrounds** (`diner`, `city_street`, `living_room`,
  `office`, `lab`, `forest`) with day/sunset/night variants, weather
  (rain/storm/snow), ambient life (neon flicker, passing traffic, sleeping
  cat, bubbling beakers, fireflies…) and true depth: actors pass **behind**
  counters and trees and **in front of** walls.
- **Voices & sound**: Web Speech API TTS with per-character natural-voice
  assignment and live lip flap, plus a procedural WebAudio retro sound bank
  (boom, zap, boing, sad trombone…). No audio assets, no subscriptions.
- **A cue-graph timeline**: cues run in sequence by default; actions inside a
  cue run in parallel; `after` + `delay` create overlaps (talk while walking
  while the camera tracks you).

## Try it without an LLM

Press **▶ PLAY DEMO** on the stage — it plays `static/demo.json`, a
three-scene episode generated from `short_story.txt`.

You can also drive it with curl:

```bash
curl -X POST http://localhost:8888/api/play -H "Content-Type: application/json" -d @src/bee_one/static/demo.json
```

## Notes & limits

- Keep the stage tab focused/visible — browsers throttle timers and speech in
  background tabs. Best under ~10 minutes per script; the validator warns on
  longer estimates.
- Voice quality depends on the browser. Edge on Windows has the best free
  natural voices; everything still works (with plainer voices) elsewhere, and
  with no voices at all the show plays silently with speech bubbles.
- If your agent plays a script while no stage tab is open (or before you click
  START STAGE), the server remembers it: the next tab to open gets it queued,
  and START STAGE (or ⟳ replay) plays it. ▶ PLAY DEMO always plays the bundled
  demo — it does **not** play your agent's script.
