@napi-rs/webcodecs 0.0.0 → 1.1.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
@@ -17,13 +18,21 @@ WebCodecs API implementation for Node.js using FFmpeg, built with [NAPI-RS](http
 ## Installation
 
 ```bash
-npm install @napi-rs/webcodecs
+bun add @napi-rs/webcodecs
 # or
 pnpm add @napi-rs/webcodecs
 # or
 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