Metadata-Version: 2.4
Name: narrateai-demomaker
Version: 0.11.0
Summary: MCP server that records and narrates demo, tutorial, and onboarding videos of your web app through the NarrateAI pipeline
Requires-Python: >=3.11
Requires-Dist: fastmcp[tasks]>=3.0.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: imageio-ffmpeg>=0.5.0
Requires-Dist: playwright>=1.44.0
Requires-Dist: pydantic>=2.6.0
Requires-Dist: uvicorn>=0.30.0
Description-Content-Type: text/markdown

# NarrateAI DemoMaker

> **"A demo video creator and narrator that lives in your codebase."**

An MCP server for Cursor / Claude Code that records narrated demo videos of your app. Your coding agent already knows your routes, selectors, auth, and test data — give it NarrateAI DemoMaker, and it produces a fully narrated MP4 of any flow you describe, end-to-end.

```
┌──────────────────┐     ┌─────────────────────────┐     ┌──────────────────────┐
│  You ask Cursor  │────▶│  Agent reads codebase   │────▶│  check_app(url)      │
│  for a demo video│     │  (routes, selectors,    │     │  → confirms reachable│
└──────────────────┘     │   auth, fixtures)       │     └──────┬───────────────┘
                         └─────────────────────────┘            │
                                                                ▼
┌──────────────────┐     ┌─────────────────────────┐     ┌──────────────────────┐
│  Final MP4 URL   │◀────│  NarrateAI narration    │◀────│  NarrateAI records   │
│  (narrated)      │     │  pipeline               │     │  your session →      │
└──────────────────┘     └─────────────────────────┘     │  WebM → MP4          │
                                                         └──────────────────────┘
```

---

## What it does

- **Records** your running app or a live notebook tutorial (vscode.dev) in an isolated headless browser session — real cursor motion, viewport capture, no manual screen recording.
- **Narrates** the recording through NarrateAI's full narration pipeline: frame analysis, transcript generation, TTS with your chosen voice, final video assembly.
- **Reads your codebase** to find routes, `data-testid` selectors, test credentials, auth flows, and DOM ready signals — so the agent plans selectors it can actually hit.
- **Handles iframes** (website builders like Odoo / Webflow, embedded checkouts, Storybook, etc.) via the `frame` field in the plan schema.
- **Handles auth** — email/password inline, or one-shot `save_auth_session` for OAuth / magic links / 2FA.
- **Handles notebook tutorials** — open vscode.dev, type + run Jupyter cells, produce a how-to video with the right narrator cadence.
- **Picks the narrator's voice mode** — `demo` for product showcases, `how_to` for tutorials, `story` for narrative / presentation videos.

---

## Install (one line)

```bash
uvx narrateai-demomaker init
```

This command:
1. Detects your agent (Cursor or Claude Code) from the current project.
2. Creates / merges an `mcp.json` entry for `narrateai-demomaker`.
3. Drops `SKILL.md` + all reference docs into your agent's skills folder (progressive disclosure, so only what's needed enters context).
4. Prompts for your NarrateAI API key (stored in the config file's `env` block).

Then restart your agent. Ask:

> *"Make a 30-second demo of someone signing in and uploading a doc."*

The agent will read your codebase, propose a plan, record it, narrate it, and hand you an MP4 URL.

### Options

```bash
uvx narrateai-demomaker init --global           # install for all projects
uvx narrateai-demomaker init --api-key sk_...   # non-interactive key
uvx narrateai-demomaker init --agent cursor     # force agent choice
```

Re-running `init` is safe — it merges with your existing config rather than overwriting.

---

## Prerequisites

- **Python 3.11+** (handled by `uvx` automatically)
- **ffmpeg** on PATH — `brew install ffmpeg` / `apt install ffmpeg`. A bundled fallback is attempted via `imageio-ffmpeg`, but a real system install is more reliable.
- **A NarrateAI API key** — sign up at [narrateai.app](https://narrateai.app). The `init` command prompts for it; you can also set `NARRATEAI_API_KEY` in your agent's MCP `env` block manually.

The required Chromium binary is downloaded automatically the first time you run a recording (~170 MB, one-time).

---

## Tools exposed to your agent

### `check_app(url, viewport_width=1440, viewport_height=900, take_screenshot=False)`

Cheap probe (~3s). Returns reachability, page title, and up to 60 stable interactive selectors. The agent always calls this before planning.

### `save_auth_session(start_url, label, done_when_url="", done_when_selector="", timeout_seconds=300)`

One-time per app. Opens a **headed** browser so the user can sign in through OAuth / magic link / 2FA flows manually. The session is saved to `~/.narrateai-demomaker/auth/<label>.json` and reused by future recordings when you pass `auth_session=<label>` to `create_demo_video`.

### `create_demo_video(url, plan, narration_type="demo", voice_type="male1", language="en", auth_session="", headless=True)`

The main tool. Validates the plan → records → transcodes → uploads → narrates → polls → returns `video_url`. Runs as a long-running task with progress reporting.

- `plan` is a JSON object — the agent builds this from reading your codebase (see `skill/SKILL.md`).
- `narration_type` changes the narrator's voice: `"how_to"` for tutorials, `"demo"` for product showcases (default), `"story"` for narrative videos.

---

## What this is NOT for

- **Editing existing videos** — use the regular `narrateai` MCP (`narrate_video_full`, `dub_video_full`, etc.).
- **Transcribing meetings** — `narrateai` MCP's `transcribe_video`.
- **Recording native desktop apps** (VS Code Desktop, Cursor itself, Electron apps) — NarrateAI DemoMaker drives browsers only. For notebook tutorials use vscode.dev (browser) or a local JupyterLab server.
- **Scraping arbitrary public URLs you don't own** — flaky, OAuth-blocked, not the design goal.

---

## On-disk artifacts

- Recordings: `~/.narrateai-demomaker/runs/<timestamp>/demo.mp4` (plus the source `.webm`)
- Failed-step screenshots: `~/.narrateai-demomaker/runs/<timestamp>/step_NN_failed.png`
- Auth sessions: `~/.narrateai-demomaker/auth/<label>.json`

All safe to clean up any time.

---

## Troubleshooting

**"ffmpeg not found"** — install ffmpeg (`brew install ffmpeg`).

**"Browser engine not installed"** — happens on first run. The MCP self-installs Chromium; allow 1–2 minutes.

**"API key required"** — `NARRATEAI_API_KEY` is missing from your agent's `mcp.json` `env` block. Re-run `narrateai-demomaker init` to be prompted.

**Recording succeeds but narration fails** — the MP4 is still on disk at the `mp4_path` returned in the error. You can re-narrate it via the regular `narrateai` MCP (`narrate_video_full(video_path=...)`).

**A step keeps failing** — have the agent call `check_app(take_screenshot=True)` for fresh confirmed selectors. Most common cause: a guessed selector vs. one the recorder can actually find. `data-testid` is your friend.

**"Element not found" on an iframe target** (Odoo's editor preview, Stripe Checkout, Storybook preview panes) — the agent needs to set the `frame` field on the step. See `skill/references/iframe-targeting.md`.

---

## Under the hood

For the curious — you don't need to care about any of this to use the MCP:

- The recorder is built on [Playwright](https://playwright.dev) + headless Chromium. We chose Playwright because it's mature, maintained by Microsoft, and supports `storageState` / `frame_locator` out of the box.
- The narration pipeline is NarrateAI's proprietary backend — frame analysis, transcript generation, voice synthesis, and video assembly all happen server-side and are what the API key gates.
- `ffmpeg` handles the WebM → MP4 transcode (via `imageio-ffmpeg` with a system-binary fallback).
- The MCP server uses [FastMCP](https://github.com/jlowin/fastmcp) over stdio — no network ports opened locally.

If you want to debug the browser layer, standard Playwright diagnostics work (the recorder writes failed-step screenshots to `~/.narrateai-demomaker/runs/.../`).

---

## License

See the parent repo for licensing. The NarrateAI narration API is a hosted service gated by API key; the MCP itself is client code you're free to inspect.
