mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-19 00:18:27 +00:00
* fix(cli): every --json failure answers with one envelope, and --json only where supported
Under --json, failures came back as a bare string (`"error": "Command failed"`
from lint), a command-specific shape, or nothing at all on stdout (info,
compositions, render, snapshot, cloud get). Now every failure is
`{"ok": false, "error": {"code", "message", "hint"?}}`:
- jsonFailure() in utils/jsonError.ts builds it. The commands that printed
`{ok: false, error: "<text>"}` use it, keeping their extra fields (lint's
findings, validate's errors). A refused timeline edit now writes it to stdout
instead of stderr, and keeps its `reason` and `fix` fields.
- When a --json run fails without writing anything to stdout, cli.ts writes the
envelope itself: usage errors carry their own code (unknown_flag,
unknown_command, json_unsupported, confirmation_required), anything else is
runtime_error with the message the command printed on stderr.
--json is no longer accepted by every command. A command supports it by
declaring a `json` arg; the others reject it with exit 2 and the code
json_unsupported, instead of accepting the flag and printing prose.
The contract test now checks every command's --json path, and packages/cli
gets an AGENTS.md with the rules: stdout is data, stderr is messages, never
prompt without a TTY, exit 2 for usage errors, --json always returns an
envelope.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* fix(cli): put the real failure in the --json envelope, never the generic text or a notice
lint --json and check --json in a directory with no project answered
"message": "Command failed". The project check reports the problem, then
throws a presented "Command failed" with the real error as its cause, and the
command's own catch serialized that generic text. failureMessage() now returns
the cause, or else what the command reported through errorBox, and every
command catch that writes a --json failure uses it (lint, check, validate,
layout, snapshot, compare, grade-compare, media-treatment, tts,
remove-background, add, skills, lambda policies). compare, grade-compare and
add share failCaught() for that catch.
The boundary envelope follows the same order: the error's own message unless
it is the generic one, then its cause, then the errorBox title and hint, and
only then the stderr text. Notices (the telemetry disclosure, deprecation
lines, diag progress) are no longer captured, so validate, layout and inspect
no longer put "is deprecated" in the error message.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* fix(cli): render --json keeps human output off stdout so a failure answers with the envelope
Under --json a single render printed its header, lint findings and progress on
stdout, so a later failure such as `render --variables '{bad' --json` ended
with no JSON envelope. --json now silences that output the way --batch --json
already did, and --variables is parsed before the browser check so a bad value
fails without a Chrome download.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* fix(cli): a --strict lint abort says why, even under --json
Under --json the render is quiet, so a --strict lint abort printed nothing and
the envelope said only "Command failed". The abort is now an error box on
stderr in every mode, naming the error and warning counts and the first
finding, and the --json envelope carries the same message. Lint now runs
before the browser check, so the abort never waits on a Chrome download.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* test(cli): time the render setup cancel from the wrapper's exit
The 1 s budget started when the command did. With lint now running before the
browser check, its subprocess (about 250 ms here) sat inside that budget, and
the test failed once under load. The budget now starts when the wrapper exits,
which is the latency the test is about.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
227 lines
8.0 KiB
TypeScript
227 lines
8.0 KiB
TypeScript
import { failCommand, failUsage } from "../utils/commandResult.js";
|
||
import { defineCommand } from "../utils/defineCommand.js";
|
||
import { existsSync } from "node:fs";
|
||
import * as clack from "../ui/prompts.js";
|
||
import { c } from "../ui/colors.js";
|
||
import {
|
||
DEFAULT_MODEL,
|
||
DEVICES,
|
||
MODEL_MEMORY_MB,
|
||
isDevice,
|
||
listAvailableProviders,
|
||
modelPath,
|
||
selectProviders,
|
||
} from "../background-removal/manager.js";
|
||
import { DEFAULT_QUALITY, QUALITIES, isQuality } from "../background-removal/pipeline.js";
|
||
import type { Example } from "./_examples.js";
|
||
import { RemoveBackgroundError, removeBackground } from "../api/removeBackground.js";
|
||
import { failureMessage, jsonFailure } from "../utils/jsonError.js";
|
||
|
||
export const examples: Example[] = [
|
||
[
|
||
"Remove background from a video, output transparent VP9 WebM (default)",
|
||
"hyperframes remove-background avatar.mp4 -o transparent.webm",
|
||
],
|
||
[
|
||
"Output ProRes 4444 .mov for editing round-trip",
|
||
"hyperframes remove-background avatar.mp4 -o transparent.mov",
|
||
],
|
||
[
|
||
"Remove background from a single image, output transparent PNG",
|
||
"hyperframes remove-background portrait.jpg -o cutout.png",
|
||
],
|
||
[
|
||
"Separate the layers — emit both the cutout and an inverse-alpha background plate (subject region transparent)",
|
||
"hyperframes remove-background avatar.mp4 -o subject.webm --background-output plate.webm",
|
||
],
|
||
[
|
||
"Force CPU (skip CoreML/CUDA)",
|
||
"hyperframes remove-background avatar.mp4 -o transparent.webm --device cpu",
|
||
],
|
||
[
|
||
"Smaller file at the cost of color match (text-behind-subject won't blend as cleanly)",
|
||
"hyperframes remove-background avatar.mp4 -o transparent.webm --quality fast",
|
||
],
|
||
[
|
||
"Visually-lossless WebM (master / re-encode source)",
|
||
"hyperframes remove-background avatar.mp4 -o transparent.webm --quality best",
|
||
],
|
||
["Show detected providers without rendering", "hyperframes remove-background --info"],
|
||
];
|
||
|
||
export default defineCommand({
|
||
meta: {
|
||
name: "remove-background",
|
||
description:
|
||
"Remove background from a video or image using a local AI model — outputs transparent WebM, ProRes 4444, or PNG",
|
||
},
|
||
args: {
|
||
input: {
|
||
type: "positional",
|
||
description: "Source video (.mp4/.mov/.webm/.mkv) or image (.jpg/.png/.webp)",
|
||
required: false,
|
||
},
|
||
output: {
|
||
type: "string",
|
||
description: "Output path. Format inferred from extension: .webm (default), .mov, .png",
|
||
alias: "o",
|
||
},
|
||
"background-output": {
|
||
type: "string",
|
||
description:
|
||
"Optional second output path for the inverse-alpha background plate (subject region transparent, original surroundings opaque). Hole-cut, not inpainted — composite something underneath to fill the hole. Must be .webm or .mov; not allowed for image inputs.",
|
||
alias: "b",
|
||
},
|
||
device: {
|
||
type: "string",
|
||
description: `Execution provider: ${DEVICES.join(", ")}`,
|
||
default: "auto",
|
||
},
|
||
quality: {
|
||
type: "string",
|
||
description: `Encoder quality preset for .webm output: ${QUALITIES.join(", ")} (default: ${DEFAULT_QUALITY}). Higher quality = closer color match when overlaying on the source mp4, larger file. Ignored for .mov / .png.`,
|
||
default: DEFAULT_QUALITY,
|
||
},
|
||
info: {
|
||
type: "boolean",
|
||
description: "Print detected execution providers and exit (no render)",
|
||
default: false,
|
||
},
|
||
json: {
|
||
type: "boolean",
|
||
description: "Output result as JSON",
|
||
default: false,
|
||
},
|
||
},
|
||
async run({ args }) {
|
||
if (args.info) {
|
||
return showInfo(args.json);
|
||
}
|
||
if (!args.input) {
|
||
console.error(
|
||
c.error(
|
||
"Input file is required. Run `hyperframes remove-background --info` for providers.",
|
||
),
|
||
);
|
||
failUsage();
|
||
}
|
||
if (!args.output) {
|
||
console.error(c.error("--output (-o) is required. Use a .webm, .mov, or .png path."));
|
||
failUsage();
|
||
}
|
||
if (!isDevice(args.device)) {
|
||
console.error(
|
||
c.error(`Invalid --device '${String(args.device)}'. Use: ${DEVICES.join(", ")}.`),
|
||
);
|
||
failUsage();
|
||
}
|
||
if (!isQuality(args.quality)) {
|
||
console.error(
|
||
c.error(`Invalid --quality '${String(args.quality)}'. Use: ${QUALITIES.join(", ")}.`),
|
||
);
|
||
failUsage();
|
||
}
|
||
|
||
const spin = args.json ? null : clack.spinner();
|
||
spin?.start("Preparing background-removal pipeline...");
|
||
|
||
try {
|
||
const result = await removeBackground({
|
||
input: args.input,
|
||
output: args.output,
|
||
backgroundOutput: args["background-output"],
|
||
device: args.device,
|
||
quality: args.quality,
|
||
onProgress: (event) => {
|
||
if (event.kind === "info") {
|
||
spin?.message(event.message);
|
||
} else if (event.kind === "metadata") {
|
||
const dims = `${event.width}×${event.height}`;
|
||
const frames = event.frameCount ? ` · ${event.frameCount} frames` : "";
|
||
spin?.message(`Source ${dims} @ ${event.fps.toFixed(0)}fps${frames}`);
|
||
} else if (event.kind === "frame") {
|
||
const pct = event.total ? ` (${Math.floor((100 * event.index) / event.total)}%)` : "";
|
||
spin?.message(
|
||
`Frame ${event.index}${event.total ? `/${event.total}` : ""}${pct} — ${Math.round(event.avgMsPerFrame)}ms/frame avg`,
|
||
);
|
||
}
|
||
},
|
||
});
|
||
|
||
if (args.json) {
|
||
console.log(
|
||
JSON.stringify({
|
||
ok: true,
|
||
outputPath: result.outputPath,
|
||
...(result.backgroundOutputPath
|
||
? { backgroundOutputPath: result.backgroundOutputPath }
|
||
: {}),
|
||
framesProcessed: result.framesProcessed,
|
||
durationSeconds: Number(result.durationSeconds.toFixed(2)),
|
||
avgMsPerFrame: Number(result.avgMsPerFrame.toFixed(1)),
|
||
provider: result.provider,
|
||
format: result.format,
|
||
}),
|
||
);
|
||
} else {
|
||
const fpsThroughput = result.durationSeconds
|
||
? (result.framesProcessed / result.durationSeconds).toFixed(1)
|
||
: "n/a";
|
||
const outputs = result.backgroundOutputPath
|
||
? `${c.accent(result.outputPath)} + ${c.accent(result.backgroundOutputPath)}`
|
||
: c.accent(result.outputPath);
|
||
spin?.stop(
|
||
c.success(
|
||
`Removed background from ${c.accent(String(result.framesProcessed))} frames in ${result.durationSeconds.toFixed(1)}s (${fpsThroughput} fps, ${c.accent(result.provider)}) → ${outputs}`,
|
||
),
|
||
);
|
||
}
|
||
} catch (err) {
|
||
const message = failureMessage(err);
|
||
if (args.json) {
|
||
console.log(JSON.stringify(jsonFailure("runtime_error", message)));
|
||
} else {
|
||
spin?.stop(c.error(`Background removal failed: ${message}`));
|
||
}
|
||
failCommand(1, pipelineError(err));
|
||
}
|
||
},
|
||
});
|
||
|
||
/** The pipeline's own error, which the command reported before the API wrapped it. */
|
||
function pipelineError(err: unknown): unknown {
|
||
return err instanceof RemoveBackgroundError ? err.cause : err;
|
||
}
|
||
|
||
async function showInfo(json: boolean): Promise<void> {
|
||
const providers = listAvailableProviders();
|
||
const auto = selectProviders("auto");
|
||
const cached = existsSync(modelPath());
|
||
|
||
if (json) {
|
||
console.log(
|
||
JSON.stringify({
|
||
defaultModel: DEFAULT_MODEL,
|
||
modelCached: cached,
|
||
modelPath: modelPath(),
|
||
peakMemoryMb: MODEL_MEMORY_MB[DEFAULT_MODEL],
|
||
availableProviders: providers,
|
||
autoProvider: auto.label,
|
||
}),
|
||
);
|
||
return;
|
||
}
|
||
|
||
console.log(c.bold("hyperframes remove-background — system info"));
|
||
console.log("");
|
||
console.log(` ${c.dim("Default model:")} ${c.accent(DEFAULT_MODEL)}`);
|
||
console.log(` ${c.dim("Peak memory:")} ~${MODEL_MEMORY_MB[DEFAULT_MODEL]} MB`);
|
||
console.log(
|
||
` ${c.dim("Weights cached:")} ${cached ? c.success("yes") : c.dim("no (will download on first run)")}`,
|
||
);
|
||
console.log(` ${c.dim("Cache path:")} ${modelPath()}`);
|
||
console.log("");
|
||
console.log(` ${c.dim("Available providers:")} ${providers.join(", ")}`);
|
||
console.log(` ${c.dim("Auto-selected:")} ${c.accent(auto.label)}`);
|
||
}
|