@astropub/codecs

Codecs

Codecs lets you use read, write, edit, and analyze images.

npm install @astropub/codecs

Usage

import * as fs from 'node:fs/promises'
import * as codecs from '@astropub/codecs'

// load the JPG image
const image = await codecs.load(
	await fs.readFile('./kitten.jpg')
)

image.type   // string representing the image type ('image/jpeg')
image.data   // Uint8Array representing the image data
image.width  // number representing the image width
image.height // number representing the image height
image.ext    // string representing the image extension ('jpg')

const decoded = await image.decode()

decoded.data   // Uint8ClampedArray representing the decoded image data
decoded.width  // number representing the decoded image width
decoded.height // number representing the decoded image height

// encode the image as Avif & WebP, at 320, 640, & 960
for (const size of [ 320, 640, 960 ]) {
	const resized = await decoded.resize({ width: size })

	for (const type of [ 'image/avif', 'image/webp' ]) {
		const encoded = await resized.encode(type, { quality: 80 })

		encoded.type   // string representing the encoded image type ('image/webp')
		encoded.data   // Uint8Array representing the encoded image data
		encoded.width  // number representing the encoded image width (320 | 640 | 960)
		encoded.height // number representing the encoded image height
		encoded.ext    // string representing the encoded image extension ('webp')

		await fs.writeFile(`./kitten-${size}.${encoded.ext}`, encoded.data)
	}
}

API

load

The load function returns a loaded image. It accepts a string path, file URL, Buffer, Response, or TypedArray.

const image = await codecs.load('./kitten.jpg')

image.type   // string representing the image type ('image/jpeg')
image.data   // Uint8Array representing the image data
image.width  // number representing the image width
image.height // number representing the image height
image.ext    // string representing the image extension ('jpg')

decode

The decode function returns a decoded image. It accepts a Buffer or TypedArray.

const buffer = await fs.readFile('./kitten.jpg')

const decoded = await codecs.decode(buffer)

decoded.data   // Uint8ClampedArray representing the decoded image data
decoded.width  // number representing the decoded image width
decoded.height // number representing the decoded image height

Individual decoders are available for avif, jpg, jxl, png, webp, and wp2.

import * as codecs from '@astropub/codecs'

codecs.avif.decode(await fs.readFile('./kitten.avif'))
codecs.jpg.decode(await fs.readFile('./kitten.jpg'))
codecs.jxl.decode(await fs.readFile('./kitten.jxl'))
codecs.png.decode(await fs.readFile('./kitten.png'))
codecs.webp.decode(await fs.readFile('./kitten.webp'))
codecs.wp2.decode(await fs.readFile('./kitten.wp2'))

encode

The encode function returns an encoded image. It accepts a decoded image.

const encodedImage = await codecs.encode(decoded, 'image/webp', { quality: 80 })

encoded.type   // string representing the encoded image type ('image/webp')
encoded.data   // Uint8Array representing the encoded image data
encoded.width  // number representing the encoded image width (320 | 640 | 960)
encoded.height // number representing the encoded image height
encoded.ext    // string representing the encoded image extension ('webp')

await fs.writeFile('./kitten.webp', encodedImage)

Individual encoders are available for avif, jpg, jxl, png, webp, and wp2.

import * as codecs from '@astropub/codecs'

codecs.avif.encode(decoded)
codecs.jpg.encode(decoded)
codecs.jxl.encode(decoded)
codecs.png.encode(decoded)
codecs.webp.encode(decoded)
codecs.wp2.encode(decoded)

resize

The resize function returns a resized image. It accepts a decoded image.

const resized = await codecs.resize(decoded, { width: 320 })

resized.data   // Uint8ClampedArray representing the resized image data
resized.width  // number representing the resized image width
resized.height // number representing the resized image height

If not specified, the resized height will be determined from the width using the formula width / naturalWidth * naturalHeight.

blur

The blur function returns a blurred image. It accepts a decoded image.

const blurred = await codecs.blur(decoded, { radius: 30 })

blurhash

The blurhash function returns a blurhashed image, using the Wolt BlurHash algorithm. It accepts a decoded image.

const blurhashed = await decoded.blurhash({ width: 32 })

If not specified, the height will be determined from the image width using the formula width / naturalWidth * naturalHeight.

type

The type function returns the content type for an image buffer. It accepts a Buffer or TypedArray.

// 'image/jpeg'
const type = await codecs.type(buffer)

ext

The ext function returns the file extension for an image buffer. It accepts a Buffer or TypedArray.

// 'jpg'
const ext = await codecs.ext(buffer)

DecodedImage

The DecodedImage class represents raw, decoded image data.

const decoded = new DecodedImage(
	data   // Uint8ClampedArray
	width  // number
	height // number
)

DecodedImage#encode

The encode function of DecodedImage returns a promised encoded image from the current decoded image.

const encoded = await decoded.encoded('image/webp') // EncodedImage<'image/web', Uint8Array>

DecodedImage#blur

The blur function of DecodedImage returns a promised blurred image from the current decoded image.

const blurred = await decoded.blur({ radius: 30 }) // DecodedImage

DecodedImage#blurhash

The blurhash function of DecodedImage returns a promised blurhashed image from the current decoded image.

const blurhash = await decoded.blurhash({ radius: 30 }) // DecodedImage

DecodedImage#resize

The resize function of DecodedImage returns a promised resized image from the current decoded image.

const resized = await decoded.resize({ width: 320 }) // DecodedImage

DecodedImage#color

The color property of DecodedImage returns the dominant color in the decoded image.

decoded.color // [ 57, 52, 43 ]

EncodedImage

The EncodedImage class represents analyzed, encoded image data.

const encoded = new EncodedImage(
	type   // string ('image/avif' | 'image/gif' | 'image/jpeg' | 'image/jxl' | 'image/png' | 'image/svg+xml' | 'image/webp' | 'image/webp2')
	data   // Uint8Array
	width  // number
	height // number
)

EncodedImage#decode

The decode function of EncodedImage returns a promised decoded image from the current encoded image.

const decoded = await encoded.decoded()

Types

ImageType

The ImageType type represents known image content types.

import type { ImageType } from '@astropub/codecs'

// 'image/avif' | 'image/gif' | 'image/jpeg' | 'image/jxl' | 'image/png' | 'image/svg+xml' | 'image/webp' | 'image/webp2'
ImageType

ImageType

The ImageType type represents known image content types.

import type { ImageType } from '@astropub/codecs'

// 'image/avif' | 'image/gif' | 'image/jpeg' | 'image/jxl' | 'image/png' | 'image/svg+xml' | 'image/webp' | 'image/webp2'
ImageType

License

Codecs is generally a remix of Squoosh!.

Code original to this project is licensed under the CC0-1.0 License.

Code from Squoosh! is licensed under the Apache-2.0 License, copyright Google Inc.

Code from Avif Encoder is licensed under the BSD License, copyright Joe Drago.

Code from MozJPEG is licensed under the Modified (3-clause) BSD License, copyright Viktor Szathmáry.

Code from JXL is licensed under the Apache-2.0 License, copyright Google Inc.

Code from OxiPNG is licensed under the MIT License, copyright Joshua Holmer.

Code from WebP is licensed under the Modified (3-clause) BSD License, copyright Google Inc.

Code from WebP2 is licensed under the Apache-2.0 License, copyright Google Inc.

Code from blurhash is licensed under the MIT License, copyright Olli Mahlamäki.