🖼️ avif-opt.sh

A smart AVIF optimizer for the command line — designed for the best image quality and smallest possible filesize with minimal effort.

This Bash script automates AVIF image conversion using libaom (the reference AV1 codec) and optional ImageMagick preprocessing.
It works great for web developers, photographers, and automated pipelines that need tiny yet high-quality images.

---

🚀 Features

✅ Best defaults out of the box

• Uses libaom (highest-quality AV1 encoder)
• Auto-detects grayscale → encodes as YUV 400 (smaller)
• Strips EXIF/ICC metadata (if ImageMagick is available)
• Runs multi-threaded (--jobs all) by default
• Produces a _best.avif and a CSV manifest with all variants

✅ Automatic quality ladder

• Tests a range of qualities (45–24 by default)
• Chooses the smallest file automatically

✅ Optional advanced flags

• Custom qualities, chroma sampling, speed, and depth
• Downscale or stop early when a size target is reached
• Try true lossless (YUV 444)
• Clean up all intermediate files and keep only the best

---

📦 Requirements

Core

• libavif command-line tool (avifenc)

  sudo apt install libavif-bin
  # or on macOS
  brew install libavif

Optional (for metadata stripping, resizing, grayscale detection)

• ImageMagick 7 (preferred)
  If your system only has the older convert command, you can symlink it:

  sudo ln -s "$(command -v convert)" /usr/local/bin/magick

  or upgrade:

  sudo apt install imagemagick

---

⚙️ Usage

🧠 Simple mode (recommended)

chmod +x avif-opt.sh
./avif-opt.sh photo.jpg

This will:

• Strip metadata (if ImageMagick is present)
• Try multiple quality levels
• Pick the smallest file automatically
• Output:
  • photo_best.avif
  • photo_manifest.csv (size, hash, and settings of all variants)

---

📁 Output example

photo_q45_y420.avif  (1.2 MB)
photo_q36_y420.avif  (1.0 MB)
photo_q30_y420.avif  (820 KB)
photo_q26_y420.avif  (740 KB)
photo_best.avif      (740 KB)
photo_manifest.csv

---

🔧 Advanced usage (for “nerds”)

You can fine-tune behavior with flags:

Flag	Description	Example
--qualities "list"	Custom quality ladder	--qualities "50,45,40,35,30,25"
--yuvs "list"	Chroma modes (420,422)	--yuvs "420,422"
`--threads N	all`	CPU threads
--speed N	AVIF speed 0–10 (lower = better)	--speed 2
`--depth 8	10	12`
--no-strip	Keep EXIF/ICC metadata	--no-strip
--downscale PCT	Downscale before encoding	--downscale 95%
--target-ratio 0.60	Stop once ≤60% of original size	--target-ratio 0.6
--try-lossless	Also encode lossless variant	--try-lossless
--keep-only-best	Delete all non-best variants	--keep-only-best

Example:

./avif-opt.sh big-photo.jpg out/   --qualities "50,45,40,35,30"   --downscale 95%   --target-ratio 0.6   --threads all   --keep-only-best

---

📊 CSV Manifest

Each run creates a manifest like:

filename,mode,quality,yuv,depth,speed,size_bytes,sha256
photo_q45_y420.avif,lossy,45,420,8,1,1023456,abcd1234...
photo_q40_y420.avif,lossy,40,420,8,1,983042,ef5678...
...
photo_best.avif,lossy,26,420,8,1,743112,9a5f...

You can use this for analytics or automated pipelines.

---

🧠 How it decides “best”

The script automatically picks the smallest file among all candidates (lossy + optional lossless).
If --target-ratio is set, it stops once the file is smaller than that ratio (e.g., ≤60% of original size).

---

💡 Recommended defaults

Parameter	Default	Why
YUV	420	best size/quality for web photos
Depth	8	smallest file size
Speed	1	good trade-off between speed & compression
Qualities	45,40,36,34,32,30,28,26,24	smooth coverage from high → small
Threads	all	use all CPU cores

---

🧰 Troubleshooting

🧩 “ℹ️ ImageMagick not found”

You have ImageMagick 6 (with convert, not magick). Either:

sudo ln -s "$(command -v convert)" /usr/local/bin/magick

or upgrade to IM7.

🧩 “avifenc not found”

Install libavif-bin or build from source:

sudo apt install libavif-bin

---

🧠 Why AVIF?

• ~40–60% smaller than JPEG/WebP at similar visual quality
• Full HDR and alpha transparency
• Supported by all modern browsers (Chrome, Firefox, Safari, Edge)
• Perfect for photography, web apps, and next-gen pipelines

---

📜 License

MIT License — do whatever you like, but a credit link is appreciated.

---

❤️ Credits

Created by devdudeio
Optimized for high-end multi-core systems and modern web pipelines.