@vfrey/vfrey 0.0.1 → 1.0.0-beta.0

package/src/render/html-engine.ts

@@ -0,0 +1,149 @@
+import { execFile, spawn } from "node:child_process";
+import { promisify } from "node:util";
+import { copyFile, mkdir, rm, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import type { RenderProps } from "@vfrey/contracts";
+import { hyperframesCli, commandFor, FRAMEY_ENTRY } from "../product/probes.js";
+import { resolveHeadlessShell } from "./chrome.js";
+import { retimeToVoice } from "./framey-template.js";
+import { kineticTypeHtml } from "./framey-template.js";
+
+const GSAP_FILE = fileURLToPath(new URL("../scene/assets/gsap/gsap.min.js", import.meta.url));
+
+export type HtmlEngineId = "vfrey-framey" | "hyperframes";
+
+type Env = Record<string, string | undefined>;
+
+export interface HtmlRenderInput {
+  engine: HtmlEngineId;
+  props: RenderProps;
+  voiceoverPath: string | null;
+  outputPath: string;
+  /** A folder this render owns. It holds the composition project and is removed after a good render. */
+  workDir: string;
+  env?: Env;
+  cwd?: string;
+}
+
+/** Test-only: `VFREY_ENGINE_FAIL=<engine id>` (or `1`) makes that engine throw before it writes output. */
+export function forcedFailure(engine: string, env: Env): string | null {
+  const value = env.VFREY_ENGINE_FAIL;
+  return value && (value === engine || value === "1") ? "Forced to fail by VFREY_ENGINE_FAIL (test hook)." : null;
+}
+
+/** Writes the composition project: one `index.html` and the voice track under `assets/`. */
+export async function writeProject(props: RenderProps, voiceoverPath: string | null, dir: string, env: Env = process.env): Promise<void> {
+  await mkdir(path.join(dir, "assets"), { recursive: true });
+  // GSAP is vfrey's own pinned copy: a render never loads a script from a CDN.
+  await copyFile(GSAP_FILE, path.join(dir, "assets", "gsap.min.js"));
+  let voiceFile: string | null = null;
+  if (voiceoverPath) {
+    voiceFile = `assets/voice${path.extname(voiceoverPath) || ".mp3"}`;
+    await copyFile(voiceoverPath, path.join(dir, voiceFile));
+  }
+  const timed = voiceoverPath ? retimeToVoice(props, await voiceSeconds(path.join(dir, voiceFile!), env)) : props;
+  await writeFile(path.join(dir, "index.html"), kineticTypeHtml(timed, voiceFile));
+}
+
+/** The voice track's length in seconds, or null when ffprobe cannot say. */
+export async function voiceSeconds(file: string, env: Env): Promise<number | null> {
+  try {
+    const { stdout } = await promisify(execFile)("ffprobe", ["-v", "error", "-show_entries", "format=duration", "-of", "csv=p=0", file], {
+      env: env as NodeJS.ProcessEnv,
+      timeout: 15_000,
+    });
+    const value = Number(String(stdout).trim());
+    return Number.isFinite(value) && value > 0 ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+const DOWNLOAD_LINE = "Downloading Chrome Headless Shell (about 170 MB), first time only…";
+
+/**
+ * The Chrome Headless Shell to render with. When it is not cached yet, download it the way Remotion does on its
+ * first render, into the same cache, so both engines share it. A failed download ends the render with a Fix line.
+ *
+ * `VFREY_TEST_CHROME_MISSING` is a test hook: `1` pretends the shell is missing (the line prints, nothing is
+ * downloaded, the shell that exists is used), and `fail` also makes the download fail. The real cache is untouched.
+ */
+export async function ensureChrome(env: Env, cwd: string): Promise<string> {
+  const simulated = env.VFREY_TEST_CHROME_MISSING;
+  const found = resolveHeadlessShell(env, cwd);
+  if (found && !simulated) return found;
+  process.stderr.write(`${DOWNLOAD_LINE}\n`);
+  try {
+    if (simulated === "fail") throw new Error("the download server could not be reached");
+    if (!simulated) {
+      const { ensureBrowser } = await import("@remotion/renderer");
+      // Quiet: stdout belongs to the summary and --json, and the line above already says what is happening.
+      await ensureBrowser({ logLevel: "error", chromeMode: "headless-shell" });
+    }
+  } catch (error) {
+    const why = (error instanceof Error ? error.message : String(error)).replace(/\s+/g, " ").trim().replace(/\.$/, "").slice(0, 200);
+    throw new Error(`Chrome Headless Shell could not be downloaded (${why}). Fix: connect to the internet and run it again, or choose Remotion with --engine remotion.`);
+  }
+  const after = resolveHeadlessShell(env, cwd);
+  if (!after) throw new Error("Chrome Headless Shell could not be found after the download. Fix: run it again, or choose Remotion with --engine remotion.");
+  return after;
+}
+
+export function run(command: string, args: string[], env: NodeJS.ProcessEnv, cwd: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { env, cwd, stdio: ["ignore", "pipe", "pipe"] });
+    let tail = "";
+    const keep = (chunk: Buffer) => {
+      tail = (tail + chunk.toString()).slice(-4000);
+    };
+    child.stdout.on("data", keep);
+    child.stderr.on("data", keep);
+    child.on("error", reject);
+    child.on("exit", (code, signal) => {
+      if (code === 0) return resolve();
+      const lines = tail.split(/\r?\n/).map((line) => line.trim()).filter(Boolean).slice(-6).join(" | ");
+      reject(new Error(`the renderer exited with ${signal ?? `code ${code}`}${lines ? `: ${lines}` : ""}`));
+    });
+  });
+}
+
+/**
+ * Renders the vfrey vertical short with an HTML engine. Framey (the vendored build) and the upstream
+ * HyperFrames CLI take the same project folder and the same `render` arguments, so one adapter drives both.
+ */
+export async function renderHtmlEngine(input: HtmlRenderInput): Promise<void> {
+  const env = input.env ?? process.env;
+  const cwd = input.cwd ?? process.cwd();
+  let command: string;
+  let args: string[];
+  if (input.engine === "vfrey-framey") {
+    command = process.execPath;
+    args = [FRAMEY_ENTRY];
+  } else {
+    const cli = hyperframesCli(env, cwd);
+    if (!cli) throw new Error("the HyperFrames CLI was not found");
+    ({ command, args } = commandFor(cli.bin));
+  }
+  const chrome = await ensureChrome(env, cwd);
+  await mkdir(path.dirname(input.outputPath), { recursive: true });
+  await rm(input.workDir, { recursive: true, force: true });
+  await writeProject(input.props, input.voiceoverPath, input.workDir, env);
+  await rm(input.outputPath, { force: true });
+  await run(
+    command,
+    [...args, "render", input.workDir, "-o", input.outputPath, "--quality", "standard", "--fps", "30"],
+    {
+      ...env,
+      PRODUCER_HEADLESS_SHELL_PATH: chrome,
+      HYPERFRAMES_BROWSER_PATH: chrome,
+      HYPERFRAMES_NO_TELEMETRY: "1",
+      HYPERFRAMES_NO_UPDATE_CHECK: "1",
+      DO_NOT_TRACK: "1",
+    },
+    input.workDir,
+  );
+  const info = await stat(input.outputPath).catch(() => null);
+  if (!info || info.size <= 0) throw new Error("the renderer wrote no video");
+  await rm(input.workDir, { recursive: true, force: true });
+}

package/src/render/node-crypto-stub.ts

@@ -0,0 +1,11 @@
+export function randomBytes(): Uint8Array {
+  return new Uint8Array(12);
+}
+
+export function createCipheriv(): never {
+  throw new Error("node:crypto is not available inside the Remotion bundle");
+}
+
+export function createDecipheriv(): never {
+  throw new Error("node:crypto is not available inside the Remotion bundle");
+}

package/src/render/probe.ts

@@ -0,0 +1,29 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+type Env = Record<string, string | undefined>;
+
+/** What a rendered file really is, read from the file and not from the plan. */
+export interface RenderedVideo {
+  durationSec: number;
+  width: number;
+  height: number;
+}
+
+/** Probes the mp4 with ffprobe. Null when ffprobe is missing or the file is not a video. */
+export async function probeVideo(file: string, env: Env = process.env): Promise<RenderedVideo | null> {
+  try {
+    const { stdout } = await promisify(execFile)(
+      "ffprobe",
+      ["-v", "error", "-select_streams", "v:0", "-show_entries", "stream=width,height", "-show_entries", "format=duration", "-of", "json", file],
+      { env: env as NodeJS.ProcessEnv, timeout: 15_000 },
+    );
+    const parsed = JSON.parse(String(stdout)) as { streams?: Array<{ width?: number; height?: number }>; format?: { duration?: string } };
+    const stream = parsed.streams?.[0];
+    const durationSec = Number(parsed.format?.duration);
+    if (!stream?.width || !stream.height || !Number.isFinite(durationSec) || durationSec <= 0) return null;
+    return { durationSec: Math.round(durationSec * 10) / 10, width: stream.width, height: stream.height };
+  } catch {
+    return null;
+  }
+}

package/src/render/props.ts

@@ -0,0 +1,17 @@
+import { templatePalette } from "@vfrey/contracts";
+import type { ContentPackage, RenderProps } from "@vfrey/contracts";
+
+export function toRenderProps(content: ContentPackage, voiceoverFile: string | null): RenderProps {
+  return {
+    templateId: content.plan.templateId,
+    title: content.title,
+    hook: content.hook,
+    beats: content.beats,
+    palette: templatePalette(content.plan.templateId, content.plan.paletteId),
+    captionStyle: content.plan.captionStyle,
+    pacing: content.plan.pacing,
+    voiceoverFile,
+    layoutSeed: content.plan.layoutSeed,
+    durationSec: content.durationSec,
+  };
+}

package/src/render/vertical-short.ts

@@ -0,0 +1,35 @@
+import { mkdir } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import type { RenderProps } from "@vfrey/contracts";
+import { withJsExtensions } from "./webpack.js";
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+
+/** Renders one of the existing vertical compositions. Not EngineMark. */
+export async function renderVerticalShort(outputPath: string, props: RenderProps, port = 4223): Promise<void> {
+  await mkdir(path.dirname(outputPath), { recursive: true });
+  const { bundle } = await import("@remotion/bundler");
+  const { renderMedia, selectComposition } = await import("@remotion/renderer");
+  const serveUrl = await bundle({
+    entryPoint: path.join(packageRoot, "src/remotion/index.ts"),
+    webpackOverride: withJsExtensions,
+  });
+  const inputProps = props as unknown as Record<string, unknown>;
+  const composition = await selectComposition({
+    serveUrl,
+    id: props.templateId,
+    inputProps,
+    port,
+  });
+  await renderMedia({
+    composition,
+    serveUrl,
+    codec: "h264",
+    outputLocation: outputPath,
+    inputProps,
+    port,
+    concurrency: Math.max(1, Math.min(4, os.availableParallelism())),
+  });
+}

package/src/render/webpack.ts

@@ -0,0 +1,33 @@
+import { fileURLToPath } from "node:url";
+import type { WebpackOverrideFn } from "@remotion/bundler";
+
+const stub = fileURLToPath(new URL("./node-crypto-stub.ts", import.meta.url));
+
+const rewriteNodeScheme = {
+  apply(compiler: {
+    hooks: {
+      normalModuleFactory: {
+        tap: (name: string, fn: (factory: { hooks: { beforeResolve: { tap: (name: string, fn: (data: { request: string }) => void) => void } } }) => void) => void;
+      };
+    };
+  }) {
+    compiler.hooks.normalModuleFactory.tap("RewriteNodeScheme", (factory) => {
+      factory.hooks.beforeResolve.tap("RewriteNodeScheme", (data) => {
+        if (data.request.startsWith("node:")) data.request = stub;
+      });
+    });
+  },
+};
+
+/** Remotion's webpack build does not map .js specifiers onto .ts files. Node and tsc do. */
+export const withJsExtensions: WebpackOverrideFn = (current) => ({
+  ...current,
+  plugins: [...(current.plugins ?? []), rewriteNodeScheme],
+  resolve: {
+    ...current.resolve,
+    extensionAlias: {
+      ...current.resolve?.extensionAlias,
+      ".js": [".tsx", ".ts", ".js"],
+    },
+  },
+});

package/src/render/worker.ts

@@ -0,0 +1,65 @@
+import { mkdir, copyFile, rm } from "node:fs/promises";
+import path from "node:path";
+import type { RenderProps } from "@vfrey/contracts";
+import { withJsExtensions } from "./webpack.js";
+import { resolveHeadlessShell } from "./chrome.js";
+
+/**
+ * Remotion bundles publicDir at bundle time, so the voice file is copied
+ * before bundle(). One bundle per render keeps the voice inside the serve URL.
+ * Rendering stays on a worker with ffmpeg and a headless browser. It does not
+ * run inside a short serverless invocation.
+ */
+export async function renderMp4(input: {
+  props: RenderProps;
+  voiceoverPath: string | null;
+  outputPath: string;
+  publicDir: string;
+  entryPoint: string;
+}): Promise<void> {
+  const publicDir = path.resolve(input.publicDir);
+  await mkdir(publicDir, { recursive: true });
+  await mkdir(path.dirname(input.outputPath), { recursive: true });
+  let voiceoverFile: string | null = null;
+  if (input.voiceoverPath) {
+    const ext = path.extname(input.voiceoverPath) || ".mp3";
+    voiceoverFile = `voice${ext}`;
+    await copyFile(input.voiceoverPath, path.join(publicDir, voiceoverFile));
+  }
+  const props: RenderProps = { ...input.props, voiceoverFile };
+  const { bundle } = await import("@remotion/bundler");
+  const { renderMedia, selectComposition } = await import("@remotion/renderer");
+  const bundleDir = `${publicDir}.bundle`;
+  try {
+  const serveUrl = await bundle({
+    entryPoint: input.entryPoint,
+    publicDir,
+    // The bundle lives beside the render and is removed after it; the default folder under the system temp is never cleaned.
+    outDir: bundleDir,
+    webpackOverride: withJsExtensions,
+  });
+  const inputProps = props as unknown as Record<string, unknown>;
+  // Reuse a Chrome Headless Shell that is already on this machine, so a fresh folder does not download another.
+  const browserExecutable = resolveHeadlessShell(process.env);
+  const browser = browserExecutable ? { browserExecutable } : {};
+  const port = Number(process.env.VFREY_REMOTION_PORT) || 4123;
+  const composition = await selectComposition({
+    serveUrl,
+    id: props.templateId,
+    inputProps,
+    port,
+    ...browser,
+  });
+  await renderMedia({
+    composition,
+    serveUrl,
+    codec: "h264",
+    outputLocation: input.outputPath,
+    inputProps,
+    port,
+    ...browser,
+  });
+  } finally {
+    await rm(bundleDir, { recursive: true, force: true });
+  }
+}

package/src/scene/assets/fonts/TitanOne-OFL.txt

@@ -0,0 +1,94 @@
+Copyright (c) 2011, Rodrigo Fuenzalida (www.rfuenzalida.com|hello@rfuenzalida.com),
+with Reserved Font Name Titan.
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/src/scene/assets/gsap/LICENSE.txt

@@ -0,0 +1,8 @@
+GSAP 3.14.2 (gsap.min.js), https://gsap.com
+
+Copyright 2025, GreenSock. All rights reserved.
+Subject to the terms of the GSAP Standard "no charge" license: https://gsap.com/standard-license
+
+This copy is bundled so scenes never load GSAP from a CDN while they render. It is the file
+gsap@3.14.2/dist/gsap.min.js from the npm package, unchanged. Pinned: it is replaced only by a
+deliberate change that also updates this note.