# demofly

Automated demo video generation from the command line. Record browser interactions, generate narration with text-to-speech, and assemble polished demo videos — all in one workflow.

## Installation

```bash
npm install -g demofly
```

Requires **Node.js 22** or later.

## Quick Start

```bash
# Initialize prerequisites (Playwright, ffmpeg, TTS models)
demofly init

# Generate a demo (record + narrate + assemble)
demofly generate my-demo --record

# Push to the cloud
demofly push my-demo
```

## Commands

### Core Workflow

| Command | Description |
|---------|-------------|
| `demofly init` | Install prerequisites (Playwright, ffmpeg, Kokoro TTS model) |
| `demofly generate <demo>` | Record, narrate, and assemble a demo video |
| `demofly push <demo>` | Push a completed demo to the demofly cloud |
| `demofly status` | Check prerequisite status without installing |

### Generate Options

```
--record              Record browser interactions with Playwright
--audio               Generate narration audio only
--video               Record video only (skip audio)
--assemble            Full intelligent assembly (align + retiming)
--scene <id>          Generate audio for a specific scene
--voice <name>        TTS voice (e.g., "heart", "aria")
--provider <provider> TTS provider (kokoro, elevenlabs, openai)
--speed <multiplier>  TTS speed multiplier (default: 1.0)
--no-audio            Skip TTS generation
--verbose             Show detailed debug output
```

### Authentication

```bash
demofly auth login              # Device code flow (default)
demofly auth login --browser    # OAuth browser flow
demofly auth login --otp        # Email OTP
demofly auth logout             # Clear credentials
demofly auth status             # Check login state
```

### Demo Management

```bash
demofly demos list              # List local and cloud demos
demofly demos get <name>        # Get demo details
demofly demos update <name>     # Update demo metadata
demofly demos delete <name>     # Delete a demo
demofly demos open <name>       # Open demo in browser
```

### Voice Selection

```bash
demofly voices list             # List available TTS voices
demofly voices select           # Choose a default voice interactively
```

### Utilities

```bash
demofly version                 # Print CLI version
demofly update                  # Update to latest version
demofly update --check          # Check for updates without installing
```

## Voices

### Local (free, always available)

Powered by [Kokoro](https://github.com/thewh1teagle/kokoro-onnx) — runs entirely on your machine, no API key needed.

| Voice | Gender |
|-------|--------|
| heart | Female |
| bella | Female |
| nicole | Female |
| nova | Female |
| sarah | Female |
| adam | Male |
| michael | Male |

### Cloud (Pro)

With a Pro subscription, access premium voices from **ElevenLabs** and **OpenAI**. Run `demofly voices list` to see all available options.

## Project Structure

After running `demofly init`, a `demofly/` directory is created in your project root. Each demo gets its own subdirectory:

```
demofly/
└── my-demo/
    ├── demo.spec.ts          # Playwright test script
    ├── playwright.config.ts  # Playwright configuration
    ├── proposal.md           # Demo proposal and metadata
    ├── script.md             # Demo script outline
    ├── narration.md          # Scene-by-scene narration for TTS
    ├── demofly.json          # Demo config (cloud sync ID)
    ├── audio/                # Generated TTS audio per scene
    └── recordings/           # Recorded video, timing data, final output
        ├── video.webm
        ├── timing.json
        └── final.mp4
```

## Claude Code Integration

Demofly works with [Claude Code](https://docs.anthropic.com/en/docs/claude-code) to create demos conversationally. Running `demofly init` installs the Playwright MCP plugin so Claude Code can drive the browser and record demos for you.

## Configuration

### Default Voice

Set with `demofly voices select` or pass `--voice` and `--provider` flags per command. Stored in `~/.config/demofly/config.json`.

### Credentials

Authentication tokens are stored in `~/.demofly/credentials` with restricted file permissions.

### Environment Variables

| Variable | Description |
|----------|-------------|
| `DEMOFLY_URL` | Override the API base URL (default: `https://app.demofly.ai`) |

## Links

- **Website:** [demofly.ai](https://demofly.ai)
- **Issues:** [GitHub Issues](https://github.com/llama-farm/demofly/issues)

## License

MIT