Problem
A video whose container says it has alpha, but whose alpha plane decodes fully opaque, composites as a solid black rectangle over whatever is beneath it. We render it correctly — there is nothing to see through — but nothing anywhere tells the user their file is the problem, so it presents as a rendering bug.
#3220 is the worked example. The reporter built a repro repository with an opaque control clip, tested both the local CLI and the cloud renderer, and verified alpha_mode=1 with ffprobe before filing. They still could not reach the answer, because the tag they checked is exactly the thing that lies.
alpha_mode=1 is metadata and can outlive the alpha it describes. A remux can preserve the tag while dropping the BlockAdditional sidecar that carries the alpha plane, so the file keeps promising transparency it no longer contains.
Why this is cheap for us to catch
We already probe every video input, and VideoMetadata.hasAlpha already exists (pixelFormatHasAlpha(pixelFormat) || alphaMode === "1"). We also already extract alpha-capable codecs to PNG through libvpx-vp9, so a decoded frame with an alpha channel is in hand on this path anyway.
The missing step is noticing that the alpha channel is uniformly opaque and saying so.
Proposed
When a video input declares alpha but its decoded alpha plane is uniformly 255, emit a warning naming the file, something to the effect of:
avatar.webm declares an alpha channel but decodes fully opaque. Transparency will not composite. If this should be transparent, re-export with -pix_fmt yuva420p and avoid remuxing afterward, which can drop the alpha sidecar while keeping the tag.
Warning only, never an error. An opaque video used as a full-frame background is perfectly legitimate, so this cannot block a render.
Worth deciding: whether to check the first frame only (cheap, catches the common case) or sample a few (catches a clip that is opaque at the head and transparent later). First-frame-only is probably the right trade, but it should be a decision rather than an accident.
Verification
Users can already check by hand, and the warning should agree with this:
ffmpeg -c:v libvpx-vp9 -i in.webm -vf alphaextract -frames:v 1 out.png
Uniformly white means no transparency. Black and white means real alpha.
Filed off #3220.
— Rames Jusso
Problem
A video whose container says it has alpha, but whose alpha plane decodes fully opaque, composites as a solid black rectangle over whatever is beneath it. We render it correctly — there is nothing to see through — but nothing anywhere tells the user their file is the problem, so it presents as a rendering bug.
#3220 is the worked example. The reporter built a repro repository with an opaque control clip, tested both the local CLI and the cloud renderer, and verified
alpha_mode=1with ffprobe before filing. They still could not reach the answer, because the tag they checked is exactly the thing that lies.alpha_mode=1is metadata and can outlive the alpha it describes. A remux can preserve the tag while dropping the BlockAdditional sidecar that carries the alpha plane, so the file keeps promising transparency it no longer contains.Why this is cheap for us to catch
We already probe every video input, and
VideoMetadata.hasAlphaalready exists (pixelFormatHasAlpha(pixelFormat) || alphaMode === "1"). We also already extract alpha-capable codecs to PNG throughlibvpx-vp9, so a decoded frame with an alpha channel is in hand on this path anyway.The missing step is noticing that the alpha channel is uniformly opaque and saying so.
Proposed
When a video input declares alpha but its decoded alpha plane is uniformly
255, emit a warning naming the file, something to the effect of:Warning only, never an error. An opaque video used as a full-frame background is perfectly legitimate, so this cannot block a render.
Worth deciding: whether to check the first frame only (cheap, catches the common case) or sample a few (catches a clip that is opaque at the head and transparent later). First-frame-only is probably the right trade, but it should be a decision rather than an accident.
Verification
Users can already check by hand, and the warning should agree with this:
Uniformly white means no transparency. Black and white means real alpha.
Filed off #3220.
— Rames Jusso