videoclaw 3.0.0-alpha.1

package/src/video/reference-sheets.ts

@@ -0,0 +1,224 @@
+import type {
+  ReferenceEntry,
+  ReferenceRole,
+  ReferenceSheet,
+  ReferenceSheetType,
+  ReferenceSheetsArtifact,
+} from './types.js';
+
+export const ROLE_VOCABULARY: Record<ReferenceSheetType, readonly ReferenceRole[]> = {
+  'identity': ['identity', 'wardrobe', 'silhouette', 'age-reference'],
+  'outfit-material': [
+    'outfit', 'material', 'accessory', 'texture',
+    'product-hero', 'product-variant', 'product-in-use', 'packaging',
+  ],
+  'environment': ['location', 'set-dressing', 'weather', 'time-of-day'],
+  'motion-camera': ['motion-rhythm', 'camera-behavior', 'blocking', 'shot-framing'],
+  'palette-mood': ['palette', 'composition', 'mood', 'lighting-reference'],
+};
+
+export const REFERENCE_SHEET_TYPES: readonly ReferenceSheetType[] = [
+  'identity',
+  'outfit-material',
+  'environment',
+  'motion-camera',
+  'palette-mood',
+];
+
+export function isRoleValidForType(role: ReferenceRole, type: ReferenceSheetType): boolean {
+  return (ROLE_VOCABULARY[type] as readonly ReferenceRole[]).includes(role);
+}
+
+export interface ValidationResult {
+  ok: boolean;
+  errors: string[];
+}
+
+export function validateSheet(sheet: ReferenceSheet): ValidationResult {
+  const errors: string[] = [];
+
+  if (!REFERENCE_SHEET_TYPES.includes(sheet.type)) {
+    errors.push(`unknown-sheet-type: ${sheet.type}`);
+  }
+
+  for (const [i, ref] of sheet.references.entries()) {
+    if (!ref.role) {
+      errors.push(`unassigned-role: sheet=${sheet.id} ref-index=${i}`);
+      continue;
+    }
+    if (!isRoleValidForType(ref.role, sheet.type)) {
+      errors.push(`role-vocabulary-violation: sheet=${sheet.id} role=${ref.role} type=${sheet.type}`);
+    }
+  }
+
+  for (const sceneIndex of sheet.bindings.sceneIndices) {
+    if (!Number.isInteger(sceneIndex) || sceneIndex < 0) {
+      errors.push(`invalid-scene-index: sheet=${sheet.id} sceneIndex=${sceneIndex}`);
+    }
+  }
+
+  return { ok: errors.length === 0, errors };
+}
+
+export function validateArtifact(artifact: ReferenceSheetsArtifact): ValidationResult {
+  const errors: string[] = [];
+  const seenIds = new Set<string>();
+  for (const sheet of artifact.sheets) {
+    if (seenIds.has(sheet.id)) {
+      errors.push(`duplicate-sheet-id: ${sheet.id}`);
+    }
+    seenIds.add(sheet.id);
+    const sheetResult = validateSheet(sheet);
+    errors.push(...sheetResult.errors);
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+export interface CreateSheetInput {
+  type: ReferenceSheetType;
+  name: string;
+  description?: string;
+  characterName?: string;
+  id?: string;
+  existingIds: string[];
+  now?: Date;
+}
+
+export function createSheet(input: CreateSheetInput): ReferenceSheet {
+  const now = (input.now ?? new Date()).toISOString();
+  const id = input.id ?? nextSheetId(input.existingIds);
+  const sheet: ReferenceSheet = {
+    id,
+    type: input.type,
+    name: input.name,
+    references: [],
+    bindings: { sceneIndices: [] },
+    createdAt: now,
+    updatedAt: now,
+  };
+  if (input.description !== undefined) sheet.description = input.description;
+  if (input.characterName !== undefined) sheet.characterName = input.characterName;
+  return sheet;
+}
+
+function nextSheetId(existing: string[]): string {
+  const used = new Set(existing);
+  for (let n = 1; n < 10_000; n++) {
+    const candidate = `sheet-${String(n).padStart(3, '0')}`;
+    if (!used.has(candidate)) return candidate;
+  }
+  throw new Error('ran out of sheet ids');
+}
+
+export function addReferenceToSheet(
+  sheet: ReferenceSheet,
+  entry: ReferenceEntry,
+  now: Date = new Date(),
+): ReferenceSheet {
+  return {
+    ...sheet,
+    references: [...sheet.references, entry],
+    updatedAt: now.toISOString(),
+  };
+}
+
+export function bindSheetToScenes(
+  sheet: ReferenceSheet,
+  sceneIndices: number[],
+  now: Date = new Date(),
+): ReferenceSheet {
+  const merged = Array.from(new Set([...sheet.bindings.sceneIndices, ...sceneIndices]))
+    .sort((a, b) => a - b);
+  return {
+    ...sheet,
+    bindings: { sceneIndices: merged },
+    updatedAt: now.toISOString(),
+  };
+}
+
+export function findSheet(
+  artifact: ReferenceSheetsArtifact,
+  id: string,
+): ReferenceSheet | undefined {
+  return artifact.sheets.find((s) => s.id === id);
+}
+
+export function removeSheet(
+  artifact: ReferenceSheetsArtifact,
+  id: string,
+): ReferenceSheetsArtifact {
+  return {
+    ...artifact,
+    sheets: artifact.sheets.filter((s) => s.id !== id),
+  };
+}
+
+export function upsertSheet(
+  artifact: ReferenceSheetsArtifact,
+  sheet: ReferenceSheet,
+): ReferenceSheetsArtifact {
+  const idx = artifact.sheets.findIndex((s) => s.id === sheet.id);
+  const next = [...artifact.sheets];
+  if (idx >= 0) next[idx] = sheet;
+  else next.push(sheet);
+  return { ...artifact, sheets: next };
+}
+
+export interface RoleCollision {
+  sceneIndex: number;
+  role: ReferenceRole;
+  sheetIds: string[];
+}
+
+export function findRoleCollisions(artifact: ReferenceSheetsArtifact): RoleCollision[] {
+  const byScene = new Map<number, Map<ReferenceRole, string[]>>();
+  for (const sheet of artifact.sheets) {
+    for (const sceneIndex of sheet.bindings.sceneIndices) {
+      const rolesForScene = byScene.get(sceneIndex) ?? new Map<ReferenceRole, string[]>();
+      for (const ref of sheet.references) {
+        const ids = rolesForScene.get(ref.role) ?? [];
+        if (!ids.includes(sheet.id)) ids.push(sheet.id);
+        rolesForScene.set(ref.role, ids);
+      }
+      byScene.set(sceneIndex, rolesForScene);
+    }
+  }
+  const collisions: RoleCollision[] = [];
+  for (const [sceneIndex, roles] of byScene) {
+    for (const [role, ids] of roles) {
+      if (ids.length > 1) collisions.push({ sceneIndex, role, sheetIds: ids });
+    }
+  }
+  return collisions;
+}
+
+export interface ArtifactSummary {
+  count: number;
+  byType: Partial<Record<ReferenceSheetType, number>>;
+  boundSceneCount: number;
+  unboundSheetIds: string[];
+}
+
+export function summarizeArtifact(artifact: ReferenceSheetsArtifact): ArtifactSummary {
+  const byType: Partial<Record<ReferenceSheetType, number>> = {};
+  const boundScenes = new Set<number>();
+  const unbound: string[] = [];
+  for (const sheet of artifact.sheets) {
+    byType[sheet.type] = (byType[sheet.type] ?? 0) + 1;
+    if (sheet.bindings.sceneIndices.length === 0) unbound.push(sheet.id);
+    for (const i of sheet.bindings.sceneIndices) boundScenes.add(i);
+  }
+  return {
+    count: artifact.sheets.length,
+    byType,
+    boundSceneCount: boundScenes.size,
+    unboundSheetIds: unbound,
+  };
+}
+
+export function sheetsCoveringScene(
+  artifact: ReferenceSheetsArtifact,
+  sceneIndex: number,
+): ReferenceSheet[] {
+  return artifact.sheets.filter((s) => s.bindings.sceneIndices.includes(sceneIndex));
+}

package/src/video/remix-narrated.ts

@@ -0,0 +1,92 @@
+import { mkdir, mkdtemp, readdir, rm, stat } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { execFile } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+import { ensureProjectWorkspace } from './workspace.js';
+
+const execFileAsync = promisify(execFile);
+
+export interface NarratedRemixResult {
+  projectSlug: string;
+  projectDir: string;
+  inputFiles: string[];
+  outputPath: string;
+  durationSeconds?: number;
+}
+
+async function readNarratedClipPaths(videosDir: string): Promise<string[]> {
+  if (!existsSync(videosDir)) {
+    throw new Error(`No videos directory found at ${videosDir}`);
+  }
+  const entries = await readdir(videosDir, { withFileTypes: true });
+  return entries
+    .filter((entry) => entry.isFile() && entry.name.includes('narrated') && entry.name.endsWith('.mp4'))
+    .map((entry) => join(videosDir, entry.name))
+    .sort();
+}
+
+async function probeDurationSeconds(path: string): Promise<number | undefined> {
+  try {
+    const { stdout } = await execFileAsync('ffprobe', [
+      '-v', 'error',
+      '-show_entries', 'format=duration',
+      '-of', 'default=noprint_wrappers=1:nokey=1',
+      path,
+    ], { encoding: 'utf-8' });
+    const parsed = Number(stdout.trim());
+    return Number.isFinite(parsed) ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export async function remixNarratedProject(
+  projectSlug: string,
+  options: {
+    root?: string;
+    outputPath?: string;
+  } = {},
+): Promise<NarratedRemixResult> {
+  const root = options.root ?? process.cwd();
+  const workspace = await ensureProjectWorkspace(projectSlug, root);
+  const videosDir = join(workspace.projectDir, 'videos');
+  const finalDir = join(workspace.projectDir, 'final');
+  const inputFiles = await readNarratedClipPaths(videosDir);
+  if (inputFiles.length === 0) {
+    throw new Error(`No narrated mp4 clips found in ${videosDir}`);
+  }
+
+  const outputPath = options.outputPath ?? join(finalDir, 'narrated-fixed.mp4');
+  await mkdir(finalDir, { recursive: true });
+  const scratchDir = await mkdtemp(join(tmpdir(), 'vclaw-remix-narrated-'));
+  const concatPath = join(scratchDir, 'concat.txt');
+
+  try {
+    const concatContent = inputFiles
+      .map((path) => `file '${path.replaceAll("'", "'\\''")}'`)
+      .join('\n');
+    await import('node:fs/promises').then(({ writeFile }) => writeFile(concatPath, `${concatContent}\n`));
+
+    await execFileAsync('ffmpeg', [
+      '-y',
+      '-f', 'concat',
+      '-safe', '0',
+      '-i', concatPath,
+      '-c', 'copy',
+      outputPath,
+    ], { encoding: 'utf-8' });
+
+    const durationSeconds = await probeDurationSeconds(outputPath);
+    return {
+      projectSlug,
+      projectDir: workspace.projectDir,
+      inputFiles,
+      outputPath,
+      ...(durationSeconds !== undefined ? { durationSeconds } : {}),
+    };
+  } finally {
+    await rm(scratchDir, { recursive: true, force: true });
+  }
+}

package/src/video/report-diff.ts

@@ -0,0 +1,299 @@
+import { readFile } from 'node:fs/promises';
+import { listPortfolioReportSnapshots } from './report-history.js';
+import type { VideoPortfolioReport } from './report.js';
+
+export interface PortfolioReportDiff {
+  generatedAt: string;
+  root: string;
+  from?: string;
+  to?: string;
+  summary: {
+    totalProjectsDelta: number;
+    completedProjectsDelta: number;
+    completionRateDelta: number;
+    averageScoreDelta: number;
+    warningProjectsDelta: number;
+    blockedProjectsDelta: number;
+    needsReviewProjectsDelta: number;
+    legacyImportedProjectsDelta: number;
+    legacyQueueDriftProjectsDelta: number;
+    legacyNestedOutputProjectsDelta: number;
+  };
+  projectChanges: {
+    added: string[];
+    removed: string[];
+    statusChanged: Array<{
+      slug: string;
+      from: string;
+      to: string;
+    }>;
+    stageChanged: Array<{
+      slug: string;
+      from: string | null;
+      to: string | null;
+    }>;
+    platformChanged: Array<{
+      slug: string;
+      from: string | null;
+      to: string | null;
+    }>;
+    targetRuntimeChanged: Array<{
+      slug: string;
+      from: number | null;
+      to: number | null;
+    }>;
+    clipDurationChanged: Array<{
+      slug: string;
+      from: number | null;
+      to: number | null;
+    }>;
+    executionProfileChanged: Array<{
+      slug: string;
+      from: {
+        aspectRatio?: string;
+        quality?: string;
+        resolution?: string;
+        generateAudio?: boolean;
+        outputCount?: number;
+      } | null;
+      to: {
+        aspectRatio?: string;
+        quality?: string;
+        resolution?: string;
+        generateAudio?: boolean;
+        outputCount?: number;
+      } | null;
+    }>;
+    legacyImportChanged: Array<{
+      slug: string;
+      from: {
+        manifestPresent?: boolean;
+        queueFilePresent?: boolean;
+        queueStatusMismatch?: boolean;
+        nestedOutputRootDetected?: boolean;
+      } | null;
+      to: {
+        manifestPresent?: boolean;
+        queueFilePresent?: boolean;
+        queueStatusMismatch?: boolean;
+        nestedOutputRootDetected?: boolean;
+      } | null;
+    }>;
+    reviewStateChanged: Array<{
+      slug: string;
+      from: string | null;
+      to: string | null;
+    }>;
+  };
+}
+
+async function readReport(path: string): Promise<VideoPortfolioReport> {
+  return JSON.parse(await readFile(path, 'utf-8')) as VideoPortfolioReport;
+}
+
+function normalizeExecutionProfile(
+  profile: {
+    aspectRatio?: string;
+    quality?: string;
+    resolution?: string;
+    generateAudio?: boolean;
+    outputCount?: number;
+  } | null | undefined,
+): {
+  aspectRatio?: string;
+  quality?: string;
+  resolution?: string;
+  generateAudio?: boolean;
+  outputCount?: number;
+} | null {
+  if (!profile) return null;
+  const normalized = {
+    ...(profile.aspectRatio ? { aspectRatio: profile.aspectRatio } : {}),
+    ...(profile.quality ? { quality: profile.quality } : {}),
+    ...(profile.resolution ? { resolution: profile.resolution } : {}),
+    ...(typeof profile.generateAudio === 'boolean' ? { generateAudio: profile.generateAudio } : {}),
+    ...(typeof profile.outputCount === 'number' ? { outputCount: profile.outputCount } : {}),
+  };
+  return Object.keys(normalized).length > 0 ? normalized : null;
+}
+
+function normalizeLegacyImportSummary(
+  summary: {
+    manifestPresent?: boolean;
+    queueFilePresent?: boolean;
+    queueStatusMismatch?: boolean;
+    nestedOutputRootDetected?: boolean;
+  } | null | undefined,
+): {
+  manifestPresent?: boolean;
+  queueFilePresent?: boolean;
+  queueStatusMismatch?: boolean;
+  nestedOutputRootDetected?: boolean;
+} | null {
+  if (!summary) return null;
+  const normalized = {
+    ...(typeof summary.manifestPresent === 'boolean' ? { manifestPresent: summary.manifestPresent } : {}),
+    ...(typeof summary.queueFilePresent === 'boolean' ? { queueFilePresent: summary.queueFilePresent } : {}),
+    ...(typeof summary.queueStatusMismatch === 'boolean' ? { queueStatusMismatch: summary.queueStatusMismatch } : {}),
+    ...(typeof summary.nestedOutputRootDetected === 'boolean' ? { nestedOutputRootDetected: summary.nestedOutputRootDetected } : {}),
+  };
+  return Object.keys(normalized).length > 0 ? normalized : null;
+}
+
+export async function buildPortfolioReportDiff(
+  root = process.cwd(),
+  options: {
+    fromPath?: string;
+    toPath?: string;
+  } = {},
+): Promise<PortfolioReportDiff> {
+  let fromPath = options.fromPath;
+  let toPath = options.toPath;
+
+  if (!fromPath || !toPath) {
+    const snapshots = await listPortfolioReportSnapshots(root);
+    if (snapshots.length < 2) {
+      return {
+        generatedAt: new Date().toISOString(),
+        root,
+        summary: {
+          totalProjectsDelta: 0,
+          completedProjectsDelta: 0,
+          completionRateDelta: 0,
+          averageScoreDelta: 0,
+          warningProjectsDelta: 0,
+          blockedProjectsDelta: 0,
+          needsReviewProjectsDelta: 0,
+          legacyImportedProjectsDelta: 0,
+          legacyQueueDriftProjectsDelta: 0,
+          legacyNestedOutputProjectsDelta: 0,
+        },
+        projectChanges: {
+          added: [],
+          removed: [],
+          statusChanged: [],
+          stageChanged: [],
+          platformChanged: [],
+          targetRuntimeChanged: [],
+          clipDurationChanged: [],
+          executionProfileChanged: [],
+          legacyImportChanged: [],
+          reviewStateChanged: [],
+        },
+      };
+    }
+    fromPath = snapshots[snapshots.length - 2]!.path;
+    toPath = snapshots[snapshots.length - 1]!.path;
+  }
+
+  const [from, to] = await Promise.all([readReport(fromPath), readReport(toPath)]);
+  const fromProjects = new Map(from.index.projects.map((project) => [project.slug, project]));
+  const toProjects = new Map(to.index.projects.map((project) => [project.slug, project]));
+
+  const added = [...toProjects.keys()].filter((slug) => !fromProjects.has(slug)).sort();
+  const removed = [...fromProjects.keys()].filter((slug) => !toProjects.has(slug)).sort();
+  const statusChanged: PortfolioReportDiff['projectChanges']['statusChanged'] = [];
+  const stageChanged: PortfolioReportDiff['projectChanges']['stageChanged'] = [];
+  const platformChanged: PortfolioReportDiff['projectChanges']['platformChanged'] = [];
+  const targetRuntimeChanged: PortfolioReportDiff['projectChanges']['targetRuntimeChanged'] = [];
+  const clipDurationChanged: PortfolioReportDiff['projectChanges']['clipDurationChanged'] = [];
+  const executionProfileChanged: PortfolioReportDiff['projectChanges']['executionProfileChanged'] = [];
+  const legacyImportChanged: PortfolioReportDiff['projectChanges']['legacyImportChanged'] = [];
+  const reviewStateChanged: PortfolioReportDiff['projectChanges']['reviewStateChanged'] = [];
+
+  for (const [slug, toProject] of toProjects) {
+    const fromProject = fromProjects.get(slug);
+    if (!fromProject) continue;
+    if (fromProject.opsStatus !== toProject.opsStatus) {
+      statusChanged.push({
+        slug,
+        from: fromProject.opsStatus,
+        to: toProject.opsStatus,
+      });
+    }
+    if (fromProject.nextStage !== toProject.nextStage) {
+      stageChanged.push({
+        slug,
+        from: fromProject.nextStage,
+        to: toProject.nextStage,
+      });
+    }
+    if ((fromProject.platform ?? null) !== (toProject.platform ?? null)) {
+      platformChanged.push({
+        slug,
+        from: fromProject.platform ?? null,
+        to: toProject.platform ?? null,
+      });
+    }
+    if ((fromProject.targetRuntimeSeconds ?? null) !== (toProject.targetRuntimeSeconds ?? null)) {
+      targetRuntimeChanged.push({
+        slug,
+        from: fromProject.targetRuntimeSeconds ?? null,
+        to: toProject.targetRuntimeSeconds ?? null,
+      });
+    }
+    if ((fromProject.clipDurationSeconds ?? null) !== (toProject.clipDurationSeconds ?? null)) {
+      clipDurationChanged.push({
+        slug,
+        from: fromProject.clipDurationSeconds ?? null,
+        to: toProject.clipDurationSeconds ?? null,
+      });
+    }
+    const fromExecutionProfile = normalizeExecutionProfile(fromProject.executionProfile ?? null);
+    const toExecutionProfile = normalizeExecutionProfile(toProject.executionProfile ?? null);
+    if (JSON.stringify(fromExecutionProfile) !== JSON.stringify(toExecutionProfile)) {
+      executionProfileChanged.push({
+        slug,
+        from: fromExecutionProfile,
+        to: toExecutionProfile,
+      });
+    }
+    const fromLegacyImport = normalizeLegacyImportSummary(fromProject.legacyImportSummary ?? null);
+    const toLegacyImport = normalizeLegacyImportSummary(toProject.legacyImportSummary ?? null);
+    if (JSON.stringify(fromLegacyImport) !== JSON.stringify(toLegacyImport)) {
+      legacyImportChanged.push({
+        slug,
+        from: fromLegacyImport,
+        to: toLegacyImport,
+      });
+    }
+    if ((fromProject.storyboardReviewState ?? null) !== (toProject.storyboardReviewState ?? null)) {
+      reviewStateChanged.push({
+        slug,
+        from: fromProject.storyboardReviewState ?? null,
+        to: toProject.storyboardReviewState ?? null,
+      });
+    }
+  }
+
+  return {
+    generatedAt: new Date().toISOString(),
+    root,
+    from: from.generatedAt,
+    to: to.generatedAt,
+    summary: {
+      totalProjectsDelta: to.metrics.totalProjects - from.metrics.totalProjects,
+      completedProjectsDelta: to.metrics.completedProjects - from.metrics.completedProjects,
+      completionRateDelta: to.metrics.completionRate - from.metrics.completionRate,
+      averageScoreDelta: to.metrics.averageScore - from.metrics.averageScore,
+      warningProjectsDelta: to.health.warningProjects - from.health.warningProjects,
+      blockedProjectsDelta: to.metrics.byOpsStatus.blocked - from.metrics.byOpsStatus.blocked,
+      needsReviewProjectsDelta: to.metrics.byOpsStatus['needs-review'] - from.metrics.byOpsStatus['needs-review'],
+      legacyImportedProjectsDelta: to.metrics.legacyImportedProjects - from.metrics.legacyImportedProjects,
+      legacyQueueDriftProjectsDelta: to.metrics.legacyQueueDriftProjects - from.metrics.legacyQueueDriftProjects,
+      legacyNestedOutputProjectsDelta: to.metrics.legacyNestedOutputProjects - from.metrics.legacyNestedOutputProjects,
+    },
+    projectChanges: {
+      added,
+      removed,
+      statusChanged,
+      stageChanged,
+      platformChanged,
+      targetRuntimeChanged,
+      clipDurationChanged,
+      executionProfileChanged,
+      legacyImportChanged,
+      reviewStateChanged,
+    },
+  };
+}