byteshaver ๐๏ธ
byteshaver is a command-line utility focusing on converting images into other formats,
specifically focusing on support for modern image standards and encoders.
byteshaver simplifies the process of batch converting images,
optimizing for both performance and storage efficiency.
[!NOTE] Heritage: this project started out as a fork of imgc-rs by tduyng. Over time it has diverged too much from the original, so it is no longer a fork and is now developed independently as byteshaver. Thanks to @tduyng for the original work and the head start!
Usage example using the docker container:
> docker
) )
Key Features ๐งฐ
- Broad Format Support: Works with many supported image formats โ including JPEG XL and HEIC/HEIF/AVIF input, and modern targets like AVIF, JPEG XL and optimized PNG (oxipng).
- EXIF control: strip (default), keep, or filter specific tags โ with orientation baked into the pixels when the tag is dropped.
- Animation support: re-encode animated GIF/WebP/APNG input to animated WebP, APNG or GIF with frame timing and loop count preserved.
- Desktop GUI: drag-and-drop files or folders onto a queue-centric window (gui/README.md); conversions are byte-identical to the CLI.
- Works with huge images:
Can optimize very large images (~1GiB input image size,
32Kx16K px dimensions). - Speedy Processing:
Written in Rust to keep overhead to a minimum, we also take advantage of
rayonfor parallel processing. - Input selection using Glob Patterns: Target selection is made intuitive for cli enthusiasts via glob patterns.
- Scriptable: machine-readable JSON-lines event logs via
--json-log, typed job API (byteshaver::job) for embedding the converter in other Rust software. - Custom Output: Choose where your converted images are saved.
Supported formats
Input formats ๐ผ๏ธ
To keep it simple: JPEG, PNG (incl. APNG), GIF, WebP (incl. animated), JPEG XL, BMP, DDS, Farbfeld, HDR, ICO, EXR, PNM, QOI, TGA, TIFF
Input images are decoded using the image crate,
please see their documentation for supported image formats.
Additionally, HEIC, HEIF, HIF and AVIF (still images) are decoded through libheif
when the dec-heif feature is compiled in:
- multi-image files (e.g. iPhone bursts) can be expanded into one output per image
via
--heif-image-policy all(outputs are then namedstem.ext,stem_1.ext, ...); by default only the primary image is converted - EXIF metadata is extracted (with the rotation already baked in by the decoder), XMP and ICC profiles are carried over where the target format supports them
- 10/12-bit (HDR) sources are down-converted to 8-bit with a printed warning
Without the feature, HEIC/HEIF/AVIF inputs fail per-file with a clear message while the
rest of the batch keeps converting. dec-heif is enabled by default in all release
binaries (Linux musl static-pie, Linux GUI, Windows): the libheif version matching the
bindings is compiled in statically (libheif-sys embedded-libheif), with HEVC decode via
a statically linked libde265 and AV1/AVIF decode via dav1d (see tools/libheif-static/
and docs/plans/17-static-libheif-and-jxl-avx512.md).
The Windows binaries use the gnullvm/ucrt toolchain (UCRT ships with Windows 10+).
Building locally requires pkg-config plus static libde265 + dav1d
(tools/libheif-static/build-decode-only.sh) on the library search path; on Windows,
use the llvm-mingw variant (build-decode-only-windows.sh).
JPEG XL (.jxl) inputs are decoded with jxl-oxide
(still images and animations, 8/16-bit, EXIF/XMP boxes and ICC profiles).
Requires the jxl feature (enabled by default).
Output formats ๐ค
webp, webp encoder using thewebpcrate (libwebp bindings) - offers lossy and lossless encodingwebp-image, webp encoder using theimagecrate - offers lossless encodingavif, avif encoder using theravifcrate - offers lossy and lossless encoding. EXIF that survives the policy is embedded natively by ravif (>= 0.13) as a standard HEIFExifitem after the AV1 encode โ with no measurable encoding overhead.png, png encoder using thepngcrate - offers lossless encoding (with optional eXIf embedding)jpeg, jpeg optimizer using themozjpegcrate - only optimizes images (with optional EXIF embedding)jxl, jpeg-xl encoder using in-tree FFI bindings tolibjxl(vendored static build viajpegxl-src) - offers lossy and lossless encoding, real animated output (frame durations), EXIF embedding and the fullJxlEncoderFrameSettingIdsurface via repeatable--setting ID=VALUEflags. Requires thejxlfeature (enabled by default) andcmake, a C++ compiler andnasmat build time.oxipng, optimal lossless PNG compression using theoxipngcrate - PNGโPNG inputs are re-optimized byte-level passthrough (bit-exact, preserves palette/tRNS/APNG chunks); other inputs are transcoded first. Requires theopt-oxipngfeature (enabled by default).webp-anim, animated webp encoder using thewebp-animationcrate - animated input (gif/animated webp/APNG) with frame timing + loop count preserved. Requiresanim-webp(default).apng, animated PNG encoder using thepngcrate - animated input with millisecond-exact delays and loop count preserved. Requiresanim-apng(default).gif, (animated) gif encoder using theimagecrate - delays rounded to the GIF-standard 10 ms.
Output format notes ๐
When working with very large input images, please keep in mind the output format limits. In particular:
webp: maximum dimension of 16384x16384pxavif: maximum dimension of 65536x65536px, note Baseline Profile and Advanced Profile limits if you want to be friendly to consuming hardware decoders. :)jxl: maximum dimension of 262144x262144px (level 5 codestream); animation frame delays are stored in millisecond ticks (sub-millisecond remainders are truncated)
JPEG XL notes ๐
The jxl target mirrors the cjxl option surface:
--quality(JPEG-style 0-100) and--distance(Butteraugli 0.0-25.0) are mutually exclusive; the mapping between them follows libjxl's ownJxlEncoderDistanceFromQuality.--losslessenables true bit-exact encoding (implies--original-profile).--effort 1..=10(default 7),--decoding-speed 0..=4(default 0).--color-encodingselects sRGB/linear sRGB (grayscale flavors for gray inputs) or--color-encoding icc-passthroughto embed the source ICC profile verbatim.- EXIF metadata follows the global
--exifpolicy and is embedded as a (Brotli-compressed)Exifmetadata box, which automatically enables the box-based container. - Advanced libjxl frame settings can be passed through verbatim, e.g.
--setting brotli_effort=9or--setting modular=1(ids resolve case-insensitively; unknown ids print the full list). - Building requires
cmake, a C++ compiler andnasm(the vendored libjxl is compiled once during the cargo build).
Animations ๐๏ธ
Animated inputs (gif, animated webp, APNG) are decoded with frame timing and
loop count preserved, and can be re-encoded to animated targets:
| target command | animated output | container notes |
|---|---|---|
webp-anim |
yes (webp-animation/libwebp) | loop count preserved; EXIF embedded via a EXIF RIFF chunk |
apng |
yes (png crate) | .png output; a separate default image keeps non-APNG viewers happy; EXIF embedded as eXIf chunk |
gif |
yes (image crate) | no EXIF support |
Rounding notes:
- internal timing is millisecond-exact;
giftargets round down to the GIF-standard 10 ms granularity (minimum 10 ms per frame), apngwrites millisecond-exact delays (1/1000 s fractions),- animated
webpkeeps millisecond-exact cumulative timestamps.
Converting animated input to a target that cannot encode animations
(jpeg, avif, still webp/png, ...) defaults to encoding the first frame
with a notice. Use --animated-input error to fail such files instead
(e.g. in pipelines that must never silently drop animation), and
--max-animation-memory <MiB> (default 4096) to bound the memory used by
decoded frame buffers.
EXIF metadata ๐ธ
EXIF handling is controlled by global flags that work with every conversion command:
# strip all EXIF (this is the default) - orientation is baked into the pixels
# keep EXIF verbatim and embed it into the output
# keep everything except location and camera orientation
# keep only a whitelist of tags
# print all recognized tag names (also IFD wildcards: ifd0, exif, gps, ...)
Policies:
strip(default): removes all EXIF from outputs. Privacy-safe: before the pixels are re-encoded, theOrientationtag is applied to the image data, so photos never appear rotated/sideways in software that ignores EXIF.keep: copies EXIF verbatim into outputs where the container supports it; pixels are left untouched (viewers rotate using the Orientation tag).filter: keep all tags except--exif-except <TAGS>, or keep only--exif-only <TAGS>(mutually exclusive). Tag lists accept comma-separated tag names (see--exif-list-tags), IFD wildcards (ifd0,exif,gps,interop) and numeric tags (0x8825). Unknown names abort with the recognized set.
Where EXIF ends up per target:
| target | EXIF embedding |
|---|---|
jpeg |
APP1 segment |
png, apng |
eXIf chunk |
oxipng |
eXIf chunk; under keep/filter metadata stripping is forced off, under strip an unset --strip is bumped to safe |
webp, webp-image, webp-anim |
EXIF RIFF chunk |
jxl |
Exif metadata box (Brotli-compressed) |
avif |
standard HEIF Exif item (ISOBMFF), embedded natively by ravif after the AV1 encode |
gif |
not supported โ a warning is printed per file and the count appears in the run summary |
Notes:
- inputs without EXIF simply produce outputs without EXIF, regardless of policy (no synthetic metadata is created),
- when a
filterresult cannot be re-serialized, the verbatim EXIF is kept and a warning is printed (EXIF is never silently lost), - ICC profiles are carried over where supported (e.g.
jxl); a dedicated ICC policy flag may arrive later.
Overwrite & collision behavior โป๏ธ
By default an existing output file is never touched (the file is reported as skipped). This can be tuned:
--overwrite-if-smaller: replace an existing output when the new encode is smaller (keeps the best result of multiple runs),--overwrite-existing: always replace existing outputs,--discard-if-larger-than-input: don't write the output at all when the encode is bigger than the input file (useful when re-optimizing already-compressed directories).
Collisions (e.g. a.jpg and a.png in one batch both map to a.webp): the
first conversion wins, later ones are reported as skipped with a notice.
Exception: multi-image HEIF expansion (--heif-image-policy all) always uses
distinct names (stem.ext, stem_1.ext, ...).
JSON logs
Every conversion command accepts the global --json-log <PATH> flag (enabled
in default builds): alongside the regular terminal output, one JSON object per
progress event is appended per line (JSON lines), e.g.
byteshaver "images/**/*.jpg" webp -o out --json-log run.jsonl
Each line is flushed immediately, so the log can be tailed while a batch
runs; events include Started, FileStarted, FileFinished (with the
per-file outcome), ProgressStats (running byte/count totals), Notice
(warnings) and Finished.
GUI (desktop) ๐ฑ๏ธ
byteshaver ships a desktop GUI as a separate workspace crate
(gui/ = byteshaver-gui, egui/eframe): a queue-centric single window where
the entire window is a drag-and-drop target โ drop files or folders
anywhere (folders are expanded recursively by the core), or use the native
file picker. One global target format with its full option surface, EXIF /
collision / animation policies, live per-file progress, cancel, and a report
panel with JSONL export. Conversions run through the same headless core the
CLI uses, so outputs are byte-identical.
Build it from source:
# binary: target/release/byteshaver-gui
Notes:
- Linux: needs GL at runtime (X11 or Wayland); file dialogs use the xdg-desktop-portal service. No GTK development packages are required to compile.
- The encoder list reflects the build: encoders compiled out (e.g. a build
without
jxl) are shown grayed-out with the reason, and HEIC/HEIF/AVIF input is only offered when the core was built with thedec-heiffeature. - Settings (output dir, encoder + options, policies, window size) persist in
the OS config dir under
byteshaver-gui/settings.json. - GUI binaries are published for every release alongside the CLI (see Installation); Linux builds use the X11 windowing backend. See gui/README.md for build details.
Requests
If this does not cover your needs, please feel free to open an issue to request additional input and/or output formats.
I am focusing on supporting modern image formats supported in browsers, as this tool is optimally suited for optimizing static directories for different web apps.
For a good overview of browser support, see the caniuse.com pages for different images, e.g.: avif, webp.
Installation ๐พ
Using published binaries ๐ก
Binaries for Windows and Linux are built for every tag โ the classic CLI binary and the desktop GUI as separate downloads:
byteshaver-<version>[-cpu]โ CLI, Linux (musl, static-pie)byteshaver-<version>[-cpu].exeโ CLI, Windowsbyteshaver-gui-<version>[-cpu]โ desktop GUI, Linux (musl, static-pie, X11)byteshaver-gui-<version>[-cpu].exeโ desktop GUI, Windows...-packed[.exe]variants of each of the above โ optional self-extracting packed copies (65โ70 % smaller download/disk at the cost of ~9 ms slower process startup on Linux)
The default artifacts are not packed: measurements
(docs/zstd-packer-analysis.md,
docs/upx-binary-size-report.md) show packed
variants pay a fixed per-invocation decompression toll. The -packed
variants are produced by the in-repo zstd packer
(tools/packer) in a dedicated CI job for size-constrained
setups; they are plain zstd frames and can be restored with zstd -d.
The suffixless artifacts target x86-64-v3 (Intel Haswell / AMD Zen and newer).
AVX-512-and-newer CPUs are served by runtime dispatch inside the shipped
libraries, so no separate v4+ artifacts are built by default; tuned builds
(x86-64-v4, znver3, znver5) are opt-in via the repository's CPU_TARGETS_EXTRA
setting. Every artifact ships with a .sha256 checksum. Third-party code embedded by the packer
(zstd, BSD-2-Clause) is attributed in
THIRD-PARTY-NOTICES.md.
Feature notes: all release binaries include HEIC/HEIF/AVIF input
(dec-heif, statically embedded libheif + libde265 + dav1d). The Windows
binaries use the gnullvm/ucrt toolchain (UCRT ships with Windows 10 and
newer). The Linux GUI build uses the X11 windowing backend.
See the GitHub releases page for downloads.
Using the docker image ๐ณ
Docker containers are also built for every tag. The image is the prebuilt
static Linux binary on a minimal alpine base โ it includes HEIC/HEIF/AVIF
input support (dec-heif, statically linked) and starts instantly. To
reproduce the entire build inside docker instead, the default
docker build . compiles everything from source (see Dockerfile):
images and validates the complete chain โ including a real HEIC file decoded
inside the container โ before they are published.
See the Docker Hub page for available tags.
# directory passthrough on linux
# note that on windows the volume passthroughs need to have absolute paths, e.g. (for powershell)
How to Use byteshaver ๐งโ๐ป
Basic Usage
The byteshaver program uses glob patterns for target selection:
Specifying an output directory ๐๏ธ
Common recipes ๐ณ
# re-optimize existing PNGs in place (bit-exact, never grows)
# shrink a photo library to jpeg-xl at explicit quality
# convert a folder of gifs to animated webp (timing + loop count preserved)
# strip location data from everything that gets re-encoded,
# keep all other EXIF where the target supports it
# pipeline-friendly run: fail on dropped animations, log every event
Cleaning up generated files ๐งน
Warning: Use this command with caution. This is basically rm -rf with regex.
Command Help ๐
For detailed command usage, see all arguments with --help or -h:
)
)
)
)
)
)
)
));
));
) );
)
<PATTERN>
) )
)
) if )
|| ))
)
; );
);
| ) ))
)
)
) )
)
> Note: )
> expose
Command-specific options (every command also accepts all global options shown above โ
run byteshaver <command> --help for the full list with descriptions):
| command | command-specific options |
|---|---|
webp |
--lossless ยท -q, --quality <0-100> (default 90) |
webp-image |
โ |
avif |
-q, --quality <0-100> (default 90) ยท -s, --speed <1-10> (default 3) ยท --bit-depth eight|ten|auto ยท --color-model y-cb-cr|rgb ยท --alpha-color-mode unassociated-dirty|unassociated-clean|premultiplied ยท -a, --alpha-quality <0-100> |
png |
--compression-type default|fast|best ยท --filter-type no-filter|sub|up|avg|paeth|adaptive |
jpeg |
โ |
jxl |
-q, --quality <0-100> ยท --distance <0-25> (mutually exclusive with --quality) ยท --lossless ยท -e, --effort <1-10> (default 7) ยท --container ยท --original-profile ยท --decoding-speed <0-4> ยท --intensity-target <nits> ยท --bit-depth 8|16 ยท --color-encoding srgb|linear-srgb|srgb-luma|linear-srgb-luma|icc-passthrough ยท --setting <ID=VALUE> (repeatable) |
oxipng |
-l, --level <0-6|max> (default 2) ยท --zopfli ยท --zopfli-iterations <n> (default 15) ยท --interlace keep|none|adam7 ยท --strip none|safe|all ยท --filters <list> ยท --optimize-alpha ยท --no-reduction <list> ยท --scale-16 ยท --fix-errors ยท --timeout-secs <s> |
webp-anim |
--lossless ยท -q, --quality <0-100> (default 90) ยท --kmin <n> ยท --kmax <n> ยท --minimize-size ยท --allow-mixed ยท --method <0-6> |
apng |
--compression-type default|fast|best ยท --filter-type no-filter|sub|up|avg|paeth|adaptive |
gif |
-s, --speed <1-10> |
clean |
โ |
Examples
Input Directory Structure
Example of webp command:

Example of clean command:

Building from source
Prerequisites
- Ensure you have the latest stable version of
RustandCargoinstalled on your system. - Nasm is needed for building
rav1e. Install viaapt install nasm/apk add nasm/choco install nasm. cmake, a C++ compiler andnasmare needed for building the vendoredlibjxl(jpeg-xl support; enabled by default via thejxlfeature). Install viaapt install cmake g++ nasm/apk add cmake g++ nasm.- The patched
jpegxl-srcis a git submodule (with libjxl nested inside): after cloning, initialize it and apply the patch:git submodule update --init --recursive && tools/patches/apply.sh(adds libjxl's AVX-512 highway targets; seetools/patches/). dec-heif(HEIC/HEIF/AVIF input, default) needspkg-configand static libde265 + dav1d at build time; libheif itself is compiled in bylibheif-sys'sembedded-libheiffeature. Generate the static codec libraries withtools/libheif-static/build-decode-only.sh <dist>and pointPKG_CONFIG_PATHat<dist>/lib/pkgconfig.
Installation Guide
Install via crate
To install via the published crate, execute the following command:
Install from git
# 1. Clone the repository:
# 2. Build the project:
# 3. Install locally
Uninstalling
To uninstall, remove the tool via cargo uninstall:
What's Next
- Testing (unit + integration suite;
cargo test --workspace) - Publishing automation (binaries for CLI + GUI, docker incl. libheif validation)
- Introduce advanced options for image transformations (resize, rotate)
- Progress bar for encoding
- Expand support for additional input formats
-
avif(via libheif) -
png -
jpeg(incl. progressive/pjpeg fallback decoding) -
heic/heif(input, via libheif /dec-heiffeature; statically embedded in all release binaries since plan 17) -
jxl/jpeg-xl(via jxl-oxide; stills + animation + metadata) -
heicin static release binaries (needs a statically linkable libheif + codec stack in CI) - animated
avifinput - incoming wishes
-
- Expand support for additional export formats by including more encoding libraries
-
jxl(libjxl, full option surface) -
oxipng(lossless PNG re-optimization) - animated
webp/apng/gif - animated
avif(blocked upstream: needs libheif โฅ 1.20 with an AV1 encoder; seedocs/plans/06-*)
-
- Image metadata handling (EXIF data preservation/stripping/filtering)
-
avifEXIF embedding (native Exif item via ravif >= 0.13)
-
- Output logs (JSON-lines event log via
--json-log) -
winresourceintegration (application icon and .exe metadata for Windows binaries) - GUI (egui/eframe desktop front-end; drag-and-drop queue; see
gui/)- GUI packaging polish (AppImage/.app/NSIS installers, icons, file associations)
License
This project under the MIT License.