fix(video): don't draw the encoder's alignment padding in Firefox (workaround)

[rmounce]

Draft — this is a sub-optimal workaround; posting primarily for the analysis. Firefox renders WebCodecs decoder output incorrectly and, as far as we can tell, undetectably. This PR carries the pragmatic client-side mitigation plus our full findings.

Symptom: with full-frame H.264 through the 2D-canvas paths, Firefox shows an ~8px green bar at the bottom of a 1920x1080 stream from h264_vaapi or NVENC, and renders the picture vertically resampled ("skipped lines" on fine detail). Chromium is unaffected. Reproduced on Intel/VA-API and NVIDIA/NVENC.

Root cause: H.264 codes 16x16 macroblocks, so 1080 rows are always coded as 1088 with 8 padding rows cropped via SPS. The padding content is encoder-specific: x264 edge-replicates (invisible), VA-API/NVENC zero-fill (green in YUV). Firefox's canvas drawImage — and createImageBitmap — scale the frame's full backing surface, padding included, into the nominal 1080 box. So the padding shows, and every full-frame H.264 stream (x264 included) is silently resampled ~0.74% vertically in Firefox.

Why it can't be feature-detected: on these frames Firefox reports codedWidth/Height == displayWidth/Height == visibleRect == 1920x1080, format: BGRX — the padding appears nowhere. And synthetic CPU-backed VideoFrames draw correctly, so a runtime behavior probe passes while real decoder output leaks. We tried, in order: source-rect draw, visibleRect presence gate, synthetic-frame behavior probe, coded>display gate — none can fire. Only a UA gate works.

The workaround: gated on Firefox UA, overscan the draw destination to the padded size computed from macroblock alignment (ceil16), so the visible image maps onto the canvas and the padding lands off-canvas. This eliminates the green bar and corrects the geometry, at the cost of Firefox's internal resample remaining visible at 1:1 (no worse than what Firefox already does to x264 streams). copyTo()+putImageData is the only pixel-exact escape we found (drawing APIs all share the broken conversion), but it costs a ~2M-pixel per-frame CPU copy on top of Firefox's software decode — not included here.

A cheaper full fix may be server-side: if pixelflux padded VA-API/NVENC captures by edge replication (as x264 effectively does), the bar would disappear for all clients with zero client-side cost. Happy to file that on linuxserver/pixelflux#18 if preferred.

Tested on the LSIO-based image against comprehensive-fixes (da1b55e) on Intel/VA-API and NVIDIA/NVENC.

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request addresses a Firefox-specific rendering issue where canvas.drawImage scales the full backing surface of a decoder-output VideoFrame, including alignment padding, into the frame's nominal box. To resolve this, the changes introduce helper functions to detect Firefox, calculate the padded backing size based on H.264's 16x16 macroblock alignment, and overscan the destination so that the padding falls off-canvas and is clipped. These helpers are applied to both the main thread and the video worker. There are no review comments, so I have no feedback to provide.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[ehfd]

A cheaper full fix may be server-side: if pixelflux padded VA-API/NVENC captures by edge replication (as x264 effectively does), the bar would disappear for all clients with zero client-side cost. Happy to file that on linuxserver/pixelflux#18 if preferred.

I went down this rabbit hole and concluded this was not it. The encoders are not at fault; it's a Firefox bug.

So your fix is the correct one with the least computational cost.

[ehfd]

@rmounce This is a hardware decode artifact. You should see if software decode solves the problem. If so, I can prefer software decode for Firefox.

[ehfd]

Moreover, did you try Firefox 151 or later? I don't reproduce there on software decode.

[rmounce]

My testing was on Ubuntu 24.04 on Intel laptop with Firefox via snap (I did not note the version, I refreshed within the last week so probably 152).
I believe it was software decode with Firefox on the basis that CPU load was higher (about 65% vs 10% for Chrome) and via intel_gpu_top the “Video” usage was 0 (it was used by Chrome). Render/3D was non-zero for FF but I attributed this to compositing.

I am now out of the office for a few days so I cannot check further details or do more testing until next week.

I do suspect this is a Firefox bug and I intend to try and report it upstream if so. This draft PR was a way to capture the workaround that helps to characterise the underlying bug. So I’m fine if we don’t adopt this workaround.

I’ve been making the most of promotional access to Claude Fable 5 to accelerate testing and proposed bug fixes, which is now over so I’ll be back down to Opus with more manual guidance next week. I hope you don’t mind the prolific submissions. I’ve been trying to mark all AI generated output as such, but Fable is very autonomous so there are were a few generated comments without attribution.

[ehfd]

I’ve been making the most of promotional access to Claude Fable 5 to accelerate testing and proposed bug fixes, which is now over so I’ll be back down to Opus with more manual guidance next week. I hope you don’t mind the prolific submissions. I’ve been trying to mark all AI generated output as such, but Fable is very autonomous so there are were a few generated comments without attribution.

It's fine. I agree about Fable. Everything else was critically important.

Nonetheless, my Playwright validations on Ubuntu 24.04 actually didn't find the line at the bottom, so I think it's worth more deliberate evaluation of what the cause is.

Thank you so much for the test and bug hunts!