--- 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: ```typescript 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. ```javascript // 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 ```typescript 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. The MIME type of the image (e.g., `'image/jpeg'`, `'image/png'`, `'image/webp'`). How to handle color space conversion. - `'default'`: Convert to sRGB color space - `'none'`: Keep original color space Desired output width for scaling. The decoder may scale during decode for efficiency. Desired output height for scaling. The decoder may scale during decode for efficiency. For images with both animated and static representations (like APNG), whether to prefer the animated version. ### Example ```typescript 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: ```typescript 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. ```typescript console.log(decoder.type); // 'image/jpeg' ``` ## Static Methods ### isTypeSupported() ```typescript static isTypeSupported(type: string): Promise ``` 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 ``` **Parameters:** - `type` (string): The MIME type to check **Returns:** `Promise` - Resolves to `true` if the format is supported ## Instance Methods ### decode() ```typescript decode(options?: ImageDecodeOptions): Promise ``` 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(); ``` ```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)); } ``` **Parameters:** Optional decode options. 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. 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. **Returns:** `Promise` - 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(); ``` **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(); } ``` **Returns:** `void` ## Interfaces ### ImageDecodeResult The result of a decode operation. The decoded image as a `VideoFrame`. You must call `close()` on this frame when done to release memory. Whether the image is fully decoded. For animated images, this indicates whether this is the last frame. ### ImageDecodeOptions Options for the `decode()` method. The index of the frame to decode (0-based). Defaults to `0`. Whether to only return complete frames. Defaults to `true`. ### ImageDecoderInit Configuration for creating an `ImageDecoder`. The compressed image data. The MIME type of the image. Color space conversion mode. Desired output width for scaling. Desired output height for scaling. Whether to prefer animated representation. ## See Also Learn about the VideoFrame class returned by decode() Encode decoded images into video Generate thumbnails from images and videos Complete transcoding workflow