{"record":{"id":"b74d88d327121cc9","repo":"heygen-com/hyperframes","slug":"background-output-must-be-webm-or-mov-png-is","errorCode":null,"errorMessage":"--background-output must be .webm or .mov; .png is only valid for single-image inputs.","messagePattern":"--background-output must be \\.webm or \\.mov; \\.png is only valid for single-image inputs\\.","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/cli/src/background-removal/pipeline.ts","lineNumber":260,"sourceCode":"      `Image input requires a .png output (got ${extname(outputPath)}). Use a video input for .webm/.mov.`,\n    );\n  }\n  if (inputKind === \"video\" && format === \"png\") {\n    throw new Error(\n      `Video input requires a .webm or .mov output (got .png). Use an image input for .png.`,\n    );\n  }\n\n  let bgFormat: OutputFormat | undefined;\n  if (backgroundOutputPath) {\n    if (inputKind === \"image\") {\n      throw new Error(\n        \"--background-output is not supported for image inputs. Use a video input (mp4/mov/webm) to produce both a cutout and a background plate.\",\n      );\n    }\n    bgFormat = inferOutputFormat(backgroundOutputPath);\n    if (bgFormat === \"png\") {\n      throw new Error(\n        \"--background-output must be .webm or .mov; .png is only valid for single-image inputs.\",\n      );\n    }\n  }\n\n  return { format, inputKind, bgFormat };\n}\n\nexport async function render(options: RenderOptions): Promise<RenderResult> {\n  const ffmpegPath = findFFmpeg();\n  if (!ffmpegPath || !findFFprobe()) {\n    throw new Error(`ffmpeg and ffprobe are required. Install: ${getFFmpegInstallHint()}`);\n  }\n\n  const { format, bgFormat } = resolveRenderTargets(\n    options.inputPath,\n    options.outputPath,\n    options.backgroundOutputPath,","sourceCodeStart":242,"sourceCodeEnd":278,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/cli/src/background-removal/pipeline.ts#L242-L278","documentation":"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.","triggerScenarios":"Calling render({ inputPath: 'clip.mp4', outputPath: 'cutout.webm', backgroundOutputPath: 'bg.png' }) — backgroundOutputPath ending in .png.","commonSituations":"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.","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."],"exampleFix":"// before\nawait render({\n  inputPath: 'clip.mp4',\n  outputPath: 'cutout.webm',\n  backgroundOutputPath: 'bg.png', // rejected\n});\n// after\nawait render({\n  inputPath: 'clip.mp4',\n  outputPath: 'cutout.webm',\n  backgroundOutputPath: 'bg.webm',\n});","handlingStrategy":"validation","validationCode":"function assertBgNotPng(bgPath: string) {\n  if (extname(bgPath).toLowerCase() === '.png') {\n    throw new Error('--background-output must be .webm or .mov.');\n  }\n}\nif (options.backgroundOutputPath) assertBgNotPng(options.backgroundOutputPath);\nawait render(options);","typeGuard":"function bgExtValid(bgPath: string): boolean {\n  const ext = extname(bgPath).toLowerCase();\n  return ext === '.webm' || ext === '.mov';\n}","tryCatchPattern":null,"preventionTips":["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."],"tags":["validation","background-removal","format-mismatch","pre-io"],"backgroundTag":null,"analyzedSha":"c2996c8626135db5253519359d8a063d3bafad8d","analyzedAt":"2026-08-12T22:18:56.877Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}