bare-media

A set of media APIs for Bare

Install

npm i bare-media

Usage

Image:

import { image } from 'bare-media'

const preview = await image(path)
  .decode({ maxFrames })
  .resize({ maxWidth, maxHeight })
  .encode({ mimetype: 'image/webp' })

Video:

import { video } from 'bare-media'

const frames = video(path).extractFrames({ frameIndex })

Each method can also be used independently:

const rgba = await image.decode(buffer, { maxFrames })

Image API

decode()

Decode an image to RGBA

| Parameter | Type | Description | | ---------------- | ------ | --------------------------------------------------------- | | buffer | object | The encoded image | | opts.maxFrames | number | Max number of frames to decode in case of animated images |

encode()

Encodes an image to a specific format

| Parameter | Type | Description | | --------------- | ------ | ----------------------------------------------------------------------------------- | | buffer | object | The rgba image | | opts.mimetype | string | The mimetype of the output image | | opts.maxBytes | number | Max bytes for the encoded image (reduces quality or fps in case of animated images) | | opts... | any | Additional encoder-specific options |

crop()

Crop an image

| Parameter | Type | Description | | ------------- | ------ | ---------------------------- | | buffer | object | The rgba image | | opts.left | number | Offset from left edge | | opts.top | number | Offset from top edge | | opts.width | number | Width of the region to crop | | opts.height | number | Height of the region to crop |

resize()

Resize an image

| Parameter | Type | Description | | ---------------- | ------ | ----------------------------- | | buffer | object | The rgba image | | opts.maxWidth | number | Max width of the output rgba | | opts.maxHeight | number | Max height of the output rgba |

slice()

Limits an animated image to a subset of frames. If the image is not animated, it returns the same rgba.

| Parameter | Type | Description | | ------------ | ------ | ------------------------------------------------------------------------ | | buffer | object | The rgba image | | opts.start | number | Frame index at which to start extraction. Default 0. | | opts.end | number | Frame index at which to end extraction. Defaults to end of the animation |

orientate()

Apply EXIF orientation.

| Parameter | Type | Description | | ---------------- | ------ | --------------------------------------------------------------- | | buffer | object | The rgba image | | opts.file | Buffer | Optional. Input image used to extract EXIF metadata. | | opts.exif | number | Optional. EXIF orientation value. | | opts.transform | object | Optional. Transform object with rotate, flipH, and flipV. |

At least one of opts.file, opts.exif, or opts.transform is required. In a pipeline, orientate() can be called without options:

const rgba = await image(path).decode().orientate()

rotate()

Rotate an image in 90-degree multiples.

| Parameter | Type | Description | | ---------- | ------ | -------------------------------------------------------------- | | buffer | object | The rgba image | | opts.deg | number | Rotation in degrees. Allowed values: [0, 90, 180, 270] |

flip()

Flip an image horizontally or vertically.

| Parameter | Type | Description | | --------- | ------- | ------------------------------------------- | | buffer | object | The rgba image | | opts.h | boolean | Optional. Flip horizontally. Default true | | opts.v | boolean | Optional. Flip vertically |

read()

Read an image from a file path, URL, or buffer.

| Parameter | Type | Description | | --------- | ------ | ------------------------------------------- | | input | object | File path, http(s) URL, or raw image buffer |

save()

Write an encoded image buffer to a file.

| Parameter | Type | Description | | ---------- | ------ | ---------------------------------------- | | filename | string | Destination file path | | buffer | object | Encoded image buffer | | opts | object | Options passed through to fs.writeFile |

metadata()

[!IMPORTANT] This feature is experimental. The API is subject to change and may break at any time.

Read image metadata.

const data = await image(path).metadata()
const orientation = await image(path).metadata({ tag: 'orientation' })

| Parameter | Type | Description | | ---------- | ------ | ---------------------------------------- | | opts.tag | string | Optional. Read a single EXIF tag by name |

Returns:

| Field | Type | Description | | ------------- | ------ | ---------------------------------------------- | | exif | object | EXIF tags by name | | orientation | number | EXIF orientation, when present | | xmp | string | HEIF only. The raw XMP packet, when present | | mime | array | HEIF only. Any other mime item, when present | | uri | array | HEIF only. Every uri item, when present |

Supported formats: jpeg, tiff, heic, heif, avif

metadata.strip()

[!IMPORTANT] This feature is experimental. The API is subject to change and may break at any time.

Strip metadata from an image returning a new image buffer.

await image(path).metadata.strip().save(outPath)

| Parameter | Type | Description | | ---------------------- | ------- | ---------------------------------------------------------------------------- | | opts.keepColor | boolean | Keep color-transform metadata. Default true. Can only be disabled for JPEG | | opts.keepOrientation | boolean | Preserve the Exif orientation tag. Default false |

Check with isStripMetadataSupported() for supported types: jpeg, heic, heif, and avif.

Video API

extractFrames()

Extracts frames from a video in RGBA

| Parameter | Type | Description | | ----------------- | ------ | ------------------------------ | | opts.frameIndex | number | Number of the frame to extract |

metadata()

Basic metadata for the primary video stream

Returns:

| Field | Type | Description | | -------------------------- | ------- | ------------------------------------------------------ | | width | number | Width of the primary video stream | | height | number | Height of the primary video stream | | codec.id | number | FFmpeg codec id of the primary video stream | | codec.name | string | FFmpeg codec name of the primary video stream | | duration | number | Stream duration in seconds | | avgFramerate.numerator | number | Average frame rate numerator | | avgFramerate.denominator | number | Average frame rate denominator | | displayRotation | number | Rotation stored in display metadata | | rotation | number | Corrective rotation to display the video upright | | flipH | boolean | Whether the display metadata applies a horizontal flip | | flipV | boolean | Whether the display metadata applies a vertical flip |

Throws if the input has no video stream.

transcode()

[!IMPORTANT] This feature is experimental. The API is subject to change and may break at any time.

Transcode a media file to a different format

| Parameter | Type | Description | | ------------- | ------ | ------------------------------------------------------------------- | | opts.format | string | Output format name (e.g., mp4, webm, matroska). Default mp4 | | opts.width | number | Width of the output video | | opts.height | number | Height of the output video |

Supported formats: mp4 (VP9+Opus), webm (VP9+Opus), matroska/mkv (VP9+Opus)

Example

import { video } from 'bare-media'

for await (const chunk of video('input.mkv').transcode({
  format: 'mp4',
  width: 1280,
  height: 720
})) {
  console.log('Received chunk:', chunk.buffer.length)
}

CLI

bare-media [flags] [command]

Flags:
  --version|-v   Print version
  --help|-h      Show help

Commands:
  metadata       Print image or video metadata (experimental)
  convert        Convert an image
  transcode      Transcode a video
  types          List supported MIME types

Supported Types

Helpers to check supported media types are exposed in bare-media/types:

• supportedImageMimetypes: list of supported image mimetypes.
• supportedVideoMimetypes: list of supported video mimetypes.
• isImageSupported(mimetype): returns true if the mimetype is a supported image format.
• isVideoSupported(mimetype): returns true if the mimetype is a supported video format.
• isMediaSupported(mimetype): returns true if the mimetype is either a supported image or video format.
• isStripMetadataSupported(mimetype): returns true if metadata.strip() supports the mimetype.

Detect the MIME type of a buffer:

import { detectMimeType } from 'bare-media'

const mimetype = detectMimeType(buffer)

This may return non-media MIME types, use isMediaSupported() to validate support.

License

Apache-2.0