mono/packages/media/cpp

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 examples

Paths below use Unix style; on Windows run dist\media-img.exe and use .\ or full paths as needed.

Help and version

./dist/media-img --help
./dist/media-img resize --help
./dist/media-img -v

resize — fit inside a box (default), write WebP / AVIF by extension

# Max 800×600, stay inside the box, Lanczos3 (default), write JPEG quality 85 (default)
./dist/media-img resize photo.jpg out.jpg --max-width 800 --max-height 600

# Same, explicit quality
./dist/media-img resize photo.jpg out.jpg --max-width 800 --max-height 600 -q 90

# WebP output (quality applies)
./dist/media-img resize photo.jpg thumb.webp --max-width 400 --max-height 400 -q 82

# AVIF output (quality applies; needs HEIF/AVIF support in your libvips build)
./dist/media-img resize photo.png out.avif --max-width 1200 --max-height 1200 -q 50

# Force output format when the path has no extension you trust
./dist/media-img resize in.tif /tmp/out --format webp --max-width 512

resize — square images (1:1)

Use the same --max-width and --max-height (that value is the square side in pixels). Pick --fit:

fit	Result
cover	Fills the square; crops overflow (default crop: --position centre, or attention / entropy for smart crop).
contain	Full image inside the square; letterboxing on two sides if needed (--background).
fill	Stretches to the square (ignores aspect ratio).

# 512×512 crop-to-square (avatars, thumbnails)
./dist/media-img resize portrait.jpg avatar.jpg --fit cover --max-width 512 --max-height 512

# 1080×1080 WebP, smart crop on subject
./dist/media-img resize product.png grid.webp --fit cover --max-width 1080 --max-height 1080 --position attention -q 85

# Square canvas, no crop — padded bands with a colour
./dist/media-img resize panoramic.jpg square.jpg --fit contain --max-width 800 --max-height 800 --background '#111111'

# Exact square by stretching (rare)
./dist/media-img resize any.jpg out.jpg --fit fill --max-width 256 --max-height 256

REST / IPC JSON: e.g. "max_width": 512, "max_height": 512, "fit": "cover", "position": "attention".

resize — cover (crop), contain (letterbox), rotate / flip

# Cover: fill 1200×630, crop centre (use --position attention for smart crop)
./dist/media-img resize wide.jpg social.jpg --fit cover --max-width 1200 --max-height 630

# Contain: fit inside 800×600 canvas, letterbox with a background
./dist/media-img resize logo.png padded.png --fit contain --max-width 800 --max-height 600 --background '#1a1a1a'

# EXIF autorotate (default), then rotate 90° CCW, vertical flip
./dist/media-img resize img.jpg rotated.jpg --max-width 1024 --rotate 90 --flip

serve — HTTP REST

# Default: http://127.0.0.1:8080 — GET /health, POST /v1/resize with JSON body
./dist/media-img serve --host 127.0.0.1 -p 8080

Example resize request (paths must be readable/writable by the server process):

curl -s http://127.0.0.1:8080/health
curl -s -X POST http://127.0.0.1:8080/v1/resize \
  -H 'Content-Type: application/json' \
  -d '{"input":"/path/in.png","output":"/path/out.webp","max_width":400,"quality":80}'

ipc — one JSON line per connection (TCP; Unix socket on Linux/macOS)

./dist/media-img ipc --host 127.0.0.1 -p 9333
# elsewhere: send a single line, read one line back, e.g.
# {"input":"/tmp/a.jpg","output":"/tmp/b.webp","max_width":320,"format":"webp"}

kbot — forward to another binary (optional)

Requires KBOT_EXE pointing at the kbot executable; remaining args are passed through.

export KBOT_EXE=/path/to/kbot    # Windows: set KBOT_EXE=C:\path\to\kbot.exe
./dist/media-img kbot ai --prompt "hello"

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.