videoclaw 3.0.0-alpha.1

package/src/video/template-store.ts

@@ -0,0 +1,241 @@
+import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { artifactPathFor } from './artifact-store.js';
+import { resolveProjectWorkspace } from './workspace.js';
+import type { StoryboardArtifact } from './artifacts.js';
+import type { VideoAnalyzeOutput } from './types.js';
+
+export interface VideoTemplate {
+  name: string;
+  sourceProject: string;
+  createdAt: string;
+  updatedAt: string;
+  summary: string;
+  pacing: VideoAnalyzeOutput['pacing'];
+  structure: VideoAnalyzeOutput['structure'];
+  motionClassification: VideoAnalyzeOutput['motionClassification'];
+  keep: string[];
+  change: string[];
+  reusableVariables: string[];
+  styleLayers?: string[];
+  beatCompression?: VideoAnalyzeOutput['beatCompression'];
+  technicalNotes?: string[];
+  dialogueNotes?: string[];
+  workflowChecklist?: string[];
+}
+
+export interface ClonePlan {
+  templateName: string;
+  projectSlug: string;
+  intent: string;
+  recommendedPacing: VideoAnalyzeOutput['pacing']['label'];
+  recommendedMotionMode: VideoAnalyzeOutput['motionClassification']['primaryMode'];
+  keepFromReference: string[];
+  adaptForIntent: string[];
+  reusableVariables: string[];
+  beats: string[];
+  styleLayers?: string[];
+  beatCompression?: VideoAnalyzeOutput['beatCompression'];
+  technicalNotes?: string[];
+  dialogueNotes?: string[];
+  workflowChecklist?: string[];
+  generatedAt: string;
+}
+
+export interface TemplateValidationIssue {
+  severity: 'error' | 'warning';
+  message: string;
+}
+
+export interface TemplateValidationResult {
+  templateName: string;
+  valid: boolean;
+  issues: TemplateValidationIssue[];
+}
+
+export function buildStoryboardFromClonePlan(
+  clonePlan: ClonePlan,
+  productionMode: 'storyboard' | 'director' = 'storyboard',
+): StoryboardArtifact {
+  return {
+    projectSlug: clonePlan.projectSlug,
+    productionMode,
+    scenes: clonePlan.beats.map((beat, sceneIndex) => ({
+      sceneIndex,
+      description: `${beat}: adapt this beat for "${clonePlan.intent}" while keeping ${clonePlan.keepFromReference.join(', ') || 'the reference energy'}.`,
+    })),
+  };
+}
+
+function defaultStyleLayers(analyze: VideoAnalyzeOutput): string[] {
+  return [
+    `pacing:${analyze.pacing.label}`,
+    `motion:${analyze.motionClassification.primaryMode}`,
+    ...(analyze.structure.hook ? ['hook-first'] : []),
+  ];
+}
+
+function defaultBeatCompression(analyze: VideoAnalyzeOutput): NonNullable<VideoAnalyzeOutput['beatCompression']> {
+  const targetDurationSeconds = Math.min(Math.max(analyze.reference.durationSeconds ?? 15, 6), 30);
+  return {
+    targetDurationSeconds,
+    maxBeats: Math.min(Math.max(analyze.structure.beats.length, 3), 6),
+    dialogueWordBudget: Math.floor(targetDurationSeconds * 2.5),
+    notes: ['Keep each beat short enough to fit a compact social clip.'],
+  };
+}
+
+function defaultWorkflowChecklist(template: Pick<VideoTemplate, 'keep' | 'change' | 'reusableVariables'>): string[] {
+  return [
+    'Preserve the reusable hook and beat order, not brand-specific wording.',
+    'Replace product, audience, proof, and offer variables for the new intent.',
+    template.keep.length > 0
+      ? `Keep reference traits: ${template.keep.join(', ')}.`
+      : 'Keep only the reference pacing and structural energy.',
+    template.change.length > 0
+      ? `Change for new intent: ${template.change.join(', ')}.`
+      : 'Change all claims, names, and brand-specific details.',
+    template.reusableVariables.length > 0
+      ? `Fill variables: ${template.reusableVariables.join(', ')}.`
+      : 'Define product, audience, offer, proof, objection, and CTA variables.',
+  ];
+}
+
+function templatesDir(root: string): string {
+  return join(resolve(root), 'templates', 'video');
+}
+
+function templatePath(root: string, name: string): string {
+  return join(templatesDir(root), `${name}.json`);
+}
+
+export async function saveTemplateFromAnalyzeOutput(input: {
+  root?: string;
+  projectSlug: string;
+  templateName: string;
+}): Promise<{ outputPath: string; template: VideoTemplate }> {
+  const root = input.root ?? process.cwd();
+  const workspace = resolveProjectWorkspace(input.projectSlug, root);
+  const analyzePath = artifactPathFor(workspace, 'analyze-output');
+  if (!existsSync(analyzePath)) {
+    throw new Error(`Analyze artifact not found for project "${input.projectSlug}".`);
+  }
+
+  const analyze = JSON.parse(await readFile(analyzePath, 'utf-8')) as VideoAnalyzeOutput;
+  const now = new Date().toISOString();
+  const template: VideoTemplate = {
+    name: input.templateName,
+    sourceProject: input.projectSlug,
+    createdAt: now,
+    updatedAt: now,
+    summary: analyze.reference.title ?? analyze.reference.source,
+    pacing: analyze.pacing,
+    structure: analyze.structure,
+    motionClassification: analyze.motionClassification,
+    keep: analyze.keep,
+    change: analyze.change,
+    reusableVariables: analyze.reusableVariables,
+    styleLayers: analyze.styleLayers ?? defaultStyleLayers(analyze),
+    beatCompression: analyze.beatCompression ?? defaultBeatCompression(analyze),
+    technicalNotes: analyze.technicalNotes ?? [],
+    dialogueNotes: analyze.dialogueNotes ?? [],
+  };
+  template.workflowChecklist = defaultWorkflowChecklist(template);
+
+  const dir = templatesDir(root);
+  await mkdir(dir, { recursive: true });
+  const outputPath = templatePath(root, input.templateName);
+  await writeFile(outputPath, `${JSON.stringify(template, null, 2)}\n`);
+  return { outputPath, template };
+}
+
+export async function listTemplates(root = process.cwd()): Promise<string[]> {
+  const dir = templatesDir(root);
+  if (!existsSync(dir)) return [];
+  return (await readdir(dir))
+    .filter((entry) => entry.endsWith('.json'))
+    .map((entry) => entry.replace(/\.json$/, ''))
+    .sort();
+}
+
+export async function readTemplate(
+  name: string,
+  root = process.cwd(),
+): Promise<VideoTemplate | null> {
+  const path = templatePath(root, name);
+  if (!existsSync(path)) return null;
+  return JSON.parse(await readFile(path, 'utf-8')) as VideoTemplate;
+}
+
+export async function validateTemplate(
+  name: string,
+  root = process.cwd(),
+): Promise<TemplateValidationResult> {
+  const template = await readTemplate(name, root);
+  if (!template) {
+    throw new Error(`Template "${name}" not found.`);
+  }
+
+  const issues: TemplateValidationIssue[] = [];
+  if (!template.name.trim()) issues.push({ severity: 'error', message: 'Template missing name.' });
+  if (!template.sourceProject.trim()) issues.push({ severity: 'error', message: 'Template missing sourceProject.' });
+  if (!template.summary.trim()) issues.push({ severity: 'error', message: 'Template missing summary.' });
+  if (!['slow', 'medium', 'fast', 'mixed'].includes(template.pacing.label)) {
+    issues.push({ severity: 'error', message: 'Template has invalid pacing label.' });
+  }
+  if (!['motion-clips', 'animated-stills', 'mixed', 'unknown'].includes(template.motionClassification.primaryMode)) {
+    issues.push({ severity: 'error', message: 'Template has invalid motion classification.' });
+  }
+  if (!Array.isArray(template.structure.beats) || template.structure.beats.length === 0 || template.structure.beats.some((beat) => beat.trim() === '')) {
+    issues.push({ severity: 'error', message: 'Template must contain at least one non-empty beat.' });
+  }
+  if (!Array.isArray(template.keep)) issues.push({ severity: 'error', message: 'Template keep field must be an array.' });
+  if (!Array.isArray(template.change)) issues.push({ severity: 'error', message: 'Template change field must be an array.' });
+  if (!Array.isArray(template.reusableVariables)) issues.push({ severity: 'error', message: 'Template reusableVariables field must be an array.' });
+  if (template.styleLayers !== undefined && !Array.isArray(template.styleLayers)) {
+    issues.push({ severity: 'error', message: 'Template styleLayers field must be an array when present.' });
+  }
+  if (template.workflowChecklist !== undefined && !Array.isArray(template.workflowChecklist)) {
+    issues.push({ severity: 'error', message: 'Template workflowChecklist field must be an array when present.' });
+  }
+  if (!template.createdAt.trim()) issues.push({ severity: 'error', message: 'Template missing createdAt.' });
+  if (!template.updatedAt.trim()) issues.push({ severity: 'error', message: 'Template missing updatedAt.' });
+
+  return {
+    templateName: template.name,
+    valid: !issues.some((issue) => issue.severity === 'error'),
+    issues,
+  };
+}
+
+export async function buildClonePlan(input: {
+  root?: string;
+  templateName: string;
+  projectSlug: string;
+  intent: string;
+}): Promise<ClonePlan> {
+  const root = input.root ?? process.cwd();
+  const template = await readTemplate(input.templateName, root);
+  if (!template) {
+    throw new Error(`Template "${input.templateName}" not found.`);
+  }
+
+  return {
+    templateName: template.name,
+    projectSlug: input.projectSlug,
+    intent: input.intent,
+    recommendedPacing: template.pacing.label,
+    recommendedMotionMode: template.motionClassification.primaryMode,
+    keepFromReference: template.keep,
+    adaptForIntent: template.change,
+    reusableVariables: template.reusableVariables,
+    beats: template.structure.beats,
+    ...(template.styleLayers ? { styleLayers: template.styleLayers } : {}),
+    ...(template.beatCompression ? { beatCompression: template.beatCompression } : {}),
+    ...(template.technicalNotes ? { technicalNotes: template.technicalNotes } : {}),
+    ...(template.dialogueNotes ? { dialogueNotes: template.dialogueNotes } : {}),
+    workflowChecklist: template.workflowChecklist ?? defaultWorkflowChecklist(template),
+    generatedAt: new Date().toISOString(),
+  };
+}

package/src/video/timeline.ts

@@ -0,0 +1,32 @@
+import { listProjects } from './projects.js';
+import { readProjectEvents } from './events.js';
+import { resolveProjectWorkspace } from './workspace.js';
+
+export interface VideoTimelineEvent {
+  slug: string;
+  type: string;
+  recordedAt: string;
+  payload?: Record<string, unknown>;
+}
+
+export async function buildTimeline(
+  root = process.cwd(),
+): Promise<VideoTimelineEvent[]> {
+  const slugs = await listProjects(root);
+  const events: VideoTimelineEvent[] = [];
+
+  for (const slug of slugs) {
+    const workspace = resolveProjectWorkspace(slug, root);
+    const projectEvents = await readProjectEvents(workspace);
+    for (const event of projectEvents) {
+      events.push({
+        slug,
+        type: event.type,
+        recordedAt: event.recordedAt,
+        payload: event.payload,
+      });
+    }
+  }
+
+  return events.sort((left, right) => right.recordedAt.localeCompare(left.recordedAt));
+}

package/src/video/title-overlay.ts

@@ -0,0 +1,234 @@
+/**
+ * title-overlay.ts — music-video TITLE overlays (the "titles like you see in
+ * music videos" layer): a faded lower-third early in the song and/or a centred
+ * end card that holds to EOF. Works on ANY ffmpeg build and ANY script
+ * (Devanagari/Arabic) because the text is rasterized by Pillow + RAQM rather than
+ * ffmpeg `drawtext` (no libfreetype needed, complex scripts shaped correctly).
+ *
+ * Two halves mirror {@link ./assemble/text-card}: the PURE {@link buildTitleCards}
+ * turns parsed options + probed video dims/duration into the card SPECS (text →
+ * PNG) and their composite TIMINGS — fully unit-testable, no I/O. The thin
+ * {@link runTitleOverlay} probes the input, renders each spec to a PNG, then burns
+ * them on with {@link buildTitleCompositeArgs}. `--dry-run` returns the plan
+ * without rendering or spawning.
+ */
+import {
+  buildTitleCompositeArgs,
+  renderTextCard,
+  pillowAvailable,
+  type TextCardSpec,
+  type TitleCard,
+} from './assemble/text-card.js';
+import { probeMedia } from './final-media.js';
+import { runFfmpeg } from './assemble/ffmpeg.js';
+import { join } from 'node:path';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+
+/** Defaults tuned for a cinematic music-video look. */
+export const TITLE_DEFAULTS = {
+  titleColor: '#f5f0e6',
+  subColor: '#cbb89a',
+  accentColor: '#d4622a',
+  titleFont: 'didot',
+  bodyFont: 'avenir',
+  lowerThirdStartSec: 4,
+  lowerThirdEndSec: 11,
+  fadeSec: 0.6,
+  endCardSec: 4.5,
+} as const;
+
+export interface TitleOverlayOptions {
+  /** Lower-third lines (first = title-weight, rest = body). Empty = no lower third. */
+  lowerThird?: string[];
+  lowerThirdStartSec?: number;
+  lowerThirdEndSec?: number;
+  /** End-card lines (centred). Empty = no end card. */
+  endCard?: string[];
+  /** How long before EOF the end card starts; it holds to the end with no fade-out. */
+  endCardSec?: number;
+  /** Font alias or absolute path for the first/title line. */
+  titleFont?: string;
+  /** Font alias or absolute path for body/subtitle lines. */
+  bodyFont?: string;
+  titleColor?: string;
+  subColor?: string;
+  accentColor?: string;
+  /** Drop the ember accent rule on the lower third. */
+  noAccent?: boolean;
+}
+
+export interface TitleCardsPlan {
+  specs: TextCardSpec[];
+  /** Composite timings, parallel to `specs` (pngPath filled at render time). */
+  timings: Array<Omit<TitleCard, 'pngPath'>>;
+}
+
+function scaled(value: number, height: number, ref = 1080): number {
+  return Math.max(1, Math.round((value * height) / ref));
+}
+
+/**
+ * Build the title-card specs + composite timings for a `width`×`height` video of
+ * `durationSec`. PURE — no I/O. Sizes type relative to the frame height so a 720p
+ * and a 1080p master read the same. Throws if neither a lower third nor an end
+ * card is requested.
+ */
+export function buildTitleCards(
+  opts: TitleOverlayOptions,
+  width: number,
+  height: number,
+  durationSec: number,
+): TitleCardsPlan {
+  const hasLT = (opts.lowerThird ?? []).filter((l) => l.trim()).length > 0;
+  const hasEnd = (opts.endCard ?? []).filter((l) => l.trim()).length > 0;
+  if (!hasLT && !hasEnd) {
+    throw new Error('buildTitleCards: at least one of lowerThird / endCard is required.');
+  }
+  const titleFont = opts.titleFont ?? TITLE_DEFAULTS.titleFont;
+  const bodyFont = opts.bodyFont ?? TITLE_DEFAULTS.bodyFont;
+  const titleColor = opts.titleColor ?? TITLE_DEFAULTS.titleColor;
+  const subColor = opts.subColor ?? TITLE_DEFAULTS.subColor;
+
+  const specs: TextCardSpec[] = [];
+  const timings: Array<Omit<TitleCard, 'pngPath'>> = [];
+
+  if (hasLT) {
+    const lines = opts.lowerThird!.filter((l) => l.trim());
+    const start = opts.lowerThirdStartSec ?? TITLE_DEFAULTS.lowerThirdStartSec;
+    const end = Math.min(opts.lowerThirdEndSec ?? TITLE_DEFAULTS.lowerThirdEndSec, durationSec);
+    // An empty/out-of-range window silently produced an output with NO title
+    // (the drawtext enable window was never true) — fail at plan time instead.
+    if (start >= durationSec) {
+      throw new Error(
+        `buildTitleCards: lower-third starts at ${start}s but the video is only ${durationSec.toFixed(2)}s — the title would never appear.`,
+      );
+    }
+    if (end <= start) {
+      throw new Error(
+        `buildTitleCards: lower-third window is empty (start ${start}s, end ${end}s after clamping to the ${durationSec.toFixed(2)}s video).`,
+      );
+    }
+    specs.push({
+      width,
+      height,
+      outputPath: '', // filled by runTitleOverlay
+      anchor: 'bottom-left',
+      lines: lines.map((text, i) => ({
+        text,
+        font: i === 0 ? titleFont : bodyFont,
+        size: i === 0 ? scaled(64, height) : scaled(40, height),
+        color: i === 0 ? titleColor : subColor,
+        ...(i === 0 ? { tracking: scaled(2, height) } : {}),
+      })),
+      shadow: true,
+      ...(opts.noAccent
+        ? {}
+        : { accentRule: { color: opts.accentColor ?? TITLE_DEFAULTS.accentColor, width: scaled(7, height) } }),
+    });
+    timings.push({ startSec: start, endSec: end, fadeInSec: TITLE_DEFAULTS.fadeSec, fadeOutSec: TITLE_DEFAULTS.fadeSec });
+  }
+
+  if (hasEnd) {
+    const lines = opts.endCard!.filter((l) => l.trim());
+    const hold = opts.endCardSec ?? TITLE_DEFAULTS.endCardSec;
+    const start = Math.max(0, durationSec - hold);
+    specs.push({
+      width,
+      height,
+      outputPath: '',
+      anchor: 'center',
+      // Drop the end card into the lower third (not dead center) so it sits
+      // UNDERNEATH a centered subject — e.g. a product whose own wordmark is
+      // mid-frame — instead of colliding with it.
+      y: Math.round(height * 0.72),
+      lines: lines.map((text, i) => ({
+        text,
+        font: i === 0 ? titleFont : bodyFont,
+        // Smaller than before (was 88/44): a held end card over busy product
+        // footage reads better small + low, and the fit-to-width guard keeps a
+        // long tagline from overflowing regardless.
+        size: i === 0 ? scaled(52, height) : scaled(30, height),
+        color: i === 0 ? titleColor : subColor,
+        ...(i === 0 ? { tracking: scaled(2, height) } : {}),
+      })),
+      shadow: true,
+    });
+    // hold to EOF: fade in, no fade-out.
+    timings.push({ startSec: start, endSec: durationSec, fadeInSec: TITLE_DEFAULTS.fadeSec, fadeOutSec: 0 });
+  }
+
+  return { specs, timings };
+}
+
+export interface RunTitleOverlayResult {
+  output: string;
+  width: number;
+  height: number;
+  durationSec: number;
+  cards: Array<{ kind: 'lower-third' | 'end-card'; lines: string[]; startSec: number; endSec: number }>;
+  dryRun: boolean;
+}
+
+export interface RunTitleOverlayOptions extends TitleOverlayOptions {
+  input: string;
+  output: string;
+  dryRun?: boolean;
+  python?: string;
+  ffmpegBin?: string;
+}
+
+/**
+ * Probe the input, render the title PNGs (Pillow + RAQM), and burn them on. On
+ * `dryRun`, returns the planned cards without rendering or spawning. Throws a
+ * clear error if Pillow/RAQM is unavailable on a real run (the renderer dep).
+ */
+export async function runTitleOverlay(opts: RunTitleOverlayOptions): Promise<RunTitleOverlayResult> {
+  const probe = await probeMedia(opts.input);
+  const { width, height } = probe;
+  // Cards are sized/positioned off the real canvas — silently composing for an
+  // assumed 1280x720 would misplace and mis-scale every title on other inputs.
+  if (!width || !height) {
+    throw new Error(`runTitleOverlay: could not determine the dimensions of ${opts.input}.`);
+  }
+  const durationSec = probe.durationSeconds ?? 0;
+  if (!durationSec) {
+    throw new Error(`runTitleOverlay: could not determine the duration of ${opts.input}.`);
+  }
+
+  const plan = buildTitleCards(opts, width, height, durationSec);
+  const describe = (i: number): RunTitleOverlayResult['cards'][number] => ({
+    kind: plan.specs[i].anchor === 'center' ? 'end-card' : 'lower-third',
+    lines: plan.specs[i].lines.map((l) => l.text),
+    startSec: plan.timings[i].startSec,
+    endSec: plan.timings[i].endSec,
+  });
+  const cards = plan.specs.map((_, i) => describe(i));
+
+  if (opts.dryRun) {
+    return { output: opts.output, width, height, durationSec, cards, dryRun: true };
+  }
+
+  if (!(await pillowAvailable({ ...(opts.python ? { python: opts.python } : {}) }))) {
+    throw new Error(
+      'runTitleOverlay: python3 with Pillow + RAQM is required to rasterize titles ' +
+        '(pip install "Pillow[raqm]"). Use --dry-run to plan without rendering.',
+    );
+  }
+
+  const dir = await mkdtemp(join(tmpdir(), 'vclaw-titles-'));
+  try {
+    const titleCards: TitleCard[] = [];
+    for (let i = 0; i < plan.specs.length; i++) {
+      const pngPath = join(dir, `card-${i}.png`);
+      await renderTextCard({ ...plan.specs[i], outputPath: pngPath }, { ...(opts.python ? { python: opts.python } : {}) });
+      titleCards.push({ ...plan.timings[i], pngPath });
+    }
+    const args = buildTitleCompositeArgs({ baseVideo: opts.input, cards: titleCards, outputPath: opts.output });
+    await runFfmpeg(args, { ...(opts.ffmpegBin ? { ffmpegBin: opts.ffmpegBin } : {}) });
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+
+  return { output: opts.output, width, height, durationSec, cards, dryRun: false };
+}