@flatkey-ai/cli 0.2.9 → 0.3.3

package/src/help.js

@@ -14,8 +14,9 @@ JSON mode:
 - ASCII animation and human logs are disabled.
 
 Commands:
-- flatkey image generate --prompt "<prompt>" --json [--model <model>] [--output image.png]
-- flatkey video generate --prompt "<prompt>" --json [--model seedance2] [--ratio 16:9] [--resolution 720p] [--output video.mp4]
+- flatkey image generate --prompt "<prompt>" --json [--model <model>] [--file <path>] [--image-url <url>] [--output image.png]
+- flatkey video generate --prompt "<prompt>" --json [--model seedance2] [--file <path>] [--image-url <url>] [--video-url <url>] [--ratio 16:9] [--resolution 720p] [--output video.mp4]
+- flatkey video copy --source input.mp4 --json [--model seedance2] [--frame-ratio 80] [--depth-resolution 480p] [--output video.mp4]
 - flatkey audio generate --prompt "<text>" --json [--voice-id <voice_id>] [--model eleven_multilingual_v2] [--output speech.mp3]
 - flatkey audio sfx --prompt "<sound>" --json [--duration <seconds>] [--output sfx.mp3]
 - flatkey audio music --prompt "<music prompt>" --json [--music-length-ms <ms>] [--output music.mp3]
@@ -54,6 +55,7 @@ Commands:
   image generate --prompt <txt>  Generate image
   image upload --file <path>     Upload local image and return a temporary URL
   video generate --prompt <txt>  Generate video
+  video copy --source <mp4>       Recreate a 5-15s video from Depth Anything V2 motion
   audio generate --prompt <txt>  Generate speech with ElevenLabs voices
   audio sfx --prompt <txt>       Generate sound effects
   audio music --prompt <txt>     Generate music
@@ -66,6 +68,9 @@ Commands:
 
 Global options:
   --json                         Print machine-readable JSON
+  --file <path>                   Attach local media input
+  --image-url <url>               Add remote image input, repeatable
+  --video-url <url>               Add remote video input, repeatable
   --output, -o <file>             Write generated output to a local file
   --verbose                      Print request/response logs to stderr
   --base-url <url>               Override Flatkey router URL
@@ -76,7 +81,7 @@ Environment:
   --console-url <url>            Override Flatkey console URL for login
 
 Video options:
-  --ratio <value>                 16:9, 9:16, 4:3, 3:4, 21:9, or 1:1
+  --ratio <value>                 16:9, 9:16, 4:3, 3:4, 21:9, 1:1, or adaptive
   --resolution <value>            480p, 720p, or 1080p
 `;
 }
@@ -163,6 +168,8 @@ Options:
   --size <size>                  Image size for OpenAI-style image models
   --quality <quality>             Image quality for supported models
   --n <count>                    Number of images for supported models
+  --file <path>                  Local image input, repeatable
+  --image-url <url>               Remote image input, repeatable
   --output, -o <file>             Write image file
   --json                         Print machine-readable JSON`,
   models: `Usage: flatkey models [options]
@@ -211,21 +218,34 @@ Aliases:
 
 Options:
   --json                         Print machine-readable JSON`,
-  video: `Usage: flatkey video generate --prompt <txt> [options]
+  video: `Usage: flatkey video <command> [options]
+
+Commands:
+  generate --prompt <txt>        Generate video
+  copy --source <mp4>            Recreate a 5-15s video from local depth motion
 
 Options:
   --model <model>                Model id, default seedance-2.0-pro
   --duration <seconds>            Video duration
+  --ratio <value>                 16:9, 9:16, 4:3, 3:4, 21:9, 1:1, or adaptive
+  --resolution <value>            480p, 720p, or 1080p
+  --generate-audio <true|false>   Generate audio, default true
+  --output, -o <file>             Write video file
+  --json                         Print machine-readable JSON`,
+  "video copy": `Usage: flatkey video copy --source <mp4> [options]
+
+Options:
+  --source <mp4>                  Local source video, must be 5-15 seconds
+  --frame-ratio <20..100>         Percent of frames kept for depth, default 100
+  --depth-resolution <value>      original, 480p, or 320p; default 480p
+  --depth-location <dir>          Directory for temporary depth video files
+  --keep-depth                    Keep generated depth video and reference frames
+  --model <model>                Model id, default seedance-2.0-pro
+  --prompt <txt>                 Prompt override for copy generation
+  --duration <seconds>            Must match source duration, 5-15 seconds
   --ratio <value>                 16:9, 9:16, 4:3, 3:4, 21:9, or 1:1
   --resolution <value>            480p, 720p, or 1080p
   --generate-audio <true|false>   Generate audio, default true
-  --image <file>                  Upload local reference image, repeatable
-  --image-url <url>               Add reference image URL, repeatable
-  --first-frame <file>            Upload local first frame image
-  --video-url <url>               Add reference video URL, repeatable
-  --first-frame-url <url>         Add first frame image URL
-  --last-frame <file>             Upload local last frame image
-  --last-frame-url <url>          Add last frame image URL
   --fps <fps>                    Frames per second
   --output, -o <file>             Write video file
   --json                         Print machine-readable JSON`,
@@ -239,8 +259,9 @@ Options:
   --generate-audio <true|false>   Generate audio, default true
   --image <file>                  Upload local reference image, repeatable
   --image-url <url>               Add reference image URL, repeatable
+  --file <path>                   Local image or video input, repeatable
   --first-frame <file>            Upload local first frame image
-  --video-url <url>               Add reference video URL, repeatable
+  --video-url <url>               Add reference video URL, repeatable; Seedance 2.5 supports up to 10
   --first-frame-url <url>         Add first frame image URL
   --last-frame <file>             Upload local last frame image
   --last-frame-url <url>          Add last frame image URL

package/src/video-copy.js

@@ -0,0 +1,251 @@
+import { access, mkdir, rm } from "node:fs/promises";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+import { spawn } from "node:child_process";
+
+export const MIN_COPY_DURATION_SECONDS = 5;
+export const MAX_COPY_DURATION_SECONDS = 15;
+export const DEFAULT_FRAME_RATIO = 100;
+export const DEFAULT_DEPTH_RESOLUTION = "480p";
+
+export async function prepareVideoCopy(options, deps = {}) {
+  const source = await expandHomePath(options.source);
+  const sourceInfo = await inspectVideo(source, deps);
+  const duration = sourceInfo.duration;
+  validateCopyDuration(duration, "source video");
+
+  const requestedDuration = options.duration === undefined
+    ? duration
+    : parseDuration(options.duration, "--duration");
+  validateCopyDuration(requestedDuration, "--duration");
+  if (Math.abs(requestedDuration - duration) > 0.01) {
+    throw new Error(
+      `--duration must match the source video duration (${formatSeconds(duration)}s); time stretching is not supported by video copy.`,
+    );
+  }
+
+  const depthRoot = await resolveDepthLocation(options.depth_location, deps);
+  const workDir = join(depthRoot, `copy-${Date.now()}-${Math.random().toString(16).slice(2)}`);
+  await mkdir(workDir, { recursive: true });
+  const depthPath = join(workDir, "depth.mp4");
+  let helperResult;
+  try {
+    helperResult = await runDepthHelper({
+      source,
+      output: depthPath,
+      frameRatio: parseFrameRatio(options.frame_ratio),
+      resolution: parseDepthResolution(options.depth_resolution),
+      model: options.depth_model,
+      workDir,
+    }, deps);
+  } catch (error) {
+    if (!options.keep_depth) await rm(workDir, { recursive: true, force: true });
+    throw error;
+  }
+  let referencePaths;
+  try {
+    referencePaths = await (deps.extractReferenceFrames ?? extractReferenceFrames)({
+      source: helperResult.output ?? depthPath,
+      outputDir: workDir,
+      duration,
+      ffmpegPath: deps.ffmpegPath,
+      env: deps.env,
+    }, deps);
+  } catch (error) {
+    if (!options.keep_depth) await rm(workDir, { recursive: true, force: true });
+    throw error;
+  }
+
+  return {
+    source,
+    depthPath: helperResult.output ?? depthPath,
+    referencePaths,
+    workDir,
+    duration: requestedDuration,
+    sourceInfo,
+    helper: helperResult,
+    cleanup: async () => {
+      if (!options.keep_depth) {
+        await rm(workDir, { recursive: true, force: true });
+      }
+    },
+  };
+}
+
+export function validateCopyDuration(value, label = "duration") {
+  const duration = parseDuration(value, label);
+  if (duration < MIN_COPY_DURATION_SECONDS || duration > MAX_COPY_DURATION_SECONDS) {
+    throw new Error(
+      `${label} must be between ${MIN_COPY_DURATION_SECONDS} and ${MAX_COPY_DURATION_SECONDS} seconds; received ${formatSeconds(duration)}s.`,
+    );
+  }
+  return duration;
+}
+
+export function parseDuration(value, label = "duration") {
+  const duration = Number(value);
+  if (!Number.isFinite(duration) || duration <= 0) {
+    throw new Error(`${label} must be a positive number of seconds.`);
+  }
+  return duration;
+}
+
+export function parseFrameRatio(value = DEFAULT_FRAME_RATIO) {
+  const ratio = Number(value);
+  if (!Number.isInteger(ratio) || ratio < 20 || ratio > 100) {
+    throw new Error("--frame-ratio must be an integer between 20 and 100.");
+  }
+  return ratio;
+}
+
+export function parseDepthResolution(value = DEFAULT_DEPTH_RESOLUTION) {
+  const normalized = String(value).toLowerCase();
+  if (normalized === "original" || normalized === "480" || normalized === "480p") return normalized === "original" ? "original" : "480p";
+  if (normalized === "320" || normalized === "320p") return "320p";
+  throw new Error("--depth-resolution must be original, 480p, or 320p.");
+}
+
+export async function resolveDepthLocation(value, deps = {}) {
+  const candidates = [
+    value,
+    deps.tmpdir,
+    tmpdir(),
+    join(homedir(), ".tmp"),
+    join(process.cwd(), ".flatkey-tmp"),
+  ].filter(Boolean);
+
+  let lastError;
+  for (const candidate of candidates) {
+    const expanded = await expandHomePath(candidate);
+    try {
+      await mkdir(expanded, { recursive: true });
+      await access(expanded);
+      return join(expanded, "flatkey-video-copy");
+    } catch (error) {
+      lastError = error;
+    }
+  }
+  throw new Error(`Unable to create a writable depth-video directory${lastError ? `: ${lastError.message}` : "."}`);
+}
+
+export async function inspectVideo(source, deps = {}) {
+  const ffprobe = deps.ffprobePath ?? "ffprobe";
+  const result = await runProcess(ffprobe, [
+    "-v", "error",
+    "-show_entries", "format=duration:stream=width,height,avg_frame_rate",
+    "-of", "json",
+    source,
+  ], deps);
+  let metadata;
+  try {
+    metadata = JSON.parse(result.stdout);
+  } catch {
+    throw new Error(`ffprobe returned invalid metadata for ${source}.`);
+  }
+  const duration = Number(metadata?.format?.duration);
+  if (!Number.isFinite(duration) || duration <= 0) {
+    throw new Error(`Unable to read source video duration: ${source}`);
+  }
+  return {
+    duration,
+    width: Number(metadata?.streams?.[0]?.width) || undefined,
+    height: Number(metadata?.streams?.[0]?.height) || undefined,
+    frameRate: metadata?.streams?.[0]?.avg_frame_rate,
+  };
+}
+
+export async function runDepthHelper(options, deps = {}) {
+  let helper = deps.depthHelperPath ?? deps.env?.FLATKEY_DEPTH_HELPER ?? process.env.FLATKEY_DEPTH_HELPER;
+  if (!helper) {
+    const { ensureVideoRuntime } = await import("./video-runtime.js");
+    helper = (await ensureVideoRuntime({
+      env: deps.env,
+      fetch: deps.fetch,
+      platform: deps.platform,
+      arch: deps.arch,
+    })).helperPath;
+  }
+
+  const args = [
+    "--source", options.source,
+    "--output", options.output,
+    "--frame-ratio", String(options.frameRatio),
+    "--resolution", options.resolution,
+    "--work-dir", options.workDir,
+  ];
+  if (options.model) args.push("--model", options.model);
+  const result = await runProcess(helper, args, deps);
+  try {
+    return JSON.parse(result.stdout);
+  } catch {
+    throw new Error("The Flatkey Rust depth helper returned invalid JSON.");
+  }
+}
+
+export async function extractReferenceFrames(options, deps = {}) {
+  const ffmpeg = options.ffmpegPath
+    ?? deps.env?.FFMPEG_PATH
+    ?? process.env.FFMPEG_PATH
+    ?? "ffmpeg";
+  const duration = Number(options.duration);
+  if (!Number.isFinite(duration) || duration <= 0) {
+    throw new Error("Cannot extract depth reference frames without a valid duration.");
+  }
+
+  await mkdir(options.outputDir, { recursive: true });
+  const timestamps = [
+    0,
+    duration / 2,
+    Math.max(0, duration - 1 / 30),
+  ];
+  const paths = [];
+  for (let index = 0; index < timestamps.length; index += 1) {
+    const output = join(options.outputDir, `depth-frame-${String(index + 1).padStart(2, "0")}.png`);
+    await runProcess(ffmpeg, [
+      "-v", "error",
+      "-y",
+      "-ss", timestamps[index].toFixed(6),
+      "-i", options.source,
+      "-frames:v", "1",
+      output,
+    ], deps);
+    paths.push(output);
+  }
+  return paths;
+}
+
+export function runProcess(command, args, deps = {}) {
+  if (deps.runProcess) return deps.runProcess(command, args);
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      cwd: deps.cwd,
+      env: deps.env ?? process.env,
+      windowsHide: true,
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout?.on("data", (chunk) => { stdout += chunk; });
+    child.stderr?.on("data", (chunk) => { stderr += chunk; });
+    child.once("error", (error) => {
+      reject(new Error(`Failed to start ${command}: ${error.message}`));
+    });
+    child.once("close", (code) => {
+      if (code === 0) {
+        resolve({ stdout, stderr, code });
+        return;
+      }
+      reject(new Error(`${command} failed with exit code ${code}${stderr.trim() ? `: ${stderr.trim()}` : "."}`));
+    });
+  });
+}
+
+async function expandHomePath(value) {
+  if (typeof value !== "string") return value;
+  if (value === "~") return homedir();
+  if (value.startsWith("~/")) return join(homedir(), value.slice(2));
+  return value;
+}
+
+function formatSeconds(value) {
+  return Number(value).toFixed(3).replace(/\.?0+$/, "");
+}

package/src/video-runtime.js

@@ -0,0 +1,119 @@
+import { createHash } from "node:crypto";
+import { chmod, mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+
+export const VIDEO_RUNTIME_VERSION = "0.1.0";
+
+export function runtimePlatform(platform = process.platform, arch = process.arch) {
+  const supported = {
+    darwin: { arm64: "darwin-arm64", x64: "darwin-x64" },
+    linux: { arm64: "linux-arm64", x64: "linux-x64" },
+    win32: { arm64: "win32-arm64", x64: "win32-x64" },
+  };
+  const target = supported[platform]?.[arch];
+  if (!target) throw new Error(`Unsupported Flatkey video runtime platform: ${platform}-${arch}`);
+  return target;
+}
+
+export async function runtimeDirectory({ platform = process.platform, arch = process.arch, env = process.env } = {}) {
+  const target = runtimePlatform(platform, arch);
+  const base = env.FLATKEY_RUNTIME_HOME
+    ?? (platform === "win32"
+      ? join(env.LOCALAPPDATA ?? join(homedir(), "AppData", "Local"), "flatkey")
+      : platform === "darwin"
+        ? join(homedir(), "Library", "Caches", "flatkey")
+        : join(env.XDG_CACHE_HOME ?? join(homedir(), ".cache"), "flatkey"));
+  return join(base, "runtime", VIDEO_RUNTIME_VERSION, target);
+}
+
+export async function ensureVideoRuntime(options = {}) {
+  const directory = await runtimeDirectory(options);
+  const helperName = options.platform === "win32" || (options.platform ?? process.platform) === "win32"
+    ? "flatkey-depth.exe"
+    : "flatkey-depth";
+  const helperPath = join(directory, helperName);
+  try {
+    await stat(helperPath);
+    return { directory, helperPath, downloaded: false };
+  } catch {
+    // Continue to download below.
+  }
+
+  const baseUrl = options.baseUrl
+    ?? options.env?.FLATKEY_VIDEO_RUNTIME_BASE_URL
+    ?? process.env.FLATKEY_VIDEO_RUNTIME_BASE_URL;
+  if (!baseUrl) {
+    throw new Error(
+      `Flatkey video runtime is missing at ${helperPath}. Set FLATKEY_VIDEO_RUNTIME_BASE_URL to enable automatic download.`,
+    );
+  }
+  const target = runtimePlatform(options.platform, options.arch);
+  const fetchImpl = options.fetch ?? fetch;
+  const manifestUrl = `${baseUrl.replace(/\/$/, "")}/${VIDEO_RUNTIME_VERSION}/${target}/manifest.json`;
+  const manifestResponse = await fetchImpl(manifestUrl);
+  if (!manifestResponse.ok) throw new Error(`Failed to download Flatkey video runtime manifest: HTTP ${manifestResponse.status}`);
+  const manifest = await manifestResponse.json();
+  const archiveUrl = manifest.archive_url ?? manifest.url;
+  if (Array.isArray(manifest.files)) {
+    await mkdir(directory, { recursive: true });
+    for (const file of manifest.files) {
+      await downloadRuntimeFile(file, directory, fetchImpl);
+    }
+    await stat(helperPath);
+    return { directory, helperPath, downloaded: true };
+  }
+
+  const sha256 = manifest.sha256;
+  if (!archiveUrl || !sha256) throw new Error("Flatkey video runtime manifest is missing files or archive_url/sha256.");
+
+  const archivePath = join(tmpdir(), `flatkey-video-runtime-${Date.now()}.archive`);
+  try {
+    const response = await fetchImpl(archiveUrl);
+    if (!response.ok) throw new Error(`Failed to download Flatkey video runtime: HTTP ${response.status}`);
+    const bytes = Buffer.from(await response.arrayBuffer());
+    const actualHash = createHash("sha256").update(bytes).digest("hex");
+    if (actualHash !== sha256.toLowerCase()) throw new Error("Flatkey video runtime checksum verification failed.");
+    await mkdir(directory, { recursive: true });
+    await writeFile(archivePath, bytes);
+    await extractArchive(archivePath, directory, options);
+    await stat(helperPath);
+    return { directory, helperPath, downloaded: true };
+  } finally {
+    await rm(archivePath, { force: true });
+  }
+}
+
+async function downloadRuntimeFile(file, directory, fetchImpl) {
+  if (!file?.path || !file?.url || !file?.sha256) {
+    throw new Error("Flatkey video runtime manifest contains an invalid file entry.");
+  }
+  if (file.path.includes("..") || file.path.startsWith("/") || /^[a-z]:/i.test(file.path)) {
+    throw new Error(`Flatkey video runtime manifest contains an unsafe path: ${file.path}`);
+  }
+  const response = await fetchImpl(file.url);
+  if (!response.ok) throw new Error(`Failed to download Flatkey video runtime file ${file.path}: HTTP ${response.status}`);
+  const bytes = Buffer.from(await response.arrayBuffer());
+  const actualHash = createHash("sha256").update(bytes).digest("hex");
+  if (actualHash !== file.sha256.toLowerCase()) {
+    throw new Error(`Flatkey video runtime checksum verification failed for ${file.path}.`);
+  }
+  const destination = join(directory, file.path);
+  await mkdir(join(destination, ".."), { recursive: true });
+  await writeFile(destination, bytes);
+  if (file.executable || file.mode === "755") {
+    await chmod(destination, 0o755);
+  }
+}
+
+async function extractArchive(archivePath, directory, options) {
+  if (options.extractArchive) {
+    await options.extractArchive(archivePath, directory);
+    return;
+  }
+  throw new Error("Flatkey video runtime archive extraction is not configured for this build.");
+}
+
+export async function sha256File(path) {
+  return createHash("sha256").update(await readFile(path)).digest("hex");
+}