--background-output must be .webm or .mov; .png is only vali

Error message

--background-output must be .webm or .mov; .png is only valid for single-image inputs.

What it means

Thrown by resolveRenderTargets() when backgroundOutputPath has a .png extension. The background plate is an inverse-alpha video (transparent where the subject was), so it must be a format that supports alpha over time: .webm (VP9 alpha) or .mov (ProRes 4444). A single .png plate is not a supported output of this feature — .png is reserved for the single-image foreground cutout only.

Source

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

      `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.",
      );
    }
  }

  return { format, inputKind, bgFormat };
}

export async function render(options: RenderOptions): Promise<RenderResult> {
  const ffmpegPath = findFFmpeg();
  if (!ffmpegPath || !findFFprobe()) {
    throw new Error(`ffmpeg and ffprobe are required. Install: ${getFFmpegInstallHint()}`);
  }

  const { format, bgFormat } = resolveRenderTargets(
    options.inputPath,
    options.outputPath,
    options.backgroundOutputPath,

View on GitHub (pinned to c2996c8626)

Solutions

Change the backgroundOutputPath extension to .webm (for web) or .mov (for editing).
If you actually want a single still, use an image input and drop backgroundOutputPath entirely.
Keep the two output formats aligned with the docs: foreground and plate both .webm or both .mov for video inputs.

Example fix

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

Defensive patterns

Strategy: validation

Validate before calling

function assertBgNotPng(bgPath: string) {
  if (extname(bgPath).toLowerCase() === '.png') {
    throw new Error('--background-output must be .webm or .mov.');
  }
}
if (options.backgroundOutputPath) assertBgNotPng(options.backgroundOutputPath);
await render(options);

Type guard

function bgExtValid(bgPath: string): boolean {
  const ext = extname(bgPath).toLowerCase();
  return ext === '.webm' || ext === '.mov';
}

Prevention

Default the background output extension to match the foreground (.webm/.mov).
Never reuse a .png foreground path for the background option.
Validate both output paths in a single pre-flight check.

When it happens

Trigger: Calling render({ inputPath: 'clip.mp4', outputPath: 'cutout.webm', backgroundOutputPath: 'bg.png' }) — backgroundOutputPath ending in .png.

Common situations: User assumes the plate is a still and names it .png; copy-paste of the foreground .png path into the background option; default output template that uses .png for both.

Related errors

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