v138 · multimedia

Add support for video frame orientation metadata to WebCodecs

Introduces "rotation: int" and "flip: bool" values to various video related interfaces in WebCodecs so that developers can work with frame sources that have orientation (E.g., Android cameras, certain media). The VideoFrame interface grows the ability to create VideoFrames with arbitrary rotation and flip as well as accessors for this information on the V

concepts

  1. Video Orientation

    VideoFrame exposes rotation + flip metadata. Constructors, renderers, and encoders can inspect those fields; codec round-trips still need live verification because some paths normalize the decoded frame.

  2. Encode → decode carriage check

    A captured frame is encoded, the chunk is decoded, and the page reports whether the decoded VideoFrame preserved rotation and flip or needs a sidecar/container value.

  3. Rotation matrix test

    Pick one of the four stored rotations plus the boolean horizontal flip flag. Side-by-side raw vs corrected frame, computed display dimensions, and the 3×3 transform matrix the compositor applies.

  4. Orientation gallery

    All eight EXIF/HEIF orientation values rendered side by side using VideoFrame orientation metadata. Each frame is created with a different rotation and flip combination, drawn to canvas via the correct transform, and tagged with live VideoFrame.rotation readout where supported.

  5. Active Orientation Lock

    Chrome 138 enforces orientation consistency within a VideoEncoder session: encode frame 1 with rotation: 90 and the encoder locks to that orientation — a subsequent frame with a different rotation fires a DataError. Try both matching and mismatching orientations to see the lock in action.

  6. Rotation rounding probe

    The rotation field stores 0, 90, 180, or 270, but arbitrary numeric input is rounded to the nearest quarter turn and normalized. Run the full candidate table in your browser and try custom values to see the exact frame.rotation readback.

  7. Codec-specific orientation carriage

    VP8 has no bitstream orientation field; H.264 relies on the MP4 container’s tkhd matrix or optional SEI; AV1 can use metadata OBUs. Run roundtrip tests across supported codecs and inspect the decoded VideoFrame.

why it shipped

Currently developers have no way of knowing when they receive frames with a non-default orientation. Containers may contain orientation information that developers have no way of telling decoded frames about. Encoding may silently encode incorrectly.

references