@napi-rs/webcodecs 0.0.0 → 1.0.0

package/README.md

@@ -10,6 +10,7 @@ WebCodecs API implementation for Node.js using FFmpeg, built with [NAPI-RS](http
 - **Video encoding/decoding** - H.264, H.265, VP8, VP9, AV1
 - **Audio encoding/decoding** - AAC, Opus, MP3, FLAC, Vorbis, PCM variants
 - **Image decoding** - JPEG, PNG, WebP, GIF, BMP, AVIF
+- **Canvas integration** - Create VideoFrames from `@napi-rs/canvas` for graphics and text rendering
 - **Hardware acceleration** - Zero-copy GPU encoding with VideoToolbox (macOS), NVENC (NVIDIA), VAAPI (Linux), QSV (Intel)
 - **Cross-platform** - macOS, Windows, Linux (glibc/musl, x64/arm64/armv7)
 - **Structured logging** - FFmpeg logs redirected to Rust `tracing` crate for easy integration
@@ -24,6 +25,14 @@ pnpm add @napi-rs/webcodecs
 yarn add @napi-rs/webcodecs
 ```
 
+### Optional: Canvas Integration
+
+For creating VideoFrames from canvas content, install `@napi-rs/canvas`:
+
+```bash
+npm install @napi-rs/canvas
+```
+
 ## Quick Start
 
 ### Video Encoding
@@ -157,6 +166,39 @@ result.image.close()
 decoder.close()
 ```
 
+### VideoFrame from Canvas
+
+Create VideoFrames from `@napi-rs/canvas` for graphics, text rendering, or image compositing:
+
+```typescript
+import { VideoFrame } from '@napi-rs/webcodecs'
+import { createCanvas } from '@napi-rs/canvas'
+
+const canvas = createCanvas(1920, 1080)
+const ctx = canvas.getContext('2d')
+
+// Draw graphics
+ctx.fillStyle = '#FF0000'
+ctx.fillRect(0, 0, 1920, 1080)
+ctx.fillStyle = '#FFFFFF'
+ctx.font = '48px sans-serif'
+ctx.fillText('Hello WebCodecs!', 100, 100)
+
+// Create VideoFrame from canvas (timestamp required per W3C spec)
+const frame = new VideoFrame(canvas, {
+  timestamp: 0,
+  duration: 33333, // optional: frame duration in microseconds
+})
+
+console.log(frame.format) // 'RGBA'
+console.log(frame.codedWidth, frame.codedHeight) // 1920, 1080
+
+// Use with VideoEncoder (see Video Encoding section)
+frame.close()
+```
+
+**Note:** Canvas pixel data is copied as RGBA format with sRGB color space.
+
 ## Supported Codecs
 
 ### Video
@@ -213,7 +255,7 @@ This implementation is validated against the [W3C Web Platform Tests](https://gi
 
 | Status      | Count | Percentage |
 | ----------- | ----- | ---------- |
-| **Passing** | 522   | 99.1%      |
+| **Passing** | 573   | 99.1%      |
 | **Skipped** | 5     | 0.9%       |
 | **Failing** | 0     | 0%         |
 
@@ -296,6 +338,40 @@ const encoder = new VideoEncoder({
 })
 ```
 
+### VideoFrame Format Conversion
+
+`VideoFrame.copyTo()` and `VideoFrame.allocationSize()` support format conversion per W3C WebCodecs spec:
+
+```typescript
+const frame = new VideoFrame(i420Data, {
+  format: 'I420',
+  codedWidth: 1920,
+  codedHeight: 1080,
+  timestamp: 0,
+})
+
+// Get allocation size for RGBA output
+const rgbaSize = frame.allocationSize({ format: 'RGBA' })
+
+// Copy with format conversion (I420 → RGBA)
+const rgbaBuffer = new Uint8Array(rgbaSize)
+const layout = await frame.copyTo(rgbaBuffer, { format: 'RGBA' })
+
+frame.close()
+```
+
+**Supported conversions:**
+
+| Source Format                | Target Format          | Status               |
+| ---------------------------- | ---------------------- | -------------------- |
+| I420, I422, I444, NV12, NV21 | RGBA, RGBX, BGRA, BGRX | ✅                   |
+| RGBA, RGBX, BGRA, BGRX       | RGBA, RGBX, BGRA, BGRX | ✅                   |
+| RGBA, RGBX, BGRA, BGRX       | I420, I422, I444, NV12 | ❌ NotSupportedError |
+
+Per WPT `videoFrame-copyTo-rgb.any.js`, RGB-to-YUV conversion throws `NotSupportedError`.
+
+Custom layouts with overflow-inducing values (e.g., `offset: 2³²-2`) throw `TypeError` via checked arithmetic. Rect alignment is validated against the source format during conversion.
+
 ### ImageDecoder Options
 
 ImageDecoder supports all W3C spec options:
@@ -355,7 +431,7 @@ This package implements the [W3C WebCodecs API](https://w3c.github.io/webcodecs/
 
 - `VideoEncoder` / `VideoDecoder` - Video encoding and decoding with EventTarget support
 - `AudioEncoder` / `AudioDecoder` - Audio encoding and decoding with EventTarget support
-- `VideoFrame` - Raw video frame data (RGBA formats default to sRGB colorSpace)
+- `VideoFrame` - Raw video frame data (supports buffer data, existing VideoFrame, or `@napi-rs/canvas` Canvas)
 - `AudioData` - Raw audio sample data
 - `EncodedVideoChunk` / `EncodedAudioChunk` - Encoded media data
 - `ImageDecoder` - Static image decoding

package/index.d.ts

@@ -33,6 +33,33 @@ export {
   AllowSharedBufferSource,
 } from './standard'
 
+export type TypedArray =
+  | Int8Array
+  | Uint8Array
+  | Uint8ClampedArray
+  | Int16Array
+  | Uint16Array
+  | Int32Array
+  | Uint32Array
+  | Float32Array
+  | Float64Array
+  | BigInt64Array
+  | BigUint64Array
+
+/**
+ * Interface for Canvas-like objects compatible with VideoFrame constructor.
+ * Compatible with @napi-rs/canvas Canvas class.
+ *
+ * @napi-rs/canvas is an optional peer dependency. If installed, Canvas objects
+ * can be used as VideoFrame sources. The Canvas pixel data is copied (RGBA format).
+ */
+export interface CanvasLike {
+  readonly width: number
+  readonly height: number
+  /** Returns raw RGBA pixel data as a Buffer */
+  data(): Uint8Array
+}
+
 export type TypedArray =
   | Int8Array
   | Uint8Array
@@ -668,13 +695,14 @@ export declare class VideoEncoder {
  */
 export declare class VideoFrame {
   /**
-   * Create a new VideoFrame from buffer data or another VideoFrame (W3C WebCodecs spec)
+   * Create a new VideoFrame from buffer data, another VideoFrame, or a Canvas (W3C WebCodecs spec)
    *
-   * Two constructor forms per W3C spec:
+   * Constructor forms per W3C spec:
    * 1. `new VideoFrame(data, init)` - from BufferSource with VideoFrameBufferInit
    * 2. `new VideoFrame(source, init?)` - from another VideoFrame with optional VideoFrameInit
+   * 3. `new VideoFrame(canvas, init)` - from @napi-rs/canvas Canvas (requires timestamp in init)
    */
-  constructor(source: VideoFrame | Uint8Array, init?: VideoFrameBufferInit | VideoFrameInit)
+  constructor(source: VideoFrame | Uint8Array | CanvasLike, init?: VideoFrameBufferInit | VideoFrameInit)
   /** Get the pixel format */
   get format(): VideoPixelFormat | null
   /** Get the coded width in pixels (returns 0 when closed per W3C spec) */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@napi-rs/webcodecs",
-  "version": "0.0.0",
+  "version": "1.0.0",
   "description": "WebCodecs API implementation for Node.js using FFmpeg",
   "keywords": [
     "N-API",
@@ -14,6 +14,10 @@
     "type": "git",
     "url": "git+ssh://git@github.com/Brooooooklyn/webcodecs-node.git"
   },
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/Brooooooklyn"
+  },
   "license": "MIT",
   "main": "index.js",
   "exports": {
@@ -68,6 +72,7 @@
   "devDependencies": {
     "@emnapi/core": "^1.7.1",
     "@emnapi/runtime": "^1.7.1",
+    "@napi-rs/canvas": "^0.1.84",
     "@napi-rs/cli": "^3.5.0",
     "@napi-rs/wasm-runtime": "^1.1.0",
     "@oxc-node/core": "^0.0.35",
@@ -88,6 +93,14 @@
     "tinybench": "^6.0.0",
     "typescript": "^5.9.3"
   },
+  "peerDependencies": {
+    "@napi-rs/canvas": ">=0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@napi-rs/canvas": {
+      "optional": true
+    }
+  },
   "napi": {
     "binaryName": "webcodecs",
     "constEnum": false,
@@ -137,14 +150,14 @@
     "registry": "https://registry.npmjs.org/"
   },
   "optionalDependencies": {
-    "@napi-rs/webcodecs-darwin-x64": "0.0.0",
-    "@napi-rs/webcodecs-darwin-arm64": "0.0.0",
-    "@napi-rs/webcodecs-linux-x64-gnu": "0.0.0",
-    "@napi-rs/webcodecs-linux-x64-musl": "0.0.0",
-    "@napi-rs/webcodecs-win32-x64-msvc": "0.0.0",
-    "@napi-rs/webcodecs-linux-arm64-gnu": "0.0.0",
-    "@napi-rs/webcodecs-linux-arm64-musl": "0.0.0",
-    "@napi-rs/webcodecs-win32-arm64-msvc": "0.0.0",
-    "@napi-rs/webcodecs-linux-arm-gnueabihf": "0.0.0"
+    "@napi-rs/webcodecs-darwin-x64": "1.0.0",
+    "@napi-rs/webcodecs-darwin-arm64": "1.0.0",
+    "@napi-rs/webcodecs-linux-x64-gnu": "1.0.0",
+    "@napi-rs/webcodecs-linux-x64-musl": "1.0.0",
+    "@napi-rs/webcodecs-win32-x64-msvc": "1.0.0",
+    "@napi-rs/webcodecs-linux-arm64-gnu": "1.0.0",
+    "@napi-rs/webcodecs-linux-arm64-musl": "1.0.0",
+    "@napi-rs/webcodecs-win32-arm64-msvc": "1.0.0",
+    "@napi-rs/webcodecs-linux-arm-gnueabihf": "1.0.0"
   }
 }

package/standard.d.ts

@@ -296,6 +296,28 @@ export type VideoPixelFormat =
   | 'BGRA'
   | 'BGRX'
 
+/**
+ * Layout information for a single plane
+ * @see https://w3c.github.io/webcodecs/#dictdef-planelayout
+ */
+export interface PlaneLayout {
+  /** Byte offset from the start of the buffer to the start of the plane */
+  offset: number
+  /** Number of bytes per row (stride) */
+  stride: number
+}
+
+/**
+ * DOMRectInit for specifying regions
+ * @see https://drafts.fxtf.org/geometry/#dictdef-domrectinit
+ */
+export interface DOMRectInit {
+  x?: number
+  y?: number
+  width?: number
+  height?: number
+}
+
 /**
  * VideoFrame buffer init
  * @see https://w3c.github.io/webcodecs/#dictdef-videoframebufferinit
@@ -311,6 +333,10 @@ export interface VideoFrameBufferInit {
   timestamp: number
   /** Duration in microseconds */
   duration?: number
+  /** Layout for input planes (offset and stride per plane) */
+  layout?: PlaneLayout[]
+  /** Visible rect within the coded frame */
+  visibleRect?: DOMRectInit
   /** Display width */
   displayWidth?: number
   /** Display height */