@devinilabs/reelstack 1.2.0

package/cli/preview.js

@@ -0,0 +1,59 @@
+/**
+ * `reelstack preview` — render a 10-second free demo (no license required).
+ * Used as a marketing hook so prospective buyers can see the quality before
+ * they pay.
+ */
+const path = require("node:path");
+const fs = require("node:fs");
+const { spawnSync } = require("node:child_process");
+const { banner, info, success, warn, fail, c } = require("./utils");
+
+async function run(_argv) {
+  banner();
+  info("Rendering a 10-second ReelStack demo (free, no license).");
+  console.log("");
+  warn("This previews the DesignReel preset (Cream Paper family) for 300 frames.");
+  console.log("");
+
+  const cwdPkgJson = path.join(process.cwd(), "package.json");
+  if (!fs.existsSync(cwdPkgJson)) {
+    fail("Run this inside a Remotion project (npm create video@latest first).");
+    process.exit(2);
+  }
+
+  // The preview uses the existing scaffolder but renders to /tmp.
+  const scaffold = require("./scaffold");
+  await scaffold.run([
+    "--family=paper",
+    "--preset=designreel",
+    "--name=ReelStackPreview",
+    "--force",
+  ]);
+
+  const out = path.join("/tmp", `reelstack-preview-${Date.now()}.mp4`);
+  info(`Rendering to ${out}…`);
+  const result = spawnSync(
+    "npx",
+    [
+      "remotion", "render", "ReelStackPreviewReel", out,
+      "--codec=h264", "--crf=18", "--video-bitrate=8M", "--pixel-format=yuv420p",
+    ],
+    { stdio: "inherit" },
+  );
+
+  if (result.status !== 0) {
+    fail("Preview render failed. Try: npm run dev to debug in Studio.");
+    process.exit(result.status ?? 1);
+  }
+
+  console.log("");
+  success(`Preview rendered: ${out}`);
+  console.log("");
+  console.log(c.gray("Like what you see? Get the full ReelStack:"));
+  console.log(`  ${c.cyan("https://devini.io/reelstack")}`);
+  console.log("");
+  console.log(c.gray("₹149 INR / $3 USD one-time (region-detected). All 5 families, all 22 presets, lifetime v1.x updates."));
+  console.log("");
+}
+
+module.exports = { run };

package/cli/render.js

@@ -0,0 +1,404 @@
+/**
+ * `reelstack render <comp-id> [flags]`
+ *
+ * Flags:
+ *   --platform=ig|tiktok|shorts   Apply platform-optimal preset (default: ig).
+ *   --out=<path>                  Override output path (default: out/<id>-<platform>.mp4).
+ *   --force                       Skip pre-render lint failures.
+ *   --format=mp4,gif              Comma list. When `gif` is included, also
+ *                                 produce a palette-optimized GIF (lanczos+palettegen).
+ *   --bgm=<path.mp3>              Auto-mix background music at -14 LUFS-ish (volume=0.4).
+ *   --interpolate=60              Render at 60fps (passes `--fps 60` to Remotion if supported).
+ *   --palette-optimize            Use a 64-color palette quantization for GIF (default 256).
+ *
+ * Pre-render pipeline:
+ *   1. Lint. Aborts on violations unless --force.
+ *   2. Smoke check: render frame 0 / midpoint / last via `remotion still`,
+ *      check each PNG > 30KB. Warn if any frame looks all-black.
+ *   3. Render MP4.
+ *   4. Optional: mix BGM, produce GIF.
+ */
+const path = require("node:path");
+const fs = require("node:fs");
+const { spawnSync } = require("node:child_process");
+const { info, success, fail, warn, c, readJson, ask } = require("./utils");
+const { lint } = require("./lint");
+
+const REELSTACK_PKG = path.dirname(__dirname);
+const PRESETS = readJson(path.join(REELSTACK_PKG, "utils", "render-presets.json"));
+
+function parseArgs(argv) {
+  const out = { positional: [] };
+  for (const a of argv) {
+    if (a.startsWith("--")) {
+      const m = a.match(/^--([^=]+)(?:=(.*))?$/);
+      out[m[1]] = m[2] ?? true;
+    } else out.positional.push(a);
+  }
+  return out;
+}
+
+/**
+ * Recursive directory walker — collects absolute paths of every .tsx file
+ * under `dir`, ignoring node_modules / dot-dirs / build outputs.
+ */
+function walkTsx(dir, results = []) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return results;
+  }
+  for (const ent of entries) {
+    if (ent.name.startsWith(".") || ent.name === "node_modules" || ent.name === "dist" || ent.name === "out") continue;
+    const full = path.join(dir, ent.name);
+    if (ent.isDirectory()) walkTsx(full, results);
+    else if (ent.isFile() && ent.name.endsWith(".tsx")) results.push(full);
+  }
+  return results;
+}
+
+/**
+ * Resolve the source file for a composition id using a tiered strategy:
+ *   1. ./src/<compId>.tsx (the simple convention)
+ *   2. Parse src/Root.tsx (or src/index.tsx) for `import { CompId } from "./Path"`
+ *      that matches `compId` or `${compId}Reel`.
+ *   3. Recursive scan of src/ for <compId>.tsx and <compId>Reel.tsx.
+ *      If multiple, prefer the shallowest path.
+ *   4. stderr prompt to the user.
+ */
+async function resolveCompFile(cwd, compId) {
+  const srcDir = path.join(cwd, "src");
+
+  // 1. Simple convention.
+  const candidates = [
+    path.join(srcDir, `${compId}.tsx`),
+    path.join(srcDir, `${compId}Reel.tsx`),
+  ];
+  for (const cand of candidates) {
+    if (fs.existsSync(cand)) return cand;
+  }
+
+  // 2. Parse Root.tsx / index.tsx imports.
+  const rootCandidates = [
+    path.join(srcDir, "Root.tsx"),
+    path.join(srcDir, "index.tsx"),
+    path.join(srcDir, "Root.ts"),
+  ];
+  for (const root of rootCandidates) {
+    if (!fs.existsSync(root)) continue;
+    const rootSrc = fs.readFileSync(root, "utf8");
+    const importRegex = /import\s*\{\s*([^}]+)\s*\}\s*from\s*["']([^"']+)["']/g;
+    let m;
+    while ((m = importRegex.exec(rootSrc)) !== null) {
+      const names = m[1].split(",").map((s) => s.trim().split(/\s+as\s+/)[0].trim());
+      const relPath = m[2];
+      if (!relPath.startsWith(".")) continue;
+      const wantsForms = [compId, `${compId}Reel`];
+      const hit = names.find((n) => wantsForms.includes(n));
+      if (!hit) continue;
+      const baseResolved = path.resolve(path.dirname(root), relPath);
+      const tries = [
+        baseResolved + ".tsx",
+        baseResolved + ".ts",
+        path.join(baseResolved, "index.tsx"),
+        path.join(baseResolved, "index.ts"),
+      ];
+      for (const t of tries) {
+        if (fs.existsSync(t)) return t;
+      }
+    }
+  }
+
+  // 3. Recursive scan of src/.
+  if (fs.existsSync(srcDir)) {
+    const all = walkTsx(srcDir);
+    const targets = new Set([`${compId}.tsx`, `${compId}Reel.tsx`]);
+    const matches = all.filter((p) => targets.has(path.basename(p)));
+    if (matches.length > 0) {
+      matches.sort(
+        (a, b) =>
+          path.relative(srcDir, a).split(path.sep).length -
+          path.relative(srcDir, b).split(path.sep).length,
+      );
+      return matches[0];
+    }
+  }
+
+  // 4. Prompt.
+  warn(`Could not auto-resolve source file for composition "${compId}".`);
+  const answer = await ask("Enter the path to the .tsx file (relative to cwd, or absolute):");
+  if (!answer) return null;
+  const resolved = path.isAbsolute(answer) ? answer : path.resolve(cwd, answer);
+  if (!fs.existsSync(resolved)) {
+    fail(`File not found: ${resolved}`);
+    return null;
+  }
+  return resolved;
+}
+
+/**
+ * Pre-render smoke check — render 3 stills (frame 0, midpoint, last) and
+ * warn if any PNG is < 30KB (likely all-black, probably a broken composition).
+ *
+ * Best-effort: if `npx remotion still` doesn't accept the args we pass, we
+ * skip silently rather than block the render.
+ */
+function preRenderSmokeCheck(compId, totalFrames) {
+  const checkFrames = [
+    0,
+    Math.max(0, Math.floor(totalFrames / 2)),
+    Math.max(0, totalFrames - 1),
+  ];
+  const outDir = path.join(process.cwd(), "out");
+  try { fs.mkdirSync(outDir, { recursive: true }); } catch {}
+  const warnings = [];
+  for (const f of checkFrames) {
+    const pngPath = path.join(outDir, `_check_f${f}.png`);
+    const r = spawnSync(
+      "npx",
+      ["remotion", "still", compId, pngPath, `--frame=${f}`],
+      { stdio: "pipe", timeout: 60_000 },
+    );
+    if (r.error && r.error.code === "ETIMEDOUT") {
+      warn(`Smoke check frame ${f}: remotion still timed out after 60 seconds.`);
+      return { ok: true, skipped: true };
+    }
+    if (r.status !== 0) {
+      // Smoke check failed mechanically — don't block.
+      return { ok: true, skipped: true };
+    }
+    try {
+      const stat = fs.statSync(pngPath);
+      if (stat.size < 30 * 1024) {
+        warnings.push(`Frame ${f}: ${(stat.size / 1024).toFixed(1)}KB — looks all-black.`);
+      }
+    } catch {}
+  }
+  return { ok: warnings.length === 0, warnings, skipped: false };
+}
+
+/**
+ * Convert MP4 → palette-optimized GIF using ffmpeg.
+ * Two-pass: palettegen then paletteuse with lanczos scaling at 12fps / 540w.
+ */
+function mp4ToGif(mp4Path, gifPath, paletteOptimize) {
+  const palettePath = gifPath.replace(/\.gif$/, "-palette.png");
+  const maxColors = paletteOptimize ? 64 : 256;
+  const palettegen = spawnSync(
+    "ffmpeg",
+    [
+      "-y", "-i", mp4Path,
+      "-vf", `fps=12,scale=540:-1:flags=lanczos,palettegen=stats_mode=diff:max_colors=${maxColors}`,
+      palettePath,
+    ],
+    { stdio: "inherit", timeout: 120_000 },
+  );
+  if (palettegen.error && palettegen.error.code === "ETIMEDOUT") {
+    fail("ffmpeg palettegen timed out after 2 minutes. Check that the input file isn't corrupted.");
+    return false;
+  }
+  if (palettegen.status !== 0) return false;
+  const paletteuse = spawnSync(
+    "ffmpeg",
+    [
+      "-y", "-i", mp4Path, "-i", palettePath,
+      "-filter_complex", "fps=12,scale=540:-1:flags=lanczos[x];[x][1:v]paletteuse",
+      gifPath,
+    ],
+    { stdio: "inherit", timeout: 120_000 },
+  );
+  try { fs.unlinkSync(palettePath); } catch {}
+  if (paletteuse.error && paletteuse.error.code === "ETIMEDOUT") {
+    fail("ffmpeg paletteuse timed out after 2 minutes. Check that the input file isn't corrupted.");
+    return false;
+  }
+  return paletteuse.status === 0;
+}
+
+/**
+ * Mix BGM into existing MP4, replacing the original.
+ */
+function mixBgm(mp4Path, bgmPath) {
+  const tmpOut = mp4Path.replace(/\.mp4$/, ".bgm.mp4");
+  const r = spawnSync(
+    "ffmpeg",
+    [
+      "-y", "-i", mp4Path, "-i", bgmPath,
+      "-filter_complex", "[1:a]volume=0.4[bgm];[0:a][bgm]amix=inputs=2:duration=first[a]",
+      "-map", "0:v", "-map", "[a]", "-c:v", "copy",
+      tmpOut,
+    ],
+    { stdio: "inherit", timeout: 120_000 },
+  );
+  if (r.error && r.error.code === "ETIMEDOUT") {
+    fail("ffmpeg BGM mix timed out after 2 minutes. Check that the input file isn't corrupted.");
+    return false;
+  }
+  if (r.status !== 0) return false;
+  try {
+    fs.renameSync(tmpOut, mp4Path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Pure function: given an interpolate fps target, return the Remotion CLI
+ * flags to add and an optional warning string. Exported for unit testing.
+ *
+ * Remotion 4 (verified at 4.0.459) supports `--fps <n>` via the
+ * `overrideFpsOption` in @remotion/renderer (cliFlag = 'fps'). It overrides
+ * the composition's declared fps but does NOT perform frame interpolation.
+ *
+ * Returns:
+ *   { flagsToAdd: string[], warning: string|null }
+ *
+ * - If `interpolateFps` is null/undefined/NaN, returns no-op (no flags).
+ * - If `interpolateFps` is a finite positive number, returns `--fps=<n>`.
+ * - If `interpolateFps` is unparseable (NaN), returns no flags + a warning.
+ */
+function applyInterpolate({ interpolateFps }) {
+  if (interpolateFps === null || interpolateFps === undefined) {
+    return { flagsToAdd: [], warning: null };
+  }
+  if (!Number.isFinite(interpolateFps) || interpolateFps <= 0) {
+    return {
+      flagsToAdd: [],
+      warning:
+        "--interpolate=<fps> requires a positive number. Falling back to source fps. " +
+        "Note: Remotion 4's --fps flag overrides composition fps but doesn't interpolate frames; " +
+        "for true interpolation, use ffmpeg minterpolate post-render (planned for v1.2).",
+    };
+  }
+  return {
+    flagsToAdd: [`--fps=${interpolateFps}`],
+    warning: null,
+  };
+}
+
+async function run(argv) {
+  const args = parseArgs(argv);
+  const compId = args.positional[0];
+  if (!compId) {
+    fail("Usage: reelstack render <comp-id> [--platform=ig|tiktok|shorts] [--out=<path>] [--force] [--format=mp4,gif] [--bgm=<path>] [--interpolate=60] [--palette-optimize]");
+    process.exit(2);
+  }
+  const platform = args.platform || "ig";
+  const preset = PRESETS[platform];
+  if (!preset) {
+    fail(`Unknown platform "${platform}". Valid: ${Object.keys(PRESETS).join(", ")}.`);
+    process.exit(2);
+  }
+
+  const formats = (typeof args.format === "string" ? args.format : "mp4")
+    .split(",")
+    .map((s) => s.trim().toLowerCase())
+    .filter(Boolean);
+  const bgmPath = typeof args.bgm === "string" ? args.bgm : null;
+  const interpolateFps = typeof args.interpolate === "string" ? Number(args.interpolate) : null;
+  const paletteOptimize = args["palette-optimize"] === true || args["palette-optimize"] === "true";
+
+  if (bgmPath && !fs.existsSync(bgmPath)) {
+    fail(`BGM file not found: ${bgmPath}`);
+    process.exit(2);
+  }
+
+  // Find matching src file by composition id (tiered resolution).
+  const candidate = await resolveCompFile(process.cwd(), compId);
+  if (candidate && !args.force) {
+    info(`Linting ${path.relative(process.cwd(), candidate)} before render…`);
+    const v = lint(candidate);
+    if (v.length > 0) {
+      warn(`Lint reported ${v.length} violation(s). Pass --force to render anyway.`);
+      v.forEach((item) =>
+        console.log(`  ${c.gray(`L${item.line}`)}  ${c.yellow(item.code)}  ${item.msg}`),
+      );
+      process.exit(1);
+    }
+  } else if (!candidate) {
+    warn(`Could not resolve source file for "${compId}". Skipping pre-render lint.`);
+  }
+
+  // Pre-render smoke check (frame 0 / mid / last). Best-effort.
+  // We don't know the comp's totalFrames here without parsing — use a coarse
+  // 270-frame guess (9s at 30fps) for the midpoint/last check. Remotion's
+  // `still` will clamp out-of-range frames and may still error; we treat any
+  // smoke-check failure as a skip rather than a hard block.
+  const guessTotalFrames = 270;
+  if (!args.force && !args["skip-smoke"]) {
+    info("Smoke-checking 3 frames (0 / mid / last)…");
+    const smoke = preRenderSmokeCheck(compId, guessTotalFrames);
+    if (smoke.skipped) {
+      warn("Smoke check skipped (remotion still didn't run cleanly). Continuing.");
+    } else if (smoke.warnings && smoke.warnings.length > 0) {
+      warn("Smoke check warnings:");
+      smoke.warnings.forEach((w) => console.log(`  ${c.yellow("•")} ${w}`));
+      const proceed = await ask("Looks like one or more frames may be all-black. Continue rendering? (y/N)");
+      if (!/^y(es)?$/i.test(proceed.trim())) {
+        fail("Aborted by user.");
+        process.exit(1);
+      }
+    } else {
+      success("Smoke check passed.");
+    }
+  }
+
+  const out = args.out || `out/${compId}-${platform}.mp4`;
+  const remotionFlags = [...preset.remotionFlags];
+
+  // --interpolate=<fps> → pass `--fps <n>` to Remotion (Remotion 4 supports
+  // `overrideFpsOption` with cliFlag 'fps' — verified via @remotion/renderer
+  // source @ dist/options/override-fps.js, available since 4.0.x).
+  //
+  // CAVEAT: Remotion's `--fps` overrides the composition's declared fps but
+  // does NOT perform frame interpolation between frames — it just plays the
+  // existing N frames at the new rate. For real motion interpolation (RIFE
+  // / optical flow), use ffmpeg `minterpolate` post-render or
+  // Remotion-Lambda's interpolation utility (see TODO below).
+  //
+  // TODO(v1.2): swap --fps for true frame interpolation via either
+  //   (a) ffmpeg minterpolate=fps=60:mi_mode=mci in mp4ToGif's sibling step,
+  //   (b) @remotion/lambda's interpolation pipeline once it ships.
+  const { flagsToAdd, warning } = applyInterpolate({ interpolateFps });
+  if (warning) warn(warning);
+  remotionFlags.push(...flagsToAdd);
+  if (flagsToAdd.length > 0) {
+    info(`Interpolating to ${interpolateFps}fps via Remotion --fps flag.`);
+  }
+
+  const effectiveFps = flagsToAdd.length > 0 && Number.isFinite(interpolateFps) && interpolateFps > 0
+    ? interpolateFps
+    : preset.fps;
+  info(`Rendering ${compId} → ${out} (${preset.label}, ${preset.width}×${preset.height} ${effectiveFps}fps)`);
+  const result = spawnSync(
+    "npx",
+    ["remotion", "render", compId, out, ...remotionFlags],
+    { stdio: "inherit" },
+  );
+  if (result.status !== 0) {
+    fail("Render failed. See remotion output above.");
+    process.exit(result.status ?? 1);
+  }
+  success(`Rendered MP4 to ${out}`);
+
+  // Optional: BGM mix.
+  if (bgmPath) {
+    info(`Mixing BGM (${bgmPath}) at -14 LUFS-ish (volume=0.4)…`);
+    const ok = mixBgm(out, bgmPath);
+    if (ok) success(`BGM mixed in-place: ${out}`);
+    else warn("BGM mix failed (ffmpeg error). Original MP4 is preserved.");
+  }
+
+  // Optional: GIF.
+  if (formats.includes("gif")) {
+    const gifOut = out.replace(/\.mp4$/, ".gif");
+    info(`Producing palette-optimized GIF → ${gifOut} (${paletteOptimize ? "64-color" : "256-color"})`);
+    const ok = mp4ToGif(out, gifOut, paletteOptimize);
+    if (ok) success(`Rendered GIF to ${gifOut}`);
+    else warn("GIF generation failed (ffmpeg error).");
+  }
+}
+
+module.exports = { run, resolveCompFile, mp4ToGif, mixBgm, applyInterpolate };