"Alpha channel (transparent WebM) is not composited during render — shows opaque black instead

[Didi-1962]

Describe the bug

Per the "Remove Background" guide (https://hyperframes.heygen.com/guides/remove-background), a transparent VP9 WebM placed in a

Environment

• hyperframes CLI: 0.7.106
• OS: Ubuntu (WSL2)
• Node: v22.23.2
• Render mode: local (npx hyperframes render -o output.mp4), default settings
• Also reproduced via HeyGen's cloud renderer (POST /v3/hyperframes/renders, format: "mp4") — same result

Repro See linked repo. Two test videos: a solid-color opaque clip composites correctly (top layer shows properly over bottom layer — rules out a data-track-index/z-index/stacking issue). Swapping the top layer for a confirmed-alpha WebM (alpha_mode=1 tag verified via ffprobe) makes the "transparent" region render as solid black instead of showing the background layer through it.

Expected Red square visible, floating over the green background clip everywhere else.

Actual Red square visible, but everywhere else is solid black — the green background is completely hidden.

Question Is there an additional attribute/setup required for a

Link to reproduction

https://github.com/Didi-1962/hyperframes-alpha-bug-repro

Steps to reproduce

1. Clone the repo above
2. cd into the repo
3. Run npx hyperframes render -o output.mp4
4. Extract a frame from output.mp4 partway through (e.g. ffmpeg -i output.mp4 -vf "select=eq(n\,50)" -vframes 1 frame.png)
5. Observe: red square visible, but background is solid black instead of the green broll.mp4 showing through

Expected behavior

Red square visible, floating over the green background clip everywhere else.

Actual behavior

Red square visible, but everywhere else is solid black — the green background is completely hidden.

Environment

- hyperframes CLI: 0.7.106
- OS: Ubuntu (WSL2 on Windows)
- Node: v22.23.2
- Render mode: local (Puppeteer + system FFmpeg), default settings
- Also reproduced via HeyGen's cloud renderer (POST /v3/hyperframes/renders, format: "mp4") with the same composition — same result

Additional context

No response

[jrusso1020]

Thanks for the repro repo, that made this quick to test.

The short version: test_avatar_transparent.webm has no alpha data in it. It carries the ALPHA_MODE=1 tag, but the pixels behind it are opaque.

Decoding it with the same command our extractor uses:

your file      alpha extrema (255, 255)   corner pixel (0, 0, 0, 255)   <- opaque black
control        alpha extrema (0, 255)     corner pixel (0, 0, 0, 0)     <- real transparency

The control is a VP9 alpha WebM I encoded with -pix_fmt yuva420p. ffprobe describes it identically to yours, pix_fmt=yuv420p plus an alpha_mode tag, and its transparency survives the same decode. So the black you are seeing is the actual content of the file, not something we flatten during compositing.

The trap here is a fair one: alpha_mode=1 is metadata, and it can outlive the alpha it describes. A remux in particular can keep the tag while dropping the BlockAdditional sidecar that holds the alpha plane. Your file's tag is uppercase ALPHA_MODE where ffmpeg writes lowercase, and it carries an mkvmerge-style DURATION tag, so something rewrapped it after encoding.

How did you produce that WebM? Specifically, did it come from our remove-background path, or from your own ffmpeg/encoder step? If ours produced it, that is a bug on our side and I want to chase it there instead.

To check any file yourself:

ffmpeg -c:v libvpx-vp9 -i in.webm -vf alphaextract -frames:v 1 out.png

A uniformly white out.png means no transparency; a black-and-white one means real alpha.

Separately, we should be telling you this rather than making you build a repro. I will open an issue for a warning when an input declares alpha but decodes fully opaque.

— Rames Jusso

[Didi-1962]

Thanks for digging in so quickly, and for the exact repro command — really appreciated.

You're right about the test file. I confirmed it myself with your alphaextract check:

Alpha extrema: (255, 255)

Fully opaque, despite the ALPHA_MODE=1 tag.

To answer your question directly: that WebM did not come from your remove-background path or from HeyGen's avatar API. I generated it myself as a minimal synthetic test file, with:

ffmpeg -f lavfi -i "color=c=black@0.0:s=480x854:d=5" \
  -vf "drawbox=x=140:y=300:w=200:h=200:color=red@1.0:t=fill,format=yuva420p" \
  -c:v libvpx-vp9 -pix_fmt yuva420p -metadata:s:v:0 alpha_mode=1 -auto-alt-ref 0 \
  test_avatar_transparent.webm

That's on me — my minimal test command apparently never produced real per-pixel alpha in the first place (possibly the color lavfi source not carrying @0.0 through to the encoder correctly), it just carried the tag. Sorry for the noise there.

However, since our actual use case is compositing a real HeyGen-generated avatar clip (output_format: webm from your own avatar-generation API), I went back and pulled an actual output file and ran your alphaextract check on it too, before assuming anything:

Alpha extrema: (0, 255)

Real, varying alpha — a clean head-and-shoulders silhouette mask, not a flat value. So this one genuinely does come from your side (HeyGen's own output_format: webm avatar export), and it still shows the same "invisible over background / renders as solid black" behavior when composited the same way (<video src="..."> over a background layer, per the remove-background guide).

I've replaced the test file in the repro repo with a 4-second trimmed clip from that real avatar export (stream-copied, not re-encoded, so the alpha survives the trim intact — verified again after trimming): https://github.com/Didi-1962/hyperframes-alpha-bug-repro

Same composition (index.html), just pointed at assets/real_avatar_kurz.webm instead of the synthetic file. Happy to swap in the full-length original too if that's more useful for you.