@mediaruntime/cli 1.3.0 → 1.4.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 1.4.0 — 2026-09-13
+
+- Add capability-discovered Clip Candidates and Video Clip commands, bounded ranges,
+  original or vertical blurred framing, keyword controls, and opt-in burned captions.
+- Attach local JSON plans/segment arrays, SRT, or VTT with source timestamps; reuse
+  transcripts for analysis without another Whisper run. Validate bounded UTF-8 attachments
+  before submission and preserve the normal wait and verified ZIP download flow.
+- Require `@mediaruntime/node` 1.4.0 for clipping serialization and report parity.
+- Correct the executable version and regression-test it against the package manifest.
+
 ## 1.3.0 — 2026-08-31
 
 - Add complete Hosted Sticker Runtime commands for collection lifecycle, pack binding,

package/README.md

@@ -4,7 +4,12 @@ Official command-line client for MediaRuntime. It submits media, waits for jobs,
 the canonical ZIP output bundle, inspects account jobs, and sends correctly signed
 synthetic webhooks to a local receiver.
 
-Status: stable `1.3.0`. The documented `1.x` command names, flags, JSON envelopes, exit
+Version `1.4.0` adds [clipping commands](docs/clipping.md) for analysis,
+manual ranges, vertical blur-fill, and JSON/SRT/VTT transcript attachments. It requires
+Node SDK 1.4.0 or newer and a gateway/engine deployment supporting the clipping
+presets. The live capability catalog determines which presets are available.
+
+The documented `1.x` command names, flags, JSON envelopes, exit
 codes, and credential precedence follow semantic versioning. Breaking changes require a
 new major version; additive commands and fields may ship in minor releases.
 

package/dist/cli.js

@@ -608,6 +608,93 @@ async function runJobsCommand(args, dependencies) {
   throw new UsageError("Usage: mediaruntime jobs <list|get>");
 }
 
+// src/clipTranscript.ts
+import { open } from "fs/promises";
+var MAX_FILE_BYTES = 1024 * 1024;
+function timestamp(value) {
+  const match = /^(?:(\d{2,}):)?(\d{2}):(\d{2})[.,](\d{3})$/.exec(value);
+  if (!match || Number(match[2]) > 59 || Number(match[3]) > 59) {
+    throw new UsageError("Transcript cue times must use HH:MM:SS,mmm (SRT) or MM:SS.mmm / HH:MM:SS.mmm (VTT)");
+  }
+  return Number(match[1] ?? 0) * 3600 + Number(match[2]) * 60 + Number(match[3]) + Number(match[4]) / 1e3;
+}
+function subtitleSegments(text, vtt) {
+  if (vtt && !/^WEBVTT(?:\s|$)/.test(text)) throw new UsageError("VTT transcripts must begin with WEBVTT");
+  const segments = [];
+  for (const block of text.split(/\n[ \t]*\n/)) {
+    if (vtt && /^(WEBVTT(?:\s|$)|NOTE(?:\s|$)|STYLE(?:\s|$)|REGION(?:\s|$))/.test(block)) continue;
+    const lines = block.split("\n");
+    const timing = lines[0]?.includes("-->") ? 0 : 1;
+    const match = /^(\S+)\s+-->\s+(\S+)(?:\s+.*)?$/.exec(lines[timing] ?? "");
+    if (!match) throw new UsageError("Transcript contains an invalid SRT/VTT cue");
+    const entities = { amp: "&", lt: "<", gt: ">", quot: '"', apos: "'", nbsp: " " };
+    const cue = lines.slice(timing + 1).join("\n").replace(/<[^>]*>/g, "").replace(/&(amp|lt|gt|quot|apos|nbsp);/g, (_, name) => entities[name]);
+    segments.push({ startTimeSec: timestamp(match[1]), endTimeSec: timestamp(match[2]), text: cue });
+  }
+  return segments;
+}
+async function readClipTranscript(path) {
+  if (!/\.(json|srt|vtt)$/i.test(path)) throw new UsageError("--clip-transcript accepts a local .json, .srt, or .vtt file");
+  let data;
+  try {
+    const file = await open(path, "r");
+    try {
+      if (!(await file.stat()).isFile()) throw new UsageError("Clip transcript must be a regular file");
+      const buffer = Buffer.alloc(MAX_FILE_BYTES + 1);
+      let size = 0;
+      while (size < buffer.length) {
+        const read = await file.read(buffer, size, buffer.length - size, null);
+        if (!read.bytesRead) break;
+        size += read.bytesRead;
+      }
+      if (size > MAX_FILE_BYTES) throw new UsageError("Clip transcript file must be at most 1 MiB");
+      data = buffer.subarray(0, size);
+    } finally {
+      await file.close();
+    }
+  } catch (error) {
+    if (error instanceof UsageError) throw error;
+    throw new UsageError("Cannot read clip transcript file; check its path and permissions");
+  }
+  let text;
+  try {
+    text = new TextDecoder("utf-8", { fatal: true }).decode(data).replace(/^\uFEFF/, "").replace(/\r\n?/g, "\n").trim();
+  } catch {
+    throw new UsageError("Clip transcript must be valid UTF-8 text");
+  }
+  let segments;
+  if (/\.json$/i.test(path)) {
+    let value;
+    try {
+      value = JSON.parse(text);
+    } catch {
+      throw new UsageError("Clip transcript must be valid JSON");
+    }
+    segments = Array.isArray(value) ? value : value && typeof value === "object" && "transcript" in value ? value.transcript : void 0;
+  } else segments = subtitleSegments(text, /\.vtt$/i.test(path));
+  if (!Array.isArray(segments) || !segments.length || segments.length > 2e3) {
+    throw new UsageError("Clip transcript must contain 1 to 2000 segments");
+  }
+  let previous = -1;
+  let totalBytes = 0;
+  return segments.map((value) => {
+    const segment = value && typeof value === "object" ? value : {};
+    const start = segment.start_time_sec ?? segment.startTimeSec;
+    const end = segment.end_time_sec ?? segment.endTimeSec;
+    const cue = segment.text;
+    if (typeof start !== "number" || !Number.isFinite(start) || typeof end !== "number" || !Number.isFinite(end) || start < 0 || end <= start || end > 604800 || start < previous) {
+      throw new UsageError("Transcript segments require ordered finite source times with end after start (within 604800 seconds)");
+    }
+    if (typeof cue !== "string" || !cue.trim() || Buffer.byteLength(cue, "utf8") > 2e3) {
+      throw new UsageError("Transcript segments require nonblank text of at most 2000 UTF-8 bytes");
+    }
+    previous = start;
+    totalBytes += Buffer.byteLength(cue, "utf8");
+    if (totalBytes > 256 * 1024) throw new UsageError("Transcript text exceeds 256 KiB");
+    return { startTimeSec: start, endTimeSec: end, text: cue.trim() };
+  });
+}
+
 // src/commands/run.ts
 var UNSUCCESSFUL_TERMINAL_STATUSES2 = /* @__PURE__ */ new Set(["FAILED", "REJECTED", "PARTIAL"]);
 var OUTPUT_ALIASES = /* @__PURE__ */ new Set([
@@ -665,6 +752,9 @@ function parseRunOptions(args) {
   const contactSheet = {};
   const image = {};
   const audiogram = {};
+  const clip = {};
+  const clipAnalysis = {};
+  let clipTranscriptFile;
   const privacyRedaction = {};
   const privacyDetectors = [];
   for (let index = 0; index < args.length; index += 1) {
@@ -794,6 +884,36 @@ function parseRunOptions(args) {
     } else if (argument === "--image-min-quality") {
       image.minQuality = boundedNumber(args, index, argument, 1, 100, true);
       index += 1;
+    } else if (argument === "--clip-start") {
+      clip.startTimeSec = boundedNumber(args, index, argument, 0, 604800);
+      index += 1;
+    } else if (argument === "--clip-duration") {
+      clip.durationSec = boundedNumber(args, index, argument, 0.1, 300);
+      index += 1;
+    } else if (argument === "--clip-layout") {
+      const value = optionValue2(args, index, argument);
+      if (value !== "original" && value !== "vertical_blur") {
+        throw new UsageError("--clip-layout must be original or vertical_blur");
+      }
+      clip.layout = value;
+      index += 1;
+    } else if (argument === "--clip-captions") {
+      clip.burnCaptions = true;
+    } else if (argument === "--clip-transcript") {
+      clipTranscriptFile = optionValue2(args, index, argument);
+      index += 1;
+    } else if (argument === "--clip-min-duration") {
+      clipAnalysis.minDurationSec = boundedNumber(args, index, argument, 1, 300);
+      index += 1;
+    } else if (argument === "--clip-max-duration") {
+      clipAnalysis.maxDurationSec = boundedNumber(args, index, argument, 1, 300);
+      index += 1;
+    } else if (argument === "--clip-count") {
+      clipAnalysis.maxCandidates = boundedNumber(args, index, argument, 1, 20, true);
+      index += 1;
+    } else if (argument === "--clip-keyword") {
+      (clipAnalysis.keywords ??= []).push(optionValue2(args, index, argument));
+      index += 1;
     } else if (argument === "--audiogram-artwork") {
       audiogram.artworkSource = optionValue2(args, index, argument);
       index += 1;
@@ -994,6 +1114,33 @@ function parseRunOptions(args) {
     }
   }
   const hasPrivacyOptions = privacyDetectors.length > 0 || Object.keys(privacyRedaction).length > 0;
+  const clipPreset = outputs.length === 1 && outputs[0]?.kind === "preset" ? outputs[0].value : void 0;
+  const hasClip = Object.keys(clip).length > 0 || clipPreset === "video_clip_v1";
+  const hasClipAnalysis = Object.keys(clipAnalysis).length > 0 || clipPreset === "clip_candidates_v1";
+  if (hasClip && (recipe || clipPreset !== "video_clip_v1" || hasClipAnalysis)) {
+    throw new UsageError("clip render options require exactly one video_clip_v1 --preset");
+  }
+  if (hasClip && (clip.startTimeSec === void 0 || clip.durationSec === void 0)) {
+    throw new UsageError("video_clip_v1 requires --clip-start and --clip-duration");
+  }
+  if (hasClipAnalysis && (recipe || clipPreset !== "clip_candidates_v1")) {
+    throw new UsageError("clip analysis options require exactly one clip_candidates_v1 --preset");
+  }
+  if ((clipAnalysis.minDurationSec ?? 15) > (clipAnalysis.maxDurationSec ?? 60)) {
+    throw new UsageError("--clip-min-duration must not exceed --clip-max-duration");
+  }
+  if ((clipAnalysis.keywords?.length ?? 0) > 20) {
+    throw new UsageError("At most 20 --clip-keyword values are supported");
+  }
+  if (clipAnalysis.keywords?.some((keyword) => !keyword.trim() || Buffer.byteLength(keyword, "utf8") > 100)) {
+    throw new UsageError("Each --clip-keyword must contain 1 to 100 UTF-8 bytes of nonblank text");
+  }
+  if (clipTranscriptFile && !hasClip && !hasClipAnalysis) {
+    throw new UsageError("--clip-transcript requires a clipping preset");
+  }
+  if (clip.burnCaptions && !clipTranscriptFile) {
+    throw new UsageError("--clip-captions requires --clip-transcript with source timestamps");
+  }
   if (hasPrivacyOptions) {
     if (recipe) throw new UsageError("privacy-redaction options cannot be combined with --recipe");
     if (privacyDetectors.length === 0) {
@@ -1021,6 +1168,9 @@ function parseRunOptions(args) {
     ...hasPlaceholderOptions ? { placeholders } : {},
     ...hasContactSheetOptions ? { contactSheet } : {},
     ...hasImageOptions ? { image } : {},
+    ...hasClip ? { clip } : {},
+    ...hasClipAnalysis ? { clipAnalysis } : {},
+    ...clipTranscriptFile ? { clipTranscriptFile } : {},
     ...hasAudiogramOptions || audiogramSelections.length > 0 ? { audiogram } : {},
     ...hasPrivacyOptions ? { privacyRedaction } : {}
   };
@@ -1047,7 +1197,7 @@ async function resolveAudiogram(value, uploads) {
     ...captionsSource === void 0 ? {} : { captionsSource, burnCaptions: true }
   };
 }
-async function resolveOutputs(selections, capabilitiesClient, animation, placeholders, contactSheet, image, audiogram, privacyRedaction) {
+async function resolveOutputs(selections, capabilitiesClient, animation, placeholders, contactSheet, image, audiogram, privacyRedaction, clip, clipAnalysis) {
   if (!privacyRedaction && !selections.some((selection) => selection.kind === "preset")) {
     return selections.map((selection) => selection.value);
   }
@@ -1084,6 +1234,8 @@ async function resolveOutputs(selections, capabilitiesClient, animation, placeho
     }
     if (audiogram) output3.audiogram = audiogram;
     if (privacyRedaction) output3.privacyRedaction = privacyRedaction;
+    if (clip) output3.clip = clip;
+    if (clipAnalysis) output3.clipAnalysis = clipAnalysis;
     return output3;
   });
 }
@@ -1146,6 +1298,14 @@ async function runCommand(args, dependencies) {
     isLocalSource || hasLocalAudiogramAsset ? "Uploading local media and creating job\u2026" : "Creating job\u2026"
   );
   try {
+    if ((options.clip || options.clipAnalysis) && !("getClipCandidates" in dependencies.jobs)) {
+      throw new UsageError("Clipping requires the MediaRuntime Node SDK release with getClipCandidates support");
+    }
+    if (options.clipTranscriptFile) {
+      const transcript = await readClipTranscript(options.clipTranscriptFile);
+      if (options.clip) options.clip.transcript = transcript;
+      if (options.clipAnalysis) options.clipAnalysis.transcript = transcript;
+    }
     const audiogram = options.audiogram === void 0 ? void 0 : await resolveAudiogram(options.audiogram, dependencies.uploads);
     const outputs = options.recipe ? void 0 : await resolveOutputs(
       options.outputs,
@@ -1155,7 +1315,9 @@ async function runCommand(args, dependencies) {
       options.contactSheet,
       options.image,
       audiogram,
-      options.privacyRedaction
+      options.privacyRedaction,
+      options.clip,
+      options.clipAnalysis
     );
     const params = {
       source: options.source,
@@ -2032,7 +2194,7 @@ async function runTriggerCommand(args, dependencies = {}) {
     writeStdout: dependencies.writeStdout ?? ((text) => process.stdout.write(text))
   };
   const secret = await resolveSecret(parsed, deps);
-  const timestamp = Math.floor(deps.now() / 1e3);
+  const timestamp2 = Math.floor(deps.now() / 1e3);
   const unique = deps.randomUUID();
   const eventId = `evt_cli_${unique}`;
   const jobId = parsed.jobId ?? `job_cli_${unique}`;
@@ -2041,9 +2203,9 @@ async function runTriggerCommand(args, dependencies = {}) {
     eventId,
     jobId,
     accountId,
-    timestamp
+    timestamp: timestamp2
   });
-  const signed = signSyntheticWebhook(payload, { eventId, timestamp, secret });
+  const signed = signSyntheticWebhook(payload, { eventId, timestamp: timestamp2, secret });
   const response = await deps.fetch(parsed.destination, {
     method: "POST",
     headers: signed.headers,
@@ -2117,7 +2279,7 @@ function createActivityIndicator(write, enabled) {
 }
 
 // src/cli.ts
-var VERSION = "1.2.0";
+var VERSION = "1.4.0";
 var HELP = `MediaRuntime CLI
 
 Usage:
@@ -2133,6 +2295,11 @@ Usage:
       [--image-width PX] [--image-height PX] [--image-mode fit|fill|cover|contain]
       [--image-format jpg|png|webp|avif] [--image-quality N]
       [--image-max-bytes N] [--image-min-quality N]
+    Clip render: --preset video_clip_v1 --clip-start SEC --clip-duration SEC
+      [--clip-layout original|vertical_blur] [--clip-transcript <plan.json|captions.srt|captions.vtt>] [--clip-captions]
+    Clip suggestions: --preset clip_candidates_v1 [--clip-min-duration SEC]
+      [--clip-max-duration SEC] [--clip-count 1..20] [--clip-keyword TEXT]
+      [--clip-transcript <plan.json|captions.srt|captions.vtt>]
     Audiogram preset: --audiogram-artwork <source> [--audiogram-captions <source>]
       [--audiogram-layout square|portrait|landscape]
       [--audiogram-fit contain|cover|blurred_background]