fix(engine): warn when a video input declares alpha but decodes opaque - #3259
Open
santhiprakash wants to merge 1 commit into
Open
fix(engine): warn when a video input declares alpha but decodes opaque#3259santhiprakash wants to merge 1 commit into
santhiprakash wants to merge 1 commit into
Conversation
- Problem: a video input whose alpha_mode=1 tag outlives its alpha plane (a remux drops the BlockAdditional sidecar while keeping the tag) composites as a solid rectangle, and nothing tells the user their file, not the renderer, is the problem (heygen-com#3220 / heygen-com#3226). - Fix: during extraction preflight, when an input declares alpha (hasAlpha) and its codec can carry alpha, sample the decoded alpha plane (up to 3 frames at 8x8 rgba, bounded 30s, ~768-byte ceiling). If uniformly opaque, emit a non-blocking stderr warning naming the file with the re-export remedy. Inconclusive probes stay silent; opaque full-frame backgrounds are legitimate and never fail the render. - Verification: 8 new unit tests (byte logic + message); engine suite 1483/1487 with 4 pre-existing failures on clean main (missing hdr-regression PNG fixture in this clone); typecheck/lint/format clean; real-fixture checks: lying-tag WebM warns, genuine-alpha WebM stays silent, both agree with ffmpeg alphaextract. Signed-off-by: Santhi Prakash <b.santhiprakash@gmail.com>
santhiprakash
force-pushed
the
fix/engine-input-alpha-opaque-warning
branch
from
August 13, 2026 05:17
ccfb862 to
76fd3cc
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Implements #3226 — a video input whose
alpha_mode=1tag outlives its alpha plane composites as a solid opaque rectangle, and nothing tells the user their file, not the renderer, is the problem (#3220 is the worked example).What
packages/engine/src/utils/alphaPlaneProbe.ts(new):probeInputAlphaPlanesamples a video input's decoded alpha plane (forcedlibvpx-vp9input decoder, up to 3 frames at 8x8 rgba, 30s bound, ~768-byte ceiling);sampledRgbaAlphaIsFullyOpaquedecides uniformly-opaque / transparent / inconclusive. Sibling of the CLI's post-renderwebmAlphaCheck.sampledAlphaIsFullyOpaque, rebuilt for the engine (async viarunFfmpeg, temp-file output).packages/engine/src/services/videoFrameExtractor.ts: during extraction preflight, for every input whose metadata declares alpha (hasAlpha) and whose codec can carry alpha (vp9/vp8/prores), run the probe. If the alpha plane is uniformly opaque, emit a non-blocking stderr warning naming the file with the re-export remedy (deduped per src, abort-aware).packages/engine/src/utils/alphaPlaneProbe.test.ts(new): 8 unit tests covering the byte logic and the warning text.Why
alpha_mode=1is container metadata that can outlive the alpha it describes — a remux can drop the BlockAdditional sidecar while keeping the tag. Warning only, never an error: an opaque video used as a full-frame background is legitimate, and an inconclusive probe stays silent. Sampling a few frames rather than first-frame-only is an explicit choice (the decision #3226 asked to make): it catches a clip that is opaque at the head and transparent later. The engine-level hook covers every render path (local CLI, Docker, cloud).Verification
hdr-regressionPNG fixture and the@hyperframes/core/audio-fx-runtimesubpath, both absent locally; confirmed by stashing the change and re-running).bun run lint0 warnings;bun run format:checkclean on the changed files.ALPHA_MODE=1but no alpha plane → warns; a genuineyuva420pVP9 WebM (alpha 128) → silent; both agree with thealphaextractcross-check from Warn when a video input declares alpha but decodes fully opaque #3226.Notes
--no-verify: this checkout's lefthooktypecheck/fallowsteps fail on clean upstream main (missing generated artifacts), so they were skipped locally; the staged files themselves pass the hook's lint + format steps. CI runs the authoritative checks.