Skip to content

render: fix WebM overlay alpha and ffmpeg 8 subtitles filter syntax #102

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wdeynes wants to merge 1 commit into
base: main
Choose a base branch
from
+14 −3
Open

render: fix WebM overlay alpha and ffmpeg 8 subtitles filter syntax #102

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 14 additions & 3 deletions helpers/render.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -515,6 +515,11 @@ def build_final_composite(
inputs: list[str] = ["-i", str(base_path)]
for ov in overlays:
ov_path = resolve_path(ov["file"], edit_dir)
# WebM/VP9 alpha lives in a side-channel that ffmpeg's native vp9
# decoder ignores; force libvpx-vp9 so transparent overlays stay
# transparent instead of compositing as opaque black.
if ov_path.suffix.lower() == ".webm":
inputs += ["-c:v", "libvpx-vp9"]
Comment on lines +521 to +522

@cubic-dev-ai cubic-dev-ai Bot Jul 4, 2026 •
edited
Loading

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: Forcing the libvpx-vp9 decoder on every .webm overlay based only on file extension introduces a codec-compatibility regression. WebM is a container that can hold VP8 as well as VP9, and libvpx-vp9 is registered in FFmpeg exclusively for VP9 (AV_CODEC_ID_VP9)—it cannot decode VP8 streams. If a .webm overlay happens to contain VP8 (or another codec), ffmpeg will fail to open the input and abort compositing. Previously ffmpeg auto-selected the correct decoder, so this change narrows acceptable inputs and could break existing workflows. Consider probing the actual codec (e.g., via ffprobe) before selecting the decoder, or constraining the forced decoder to files verified as VP9.

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

<comment>Forcing the `libvpx-vp9` decoder on every `.webm` overlay based only on file extension introduces a codec-compatibility regression. WebM is a container that can hold VP8 as well as VP9, and `libvpx-vp9` is registered in FFmpeg exclusively for VP9 (`AV_CODEC_ID_VP9`)—it cannot decode VP8 streams. If a `.webm` overlay happens to contain VP8 (or another codec), ffmpeg will fail to open the input and abort compositing. Previously ffmpeg auto-selected the correct decoder, so this change narrows acceptable inputs and could break existing workflows. Consider probing the actual codec (e.g., via `ffprobe`) before selecting the decoder, or constraining the forced decoder to files verified as VP9.</comment>

<file context>
@@ -515,6 +515,11 @@ def build_final_composite(
+        # WebM/VP9 alpha lives in a side-channel that ffmpeg's native vp9
+        # decoder ignores; force libvpx-vp9 so transparent overlays stay
+        # transparent instead of compositing as opaque black.
+        if ov_path.suffix.lower() == ".webm":
+            inputs += ["-c:v", "libvpx-vp9"]
         inputs += ["-i", str(ov_path)]
</file context>
Suggested change
if ov_path.suffix.lower() == ".webm":
inputs += ["-c:v", "libvpx-vp9"]
if ov_path.suffix.lower() == ".webm":
# Probe to ensure we only force libvpx-vp9 for actual VP9 streams.
probe = subprocess.run(
["ffprobe", "-v", "error", "-select_streams", "v:0",
"-show_entries", "stream=codec_name", "-of",
"default=noprint_wrappers=1:nokey=1", str(ov_path)],
capture_output=True, text=True,
)
if probe.returncode == 0 and probe.stdout.strip() == "vp9":
inputs += ["-c:v", "libvpx-vp9"]
Fix with cubic

inputs += ["-i", str(ov_path)]

filter_parts: list[str] = []
Expand All @@ -538,9 +543,15 @@ def build_final_composite(
# Subtitles LAST — Rule 1
if has_subs:
subs_abs = str(subtitles_path.resolve()).replace(":", r"\:").replace("'", r"\'")
filter_parts.append(
f"{current}subtitles='{subs_abs}':force_style='{SUB_FORCE_STYLE}'[outv]"
)
# filename= (named option) is required: ffmpeg 8's filtergraph parser
# rejects the positional quoted form when the path needs quoting.
if subtitles_path.suffix.lower() == ".ass":
# ASS files carry their own styles — force_style would clobber them.
filter_parts.append(f"{current}subtitles=filename='{subs_abs}'[outv]")
else:
filter_parts.append(
f"{current}subtitles=filename='{subs_abs}':force_style='{SUB_FORCE_STYLE}'[outv]"
)
out_label = "[outv]"
else:
# Rename the last overlay output to [outv] for consistency
Expand Down