media-img (C++)

CMake-based media-img binary: CLI, HTTP REST (serve), and line-delimited JSON IPC (ipc). Image processing uses libvips — the same engine as Sharp (Node.js), exposed with a similar option model. Optional .env is loaded from the working directory (laserpants/dotenv-cpp).

API reference (underlying library): libvips VipsImage

Prerequisites

Requirement	Notes
CMake	≥ 3.20
C++ compiler	C++17
libvips	Required — pkg-config (Unix) or `third_party/vips-dev-*` / `VIPS_ROOT` (Windows)
Git	For `FetchContent` (CLI11, Asio, httplib, json, dotenv)
Node.js	Optional — `npm run test:media` (Node 18+)

Installing libvips

Debian / Ubuntu

sudo apt install libvips-dev pkg-config

macOS (Homebrew)

brew install vips pkg-config

Windows (official dev bundle — recommended)

npm run setup:vips

Downloads build-win64-mxe vips-dev-x64-all into third_party/vips-dev-*. CMake adds that path automatically; DLLs are copied to dist/ on link.

Pin the version with MEDIA_VIPS_VERSION (default 8.18.2) if needed.

Alternatively set VIPS_ROOT or CMAKE_PREFIX_PATH to a tree with include/vips/vips.h and lib/libvips.lib.

Build

cd packages/media/cpp
cmake --preset release
cmake --build --preset release

Binary: dist/media-img (.exe on Windows).

Formats — same idea as Sharp / libvips

Sharp wraps libvips: decode → process → encode. We do the same with vips_image_new_from_file and format-specific savers.

	Supported
Resize / geometry	`fit`, dimensions, crop (`cover` + `position`), letterbox (`contain` + `background`), rotate, flip, flop, EXIF `autorotate`
Output (first-class in code)	JPEG (`Q`, strip), PNG (`compression`), WebP (`Q`, strip), TIFF
AVIF / HEIC	Via `format` / file extension and `quality` (libvips HEIF/AVIF saver — needs libheif in your libvips build)
Anything else libvips knows	Fallback: `vips_image_write_to_file` from extension (e.g. GIF, JP2K, … depending on how libvips was built)

Input types match whatever your libvips build can load (the Windows vips-dev-x64-all bundle includes broad loader support). Set output format with the output path extension or JSON / CLI format (webp, avif, jpg, …).

Sharp-like options (`resize` / JSON)

Sharp concept	`media-img` / JSON field	Notes
`resize.fit`	`fit`	`inside`, `cover`, `contain`, `fill`, `outside`
`resize.position`	`position`	`centre`, `attention`, `entropy`, … → libvips interesting
`resize.kernel`	`kernel`	`nearest`, `cubic`, `mitchell`, `lanczos2`, `lanczos3` (default)
`jpeg	webp	… quality`
`png compression`	`png_compression`	0–9
`withoutEnlargement`	`without_enlargement`	Default true; CLI `--allow-enlargement` flips
EXIF orientation	`autorotate`	Default true; CLI `--no-autorotate`
Strip metadata	`strip_metadata`	Default true; CLI `--no-strip`
`rotate`	`rotate`	0, 90, 180, 270 (after autorotate)
`flip` / `flop`	`flip` / `flop`
Letterbox	`background`	`#rrggbb` for `contain`

REST POST /v1/resize accepts the same keys as columns in the table (plus input, output paths).

IPC sends one JSON object per line with the same keys.

Concurrency

HTTP serve: cpp-httplib default thread pool (CPPHTTPLIB_THREAD_POOL_COUNT — see upstream httplib.h).
libvips: processing is thread-safe per image; configure process-wide concurrency with VIPS_CONCURRENCY (or vips_concurrency_set in code later if needed).

CLI overview

media-img resize --help
media-img serve --help
media-img ipc --help

kbot subcommand forwards to KBOT_EXE (optional).

Tests

npm run test:media

Requires a built dist/media-img linked against libvips and fixture PNGs (npm run generate:assets if missing).

License

See LICENSE in this directory when present.

4.4 KiB Raw Blame History Unescape Escape