| title | ImageDecoder |
|---|---|
| description | Decode image files into VideoFrame objects for processing |
| icon | image |
The ImageDecoder class decodes compressed image data (JPEG, PNG, WebP, GIF, AVIF) into VideoFrame objects that can be processed, edited, or re-encoded.
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();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!| 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.
new ImageDecoder(init: ImageDecoderInit): ImageDecoderCreates a new ImageDecoder instance.
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>
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',
});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.
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');console.log(decoder.type); // 'image/jpeg'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');
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>