Skip to content

armgit / hypit

Public Imported from GitHub
0

Clone any viral video with AI agents. Not just a script, the whole workflow: swap the face, the words, the B-roll, ship 100 variants in one command, and get your 100M views.

fix(media): inspect staged Surface files without duplicate buffering

kashorin2caa49c2dd2b
diff --git a/packages/media-execution/README.md b/packages/media-execution/README.md
index ed80aab8..d1a29756 100644
--- a/packages/media-execution/README.md
+++ b/packages/media-execution/README.md
@@ -26,6 +26,13 @@ deployments can reuse the same functions to preserve stream selection, timing, c
This is not an author package, Provider, queue or Core extension. It performs no endpoint selection,
credential lookup or SVML parsing.
+`verifyCompositableSurfaceFile({ surface, path, ... })` inspects a file already staged by an execution
+owner. That owner must keep it unchanged until the call settles, including cancellation; inspection
+neither copies nor removes it. `verifyCompositableSurfaceBytes({ surface, bytes, ... })` remains a
+convenience wrapper for callers that have bytes, creates its own temporary file, and removes that
+file only after probing has settled. Both use the same decoded Surface checks and return no extra
+result facts. Filesystem paths belong to this Node execution boundary, not to Surface or Blob refs.
+
Audio gain envelopes and audible subranges are evaluated per sample after tempo/looping and Clip
fades, before the requested range is cropped. Original source and envelope progress therefore survive
local silence and range rendering. This is generic AudioProgramPlan execution, independent of author
diff --git a/packages/media-execution/src/index.ts b/packages/media-execution/src/index.ts
index fcc10457..6aa6796b 100644
--- a/packages/media-execution/src/index.ts
+++ b/packages/media-execution/src/index.ts
@@ -10,7 +10,7 @@ export {
executeTransformMedia,
} from "./execute.js";
export { parseMediaInspection } from "./probe.js";
-export { verifyCompositableSurfaceBytes } from "./surface.js";
+export { verifyCompositableSurfaceBytes, verifyCompositableSurfaceFile } from "./surface.js";
export { probeMediaToolchain } from "./toolchain.js";
export type { MediaToolchainState } from "./toolchain.js";
export type * from "./execute.js";
diff --git a/packages/media-execution/src/surface.ts b/packages/media-execution/src/surface.ts
index eea23b9d..e3737029 100644
--- a/packages/media-execution/src/surface.ts
+++ b/packages/media-execution/src/surface.ts
@@ -1,5 +1,5 @@
import { spawn } from "node:child_process";
-import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { mkdtemp, rm, stat, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
@@ -192,95 +192,101 @@ async function pixelFormatAlpha(
return result;
}
-function suffix(mediaType: string): string {
- if (mediaType === "image/png") return ".png";
- if (mediaType === "image/webp") return ".webp";
- if (mediaType === "video/webm") return ".webm";
- if (mediaType === "video/mp4") return ".mp4";
- throw new Error(`Surface media type ${mediaType} is unsupported`);
-}
-
-/**
- * Decode and verify one typed Surface before its bytes enter a renderer.
- *
- * This is an admission gate, not a second media Product. Success returns no
- * side-channel facts; anything a later graph step needs must be an explicit output.
- */
-export async function verifyCompositableSurfaceBytes(options: {
+type SurfaceInspectionOptions = {
readonly surface: CompositableSurfaceRef;
- readonly bytes: Uint8Array;
readonly ffprobePath?: string;
readonly processTimeoutMs?: number;
readonly maxProbeOutputBytes?: number;
readonly signal?: AbortSignal;
+};
+
+/** Inspect bytes supplied by callers that do not already own a staged file. */
+export async function verifyCompositableSurfaceBytes(options: SurfaceInspectionOptions & {
+ readonly bytes: Uint8Array;
+}): Promise<void> {
+ options.signal?.throwIfAborted();
+ assertCompositableSurfaceRef(options.surface);
+ assert(options.bytes.byteLength === options.surface.artifact.size,
+ `Surface ${options.surface.artifact.resource} byte size differs`);
+ const directory = await mkdtemp(join(tmpdir(), "hypit-surface-verify-"));
+ try {
+ // FFprobe detects the encoded media itself; both entry points inspect the same formats.
+ const path = join(directory, "surface");
+ await writeFile(path, options.bytes, { signal: options.signal });
+ await verifyCompositableSurfaceFile({ ...options, path });
+ } finally {
+ await rm(directory, { recursive: true, force: true }).catch(() => {});
+ }
+}
+
+/**
+ * Inspect an existing execution file without copying it. The caller owns the file
+ * and keeps it unchanged until this call settles. Success returns no side-channel facts.
+ */
+export async function verifyCompositableSurfaceFile(options: SurfaceInspectionOptions & {
+ readonly path: string;
}): Promise<void> {
const controller = new AbortController();
const signal = options.signal === undefined ? controller.signal : AbortSignal.any([controller.signal, options.signal]);
signal.throwIfAborted();
assertCompositableSurfaceRef(options.surface);
- assert(options.bytes.byteLength === options.surface.artifact.size,
+ assert((await stat(options.path)).size === options.surface.artifact.size,
`Surface ${options.surface.artifact.resource} byte size differs`);
+ signal.throwIfAborted();
const ffprobePath = options.ffprobePath ?? "ffprobe";
const timeoutMs = options.processTimeoutMs ?? 120_000;
const maxOutputBytes = options.maxProbeOutputBytes ?? 8 * 1024 * 1024;
- const directory = await mkdtemp(join(tmpdir(), "hypit-surface-verify-"));
- try {
- const path = join(directory, `surface${suffix(options.surface.artifact.mediaType)}`);
- await writeFile(path, options.bytes, { signal });
- const pending = [
- runProcess({
- executable: ffprobePath,
- argv: ["-v", "error", "-print_format", "json", "-show_streams", "-count_frames", path],
- timeoutMs,
- maxOutputBytes, signal,
- }),
- pixelFormatAlpha(ffprobePath, timeoutMs, maxOutputBytes, signal),
- ] as const;
- await Promise.allSettled(pending.map(async (job) => {
- try { return await job; } catch (error) { controller.abort(error); throw error; }
- }));
- signal.throwIfAborted();
- const [probe, formats] = await Promise.all(pending);
- const root = json(probe, "ffprobe Surface query");
- assert(Array.isArray(root.streams) && root.streams.length === 1,
- "Surface must contain exactly one visual stream and no audio or auxiliary streams");
- const stream = root.streams[0] as ProbeStream;
- assert(stream.codec_type === "video", "Surface stream is not visual");
- assert(stream.disposition?.attached_pic !== 1, "Surface cannot be an attached-picture stream");
- const width = positiveInteger(stream.width, "Surface width");
- const height = positiveInteger(stream.height, "Surface height");
- assert(width === options.surface.width && height === options.surface.height,
- "Surface decoded dimensions differ from its declaration");
- assert(stream.sample_aspect_ratio === undefined || stream.sample_aspect_ratio === "1:1",
- "Surface must use square pixels");
- assert(rotation(stream) === 0, "Surface must not depend on display rotation metadata");
- assert(stream.field_order === undefined || stream.field_order === "progressive" || stream.field_order === "unknown",
- "Surface must be progressive");
- assertSrgb(stream);
+ const pending = [
+ runProcess({
+ executable: ffprobePath,
+ argv: ["-v", "error", "-print_format", "json", "-show_streams", "-count_frames", options.path],
+ timeoutMs,
+ maxOutputBytes, signal,
+ }),
+ pixelFormatAlpha(ffprobePath, timeoutMs, maxOutputBytes, signal),
+ ] as const;
+ await Promise.allSettled(pending.map(async (job) => {
+ try { return await job; } catch (error) { controller.abort(error); throw error; }
+ }));
+ signal.throwIfAborted();
+ const [probe, formats] = await Promise.all(pending);
+ const root = json(probe, "ffprobe Surface query");
+ assert(Array.isArray(root.streams) && root.streams.length === 1,
+ "Surface must contain exactly one visual stream and no audio or auxiliary streams");
+ const stream = root.streams[0] as ProbeStream;
+ assert(stream.codec_type === "video", "Surface stream is not visual");
+ assert(stream.disposition?.attached_pic !== 1, "Surface cannot be an attached-picture stream");
+ const width = positiveInteger(stream.width, "Surface width");
+ const height = positiveInteger(stream.height, "Surface height");
+ assert(width === options.surface.width && height === options.surface.height,
+ "Surface decoded dimensions differ from its declaration");
+ assert(stream.sample_aspect_ratio === undefined || stream.sample_aspect_ratio === "1:1",
+ "Surface must use square pixels");
+ assert(rotation(stream) === 0, "Surface must not depend on display rotation metadata");
+ assert(stream.field_order === undefined || stream.field_order === "progressive" || stream.field_order === "unknown",
+ "Surface must be progressive");
+ assertSrgb(stream);
- assert(typeof stream.pix_fmt === "string" && stream.pix_fmt.length > 0,
- "Surface pixel format is absent");
- const pixelAlpha = formats.get(stream.pix_fmt);
- assert(pixelAlpha !== undefined, `Surface pixel format ${stream.pix_fmt} is unknown to ffprobe`);
- const taggedAlpha = stream.tags?.alpha_mode === "1" || stream.tags?.alpha_mode === "straight";
- const hasAlpha = pixelAlpha || taggedAlpha;
- if (options.surface.alphaMode === "straight") {
- assert(hasAlpha, "Surface declares straight alpha but its bytes carry no alpha channel");
- } else {
- assert(!hasAlpha, "Surface declares opaque pixels but its encoded format carries alpha");
- }
+ assert(typeof stream.pix_fmt === "string" && stream.pix_fmt.length > 0,
+ "Surface pixel format is absent");
+ const pixelAlpha = formats.get(stream.pix_fmt);
+ assert(pixelAlpha !== undefined, `Surface pixel format ${stream.pix_fmt} is unknown to ffprobe`);
+ const taggedAlpha = stream.tags?.alpha_mode === "1" || stream.tags?.alpha_mode === "straight";
+ const hasAlpha = pixelAlpha || taggedAlpha;
+ if (options.surface.alphaMode === "straight") {
+ assert(hasAlpha, "Surface declares straight alpha but its bytes carry no alpha channel");
+ } else {
+ assert(!hasAlpha, "Surface declares opaque pixels but its encoded format carries alpha");
+ }
- const frameCount = positiveInteger(stream.nb_read_frames ?? stream.nb_frames, "Surface frame count");
- if (options.surface.timing.kind === "still") {
- assert(frameCount === 1, "Still Surface must decode to exactly one frame");
- } else {
- assert(frameCount === options.surface.timing.frameCount,
- "Surface decoded frame count differs from its declaration");
- const rate = rational(stream.avg_frame_rate ?? stream.r_frame_rate, "Surface frame rate");
- assert(sameRational(rate, options.surface.timing.frameRate),
- "Surface decoded frame rate differs from its declaration");
- }
- } finally {
- await rm(directory, { recursive: true, force: true }).catch(() => {});
+ const frameCount = positiveInteger(stream.nb_read_frames ?? stream.nb_frames, "Surface frame count");
+ if (options.surface.timing.kind === "still") {
+ assert(frameCount === 1, "Still Surface must decode to exactly one frame");
+ } else {
+ assert(frameCount === options.surface.timing.frameCount,
+ "Surface decoded frame count differs from its declaration");
+ const rate = rational(stream.avg_frame_rate ?? stream.r_frame_rate, "Surface frame rate");
+ assert(sameRational(rate, options.surface.timing.frameRate),
+ "Surface decoded frame rate differs from its declaration");
}
}
diff --git a/packages/media-execution/test/surface.test.ts b/packages/media-execution/test/surface.test.ts
index 4aa534ea..82785b49 100644
--- a/packages/media-execution/test/surface.test.ts
+++ b/packages/media-execution/test/surface.test.ts
@@ -6,7 +6,7 @@ import assert from "node:assert/strict";
import test from "node:test";
import { setTimeout as delay } from "node:timers/promises";
-import { verifyCompositableSurfaceBytes } from "@hypit/media-execution";
+import { verifyCompositableSurfaceBytes, verifyCompositableSurfaceFile } from "@hypit/media-execution";
import type { CompositableSurfaceRef } from "@hypit/media";
const hasMediaTools = spawnSync("ffmpeg", ["-version"], { stdio: "ignore", windowsHide: true }).status === 0
@@ -46,7 +46,7 @@ function surface(bytes: Uint8Array, options: {
};
}
-test("cancelling Surface validation stops both probes without poisoning later calls", {
+test("cancelling staged Surface inspection stops both probes and preserves the caller's file", {
skip: process.platform === "win32",
}, async () => {
const directory = await mkdtemp(join(tmpdir(), "hypit-surface-cancel-"));
@@ -62,8 +62,10 @@ fs.writeFileSync(${JSON.stringify(marker)} + '-' + process.pid, '');
setInterval(() => {}, 1000);
`);
await chmod(program, 0o755);
+ const path = join(directory, "staged.png");
+ await writeFile(path, bytes);
const controller = new AbortController();
- const checking = verifyCompositableSurfaceBytes({ surface: value, bytes, ffprobePath: program,
+ const checking = verifyCompositableSurfaceFile({ surface: value, path, ffprobePath: program,
signal: controller.signal });
const rejected = assert.rejects(checking, /stop probes/u);
let pids: number[] = [];
@@ -77,6 +79,7 @@ setInterval(() => {}, 1000);
await rejected;
assert.equal(pids.length, 2);
for (const pid of pids) assert.throws(() => process.kill(pid, 0), { code: "ESRCH" });
+ assert.deepEqual([...await readFile(path)], [...bytes]);
await writeFile(program, `#!${process.execPath}
console.log(JSON.stringify(process.argv.includes('-show_pixel_formats')
? { pixel_formats: [{ name: 'rgb24', flags: { alpha: 0 } }] }
@@ -117,6 +120,14 @@ test("Surface byte admission accepts matching still/video bytes and rejects cont
await verifyCompositableSurfaceBytes({ surface: opaqueSurface, bytes: opaque });
await verifyCompositableSurfaceBytes({ surface: alphaSurface, bytes: alpha });
await verifyCompositableSurfaceBytes({ surface: videoSurface, bytes: video });
+ await verifyCompositableSurfaceFile({ surface: videoSurface, path: videoPath });
+ await assert.rejects(verifyCompositableSurfaceFile({ surface: {
+ ...videoSurface, artifact: { ...videoSurface.artifact, size: video.byteLength + 1 },
+ }, path: videoPath }), /byte size differs/u);
+ await assert.rejects(verifyCompositableSurfaceFile({ surface: {
+ ...videoSurface, width: 10,
+ }, path: videoPath }), /dimensions differ/u);
+ assert.deepEqual(await readFile(videoPath), video, "inspection never rewrites or deletes the caller's file");
await assert.rejects(
verifyCompositableSurfaceBytes({ surface: { ...opaqueSurface, width: 9 }, bytes: opaque }),