demo-composer 0.1.1

package/README.md

@@ -0,0 +1,262 @@
+# demo-composer
+
+Generate narrated demo videos from Cucumber BDD tests using Playwright and Gemini AI.
+
+demo-composer records your Cucumber scenarios running against a live application, generates AI narration with text-to-speech, and composes polished demo videos — complete with title cards, subtitles, sidebar overlays, cursor effects, and optional background music.
+
+## Prerequisites
+
+- **Node.js** >= 18
+- **FFmpeg** with the `sidechaincompress` filter (required for background music ducking)
+  ```sh
+  brew install ffmpeg
+  ```
+- **Google Cloud credentials** configured for Vertex AI (Gemini)
+
+## Quick Start
+
+```sh
+npm install demo-composer
+npx demo-composer
+```
+
+## Project Conventions
+
+demo-composer follows **convention over configuration**. Place your files according to these conventions and everything works out of the box:
+
+```
+project-root/
+├── demo.json              # Optional: override convention defaults
+├── demo-music.mp3         # Optional: background music (auto-detected)
+├── features/
+│   ├── login/
+│   │   ├── login.feature       # Gherkin feature files
+│   │   └── login.steps.ts      # Step definitions
+│   └── checkout/
+│       ├── checkout.feature
+│       └── checkout.steps.ts
+├── support/
+│   └── world.ts           # Optional: extend DemoWorld for project-specific helpers
+└── demos/                 # Output directory (auto-created)
+    └── login/
+        └── login.mp4
+```
+
+### Feature Files
+
+Place Gherkin `.feature` files in `features/**/*.feature`. These are the same files you use for testing — no separate demo features needed.
+
+### Step Definitions
+
+Place step definition files as `features/**/*.steps.ts`. Use the `DemoWorld` API in your steps.
+
+### Support Files
+
+If you need to extend `DemoWorld` (e.g., to add project-specific helpers or override the World constructor), place a `support/world.ts` file. It will be auto-imported.
+
+## Writing Step Definitions
+
+Import `DemoWorld` and use its methods for visual demo actions:
+
+```typescript
+import { Given, When, Then } from '@cucumber/cucumber';
+import type { DemoWorld } from 'demo-composer';
+
+When('the user clicks the sign in button', async function (this: DemoWorld) {
+    const button = this.page.getByRole('button', { name: 'Sign In' });
+    await this.demoClick(button);
+});
+
+When('the user enters their email', async function (this: DemoWorld) {
+    const input = this.page.getByLabel('Email');
+    await this.demoType(input, 'user@example.com');
+});
+
+Then('the user should see their profile', async function (this: DemoWorld) {
+    const profile = this.page.getByTestId('profile');
+    await this.demoVisible(profile);
+});
+```
+
+### DemoWorld API
+
+| Method | Description |
+|--------|-------------|
+| `demoClick(locator, page?)` | Zoom to element, glide cursor, click, zoom back |
+| `demoType(locator, text, page?)` | Zoom to element, click, type with visible keystrokes, zoom back |
+| `demoVisible(locator)` | Highlight element with pulsing glow, zoom in, then reset |
+| `this.page` | The Playwright `Page` instance |
+| `this.context` | The Playwright `BrowserContext` (with video recording) |
+| `this.appBaseUrl` | The application URL (from `APP_BASE_URL` env var) |
+
+When recording is disabled (i.e., running as a normal test), `demoClick` performs a plain click, `demoType` clears and types, and `demoVisible` is a no-op. This lets you **reuse the same step definitions for both tests and demo videos** with no code changes.
+
+### Using DemoWorld for Tests
+
+`DemoWorld` works in lightweight mode by default — no video recording, no visual effects. Just re-export it as your test World:
+
+```typescript
+// support/world.ts
+export { DemoWorld } from 'demo-composer';
+```
+
+```typescript
+// support/hooks.ts
+import { Before, After, setWorldConstructor, AfterAll } from '@cucumber/cucumber';
+import { DemoWorld } from './world.ts';
+
+setWorldConstructor(DemoWorld);
+
+Before(async function (this: DemoWorld) {
+    await this.init();
+});
+
+After(async function (this: DemoWorld) {
+    await this.cleanup();
+});
+
+AfterAll(async function () {
+    await DemoWorld.closeBrowser();
+});
+```
+
+When you run `npx demo-composer`, the demo hooks automatically enable recording mode, and the same step definitions produce polished demo videos.
+
+### Extending DemoWorld
+
+For project-specific helpers, extend `DemoWorld` in `support/world.ts`:
+
+```typescript
+import { DemoWorld } from 'demo-composer';
+import { setWorldConstructor, type IWorldOptions } from '@cucumber/cucumber';
+
+class MyWorld extends DemoWorld {
+    constructor(options: IWorldOptions) {
+        super(options);
+    }
+
+    override async init() {
+        await super.init();
+        // Project-specific initialization
+    }
+}
+
+setWorldConstructor(MyWorld);
+```
+
+## Custom Templates
+
+Override the visual design of title cards, subtitles, and overlays by passing `TemplateOverrides` to the programmatic API. To reference the default implementations when writing overrides, import them from `demo-composer/templates`:
+
+```typescript
+import { titleCardHtml } from 'demo-composer/templates';
+```
+
+## Environment Variables
+
+### Required
+
+| Variable | Description |
+|----------|-------------|
+| `APP_BASE_URL` | URL of the running application to record |
+| `GEMINI_API_KEY` | Google Gemini API key (or use Application Default Credentials) |
+
+### Optional
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `GOOGLE_CLOUD_PROJECT` | Google Cloud project ID | — |
+| `GOOGLE_CLOUD_REGION` | Google Cloud region | `us-central1` |
+
+## Configuration: `demo.json`
+
+Place an optional `demo.json` at the project root to override convention defaults. All fields are optional:
+
+```json
+{
+    "width": 1920,
+    "height": 1080,
+    "outputDir": "demos",
+    "featuresGlob": "features/**/*.feature",
+    "musicFile": "demo-music.mp3",
+    "musicVolume": 0.15,
+    "musicFadeSeconds": 2,
+    "stepDelayMs": 500,
+    "stepSettleMs": 500,
+    "scenarioEndPauseMs": 2000,
+    "ttsModel": "gemini-2.5-pro-tts",
+    "ttsVoice": "Kore",
+    "ttsStylePreamble": "Read the following in a calm, steady, professional tone...",
+    "introLabel": "Demo"
+}
+```
+
+### Field Reference
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `width` | number | `1920` | Video width in pixels |
+| `height` | number | `1080` | Video height in pixels |
+| `outputDir` | string | `"demos"` | Output directory (relative to project root) |
+| `featuresGlob` | string | `"features/**/*.feature"` | Glob pattern for feature files |
+| `musicFile` | string | `"demo-music.mp3"` if present | Path to background music file |
+| `musicVolume` | number | `0.15` | Background music volume (0–1) |
+| `musicFadeSeconds` | number | `2` | Fade in/out duration for music |
+| `stepDelayMs` | number | `500` | Delay before each step (milliseconds) |
+| `stepSettleMs` | number | `500` | Settle time after each step |
+| `scenarioEndPauseMs` | number | `2000` | Pause at end of each scenario |
+| `ttsModel` | string | `"gemini-2.5-pro-tts"` | Gemini TTS model |
+| `ttsVoice` | string | `"Kore"` | TTS voice name |
+| `ttsStylePreamble` | string | *(calm professional tone)* | Preamble text prepended to every TTS request |
+| `introLabel` | string | `"Demo"` | Label shown on the intro title card |
+
+### Config Resolution Order
+
+```
+Built-in conventions → demo.json overrides → Environment variables (secrets/runtime only)
+```
+
+## Background Music
+
+If a file named `demo-music.mp3` exists at the project root, it is automatically used as background music. The music:
+
+- Loops for the full video duration
+- Fades in at the start and out at the end
+- Automatically ducks (reduces volume) when narration is playing
+
+To use a different file or disable music, set the `musicFile` field in `demo.json`.
+
+## CLI
+
+```sh
+npx demo-composer [options]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--config <path>` | Path to a custom Cucumber config file |
+| `--cwd <path>` | Working directory (default: current directory) |
+| `-h, --help` | Show help |
+
+### Custom Cucumber Config
+
+If you provide `--config`, you are responsible for importing demo-composer hooks:
+
+```typescript
+import type { IConfiguration } from '@cucumber/cucumber';
+
+export default {
+    failFast: true,
+    format: ['summary'],
+    paths: ['features/**/*.feature'],
+    import: ['demo-composer/hooks', 'support/**/*.ts', 'features/**/*.steps.ts'],
+} satisfies Partial<IConfiguration>;
+```
+
+## How It Works
+
+1. **Discover** feature files via glob pattern
+2. **Generate narration** text using Gemini AI from the Gherkin scenarios
+3. **Synthesize speech** for all narration clips using Gemini TTS
+4. **Record** scenarios running in Playwright with video recording, cursor effects, and dynamic step delays synchronized to narration audio durations
+5. **Compose** final videos with title cards, subtitle overlays, sidebar progress panels, picture-in-picture popups, and background music with sidechain ducking

package/dist/bin/demo-composer.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/demo-composer.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+import { run } from '../runner.js';
+const args = process.argv.slice(2);
+if (args.includes('--help') || args.includes('-h')) {
+    console.log(`
+demo-composer — Generate narrated demo videos from Cucumber BDD tests
+
+Usage: demo-composer [options]
+
+Options:
+  --config <path>   Path to a custom Cucumber config file
+  --cwd <path>      Working directory (default: current directory)
+  -h, --help        Show this help message
+
+Environment variables (required):
+  GEMINI_API_KEY       Google Gemini API key
+  APP_BASE_URL         URL of the running application
+
+Environment variables (optional):
+  GOOGLE_CLOUD_PROJECT  Google Cloud project ID
+  GOOGLE_CLOUD_REGION   Google Cloud region (default: us-central1)
+
+Configuration:
+  Place a demo.json file at the project root to override convention defaults.
+  See the README for the full schema.
+`);
+    process.exit(0);
+}
+let cwd;
+let cucumberConfig;
+for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--config' && args[i + 1]) {
+        cucumberConfig = args[++i];
+    }
+    else if (args[i] === '--cwd' && args[i + 1]) {
+        cwd = args[++i];
+    }
+}
+if (!process.env.APP_BASE_URL) {
+    console.error('Error: APP_BASE_URL environment variable is required.');
+    process.exit(1);
+}
+run({ cwd, cucumberConfig }).catch((err) => {
+    console.error('Demo generation failed:', err);
+    process.exit(1);
+});
+//# sourceMappingURL=demo-composer.js.map

package/dist/bin/demo-composer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"demo-composer.js","sourceRoot":"","sources":["../../src/bin/demo-composer.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAEnC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AAEnC,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;IACjD,OAAO,CAAC,GAAG,CAAC;;;;;;;;;;;;;;;;;;;;;CAqBf,CAAC,CAAC;IACC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AACpB,CAAC;AAED,IAAI,GAAuB,CAAC;AAC5B,IAAI,cAAkC,CAAC;AAEvC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;IACnC,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,UAAU,IAAI,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;QACxC,cAAc,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;IAC/B,CAAC;SAAM,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,OAAO,IAAI,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;QAC5C,GAAG,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;IACpB,CAAC;AACL,CAAC;AAED,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,YAAY,EAAE,CAAC;IAC5B,OAAO,CAAC,KAAK,CAAC,uDAAuD,CAAC,CAAC;IACvE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AACpB,CAAC;AAED,GAAG,CAAC,EAAE,GAAG,EAAE,cAAc,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACvC,OAAO,CAAC,KAAK,CAAC,yBAAyB,EAAE,GAAG,CAAC,CAAC;IAC9C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AACpB,CAAC,CAAC,CAAC"}

package/dist/composer.d.ts

@@ -0,0 +1,17 @@
+import type { ScenarioRecording } from './world.js';
+import type { AudioClip } from './tts.js';
+import type { ScenarioNarration } from './narration.js';
+import { type TemplateOverrides } from './templates.js';
+interface ScenarioCompositionInput {
+    recording: ScenarioRecording;
+    narration: ScenarioNarration;
+    titleAudio: AudioClip;
+    stepAudios: AudioClip[];
+}
+export interface MusicConfig {
+    filePath: string;
+    volume: number;
+    fadeSeconds: number;
+}
+export declare function composeFeatureVideo(inputs: ScenarioCompositionInput[], featureName: string, featureDescription: string, introAudio: AudioClip, conclusionAudio: AudioClip, outputDir: string, width: number, height: number, music?: MusicConfig, templates?: TemplateOverrides): Promise<string>;
+export {};