fix(engine): pad odd output dimensions up to even for H.264/H.265 encode (#1802)

* fix(engine): pad odd output dimensions up to even for H.264/H.265 encode A composition with an odd data-width or data-height (e.g. a custom 3:1 canvas at 1080x723) failed to encode to MP4. libx264/libx265 with 4:2:0 chroma subsampling (yuv420p, yuv420p10le) require both dimensions to be even and abort before writing a packet: [libx264] height not divisible by 2 (1080x723) Error while opening encoder ... Invalid argument Both the streaming encoder and the chunk encoder built the software range-conversion filter ("scale=in_range=pc:out_range=tv") with no even-dimension enforcement, so any odd-sized canvas reached libx264 unmodified and the whole render failed. Add a shared withEvenDimensionPad helper that appends pad=ceil(iw/2)*2:ceil(ih/2)*2 to the filter chain only for 4:2:0 pixel formats. The pad rounds each odd dimension up by one pixel (a no-op when already even) without scaling, so content is never resampled. Formats that accept odd dimensions (ProRes 4444 yuva444p10le, VP9 yuva420p) are excluded, so transparent/alpha output is untouched. * fix(engine): extend even-dimension pad to GPU 4:2:0 encode paths The odd-dimension pad added for libx264/libx265 only covered the software encoder branches. nvenc, videotoolbox, qsv, and amf feed software frames straight to the hardware encoder with no -vf chain, so an odd-sized 4:2:0 canvas on --gpu (or an auto-selected hardware encoder) reproduced the same "height not divisible by 2" abort before any packet was written. Add the even-dimension pad to the software-side -vf chain for those four GPU paths in both the chunk and streaming encoders, reusing the shared withEvenDimensionPad helper (the pad runs on CPU before the encode). vaapi is left as-is: its existing format=nv12,hwupload conversion already aligns odd dimensions before upload, so it is not double-padded. ProRes 4444 and VP9 alpha stay untouched, exactly as the software fix excludes them. nvenc/videotoolbox/qsv/amf arg construction is logic-tested (the pad filter is asserted on the built arg list for 8-bit and 10-bit 4:2:0, with alpha ProRes asserted padless); runtime hardware encode is not exercised here.
2026-09-11 23:00:03 +00:00 · 2026-06-30 10:55:22 -07:00
parent c01d1ae03d
commit 3a2f052889
6 changed files with 175 additions and 10 deletions
@@ -0,0 +1,45 @@
+/**
+ * Even-dimension normalization for chroma-subsampled encodes.
+ *
+ * libx264 / libx265 with 4:2:0 chroma subsampling (yuv420p, yuv420p10le)
+ * require both width and height to be even. An odd output dimension makes the
+ * encoder abort before writing a single packet:
+ *
+ *   [libx264] height not divisible by 2 (1080x723)
+ *   Error while opening encoder ... Invalid argument
+ *
+ * A composition with an odd data-width / data-height (e.g. a custom 3:1 canvas
+ * at 1080x723) therefore fails to encode to H.264. The fix pads the odd
+ * dimension up by a single pixel inside the encode filter chain, so the
+ * encoder always receives even dimensions. Padding (not scaling) means content
+ * is never resampled — at most one transparent/black row or column is added at
+ * the bottom-right edge.
+ */
+
+// `pad=ceil(iw/2)*2:ceil(ih/2)*2` rounds each dimension UP to the next even
+// value (a no-op when already even) and keeps content at the top-left (x=0,y=0
+// default), so nothing shifts. iw/ih are evaluated by FFmpeg at runtime, so
+// this works whether or not the caller knows the frame size up front.
+const EVEN_DIMENSION_PAD = "pad=ceil(iw/2)*2:ceil(ih/2)*2";
+
+/**
+ * Pixel formats whose chroma subsampling requires even width AND height.
+ * 4:2:0 family only: yuv420p (H.264 SDR), yuv420p10le (H.265 HDR), and the
+ * full-range yuvj420p Chrome screenshots arrive as. ProRes 4444
+ * (yuva444p10le) and other 4:4:4 / alpha formats sample chroma per-pixel and
+ * accept odd dimensions, so they are deliberately excluded — padding them
+ * would needlessly distort transparent output.
+ */
+export function requiresEvenDimensions(pixelFormat: string): boolean {
+  return pixelFormat.startsWith("yuv420") || pixelFormat.startsWith("yuvj420");
+}
+
+/**
+ * Append the even-dimension pad to an FFmpeg `-vf` chain when the target pixel
+ * format requires it. Returns the chain unchanged for formats that accept odd
+ * dimensions, and returns just the pad when there is no existing chain.
+ */
+export function withEvenDimensionPad(vfChain: string, pixelFormat: string): string {
+  if (!requiresEvenDimensions(pixelFormat)) return vfChain;
+  return vfChain ? `${vfChain},${EVEN_DIMENSION_PAD}` : EVEN_DIMENSION_PAD;
+}