BENCHMARK_XL(1)

📦
version 0.11.2 · 9 versions
, in ubuntu stonking

✨ benchmark_xl — the manual, but make it make sense ✨

okay so bestie, you're in section 1 of the manual (User Commands, iykyk) and this is the whole entire page for benchmark_xl 💖 it's a benchmarking tool, it's giving main character energy for image codecs, and yes we are reading the WHOLE thing together, no skimming, periodt.

🌸 NAME 🌸

benchmark_xl - benchmark_xl

like. that's it. that's the name. iconic of it honestly 💅

🦋 SYNOPSIS 🦋

benchmark_xl [OPTIONS...]

that's the whole vibe check: you run it, you feed it [OPTIONS...], it does its thing ✨

💜 DESCRIPTION 💜

okay so here's the part where every single option lives. no cap, there are a LOT. grab a snack 🍓

  • --input=<string> — the file, or the file pattern that matches your input files. that's your corpus, bestie 🫶
  • --codec=<string> — a comma separated list of image codec descriptions to benchmark. yes, plural, you can throw multiple codecs in there and let them fight 🔥
  • --print_details, --noprint_details — prints size and distortion for each image. NOT safe for concurrent benchmark runs, so don't be out here running these side by side, it's giving chaos 💀
  • --print_details_csv, --noprint_details_csv — when print_details is used, print it as CSV instead. spreadsheet girlies rise 🌈
  • --extra_metrics=<string> — extra metrics to be computed. these ONLY show up with --print_details or --print_details_csv, so don't come crying if you forgot the flag 😭. it's a comma-separated list of NAME:COMMAND pairs; COMMAND gets invoked with the original image as the first argument, the decompressed image as a second argument, and the name of the file where to write the metric value (as a single floating point number) as the third argument. three args, no more, no less 💅
  • --print_more_stats, --noprint_more_stats — prints codec-specific stats. also NOT safe for concurrent benchmark runs 🙈
  • --print_distance_percentiles, --noprint_distance_percentiles — prints distance percentiles for the corpus. you guessed it: NOT safe for concurrent benchmark runs 💀
  • --silent_errors, --nosilent_errors — if true (that's the silent one), it doesn't print error messages on compression or decompression errors. the error counts are still visible in the 'Errors' column of the result table, so you're not flying blind 👀. ⚠️ heads up though: depending on the JXL build settings, error messages and asserts from within the codec may be printed irrespective of this flag anyway, so use a release build to ensure no messages. it's giving "I tried my best" 😭
  • --save_compressed, --nosave_compressed — saves the compressed files for each input image and each codec. so many little files. so cute 🎀
  • --save_decompressed, --nosave_decompressed — saves the decompressed files as PNG for each input image and each codec 🖼️
  • --output_extension=<string> — the extension (starting with a dot!) to use for saving output images. dot. don't forget the dot. 🫶
  • --output_description=<string> — color encoding (see ParseDescription; e.g. RGB_D65_SRG_Rel_709) for saving output images, and it defaults to sRGB ✨
  • --intensity_target=<scalar> — intended viewing intensity target in nits. defaults to 255 for SDR images, and 4000 for HDR images (that's when the input image uses PQ or HLG transfer function) ⭐
  • --dec-hints=<string> — color encoding hints for the input images to the encoder. comma separated key=value pairs. the key color_space indicates ColorEncoding (see ParseDescription; e.g. RGB_D65_SRG_Rel_709) for input images without color encoding (such as PNM) 🧚
  • --override_bitdepth=<unsigned> — if nonzero, store the given bit depth in the JPEG XL file metadata (1-32), instead of using the bit depth from the original input image. you get to be in charge, lowkey 👑
  • --mul_output=<scalar> — if nonzero, multiplies linear sRGB by this and clamps to 255 🌈
  • --save_heatmap, --nosave_heatmap — saves the heatmap images 🔥🔥🔥 (literally heatmap)
  • --heatmap_good=<scalar> — if greater than zero, use this as the good threshold for creating heatmap images 💚
  • --heatmap_bad=<scalar> — if greater than zero, use this as the bad threshold for creating heatmap images ❤️
  • --write_html_report, --nowrite_html_report — creates an html report with original and compressed images. show and tell time 🎀
  • --html_report_self_contained, --nohtml_report_self_contained — Base64-encode the images in the HTML report rather than use external file names. may cause very large HTML data size, so like, be aware 💀
  • --html_report_use_decompressed, --nohtml_report_use_decompressed — show the compressed image as decompressed to --output_extension 👀
  • --html_report_add_heatmap, --nohtml_report_add_heatmap — add heatmaps to the image comparisons 🔥
  • --markdown, --nomarkdown — adds formatting around the ASCII table so it renders correctly in Markdown based interfaces ✨ (yes bestie, your table can slay in Markdown too)
  • --more_columns, --nomore_columns — print extra columns in the table 📊
  • --originals_url=<string> — url prefix to serve original images from in the html report 🌐
  • --output_dir=<string> — if not empty, save compressed and decompressed images here 📁
  • --num_threads=<integer> — the number of threads for concurrent benchmarking. defaults to 1 thread per CPU core (that's when it's negative) 🧵
  • --inner_threads=<integer> — the number of extra threads per task. defaults to occupy cores (when negative) 🧵🧵
  • --encode_reps=<unsigned> — how many times to encode (>1 for more precise measurements). defaults to 1 🔁
  • --decode_reps=<unsigned> — how many times to decode (>1 for more precise measurements). defaults to 1 🔁
  • --sample_tmp_dir=<string> — directory to put samples from input images 🗂️
  • --num_samples=<integer> — how many sample areas to take 🔍
  • --sample_dimensions=<integer> — how big the areas to sample from the input are 📐
  • --error_pnorm=<scalar> — smallest p norm for pooling butteraugli values 🧈
  • --show_progress, --noshow_progress — show activity dots per completed file during the benchmark. dots!! ✨✨✨
  • --skip_butteraugli, --noskip_butteraugli — if true, it doesn't compute distance metrics, only compression and decompression speed and size. the distance numbers shown in the table are invalid when you do that, so don't quote them 💀
  • --decode_only, --nodecode_only — if true, it only decodes, and the input files must be compressed with a compatible format for the given codec(s). it only measures decompression speed and sizes, and it can only use a single set of compatible decoders. the distance numbers AND compression speeds shown in the table are invalid in this mode 🙈
  • --generations=<unsigned> — if nonzero, enables generation loss testing with this number of intermediate generations. that is, the decoded image gets re-encoded, iteratively, N times. generational trauma but for pixels 😭 (it's for science, bestie)
  • --custom_codec_extension=<string> — converts input and output of the codec to this file type (default: png) 🎀
  • --custom_codec_colorspace=<string> — if not empty, converts input and output of the codec to this colorspace 🌈
  • --custom_codec_quiet, --nocustom_codec_quiet — whether stdin and stdout of the custom codec should be shown. shy codec or loud codec, your call 🤫
  • --qprogressive, --noqprogressive — enable quantized progressive mode for AC ✨
  • --progressive, --noprogressive — enable progressive mode for AC ✨
  • --progressive_dc=<integer> — enable progressive mode for DC ✨
  • --noise=0|1 — enable(1)/disable(0) noise generation 🌫️
  • --dots=0|1 — enable(1)/disable(0) dots generation ⚫
  • --patches=0|1 — enable(1)/disable(0) patch dictionary 🩹
  • --debug_image_dir=<string> — if not empty, saves debug images for each input image and each codec that provides it to this directory 🐛🔍
  • --qtables=<string> — custom base quantization tables 📋
  • --search_q_start=<scalar> — starting quality for quality-to-target search 🎯
  • --search_q_min=<scalar> — minimum quality for quality-to-target search ⬇️
  • --search_q_max=<scalar> — maximum quality for quality-to-target search ⬆️
  • --search_d_min=<scalar> — minimum distance for quality-to-target search 📉
  • --search_d_max=<scalar> — maximum distance for quality-to-target search 📈
  • --search_tolerance=<scalar> — percentage value; if the quality-to-target search result relative error is within this, the search stops 🛑
  • --search_q_precision=<scalar> — if the last quality change in quality-to-target search is within this value, the search stops 🛑
  • --search_first_iter_slope=<scalar> — slope of the first extrapolation step in quality-to-target search 📏
  • --search_max_iters=<integer> — maximum search steps in quality-to-target search 🏁
  • --avif_chroma_subsampling=444/422/420/400 — default AVIF chroma subsampling (default: 444) 🎨
  • -h, --help — prints this help message. all options are shown above 🫶 (yes, the whole list. we told you it was a lot)

👑 AUTHOR 👑

this manual page was written by Mathieu Malaterre <malat@debian.org> for the Debian GNU/Linux system (but may be used by others) 💖 thank you for your service, legend 🫡

okay bestie that's the whole page, we made it, we survived, we're stronger 🦋

sign-off time ✨ this was benchmark_xl version 0.11.2, dated August 2026 — and that's the BENCHMARK_XL(1) page, done and dusted 💅💖 no cap.

📦 where this page comes from