Skip to content

Latest commit

 

History

History
508 lines (379 loc) · 12.4 KB

ImageDecoder.mdx

File metadata and controls

508 lines (379 loc) · 12.4 KB
title ImageDecoder
description Decode image files into VideoFrame objects for processing
icon image

ImageDecoder

The ImageDecoder class decodes compressed image data (JPEG, PNG, WebP, GIF, AVIF) into VideoFrame objects that can be processed, edited, or re-encoded.

This implementation follows the [W3C WebCodecs ImageDecoder specification](https://w3c.github.io/webcodecs/#imagedecoder-interface).

Quick Example

Decode a JPEG or PNG image into a VideoFrame:

import { ImageDecoder } from 'node-webcodecs';
import { readFileSync } from 'fs';

// Read image file
const imageData = readFileSync('photo.jpg');

// Create decoder
const decoder = new ImageDecoder({
  data: imageData,
  type: 'image/jpeg',
});

// Wait for image to be fully parsed
await decoder.completed;

// Decode the image
const result = await decoder.decode();
const frame = result.image;

console.log(`Decoded ${frame.codedWidth}x${frame.codedHeight} image`);

// Process the frame...

// IMPORTANT: Always close frames when done
frame.close();
decoder.close();
**Always call `frame.close()` on decoded images**

Decoded VideoFrame objects hold native memory that is not tracked by JavaScript's garbage collector. Forgetting to close frames will cause memory leaks.

// Good
const result = await decoder.decode();
processFrame(result.image);
result.image.close();  // Release memory

// Bad - memory leak!
const result = await decoder.decode();
processFrame(result.image);
// Forgot to close!

Supported Formats

Format MIME Type Animated
JPEG image/jpeg No
PNG image/png No
WebP image/webp Yes
GIF image/gif Yes
AVIF image/avif Yes

Use ImageDecoder.isTypeSupported() to check format support at runtime.

Constructor

new ImageDecoder(init: ImageDecoderInit): ImageDecoder

Creates a new ImageDecoder instance.

Parameters

Configuration object for the decoder. The compressed image data. Can be a `Buffer`, `ArrayBuffer`, `TypedArray`, or a `ReadableStream` for progressive loading.
<ParamField path="type" type="string" required>
  The MIME type of the image (e.g., `'image/jpeg'`, `'image/png'`, `'image/webp'`).
</ParamField>

<ParamField path="colorSpaceConversion" type="'default' | 'none'" default="'default'">
  How to handle color space conversion.
  - `'default'`: Convert to sRGB color space
  - `'none'`: Keep original color space
</ParamField>

<ParamField path="desiredWidth" type="number">
  Desired output width for scaling. The decoder may scale during decode for efficiency.
</ParamField>

<ParamField path="desiredHeight" type="number">
  Desired output height for scaling. The decoder may scale during decode for efficiency.
</ParamField>

<ParamField path="preferAnimation" type="boolean" default="true">
  For images with both animated and static representations (like APNG), whether to prefer the animated version.
</ParamField>

Example

import { ImageDecoder } from 'node-webcodecs';

// From Buffer
const decoder = new ImageDecoder({
  data: imageBuffer,
  type: 'image/png',
});

// With scaling
const thumbnailDecoder = new ImageDecoder({
  data: imageBuffer,
  type: 'image/jpeg',
  desiredWidth: 200,
  desiredHeight: 200,
});

// From ReadableStream (progressive loading)
const streamDecoder = new ImageDecoder({
  data: readableStream,
  type: 'image/webp',
});

Accessors

Whether all image data has been received and parsed.

For images loaded from a Buffer, this is true immediately after construction. For images loaded from a ReadableStream, this becomes true when the stream ends.

A promise that resolves when `complete` becomes `true`.

Use this to wait for the image to be fully loaded before decoding:

const decoder = new ImageDecoder({ data: stream, type: 'image/gif' });
await decoder.completed;
console.log('Image fully loaded, ready to decode');
The MIME type of the image being decoded.
console.log(decoder.type); // 'image/jpeg'

Static Methods

isTypeSupported()

static isTypeSupported(type: string): Promise<boolean>

Check if a MIME type is supported for decoding.

```typescript import { ImageDecoder } from 'node-webcodecs';

async function checkSupport() { const formats = ['image/jpeg', 'image/png', 'image/webp', 'image/avif', 'image/gif'];

for (const format of formats) { const supported = await ImageDecoder.isTypeSupported(format); console.log(${format}: ${supported ? 'Supported' : 'Not supported'}); } }

checkSupport(); // Output: // image/jpeg: Supported // image/png: Supported // image/webp: Supported // image/avif: Supported // image/gif: Supported

</Accordion>

**Parameters:**
- `type` (string): The MIME type to check

**Returns:** `Promise<boolean>` - Resolves to `true` if the format is supported

## Instance Methods

### decode()

```typescript
decode(options?: ImageDecodeOptions): Promise<ImageDecodeResult>

Decode an image frame.

```typescript const decoder = new ImageDecoder({ data: imageBuffer, type: 'image/jpeg', });

const result = await decoder.decode();

console.log(Decoded: ${result.image.codedWidth}x${result.image.codedHeight}); console.log(Complete: ${result.complete});

result.image.close();

</Accordion>

<Accordion title="Example: Animated GIF frame extraction">
```typescript
import { ImageDecoder } from 'node-webcodecs';
import { readFileSync } from 'fs';

async function extractGifFrames(gifPath: string) {
  const gifData = readFileSync(gifPath);

  const decoder = new ImageDecoder({
    data: gifData,
    type: 'image/gif',
  });

  await decoder.completed;

  const frames = [];
  let frameIndex = 0;

  while (true) {
    try {
      const result = await decoder.decode({ frameIndex });

      // Clone the frame if you need to keep it after decoding more frames
      const frameClone = result.image.clone();
      frames.push(frameClone);

      // Close the original
      result.image.close();

      console.log(`Extracted frame ${frameIndex}: ${frameClone.codedWidth}x${frameClone.codedHeight}`);

      // Check if this was the last frame
      if (result.complete) {
        break;
      }

      frameIndex++;
    } catch (error) {
      // No more frames
      break;
    }
  }

  console.log(`Extracted ${frames.length} frames from GIF`);

  // Process frames...

  // Clean up
  frames.forEach(frame => frame.close());
  decoder.close();

  return frames.length;
}

extractGifFrames('animation.gif');
```typescript import { ImageDecoder, VideoEncoder, VideoFrame } from 'node-webcodecs';

async function convertWebpToVideo(webpPath: string, outputPath: string) { const webpData = readFileSync(webpPath);

const decoder = new ImageDecoder({ data: webpData, type: 'image/webp', preferAnimation: true, });

await decoder.completed;

// Get first frame to determine dimensions const firstResult = await decoder.decode({ frameIndex: 0 }); const { codedWidth, codedHeight } = firstResult.image;

const chunks: Buffer[] = []; const encoder = new VideoEncoder({ output: (chunk) => { const buffer = Buffer.alloc(chunk.byteLength); chunk.copyTo(buffer); chunks.push(buffer); }, error: console.error, });

encoder.configure({ codec: 'avc1.42E01E', width: codedWidth, height: codedHeight, bitrate: 2_000_000, });

// Encode first frame encoder.encode(firstResult.image, { keyFrame: true }); firstResult.image.close();

// Encode remaining frames let frameIndex = 1; while (true) { try { const result = await decoder.decode({ frameIndex }); encoder.encode(result.image); result.image.close();

  if (result.complete) break;
  frameIndex++;
} catch {
  break;
}

}

await encoder.flush(); encoder.close(); decoder.close();

writeFileSync(outputPath, Buffer.concat(chunks)); }

</Accordion>

**Parameters:**

<ParamField path="options" type="ImageDecodeOptions">
  Optional decode options.

  <Expandable title="ImageDecodeOptions properties">
    <ParamField path="frameIndex" type="number" default="0">
      The index of the frame to decode. For static images, this is always `0`. For animated images (GIF, WebP, AVIF), use this to decode specific frames.
    </ParamField>

    <ParamField path="completeFramesOnly" type="boolean" default="true">
      Whether to only return complete frames. When `true`, the promise will not resolve until the frame is fully decoded. When `false`, partial frames may be returned for progressive images.
    </ParamField>
  </Expandable>
</ParamField>

**Returns:** `Promise<ImageDecodeResult>` - Resolves to an object containing the decoded frame

### reset()

```typescript
reset(): void

Reset the decoder state. Aborts any pending decode operations.

```typescript const decoder = new ImageDecoder({ data: imageBuffer, type: 'image/png', });

// Decode first frame const result1 = await decoder.decode(); result1.image.close();

// Reset decoder state decoder.reset();

// Decode again const result2 = await decoder.decode(); result2.image.close();

decoder.close();

</Accordion>

**Returns:** `void`

### close()

```typescript
close(): void

Close the decoder and release all resources. The decoder cannot be used after calling this method.

```typescript const decoder = new ImageDecoder({ data: imageBuffer, type: 'image/jpeg', });

try { const result = await decoder.decode(); // Process frame... result.image.close(); } finally { // Always close the decoder decoder.close(); }

</Accordion>

**Returns:** `void`

## Interfaces

### ImageDecodeResult

The result of a decode operation.

<ResponseField name="image" type="VideoFrame" required>
  The decoded image as a `VideoFrame`. You must call `close()` on this frame when done to release memory.
</ResponseField>

<ResponseField name="complete" type="boolean" required>
  Whether the image is fully decoded. For animated images, this indicates whether this is the last frame.
</ResponseField>

### ImageDecodeOptions

Options for the `decode()` method.

<ResponseField name="frameIndex" type="number">
  The index of the frame to decode (0-based). Defaults to `0`.
</ResponseField>

<ResponseField name="completeFramesOnly" type="boolean">
  Whether to only return complete frames. Defaults to `true`.
</ResponseField>

### ImageDecoderInit

Configuration for creating an `ImageDecoder`.

<ResponseField name="data" type="BufferSource | ReadableStream<BufferSource>" required>
  The compressed image data.
</ResponseField>

<ResponseField name="type" type="string" required>
  The MIME type of the image.
</ResponseField>

<ResponseField name="colorSpaceConversion" type="'default' | 'none'">
  Color space conversion mode.
</ResponseField>

<ResponseField name="desiredWidth" type="number">
  Desired output width for scaling.
</ResponseField>

<ResponseField name="desiredHeight" type="number">
  Desired output height for scaling.
</ResponseField>

<ResponseField name="preferAnimation" type="boolean">
  Whether to prefer animated representation.
</ResponseField>

## See Also

<CardGroup cols={2}>
  <Card title="VideoFrame" icon="film" href="https://github.com/api-reference/VideoFrame">
    Learn about the VideoFrame class returned by decode()
  </Card>
  <Card title="VideoEncoder" icon="clapperboard" href="https://github.com/api-reference/VideoEncoder">
    Encode decoded images into video
  </Card>
  <Card title="Thumbnail Generation" icon="images" href="https://github.com/cookbook/thumbnails">
    Generate thumbnails from images and videos
  </Card>
  <Card title="Video Transcoding" icon="shuffle" href="https://github.com/cookbook/transcode">
    Complete transcoding workflow
  </Card>
</CardGroup>