demofly 0.2.8 → 0.2.9

package/dist/commands/generate.js

@@ -1,5 +1,5 @@
 import { execSync } from "node:child_process";
-import { existsSync, mkdirSync, readdirSync, writeFileSync, readFileSync, copyFileSync, } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, writeFileSync, readFileSync, copyFileSync, renameSync, unlinkSync, } from "node:fs";
 import { resolve, basename, extname } from "node:path";
 import * as readline from "node:readline";
 import { parseTimingMarkers, normalizeTimingData } from "../lib/timing.js";
@@ -12,14 +12,18 @@ import { retimeAndAssemble } from "../lib/retiming.js";
 import { getToken } from "../lib/credentials.js";
 import { createApiClient, getAppUrl } from "../lib/api-client.js";
 import { getDefaultVoice } from "../lib/voice-config.js";
-import { isCloudVoice, KOKORO_VOICES, KOKORO_DEFAULT_VOICE, resolveVoiceFromFlags, } from "../lib/voice-resolver.js";
+import { getDemoVoicePreference, setDemoVoicePreference } from "../lib/demo-config.js";
+import { isCloudVoice, KOKORO_DEFAULT_VOICE, resolveVoiceFromFlags, } from "../lib/voice-resolver.js";
 import { generateCloudAudio, getSubscriptionStatus } from "../lib/cloud-tts.js";
 function validateDemoArtifacts(demoDir, demo) {
-    const specPath = resolve(demoDir, "demo.spec.ts");
     const configPath = resolve(demoDir, "playwright.config.ts");
+    const scenesDir = resolve(demoDir, "scenes");
+    const legacySpecPath = resolve(demoDir, "demo.spec.ts");
     let valid = true;
-    if (!existsSync(specPath)) {
-        console.error(`No demo.spec.ts found in demofly/${demo}/. Create one with /demofly:create ${demo} in Claude Code.`);
+    const hasScenes = existsSync(scenesDir) && readdirSync(scenesDir).some(f => f.endsWith(".spec.ts"));
+    const hasLegacySpec = existsSync(legacySpecPath);
+    if (!hasScenes && !hasLegacySpec) {
+        console.error(`No scene specs or demo.spec.ts found in demofly/${demo}/. Create one with /demofly:create ${demo} in Claude Code.`);
         valid = false;
     }
     if (!existsSync(configPath)) {
@@ -28,6 +32,382 @@ function validateDemoArtifacts(demoDir, demo) {
     }
     return valid;
 }
+function readSceneGroups(demoDir) {
+    const sharedPath = resolve(demoDir, "scenes", "shared.ts");
+    if (!existsSync(sharedPath))
+        return null;
+    const content = readFileSync(sharedPath, "utf-8");
+    const match = content.match(/export\s+const\s+SCENE_GROUPS\s*=\s*(\[[\s\S]*?\n\];)/);
+    if (!match)
+        return null;
+    try {
+        // Parse the TypeScript array literal as JSON (strip trailing commas, convert single quotes)
+        const jsonStr = match[1]
+            .replace(/'/g, '"')
+            .replace(/,\s*]/g, "]")
+            .replace(/,\s*}/g, "}")
+            .replace(/(\w+)\s*:/g, '"$1":');
+        return JSON.parse(jsonStr);
+    }
+    catch {
+        debug("Could not parse SCENE_GROUPS from shared.ts, falling back to file scan");
+        return null;
+    }
+}
+function discoverSceneGroups(demoDir) {
+    // Try reading from shared.ts first
+    const fromShared = readSceneGroups(demoDir);
+    if (fromShared)
+        return fromShared;
+    // Fall back to scanning scene spec files
+    const scenesDir = resolve(demoDir, "scenes");
+    if (!existsSync(scenesDir))
+        return [];
+    const specFiles = readdirSync(scenesDir)
+        .filter(f => f.endsWith(".spec.ts") && f.startsWith("scene-"))
+        .sort();
+    return specFiles.map(f => {
+        const id = f.replace(".spec.ts", "");
+        const scenes = id.split("-").filter(p => /^\d+$/.test(p)).map(n => `scene-${n}`);
+        if (scenes.length === 0)
+            scenes.push(id);
+        return { id, scenes, startUrl: "/", independent: scenes.length === 1 };
+    });
+}
+function findGroupForScene(groups, sceneId) {
+    return groups.find(g => g.scenes.includes(sceneId)) ?? null;
+}
+function runSceneGroupRecording(demoDir, demo, group, force) {
+    const scenesRecordingsDir = resolve(demoDir, "recordings", "scenes");
+    const groupVideoDir = resolve(scenesRecordingsDir, group.id);
+    const groupVideoPath = resolve(groupVideoDir, "video.webm");
+    // Skip if already recorded (unless --force)
+    if (!force && existsSync(groupVideoPath)) {
+        debug(`Skipping ${group.id}: recording exists at ${groupVideoPath}`);
+        return { groupId: group.id, scenes: group.scenes, status: "skipped" };
+    }
+    const specPath = `demofly/${demo}/scenes/${group.id}.spec.ts`;
+    const configPath = `demofly/${demo}/playwright.config.ts`;
+    const cmd = `npx playwright test ${specPath} --config ${configPath}`;
+    debug(`Recording scene group: ${cmd}`);
+    console.log(`\nRecording ${group.id}...`);
+    try {
+        const output = execSync(cmd, {
+            encoding: "utf-8",
+            timeout: 600_000,
+            stdio: ["pipe", "pipe", "pipe"],
+            cwd: resolve(demoDir, "..", ".."),
+        });
+        // Extract timing and save
+        const timingData = parseTimingMarkers(output);
+        mkdirSync(groupVideoDir, { recursive: true });
+        // Find and move video
+        const videoPath = findRecordedVideo(demoDir);
+        if (videoPath) {
+            execSync(`cp "${videoPath}" "${groupVideoPath}"`);
+        }
+        // Write timing data for the group
+        writeFileSync(resolve(groupVideoDir, "timing.json"), JSON.stringify(timingData, null, 2), "utf-8");
+        // If this is a multi-scene group, split into per-scene clips and timing
+        if (group.scenes.length > 1 && videoPath) {
+            splitGroupIntoScenes(groupVideoPath, timingData, scenesRecordingsDir, group);
+        }
+        else if (group.scenes.length === 1 && group.scenes[0] !== group.id) {
+            // Single scene with different scene name — symlink/copy
+            const sceneDir = resolve(scenesRecordingsDir, group.scenes[0]);
+            mkdirSync(sceneDir, { recursive: true });
+            execSync(`cp "${groupVideoPath}" "${resolve(sceneDir, "video.webm")}"`);
+            writeFileSync(resolve(sceneDir, "timing.json"), JSON.stringify(timingData, null, 2), "utf-8");
+        }
+        const durationMs = timingData.totalDuration;
+        console.log(`  ${group.id}: recorded (${formatDuration(durationMs)})`);
+        return {
+            groupId: group.id,
+            scenes: group.scenes,
+            status: "success",
+            videoPath: groupVideoPath,
+            durationMs,
+        };
+    }
+    catch (error) {
+        const execError = error;
+        const errMsg = execError.stderr ?? execError.stdout ?? "Unknown error";
+        console.error(`  ${group.id}: FAILED`);
+        debug(`Recording failed for ${group.id}: ${errMsg}`);
+        return {
+            groupId: group.id,
+            scenes: group.scenes,
+            status: "failed",
+            error: errMsg.slice(0, 500),
+        };
+    }
+}
+function splitGroupIntoScenes(groupVideoPath, timingData, scenesRecordingsDir, group) {
+    for (const sceneId of group.scenes) {
+        const sceneTimingData = extractSceneTiming(timingData, sceneId);
+        if (!sceneTimingData)
+            continue;
+        const sceneDir = resolve(scenesRecordingsDir, sceneId);
+        mkdirSync(sceneDir, { recursive: true });
+        // Split video for this scene
+        const startSec = sceneTimingData.scenes[0].startMs / 1000;
+        const durationSec = (sceneTimingData.scenes[0].endMs - sceneTimingData.scenes[0].startMs) / 1000;
+        const outputPath = resolve(sceneDir, "video.webm");
+        // Use a temp file when input and output are the same (single-scene groups)
+        const sameFile = resolve(groupVideoPath) === resolve(outputPath);
+        const writePath = sameFile ? resolve(sceneDir, "video.trimmed.webm") : outputPath;
+        try {
+            execSync(`ffmpeg -y -i "${groupVideoPath}" -ss ${startSec} -t ${durationSec} -c copy "${writePath}"`, { encoding: "utf-8", timeout: 300_000, stdio: ["pipe", "pipe", "pipe"] });
+            if (sameFile) {
+                renameSync(writePath, outputPath);
+            }
+        }
+        catch (err) {
+            const execError = err;
+            console.warn(`  Warning: Failed to split ${sceneId} from group ${group.id}`);
+            if (execError.stderr)
+                debug(execError.stderr);
+        }
+        // Write scene-relative timing
+        writeFileSync(resolve(sceneDir, "timing.json"), JSON.stringify(sceneTimingData, null, 2), "utf-8");
+    }
+}
+function extractSceneTiming(timingData, sceneId) {
+    const scene = timingData.scenes.find(s => s.sceneId === sceneId);
+    if (!scene)
+        return null;
+    const sceneStartMs = scene.startMs;
+    return {
+        totalDuration: scene.endMs - scene.startMs,
+        scenes: [{
+                sceneId: scene.sceneId,
+                startMs: 0,
+                endMs: scene.endMs - sceneStartMs,
+                markers: scene.markers.map(m => ({
+                    ...m,
+                    ms: m.ms - sceneStartMs,
+                })),
+            }],
+    };
+}
+function buildCombinedTimingData(demoDir, groups) {
+    const allScenes = [];
+    let cumulativeMs = 0;
+    for (const group of groups) {
+        for (const sceneId of group.scenes) {
+            const sceneTimingPath = resolve(demoDir, "recordings", "scenes", sceneId, "timing.json");
+            if (!existsSync(sceneTimingPath)) {
+                // Also check group-level timing
+                const groupTimingPath = resolve(demoDir, "recordings", "scenes", group.id, "timing.json");
+                if (existsSync(groupTimingPath)) {
+                    try {
+                        const groupTiming = normalizeTimingData(JSON.parse(readFileSync(groupTimingPath, "utf-8")));
+                        const sceneData = groupTiming.scenes.find(s => s.sceneId === sceneId);
+                        if (sceneData) {
+                            allScenes.push({
+                                ...sceneData,
+                                startMs: cumulativeMs,
+                                endMs: cumulativeMs + (sceneData.endMs - sceneData.startMs),
+                                markers: sceneData.markers.map(m => ({
+                                    ...m,
+                                    ms: cumulativeMs + m.ms - sceneData.startMs,
+                                })),
+                            });
+                            cumulativeMs += sceneData.endMs - sceneData.startMs;
+                        }
+                    }
+                    catch { /* skip */ }
+                }
+                continue;
+            }
+            try {
+                const sceneTiming = normalizeTimingData(JSON.parse(readFileSync(sceneTimingPath, "utf-8")));
+                for (const scene of sceneTiming.scenes) {
+                    allScenes.push({
+                        ...scene,
+                        startMs: cumulativeMs + scene.startMs,
+                        endMs: cumulativeMs + scene.endMs,
+                        markers: scene.markers.map(m => ({
+                            ...m,
+                            ms: cumulativeMs + m.ms,
+                        })),
+                    });
+                }
+                cumulativeMs += sceneTiming.totalDuration;
+            }
+            catch { /* skip */ }
+        }
+    }
+    return { totalDuration: cumulativeMs, scenes: allScenes };
+}
+function collectSceneClips(demoDir, groups) {
+    const clips = [];
+    for (const group of groups) {
+        for (const sceneId of group.scenes) {
+            const sceneDir = resolve(demoDir, "recordings", "scenes", sceneId);
+            const videoPath = resolve(sceneDir, "video.webm");
+            const timingPath = resolve(sceneDir, "timing.json");
+            if (!existsSync(videoPath))
+                continue;
+            let durationMs = 0;
+            let trimStartMs = 0;
+            if (existsSync(timingPath)) {
+                try {
+                    const timing = normalizeTimingData(JSON.parse(readFileSync(timingPath, "utf-8")));
+                    const firstScene = timing.scenes[0];
+                    if (firstScene) {
+                        trimStartMs = firstScene.startMs;
+                        durationMs = firstScene.endMs - firstScene.startMs;
+                    }
+                    else {
+                        durationMs = timing.totalDuration;
+                    }
+                }
+                catch { /* use 0 */ }
+            }
+            clips.push({
+                sceneId,
+                videoPath,
+                durationMs,
+                trimStartMs,
+                transition: "hard_cut", // default; could be overridden from narration metadata
+            });
+        }
+    }
+    return clips;
+}
+function assembleFromSceneClips(clips, audioMatches, recordingsDir, applyWatermark = false) {
+    if (clips.length === 0)
+        return null;
+    const outputPath = resolve(recordingsDir, "final.mp4");
+    const inputArgs = [];
+    const filterParts = [];
+    // Add all video inputs
+    for (const clip of clips) {
+        inputArgs.push("-i", clip.videoPath);
+    }
+    // Add audio inputs
+    let cumulativeMs = 0;
+    for (let i = 0; i < clips.length; i++) {
+        const clip = clips[i];
+        const audioMatch = audioMatches.find(a => a.sceneId === clip.sceneId);
+        if (audioMatch) {
+            inputArgs.push("-i", audioMatch.filePath);
+            const audioIdx = inputArgs.filter(a => a === "-i").length - 1;
+            filterParts.push(`[${audioIdx}:a]adelay=${cumulativeMs}|${cumulativeMs}[a${audioIdx}]`);
+        }
+        cumulativeMs += clip.durationMs;
+    }
+    // Build video concatenation filter
+    // Trim white screen from start of each clip using timing data
+    if (clips.length === 1) {
+        const clip = clips[0];
+        if (clip.trimStartMs > 0) {
+            const trimSec = clip.trimStartMs / 1000;
+            const durSec = clip.durationMs / 1000;
+            filterParts.push(`[0:v]trim=start=${trimSec}:duration=${durSec},setpts=PTS-STARTPTS[vconcat]`);
+        }
+    }
+    else {
+        // Scale and trim all inputs to consistent format for concat
+        const scaledParts = [];
+        for (let i = 0; i < clips.length; i++) {
+            const clip = clips[i];
+            if (clip.trimStartMs > 0) {
+                const trimSec = clip.trimStartMs / 1000;
+                const durSec = clip.durationMs / 1000;
+                scaledParts.push(`[${i}:v]trim=start=${trimSec}:duration=${durSec},setpts=PTS-STARTPTS[v${i}]`);
+            }
+            else {
+                scaledParts.push(`[${i}:v]setpts=PTS-STARTPTS[v${i}]`);
+            }
+        }
+        filterParts.push(...scaledParts);
+        // Apply transitions between clips
+        let currentLabel = "v0";
+        for (let i = 1; i < clips.length; i++) {
+            const transition = clips[i].transition;
+            const nextLabel = i === clips.length - 1 ? "vconcat" : `vt${i}`;
+            if (transition === "crossfade") {
+                filterParts.push(`[${currentLabel}][v${i}]xfade=transition=fade:duration=0.3:offset=${(clips[i - 1].durationMs - 300) / 1000}[${nextLabel}]`);
+            }
+            else if (transition === "black_gap") {
+                // Insert a 0.2s black frame between clips
+                filterParts.push(`color=c=black:s=1280x800:d=0.2[black${i}]`);
+                filterParts.push(`[${currentLabel}][black${i}][v${i}]concat=n=3:v=1:a=0[${nextLabel}]`);
+            }
+            else {
+                // hard_cut — simple concat
+                filterParts.push(`[${currentLabel}][v${i}]concat=n=2:v=1:a=0[${nextLabel}]`);
+            }
+            currentLabel = nextLabel;
+        }
+    }
+    // Build audio mix
+    const audioFilterParts = filterParts.filter(p => p.includes("adelay"));
+    const audioLabels = audioFilterParts.map(p => {
+        const match = p.match(/\[a(\d+)\]$/);
+        return match ? `[a${match[1]}]` : "";
+    }).filter(Boolean);
+    let audioMap = "";
+    if (audioLabels.length > 0) {
+        filterParts.push(`${audioLabels.join("")}amix=inputs=${audioLabels.length}:normalize=0[aout]`);
+        audioMap = "[aout]";
+    }
+    // Add watermark if needed
+    let videoMap = "[vconcat]";
+    const watermarkPath = applyWatermark ? getWatermarkPath() : null;
+    if (watermarkPath && existsSync(watermarkPath)) {
+        inputArgs.push("-i", watermarkPath);
+        const wmIdx = inputArgs.filter(a => a === "-i").length - 1;
+        filterParts.push(`[${wmIdx}:v]scale=120:-1,format=rgba,colorchannelmixer=aa=0.6[wm]`, `[vconcat][wm]overlay=W-w-24:H-h-16[vout]`);
+        videoMap = "[vout]";
+    }
+    const mapArgs = ["-map", videoMap];
+    if (audioMap) {
+        mapArgs.push("-map", audioMap);
+    }
+    const args = [
+        "ffmpeg", "-y",
+        ...inputArgs,
+        "-filter_complex", `"${filterParts.join("; ")}"`,
+        ...mapArgs,
+        "-c:v", "libx264", "-preset", "fast", "-crf", "23", "-pix_fmt", "yuv420p",
+        "-shortest",
+        outputPath,
+    ];
+    console.log("Assembling from per-scene clips...\n");
+    try {
+        execSync(args.join(" "), {
+            encoding: "utf-8",
+            timeout: 600_000,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        return outputPath;
+    }
+    catch (error) {
+        const execError = error;
+        console.error("ffmpeg assembly from per-scene clips failed:");
+        if (execError.stderr) {
+            debug(execError.stderr);
+        }
+        return null;
+    }
+}
+function printSceneResults(results) {
+    console.log("\n--- Per-Scene Recording Results ---\n");
+    console.log("  Scene Group     Status     Duration");
+    console.log("  ─────────────   ────────   ────────");
+    for (const r of results) {
+        const status = r.status === "success" ? "OK" : r.status === "skipped" ? "skipped" : "FAILED";
+        const duration = r.durationMs ? formatDuration(r.durationMs) : "-";
+        console.log(`  ${r.groupId.padEnd(16)}${status.padEnd(11)}${duration}`);
+    }
+    const succeeded = results.filter(r => r.status === "success").length;
+    const skipped = results.filter(r => r.status === "skipped").length;
+    const failed = results.filter(r => r.status === "failed").length;
+    console.log(`\n  Total: ${succeeded} recorded, ${skipped} skipped, ${failed} failed\n`);
+}
 function runPlaywrightTest(demoDir, demo) {
     const specPath = `demofly/${demo}/demo.spec.ts`;
     const configPath = `demofly/${demo}/playwright.config.ts`;
@@ -155,12 +535,10 @@ function buildFfmpegCommand(videoPath, audioMatches, timingData, outputPath, app
     // Build video filter chain with optional watermark overlay
     let videoMap = "0:v";
     if (applyWatermark && watermarkInputIndex >= 0) {
-        // Scale watermark to ~8% of video width, position bottom-right with padding
-        // Use scale2ref so dimensions reference the main video, not the watermark PNG
+        // Scale watermark to fixed 120px wide, position bottom-right with padding
         filterComplex +=
-            `; [${watermarkInputIndex}:v][0:v]scale2ref=w=main_w*0.08:h=-1[wm_scaled][vmain]` +
-                `; [wm_scaled]format=rgba,colorchannelmixer=aa=0.6[wm]` +
-                `; [vmain][wm]overlay=W-w-24:H-h-16[vout]`;
+            `; [${watermarkInputIndex}:v]scale=120:-1,format=rgba,colorchannelmixer=aa=0.6[wm]` +
+                `; [0:v][wm]overlay=W-w-24:H-h-16[vout]`;
         videoMap = "[vout]";
     }
     const args = [
@@ -216,8 +594,14 @@ export function splitScenes(videoPath, timingData, recordingsDir) {
         const startSec = scene.startMs / 1000;
         const durationSec = (scene.endMs - scene.startMs) / 1000;
         const outputPath = resolve(sceneDir, "video.webm");
+        // Use a temp file when input and output are the same path
+        const sameFile = resolve(videoPath) === resolve(outputPath);
+        const writePath = sameFile ? resolve(sceneDir, "video.trimmed.webm") : outputPath;
         try {
-            execSync(`ffmpeg -y -i "${videoPath}" -ss ${startSec} -t ${durationSec} -c copy "${outputPath}"`, { encoding: "utf-8", timeout: 300_000, stdio: ["pipe", "pipe", "pipe"] });
+            execSync(`ffmpeg -y -i "${videoPath}" -ss ${startSec} -t ${durationSec} -c copy "${writePath}"`, { encoding: "utf-8", timeout: 300_000, stdio: ["pipe", "pipe", "pipe"] });
+            if (sameFile) {
+                renameSync(writePath, outputPath);
+            }
             outputs.push(outputPath);
         }
         catch (error) {
@@ -396,11 +780,13 @@ function shouldRegenerateAudio(projectDir, resolvedVoice, explicitVoiceFlag, tim
         return true;
     return meta.name !== resolvedVoice.name || meta.provider !== resolvedVoice.provider;
 }
-function resolveVoiceForGenerate(voiceName, providerName) {
+function resolveVoiceForGenerate(voiceName, providerName, projectDir) {
+    const demoVoicePreference = projectDir ? getDemoVoicePreference(projectDir) : null;
     return resolveVoiceFromFlags(voiceName, providerName, {
         getDefaultVoice,
         getToken,
         createApiClient,
+        demoVoicePreference,
     });
 }
 async function generateAudioForProject(narrationPath, projectDir, voice, speed, sceneFilter) {
@@ -419,23 +805,31 @@ async function generateAudioForProject(narrationPath, projectDir, voice, speed,
     }
     if (results.length > 0) {
         writeVoiceMetadata(projectDir, actualVoice);
+        // Auto-set demo voice preference on first generation
+        if (!getDemoVoicePreference(projectDir)) {
+            setDemoVoicePreference(projectDir, { name: actualVoice.name, provider: actualVoice.provider });
+        }
     }
     return { ttsResults: results, actualVoice };
 }
 async function generateCloudTtsInline(narrationPath, projectDir, voice, speed, sceneFilter) {
     const token = await getToken();
     if (!token) {
-        return fallbackToKokoro(narrationPath, projectDir, speed, "Not authenticated.", sceneFilter);
+        console.error("Not authenticated. Premium voices require authentication.");
+        console.error("Run `demofly auth login` to authenticate, or use a free voice.\n");
+        process.exit(1);
     }
     const api = createApiClient(token);
     try {
         const sub = await getSubscriptionStatus(api);
         if (sub.plan !== "pro") {
-            return fallbackToKokoro(narrationPath, projectDir, speed, `Premium voices require a Pro subscription. Upgrade at ${getAppUrl()}/upgrade`, sceneFilter);
+            console.error(`Premium voices require a Pro subscription. Upgrade at ${getAppUrl()}/upgrade`);
+            process.exit(1);
         }
     }
     catch {
-        return fallbackToKokoro(narrationPath, projectDir, speed, "Cloud TTS unavailable.", sceneFilter);
+        console.error("Could not verify subscription status. Cloud TTS unavailable.");
+        process.exit(1);
     }
     const content = readFileSync(narrationPath, "utf-8");
     let scenes = parseTranscript(content);
@@ -444,10 +838,42 @@ async function generateCloudTtsInline(narrationPath, projectDir, voice, speed, s
     }
     if (scenes.length === 0)
         return { ttsResults: [], actualVoice: voice };
+    // Credit pre-check: estimate total cost before starting
+    const allText = scenes.map(s => s.text).join(" ");
+    const operationType = `${voice.provider}-tts`;
+    try {
+        const estimate = await api.post("/credits/estimate", { operation: operationType, input: { text: allText } });
+        if (!estimate.sufficient) {
+            console.log(`\nThis demo needs ~${estimate.estimatedCredits} credits but you have ${estimate.available}.`);
+            if (process.stdin.isTTY) {
+                const useFree = await promptYesNo(`Generate with free voice (${getDefaultFreeVoice().name}) instead?`);
+                if (useFree) {
+                    console.log();
+                    const freeVoice = getDefaultFreeVoice();
+                    const ttsResults = generateAllAudio(narrationPath, projectDir, {
+                        voice: freeVoice.providerId,
+                        speed,
+                        sceneFilter,
+                    });
+                    return { ttsResults, actualVoice: freeVoice };
+                }
+            }
+            else {
+                console.log(`Run interactively to switch to a free voice, or use --voice heart.`);
+            }
+            console.log(`\nUse \`demofly voices select ${basename(projectDir)}\` to choose a different voice, or add credits at ${getAppUrl()}`);
+            process.exit(1);
+        }
+    }
+    catch {
+        // Credit API unreachable — warn and proceed optimistically
+        console.warn("Warning: Could not verify credit balance. Proceeding with generation.\n");
+    }
     const audioDir = resolve(projectDir, "audio");
     if (!existsSync(audioDir))
         mkdirSync(audioDir, { recursive: true });
     const results = [];
+    const generatedFiles = [];
     for (const scene of scenes) {
         console.log(`  TTS: ${scene.sceneId} (${scene.text.length} chars)`);
         try {
@@ -456,27 +882,35 @@ async function generateCloudTtsInline(narrationPath, projectDir, voice, speed, s
             const elapsedS = (performance.now() - start) / 1000;
             const outputPath = resolve(audioDir, `${scene.sceneId}.mp3`);
             writeFileSync(outputPath, Buffer.from(audio));
+            generatedFiles.push(outputPath);
             results.push({ sceneId: scene.sceneId, filePath: outputPath, durationS, peakMemoryMb: 0, elapsedS });
             console.log(`    -> ${durationS.toFixed(1)}s audio, ${elapsedS.toFixed(1)}s elapsed`);
         }
         catch (err) {
-            if (err.status === 403) {
-                return fallbackToKokoro(narrationPath, projectDir, speed, `Premium voices require a Pro subscription. Upgrade at ${getAppUrl()}/upgrade`, sceneFilter);
+            // Clean up audio files generated during this failed run
+            for (const file of generatedFiles) {
+                try {
+                    unlinkSync(file);
+                }
+                catch { }
             }
-            console.warn(`    Cloud TTS failed for ${scene.sceneId}: ${err.message}`);
-            return fallbackToKokoro(narrationPath, projectDir, speed, "Cloud TTS unavailable, falling back to local voice.", sceneFilter);
+            if (err.status === 402) {
+                console.error(`\nRan out of credits during generation at ${scene.sceneId}. No audio was produced.`);
+            }
+            else if (err.status === 403) {
+                console.error(`\nPremium voices require a Pro subscription. Upgrade at ${getAppUrl()}/upgrade`);
+            }
+            else {
+                console.error(`\nPremium voice generation failed for ${scene.sceneId}: ${err.message}`);
+            }
+            console.error(`Re-run with a free voice (--voice heart) or use \`demofly voices select ${basename(projectDir)}\` to change voice.\n`);
+            process.exit(1);
         }
     }
     return { ttsResults: results, actualVoice: voice };
 }
-function fallbackToKokoro(narrationPath, projectDir, speed, reason, sceneFilter) {
-    console.warn(`${reason} Falling back to Kokoro.\n`);
-    const ttsResults = generateAllAudio(narrationPath, projectDir, {
-        voice: KOKORO_VOICES[0].kokoroId,
-        speed,
-        sceneFilter,
-    });
-    return { ttsResults, actualVoice: KOKORO_DEFAULT_VOICE };
+function getDefaultFreeVoice() {
+    return KOKORO_DEFAULT_VOICE;
 }
 export function registerGenerateCommand(program) {
     program
@@ -488,7 +922,8 @@ export function registerGenerateCommand(program) {
         .option("--align", "Produce alignment.json from timestamps + timing data")
         .option("--assemble", "Full intelligent assembly (align + edit proposals + retiming)")
         .option("--video", "Record video only (skip audio generation)")
-        .option("--scene <id>", "Generate audio for a specific scene only")
+        .option("--scene <id>", "Record or generate audio for a specific scene only")
+        .option("--force", "Re-record scenes even if recordings exist")
         .option("--voice <name>", "TTS voice name")
         .option("--provider <provider>", "TTS provider (e.g., elevenlabs, openai, kokoro)")
         .option("--speed <multiplier>", "TTS speed multiplier", "1.0")
@@ -517,7 +952,7 @@ export function registerGenerateCommand(program) {
                 process.exit(1);
             }
             const speed = parseFloat(opts.speed);
-            const voice = await resolveVoiceForGenerate(opts.voice, opts.provider);
+            const voice = await resolveVoiceForGenerate(opts.voice, opts.provider, projectDir);
             const { ttsResults, actualVoice } = await generateAudioForProject(sourcePath, projectDir, voice, speed, opts.scene);
             console.log("\n--- demofly generate --audio summary ---\n");
             console.log(`  Voice:       ${actualVoice.name} (${actualVoice.provider})`);
@@ -563,7 +998,31 @@ export function registerGenerateCommand(program) {
         }
         // Video-only mode: record and exit
         if (opts.video) {
-            debug("Video-only mode: running Playwright test");
+            const sceneGroups = discoverSceneGroups(projectDir);
+            if (sceneGroups.length > 0) {
+                // Per-scene recording
+                debug("Video-only mode: per-scene recording");
+                let groupsToRecord = sceneGroups;
+                if (opts.scene) {
+                    const group = findGroupForScene(sceneGroups, opts.scene);
+                    if (!group) {
+                        console.error(`Scene "${opts.scene}" not found in any scene group.`);
+                        process.exit(1);
+                    }
+                    groupsToRecord = [group];
+                }
+                const results = [];
+                for (const group of groupsToRecord) {
+                    results.push(runSceneGroupRecording(projectDir, demo, group, opts.force ?? false));
+                }
+                printSceneResults(results);
+                const anyFailed = results.some(r => r.status === "failed");
+                if (anyFailed)
+                    process.exit(2);
+                return;
+            }
+            // Legacy monolithic recording
+            debug("Video-only mode: running Playwright test (legacy)");
             const result = recordDemo(projectDir, demo);
             const videoPath = result.videoPath
                 ? resolve(recordingsDir, "video.webm")
@@ -582,27 +1041,64 @@ export function registerGenerateCommand(program) {
         let timingPath;
         // Step 2: Record or use existing artifacts
         if (opts.record) {
-            debug("Recording mode: running Playwright test");
-            const result = recordDemo(projectDir, demo);
-            videoPath = result.videoPath
-                ? resolve(recordingsDir, "video.webm")
-                : null;
-            const stdout = result.stdout;
-            timingData = parseTimingMarkers(stdout);
-            timingPath = resolve(recordingsDir, "timing.json");
-            if (timingData.scenes.length === 0) {
-                console.warn("Warning: No DEMOFLY timing markers found in test output. Video was still recorded.");
+            const sceneGroups = discoverSceneGroups(projectDir);
+            if (sceneGroups.length > 0) {
+                // Per-scene recording mode
+                debug("Recording mode: per-scene recording");
+                let groupsToRecord = sceneGroups;
+                if (opts.scene) {
+                    const group = findGroupForScene(sceneGroups, opts.scene);
+                    if (!group) {
+                        console.error(`Scene "${opts.scene}" not found in any scene group.`);
+                        process.exit(1);
+                    }
+                    groupsToRecord = [group];
+                }
+                const results = [];
+                for (const group of groupsToRecord) {
+                    results.push(runSceneGroupRecording(projectDir, demo, group, opts.force ?? false));
+                }
+                printSceneResults(results);
+                const anyFailed = results.some(r => r.status === "failed");
+                // Build combined timing data from per-scene recordings
+                timingData = buildCombinedTimingData(projectDir, sceneGroups);
+                timingPath = resolve(recordingsDir, "timing.json");
+                writeTimingJson(recordingsDir, timingData);
+                // Use the first successful scene's parent video or look for combined
+                const firstSuccess = results.find(r => r.status === "success");
+                videoPath = firstSuccess?.videoPath ?? null;
+                if (anyFailed) {
+                    console.warn("Some scenes failed to record. Assembly will use available clips.\n");
+                }
+            }
+            else {
+                // Legacy monolithic recording
+                debug("Recording mode: running Playwright test (legacy)");
+                const result = recordDemo(projectDir, demo);
+                videoPath = result.videoPath
+                    ? resolve(recordingsDir, "video.webm")
+                    : null;
+                const stdout = result.stdout;
+                timingData = parseTimingMarkers(stdout);
+                timingPath = resolve(recordingsDir, "timing.json");
+                if (timingData.scenes.length === 0) {
+                    console.warn("Warning: No DEMOFLY timing markers found in test output. Video was still recorded.");
+                }
             }
         }
         else {
             // Assembler-first: look for existing artifacts
             const existingVideo = resolve(recordingsDir, "video.webm");
             const existingTiming = resolve(recordingsDir, "timing.json");
+            // Check for video: either legacy combined video or per-scene clips
             const hasVideo = existsSync(existingVideo);
+            const scenesDir = resolve(recordingsDir, "scenes");
+            const hasSceneClips = existsSync(scenesDir) && readdirSync(scenesDir, { withFileTypes: true })
+                .some(d => d.isDirectory() && existsSync(resolve(scenesDir, d.name, "video.webm")));
             const hasTiming = existsSync(existingTiming);
-            if (!hasVideo || !hasTiming) {
+            if ((!hasVideo && !hasSceneClips) || !hasTiming) {
                 const missingParts = [];
-                if (!hasVideo)
+                if (!hasVideo && !hasSceneClips)
                     missingParts.push("recordings/video.webm");
                 if (!hasTiming)
                     missingParts.push("recordings/timing.json");
@@ -637,7 +1133,7 @@ export function registerGenerateCommand(program) {
             }
             // If we didn't record (existing artifacts found), load from disk
             if (!videoPath) {
-                videoPath = existingVideo;
+                videoPath = hasVideo ? existingVideo : null; // null when only scene clips exist
                 timingData = normalizeTimingData(JSON.parse(readFileSync(existingTiming, "utf-8")));
                 timingPath = existingTiming;
             }
@@ -660,7 +1156,7 @@ export function registerGenerateCommand(program) {
         const narrationSourcePath = resolve(projectDir, "narration.md");
         if (opts.audio !== false && existsSync(narrationSourcePath)) {
             const speed = parseFloat(opts.speed);
-            const voice = await resolveVoiceForGenerate(opts.voice, opts.provider);
+            const voice = await resolveVoiceForGenerate(opts.voice, opts.provider, projectDir);
             const explicitVoiceFlag = !!(opts.voice || opts.provider);
             if (opts.scene || shouldRegenerateAudio(projectDir, voice, explicitVoiceFlag, timingData)) {
                 const { ttsResults, actualVoice } = await generateAudioForProject(narrationSourcePath, projectDir, voice, speed, opts.scene);
@@ -696,6 +1192,11 @@ export function registerGenerateCommand(program) {
         const { matched, missing } = findAudioFiles(projectDir, timingData);
         debug(`Audio files: ${matched.length} matched, ${missing.length} missing`);
         let finalPath = null;
+        // Check for per-scene clips
+        const sceneGroups = discoverSceneGroups(projectDir);
+        const sceneClips = sceneGroups.length > 0
+            ? collectSceneClips(projectDir, sceneGroups)
+            : [];
         if (matched.length > 0) {
             if (!hasFfmpeg()) {
                 console.error("Audio files found but ffmpeg is not installed. Install ffmpeg to stitch audio with video.");
@@ -724,16 +1225,34 @@ export function registerGenerateCommand(program) {
                 // Fall back to simple stitch if intelligent assembly failed
                 if (!finalPath) {
                     console.log("  Intelligent assembly incomplete, falling back to simple stitch.\n");
-                    finalPath = stitchAudio(videoPath, matched, timingData, recordingsDir, applyWatermark);
+                    if (sceneClips.length > 0) {
+                        finalPath = assembleFromSceneClips(sceneClips, matched, recordingsDir, applyWatermark);
+                    }
+                    else {
+                        finalPath = stitchAudio(videoPath, matched, timingData, recordingsDir, applyWatermark);
+                    }
                 }
             }
+            else if (sceneClips.length > 0) {
+                // Per-scene assembly (default when scene clips exist)
+                finalPath = assembleFromSceneClips(sceneClips, matched, recordingsDir, applyWatermark);
+            }
             else {
-                // Simple stitch (default)
+                // Legacy simple stitch (default)
                 finalPath = stitchAudio(videoPath, matched, timingData, recordingsDir, applyWatermark);
             }
         }
+        else if (sceneClips.length > 0) {
+            // Per-scene clips but no audio — concatenate video only
+            if (hasFfmpeg()) {
+                finalPath = assembleFromSceneClips(sceneClips, [], recordingsDir, applyWatermark);
+            }
+            else {
+                console.warn("Warning: ffmpeg not available. Cannot assemble per-scene clips.");
+            }
+        }
         else if (videoPath) {
-            // No audio — copy or convert video as final output
+            // No audio — copy or convert single video as final output
             if (hasFfmpeg()) {
                 const outputPath = resolve(recordingsDir, "final.mp4");
                 console.log("No audio files found. Converting video to mp4...\n");
@@ -741,7 +1260,7 @@ export function registerGenerateCommand(program) {
                     const watermarkPath = getWatermarkPath();
                     if (applyWatermark && existsSync(watermarkPath)) {
                         execSync(`ffmpeg -y -i "${videoPath}" -i "${watermarkPath}" ` +
-                            `-filter_complex "[1:v][0:v]scale2ref=w=main_w*0.08:h=-1[wm_scaled][vmain];[wm_scaled]format=rgba,colorchannelmixer=aa=0.6[wm];[vmain][wm]overlay=W-w-24:H-h-16[vout]" ` +
+                            `-filter_complex "[1:v]scale=120:-1,format=rgba,colorchannelmixer=aa=0.6[wm];[0:v][wm]overlay=W-w-24:H-h-16[vout]" ` +
                             `-map "[vout]" -c:v libx264 -preset fast -crf 23 -pix_fmt yuv420p "${outputPath}"`, { encoding: "utf-8", timeout: 600_000, stdio: ["pipe", "pipe", "pipe"] });
                     }
                     else {
@@ -769,10 +1288,17 @@ export function registerGenerateCommand(program) {
             console.warn("Warning: No recorded video found. Skipping assembly.");
         }
         // Step 5: Split scenes and extract thumbnails
-        if (videoPath && timingData.scenes.length > 0 && hasFfmpeg()) {
+        // Skip splitting when per-scene recordings already exist — splitScenes is
+        // for legacy monolithic recordings and would corrupt per-scene videos by
+        // seeking with cumulative timing offsets into individual scene files.
+        const hasPerSceneRecordings = sceneGroups.length > 0
+            && sceneGroups.some(g => existsSync(resolve(recordingsDir, "scenes", g.id, "video.webm")));
+        if (videoPath && timingData.scenes.length > 0 && hasFfmpeg() && !hasPerSceneRecordings) {
             console.log("Splitting video into per-scene clips...\n");
             const sceneClips = splitScenes(videoPath, timingData, recordingsDir);
             console.log(`  Split ${sceneClips.length} scene clip(s)`);
+        }
+        if (videoPath && timingData.scenes.length > 0 && hasFfmpeg()) {
             console.log("Extracting thumbnails...\n");
             const thumbnails = extractThumbnails(videoPath, timingData, recordingsDir);
             console.log(`  Extracted ${thumbnails.length} thumbnail(s)\n`);