gamut

Project Status: Early development. Do not use it for anything serious!

A collection of space-efficient image encoding libraries, organized as a Cargo workspace.

Why gamut?

The world doesn't lack image codecs. libavif/libaom, libwebp, and libjpeg-turbo are mature, fast, and battle-tested — we're not out to beat a decade of hand-tuned SIMD assembly on raw encode speed. gamut exists because "fast C that works" still leaves real gaps, and those gaps are exactly where a clean-slate, pure-Rust, permissively-licensed implementation wins.

• Memory safety on the industry's worst attack surface. Image parsers chew on hostile, attacker-controlled bytes from the open internet, and the C codecs have the CVE record to show how that goes — libwebp's CVE-2023-4863 was a zero-click, wormable heap overflow that triggered emergency out-of-band patches across browsers, Electron apps, and mobile OSes in a single week. Safe Rust deletes that entire bug class (spatial and temporal memory corruption) from the encode and parse paths. For anything that ingests untrusted images, that alone justifies the rewrite.

• Builds anywhere cargo does. No autotools, no CMake, no nasm/yasm, no vendored C, no FFI boundary to audit. cargo build cross-compiles cleanly to wasm32, aarch64, and musl targets that libaom makes miserable — one toolchain, reproducible builds, no system-library version skew.

• WASM as a first-class target, not an afterthought. The C codecs run through Emscripten come out large, slow to instantiate, and awkward to tree-shake. A native Rust → wasm build is smaller and talks to the JS/TS ecosystem directly, which makes serverless/edge image optimization (Workers, Lambda, and friends) practical instead of shipping a multi-megabyte blob.

• A genuinely clean license story. gamut deliberately targets royalty-free formats and ships under MIT OR Apache-2.0 — no GPL/LGPL reach, no vendored-code license soup, no static-linking exceptions to reason about. Patent-unencumbered formats deserve permissively-licensed code to match.

• Encoder-first, size-first — the gap the Rust ecosystem actually has. Most Rust imaging is decode-only and hands the hard encoders off to C wrappers. gamut is built the other way round: encoders are the product, and the thing we optimize is output bytes at a given quality and speed, with the space/time tradeoff documented per format. That's the number that lands on storage and bandwidth bills.

• One codebase, shared primitives. Color management, DSP, bitstream, and container parsing live in shared crates (gamut-color, gamut-dsp, gamut-bitstream, gamut-isobmff, gamut-riff) instead of being re-implemented inside each separate C library. Consistent behavior across formats, one API, one place to fix a color bug — and you compile in only the formats you enable via Cargo features.

• Readable enough to change. Implemented clean-slate from the official specs in references/, the code is something you can actually audit, fork, and experiment with — not decades of accreted platform #ifdefs and inline assembly.

Scope

The initial focus is AVIF, WebP, and JPEG — the formats with the best size-versus-compatibility tradeoff today. JPEG XL is intentionally out of scope for now (it is better served by a dedicated effort). The other format crates in the tree (HEIC, VVC, AV2, JXL) are scaffolding, and may move or be dropped as the focus sharpens.

Usage

Add the umbrella gamut crate and enable only the formats you need:

[dependencies]
gamut = { version = "0.1", features = ["avif", "jxl"] }

The umbrella has no default features, so a bare dependency compiles only gamut-core. The primitives feature additionally re-exports the shared building blocks (gamut::color / gamut::dsp / gamut::bitstream) for tooling and sandbox use; all enables it along with every format.

Crates

All cargo metadata except per-crate version is centralized in the root [workspace.package] / [workspace.dependencies]; each crate inherits the shared fields via .workspace = true and sets its own version (see Versioning).

Prerequisites

• Rust (rustup) -- toolchain (channel pinned via rust-toolchain.toml); see Minimum Supported Rust Version for the lower bound
• just -- command runner
• Lefthook -- git hooks manager
• cargo-llvm-cov -- code coverage tool
• jq -- JSON processor (optional; used by just versions)
• cargo-edit -- provides cargo set-version (optional; used by just bump)

Quick Start

cargo build --workspace
cargo test --workspace

Development

Minimum Supported Rust Version (MSRV)

The MSRV is Rust 1.88 (stable), built against edition 2024. This is the lowest version CI is expected to support, and it is declared once in the root [workspace.package] (rust-version = "1.88"); every crate inherits it via rust-version.workspace = true.

Policy:

• The MSRV is the floor we test and publish against, not necessarily the newest toolchain. Day-to-day development tracks the latest stable (pinned to the stable channel in rust-toolchain.toml).
• Raising the MSRV is a deliberate, semver-relevant change: bump rust-version in the root Cargo.toml and note it here. Pre-1.0, an MSRV bump rides a minor release.
• Edition (2024) is likewise centralized in [workspace.package] and inherited by every crate; it changes only alongside an MSRV bump that allows it.

Git Hooks

This project uses Lefthook. Pre-commit hooks auto-fix formatting and linting on staged files. Pre-push hooks run format checks, lint checks, tests, and a coverage gate.

CI/CD

GitHub Actions runs format checks, linting, tests, and coverage on pushes to master and pull requests.

Code Coverage

This project uses cargo-llvm-cov for LLVM-based code coverage. CI enforces a minimum of 80% line coverage.

just coverage

The bindings/binary crates (gamut-cli, gamut-wasm, gamut-ffi) are excluded from the gate — their entry points are not meaningfully unit-testable.

AI Policy

Vibe-coded contributions are welcome. AI-assisted PRs are accepted as long as you personally vouch for the work — you've read it, you understand it, and you stand behind it as if you'd written every line — and it matches the project's existing code style and requirements. The CI and git hooks loosely enforce the bare minimum; meeting that bar is necessary but not sufficient. Review your output before opening a PR.

Versioning

Every crate is versioned independently following SemVer, based on its own changes. There is no guarantee that versions line up across the workspace — a change to one codec bumps only that crate (and anything that depends on it), so version numbers drift apart over time. Only version is per-crate; shared metadata such as the edition and MSRV stays workspace-owned.

Bumps are automated: release-plz reads each crate's conventional-commit history, computes its next version, and updates dependents' requirements as needed. Each crate keeps its own CHANGELOG.md and is tagged and GitHub-released as <crate>-v<version> (e.g. gamut-core-v0.2.0) — there is no single repo-wide version tag, so the umbrella gamut crate's version serves as the headline "project" version. Run just versions to see every crate's current version at a glance.

Releases

Publishing to crates.io is automated with release-plz. On pushes to master it opens a release PR (per-crate version bumps + changelogs); merging that PR publishes every changed crate in dependency order, then creates the per-crate tags and GitHub releases. Publishing authenticates via crates.io Trusted Publishing (OIDC) — no CARGO_REGISTRY_TOKEN secret is stored.

License

Licensed under either of MIT or Apache-2.0 at your option.