Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Warn when a video input declares alpha but decodes fully opaque

Open
  • Is something wrong?
#3,226 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
65/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Quiet
Tech stack
typescript
Domain
audio-video-rtc

Research direction

Start by tracing the existing video-probing path around VideoMetadata.hasAlpha and the libvpx-vp9 alpha extraction mentioned in the issue. Use the provided ffmpeg alphaextract command to compare decoded alpha, and decide whether to inspect the first frame or a sample. Done means a warning identifies declared-but-fully-opaque alpha without blocking rendering.

Written by the indexing model from the issue text.

Description

triage/needs-triage
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

Dominant language
TypeScript
Stars
54.1k
Forks
4.9k
Avg merge
7h 29m
Merged PRs (30d)
778

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from heygen-com/hyperframes

All issues in heygen-com/hyperframes

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.