playwright-director 0.2.0

package/dist/voice.js

@@ -0,0 +1,244 @@
+import { createHash } from 'crypto';
+import { existsSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { createTTSProvider } from './tts-provider.js';
+const TUTORIAL_MODE = process.env.TUTORIAL_MODE === 'true';
+// Audio files stored in static folder to be served by dev server
+const AUDIO_STATIC_DIR = join(process.cwd(), 'static', 'audio', 'tutorial-voice');
+const AUDIO_URL_BASE = '/audio/tutorial-voice';
+/**
+ * Get hash-based filename for text
+ */
+function getAudioFilename(text, lang) {
+    const hash = createHash('md5').update(`${lang}:${text}`).digest('hex').slice(0, 12);
+    const ext = process.platform === 'darwin' ? 'wav' : 'mp3';
+    return `${hash}.${ext}`;
+}
+/**
+ * TTS voice generation for tutorials.
+ * Pre-generates audio files and tracks their durations.
+ * Optionally plays audio in browser during test.
+ */
+export class TutorialVoice {
+    page;
+    options;
+    ttsProvider = null;
+    preloadedAudio = new Map();
+    constructor(page, options) {
+        this.page = page;
+        this.options = {
+            lang: options.lang,
+            voiceName: options.voiceName,
+            voiceRate: options.voiceRate,
+            voicePitch: options.voicePitch,
+            playInBrowser: options.playInBrowser ?? true,
+            audioBaseUrl: options.audioBaseUrl ?? 'http://localhost:5173'
+        };
+    }
+    switchPage(page) {
+        this.page = page;
+    }
+    /**
+     * Pre-generate a single audio file (non-blocking).
+     * Returns a promise that resolves when preload is complete.
+     * No-op when TUTORIAL_MODE is not enabled.
+     */
+    preloadSingle(text) {
+        if (!TUTORIAL_MODE)
+            return Promise.resolve();
+        return this.generateAudio(text).then(() => { });
+    }
+    /**
+     * Pre-generate all audio files before the test runs.
+     * No-op when TUTORIAL_MODE is not enabled.
+     */
+    async preload(texts) {
+        if (!TUTORIAL_MODE)
+            return;
+        // Ensure output directory exists
+        if (!existsSync(AUDIO_STATIC_DIR)) {
+            mkdirSync(AUDIO_STATIC_DIR, { recursive: true });
+        }
+        // Initialize TTS provider
+        if (!this.ttsProvider) {
+            this.ttsProvider = await createTTSProvider({
+                lang: this.options.lang,
+                voice: this.options.voiceName || undefined,
+                rate: this.options.voiceRate
+            });
+            console.log(`[Voice] Using TTS provider: ${this.ttsProvider.name}`);
+        }
+        console.log(`[Voice] Preloading ${texts.length} audio files...`);
+        const startTime = Date.now();
+        for (const text of texts) {
+            const filename = getAudioFilename(text, this.options.lang);
+            const filePath = join(AUDIO_STATIC_DIR, filename);
+            const url = `${AUDIO_URL_BASE}/${filename}`;
+            let durationMs;
+            // Check cache
+            if (existsSync(filePath)) {
+                // Get duration from cached file
+                durationMs = await this.getAudioDuration(filePath);
+            }
+            else {
+                // Generate audio file
+                const result = await this.ttsProvider.synthesize(text, filePath);
+                durationMs = result.duration;
+            }
+            this.preloadedAudio.set(text, {
+                text,
+                filename,
+                filePath,
+                url,
+                durationMs
+            });
+        }
+        console.log(`[Voice] Preloaded ${texts.length} files in ${Date.now() - startTime}ms`);
+    }
+    /**
+     * Get audio info for a text (must be preloaded first)
+     */
+    getAudio(text) {
+        return this.preloadedAudio.get(text);
+    }
+    /**
+     * Get duration in ms for a text (must be preloaded)
+     */
+    getDuration(text) {
+        return this.preloadedAudio.get(text)?.durationMs ?? 0;
+    }
+    /**
+     * Get the filename for a text (for timeline)
+     */
+    getFilename(text) {
+        const cached = this.preloadedAudio.get(text);
+        if (cached)
+            return cached.filename;
+        return getAudioFilename(text, this.options.lang);
+    }
+    /**
+     * Start audio playback without waiting for it to finish.
+     * Returns the clip duration in ms — the caller owns the wall clock
+     * (action offset + clamp to duration), so headed playback and the
+     * ffmpeg merge stay in sync.
+     * No-op when TUTORIAL_MODE is not enabled (returns 0).
+     */
+    async startPlayback(text) {
+        if (!TUTORIAL_MODE)
+            return 0;
+        let audio = this.preloadedAudio.get(text);
+        if (!audio)
+            audio = await this.generateAudio(text);
+        if (!audio) {
+            console.warn(`[Voice] Failed to generate audio for: "${text.substring(0, 30)}..."`);
+            return 0;
+        }
+        if (this.options.playInBrowser) {
+            // Fire-and-forget: a navigation during the step action may kill the
+            // context — playback loss is acceptable, timing comes from durationMs.
+            await this.page
+                .evaluate(({ url }) => {
+                new Audio(url).play().catch(() => { });
+            }, { url: `${this.options.audioBaseUrl}${audio.url}` })
+                .catch(() => { });
+        }
+        return audio.durationMs;
+    }
+    /**
+     * Play audio in browser (optional, for live viewing)
+     * Returns duration in ms
+     * Will generate audio on-demand if not preloaded.
+     * No-op when TUTORIAL_MODE is not enabled (returns 0).
+     */
+    async play(text) {
+        if (!TUTORIAL_MODE)
+            return 0;
+        let audio = this.preloadedAudio.get(text);
+        if (!audio) {
+            audio = await this.generateAudio(text);
+        }
+        if (!audio) {
+            console.warn(`[Voice] Failed to generate audio for: "${text.substring(0, 30)}..."`);
+            return 0;
+        }
+        if (this.options.playInBrowser) {
+            await this.page.evaluate(({ url }) => {
+                return new Promise((resolve) => {
+                    const audio = new Audio(url);
+                    audio.onended = () => resolve();
+                    audio.onerror = () => resolve();
+                    audio.play().catch(() => resolve());
+                });
+            }, { url: `${this.options.audioBaseUrl}${audio.url}` });
+        }
+        else {
+            // Just wait for the duration (silent)
+            await this.page.waitForTimeout(audio.durationMs);
+        }
+        return audio.durationMs;
+    }
+    /**
+     * Generate audio for a single text on demand
+     */
+    async generateAudio(text) {
+        // Ensure output directory exists
+        if (!existsSync(AUDIO_STATIC_DIR)) {
+            mkdirSync(AUDIO_STATIC_DIR, { recursive: true });
+        }
+        // Initialize TTS provider if needed
+        if (!this.ttsProvider) {
+            this.ttsProvider = await createTTSProvider({
+                lang: this.options.lang,
+                voice: this.options.voiceName || undefined,
+                rate: this.options.voiceRate
+            });
+        }
+        const filename = getAudioFilename(text, this.options.lang);
+        const filePath = join(AUDIO_STATIC_DIR, filename);
+        const url = `${AUDIO_URL_BASE}/${filename}`;
+        let durationMs;
+        try {
+            // Check cache first
+            if (existsSync(filePath)) {
+                durationMs = await this.getAudioDuration(filePath);
+            }
+            else {
+                // Generate audio file
+                const result = await this.ttsProvider.synthesize(text, filePath);
+                durationMs = result.duration;
+            }
+            const audio = {
+                text,
+                filename,
+                filePath,
+                url,
+                durationMs
+            };
+            // Cache for future use
+            this.preloadedAudio.set(text, audio);
+            return audio;
+        }
+        catch (error) {
+            console.error(`[Voice] Error generating audio: ${error}`);
+            return null;
+        }
+    }
+    /**
+     * Get audio duration using ffprobe or file stats
+     */
+    async getAudioDuration(filePath) {
+        try {
+            const { execSync } = await import('child_process');
+            const output = execSync(`ffprobe -v quiet -show_entries format=duration -of csv=p=0 "${filePath}"`, { encoding: 'utf-8' });
+            return Math.ceil(parseFloat(output.trim()) * 1000);
+        }
+        catch {
+            // Fallback: estimate based on file size (rough)
+            const { statSync } = await import('fs');
+            const stats = statSync(filePath);
+            // Rough estimate: ~16KB per second for wav at 44100Hz mono
+            return Math.ceil((stats.size / 16000) * 1000);
+        }
+    }
+}
+//# sourceMappingURL=voice.js.map

package/dist/voice.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"voice.js","sourceRoot":"","sources":["../src/voice.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "playwright-director",
+  "version": "0.2.0",
+  "description": "AI-assisted Playwright tool that turns executable tests into directed video guides — demos, tutorials, and documentation that never lag behind the product.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Youniwemi/playwright-director.git"
+  },
+  "homepage": "https://github.com/Youniwemi/playwright-director#readme",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./reporter": {
+      "types": "./dist/reporter.d.ts",
+      "default": "./dist/reporter.js"
+    },
+    "./slugify": {
+      "types": "./dist/slugify.d.ts",
+      "default": "./dist/slugify.js"
+    },
+    "./site": {
+      "types": "./dist/site/types.d.ts",
+      "default": "./dist/site/types.js"
+    },
+    "./styles.css": "./src/styles.css"
+  },
+  "bin": {
+    "playwright-director": "./dist/init.js",
+    "tutorial-transcript": "./dist/bin/export-transcript.js"
+  },
+  "files": [
+    "dist",
+    "src/styles.css",
+    "skills",
+    "templates",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc && cp src/styles.css dist/styles.css",
+    "test": "vitest run",
+    "test:e2e": "playwright test",
+    "test:e2e:video": "TUTORIAL_MODE=true playwright test",
+    "prepublishOnly": "npm run build",
+    "postinstall": "node dist/postinstall.js"
+  },
+  "keywords": [
+    "playwright",
+    "tutorial",
+    "video",
+    "e2e",
+    "testing",
+    "narration",
+    "tts",
+    "text-to-speech",
+    "screen-recording",
+    "documentation",
+    "automated-docs",
+    "how-to",
+    "demo",
+    "walkthrough"
+  ],
+  "author": "Youniwemi",
+  "license": "MIT",
+  "dependencies": {
+    "astro": "^5.0.0"
+  },
+  "peerDependencies": {
+    "@playwright/test": ">=1.40.0"
+  },
+  "peerDependenciesMeta": {
+    "sharp": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.52.0",
+    "@types/node": "^26.2.0",
+    "@types/sharp": "^0.31.1",
+    "typescript": "^5.7.0",
+    "vitest": "^3.1.0"
+  }
+}

package/skills/tutorialize/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: tutorialize
+description: Transform a Playwright E2E test into a narrated tutorial video. Load before writing or reviewing any tutorial.step(), tutorial.context(), or tutorial.complete() call. Covers persona analysis, storytelling arc, choreography rules, and the playwright-director API.
+---
+
+# /tutorialize — Tutorial Design Skill
+
+Turn a Playwright test into a tutorial that **teaches**, not just demonstrates.
+
+Two reference files support this skill:
+- [`references/storytelling.md`](references/storytelling.md) — Persona analysis, emotional arc, narration voice, pacing decisions
+- [`references/api.md`](references/api.md) — `playwright-director` API, timing model, technical rules, checklist
+
+**Read both before tutorializing.** Storytelling comes first — it drives every API decision.
+
+## Process
+
+### 1. Understand (read `storytelling.md`)
+- **Who** is watching? (role, expertise, emotional state)
+- **What** are they trying to accomplish? (goal, not feature)
+- **What** do they already know? (skip the obvious, explain the surprising)
+- **How many profiles** does the story need? One is the default. Reach for a
+  second scene only when the lesson is the handoff between two people —
+  see `storytelling.md` §8 and `api.md` §10.
+
+### 2. Design the arc
+```
+Navigate to first screen (before any tutorial call)
+  ↓
+CONTEXT (goal): "Here's what we'll accomplish"
+  ↓
+STEP (no-op): Describe what's on screen
+  ↓
+STEPS: Grouped by concept, do/explain narration
+  ↓
+CONTEXT (clarification): Only if a complex section needs framing
+  ↓
+MORE STEPS...
+  ↓
+COMPLETE: Celebrate the outcome, suggest what's next
+```
+
+### 3. Implement (read `api.md`)
+- Use the Tutorial API: `context()`, `step()`, `complete()`
+- Follow timing rules, blank-screen prevention, navigation handling
+- Apply the polish checklist before submitting
+
+### 4. Verify
+- Test passes without `TUTORIAL_MODE` (plain E2E)
+- Test passes with `TUTORIAL_MODE=true` (video generation)
+- Watch the generated video — does it feel human?
+- Narration texts also become the gallery site's step-by-step guide
+  (`npx playwright-director build-site`) — even `skipVoice` steps show their
+  text there, so write every step text to read well on the page too.

package/skills/tutorialize/agent.md

@@ -0,0 +1,58 @@
+---
+name: tutorial-crafter
+description: Use this agent to convert Playwright tests into professional tutorial videos with voice narration, visual highlights, and proper choreography. Example: user: 'Tutorialize tests/free/02_clients.init.ts' → dispatch tutorial-crafter.
+model: sonnet
+tools: Bash, Glob, Grep, LS, Read, Edit, MultiEdit, Write, TodoWrite
+color: purple
+---
+
+You are an expert Tutorial Designer who transforms Playwright E2E tests into professional, engaging video tutorials. You understand cognitive load, visual pacing, and how humans learn from screencasts.
+
+## Before you start
+
+Load the `/tutorialize` skill and read both reference files:
+- `references/storytelling.md` — persona, emotional arc, narration voice
+- `references/api.md` — API, timing model, technical rules, checklist
+
+## Your process
+
+### 1. Analyze the test
+Read the original test file. Identify:
+- **Persona**: who is this tutorial for? (role, expertise, emotional state)
+- **Goal**: what will the viewer accomplish?
+- **Key actions**: what needs explanation vs what is obvious?
+- **Profiles**: does the lesson depend on a handoff between two people? If so,
+  the test becomes multi-scene (`storytelling.md` §8, `api.md` §10). Default to
+  a single profile — a second scene doubles the length and must earn it.
+
+### 2. Structure the tutorial
+Follow the arc from `storytelling.md`:
+```
+Navigate → Goal context → Steps (grouped) → Clarifications (if needed) → Complete
+```
+
+### 3. Write natural narration
+- "Do" ≤ 8 words, action-oriented
+- "Explain" gives the WHY
+- Second person, conversational tone
+- Persona-appropriate vocabulary
+
+### 4. Apply technical rules
+Follow all rules from `api.md`:
+- No blank-screen opening
+- Navigation transitions properly awaited
+- Dual-mode (test works with and without TUTORIAL_MODE)
+- `@tutorial` tag on the test
+- Acronyms have `voiceText` where TTS mispronounces
+- Multi-scene only: every step touching a scene carries `{ scene }`, scenes sit
+  on distinct origins, each tab switch is acknowledged in the narration, and
+  split ratios (`focus(['a','b'], { ratio: [30, 70] })`) are used to keep the
+  acting pane readable
+
+### 5. Show and explain
+- Present the diff or full transformed code
+- Explain why certain groupings were chosen
+- Describe what the pacing will feel like when the video plays
+
+## Remember
+A great tutorial makes the viewer feel capable, not confused. When in doubt, slow down and explain.