Video input requires a .webm or .mov output (got .png). Use

Error message

Video input requires a .webm or .mov output (got .png). Use an image input for .png.

What it means

Thrown by resolveRenderTargets() when a video input is paired with a .png output. PNG output is a single still with alpha; a video has many frames, so encoding it to one PNG would silently drop all but one frame. The guard rejects the combination up front rather than producing a misleading single-frame result.

Source

Thrown at packages/cli/src/background-removal/pipeline.ts:246

/**
 * Resolve and validate the input/output combination before any I/O. Pure;
 * exported so unit tests can pin the error messages without spawning ffmpeg.
 */
export function resolveRenderTargets(
  inputPath: string,
  outputPath: string,
  backgroundOutputPath?: string,
): RenderTargets {
  const format = inferOutputFormat(outputPath);
  const inputKind = inferInputKind(inputPath);

  if (inputKind === "image" && format !== "png") {
    throw new Error(
      `Image input requires a .png output (got ${extname(outputPath)}). Use a video input for .webm/.mov.`,
    );
  }
  if (inputKind === "video" && format === "png") {
    throw new Error(
      `Video input requires a .webm or .mov output (got .png). Use an image input for .png.`,
    );
  }

  let bgFormat: OutputFormat | undefined;
  if (backgroundOutputPath) {
    if (inputKind === "image") {
      throw new Error(
        "--background-output is not supported for image inputs. Use a video input (mp4/mov/webm) to produce both a cutout and a background plate.",
      );
    }
    bgFormat = inferOutputFormat(backgroundOutputPath);
    if (bgFormat === "png") {
      throw new Error(
        "--background-output must be .webm or .mov; .png is only valid for single-image inputs.",
      );
    }
  }

View on GitHub (pinned to c2996c8626)

Solutions

Use a .webm or .mov output for video inputs to get the per-frame alpha matte.
If you only need one PNG from a video, extract it directly with ffmpeg: `ffmpeg -i clip.mp4 -frames:v 1 frame.png`.
Switch the input to a single image if you truly want a .png cutout.

Example fix

// before
await render({ inputPath: 'clip.mp4', outputPath: 'clip.png' });
// after
await render({ inputPath: 'clip.mp4', outputPath: 'clip.webm' });

Defensive patterns

Strategy: validation

Validate before calling

function assertVideoOutputNotPng(inputPath: string, outputPath: string) {
  const inExt = extname(inputPath).toLowerCase();
  const isVideo = ['.mp4','.mov','.webm','.mkv','.avi'].includes(inExt);
  const outExt = extname(outputPath).toLowerCase();
  if (isVideo && outExt === '.png') {
    throw new Error('Video input requires .webm or .mov output; use an image input for .png.');
  }
}
assertVideoOutputNotPng(options.inputPath, options.outputPath);
await render(options);

Type guard

function isVideoPngMismatch(inputPath: string, outputPath: string): boolean {
  const isVideo = ['.mp4','.mov','.webm','.mkv','.avi'].includes(extname(inputPath).toLowerCase());
  return isVideo && extname(outputPath).toLowerCase() === '.png';
}

Prevention

Never pair a video input with a .png output in templates.
For first-frame PNG extraction, use ffmpeg directly instead of the background-removal API.
Add a pre-flight assertion in your render orchestrator.

When it happens

Trigger: Calling render({ inputPath: 'clip.mp4', outputPath: 'frame.png' }) — any video input with a .png output path. resolveRenderTargets detects (video, format===png).

Common situations: User wants the first frame as a PNG but the API is not designed for that (use ffmpeg directly); a pipeline template hardcodes .png outputs; confusion between the still-image and video modes of the tool.

Related errors

AI-assisted analysis of heygen-com/hyperframes@c2996c8626 (2026-08-12). Data as JSON: /api/errors/f936906fd582330d. Report an issue: GitHub.