diff --git a/packages/media/cpp/README.md b/packages/media/cpp/README.md
index 0b5daa15..5090931e 100644
--- a/packages/media/cpp/README.md
+++ b/packages/media/cpp/README.md
@@ -50,6 +50,19 @@ 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 |