video-editing 2.0.0 → 3.1.0

package/dist/cli.js

@@ -2,16 +2,23 @@
 import {
   CloudClient,
   REVIEW_STAGES2,
+  assertRunCompleted,
   compileRemote,
-  composeCloud,
   defaultRenderOut,
+  formatRunEvent,
+  framesPngPath,
   initCloudJob,
+  inspectPngPath,
   installSkill,
   instructionPath2,
   jobJsonPath,
+  joinSourceWindows,
+  joinSpanWindow,
   loadPublicConfigEnv,
   loadTimeline2,
+  outWindowToSourceWindows,
   pollRender,
+  pollRun,
   publicConfigEnvPath,
   pullFiles,
   pullReview2,
@@ -19,24 +26,74 @@ import {
   pushFiles,
   pushStage2,
   pushTimeline2,
-  qaFramesLocal,
-  qaWaveformLocal,
+  qaDir,
   readJobFile,
-  requireFfmpeg,
+  readPlanSegments,
+  removePublicConfigKey,
+  resolveApiBase,
+  resolveApiKey,
   resolveConfig,
   resolveRunId2,
   savePublicConfigKey,
+  stripTrailingSlash,
   timelineJsonPath2,
   transcribeCloud,
   validateLocal,
   verifyCloud,
-  videoIdFromJob
-} from "./chunk-SSXAUKGV.js";
+  videoIdFromJob,
+  waveformPngPath,
+  waveformWordsPath,
+  webVideoUrl
+} from "./chunk-2OM7WV4W.js";
 
 // src/public/cli.ts
-import { existsSync, readFileSync, writeFileSync } from "fs";
-import { join, resolve as resolvePath } from "path";
+import { existsSync as existsSync2, mkdirSync, readFileSync as readFileSync2, writeFileSync } from "fs";
+import { join as join2, resolve as resolvePath } from "path";
 import { Command } from "commander";
+
+// src/cloud/smooth-joins.ts
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+var JOINED_REPORT_REL = "audio/joined.json";
+async function smoothJoinsCloud(client, jobDir, opts = {}) {
+  const verbose = opts.verbose !== false;
+  const log = (line) => {
+    if (verbose) process.stderr.write(line + "\n");
+  };
+  const { runId } = await client.smoothJoinsStart({
+    ...opts.crossfadeMs !== void 0 ? { crossfade_ms: opts.crossfadeMs } : {},
+    ...opts.curve !== void 0 ? { curve: opts.curve } : {},
+    ...opts.maxMs !== void 0 ? { max_ms: opts.maxMs } : {},
+    ...opts.overrides !== void 0 && opts.overrides.length > 0 ? { joins: opts.overrides.map((o) => ({ index: o.index, crossfade_ms: o.crossfadeMs })) } : {}
+  });
+  log(`  smooth-joins run: ${runId}`);
+  const state = await pollRun(client, runId, {
+    intervalMs: opts.pollIntervalMs,
+    onEvent: (ev) => log(`  ${formatRunEvent(ev)}`)
+  });
+  assertRunCompleted(state, "smooth-joins");
+  await pullFiles(client, jobDir, { only: [JOINED_REPORT_REL] });
+  const reportPath = join(jobDir, JOINED_REPORT_REL);
+  let joins = [];
+  let totalDurationS = null;
+  if (existsSync(reportPath)) {
+    try {
+      const r = JSON.parse(readFileSync(reportPath, "utf8"));
+      if (Array.isArray(r.joins)) joins = r.joins;
+      if (typeof r.total_duration_s === "number") totalDurationS = r.total_duration_s;
+    } catch {
+    }
+  }
+  return {
+    runId,
+    reportPath,
+    joins,
+    clamped: joins.filter((j) => j.clamped).length,
+    totalDurationS
+  };
+}
+
+// src/public/cli.ts
 loadPublicConfigEnv();
 function num(v) {
   if (v === void 0) return void 0;
@@ -77,17 +134,16 @@ function jobDirOf(o) {
 }
 var pkg;
 try {
-  pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+  pkg = JSON.parse(readFileSync2(new URL("../package.json", import.meta.url), "utf8"));
 } catch {
-  pkg = { version: "2.0.0" };
+  pkg = { version: "3.0.0" };
 }
 var program = new Command();
-program.name("video-editing").description("Cloud CLI for editing talking-head reels with clipready: init, transcribe, timeline authoring, verify, compose, QA, file sync, review rounds, cloud renders.").version(pkg.version);
+program.name("video-editing").description("Pure-API cloud CLI for editing talking-head reels with clipready: init (upload + server ingest/transcribe), timeline authoring, cloud compile/render/verify/QA, file sync, review rounds. No local media tools needed \u2014 just Node \u2265 20 and CLIPREADY_API_KEY.").version(pkg.version);
 addCloudOptions(
-  program.command("init").description("Create a cloud job: probe the source, optionally bake the vertical master, upload, and write <job>/job.json").requiredOption("--source <path>", "Source video path").option("--job-dir <path>", "Job directory (default ./job_<stem>)").option("--title <title>", "Project title (default: source stem)").option("--master", "Bake the vertical 9:16 master locally and upload it as the source").option("--json", "Print JSON")
+  program.command("init").description("Create the cloud job end-to-end: stream the source up, run server-side ingest (probe + transcription + screening), pull the transcript/brief artifacts, write <job>/job.json. Covers what init+transcribe used to do \u2014 no separate transcribe needed.").requiredOption("--source <path>", "Source video path").option("--job-dir <path>", "Job directory (default ./job_<stem>)").option("--title <title>", "Project title (default: source stem)").option("--poll-interval <s>", "Ingest-run poll interval in seconds", "5").option("--json", "Print JSON")
 ).action(async (o) => {
   await withCloudErrors(!!o.json, async () => {
-    requireFfmpeg();
     const cfg = resolveConfig(cloudFlags(o), { requireVideoId: false });
     const client = new CloudClient(cfg);
     let res;
@@ -96,7 +152,7 @@ addCloudOptions(
         source: o.source,
         jobDir: o.jobDir,
         title: o.title,
-        master: !!o.master,
+        pollIntervalMs: (num(o.pollInterval) ?? 5) * 1e3,
         verbose: !o.json
       });
     } catch (err) {
@@ -107,43 +163,35 @@ Your credential was rejected \u2014 get your API key at ${cfg.base}/settings and
       throw err;
     }
     if (o.json) {
-      console.log(JSON.stringify({ ok: true, job_dir: res.jobDir, job_json: res.jobJson, video_id: res.videoId, project_id: res.projectId, stem: res.stem, duration_s: res.durationS, uploaded: res.uploaded, uploaded_bytes: res.uploadedBytes }, null, 2));
+      console.log(JSON.stringify({ ok: true, job_dir: res.jobDir, job_json: res.jobJson, video_id: res.videoId, project_id: res.projectId, stem: res.stem, duration_s: res.durationS, uploaded: res.uploaded, uploaded_bytes: res.uploadedBytes, run_id: res.runId, pulled: res.pulled.pulled.map((p) => p.path), missing: res.pulled.missing, web_url: res.webUrl }, null, 2));
     } else {
       console.log(`job: ${res.jobDir}`);
       console.log(`video_id: ${res.videoId}`);
       console.log(`project_id: ${res.projectId}`);
       console.log(`job.json: ${res.jobJson}`);
+      for (const p of res.pulled.pulled) console.log(`  ${p.path} \u2192 ${p.localPath}${p.skipped ? " (unchanged)" : ""}`);
+      if (res.pulled.missing.length > 0) console.log(`  missing on server: ${res.pulled.missing.join(", ")}`);
+      console.log(`web: ${res.webUrl}`);
     }
   });
 });
 addCloudOptions(
-  program.command("transcribe").description("Extract + upload the WAV locally, run server-side Scribe transcription, pull the artifact set").option("--job-dir <path>", "Job directory (default: cwd)").option("--media <path>", "Local media to extract from (default: <job>/vertical_src.mp4, else the init source)").option("--language <code>", "Optional ISO language code").option("--num-speakers <n>", "Optional speaker count").option("--poll-interval <s>", "Run poll interval in seconds", "5").option("--json", "Print JSON")
+  program.command("transcribe").description("Re-run/pull transcription: pull the transcript artifacts when they already exist server-side, else run server-side ingest and pull (init already did this once)").option("--job-dir <path>", "Job directory (default: cwd)").option("--poll-interval <s>", "Run poll interval in seconds", "5").option("--json", "Print JSON")
 ).action(async (o) => {
   await withCloudErrors(!!o.json, async () => {
-    requireFfmpeg();
     const jobDir = jobDirOf(o);
     const cfg = jobConfig(o, jobDir);
     const client = new CloudClient(cfg);
     const job = readJobFile(jobDir);
-    let media = o.media ? resolvePath(o.media) : join(jobDir, "vertical_src.mp4");
-    if (!existsSync(media)) {
-      const alt = job ? join(jobDir, `${job.stem}.mp4`) : null;
-      if (alt && existsSync(alt)) media = alt;
-      else if (!o.media) throw new Error(`no local media found (looked for ${media}) \u2014 pass --media <path>`);
-      else throw new Error(`media not found: ${media}`);
-    }
     const res = await transcribeCloud(client, jobDir, {
-      media,
       stem: job?.stem ?? "source",
-      language: o.language,
-      numSpeakers: num(o.numSpeakers),
       pollIntervalMs: (num(o.pollInterval) ?? 5) * 1e3,
       verbose: !o.json
     });
     if (o.json) {
-      console.log(JSON.stringify({ ok: true, run_id: res.runId, wav_path: res.wavPath, duration_s: res.durationS, pulled: res.pulled.pulled.map((p) => p.path), missing: res.pulled.missing }, null, 2));
+      console.log(JSON.stringify({ ok: true, run_id: res.runId, pulled: res.pulled.pulled.map((p) => p.path), missing: res.pulled.missing }, null, 2));
     } else {
-      console.log(`run: ${res.runId}`);
+      if (res.runId) console.log(`run: ${res.runId}`);
       for (const p of res.pulled.pulled) console.log(`  ${p.path} \u2192 ${p.localPath}${p.skipped ? " (unchanged)" : ""}`);
       if (res.pulled.missing.length > 0) console.log(`  missing on server: ${res.pulled.missing.join(", ")}`);
     }
@@ -214,7 +262,6 @@ addCloudOptions(
 });
 async function runRemoteCompile(o) {
   const jobDir = jobDirOf(o);
-  requireFfmpeg();
   const client = new CloudClient(jobConfig(o, jobDir));
   const loaded = loadTimeline2(jobDir);
   if (!loaded.doc) {
@@ -230,8 +277,10 @@ async function runRemoteCompile(o) {
   }
   const res = await compileRemote(client, jobDir, loaded);
   const diagnostics = res.response.diagnostics;
+  const job = readJobFile(jobDir);
+  const webUrl = res.ok && job && job.project_id !== "" ? webVideoUrl(client.cfg.base, job.project_id, job.video_id) : null;
   if (o.json) {
-    console.log(JSON.stringify({ ok: res.ok, plan: res.planPath ?? null, edl: res.edlPath ?? null, diagnostics: res.response.diagnostics ?? null, uses: res.response.uses ?? null }, null, 2));
+    console.log(JSON.stringify({ ok: res.ok, plan: res.planPath ?? null, edl: res.edlPath ?? null, diagnostics: res.response.diagnostics ?? null, uses: res.response.uses ?? null, web_url: webUrl }, null, 2));
   } else {
     if (res.ok && res.planPath) {
       console.log(`plan: ${res.planPath}`);
@@ -243,6 +292,7 @@ async function runRemoteCompile(o) {
       const d = e;
       console.log(`  [error] ${d.path ?? ""}: ${d.message ?? ""}`);
     }
+    if (webUrl) console.log(`View & comment: ${webUrl}`);
   }
   if (!res.ok) {
     const ambiguous = (diagnostics?.errors ?? []).some((e) => e.code === "anchor-ambiguous");
@@ -261,8 +311,8 @@ addCloudOptions(
   await withCloudErrors(!!o.json, async () => {
     const jobDir = jobDirOf(o);
     const tlPath = timelineJsonPath2(jobDir);
-    if (!existsSync(tlPath)) throw new Error(`timeline not found: ${tlPath}`);
-    const raw = JSON.parse(readFileSync(tlPath, "utf8"));
+    if (!existsSync2(tlPath)) throw new Error(`timeline not found: ${tlPath}`);
+    const raw = JSON.parse(readFileSync2(tlPath, "utf8"));
     const captions = raw.captions !== null && typeof raw.captions === "object" ? raw.captions : {};
     captions.enabled = true;
     captions.preset = o.preset;
@@ -273,10 +323,9 @@ addCloudOptions(
   });
 });
 addCloudOptions(
-  program.command("verify").description("Content-verify the rendered preview server-side: upload the preview WAV, run, pull verify.json").option("--job-dir <path>", "Job directory (default: cwd)").option("--full", "Verify the whole preview instead of per-join windows").option("--window <s>", "Per-join window length in seconds").option("--poll-interval <s>", "Run poll interval in seconds", "5").option("--json", "Print JSON")
+  program.command("verify").description("Content-verify the rendered preview fully server-side (no upload): start the run, poll, pull verify.json").option("--job-dir <path>", "Job directory (default: cwd)").option("--full", "Verify the whole preview instead of per-join windows").option("--window <s>", "Per-join window length in seconds").option("--poll-interval <s>", "Run poll interval in seconds", "5").option("--json", "Print JSON")
 ).action(async (o) => {
   await withCloudErrors(!!o.json, async () => {
-    requireFfmpeg();
     const jobDir = jobDirOf(o);
     const client = new CloudClient(jobConfig(o, jobDir));
     const res = await verifyCloud(client, jobDir, {
@@ -294,84 +343,153 @@ addCloudOptions(
     if (res.verdict === "needs-fixes") process.exitCode = 2;
   });
 });
+function collectJoinOverride(raw, acc = []) {
+  const m = raw.match(/^(\d+):(\d+(?:\.\d+)?)$/);
+  if (!m) {
+    throw new Error(`--join expects <index>:<ms>, e.g. --join 3:40 (got "${raw}")`);
+  }
+  acc.push({ index: Number(m[1]), crossfadeMs: Number(m[2]) });
+  return acc;
+}
 addCloudOptions(
-  program.command("compose").description("Fetch the server-authored HyperFrames composition, build media proxies locally; with --render, render via the `hyperframes` CLI").option("--job-dir <path>", "Job directory (default: cwd)").option("--render", "Render the composition locally (requires the `hyperframes` CLI on PATH)").option("--quality <q>", "Render quality: draft|standard|high", "standard").option("--fps <n>", "Render frame rate", "30").option("--out <path>", "Rendered output path (default <job>/preview.mp4)").option("--proxy-crf <crf>", "libx264 CRF for the compressed video proxy", "23").option("--json", "Print JSON")
+  program.command("smooth-joins").description(
+    "Apply an equal-power audio crossfade to EVERY join (Premiere's Constant Power transition). Optional \u2014 renders are unaffected unless you run it"
+  ).option("--job-dir <path>", "Job directory (default: cwd)").option("--crossfade-ms <ms>", "Transition length at every join (default: 130 \u2014 Premiere's 4 frames); 0 disables").option("--curve <name>", "equal-power (default) or linear").option("--max-ms <ms>", "Ceiling on any single join").option(
+    "--join <index:ms>",
+    "Per-join override, repeatable (e.g. --join 3:40 --join 7:220)",
+    collectJoinOverride
+  ).option("--poll-interval <s>", "Run poll interval in seconds", "5").option("--json", "Print JSON")
 ).action(async (o) => {
   await withCloudErrors(!!o.json, async () => {
-    requireFfmpeg();
+    if (o.curve !== void 0 && o.curve !== "equal-power" && o.curve !== "linear") {
+      throw new Error(`--curve must be "equal-power" or "linear" (got "${o.curve}")`);
+    }
     const jobDir = jobDirOf(o);
     const client = new CloudClient(jobConfig(o, jobDir));
-    const res = await composeCloud(client, jobDir, {
-      render: !!o.render,
-      quality: o.quality,
-      fps: num(o.fps),
-      out: o.out,
-      proxyCrf: num(o.proxyCrf),
+    const res = await smoothJoinsCloud(client, jobDir, {
+      crossfadeMs: num(o.crossfadeMs),
+      ...o.curve !== void 0 ? { curve: o.curve } : {},
+      maxMs: num(o.maxMs),
+      ...Array.isArray(o.join) ? { overrides: o.join } : {},
+      pollIntervalMs: (num(o.pollInterval) ?? 5) * 1e3,
       verbose: !o.json
     });
-    if (o.render && !res.rendered) {
-      process.exitCode = res.renderExit ?? 1;
-      process.stderr.write(`hyperframes render failed with exit ${res.renderExit}
-`);
-      return;
-    }
     if (o.json) {
-      console.log(JSON.stringify({ ok: true, composition_dir: res.compositionDir, entry: res.entry, counts: res.counts, out: res.out ?? null }, null, 2));
+      console.log(
+        JSON.stringify(
+          {
+            ok: true,
+            run_id: res.runId,
+            report: res.reportPath,
+            total_duration_s: res.totalDurationS,
+            joins: res.joins
+          },
+          null,
+          2
+        )
+      );
     } else {
-      console.log(`composition: ${res.compositionDir}`);
-      console.log(`entry: ${res.entry}`);
-      if (res.out) console.log(`out: ${res.out}`);
+      console.log(`smooth-joins: ${res.joins.length} join(s), ${res.clamped} clamped by available handle`);
+      for (const j of res.joins.filter((x) => x.clamped)) {
+        console.log(`  join ${j.index}: ${j.applied_ms}ms (asked ${j.requested_ms}ms) \u2014 ${j.reason ?? "clamped"}`);
+      }
+      console.log(`report: ${res.reportPath}`);
     }
   });
 });
-var qaCmd = program.command("qa").description("Local QC: filmstrip frames (ffmpeg tile) + waveform (showwavespic) with a word-timing sidecar");
-function qaVideoPath(jobDir, which) {
-  const video = which === "vertical_src" ? join(jobDir, "vertical_src.mp4") : join(jobDir, "preview.mp4");
-  if (!existsSync(video)) throw new Error(`video not found: ${video}`);
-  return video;
+var qaCmd = program.command("qa").description("Cloud QC: server-rendered filmstrip frames, waveform (word-timing sidecar) + the combined inspect composite; windows in source seconds, or plan-addressed via --join / --out-start");
+function framesWindows(jobDir, o, joinMode = "split") {
+  const start = num(o.start);
+  const end = num(o.end);
+  const joinIdx = num(o.join);
+  const outStart = num(o.outStart);
+  const outEnd = num(o.outEnd);
+  const modes = [start !== void 0 || end !== void 0, joinIdx !== void 0, outStart !== void 0 || outEnd !== void 0];
+  if (modes.filter(Boolean).length !== 1) {
+    throw new Error("pass exactly one addressing mode: --start/--end (source s), --join <i>, or --out-start/--out-end (output s)");
+  }
+  if (joinIdx !== void 0) {
+    const segs = readPlanSegments(jobDir);
+    const span = num(o.span) ?? 2;
+    return joinMode === "span" ? [joinSpanWindow(segs, joinIdx, span)] : joinSourceWindows(segs, joinIdx, span);
+  }
+  if (outStart !== void 0 || outEnd !== void 0) {
+    if (outStart === void 0 || outEnd === void 0) throw new Error("--out-start and --out-end are both required");
+    return outWindowToSourceWindows(readPlanSegments(jobDir), outStart, outEnd);
+  }
+  if (start === void 0 || end === void 0 || end <= start) throw new Error("--start and --end must be numbers with end > start");
+  return [{ start, end, suffix: "" }];
 }
 addCloudOptions(
-  qaCmd.command("frames").description("Render a filmstrip PNG for a window (local ffmpeg tile filter)").requiredOption("--start <s>", "Window start (seconds)").requiredOption("--end <s>", "Window end (seconds)").option("--frames <n>", "Number of frames", "10").option("--cols <n>", "Grid columns", "5").option("--video <which>", "preview|vertical_src", "preview").option("--job-dir <path>", "Job directory (default: cwd)").option("--json", "Print JSON")
+  qaCmd.command("frames").description("Server-render a filmstrip PNG per window and download it under <job>/qa").option("--start <s>", "Window start (SOURCE seconds)").option("--end <s>", "Window end (SOURCE seconds)").option("--join <i>", "Plan join index (1-based): filmstrips for the last/first --span seconds of the two segments meeting there (-a tail, -b head)").option("--span <s>", "Seconds per side for --join", "2").option("--out-start <s>", "Window start in OUTPUT seconds (mapped through resolved/plan.json)").option("--out-end <s>", "Window end in OUTPUT seconds").option("--cols <n>", "Grid columns").option("--interval <s>", "Seconds between frames").option("--job-dir <path>", "Job directory (default: cwd)").option("--json", "Print JSON")
 ).action(async (o) => {
   await withCloudErrors(!!o.json, async () => {
-    requireFfmpeg();
     const jobDir = jobDirOf(o);
-    jobConfig(o, jobDir, { requireVideoId: false });
-    const start = num(o.start);
-    const end = num(o.end);
-    if (start === void 0 || end === void 0 || end <= start) throw new Error("--start and --end must be numbers with end > start");
-    const res = await qaFramesLocal(jobDir, {
-      video: qaVideoPath(jobDir, String(o.video)),
-      start,
-      end,
-      frames: num(o.frames),
-      cols: num(o.cols)
-    });
-    if (o.json) console.log(JSON.stringify({ ok: true, png: res.png }, null, 2));
-    else console.log(`frames: ${res.png}`);
+    const client = new CloudClient(jobConfig(o, jobDir));
+    const windows = framesWindows(jobDir, o);
+    const dir = qaDir(jobDir);
+    const outputs = [];
+    for (const w of windows) {
+      const res = await client.qaFrames({ start: w.start, end: w.end, cols: num(o.cols), interval: num(o.interval) });
+      const png = framesPngPath(dir, w.start, w.end, w.suffix);
+      const dl = await client.download(res.url, png);
+      outputs.push({ png: dl.path, width: res.width, height: res.height, frames: res.frames, tStart: res.tStart, tEnd: res.tEnd });
+    }
+    if (o.json) {
+      console.log(JSON.stringify({ ok: true, frames: outputs.map((r) => ({ png: r.png, width: r.width, height: r.height, frames: r.frames, t_start: r.tStart, t_end: r.tEnd })) }, null, 2));
+    } else {
+      for (const r of outputs) {
+        console.log(`frames: ${r.png}`);
+        console.log(`grid: ${r.frames} frame(s), ${r.width}x${r.height}, t ${r.tStart}s\u2013${r.tEnd}s`);
+      }
+    }
   });
 });
 addCloudOptions(
-  qaCmd.command("waveform").description("Render a waveform PNG + word-timing sidecar for a window (local ffmpeg showwavespic)").requiredOption("--start <s>", "Window start (seconds)").requiredOption("--end <s>", "Window end (seconds)").option("--video <which>", "preview|vertical_src", "preview").option("--job-dir <path>", "Job directory (default: cwd)").option("--json", "Print JSON")
+  qaCmd.command("inspect").description("Server-render the combined close-look composite (filmstrip + waveform + word labels + red cut shading from the compiled plan) per window and download it under <job>/qa").option("--start <s>", "Window start (SOURCE seconds)").option("--end <s>", "Window end (SOURCE seconds)").option("--join <i>", "Plan join index (1-based): ONE continuous composite spanning the cut \u2014 --span s of kept tail, the red-shaded cut region, --span s of kept head").option("--span <s>", "Seconds per side for --join", "2").option("--out-start <s>", "Window start in OUTPUT seconds (mapped through resolved/plan.json)").option("--out-end <s>", "Window end in OUTPUT seconds").option("--n-frames <n>", "Filmstrip frame count", "10").option("--job-dir <path>", "Job directory (default: cwd)").option("--json", "Print JSON")
 ).action(async (o) => {
   await withCloudErrors(!!o.json, async () => {
-    requireFfmpeg();
     const jobDir = jobDirOf(o);
-    jobConfig(o, jobDir, { requireVideoId: false });
+    const client = new CloudClient(jobConfig(o, jobDir));
+    const windows = framesWindows(jobDir, o, "span");
+    const dir = qaDir(jobDir);
+    const outputs = [];
+    for (const w of windows) {
+      const res = await client.qaInspect({ start: w.start, end: w.end, nFrames: num(o.nFrames) });
+      const png = inspectPngPath(dir, w.start, w.end, w.suffix);
+      const dl = await client.download(res.url, png);
+      outputs.push({ png: dl.path, tStart: res.tStart, tEnd: res.tEnd, cuts: res.cuts, cached: res.cached });
+    }
+    if (o.json) {
+      console.log(JSON.stringify({ ok: true, inspect: outputs.map((r) => ({ png: r.png, t_start: r.tStart, t_end: r.tEnd, cuts: r.cuts, cached: r.cached })) }, null, 2));
+    } else {
+      for (const r of outputs) {
+        console.log(`inspect: ${r.png}`);
+        console.log(`window: t ${r.tStart}s\u2013${r.tEnd}s, ${r.cuts.length} cut(s) shaded${r.cached ? " (cached)" : ""}`);
+      }
+    }
+  });
+});
+addCloudOptions(
+  qaCmd.command("waveform").description("Server-render a waveform PNG + word-timing sidecar for a source-time window").requiredOption("--start <s>", "Window start (SOURCE seconds)").requiredOption("--end <s>", "Window end (SOURCE seconds)").option("--job-dir <path>", "Job directory (default: cwd)").option("--json", "Print JSON")
+).action(async (o) => {
+  await withCloudErrors(!!o.json, async () => {
+    const jobDir = jobDirOf(o);
+    const client = new CloudClient(jobConfig(o, jobDir));
     const start = num(o.start);
     const end = num(o.end);
     if (start === void 0 || end === void 0 || end <= start) throw new Error("--start and --end must be numbers with end > start");
-    const job = readJobFile(jobDir);
-    const res = await qaWaveformLocal(jobDir, {
-      video: qaVideoPath(jobDir, String(o.video)),
-      start,
-      end,
-      stem: job?.stem
-    });
-    if (o.json) console.log(JSON.stringify({ ok: true, png: res.png, words_path: res.wordsPath ?? null, words: res.words ?? null }, null, 2));
+    const res = await client.qaWaveform({ start, end });
+    const dir = qaDir(jobDir);
+    const png = waveformPngPath(dir, start, end);
+    const wordsPath = waveformWordsPath(dir, start, end);
+    const dl = await client.download(res.url, png);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(wordsPath, JSON.stringify(res.words, null, 2) + "\n", "utf8");
+    if (o.json) console.log(JSON.stringify({ ok: true, png: dl.path, words_path: wordsPath, words: res.words.length }, null, 2));
     else {
-      console.log(`waveform: ${res.png}`);
-      if (res.wordsPath) console.log(`words: ${res.wordsPath} (${res.words} word(s))`);
+      console.log(`waveform: ${dl.path}`);
+      console.log(`words: ${wordsPath} (${res.words.length} word(s))`);
     }
   });
 });
@@ -440,7 +558,7 @@ addCloudOptions(
       } else {
         console.log("no active review round");
       }
-      console.log(`timeline.json: ${res.wroteTimeline ? "written" : existsSync(timelineJsonPath2(jobDir)) ? "kept (already present locally)" : "not provided"}`);
+      console.log(`timeline.json: ${res.wroteTimeline ? "written" : existsSync2(timelineJsonPath2(jobDir)) ? "kept (already present locally)" : "not provided"}`);
       if (res.downloadedSource) console.log(`source: ${res.downloadedSource}`);
     }
   });
@@ -465,7 +583,6 @@ addCloudOptions(
       else console.log(`pushed: ${o.stage} (run ${runId})`);
       return;
     }
-    requireFfmpeg();
     if (o.timeline) {
       const res2 = await pushTimeline2(client, jobDir, runId);
       if (!res2.ok) return printPush2Failure(res2, !!o.json);
@@ -500,54 +617,60 @@ addCloudOptions(
     const jobDir = jobDirOf(o);
     jobConfig(o, jobDir, { requireVideoId: false });
     const path = instructionPath2(jobDir);
-    if (!existsSync(path)) throw new Error(`no instruction found at ${path} \u2014 run \`video-editing review pull\` first`);
-    if (o.json) console.log(JSON.stringify({ ok: true, instruction: path, content: readFileSync(path, "utf8") }, null, 2));
+    if (!existsSync2(path)) throw new Error(`no instruction found at ${path} \u2014 run \`video-editing review pull\` first`);
+    if (o.json) console.log(JSON.stringify({ ok: true, instruction: path, content: readFileSync2(path, "utf8") }, null, 2));
     else {
       console.log(`instruction: ${path}`);
-      process.stdout.write(readFileSync(path, "utf8"));
+      process.stdout.write(readFileSync2(path, "utf8"));
     }
   });
 });
-var cloudCmd = program.command("cloud").description("Cloud render + status (clipready render API)");
-addCloudOptions(
-  cloudCmd.command("render").description("Submit a render; with --wait, poll to completion and download the result").requiredOption("--mode <mode>", "preview|final").option("--job-dir <path>", "Job directory (download target; default: cwd)").option("--wait", "Poll until the render is terminal, then download").option("--poll-interval <s>", "Poll interval in seconds", "10").option("--out <path>", "Output path (default <job>/preview.mp4 or final.mp4)").option("--json", "Print JSON")
-).action(async (o) => {
-  await withCloudErrors(!!o.json, async () => {
-    const mode = o.mode;
-    if (mode !== "preview" && mode !== "final") throw new Error("--mode must be preview|final");
-    const jobDir = jobDirOf(o);
-    const client = new CloudClient(jobConfig(o, jobDir));
-    const created = await client.createRender(mode);
-    if (!o.wait) {
-      if (o.json) console.log(JSON.stringify({ ok: true, render_id: created.renderId, status: created.status }, null, 2));
-      else {
-        console.log(`render_id: ${created.renderId}`);
-        console.log(`status: ${created.status}`);
-      }
-      return;
-    }
-    const intervalMs = (num(o.pollInterval) ?? 10) * 1e3;
-    const state = await pollRender(client, created.renderId, {
-      intervalMs,
-      onTick: (s, elapsed) => {
-        if (!o.json) process.stderr.write(`  [${Math.round(elapsed / 1e3)}s] ${s.status}
-`);
-      }
-    });
-    if (state.status === "failed") {
-      const detail = state.error !== void 0 ? typeof state.error === "string" ? state.error : JSON.stringify(state.error) : "unknown error";
-      throw new Error(`render ${created.renderId} failed: ${detail}`);
-    }
-    if (!state.videoUrl) throw new Error(`render ${created.renderId} completed without a video_url`);
-    const out = o.out ? resolvePath(o.out) : defaultRenderOut(jobDir, mode);
-    const dl = await client.download(state.videoUrl, out);
-    if (o.json) console.log(JSON.stringify({ ok: true, render_id: created.renderId, status: state.status, video_url: state.videoUrl, out: dl.path, bytes: dl.bytes }, null, 2));
+async function runCloudRender(o, wait) {
+  const mode = o.mode;
+  if (mode !== "preview" && mode !== "final") throw new Error("--mode must be preview|final");
+  const jobDir = jobDirOf(o);
+  const client = new CloudClient(jobConfig(o, jobDir));
+  const created = await client.createRender(mode);
+  if (!wait) {
+    if (o.json) console.log(JSON.stringify({ ok: true, render_id: created.renderId, status: created.status }, null, 2));
     else {
       console.log(`render_id: ${created.renderId}`);
-      console.log(`status: ${state.status}`);
-      console.log(`out: ${dl.path} (${dl.bytes} bytes)`);
+      console.log(`status: ${created.status}`);
+    }
+    return;
+  }
+  const intervalMs = (num(o.pollInterval) ?? 10) * 1e3;
+  const state = await pollRender(client, created.renderId, {
+    intervalMs,
+    onTick: (s, elapsed) => {
+      if (!o.json) process.stderr.write(`  [${Math.round(elapsed / 1e3)}s] ${s.status}
+`);
     }
   });
+  if (state.status === "failed") {
+    const detail = state.error !== void 0 ? typeof state.error === "string" ? state.error : JSON.stringify(state.error) : "unknown error";
+    throw new Error(`render ${created.renderId} failed: ${detail}`);
+  }
+  if (!state.videoUrl) throw new Error(`render ${created.renderId} completed without a video_url`);
+  const out = o.out ? resolvePath(String(o.out)) : defaultRenderOut(jobDir, mode);
+  const dl = await client.download(state.videoUrl, out);
+  if (o.json) console.log(JSON.stringify({ ok: true, render_id: created.renderId, status: state.status, video_url: state.videoUrl, out: dl.path, bytes: dl.bytes }, null, 2));
+  else {
+    console.log(`render_id: ${created.renderId}`);
+    console.log(`status: ${state.status}`);
+    console.log(`out: ${dl.path} (${dl.bytes} bytes)`);
+  }
+}
+addCloudOptions(
+  program.command("render").description("Cloud-render the compiled plan (works right after `timeline compile`); waits and downloads by default").option("--mode <mode>", "preview|final", "preview").option("--job-dir <path>", "Job directory (download target; default: cwd)").option("--no-wait", "Submit only; do not poll/download").option("--poll-interval <s>", "Poll interval in seconds", "10").option("--out <path>", "Output path (default <job>/preview.mp4 or final.mp4)").option("--json", "Print JSON")
+).action(async (o) => {
+  await withCloudErrors(!!o.json, () => runCloudRender(o, o.wait !== false));
+});
+var cloudCmd = program.command("cloud").description("Cloud render + status (clipready render API)");
+addCloudOptions(
+  cloudCmd.command("render").description("Submit a render; with --wait, poll to completion and download the result").requiredOption("--mode <mode>", "preview|final").option("--job-dir <path>", "Job directory (download target; default: cwd)").option("--wait", "Poll until the render is terminal, then download").option("--poll-interval <s>", "Poll interval in seconds", "10").option("--out <path>", "Output path (default <job>/preview.mp4 or final.mp4)").option("--json", "Print JSON")
+).action(async (o) => {
+  await withCloudErrors(!!o.json, () => runCloudRender(o, !!o.wait));
 });
 addCloudOptions(
   cloudCmd.command("status").description("Fetch the current status of a render").argument("<render_id>", "Render id").option("--json", "Print JSON")
@@ -580,18 +703,17 @@ addCloudOptions(
   });
 });
 var STATUS_FILES = [
-  "vertical_src.mp4",
   "timeline.json",
   "resolved/plan.json",
   "resolved/diagnostics.json",
   "edl.json",
   "preview.mp4",
   "final.mp4",
-  "preview.mp4",
   "takes_packed.md",
   "flags.txt",
   "word_dump.txt",
   "coverage.json",
+  "probe.json",
   "verify.json",
   "review/round.json",
   "review/instruction.md"
@@ -604,8 +726,8 @@ addCloudOptions(
     jobConfig(o, jobDir, { requireVideoId: false });
     const job = readJobFile(jobDir);
     const artifacts = {};
-    if (job) artifacts[`transcripts/${job.stem}.json`] = existsSync(join(jobDir, "transcripts", `${job.stem}.json`));
-    for (const f of STATUS_FILES) artifacts[f] = existsSync(join(jobDir, f));
+    if (job) artifacts[`transcripts/${job.stem}.json`] = existsSync2(join2(jobDir, "transcripts", `${job.stem}.json`));
+    for (const f of STATUS_FILES) artifacts[f] = existsSync2(join2(jobDir, f));
     if (o.json) {
       console.log(JSON.stringify({ ok: true, job_dir: jobDir, job: job ?? null, artifacts }, null, 2));
     } else {
@@ -622,6 +744,85 @@ addCloudOptions(
     }
   });
 });
+function promptSecret(promptText) {
+  return new Promise((resolve, reject) => {
+    const stdin = process.stdin;
+    process.stderr.write(promptText);
+    if (!stdin.isTTY) {
+      let data = "";
+      stdin.setEncoding("utf8");
+      stdin.on("data", (d) => data += d);
+      stdin.on("end", () => resolve(data.trim()));
+      stdin.resume();
+      return;
+    }
+    stdin.setRawMode(true);
+    stdin.resume();
+    stdin.setEncoding("utf8");
+    let value = "";
+    const done = (fn) => {
+      stdin.setRawMode(false);
+      stdin.pause();
+      stdin.off("data", onData);
+      process.stderr.write("\n");
+      fn();
+    };
+    const onData = (chunk) => {
+      for (const c of chunk) {
+        if (c === "\r" || c === "\n" || c === "") return done(() => resolve(value.trim()));
+        if (c === "") return done(() => reject(new Error("cancelled")));
+        if (c === "\x7F" || c === "\b") value = value.slice(0, -1);
+        else value += c;
+      }
+    };
+    stdin.on("data", onData);
+  });
+}
+var authCmd = program.command("auth").description("Log in to ClipReady (stores the API key in the config file)");
+authCmd.command("api-key").description("Paste your ClipReady API key once \u2014 verified against the cloud, then saved").argument("[key]", "API key (omit to be prompted; input is hidden)").option("--api-base <url>", "API base URL (default: the hosted ClipReady cloud)").action(async (keyArg, o) => {
+  const base = stripTrailingSlash(resolveApiBase(o.apiBase));
+  const key = (keyArg ?? await promptSecret(`Paste your ClipReady API key (from ${base}/settings): `)).trim();
+  if (!key) throw new Error("no API key provided");
+  let keyName = null;
+  try {
+    const me = await new CloudClient({ base, credential: key }).me();
+    const k = me.key;
+    keyName = typeof k?.name === "string" ? k.name : null;
+  } catch (err) {
+    throw new Error(
+      `that key was rejected by ${base} \u2014 check it at ${base}/settings and try again` + (err instanceof Error ? `
+(${err.message})` : "")
+    );
+  }
+  savePublicConfigKey("CLIPREADY_API_KEY", key);
+  if (o.apiBase) savePublicConfigKey("CLIPREADY_API_BASE", base);
+  console.log(`Logged in${keyName ? ` with key "${keyName}"` : ""} (\u2026${key.slice(-4)}) \u2014 saved to ${publicConfigEnvPath()}`);
+  console.log(`Cloud: ${base}`);
+});
+authCmd.command("status").description("Show the active credential/base and verify them against the cloud").action(async () => {
+  loadPublicConfigEnv();
+  const base = stripTrailingSlash(resolveApiBase(void 0));
+  const key = resolveApiKey(void 0);
+  console.log(`config: ${publicConfigEnvPath()}`);
+  console.log(`cloud:  ${base}`);
+  if (!key) {
+    console.log("key:    (none) \u2014 run `video-editing auth api-key`");
+    process.exitCode = 1;
+    return;
+  }
+  try {
+    const me = await new CloudClient({ base, credential: key }).me();
+    const k = me.key;
+    const keyName = typeof k?.name === "string" ? k.name : null;
+    console.log(`key:    \u2026${key.slice(-4)}${keyName ? ` ("${keyName}")` : ""} \u2014 valid`);
+  } catch {
+    console.log(`key:    \u2026${key.slice(-4)} \u2014 REJECTED by ${base}`);
+    process.exitCode = 1;
+  }
+});
+authCmd.command("logout").description("Remove the stored API key").action(() => {
+  console.log(`removed key from ${removePublicConfigKey("CLIPREADY_API_KEY")}`);
+});
 program.command("config").description("Manage CLI config (clipready API key/base)").argument("<action>", "set-key | set-base | path").argument("[value]", "value for set-key / set-base").action((action, value) => {
   if (action === "path") {
     console.log(publicConfigEnvPath());