fix(render): preserve alpha on .webm overlays by forcing libvpx-vp9 decoder

[DanielOwusu]

What

build_final_composite in helpers/render.py now forces -c:v libvpx-vp9 on .webm overlay inputs so their alpha channel is honored during compositing. Other overlay formats (mp4, etc.) are unaffected.

Why

ffmpeg's native VP9 decoder decodes alpha-carrying WebM (alpha stored as a side-data plane, reported as yuv420p + ALPHA_MODE=1) to opaque yuv420p. When such a file is used as an overlay via the overlay filter, the transparent regions render as opaque black. For a full-frame transparent overlay — e.g. a captions track or lower-third exported as VP9+alpha — this turns the entire frame black and hides the base video and every overlay beneath it.

Forcing the alpha-aware libvpx-vp9 decoder on the input makes ffmpeg decode to yuva420p, so overlay transparency composites correctly.

How it showed up

Compositing an EDL whose overlays included VP9+alpha WebM layers (a transparent caption overlay and a transparent CTA lower-third) produced an output that was entirely black except for the opaque pixels of the topmost overlay. The base talking-head video and an opaque demo overlay were both hidden. Swapping in the libvpx-vp9 decoder for the .webm inputs fixed it with no other changes.

Change

     inputs: list[str] = ["-i", str(base_path)]
     for ov in overlays:
         ov_path = resolve_path(ov["file"], edit_dir)
-        inputs += ["-i", str(ov_path)]
+        # VP9/WebM overlays carry alpha as a side-data plane. ffmpeg's native vp9
+        # decoder drops it (decodes to yuv420p -> opaque), which turns a full-frame
+        # transparent overlay into an opaque black layer. Force the alpha-aware
+        # libvpx-vp9 decoder so overlay alpha is honored.
+        if ov_path.suffix.lower() == ".webm":
+            inputs += ["-c:v", "libvpx-vp9", "-i", str(ov_path)]
+        else:
+            inputs += ["-i", str(ov_path)]

Notes for reviewers

• Reproduced on ffmpeg 8.1.1 (Homebrew). Behavior of the native vp9 decoder vs libvpx-vp9 re: alpha is the root cause.
• Requires the ffmpeg build to have libvpx enabled (already required elsewhere in the project for HyperFrames/VP9 work).
• No change to behavior for non-.webm overlays.

🤖 Generated with Claude Code

---

Summary by cubic

Preserves alpha in .webm overlays by forcing the libvpx-vp9 decoder in build_final_composite, fixing black frames from VP9+alpha sources. Other overlay formats are unaffected.

• Bug Fixes
  • For .webm overlays, add -c:v libvpx-vp9 before -i so ffmpeg decodes to yuva420p and the overlay filter honors transparency.
  • Prevents opaque black output caused by the native VP9 decoder dropping alpha.

^{Written for commit 257db63. Summary will update on new commits.}

[cubic-dev-ai]

1 issue found across 1 file

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="helpers/render.py">

<violation number="1" location="helpers/render.py:522">
P1: Extension-based decoder selection for .webm files is incorrect — WebM is a container that can hold VP8, VP9, or AV1 video. Forcing `libvpx-vp9` (a VP9-only decoder) for all `.webm` files will cause ffmpeg decode failure and abort the render when the overlay uses VP8 or AV1.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Fix all with cubic | Re-trigger cubic</sub>

[cubic-dev-ai]

P1: Extension-based decoder selection for .webm files is incorrect — WebM is a container that can hold VP8, VP9, or AV1 video. Forcing libvpx-vp9 (a VP9-only decoder) for all .webm files will cause ffmpeg decode failure and abort the render when the overlay uses VP8 or AV1.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At helpers/render.py, line 522:

<comment>Extension-based decoder selection for .webm files is incorrect — WebM is a container that can hold VP8, VP9, or AV1 video. Forcing `libvpx-vp9` (a VP9-only decoder) for all `.webm` files will cause ffmpeg decode failure and abort the render when the overlay uses VP8 or AV1.</comment>

<file context>
@@ -515,7 +515,14 @@ def build_final_composite(
+        # decoder drops it (decodes to yuv420p → opaque), which turns a full-frame
+        # transparent overlay into an opaque black layer. Force the alpha-aware
+        # libvpx-vp9 decoder so overlay alpha is honored.
+        if ov_path.suffix.lower() == ".webm":
+            inputs += ["-c:v", "libvpx-vp9", "-i", str(ov_path)]
+        else:
</file context>