Tiny metadata, big coverage

Extract image and video metadata from raw bytes. No native binaries. Works in Node and Cloudflare Workers.

Install

bun install @nuitsukera/metadata

Quick start

import { extractMetadata } from '@nuitsukera/metadata';

const metadata = await extractMetadata(myBytes, 'image');
console.log(metadata);

Node examples

Image

import { extractMetadata } from '@nuitsukera/metadata';
import fs from 'fs';

const bytes = fs.readFileSync('./image.jpg');
const metadata = await extractMetadata(bytes, 'image');

console.log(metadata);
// {
//   type: 'image',
//   format: 'jpeg',
//   width: 1920,
//   height: 1080,
//   size: 245000
// }

Video

import { extractMetadata } from '@nuitsukera/metadata';
import fs from 'fs';

const bytes = fs.readFileSync('./video.mp4');
const metadata = await extractMetadata(bytes, 'video');

console.log(metadata);
// {
//   type: 'video',
//   format: 'mp4',
//   duration: 120.5,
//   width: 1920,
//   height: 1080,
//   bitrate: 5000000,
//   fps: 30,
//   codec: 'h264',
//   hasAudio: true
// }

Cloudflare Workers

import { extractMetadata } from '@nuitsukera/metadata';

const bytes = await fetch('https://example.com/image.jpg').then((res) => res.arrayBuffer());
const metadata = await extractMetadata(bytes, 'image');

Optional file info

import { extractMetadata } from '@nuitsukera/metadata';

const metadata = await extractMetadata(myBytes, 'image', {
  fileName: 'image.jpg',
  createdAt: new Date('2024-01-01T10:00:00Z'),
  modifiedAt: new Date('2024-01-02T10:00:00Z'),
});

API

extractMetadata(buffer, type, options?)

Parameters

• buffer (Buffer | Uint8Array | ArrayBuffer)
• type ('image' | 'video')
• options (optional)
  • fileName (string)
  • createdAt (string | Date) stored as ISO string
  • modifiedAt (string | Date) stored as ISO string

Returns Promise<Metadata>

Supported formats

| Type | Formats | | --- | --- | | Images | SVG, PNG, ICO, JPEG/JPG, GIF, BMP, TIFF/TIF, WebP, PSD, HEIC, AVIF | | Videos | MP4, WebM, MOV, WAV, MKV |

Type references

| Type | Description | | --- | --- | | ImageMetadata | Image metadata shape returned by extractMetadata when type is image. | | VideoMetadata | Video metadata shape returned by extractMetadata when type is video. | | Metadata | Union of ImageMetadata and VideoMetadata. | | MediaType | Literal union: image or video. | | BinaryLike | Input data: Buffer, Uint8Array, or ArrayBuffer. | | MetadataOptions | Optional file info: fileName, createdAt, modifiedAt. | | FileInfo | Returned file info: fileName, createdAt, modifiedAt. |

License

MIT © 2026 Nuitsukera