webcodecs-node 0.7.5 → 0.8.5

package/dist/core/VideoFrame.d.ts

@@ -10,13 +10,12 @@ export type { VideoPixelFormat, VideoFrameBufferInit, VideoFrameCopyToOptions, V
 /**
  * VideoFrameMetadata interface per W3C WebCodecs spec
  * https://w3c.github.io/webcodecs/video_frame_metadata_registry.html
- *
- * Note: This is a stub implementation. The full metadata registry includes:
- * - rtpTimestamp: For WebRTC media synchronization
- * - rotation: Frame orientation (0, 90, 180, 270)
- * - flip: Whether to flip the frame
  */
 export interface VideoFrameMetadata {
+    /** Frame rotation in degrees (0, 90, 180, 270) */
+    rotation?: 0 | 90 | 180 | 270;
+    /** Whether to flip the frame horizontally */
+    flip?: boolean;
 }
 export declare class VideoFrame {
     private _data;
@@ -33,6 +32,9 @@ export declare class VideoFrame {
     private _duration;
     private _timestamp;
     private _colorSpace;
+    private _inputLayout;
+    private _rotation;
+    private _flip;
     get format(): VideoPixelFormat | null;
     get codedWidth(): number;
     get codedHeight(): number;
@@ -42,7 +44,11 @@ export declare class VideoFrame {
     get displayHeight(): number;
     get duration(): number | null;
     get timestamp(): number;
-    get colorSpace(): VideoColorSpace | null;
+    get colorSpace(): VideoColorSpace;
+    /** Frame rotation in degrees (0, 90, 180, 270) - preserved after close */
+    get rotation(): 0 | 90 | 180 | 270;
+    /** Whether frame is flipped horizontally - preserved after close */
+    get flip(): boolean;
     /**
      * Create a VideoFrame from raw pixel data or CanvasImageSource
      */
@@ -64,9 +70,6 @@ export declare class VideoFrame {
     /**
      * Returns metadata associated with this VideoFrame.
      * Per W3C WebCodecs spec: https://w3c.github.io/webcodecs/video_frame_metadata_registry.html
-     *
-     * Note: Currently returns an empty object. Metadata fields like rtpTimestamp,
-     * rotation, and flip will be added as use cases require them.
      */
     metadata(): VideoFrameMetadata;
     /**
@@ -77,9 +80,12 @@ export declare class VideoFrame {
      * Copies the frame data to the destination buffer
      */
     copyTo(destination: BufferSource, options?: VideoFrameCopyToOptions): Promise<PlaneLayout[]>;
+    /**
+     * Copy to destination with custom layout (offsets and strides)
+     */
+    private _copyWithLayout;
     private _copyWithConversion;
     private _copyDirectWithClipping;
-    private _getPlaneLayoutForSize;
     /**
      * Creates a copy of this VideoFrame
      */

package/dist/core/VideoFrame.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"VideoFrame.d.ts","sourceRoot":"","sources":["../../src/core/VideoFrame.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAe,WAAW,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAC7F,OAAO,EAAgB,eAAe,EAAiB,MAAM,mBAAmB,CAAC;AAGjF,OAAO,EAKL,eAAe,EAChB,MAAM,qBAAqB,CAAC;AAS7B,OAAO,KAAK,EACV,gBAAgB,EAChB,oBAAoB,EACpB,uBAAuB,EACvB,cAAc,EACf,MAAM,mBAAmB,CAAC;AAG3B,YAAY,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,cAAc,EAAE,CAAC;AAEhG;;;;;;;;GAQG;AACH,MAAM,WAAW,kBAAkB;CAElC;AAeD,qBAAa,UAAU;IACrB,OAAO,CAAC,KAAK,CAAa;IAC1B,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,YAAY,CAA4B;IAChD,OAAO,CAAC,cAAc,CAA6B;IAEnD,OAAO,CAAC,OAAO,CAAmB;IAClC,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,UAAU,CAAkB;IACpC,OAAO,CAAC,YAAY,CAAkB;IACtC,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,SAAS,CAAgB;IACjC,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,WAAW,CAAkB;IAErC,IAAI,MAAM,IAAI,gBAAgB,GAAG,IAAI,CAA+C;IACpF,IAAI,UAAU,IAAI,MAAM,CAAgD;IACxE,IAAI,WAAW,IAAI,MAAM,CAAiD;IAC1E,IAAI,SAAS,IAAI,eAAe,GAAG,IAAI,CAAkD;IACzF,IAAI,WAAW,IAAI,eAAe,GAAG,IAAI,CAAoD;IAC7F,IAAI,YAAY,IAAI,MAAM,CAAkD;IAC5E,IAAI,aAAa,IAAI,MAAM,CAAmD;IAE9E,IAAI,QAAQ,IAAI,MAAM,GAAG,IAAI,CAA2B;IACxD,IAAI,SAAS,IAAI,MAAM,CAA4B;IACnD,IAAI,UAAU,IAAI,eAAe,GAAG,IAAI,CAAmD;IAE3F;;OAEG;gBACS,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,oBAAoB;gBAC9C,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,cAAc;IAuNjD;;;OAGG;IACH,OAAO,CAAC,qBAAqB;IAwB7B;;OAEG;IACH,OAAO,CAAC,6BAA6B;IA0GrC;;OAEG;IACH,cAAc,CAAC,OAAO,CAAC,EAAE,uBAAuB,GAAG,MAAM;IAYzD;;;;;;OAMG;IACH,QAAQ,IAAI,kBAAkB;IAK9B;;OAEG;IACH,IAAI,cAAc,IAAI,MAAM,CAE3B;IAED;;OAEG;IACG,MAAM,CACV,WAAW,EAAE,YAAY,EACzB,OAAO,CAAC,EAAE,uBAAuB,GAChC,OAAO,CAAC,WAAW,EAAE,CAAC;IAiCzB,OAAO,CAAC,mBAAmB;IAwB3B,OAAO,CAAC,uBAAuB;IAmC/B,OAAO,CAAC,sBAAsB;IA4F9B;;OAEG;IACH,KAAK,IAAI,UAAU;IAyBnB;;OAEG;IACH,KAAK,IAAI,IAAI;IAcb;;OAEG;IACH,IAAI,OAAO,IAAI,UAAU,CAIxB;IAED,IAAI,OAAO,IAAI,WAAW,GAAG,IAAI,CAEhC;IAED,OAAO,CAAC,eAAe;IAMvB,OAAO,CAAC,cAAc;IAItB,OAAO,CAAC,iBAAiB;CAU1B"}
+{"version":3,"file":"VideoFrame.d.ts","sourceRoot":"","sources":["../../src/core/VideoFrame.ts"],"names":[],"mappings":"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"}

package/dist/core/VideoFrame.js

@@ -3,9 +3,14 @@
  * https://developer.mozilla.org/en-US/docs/Web/API/VideoFrame
  */
 import { DOMException, DOMRectReadOnly, isNativeFrame } from '../types/index.js';
-import { toUint8Array } from '../utils/buffer.js';
+import { toUint8Array, copyToUint8Array } from '../utils/buffer.js';
 import { getFrameAllocationSize, getPlaneCount, getPlaneInfo, isRgbFormat, VideoColorSpace, } from '../formats/index.js';
 import { convertFrameFormat, getPlaneOffset, } from '../formats/conversions/frame-converter.js';
+// Import from video-frame submodule
+import { VALID_PIXEL_FORMATS, validateFinitePositive, validateDuration, validateRotation, validateSubsamplingAlignment, validateVisibleRect, } from './video-frame/validation.js';
+import { detachArrayBuffers, validateTransferList, } from './video-frame/transfer.js';
+import { composeOrientations, computeDefaultDisplayDimensions } from './video-frame/orientation.js';
+import { getPlaneLayoutForSize } from './video-frame/layout.js';
 // Import type guards from utils
 import { isImageDataLike, isCanvasLike, isVideoFrameLike, isCanvasImageSource, extractCanvasPixels, } from '../utils/type-guards.js';
 export class VideoFrame {
@@ -23,6 +28,9 @@ export class VideoFrame {
     _duration;
     _timestamp;
     _colorSpace;
+    _inputLayout = null; // Layout from init, if provided
+    _rotation = 0;
+    _flip = false;
     get format() { return this._closed ? null : this._format; }
     get codedWidth() { return this._closed ? 0 : this._codedWidth; }
     get codedHeight() { return this._closed ? 0 : this._codedHeight; }
@@ -30,10 +38,14 @@ export class VideoFrame {
     get visibleRect() { return this._closed ? null : this._visibleRect; }
     get displayWidth() { return this._closed ? 0 : this._displayWidth; }
     get displayHeight() { return this._closed ? 0 : this._displayHeight; }
-    // timestamp and duration are preserved after close per WebCodecs spec
+    // timestamp, duration, colorSpace, rotation, flip are preserved after close per WebCodecs spec
     get duration() { return this._duration; }
     get timestamp() { return this._timestamp; }
-    get colorSpace() { return this._closed ? null : this._colorSpace; }
+    get colorSpace() { return this._colorSpace; }
+    /** Frame rotation in degrees (0, 90, 180, 270) - preserved after close */
+    get rotation() { return this._rotation; }
+    /** Whether frame is flipped horizontally - preserved after close */
+    get flip() { return this._flip; }
     constructor(dataOrImage, init) {
         // Special case: constructing from another VideoFrame without init
         if (isVideoFrameLike(dataOrImage)) {
@@ -80,9 +92,40 @@ export class VideoFrame {
             else {
                 this._visibleRect = new DOMRectReadOnly(0, 0, sourceFrame.codedWidth, sourceFrame.codedHeight);
             }
-            this._displayWidth = frameInit.displayWidth ?? sourceFrame.displayWidth;
-            this._displayHeight = frameInit.displayHeight ?? sourceFrame.displayHeight;
             this._colorSpace = new VideoColorSpace(this._getDefaultColorSpace(this._format, frameInit.colorSpace));
+            // Compose orientations: source orientation + init orientation
+            // Get source orientation from getter (if it's our VideoFrame) or metadata
+            let srcRotation = 0;
+            let srcFlip = false;
+            if (typeof sourceFrame.rotation === 'number') {
+                srcRotation = sourceFrame.rotation;
+            }
+            else if (sourceFrame.metadata) {
+                const sourceMetadata = sourceFrame.metadata();
+                srcRotation = sourceMetadata?.rotation ?? 0;
+                srcFlip = sourceMetadata?.flip ?? false;
+            }
+            if (typeof sourceFrame.flip === 'boolean') {
+                srcFlip = sourceFrame.flip;
+            }
+            const initRotation = frameInit.rotation ?? 0;
+            const initFlip = frameInit.flip ?? false;
+            // Compose the orientations per WebCodecs spec
+            const composed = composeOrientations(srcRotation, srcFlip, initRotation, initFlip);
+            this._rotation = composed.rotation;
+            this._flip = composed.flip;
+            // Display dimensions: use explicit values if provided, otherwise compute from source
+            // accounting for the composed orientation's effect on dimensions
+            if (frameInit.displayWidth !== undefined && frameInit.displayHeight !== undefined) {
+                this._displayWidth = frameInit.displayWidth;
+                this._displayHeight = frameInit.displayHeight;
+            }
+            else {
+                // Compute default display dimensions based on composed orientation
+                const defaultDisplay = computeDefaultDisplayDimensions(this._visibleRect.width, this._visibleRect.height, this._rotation);
+                this._displayWidth = frameInit.displayWidth ?? defaultDisplay.displayWidth;
+                this._displayHeight = frameInit.displayHeight ?? defaultDisplay.displayHeight;
+            }
             return;
         }
         // Validate init is provided for non-VideoFrame sources
@@ -95,15 +138,36 @@ export class VideoFrame {
             if (!bufferInit.format) {
                 throw new TypeError('format is required');
             }
-            if (typeof bufferInit.codedWidth !== 'number' || bufferInit.codedWidth <= 0) {
-                throw new TypeError('codedWidth must be a positive number');
+            // Validate pixel format is known
+            if (!VALID_PIXEL_FORMATS.has(bufferInit.format)) {
+                throw new TypeError(`Unknown pixel format: ${bufferInit.format}`);
+            }
+            if (typeof bufferInit.codedWidth !== 'number') {
+                throw new TypeError('codedWidth is required');
             }
-            if (typeof bufferInit.codedHeight !== 'number' || bufferInit.codedHeight <= 0) {
-                throw new TypeError('codedHeight must be a positive number');
+            validateFinitePositive(bufferInit.codedWidth, 'codedWidth');
+            if (typeof bufferInit.codedHeight !== 'number') {
+                throw new TypeError('codedHeight is required');
             }
-            if (typeof bufferInit.timestamp !== 'number') {
-                throw new TypeError('timestamp is required');
+            validateFinitePositive(bufferInit.codedHeight, 'codedHeight');
+            if (typeof bufferInit.timestamp !== 'number' || !Number.isFinite(bufferInit.timestamp)) {
+                throw new TypeError('timestamp must be a finite number');
             }
+            // Validate subsampling alignment
+            validateSubsamplingAlignment(bufferInit.format, bufferInit.codedWidth, bufferInit.codedHeight);
+            // Validate visibleRect bounds
+            validateVisibleRect(bufferInit.visibleRect, bufferInit.codedWidth, bufferInit.codedHeight);
+            // Validate displayWidth/displayHeight if provided
+            if (bufferInit.displayWidth !== undefined) {
+                validateFinitePositive(bufferInit.displayWidth, 'displayWidth');
+            }
+            if (bufferInit.displayHeight !== undefined) {
+                validateFinitePositive(bufferInit.displayHeight, 'displayHeight');
+            }
+            // Validate duration if provided
+            validateDuration(bufferInit.duration);
+            // Validate rotation if provided
+            validateRotation(bufferInit.rotation);
             this._nativeFrame = dataOrImage;
             this._nativeCleanup = init._nativeCleanup ?? null;
             this._data = new Uint8Array(0);
@@ -119,8 +183,13 @@ export class VideoFrame {
             else {
                 this._visibleRect = new DOMRectReadOnly(0, 0, bufferInit.codedWidth, bufferInit.codedHeight);
             }
-            this._displayWidth = bufferInit.displayWidth ?? this._visibleRect.width;
-            this._displayHeight = bufferInit.displayHeight ?? this._visibleRect.height;
+            // Set rotation/flip first as they affect default display dimensions
+            this._rotation = bufferInit.rotation ?? 0;
+            this._flip = bufferInit.flip ?? false;
+            // Compute default display dimensions (swapped for 90/270 rotation)
+            const defaultDisplay = computeDefaultDisplayDimensions(this._visibleRect.width, this._visibleRect.height, this._rotation);
+            this._displayWidth = bufferInit.displayWidth ?? defaultDisplay.displayWidth;
+            this._displayHeight = bufferInit.displayHeight ?? defaultDisplay.displayHeight;
             this._colorSpace = new VideoColorSpace(this._getDefaultColorSpace(bufferInit.format, bufferInit.colorSpace));
         }
         else if (dataOrImage instanceof ArrayBuffer || ArrayBuffer.isView(dataOrImage)) {
@@ -130,15 +199,38 @@ export class VideoFrame {
             if (!bufferInit.format) {
                 throw new TypeError('format is required');
             }
-            if (typeof bufferInit.codedWidth !== 'number' || bufferInit.codedWidth <= 0) {
-                throw new TypeError('codedWidth must be a positive number');
-            }
-            if (typeof bufferInit.codedHeight !== 'number' || bufferInit.codedHeight <= 0) {
-                throw new TypeError('codedHeight must be a positive number');
-            }
-            if (typeof bufferInit.timestamp !== 'number') {
-                throw new TypeError('timestamp is required');
-            }
+            // Validate pixel format is known
+            if (!VALID_PIXEL_FORMATS.has(bufferInit.format)) {
+                throw new TypeError(`Unknown pixel format: ${bufferInit.format}`);
+            }
+            if (typeof bufferInit.codedWidth !== 'number') {
+                throw new TypeError('codedWidth is required');
+            }
+            validateFinitePositive(bufferInit.codedWidth, 'codedWidth');
+            if (typeof bufferInit.codedHeight !== 'number') {
+                throw new TypeError('codedHeight is required');
+            }
+            validateFinitePositive(bufferInit.codedHeight, 'codedHeight');
+            if (typeof bufferInit.timestamp !== 'number' || !Number.isFinite(bufferInit.timestamp)) {
+                throw new TypeError('timestamp must be a finite number');
+            }
+            // Validate subsampling alignment
+            validateSubsamplingAlignment(bufferInit.format, bufferInit.codedWidth, bufferInit.codedHeight);
+            // Validate visibleRect bounds
+            validateVisibleRect(bufferInit.visibleRect, bufferInit.codedWidth, bufferInit.codedHeight);
+            // Validate displayWidth/displayHeight if provided
+            if (bufferInit.displayWidth !== undefined) {
+                validateFinitePositive(bufferInit.displayWidth, 'displayWidth');
+            }
+            if (bufferInit.displayHeight !== undefined) {
+                validateFinitePositive(bufferInit.displayHeight, 'displayHeight');
+            }
+            // Validate duration if provided
+            validateDuration(bufferInit.duration);
+            // Validate rotation if provided
+            validateRotation(bufferInit.rotation);
+            // Validate transfer list if provided (check for duplicates and detached buffers)
+            validateTransferList(bufferInit.transfer);
             // Validate buffer size
             const expectedSize = getFrameAllocationSize(bufferInit.format, bufferInit.codedWidth, bufferInit.codedHeight);
             const actualSize = data instanceof ArrayBuffer ? data.byteLength : data.byteLength;
@@ -146,7 +238,14 @@ export class VideoFrame {
                 throw new TypeError(`Buffer too small: expected at least ${expectedSize} bytes for ${bufferInit.format} ` +
                     `${bufferInit.codedWidth}x${bufferInit.codedHeight}, got ${actualSize}`);
             }
-            this._data = toUint8Array(data);
+            // Copy data to internal buffer (must happen before transfer detaches source)
+            // Use copyToUint8Array when transfer is specified to ensure we don't hold a view
+            // to a buffer that will be detached
+            this._data = bufferInit.transfer && bufferInit.transfer.length > 0
+                ? copyToUint8Array(data)
+                : toUint8Array(data);
+            // Detach transferred buffers after data has been copied
+            detachArrayBuffers(bufferInit.transfer);
             this._format = bufferInit.format;
             this._codedWidth = bufferInit.codedWidth;
             this._codedHeight = bufferInit.codedHeight;
@@ -159,9 +258,16 @@ export class VideoFrame {
             else {
                 this._visibleRect = new DOMRectReadOnly(0, 0, bufferInit.codedWidth, bufferInit.codedHeight);
             }
-            this._displayWidth = bufferInit.displayWidth ?? this._visibleRect.width;
-            this._displayHeight = bufferInit.displayHeight ?? this._visibleRect.height;
+            // Set rotation/flip first as they affect default display dimensions
+            this._rotation = bufferInit.rotation ?? 0;
+            this._flip = bufferInit.flip ?? false;
+            // Compute default display dimensions (swapped for 90/270 rotation)
+            const defaultDisplay = computeDefaultDisplayDimensions(this._visibleRect.width, this._visibleRect.height, this._rotation);
+            this._displayWidth = bufferInit.displayWidth ?? defaultDisplay.displayWidth;
+            this._displayHeight = bufferInit.displayHeight ?? defaultDisplay.displayHeight;
             this._colorSpace = new VideoColorSpace(this._getDefaultColorSpace(bufferInit.format, bufferInit.colorSpace));
+            // Store input layout if provided (for non-standard memory layouts)
+            this._inputLayout = bufferInit.layout ?? null;
         }
         else if (isCanvasImageSource(dataOrImage)) {
             const frameInit = init;
@@ -170,6 +276,23 @@ export class VideoFrame {
                 throw new TypeError('timestamp is required and must be a finite number for CanvasImageSource');
             }
             const result = this._extractFromCanvasImageSource(dataOrImage, frameInit);
+            // Validate canvas isn't empty
+            if (result.width <= 0 || result.height <= 0) {
+                throw new DOMException('CanvasImageSource has zero dimensions', 'InvalidStateError');
+            }
+            // Validate visibleRect bounds
+            validateVisibleRect(frameInit.visibleRect, result.width, result.height);
+            // Validate displayWidth/displayHeight if provided
+            if (frameInit.displayWidth !== undefined) {
+                validateFinitePositive(frameInit.displayWidth, 'displayWidth');
+            }
+            if (frameInit.displayHeight !== undefined) {
+                validateFinitePositive(frameInit.displayHeight, 'displayHeight');
+            }
+            // Validate duration if provided
+            validateDuration(frameInit.duration);
+            // Validate rotation if provided
+            validateRotation(frameInit.rotation);
             this._data = result.data;
             this._format = result.format;
             this._codedWidth = result.width;
@@ -183,8 +306,13 @@ export class VideoFrame {
             else {
                 this._visibleRect = new DOMRectReadOnly(0, 0, result.width, result.height);
             }
-            this._displayWidth = frameInit.displayWidth ?? this._visibleRect.width;
-            this._displayHeight = frameInit.displayHeight ?? this._visibleRect.height;
+            // Set rotation/flip first as they affect default display dimensions
+            this._rotation = frameInit.rotation ?? 0;
+            this._flip = frameInit.flip ?? false;
+            // Compute default display dimensions (swapped for 90/270 rotation)
+            const defaultDisplay = computeDefaultDisplayDimensions(this._visibleRect.width, this._visibleRect.height, this._rotation);
+            this._displayWidth = frameInit.displayWidth ?? defaultDisplay.displayWidth;
+            this._displayHeight = frameInit.displayHeight ?? defaultDisplay.displayHeight;
             this._colorSpace = new VideoColorSpace(this._getDefaultColorSpace(result.format, frameInit.colorSpace));
         }
         else {
@@ -322,13 +450,17 @@ export class VideoFrame {
     /**
      * Returns metadata associated with this VideoFrame.
      * Per W3C WebCodecs spec: https://w3c.github.io/webcodecs/video_frame_metadata_registry.html
-     *
-     * Note: Currently returns an empty object. Metadata fields like rtpTimestamp,
-     * rotation, and flip will be added as use cases require them.
      */
     metadata() {
         this._checkNotClosed();
-        return {};
+        const result = {};
+        if (this._rotation !== 0) {
+            result.rotation = this._rotation;
+        }
+        if (this._flip) {
+            result.flip = this._flip;
+        }
+        return result;
     }
     /**
      * Returns the number of planes for this frame's format
@@ -345,6 +477,7 @@ export class VideoFrame {
         const destArray = toUint8Array(destination);
         const destFormat = options?.format ?? this._format;
         const rect = options?.rect;
+        const layout = options?.layout;
         const srcX = Math.floor(rect?.x ?? this._visibleRect.x);
         const srcY = Math.floor(rect?.y ?? this._visibleRect.y);
         const srcW = Math.floor(rect?.width ?? this._visibleRect.width);
@@ -352,19 +485,83 @@ export class VideoFrame {
         if (srcX < 0 || srcY < 0 || srcX + srcW > this._codedWidth || srcY + srcH > this._codedHeight) {
             throw new DOMException('Rect is out of bounds', 'ConstraintError');
         }
-        const requiredSize = getFrameAllocationSize(destFormat, srcW, srcH);
-        if (destArray.byteLength < requiredSize) {
+        // Validate layout if provided
+        const numPlanes = getPlaneCount(destFormat);
+        if (layout) {
+            if (layout.length !== numPlanes) {
+                throw new TypeError(`layout must have ${numPlanes} entries for format ${destFormat}, got ${layout.length}`);
+            }
+            // Validate that buffer is large enough for the provided layout
+            for (let p = 0; p < numPlanes; p++) {
+                const planeInfo = getPlaneInfo(destFormat, srcW, srcH, p);
+                const planeEnd = layout[p].offset + (planeInfo.height - 1) * layout[p].stride + planeInfo.width * planeInfo.bytesPerPixel;
+                if (planeEnd > destArray.byteLength) {
+                    throw new TypeError(`destination buffer too small for layout: plane ${p} needs ${planeEnd} bytes`);
+                }
+            }
+        }
+        const requiredSize = layout ? 0 : getFrameAllocationSize(destFormat, srcW, srcH);
+        if (!layout && destArray.byteLength < requiredSize) {
             throw new TypeError(`destination buffer is too small (need ${requiredSize}, got ${destArray.byteLength})`);
         }
-        if (destFormat === this._format && srcX === 0 && srcY === 0 &&
+        // Fast path: no conversion, no clipping, no custom layout
+        if (!layout && destFormat === this._format && srcX === 0 && srcY === 0 &&
             srcW === this._codedWidth && srcH === this._codedHeight) {
             destArray.set(this._data);
-            return this._getPlaneLayoutForSize(srcW, srcH, destFormat);
+            return getPlaneLayoutForSize(srcW, srcH, destFormat);
         }
-        this._copyWithConversion(destArray, destFormat, srcX, srcY, srcW, srcH);
-        return this._getPlaneLayoutForSize(srcW, srcH, destFormat);
+        // Get colorSpace for conversion (use options if provided, otherwise use frame's colorSpace)
+        // Convert null values to undefined for proper VideoColorSpaceInit compatibility
+        const colorSpace = options?.colorSpace ?? {
+            primaries: this._colorSpace.primaries,
+            transfer: this._colorSpace.transfer,
+            matrix: this._colorSpace.matrix,
+            fullRange: this._colorSpace.fullRange ?? undefined,
+        };
+        // Copy with optional layout
+        if (layout) {
+            this._copyWithLayout(destArray, destFormat, srcX, srcY, srcW, srcH, layout, colorSpace);
+            return layout;
+        }
+        this._copyWithConversion(destArray, destFormat, srcX, srcY, srcW, srcH, colorSpace);
+        return getPlaneLayoutForSize(srcW, srcH, destFormat);
     }
-    _copyWithConversion(dest, destFormat, srcX, srcY, srcW, srcH) {
+    /**
+     * Copy to destination with custom layout (offsets and strides)
+     */
+    _copyWithLayout(dest, destFormat, srcX, srcY, srcW, srcH, layout, colorSpace) {
+        // First, convert to a temporary buffer if format conversion needed
+        let srcData;
+        if (this._format === destFormat) {
+            srcData = this._data;
+        }
+        else {
+            // Convert to temp buffer with packed layout, then copy to dest with custom layout
+            const tempSize = getFrameAllocationSize(destFormat, srcW, srcH);
+            const tempBuffer = new Uint8Array(tempSize);
+            this._copyWithConversion(tempBuffer, destFormat, srcX, srcY, srcW, srcH, colorSpace);
+            srcData = tempBuffer;
+            // Reset srcX/srcY since tempBuffer already has the clipped region
+            srcX = 0;
+            srcY = 0;
+        }
+        const numPlanes = getPlaneCount(destFormat);
+        let srcOffset = 0;
+        for (let p = 0; p < numPlanes; p++) {
+            const planeInfo = getPlaneInfo(destFormat, srcW, srcH, p);
+            const destOffset = layout[p].offset;
+            const destStride = layout[p].stride;
+            const srcStride = planeInfo.width * planeInfo.bytesPerPixel;
+            // Copy row by row with custom stride
+            for (let row = 0; row < planeInfo.height; row++) {
+                const srcRowOffset = srcOffset + row * srcStride;
+                const destRowOffset = destOffset + row * destStride;
+                dest.set(srcData.subarray(srcRowOffset, srcRowOffset + srcStride), destRowOffset);
+            }
+            srcOffset += srcStride * planeInfo.height;
+        }
+    }
+    _copyWithConversion(dest, destFormat, srcX, srcY, srcW, srcH, colorSpace) {
         if (this._format === destFormat) {
             this._copyDirectWithClipping(dest, srcX, srcY, srcW, srcH);
             return;
@@ -376,7 +573,7 @@ export class VideoFrame {
             width: this._codedWidth,
             height: this._codedHeight,
         };
-        convertFrameFormat(src, dest, destFormat, srcX, srcY, srcW, srcH);
+        convertFrameFormat(src, dest, destFormat, srcX, srcY, srcW, srcH, colorSpace);
     }
     _copyDirectWithClipping(dest, srcX, srcY, srcW, srcH) {
         const numPlanes = getPlaneCount(this._format);
@@ -401,96 +598,6 @@ export class VideoFrame {
             }
         }
     }
-    _getPlaneLayoutForSize(width, height, format) {
-        const chromaW = Math.ceil(width / 2);
-        const chromaH = Math.ceil(height / 2);
-        switch (format) {
-            case 'I420': {
-                const ySize = width * height;
-                const uvSize = chromaW * chromaH;
-                return [
-                    { offset: 0, stride: width },
-                    { offset: ySize, stride: chromaW },
-                    { offset: ySize + uvSize, stride: chromaW },
-                ];
-            }
-            case 'I420A': {
-                const ySize = width * height;
-                const uvSize = chromaW * chromaH;
-                return [
-                    { offset: 0, stride: width },
-                    { offset: ySize, stride: chromaW },
-                    { offset: ySize + uvSize, stride: chromaW },
-                    { offset: ySize + 2 * uvSize, stride: width },
-                ];
-            }
-            case 'I422': {
-                const ySize = width * height;
-                const uvSize = chromaW * height;
-                return [
-                    { offset: 0, stride: width },
-                    { offset: ySize, stride: chromaW },
-                    { offset: ySize + uvSize, stride: chromaW },
-                ];
-            }
-            case 'I444': {
-                const planeSize = width * height;
-                return [
-                    { offset: 0, stride: width },
-                    { offset: planeSize, stride: width },
-                    { offset: 2 * planeSize, stride: width },
-                ];
-            }
-            case 'NV12': {
-                const ySize = width * height;
-                return [
-                    { offset: 0, stride: width },
-                    { offset: ySize, stride: width },
-                ];
-            }
-            // 10-bit formats: 2 bytes per sample
-            case 'I420P10': {
-                const ySize = width * height * 2;
-                const uvSize = chromaW * chromaH * 2;
-                return [
-                    { offset: 0, stride: width * 2 },
-                    { offset: ySize, stride: chromaW * 2 },
-                    { offset: ySize + uvSize, stride: chromaW * 2 },
-                ];
-            }
-            case 'I422P10': {
-                const ySize = width * height * 2;
-                const uvSize = chromaW * height * 2;
-                return [
-                    { offset: 0, stride: width * 2 },
-                    { offset: ySize, stride: chromaW * 2 },
-                    { offset: ySize + uvSize, stride: chromaW * 2 },
-                ];
-            }
-            case 'I444P10': {
-                const planeSize = width * height * 2;
-                return [
-                    { offset: 0, stride: width * 2 },
-                    { offset: planeSize, stride: width * 2 },
-                    { offset: 2 * planeSize, stride: width * 2 },
-                ];
-            }
-            case 'P010': {
-                const ySize = width * height * 2;
-                return [
-                    { offset: 0, stride: width * 2 },
-                    { offset: ySize, stride: width * 2 },
-                ];
-            }
-            case 'RGBA':
-            case 'RGBX':
-            case 'BGRA':
-            case 'BGRX':
-                return [{ offset: 0, stride: width * 4 }];
-            default:
-                return [{ offset: 0, stride: width * 4 }];
-        }
-    }
     /**
      * Creates a copy of this VideoFrame
      */
@@ -516,6 +623,8 @@ export class VideoFrame {
             displayHeight: this._displayHeight,
             visibleRect: this._visibleRect.toJSON(),
             colorSpace,
+            rotation: this._rotation,
+            flip: this._flip,
         });
     }
     /**