@t3lnet/sceneforge 1.0.3 → 1.0.5

package/cli/commands/split-video.js

@@ -0,0 +1,236 @@
+import * as fs from "fs/promises";
+import * as path from "path";
+import { checkFFmpeg, getMediaDuration, runFFmpeg } from "../utils/media.js";
+import { getOutputPaths, readJson, resolveRoot } from "../utils/paths.js";
+import { getFlagValue, hasFlag } from "../utils/args.js";
+import { sanitizeFileSegment } from "../utils/sanitize.js";
+
+function printHelp() {
+  console.log(`
+Split recorded demo video into per-step clips
+
+Usage:
+  sceneforge split [options]
+
+Options:
+  --demo <name>         Process a specific demo by name
+  --all                 Process all demos with script JSON files
+  --root <path>         Project root (defaults to cwd)
+  --output-dir <path>   Output directory (defaults to e2e/output or output)
+  --help, -h            Show this help message
+
+Examples:
+  sceneforge split --demo create-quote
+  sceneforge split --all
+`);
+}
+
+async function findVideoFile(demoName, videosDir, testResultsDir) {
+  const possiblePaths = [
+    path.join(videosDir, `${demoName}.webm`),
+    path.join(videosDir, `${demoName}-flow.webm`),
+  ];
+
+  try {
+    const dirs = await fs.readdir(testResultsDir);
+    for (const dir of dirs) {
+      if (dir.includes(demoName) || dir.includes(demoName.replace(/-/g, ""))) {
+        possiblePaths.push(path.join(testResultsDir, dir, "video.webm"));
+      }
+    }
+  } catch {
+    // Ignore missing test-results directory
+  }
+
+  for (const videoPath of possiblePaths) {
+    try {
+      await fs.access(videoPath);
+      return videoPath;
+    } catch {
+      // Continue
+    }
+  }
+
+  return null;
+}
+
+async function splitDemo(demoName, paths) {
+  console.log(`\n[split] Processing: ${demoName}\n`);
+
+  const scriptPath = path.join(paths.scriptsDir, `${demoName}.json`);
+  let script;
+
+  try {
+    script = await readJson(scriptPath);
+  } catch {
+    console.error(`[split] ✗ Script not found: ${scriptPath}`);
+    console.error(`[split]   Generate scripts before splitting video`);
+    return;
+  }
+
+  if (!script.stepBoundaries || script.stepBoundaries.length === 0) {
+    console.error("[split] ✗ No step boundaries found in script");
+    console.error("[split]   Regenerate scripts with step boundaries");
+    return;
+  }
+
+  const videoPath = await findVideoFile(demoName, paths.videosDir, paths.testResultsDir);
+  if (!videoPath) {
+    console.error(`[split] ✗ Video not found for: ${demoName}`);
+    return;
+  }
+
+  console.log(`[split] Video: ${videoPath}`);
+  console.log(`[split] Steps: ${script.stepBoundaries.length}`);
+
+  const videoDurationSec = await getMediaDuration(videoPath);
+  const videoDurationMs = Math.round(videoDurationSec * 1000);
+
+  const stepClipsDir = path.join(paths.videosDir, demoName);
+  await fs.mkdir(stepClipsDir, { recursive: true });
+
+  for (const boundary of script.stepBoundaries) {
+    const isFirstStep = boundary.stepIndex === 0;
+    const startMs = isFirstStep ? 0 : boundary.videoStartMs;
+    if (startMs >= videoDurationMs) {
+      console.warn(`[split]   Skipping ${boundary.stepId}: start beyond video duration`);
+      continue;
+    }
+    const clampedEndMs = Math.min(boundary.videoEndMs, videoDurationMs);
+    if (clampedEndMs <= startMs) {
+      console.warn(`[split]   Skipping ${boundary.stepId}: invalid duration after clamp`);
+      continue;
+    }
+    const startSec = startMs / 1000;
+    const duration = (clampedEndMs - startMs) / 1000;
+    const paddedIndex = String(boundary.stepIndex + 1).padStart(2, "0");
+    const safeStepId = sanitizeFileSegment(
+      boundary.stepId,
+      `step-${boundary.stepIndex + 1}`
+    );
+    const outputFileName = `step_${paddedIndex}_${safeStepId}.mp4`;
+    const outputPath = path.join(stepClipsDir, outputFileName);
+
+    console.log(
+      `[split]   ${paddedIndex}. ${boundary.stepId}: ${startSec.toFixed(2)}s - ${(startSec + duration).toFixed(2)}s (${duration.toFixed(2)}s)`
+    );
+
+    try {
+      await runFFmpeg([
+        "-y",
+        "-i",
+        videoPath,
+        "-ss",
+        String(startSec),
+        "-t",
+        String(duration),
+        "-c:v",
+        "libx264",
+        "-preset",
+        "fast",
+        "-an",
+        outputPath,
+      ]);
+    } catch (error) {
+      console.error(`[split] ✗ Failed to extract step ${boundary.stepId}:`, error);
+      throw error;
+    }
+  }
+
+  const manifestPath = path.join(stepClipsDir, "steps-manifest.json");
+  const manifest = {
+    demoName: script.demoName,
+    title: script.title,
+    generatedAt: new Date().toISOString(),
+    sourceVideo: videoPath,
+    sourceVideoDurationMs: videoDurationMs,
+    steps: script.stepBoundaries.map((boundary) => {
+      const paddedIndex = String(boundary.stepIndex + 1).padStart(2, "0");
+      const isFirstStep = boundary.stepIndex === 0;
+      const splitStartMs = isFirstStep ? 0 : boundary.videoStartMs;
+      const clampedEndMs = Math.min(boundary.videoEndMs, videoDurationMs);
+      const safeStepId = sanitizeFileSegment(
+        boundary.stepId,
+        `step-${boundary.stepIndex + 1}`
+      );
+      return {
+        stepId: boundary.stepId,
+        safeStepId,
+        stepIndex: boundary.stepIndex,
+        videoFile: path.join(stepClipsDir, `step_${paddedIndex}_${safeStepId}.mp4`),
+        splitStartMs,
+        originalStartMs: boundary.videoStartMs,
+        originalEndMs: boundary.videoEndMs,
+        durationMs: Math.max(0, clampedEndMs - splitStartMs),
+      };
+    }),
+  };
+
+  await fs.writeFile(manifestPath, JSON.stringify(manifest, null, 2));
+
+  console.log(`\n[split] ✓ Split into ${script.stepBoundaries.length} clips`);
+  console.log(`[split]   Output: ${stepClipsDir}`);
+  console.log(`[split]   Manifest: ${manifestPath}`);
+}
+
+async function splitAll(paths) {
+  console.log("\n[split] Processing all demos...\n");
+
+  try {
+    const files = await fs.readdir(paths.scriptsDir);
+    const scriptFiles = files.filter(
+      (file) => file.endsWith(".json") && !file.endsWith(".voice.json") && !file.endsWith("manifest.json")
+    );
+
+    if (scriptFiles.length === 0) {
+      console.log("[split] No script files found");
+      return;
+    }
+
+    console.log(`[split] Found ${scriptFiles.length} demo(s)\n`);
+
+    for (const file of scriptFiles) {
+      const demoName = path.basename(file, ".json");
+      await splitDemo(demoName, paths);
+    }
+
+    console.log("\n[split] All demos processed!");
+  } catch (error) {
+    console.error("[split] Error:", error);
+  }
+}
+
+export async function runSplitVideoCommand(argv) {
+  const args = argv ?? process.argv.slice(2);
+  const help = hasFlag(args, "--help") || hasFlag(args, "-h");
+  const demo = getFlagValue(args, "--demo");
+  const all = hasFlag(args, "--all");
+  const root = getFlagValue(args, "--root");
+  const outputDir = getFlagValue(args, "--output-dir");
+
+  if (help) {
+    printHelp();
+    return;
+  }
+
+  const hasFFmpeg = await checkFFmpeg();
+  if (!hasFFmpeg) {
+    console.error("[error] FFmpeg is not installed");
+    process.exit(1);
+  }
+
+  const rootDir = resolveRoot(root);
+  const paths = await getOutputPaths(rootDir, outputDir);
+
+  if (demo) {
+    await splitDemo(demo, paths);
+    return;
+  }
+
+  if (all) {
+    await splitAll(paths);
+    return;
+  }
+
+  printHelp();
+}

package/cli/utils/args.js

@@ -0,0 +1,15 @@
+export function hasFlag(args, name) {
+  return args.includes(name);
+}
+
+export function getFlagValue(args, name) {
+  const index = args.indexOf(name);
+  if (index === -1) return null;
+  const value = args[index + 1];
+  return value ?? null;
+}
+
+export function getFlagValueOrDefault(args, name, defaultValue) {
+  const value = getFlagValue(args, name);
+  return value === null ? defaultValue : value;
+}

package/cli/utils/media.js

@@ -0,0 +1,81 @@
+import { spawn } from "child_process";
+
+const DEFAULT_MAX_OUTPUT_BYTES = 512 * 1024;
+
+function appendWithLimit(buffer, chunk, limit) {
+  const next = buffer + chunk;
+  if (next.length <= limit) {
+    return next;
+  }
+  return next.slice(next.length - limit);
+}
+
+function runCommand(command, args, options = {}) {
+  const { stdio = ["ignore", "pipe", "pipe"], cwd, maxOutputBytes = DEFAULT_MAX_OUTPUT_BYTES } = options;
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { stdio, cwd });
+    let stdout = "";
+    let stderr = "";
+
+    if (child.stdout) {
+      child.stdout.on("data", (chunk) => {
+        stdout = appendWithLimit(stdout, chunk.toString(), maxOutputBytes);
+      });
+    }
+
+    if (child.stderr) {
+      child.stderr.on("data", (chunk) => {
+        stderr = appendWithLimit(stderr, chunk.toString(), maxOutputBytes);
+      });
+    }
+
+    child.on("error", (error) => {
+      reject(error);
+    });
+
+    child.on("close", (code) => {
+      if (code === 0) {
+        resolve({ stdout, stderr });
+        return;
+      }
+      const error = new Error(`${command} exited with code ${code}`);
+      error.code = code;
+      error.stderr = stderr;
+      reject(error);
+    });
+  });
+}
+
+export async function checkFFmpeg() {
+  try {
+    await runCommand("ffmpeg", ["-version"], { stdio: ["ignore", "ignore", "ignore"] });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function getMediaDuration(filePath) {
+  const { stdout } = await runCommand("ffprobe", [
+    "-v",
+    "error",
+    "-show_entries",
+    "format=duration",
+    "-of",
+    "default=noprint_wrappers=1:nokey=1",
+    filePath,
+  ]);
+  const duration = parseFloat(stdout.trim());
+  if (!Number.isFinite(duration)) {
+    throw new Error(`Unable to parse media duration for ${filePath}`);
+  }
+  return duration;
+}
+
+export function runFFmpeg(args, options = {}) {
+  return runCommand("ffmpeg", args, options);
+}
+
+export function runFFprobe(args, options = {}) {
+  return runCommand("ffprobe", args, options);
+}

package/cli/utils/paths.js

@@ -0,0 +1,93 @@
+import * as fs from "fs/promises";
+import * as path from "path";
+
+export function resolveRoot(explicitRoot) {
+  return explicitRoot ? path.resolve(explicitRoot) : process.cwd();
+}
+
+async function pathExists(candidatePath) {
+  try {
+    await fs.access(candidatePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function resolveOutputDir(rootDir, explicitOutputDir) {
+  if (explicitOutputDir) {
+    return path.resolve(rootDir, explicitOutputDir);
+  }
+
+  const outputDir = path.join(rootDir, "output");
+  if (await pathExists(outputDir)) {
+    return outputDir;
+  }
+
+  const e2eOutputDir = path.join(rootDir, "e2e", "output");
+  if (await pathExists(e2eOutputDir)) {
+    return e2eOutputDir;
+  }
+
+  return outputDir;
+}
+
+export async function resolveEnvFile(rootDir, explicitEnvFile) {
+  if (explicitEnvFile) {
+    return path.resolve(rootDir, explicitEnvFile);
+  }
+
+  const rootEnvFile = path.join(rootDir, ".env");
+  if (await pathExists(rootEnvFile)) {
+    return rootEnvFile;
+  }
+
+  const localEnvFile = path.join(rootDir, ".local", ".env");
+  if (await pathExists(localEnvFile)) {
+    return localEnvFile;
+  }
+
+  const sceneForgeEnvFile = path.join(rootDir, "sceneforge", ".env");
+  if (await pathExists(sceneForgeEnvFile)) {
+    return sceneForgeEnvFile;
+  }
+
+  const legacyEnvFile = path.join(rootDir, "demo-yaml-creator", ".env");
+  if (await pathExists(legacyEnvFile)) {
+    return legacyEnvFile;
+  }
+
+  const e2eEnvFile = path.join(rootDir, "e2e", ".env");
+  if (await pathExists(e2eEnvFile)) {
+    return e2eEnvFile;
+  }
+
+  return null;
+}
+
+export async function getOutputPaths(rootDir, explicitOutputDir) {
+  const outputDir = await resolveOutputDir(rootDir, explicitOutputDir);
+
+  return {
+    outputDir,
+    scriptsDir: path.join(outputDir, "scripts"),
+    videosDir: path.join(outputDir, "videos"),
+    audioDir: path.join(outputDir, "audio"),
+    finalDir: path.join(outputDir, "final"),
+    tempDir: path.join(outputDir, "temp"),
+    testResultsDir: path.join(outputDir, "test-results"),
+  };
+}
+
+export async function ensureDir(dirPath) {
+  await fs.mkdir(dirPath, { recursive: true });
+}
+
+export async function readJson(filePath) {
+  const content = await fs.readFile(filePath, "utf-8");
+  return JSON.parse(content);
+}
+
+export function toAbsolute(rootDir, maybeRelative) {
+  return path.isAbsolute(maybeRelative) ? maybeRelative : path.join(rootDir, maybeRelative);
+}

package/cli/utils/sanitize.js

@@ -0,0 +1,19 @@
+const DEFAULT_MAX_LENGTH = 80;
+
+export function sanitizeFileSegment(value, fallback = "segment", maxLength = DEFAULT_MAX_LENGTH) {
+  const raw = String(value ?? "").trim();
+  if (!raw) {
+    return fallback;
+  }
+
+  const cleaned = raw.replace(/[^a-zA-Z0-9._-]+/g, "_");
+  const collapsed = cleaned.replace(/_{2,}/g, "_").replace(/^_+|_+$/g, "");
+  const safe = collapsed || fallback;
+  const trimmed = safe.length > maxLength ? safe.slice(0, maxLength) : safe;
+
+  if (trimmed === "." || trimmed === "..") {
+    return fallback;
+  }
+
+  return trimmed;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@t3lnet/sceneforge",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "SceneForge runner and generation utilities for YAML-driven demos",
   "license": "MIT",
   "author": "T3LNET",
@@ -23,12 +23,16 @@
       "require": "./dist/index.cjs"
     }
   },
+  "bin": {
+    "sceneforge": "./cli/cli.js"
+  },
   "publishConfig": {
     "access": "public"
   },
   "sideEffects": false,
   "files": [
     "dist",
+    "cli",
     "README.md",
     "LICENSE"
   ],
@@ -36,6 +40,7 @@
     "build": "tsup src/index.ts --format esm,cjs --dts --sourcemap --clean --out-dir dist"
   },
   "dependencies": {
+    "dotenv": "^17.2.3",
     "elevenlabs": "^1.59.0",
     "yaml": "^2.7.0",
     "zod": "^3.24.2"