@remotion/webcodecs: new rotateAndResizeVideoFrame() API

packages/docs/docs/webcodecs/TableOfContents.tsx

@@ -126,6 +126,10 @@ export const TableOfContents: React.FC = () => {
 					<strong>{'extractFrames()'}</strong>
 					<div>Extract frames from a video at specific timestamps.</div>
 				</TOCItem>
+				<TOCItem link="/docs/webcodecs/rotate-and-resize-video-frame">
+					<strong>{'rotateAndResizeVideoFrame()'}</strong>
+					<div>Rotate and resize a video frame.</div>
+				</TOCItem>
 			</Grid>
 		</div>
 	);

packages/docs/docs/webcodecs/rotate-and-resize-video-frame.mdx

@@ -0,0 +1,110 @@
+---
+image: /generated/articles-docs-webcodecs-rotate-and-resize-video-frame.png
+id: rotate-and-resize-video-frame
+title: rotateAndResizeVideoFrame()
+slug: /webcodecs/rotate-and-resize-video-frame
+crumb: '@remotion/webcodecs'
+---
+
+# rotateAndResizeVideoFrame()<AvailableFrom v="4.0.315"/>
+
+_Part of the [`@remotion/webcodecs`](/docs/webcodecs) package._
+
+import {LicenseDisclaimer} from './LicenseDisclaimer';
+
+<details>
+  <summary>💼 Important License Disclaimer</summary>
+  <LicenseDisclaimer />
+</details>
+
+Rotates and resizes a [`VideoFrame`](https://developer.mozilla.org/en-US/docs/Web/API/VideoFrame) object. Returns a new [`VideoFrame`](https://developer.mozilla.org/en-US/docs/Web/API/VideoFrame) object with the applied transformations.
+
+```tsx twoslash title="Rotating a video frame by 90 degrees"
+import {rotateAndResizeVideoFrame} from '@remotion/webcodecs';
+
+// Assume you have a VideoFrame object
+declare const frame: VideoFrame;
+
+const rotatedFrame = rotateAndResizeVideoFrame({
+  frame,
+  rotation: 90,
+  resizeOperation: null,
+});
+
+console.log('Original dimensions:', frame.displayWidth, 'x', frame.displayHeight);
+console.log('Rotated dimensions:', rotatedFrame.displayWidth, 'x', rotatedFrame.displayHeight);
+```
+
+```tsx twoslash title="Resizing a video frame by width"
+import {rotateAndResizeVideoFrame} from '@remotion/webcodecs';
+
+// Assume you have a VideoFrame object
+declare const frame: VideoFrame;
+
+const resizedFrame = rotateAndResizeVideoFrame({
+  frame,
+  rotation: 0,
+  resizeOperation: {
+    mode: 'width',
+    width: 640,
+  },
+});
+
+console.log('Resized frame width:', resizedFrame.displayWidth);
+```
+
+```tsx twoslash title="Rotating and resizing together"
+import {rotateAndResizeVideoFrame} from '@remotion/webcodecs';
+
+// Assume you have a VideoFrame object
+declare const frame: VideoFrame;
+
+const transformedFrame = rotateAndResizeVideoFrame({
+  frame,
+  rotation: 180,
+  resizeOperation: {
+    mode: 'height',
+    height: 480,
+  },
+  needsToBeMultipleOfTwo: true,
+});
+```
+
+## API
+
+### `frame`
+
+A [`VideoFrame`](https://developer.mozilla.org/en-US/docs/Web/API/VideoFrame) object to be transformed.
+
+### `rotation`
+
+The rotation angle in degrees. Only multiples of 90 degrees are supported (0, 90, 180, 270, etc.).
+
+### `resizeOperation`
+
+A resize operation to apply to the frame, or `null` if no resizing is needed. See [`ResizeOperation`](/docs/webcodecs/resizing) for available options.
+
+### `needsToBeMultipleOfTwo?`
+
+_optional, default: `false`_
+
+Whether the resulting dimensions should be multiples of 2. This is often required for certain video codecs. If `true`, the dimensions will be rounded down to the nearest even number.
+
+## Behavior
+
+- If no rotation and no resize operation is specified, the original frame is returned unchanged.
+- Rotation is applied first, then resizing.
+- For 90° and 270° rotations, the width and height are swapped.
+- The function creates a new `VideoFrame` using an `OffscreenCanvas` for the transformation.
+- The original frame is not modified or closed - you need to manage its lifecycle separately.
+
+## Error handling
+
+- Throws an error if the rotation is not a multiple of 90 degrees.
+- Throws an error if the 2D rendering context cannot be created.
+
+## See also
+
+- [`ResizeOperation`](/docs/webcodecs/resizing) - Available resize operations
+- [Rotate a video](/docs/webcodecs/rotate-a-video) - Guide on rotating videos
+- [`convertMedia()`](/docs/webcodecs/convert-media) - Convert entire videos with rotation and resizing

packages/docs/sidebars.js

@@ -689,6 +689,7 @@ module.exports = {
 				'webcodecs/create-audio-decoder',
 				'webcodecs/create-video-decoder',
 				'webcodecs/extract-frames',
+				'webcodecs/rotate-and-resize-video-frame',
 			],
 		},
 		{

packages/docs/src/data/articles.ts

@@ -6180,6 +6180,15 @@ export const articles = [
 		noAi: false,
 		slug: 'webcodecs/resize-a-video',
 	},
+	{
+		id: 'rotate-and-resize-video-frame',
+		title: 'rotateAndResizeVideoFrame()',
+		relativePath: 'docs/webcodecs/rotate-and-resize-video-frame.mdx',
+		compId: 'articles-docs-webcodecs-rotate-and-resize-video-frame',
+		crumb: '@remotion/webcodecs',
+		noAi: false,
+		slug: 'webcodecs/rotate-and-resize-video-frame',
+	},
 	{
 		id: 'rotate-a-video',
 		title: 'Rotate a video',

packages/webcodecs/src/index.ts

@@ -45,6 +45,7 @@ export type {
 	VideoOperation,
 } from './on-video-track-handler';
 export type {ResizeOperation} from './resizing/mode';
+export {rotateAndResizeVideoFrame} from './rotate-and-resize-video-frame';
 export {createVideoEncoder} from './video-encoder';
 export type {WebCodecsVideoEncoder} from './video-encoder';
 export {webcodecsController} from './webcodecs-controller';

packages/webcodecs/src/rotate-and-resize-video-frame.ts

@@ -11,12 +11,12 @@ export const normalizeVideoRotation = (rotation: number) => {
 export const rotateAndResizeVideoFrame = ({
 	frame,
 	rotation,
-	needsToBeMultipleOfTwo,
+	needsToBeMultipleOfTwo = false,
 	resizeOperation,
 }: {
 	frame: VideoFrame;
 	rotation: number;
-	needsToBeMultipleOfTwo: boolean;
+	needsToBeMultipleOfTwo?: boolean;
 	resizeOperation: ResizeOperation | null;
 }) => {
 	const normalized = ((rotation % 360) + 360) % 360;

packages/webcodecs/src/test/rotate-and-resize-video-frame.test.ts

@@ -0,0 +1,65 @@
+import {expect, test} from 'bun:test';
+import {rotateAndResizeVideoFrame} from '../rotate-and-resize-video-frame';
+
+// Test that focuses on API structure and parameter validation
+test('rotateAndResizeVideoFrame - function exists and has correct signature', () => {
+	expect(typeof rotateAndResizeVideoFrame).toBe('function');
+});
+
+test('rotateAndResizeVideoFrame - throws error for invalid rotation', () => {
+	// Mock VideoFrame that's sufficient for this test
+	const mockFrame = {
+		displayWidth: 100,
+		displayHeight: 200,
+		timestamp: 0,
+		duration: 1000000,
+		close: () => {},
+	} as unknown as VideoFrame;
+
+	expect(() => {
+		rotateAndResizeVideoFrame({
+			frame: mockFrame,
+			rotation: 45, // Not a multiple of 90
+			resizeOperation: null,
+		});
+	}).toThrow('Only 90 degree rotations are supported');
+});
+
+test('rotateAndResizeVideoFrame - accepts optional needsToBeMultipleOfTwo parameter', () => {
+	// Mock VideoFrame that's sufficient for this test
+	const mockFrame = {
+		displayWidth: 100,
+		displayHeight: 200,
+		timestamp: 0,
+		duration: 1000000,
+		close: () => {},
+	} as unknown as VideoFrame;
+
+	// Should not throw when needsToBeMultipleOfTwo is omitted
+	expect(() => {
+		rotateAndResizeVideoFrame({
+			frame: mockFrame,
+			rotation: 0,
+			resizeOperation: null,
+		});
+	}).not.toThrow();
+
+	// Should not throw when needsToBeMultipleOfTwo is explicitly provided
+	expect(() => {
+		rotateAndResizeVideoFrame({
+			frame: mockFrame,
+			rotation: 0,
+			resizeOperation: null,
+			needsToBeMultipleOfTwo: true,
+		});
+	}).not.toThrow();
+
+	expect(() => {
+		rotateAndResizeVideoFrame({
+			frame: mockFrame,
+			rotation: 0,
+			resizeOperation: null,
+			needsToBeMultipleOfTwo: false,
+		});
+	}).not.toThrow();
+});