AVIFGAINMAPUTIL(1)

📦 version 1.4.2, in ubuntu stonking

💖 AVIFGAINMAPUTIL 💖

okay so bestie, welcome to the avifgainmaputil man page (that's manual section 1, user commands, iykyk) — it's the tool for manipulating AVIF images with HDR gain maps, and honestly? it's giving main character energy. sit down, grab a strawberry 🍓, we're doing this.

✨ SYNOPSIS ✨

avifgainmaputil <command> [options] [arguments...]

that's it. that's the whole vibe. you pick a <command>, you throw some [options] at it, you hand it your [arguments...], and it goes. 💅

🌈 DESCRIPTION 🌈

🎀 Available commands:

  • help — prints a command's usage. the little "wait what does this do again" button, and we love her for it.
  • combine — makes an AVIF image with a gain map out of a base image and an alternate image. two images walk in, one glow-up walks out ✨
  • convert — takes a JPEG with a gain map and converts it to AVIF.
  • tonemap — tone maps an AVIF image that has a gain map to a given HDR headroom (aka how much brighter the display can go compared to SDR white, yes that's literally the definition, keep up bestie 🫶).
  • swapbase — swaps the base and alternate images. like, if the base image is SDR and the alternate is HDR, this makes the base HDR. glow-up reversal, no cap.
  • extractgainmap — saves the gain map of an AVIF file as an image. pull the whole secret out, iconic.
  • printmetadata — prints the metadata of the gain map of an AVIF file. gossip, but for pixels 👑

🦋 General concepts:

Gain maps are the whole reason this tool exists, so let's get into it. Gain maps allow creating HDR (High Dynamic Range) images that look good on any display, including SDR (Standard Dynamic Range) displays. and that's not even the best part — images with gain maps are also backward compatible with viewers that do not support gain maps. everybody eats, periodt. 💖

An image with a gain map consists of a "base image", and a "gain map image". The gain map image contains information used to "tone map" the base image, in order to adapt it to displays with different HDR capabilities. Fully applying the gain map results in a different image called the "alternate image". The gain map can also be applied partially, giving a result in between the base image and the alternate image. so you don't just get two looks, you get the whole slider. obsessed.

Typically, either the base image or the alternate image is SDR, and the other one is HDR. Both images have a target "HDR headroom" that they are meant to be displayed on. The HDR headroom is the ratio between the maximum brightness of white that the display can produce, and the standard SDR white brightness. This value is usually expressed in log2. An SDR display has an HDR headroom of 0. An HDR display with a headroom of 1 can produce white that is twice as bright as SDR white. math but make it ✨glow✨.

Viewers that support gain maps will show the base image, or the alternate image, or something in between, depending on the display's current HDR headroom and the target headroom of the base image and alternate image. Viewers that do not support gain maps will always show the base image. no gain map support? no problem. she's still cute. 🙈

👀 SEE ALSO 👀

go read those too, they're the rest of the friend group and they ate. 🔥

this page is from libavif 1.4.0, dated March 2026 — so yeah, tell the group chat it's official 💜. mwah, stay hydrated, and remember: base image stays winning no matter what display shows up. 🎀🦋🌸

📦 where this page comes from