video-editing 3.0.0 → 3.1.0

package/dist/{chunk-W4IIL2T2.js → chunk-2OM7WV4W.js}

@@ -104,6 +104,9 @@ function resolveUrl(base, videoId) {
 function verifyUrl(base, videoId) {
   return videoUrl(base, videoId, "verify");
 }
+function smoothJoinsUrl(base, videoId) {
+  return videoUrl(base, videoId, "smooth-joins");
+}
 function composeUrl(base, videoId) {
   return videoUrl(base, videoId, "compose");
 }
@@ -653,6 +656,18 @@ var CloudClient = class _CloudClient {
     }
     return { runId: o.run_id };
   }
+  async smoothJoinsStart(body = {}) {
+    const data = await this.request(
+      "POST",
+      smoothJoinsUrl(this.cfg.base, this.requireVideoId()),
+      body
+    );
+    const o = asRecord(data, "smooth-joins");
+    if (typeof o.run_id !== "string" || o.run_id === "") {
+      throw new Error(`smooth-joins response missing run_id: ${JSON.stringify(data)}`);
+    }
+    return { runId: o.run_id };
+  }
   /** GET /runs/{id} — run status + events. */
   async getRun(runId) {
     const data = await this.request("GET", runUrl(this.cfg.base, runId));

package/dist/cli.js

@@ -2,8 +2,10 @@
 import {
   CloudClient,
   REVIEW_STAGES2,
+  assertRunCompleted,
   compileRemote,
   defaultRenderOut,
+  formatRunEvent,
   framesPngPath,
   initCloudJob,
   inspectPngPath,
@@ -16,6 +18,7 @@ import {
   loadTimeline2,
   outWindowToSourceWindows,
   pollRender,
+  pollRun,
   publicConfigEnvPath,
   pullFiles,
   pullReview2,
@@ -41,12 +44,56 @@ import {
   waveformPngPath,
   waveformWordsPath,
   webVideoUrl
-} from "./chunk-W4IIL2T2.js";
+} from "./chunk-2OM7WV4W.js";
 
 // src/public/cli.ts
-import { existsSync, mkdirSync, 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;
@@ -87,7 +134,7 @@ 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: "3.0.0" };
 }
@@ -264,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;
@@ -296,6 +343,60 @@ 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("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 () => {
+    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 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.json) {
+      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(`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("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);
@@ -457,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}`);
     }
   });
@@ -516,11 +617,11 @@ 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"));
     }
   });
 });
@@ -625,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 {

package/dist/index.d.ts

@@ -3331,6 +3331,17 @@ declare class CloudClient {
     }): Promise<{
         runId: string;
     }>;
+    smoothJoinsStart(body?: {
+        crossfade_ms?: number;
+        curve?: string;
+        max_ms?: number;
+        joins?: {
+            index: number;
+            crossfade_ms: number;
+        }[];
+    }): Promise<{
+        runId: string;
+    }>;
     /** GET /runs/{id} — run status + events. */
     getRun(runId: string): Promise<RunState>;
     /** POST /videos/{id}/compile → {ok, plan, legacy_edl, diagnostics, uses}. */

package/dist/index.js

@@ -112,7 +112,7 @@ import {
   waveformPngPath,
   waveformWordsPath,
   writeJobFile
-} from "./chunk-W4IIL2T2.js";
+} from "./chunk-2OM7WV4W.js";
 
 // src/timeline-v2/anchors.ts
 function normalizeToken(text) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "video-editing",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "Pure-API cloud CLI + client for editing talking-head reels with clipready: upload once, then transcription, timeline authoring, compile, render, verify and QA all run in the cloud. Node ≥ 20 + an API key — no ffmpeg.",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",

package/skills/video-editing/SKILL.md

@@ -118,6 +118,12 @@ never work around it.
    word-timing sidecar JSON). Read the PNGs to adjudicate.
 8. **Final** — `video-editing render --mode final --job-dir "<job>"`.
 
+**Optional, any time after compile:** if joins sound clicky, chopped, or gappy,
+run `video-editing smooth-joins --job-dir "<job>"` to apply an equal-power
+audio crossfade to every cut, then re-render. It is NOT part of the sequence
+above — renders are unaffected unless you run it, and it must be re-run after
+each recompile you want it applied to. See `references/audio-joins.md`.
+
 ## Your editorial brief arrives from the cloud
 
 The deep editorial brief — retake/keep rules, pause tightening, cold-open,

package/skills/video-editing/references/audio-joins.md

@@ -0,0 +1,94 @@
+# Smoothing the audio at cuts (`smooth-joins`)
+
+**Optional.** Nothing here runs as part of a render. If you never call it,
+renders behave exactly as they always have.
+
+This is the Premiere move of selecting the whole timeline and hitting *Apply
+Audio Transition*: the picture stays a hard cut, and every join gets a short
+**Constant Power** (equal-power) audio crossfade built from the padding the cut
+threw away. One invocation treats every join — you do not opt in per cut.
+
+## Why you would run it
+
+By default each kept range is extracted with a 30 ms fade in *and* out and the
+clips are butt-joined, so every cut has a brief hole down to silence. Depending
+on where the cut landed that reads as a click, a clipped syllable, or a gap of
+dead air. The crossfade turns each one into a quick natural dip instead, and
+because it is centred on the cut the total duration does not change.
+
+Reach for it when a verify pass or a listen flags clicks, popping, or chopped
+word endings at joins — and on any edit with a lot of tight desilence trims,
+where joins are most frequent.
+
+Requires a compiled timeline (run `timeline compile` first) and an ingested
+source. Exits non-zero with `no_edl` if you run it too early.
+
+## Usage
+
+```bash
+video-editing smooth-joins --job-dir "<job>"                  # 130ms everywhere
+video-editing smooth-joins --crossfade-ms 90 --job-dir "<job>"
+video-editing smooth-joins --join 3:40 --join 7:220 --job-dir "<job>"
+```
+
+| Flag | Default | Meaning |
+|---|---|---|
+| `--crossfade-ms <ms>` | `130` | Transition length at every join (Premiere's 4 frames). `0` disables. |
+| `--curve equal-power\|linear` | `equal-power` | Fade shape. |
+| `--max-ms <ms>` | `500` | Ceiling on any single join. |
+| `--join <index>:<ms>` | — | Override one boundary. Repeatable. |
+| `--json` | — | Machine-readable output. |
+
+**Join `i` is the boundary between segment `i` and segment `i + 1`**, so an
+N-segment edit has N−1 joins. Same indexing `verify` reports its join findings
+against, so a verify finding at join 5 is `--join 5:<ms>` here.
+
+Keep `--curve equal-power` unless you have a reason: it is the only curve that
+holds loudness flat through the transition (`sin² + cos² = 1`). `linear` dips
+~3 dB in the middle of every join.
+
+Per-join overrides are for shaping, not rescue — `--join 3:40` to keep a hard
+beat change tight, `--join 7:220` to let a take change breathe, `--join 9:0` to
+leave one boundary exactly as it was.
+
+## Reading the result
+
+Writes `audio/joined.m4a` (the rebuilt track) and `audio/joined.json`:
+
+```jsonc
+{
+  "edl_sha256": "…",
+  "params": { "crossfade_ms": 130, "curve": "equal-power", "max_ms": 500 },
+  "total_duration_s": 47.213,
+  "segments": 42,
+  "joins": [
+    { "index": 0, "requested_ms": 130, "applied_ms": 130, "handle_ms": 1840, "clamped": false },
+    { "index": 1, "requested_ms": 130, "applied_ms": 52, "handle_ms": 52, "clamped": true,
+      "reason": "limited by the gap the cut removed" }
+  ]
+}
+```
+
+`applied_ms` is what the join actually got; `handle_ms` is the longest
+crossfade the surrounding material could support. **A crossfade can only borrow
+material the cut removed**, so a tight desilence trim that only took out 50 ms
+can only give you a 50 ms transition — it will come back `clamped` no matter
+what you request. That is expected and still sounds clean; 50 ms of same-speaker
+room tone is plenty. Joins between different takes have seconds of handle and
+always get the full request.
+
+Read the report before re-running: if a join you care about came back clamped
+with `"limited by the gap the cut removed"`, asking for more milliseconds will
+change nothing. Widen the cut range in `timeline.json` and recompile instead.
+
+## How it interacts with rendering
+
+Renders **consume** the artifact, they never trigger it:
+
+- Run `smooth-joins`, then render → the render uses the crossfaded audio.
+- Render without running it → unchanged from today.
+- Recompile the timeline, then render → the artifact no longer matches the
+  edit and is ignored (it is keyed to the EDL). Re-run `smooth-joins`.
+
+So the order is: `timeline compile` → `smooth-joins` → render. Re-running the
+command is cheap; re-run it after every recompile you want it applied to.

package/skills/video-editing/references/cli-reference.md

@@ -98,6 +98,16 @@ support transparently fall back to a single retried upload.
   pause-tightening joins), adjudicate against `flags.txt` instead of blindly
   recutting.
 
+- **`smooth-joins [--crossfade-ms <ms>] [--curve equal-power|linear] [--max-ms <ms>] [--join <index>:<ms>]... --job-dir <dir> [--json]`**
+  **Optional.** Applies a Constant Power (equal-power) audio crossfade to
+  **every** join — Premiere's "select the timeline, apply an audio transition"
+  move. Picture stays a hard cut. Default 130 ms (4 frames); `--join 3:40`
+  overrides a single boundary, repeatable; `0` disables one. Writes
+  `audio/joined.m4a` + an `audio/joined.json` report of what each join
+  actually got after clamping. Renders consume the result only if it matches
+  the current compile — re-run after every recompile. Full detail:
+  `references/audio-joins.md`.
+
 - **`qa frames (--start <s> --end <s> | --join <i> [--span 2] | --out-start <s> --out-end <s>) [--cols <n>] [--interval <s>] --job-dir <dir> [--json]`**
   **Server-rendered** filmstrip PNG(s) → `<job>/qa/frames_<start>_<end>.png`.
   Three addressing modes (exactly one): `--start/--end` in SOURCE seconds;