Brotli compression and decompression in safe Rust

A round trip

[dependencies]
mbrotli = "0.5.21"

use mbrotli::{Compressor, Decompressor, EncoderConfig, Quality};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let input = "hello, smaller world! ".repeat(1000);
    let mut encoder = Compressor::new(EncoderConfig::default().with_quality(Quality::Q5))?;
    let compressed = encoder.compress(input.as_bytes())?;

    let mut decoder = Decompressor::new(Default::default())?;
    assert_eq!(decoder.decompress(&compressed)?, input.as_bytes());
    Ok(())
}

Requires Rust 1.89 or later. Getting started continues from here with memory reuse, streaming and feature selection.

Pick a quality

Quality is the first decision: the default is 11, the slowest and smallest. Each bar is the compressed size of the 211 MB Silesia corpus against its original size.

mbrotli 0.5.20 in lzbench 2.4.1 on one thread of an AMD Ryzen 9 7950X VDS. Your data and machine will differ.

See the lzbench run for the command and raw output, and benchmark results for every quality against Google’s C implementation and other Rust crates.

Find your path

What you can rely on

• Safe implementation, not a C wrapper. Production code forbids unsafe; SIMD goes through fearless_simd. Google’s C library is only a test and benchmark oracle.
• Reference-compatible output. Qualities 0–11 are compared byte for byte with Google Brotli under equivalent streaming settings. See what is claimed and how it is checked.
• No hidden I/O or threads. Sessions touch only the buffers you pass in, and parallel compression hands tasks to your scheduler. The library does not create a thread pool.
• Reusable state. A codec keeps its workspace between payloads, under a retention policy you choose.

Framing and other formats behind the experimental feature may change in a patch release.

Getting started

Build a complete round trip, then choose the API that fits your application. Requires Rust 1.89+.

Install

cargo new brotli-demo
cd brotli-demo
cargo add mbrotli@0.5.21

Or add this to Cargo.toml:

[dependencies]
mbrotli = "0.5.21"

Compress and decompress

Replace src/main.rs with this complete program:

use mbrotli::{Compressor, Decompressor, EncoderConfig, Quality};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let input = "hello, smaller world! ".repeat(1000);
    let config = EncoderConfig::default().with_quality(Quality::Q5);
    let mut encoder = Compressor::new(config)?;
    let compressed = encoder.compress(input.as_bytes())?;

    let mut decoder = Decompressor::new(Default::default())?;
    let restored = decoder.decompress(&compressed)?;
    assert_eq!(restored, input.as_bytes());

    println!("{} input bytes → {} compressed bytes", input.len(), compressed.len());
    Ok(())
}

cargo run --release

Choose the quality explicitly: the default is Q11. Higher quality spends more CPU searching for compression opportunities. Compare speed and output size on your data; the benchmark pages show how results vary with input and quality.

Reuse the workspace and output

A codec retains working memory between calls. compress_into appends a stream and returns its range; clear the destination when you want to reuse it for a new payload.

use mbrotli::{Compressor, Decompressor, EncoderConfig, Quality};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut encoder = Compressor::new(
        EncoderConfig::default().with_quality(Quality::Q5),
    )?;
    let mut decoder = Decompressor::new(Default::default())?;
    let mut output = Vec::new();

    for payload in [b"first message".as_slice(), b"second message".as_slice()] {
        output.clear();
        let stream = encoder.compress_into(payload, &mut output)?;
        assert_eq!(decoder.decompress(&output[stream])?, payload);
    }
    Ok(())
}

See retention policies to control which workspace allocations remain after an operation. Caller output capacity is separate.

Stream through Write

Write plain input into the adapter, then call finish to obtain a complete Brotli stream. Dropping the writer does not finalize it.

use mbrotli::{Compressor, Decompressor, EncoderConfig, InputSize, Quality};
use std::io::Write;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let input = b"a payload arriving in two writes";
    let mut encoder = Compressor::new(
        EncoderConfig::default().with_quality(Quality::Q5),
    )?;
    let stream = InputSize::Exact(input.len() as u64).into();
    let mut writer = encoder.writer(Vec::new(), stream)?;
    writer.write_all(&input[..10])?;
    writer.write_all(&input[10..])?;
    let compressed = writer.finish().map_err(mbrotli::io::FinishError::into_error)?;

    let mut decoder = Decompressor::new(Default::default())?;
    assert_eq!(decoder.decompress(&compressed)?, input);
    Ok(())
}

For a retryable sink failure, FinishError::into_parts returns the error and writer. into_error discards the writer, as this in-memory example does. The streaming guide explains completion, backpressure, reader read-ahead, and direct sessions.

Choose features

The default features enable std and both codecs. To build only one codec, drop std, or enable framing and other experimental formats, see Cargo features.

Next steps

• Sans I/O compression and decompression: caller buffers, progress counts, and completion.
• Read / Write I/O: readers and writers for raw, parallel, and framed streams.
• Parallel compression: scoped threads, Rayon, files, and streaming.
• Framing containers: multiple resources, metadata, and indexed reads.
• Choose your API: every entry point for both codecs, with its guide.
• Configuration and features: quality, window, and Cargo features.
• Decompression and limits: budgets for untrusted input.
• Examples: pick a recipe and run the repository examples.

Choose your API

Compression and decompression expose the same I/O shapes. Pick the row that matches how your application already moves bytes, then follow its guide. New to the crate? Start with getting started.

Both codecs

Compressor and Decompressor own reusable working state. Keep one alive across payloads when allocation reuse matters.

Parallel compression

ParallelCompressor is a separate execution strategy for compression: it splits the input into independent segments and hands them to your executor as tasks. The library does not create a thread pool. The output is one ordinary Brotli stream, decoded by the ordinary Decompressor. Requires std.

See parallel compression for scoped threads, Rayon, budgets, disk staging, and streaming.

Guides by task

Errors

ConfigError covers configuration, DictionaryError covers dictionary preparation, EncodeError covers compression, and SizeOverflow covers size-bound arithmetic. I/O adapters return std::io::Error; writer finalization preserves the writer in FinishError.

Reference

• API reference on docs.rs
• Compatibility and validation: what is byte-identical to Google Brotli, and how it is checked
• Benchmark results for every quality, with raw data
• Architecture: how the implementation works
• Development and benchmarking for contributors

Examples

The recipes below include complete programs and round-trip assertions. Examples use the default std, compression, and decompression features unless stated otherwise. The documentation workflow compiles and runs their Rust code against the current checkout.

Run from the repository

Initialize the C reference submodule used by development builds:

git submodule update --init --recursive
cargo run --release --example compress

The parallel file example uses caller-owned scoped threads and disk staging. The destination must not already exist:

cargo run --release --example parallel -- input.bin output.br

For a parallel batch, all taken tasks must run or be dropped before finalization. For a streaming adapter, keep workers running while the adapter blocks. For writers, finish each resource and the enclosing stream or container explicitly.

Verify the documented recipes

python3 scripts/docs.py test-examples

This creates a temporary Cargo consumer under target/, depends on the local crate with experimental enabled and on Rayon, and runs each fenced Rust program from the recipe guides: getting started, configuration, buffers, decompression, streaming, parallel, frames, Sans I/O compression/decompression, and the I/O guide. It does not exercise the codec with --all-features, because that would also enable no_std and remove the std APIs these recipes demonstrate.

Configuration and features

Three things are configured separately: the encoder (how hard to search), the stream (what you know about one input), and the Cargo features (which codecs and adapters are compiled in). Decoder settings are covered in decompression and limits.

Choose a quality first

EncoderConfig::default() uses quality 11, the most expensive search. Set the quality explicitly for your workload:

use mbrotli::{Compressor, EncoderConfig, Quality};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = EncoderConfig::default().with_quality(Quality::Q5);
    let mut encoder = Compressor::new(config)?;
    let compressed = encoder.compress(b"configured payload")?;
    assert!(!compressed.is_empty());
    Ok(())
}

Speed and size depend on your data. The benchmark pages show both for every quality.

Encoder settings

EncoderConfig holds settings shared by successive streams:

Validated values reject out-of-range inputs. Compressor::new and reconfigure check combinations, including Large Window’s quality minimum. The capability table lists the minimum quality of each format.

StreamConfig carries the declared input size and logical stream offset. Its default is unknown size and offset zero. For a complete known input, use StreamConfig::from(InputSize::Exact(input.len() as u64)).

What each quality supports

Unsupported combinations return errors. External dictionary references require the same dictionaries at the decoder. Large Window and shared-dictionary streams require a decoder that supports the corresponding extension. See dictionaries and extended formats for each format and compatibility and validation for what is checked against C.

Cargo features

The default feature set is std, compression, and decompression.

no_std requires a global allocator. It excludes I/O adapters, parallel compression, framed I/O adapters, and profiling, and uses compile-time SIMD selection. Cargo features are additive: another dependency can re-enable a codec or std. Leave std and hotpath* disabled throughout the dependency graph for a std-free build.

See codec features and no_std support for the gates and their checks.

Buffers and memory reuse

Every call involves two kinds of memory: the destination you hand to the codec, and the workspace the codec keeps for itself. You control both.

Output buffers

compress returns a new Vec<u8>. compress_into appends to the supplied vector and returns the range containing the new stream; existing bytes remain intact. On failure, the vector’s length rolls back to its original value.

compress_to_slice returns the number of bytes written. Allocate a conservative buffer using Compressor::max_compressed_size:

use mbrotli::{Compressor, EncoderConfig, Quality};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let input = b"data to compress";
    let mut encoder = Compressor::new(
        EncoderConfig::default().with_quality(Quality::Q5),
    )?;
    let bound = Compressor::max_compressed_size(input.len())?;
    let mut output = vec![0; bound];
    let written = encoder.compress_to_slice(input, &mut output)?;
    output.truncate(written);
    assert_eq!(output, encoder.compress(input)?);
    Ok(())
}

A slice exactly as long as the stream also suffices. An undersized slice returns an error and may contain a partial prefix; retry the complete operation with a larger slice. Capacity does not select a different encoding.

Reusing memory

A compressor retains one encoder workspace. Compatible calls reset its logical state and reuse its allocations. Incompatible resolved settings can rebuild that workspace. Destination capacity is managed separately by the caller.

Set the policy with Compressor::builder(config).with_retention(policy).build(). Use trim(policy) for immediate cleanup. retained_bytes() reports owned heap allocation sizes; it excludes caller buffers, shared dictionaries, and allocator overhead. A retention ceiling is not a peak process-memory limit.

For simultaneous independent streams, use one compressor per worker. fork_empty() copies configuration, backend, and retention settings without copying the workspace. For one stream split across workers, see parallel compression.

Decompression and limits

Decompressor owns reusable state. decompress returns a Vec, decompress_into appends atomically, and decompress_to_slice writes into caller storage. Sessions report consumed/produced counts; reader and writer adapt synchronous I/O.

Set limits for untrusted input

The default accepts one complete raw member and extended window declarations up to 62 bits. Numeric budgets are unlimited by default. Configure them for your application before decoding input you do not control:

use mbrotli::{DecodeLimits, DecoderConfig, Decompressor, WindowLimit};

fn decode_payload(input: &[u8]) -> Result<Vec<u8>, Box<dyn std::error::Error>> {
    let limits = DecodeLimits::default()
        .with_max_input_bytes(Some(1 << 20))
        .with_max_output_bytes(Some(8 << 20))
        .with_max_workspace_bytes(Some(32 << 20));
    let config = DecoderConfig::default()
        .with_window_limit(WindowLimit::standard(24)?)
        .with_limits(limits);
    let mut decoder = Decompressor::new(config)?;
    Ok(decoder.decompress(input)?)
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let payload = b"a payload from the network";
    let compressed = mbrotli::Compressor::new(Default::default())?.compress(payload)?;
    assert_eq!(decode_payload(&compressed)?, payload);
    Ok(())
}

The workspace budget excludes caller output and borrowed dictionaries; it is not a process-memory limit. Keep the decoder across calls when reuse matters.

Members, dictionaries and backends

MemberMode::Concatenated accepts successive raw members. DecodeDictionary prepares decoding data without encoder indexes; PreparedDictionary can also be borrowed. RAW dictionaries work in all profiles; serialized/custom dictionaries require experimental.

Vec appends are rolled back on failure. The decoder specializes its command loops and history copies for the selected CPU backend using safe fearless_simd abstractions.

See decoder mechanics and compatibility limits.

Where to go next

Streaming and completion

Use streaming when the payload does not fit in memory, arrives in pieces, or must leave before the input ends. There are three shapes, and they drive the same state machine:

Readers and writers require std. Sessions also work with no_std and alloc, and fit async runtimes and event loops.

Readers and writers

reader(source, stream) consumes source bytes and yields transformed bytes through Read. writer(sink, stream) accepts source bytes through Write and delivers transformed bytes to the sink. Compression takes plain input; decompression takes compressed input. Both adapter families require std APIs.

use mbrotli::{Compressor, EncoderConfig, InputSize, Quality};
use std::io::Write;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let payload = b"streamed payload";
    let mut encoder = Compressor::new(
        EncoderConfig::default().with_quality(Quality::Q5),
    )?;
    let stream = InputSize::Exact(payload.len() as u64).into();
    let mut writer = encoder.writer(Vec::new(), stream)?;
    writer.write_all(payload)?;
    let compressed = writer.finish().map_err(mbrotli::io::FinishError::into_error)?;
    assert!(!compressed.is_empty());
    Ok(())
}

For a decoder reader, pass compressed input and DecodeStreamConfig::default(), then read the restored bytes to EOF. into_parts() recovers any reader read-ahead. A decoder writer must also be finished: finalization reports incomplete or invalid input. In a direct decoder session, declare final input with DecodeOperation::Finish.

A writer borrows the compressor and owns its sink. Use write_all for input, flush for an intermediate decoding boundary, and finish to terminate the stream. Frequent flushes add block boundaries and can increase output size.

try_finish(&mut self) supports retrying finalization after an I/O error. Consuming finish returns the sink on success; FinishError retains the writer on failure. Use into_parts() to recover both the error and writer for retry. into_error() discards the writer.

The writer retains pending output across short writes and sink errors. An input write can succeed after accepting bytes even if delivery then fails; that delivery error is reported on a subsequent drain. Continue according to the returned byte counts rather than replaying accepted input. Dropping a writer performs no finalization.

A reader owns its input source and borrows the compressor. Read until EOF to receive the complete compressed stream. Dropping it early abandons that stream.

Sessions

For direct buffer control, start creates an EncoderSession. Call process with input, output, and an Operation:

Use Progress to advance by the reported consumed and written counts. Finish can require several calls when output buffers are small. Sessions retain their own pending data and do not retain the caller’s slices.

A dropped unfinished session invalidates partial encoder state, allowing a fresh stream on the next call. A session discarded with mem::forget requires Compressor::recover() before reuse.

Read / Write I/O

Use std adapters to connect the codecs to files, network streams, in-memory buffers, and other implementations of Read or Write. Adapters drive the same sessions as the Sans I/O APIs, adding buffering and synchronous I/O conventions.

API map

The library has no dedicated framed decoder Write adapter. Its event API keeps resource boundaries and metadata visible; forward each payload event to an appropriate Write destination. It also has no parallel decoder: parallel compression produces one ordinary raw Brotli stream.

All adapters on this page require std. Enable experimental for framing. no_std removes the std surface even when std is also enabled.

Raw compression and decompression through Read

An encoder reader consumes plain bytes and yields compressed bytes. A decoder reader consumes compressed bytes and yields restored bytes. std::io::copy drives each one to EOF. Use a File or socket in place of a slice.

use mbrotli::{Compressor, Decompressor, EncoderConfig, InputSize, Quality};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let input = b"pull plain bytes through the encoder\n".repeat(100);
    let mut encoder = Compressor::new(
        EncoderConfig::default().with_quality(Quality::Q5),
    )?;
    let stream = InputSize::Exact(input.len() as u64).into();
    let mut reader = encoder.reader(input.as_slice(), stream)?;
    let mut compressed = Vec::new();
    std::io::copy(&mut reader, &mut compressed)?;
    drop(reader);

    let mut decoder = Decompressor::new(Default::default())?;
    let mut reader = decoder.reader(compressed.as_slice(), Default::default())?;
    let mut restored = Vec::new();
    std::io::copy(&mut reader, &mut restored)?;
    assert_eq!(restored, input);
    Ok(())
}

When the total input size is unknown, use the default stream configuration for the encoder. Reading a decoder to EOF is necessary to observe final validation errors. A raw decoder reader can read past a member boundary; recover its source and buffered suffix with into_parts when another protocol message follows.

Raw compression and decompression through Write

An encoder writer accepts plain bytes; a decoder writer accepts compressed bytes. Each owns its sink and borrows its codec owner. Finalize both writers.

use mbrotli::{Compressor, Decompressor, EncoderConfig, Quality};
use std::io::Write;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let input = b"push input into a writer\n".repeat(100);
    let mut encoder = Compressor::new(
        EncoderConfig::default().with_quality(Quality::Q5),
    )?;
    let mut writer = encoder.writer(Vec::new(), Default::default())?;
    for chunk in input.chunks(13) {
        writer.write_all(chunk)?;
    }
    let compressed = writer.finish().map_err(mbrotli::io::FinishError::into_error)?;

    let mut decoder = Decompressor::new(Default::default())?;
    let mut writer = decoder.writer(Vec::new(), Default::default())?;
    for chunk in compressed.chunks(3) {
        writer.write_all(chunk)?;
    }
    let restored = writer.finish().map_err(mbrotli::io::FinishError::into_error)?;
    assert_eq!(restored, input);
    Ok(())
}

A decoder writer’s finish checks that input ends at a valid stream boundary; flush only drains output and flushes the sink. Encoder flush also creates an intermediate decoding boundary and can change compressed size. Dropping a writer does not finalize or flush it.

Parallel compression through Read and Write

Both constructors return an adapter and a task queue. Run that queue on independent workers while using the adapter; reads, writes, and finish can block waiting for tasks. A queue with no running executor cannot make progress.

This reader example compresses across scoped threads, then uses an ordinary decoder reader to restore the assembled raw stream:

use mbrotli::compressor::parallel::{ParallelCompressor, ParallelConfig, TaskCount};
use mbrotli::{Decompressor, EncoderConfig, Quality};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let input = b"parallel reader with caller-owned workers\n".repeat(220_000);
    let mut encoder = ParallelCompressor::new(
        EncoderConfig::default().with_quality(Quality::Q5),
        ParallelConfig::default(),
    )?;
    let mut compressed = Vec::new();
    std::thread::scope(|scope| -> Result<(), Box<dyn std::error::Error>> {
        let (mut reader, queue) = encoder.reader(input.as_slice(), TaskCount::try_from(4)?)?;
        for _ in 0..4 {
            let worker_queue = queue.clone();
            scope.spawn(move || worker_queue.into_iter().for_each(|task| task.run()));
        }
        drop(queue);
        std::io::copy(&mut reader, &mut compressed)?;
        Ok(())
    })?;

    let mut decoder = Decompressor::new(Default::default())?;
    let mut reader = decoder.reader(compressed.as_slice(), Default::default())?;
    let mut restored = Vec::new();
    std::io::copy(&mut reader, &mut restored)?;
    assert_eq!(restored, input);
    Ok(())
}

For the writer direction, the complete parallel writer recipe copies a source into the returned writer, then finishes it while workers keep running. The task window bounds outstanding segments; the parallel writer’s flush ends the current segment early. Decode its output with either raw adapter shown above. See parallel output and backpressure.

Framed compression through readers and resource writers

framed_reader encodes a complete borrowed FramedInput into a Read stream. It does not accept resources that arrive later. Use framed_writer when input arrives gradually: start a resource, write its payload, finish it, release its borrow, then start another resource. Finish the enclosing container last.

The framed writer recipe demonstrates compressed and uncompressed resource writers and metadata. Here is the reader direction, paired with sequential event decoding:

use mbrotli::framing::{
    FramedCompressor, FramedDecompressor, FramedEvent,
    FramedInput, FramedItem, FramedResource,
};
use std::io::BufReader;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let input = b"a resource exposed as an encoded reader";
    let items = [FramedItem::Resource(FramedResource::from(input.as_slice()))];
    let mut encoder = FramedCompressor::new(Default::default())?;
    let mut encoded = encoder.framed_reader(
        FramedInput::from(items.as_slice()), Default::default(),
    )?;
    let mut container = Vec::new();
    std::io::copy(&mut encoded, &mut container)?;
    drop(encoded);

    let mut decoder = FramedDecompressor::new(Default::default())?;
    let source = BufReader::new(container.as_slice());
    let mut reader = decoder.framed_reader(source, Default::default())?;
    let mut restored = Vec::new();
    let mut resources = 0;
    while let Some(event) = reader.next_event()? {
        match event {
            FramedEvent::ResourceStart(_) => resources += 1,
            FramedEvent::ResourceData(data) => restored.extend_from_slice(data.bytes),
            _ => {}
        }
    }
    assert!(reader.is_finished());
    assert_eq!(resources, 1);
    assert_eq!(restored, input);
    Ok(())
}

Framed decompression into a Write sink

FramedReader lends events over a BufRead source. Wrap an ordinary Read in BufReader. For each ResourceData event, send data.bytes to your sink with write_all; use ResourceStart to select the destination for that resource. Continue until next_event returns None, after complete validation.

use mbrotli::framing::{
    FramedCompressor, FramedDecompressor, FramedEvent,
    FramedInput, FramedItem, FramedResource,
};
use std::io::{BufReader, Write};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let items = [
        FramedItem::Resource(FramedResource::from(b"first".as_slice())),
        FramedItem::Resource(FramedResource::from(b"second".as_slice())),
    ];
    let mut encoder = FramedCompressor::new(Default::default())?;
    let container = encoder.compress(FramedInput::from(items.as_slice()))?;
    let mut decoder = FramedDecompressor::new(Default::default())?;
    let mut reader = decoder.framed_reader(
        BufReader::new(container.as_slice()), Default::default(),
    )?;
    let mut sinks: Vec<Vec<u8>> = Vec::new();
    while let Some(event) = reader.next_event()? {
        match event {
            FramedEvent::ResourceStart(_) => sinks.push(Vec::new()),
            FramedEvent::ResourceData(data) => {
                let sink = sinks.last_mut().ok_or("payload without a resource")?;
                sink.write_all(data.bytes)?;
            }
            _ => {}
        }
    }
    assert!(reader.is_finished());
    assert_eq!(sinks, vec![b"first".to_vec(), b"second".to_vec()]);
    Ok(())
}

This recipe uses in-memory sinks; a resource router can instead choose files or other writers. If a sink fails after an event was read, retain its unwritten suffix before advancing to the next event. FramedReader::partial_output exposes payload produced on a failing reader call. Keep protocol bytes after the container by recovering the buffered source with into_inner.

For Read + Seek, use indexed resource reads: framed_seek_reader opens the directory and resource(index) returns a ResourceReader implementing Read, suitable for std::io::copy. For push-driven compressed input, use the native framed decoder and route the same resource events to sinks.

Completion, retries, and ownership

Short sink writes and errors must not cause accepted input to be replayed. The writer adapters retain pending output, and a later call may report an error after an earlier call already accepted input. WouldBlock is not EOF. If you need explicit readiness handling, use native sessions and drive them when your runtime says buffers are ready. See streaming completion and framed retry mechanics.

Sans I/O compression

Use a session when your application owns the input/output buffers and decides when more bytes are available. Sessions perform no I/O. This works in a blocking loop, an async task, or a custom event loop without an I/O adapter.

For transport integration, see Read / Write I/O. For the inverse operation, see Sans I/O decompression.

Drive a raw encoder

Supply chunks with Operation::Process. After the last chunk, call Finish until EncoderStatus::Finished. An empty input passed with Process is not EOF. The deliberately small output buffer below forces repeated output drains.

use mbrotli::{
    Compressor, Decompressor, EncoderConfig, EncoderStatus, InputSize, Operation, Quality,
};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let input = b"incremental encoding with tiny buffers\n".repeat(100);
    let config = EncoderConfig::default().with_quality(Quality::Q5);
    let mut encoder = Compressor::new(config)?;
    let mut compressed = Vec::new();
    let mut output = [0; 11];
    {
        let mut session = encoder.start(InputSize::Exact(input.len() as u64).into())?;
        for chunk in input.chunks(7) {
            let mut remaining = chunk;
            loop {
                let progress = session.process(remaining, &mut output, Operation::Process)?;
                remaining = &remaining[progress.consumed..];
                compressed.extend_from_slice(&output[..progress.produced]);
                if progress.status == EncoderStatus::NeedsInput {
                    assert!(remaining.is_empty());
                    break;
                }
            }
        }
        loop {
            let progress = session.process(&[], &mut output, Operation::Finish)?;
            compressed.extend_from_slice(&output[..progress.produced]);
            if progress.status == EncoderStatus::Finished {
                break;
            }
        }
    }
    // Exact input size, offset zero, and no flushes preserve one-shot bytes.
    assert_eq!(compressed, encoder.compress(&input)?);
    let mut decoder = Decompressor::new(Default::default())?;
    assert_eq!(decoder.decompress(&compressed)?, input);
    Ok(())
}

Always advance input by consumed and publish only output[..produced] before handling status. NeedsOutput requires output space and the unconsumed input suffix; reaching the end of the current input slice alone does not finish the stream.

Flush and finish are different

Operation::Flush makes accepted bytes decodable without ending the stream. Drain it to NeedsInput before changing operation or supplying new input. Flush boundaries can change output size and bytes. Finish ends the stream; while retrying it, keep the same operation and exact unconsumed input suffix.

Use InputSize::Exact when the total input size is known. Otherwise use the default unknown size; the encoder infers its size hint when it first encodes. See stream scheduling and identity.

Drive parallel input

ParallelCompressor::start(window) returns (session, queue). Keep workers running the queue while you feed input and drain output. The session’s process does not block: ParallelEncoderStatus::Pending means progress depends on tasks. Call session.wait() with independently runnable workers, or execute queued tasks yourself before waiting on a single thread.

The complete Sans I/O parallel example handles all statuses and source chunks. Its window bounds queued, running, and not-yet-delivered segments. Without flushes, output matches a batch over the same input and segment configuration. See parallel session mechanics.

Drive a framed encoder

Enable experimental. Container process takes an output buffer and a FramedEncodeOperation; resource process takes payload, output, and an ordinary Operation. Finish the resource before finishing the container.

use mbrotli::framing::{
    FramedCompressor, FramedDecompressor, FramedEncodeConfig,
    FramedEncodeOperation, FramedEncoderStatus, FramingConfig,
};
use mbrotli::{EncoderConfig, Operation, Quality};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let input = b"framed incremental payload\n".repeat(20);
    let config = FramedEncodeConfig::default()
        .with_encoder_config(EncoderConfig::default().with_quality(Quality::Q5))
        .with_framing_config(FramingConfig { chunk_bytes: 32, ..Default::default() });
    let mut encoder = FramedCompressor::new(config)?;
    let mut session = encoder.start(Default::default())?;
    let mut buffer = [0; 13];
    let mut container = Vec::new();
    // Drain the main header before accepting a resource command.
    loop {
        let progress = session.process(&mut buffer, FramedEncodeOperation::Process)?;
        container.extend_from_slice(&buffer[..progress.produced]);
        if progress.status == FramedEncoderStatus::NeedsInput {
            break;
        }
    }
    {
        let mut resource = session.resource(Default::default(), Default::default())?;
        let mut chunks = input.chunks(9).peekable();
        while let Some(chunk) = chunks.next() {
            let operation = if chunks.peek().is_none() {
                Operation::Finish
            } else {
                Operation::Process
            };
            let mut remaining = chunk;
            loop {
                let progress = resource.process(remaining, &mut buffer, operation)?;
                remaining = &remaining[progress.consumed..];
                container.extend_from_slice(&buffer[..progress.produced]);
                if progress.status == FramedEncoderStatus::Finished
                    || progress.status == FramedEncoderStatus::NeedsInput
                {
                    assert!(remaining.is_empty());
                    break;
                }
            }
        }
        assert!(resource.is_finished());
    }
    loop {
        let progress = session.process(&mut buffer, FramedEncodeOperation::Finish)?;
        container.extend_from_slice(&buffer[..progress.produced]);
        if progress.status == FramedEncoderStatus::Finished {
            break;
        }
    }
    let mut decoder = FramedDecompressor::new(Default::default())?;
    assert_eq!(decoder.decompress(&container)?.resources[0].data, input);
    Ok(())
}

The example marks the last nonempty chunk with Finish; for an empty resource, drive resource.process(&[], output, Operation::Finish) to Finished too. Metadata and new resource commands require previous container output to be drained; otherwise they return OutputPending without committing the command. See resource lifecycles and metadata.

Ownership and cancellation

Borrowed sessions exclusively borrow their codec owner. Dropping an unfinished session cancels it; dropping an unfinished framed resource abandons its container. Forgetting a session requires owner recovery. No drop performs transport I/O. Owned session variants move the codec into the session when a lifetime-free holder fits your application better. See owned sessions.

Sans I/O decompression

Feed compressed input and supply writable output space as it becomes available. Sessions own decoding state and retain no caller input/output slices between calls. DecodeOperation::Process allows more input; Finish declares the final input boundary and enables truncation checks.

There is no separate parallel decoder. Parallel compression assembles a standard raw stream, decoded through the ordinary decoder APIs. For transport adapters, see Read / Write I/O.

Decode a raw stream in chunks

This example supplies three compressed bytes at a time, uses a tiny output buffer, and declares Finish only for the last input chunk.

use mbrotli::{
    Compressor, DecodeOperation, DecoderStatus, Decompressor, EncoderConfig, Quality,
};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let input = b"incremental decoding preserves every byte\n".repeat(100);
    let mut encoder = Compressor::new(
        EncoderConfig::default().with_quality(Quality::Q5),
    )?;
    let compressed = encoder.compress(&input)?;
    let mut decoder = Decompressor::new(Default::default())?;
    let mut session = decoder.start(Default::default())?;
    let mut chunks = compressed.chunks(3).peekable();
    let mut output = [0; 11];
    let mut restored = Vec::new();
    let mut finished = false;
    while let Some(chunk) = chunks.next() {
        let operation = if chunks.peek().is_none() {
            DecodeOperation::Finish
        } else {
            DecodeOperation::Process
        };
        let mut remaining = chunk;
        loop {
            let progress = session.process(remaining, &mut output, operation)?;
            remaining = &remaining[progress.consumed..];
            restored.extend_from_slice(&output[..progress.produced]);
            match progress.status {
                DecoderStatus::NeedsInput => {
                    assert!(remaining.is_empty());
                    break;
                }
                DecoderStatus::NeedsOutput => {}
                DecoderStatus::Finished => {
                    assert!(remaining.is_empty());
                    finished = true;
                    break;
                }
            }
        }
        if finished {
            break;
        }
    }
    assert!(finished);
    assert_eq!(restored, input);
    Ok(())
}

In an application where EOF is learned from a later read, offer chunks with Process and then call process(&[], output, Finish) until Finished. After the first Finish, continue with Finish and exactly the remaining input suffix. Do not add new bytes or switch back to Process.

NeedsOutput can occur after every input byte has been consumed: deliver the output and call again with an empty input slice and fresh output space. For protocols with bytes after the Brotli member, preserve unconsumed input when Finished arrives. The example asserts an empty suffix because its input contains exactly one complete member.

Decode a framing container as events

With experimental, a framed session reports resource boundaries, metadata, payload fragments, directory entries, and a validated footer. Handle events before mutating the session again: events can borrow the session and output.

use mbrotli::framing::{
    FramedCompressor, FramedDecompressor, FramedDecoderStatus, FramedEvent,
    FramedInput, FramedItem, FramedResource,
};
use mbrotli::DecodeOperation;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let input = b"resource decoded one fragment at a time";
    let items = [FramedItem::Resource(FramedResource::from(input.as_slice()))];
    let mut encoder = FramedCompressor::new(Default::default())?;
    let container = encoder.compress(FramedInput::from(items.as_slice()))?;
    let mut decoder = FramedDecompressor::new(Default::default())?;
    let mut session = decoder.start(Default::default())?;
    let mut chunks = container.chunks(3).peekable();
    let mut buffer = [0; 5];
    let mut restored = Vec::new();
    let mut resources = 0;
    let mut finished = false;
    while let Some(chunk) = chunks.next() {
        let operation = if chunks.peek().is_none() {
            DecodeOperation::Finish
        } else {
            DecodeOperation::Process
        };
        let mut remaining = chunk;
        loop {
            let progress = session.process(remaining, &mut buffer, operation)?;
            remaining = &remaining[progress.consumed..];
            match progress.status {
                FramedDecoderStatus::Event(FramedEvent::ResourceStart(_)) => resources += 1,
                FramedDecoderStatus::Event(FramedEvent::ResourceData(data)) => {
                    restored.extend_from_slice(data.bytes);
                }
                FramedDecoderStatus::NeedsInput => {
                    assert!(remaining.is_empty());
                    break;
                }
                FramedDecoderStatus::Finished => {
                    assert!(remaining.is_empty());
                    finished = true;
                    break;
                }
                _ => {}
            }
        }
        if finished {
            break;
        }
    }
    assert!(finished);
    assert_eq!(resources, 1);
    assert_eq!(restored, input);
    Ok(())
}

ResourceDataEnd ends one resource’s payload; it does not validate the rest of the container. Continue through Finished to validate remaining structure. The recipe has one resource; for multiple resources, route ResourceData to the destination selected by ResourceStart rather than concatenating payloads. See framed event semantics.

Limits and errors

Set input, output, window, and workspace budgets in DecoderConfig before starting a raw decoder. For framing, use FramedDecodeConfig and its framing limits in addition to raw decoder limits. See resource-limit configuration.

Output delivered before a later error is partial and has not passed complete validation. Failure values carry consumed/produced counts for that failing call; account for them if your transport needs exact progress. Drop a failed session before starting a new operation. Finish reports truncated streams; an empty Process call does not declare EOF.

Parallel compression

mbrotli::compressor::parallel divides a known input into fixed independent segments and assembles them into one Brotli stream. It supports qualities 0–11 with standard windows. Dictionaries, Large Window, and framing are unsupported by this API.

The caller runs the tasks using scoped threads, Rayon, or another executor. The library does not create a thread pool.

Compressing a slice

use mbrotli::compressor::parallel::{
    BatchConfig, ParallelCompressor, ParallelConfig, TaskCount,
};
use mbrotli::{Decompressor, EncoderConfig, Quality};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let input = vec![b'a'; 8 << 20];
    let mut encoder = ParallelCompressor::new(
        EncoderConfig::default().with_quality(Quality::Q5),
        ParallelConfig::default(),
    )?;
    let mut batch = encoder.prepare_slice(
        &input,
        BatchConfig::auto(TaskCount::try_from(4)?),
    )?;
    let tasks = batch.take_tasks()?;
    std::thread::scope(|scope| {
        for task in tasks {
            scope.spawn(move || task.run());
        }
    });
    let mut output = Vec::new();
    batch.finish_into(&mut output)?;
    let mut decoder = Decompressor::new(Default::default())?;
    assert_eq!(decoder.decompress(&output)?, input);
    Ok(())
}

take_tasks transfers each task once. Every taken task must run or be dropped so its completion can be reported. Finalization collects task results, validates artifacts, and assembles them in input order. A blocking wait requires the caller’s executor to remain runnable.

Running tasks with Rayon

Add rayon = "1.12" alongside mbrotli in your dependencies. Create a pool once and reuse it across requests. Task completion order does not affect assembly order or the resulting bytes for fixed segment settings.

use mbrotli::compressor::parallel::{
    BatchConfig, ParallelCompressor, ParallelConfig, TaskCount,
};
use mbrotli::{Decompressor, EncoderConfig, Quality};
use rayon::prelude::*;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let pool = rayon::ThreadPoolBuilder::new().num_threads(4).build()?;
    let mut encoder = ParallelCompressor::new(
        EncoderConfig::default().with_quality(Quality::Q5),
        ParallelConfig::default(),
    )?;
    let input = b"parallel compression with a reusable pool\n".repeat(220_000);
    let mut batch = encoder.prepare_slice(
        &input,
        BatchConfig::auto(TaskCount::try_from(4)?),
    )?;
    let tasks = batch.take_tasks()?;
    pool.install(|| tasks.into_par_iter().for_each(|task| task.run()));

    let mut compressed = Vec::new();
    batch.finish_into(&mut compressed)?;
    let mut decoder = Decompressor::new(Default::default())?;
    assert_eq!(decoder.decompress(&compressed)?, input);
    Ok(())
}

For many unrelated small inputs, another option is one ordinary Compressor per worker. That preserves serial compression decisions for each input. The batch API above splits one input into a single assembled stream.

Streaming input

When input arrives in chunks, start(window) returns a session and a task queue. Each full segment the session accepts becomes a task on that queue; clone the queue for each executor and run for task in queue { task.run() }. The session delivers finished parts in input order while later segments are still encoding, and closes the queue when the stream finishes, fails, or is dropped.

use mbrotli::compressor::parallel::{
    ParallelCompressor, ParallelConfig, ParallelEncoderStatus, TaskCount,
};
use mbrotli::{EncoderConfig, Operation, Quality};
use std::io::{Read, Write};

fn compress(
    mut reader: impl Read,
    mut writer: impl Write,
) -> Result<(), Box<dyn std::error::Error>> {
    let mut encoder = ParallelCompressor::new(
        EncoderConfig::default().with_quality(Quality::Q5),
        ParallelConfig::default(),
    )?;
    std::thread::scope(|scope| {
        let (mut session, queue) = encoder.start(TaskCount::try_from(4)?)?;
        for _ in 0..4 {
            let queue = queue.clone();
            scope.spawn(move || queue.into_iter().for_each(|task| task.run()));
        }
        drop(queue);
        let mut chunk = vec![0; 1 << 16];
        let mut output = vec![0; 1 << 16];
        loop {
            let read = reader.read(&mut chunk)?;
            let operation = if read == 0 { Operation::Finish } else { Operation::Process };
            let mut input = &chunk[..read];
            loop {
                let progress = session.process(input, &mut output, operation)?;
                input = &input[progress.consumed..];
                writer.write_all(&output[..progress.produced])?;
                match progress.status {
                    ParallelEncoderStatus::Finished => return Ok(()),
                    ParallelEncoderStatus::Pending => session.wait()?,
                    ParallelEncoderStatus::NeedsInput if input.is_empty() => break,
                    _ => {}
                }
            }
        }
    })
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let input = b"incremental parallel input\n".repeat(350_000);
    let mut compressed = Vec::new();
    compress(input.as_slice(), &mut compressed)?;
    let mut decoder = mbrotli::Decompressor::new(Default::default())?;
    assert_eq!(decoder.decompress(&compressed)?, input);
    Ok(())
}

• process never blocks. Pending means the window is full or a flush or finish waits for queued tasks; call wait, which blocks until one completes.
• window bounds the segments queued, running or awaiting delivery, and so the session’s memory. A full window stops input from being consumed.
• Without a flush, the output is byte-identical to prepare_slice over the same bytes, however the input was chunked. Operation::Flush ends the current segment early, which moves later segment boundaries.
• On a single thread, run queue.try_recv() tasks before wait; nothing else will. Dropping every queue handle fails the stream instead of hanging.
• into_session(window) returns an owned session without a lifetime; into_compressor returns the compressor.

Reader and writer adapters

writer(sink, window) and reader(source, window) wrap the same session in std::io::Write and std::io::Read and return the task queue beside the adapter, so the loop above becomes std::io::copy:

use mbrotli::compressor::parallel::{ParallelCompressor, ParallelConfig, TaskCount};
use mbrotli::io::FinishError;
use mbrotli::{EncoderConfig, Quality};
use std::io::{Read, Write};

fn compress<W: Write>(
    mut reader: impl Read,
    writer: W,
) -> Result<W, Box<dyn std::error::Error>> {
    let mut encoder = ParallelCompressor::new(
        EncoderConfig::default().with_quality(Quality::Q5),
        ParallelConfig::default(),
    )?;
    std::thread::scope(|scope| {
        let (mut sink, queue) = encoder.writer(writer, TaskCount::try_from(4)?)?;
        for _ in 0..4 {
            let queue = queue.clone();
            scope.spawn(move || queue.into_iter().for_each(|task| task.run()));
        }
        drop(queue);
        std::io::copy(&mut reader, &mut sink)?;
        Ok(sink.finish().map_err(FinishError::into_error)?)
    })
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let input = b"stream through caller-owned workers\n".repeat(250_000);
    let compressed = compress(input.as_slice(), Vec::new())?;
    let mut decoder = mbrotli::Decompressor::new(Default::default())?;
    assert_eq!(decoder.decompress(&compressed)?, input);
    Ok(())
}

• Unlike process, the adapters block: a write waits while the window is full, a read waits for the next part, and finish waits for every part. Run the queue on threads other than the one using the adapter.
• Output is byte-identical to prepare_slice over the same bytes. The writer’s flush is Operation::Flush: it makes everything written decodable and moves later segment boundaries.
• The writer keeps every compressed byte until the sink takes it, so short writes, WouldBlock and sink errors lose nothing, and finish hands the adapter back inside FinishError for a retry, as EncoderWriter does. reader.into_parts() returns source bytes read ahead of the session.
• Session failures arrive as std::io::Error with the ParallelEncodeError as their source. Dropping an adapter abandons the stream and closes the queue.

Segments and compressed size

Segment size defaults to 4 MiB and accepts 64 KiB–16 MiB. Effective task count is at most the number of segments. For fixed input and segment settings, task grouping and completion order do not change output bytes.

Segments are encoded independently. At qualities 2-9 a segment may copy from the input before it, up to a quarter of a segment within the window, and codes distances as a serial stream does; at qualities 0-1 and 10-11 it starts from nothing and writes every distance explicitly, which costs most on input that repeats one distance, such as tables and logs. The compression ratio can be worse than serial compression, especially for repetition further back than that history. Compare both output size and elapsed time.

Empty input uses serial encoding without tasks. A nonempty input below the default 8 MiB parallel threshold uses a single serial task only when it also fits in one segment.

Sources and staging

FileSource uses positional reads on Unix and Windows. SeekSource accepts Read + Seek + Send, serializes seek/read operations, and lets compression run concurrently. Sources must remain immutable for the batch lifetime; metadata checks cannot detect every in-place mutation.

Owned sources and shared handles use the same generic entry point. For an existing Arc<FileSource>, type inference can require prepare_source::<FileSource, _>(shared_file, config).

BatchConfig::auto(tasks) stages in memory using bounds derived from source length and configured segment size. It caps effective tasks at the segment count and still enforces any configured aggregate memory limit. It does not query available RAM or switch to files.

BatchConfig::memory(tasks, max_bytes) sets an explicit payload-and-descriptor budget. To obtain its exact required preflight allowance, call estimate_source with BatchConfig::auto(tasks), then convert estimate.maximum_staging_memory_bytes()? using usize::try_from. maximum_staged_bytes remains the payload-only bound. Planning also accounts for worker and assembly storage. These estimates are not a process RSS measurement. BatchConfig::directory(tasks, directory) stages output in exclusive temporary files in an existing directory, keeping payload RAM proportional to active workers and segment size. File cleanup is best effort on drop.

Output and cancellation

finish_into appends to a vector and restores its length on failure. finish_to_writer consumes the batch and returns the destination with statistics on success. On failure it preserves destination ownership and the number of accepted bytes; the consumed batch cannot retry assembly. The caller controls flushing, file durability, and publication.

Cancellation is cooperative around source reads and segment encoding. A running codec call or blocking source read can delay it. Dropping a batch cancels work without waiting for detached tasks. Worker retention is configurable and defaults to retaining no workers.

The file example uses directory staging and creates a new output file:

cargo run --release --example parallel -- INPUT OUTPUT

See parallel mechanics for lifecycle, resource accounting, source checks, and error propagation.

Framing containers

Package multiple resources, metadata, and optional dictionary references in an experimental Shared Brotli container. This is useful when an application needs resource boundaries or indexed access in addition to compression.

Enable framing

[dependencies]
mbrotli = { version = "0.5.21", features = ["experimental"] }

The examples use std, compression, and decompression. Experimental APIs may change in a patch release. A framed container needs FramedDecompressor; the raw Decompressor API accepts raw Brotli members.

The library’s parallel compressor emits one raw Brotli stream. It does not emit framing containers. See parallel compression when the goal is compressing one input across cores.

One container, two resources

Use borrowed inputs when all resource bytes are available. The first resource below is Brotli-compressed; the second is explicitly stored without compression.

use mbrotli::framing::{
    FramedCompressor, FramedDecompressor, FramedEncodeConfig, FramedInput,
    FramedItem, FramedResource, ResourceEncoding,
};
use mbrotli::{EncoderConfig, Quality};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let text = b"a document with repeated content\n".repeat(1000);
    let binary = [0x91, 0x02, 0x7f, 0x00];
    let mut stored = FramedResource::from(binary.as_slice());
    stored.encoding = ResourceEncoding::Uncompressed;
    let items = [
        FramedItem::Resource(FramedResource::from(text.as_slice())),
        FramedItem::Resource(stored),
    ];

    let config = FramedEncodeConfig::default().with_encoder_config(
        EncoderConfig::default().with_quality(Quality::Q5),
    );
    let mut encoder = FramedCompressor::new(config)?;
    let container = encoder.compress(FramedInput::from(items.as_slice()))?;

    let mut decoder = FramedDecompressor::new(Default::default())?;
    let decoded = decoder.decompress(&container)?;
    assert_eq!(decoded.resources.len(), 2);
    assert_eq!(decoded.resources[0].data, text);
    assert_eq!(decoded.resources[1].data, binary);
    Ok(())
}

compress_into appends a container to a reusable Vec; compress_to_slice writes into caller storage. The owner can be reused for later containers. The framed compressor specification describes size contracts, retention, and native incremental output APIs.

Write resources and metadata

Use a writer when resource input arrives gradually. Resource metadata precedes the resource it describes. Finish each resource before starting the next one, then finish the container.

use mbrotli::framing::{
    FramedCompressor, FramedDecompressor, FramedEncodeConfig,
    FramingConfig, MetadataField, MetadataKind,
};
use mbrotli::{EncoderConfig, Quality};
use std::io::Write;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = FramedEncodeConfig::default()
        .with_encoder_config(EncoderConfig::default().with_quality(Quality::Q5))
        .with_framing_config(FramingConfig {
            chunk_bytes: 4096,
            ..Default::default()
        });
    let mut encoder = FramedCompressor::new(config)?;
    let mut writer = encoder.framed_writer(Vec::new(), Default::default())?;
    writer.metadata(MetadataKind::Resource, &[
        MetadataField { code: *b"id", value: b"notes.txt" },
    ])?;
    {
        let mut resource = writer.resource(Default::default(), Default::default())?;
        resource.write_all(b"first part\n")?;
        resource.write_all(b"second part\n")?;
        resource.try_finish()?;
    }
    {
        let mut resource = writer.uncompressed_resource(Default::default())?;
        resource.write_all(&[1, 2, 3, 4])?;
        resource.try_finish()?;
    }
    let container = writer.finish().map_err(|failure| failure.error)?;

    let mut decoder = FramedDecompressor::new(Default::default())?;
    let decoded = decoder.decompress(&container)?;
    assert_eq!(decoded.resources[0].data, b"first part\nsecond part\n");
    assert_eq!(decoded.resources[0].metadata.as_ref().and_then(|m| m.name()),
               Some("notes.txt"));
    assert_eq!(decoded.resources[1].data, [1, 2, 3, 4]);
    Ok(())
}

Neither resource drop nor container drop performs I/O. Dropping an unfinished resource abandons its container. try_finish supports retrying resource finalization; a failed consuming container finish retains the writer in FramingFinishError for recovery through its writer and error fields. The in-memory example above keeps the error and discards the writer. See the retry state machine.

Metadata id is a caller-provided UTF-8 name, not an extraction path or a unique lookup key. Checksums are supplied by the caller; the writer does not compute them and the decoder does not verify them.

Indexed resource reads

For a full-profile container on a Read + Seek source, open the footer and directory, then read a selected resource. You can use a File in place of the in-memory Cursor below.

use mbrotli::framing::{
    FramedCompressor, FramedDecompressor, FramedInput,
    FramedItem, FramedResource, ResourceIndex,
};
use std::io::{Cursor, Read};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let items = [
        FramedItem::Resource(FramedResource::from(b"first".as_slice())),
        FramedItem::Resource(FramedResource::from(b"second".as_slice())),
    ];
    let mut encoder = FramedCompressor::new(Default::default())?;
    let container = encoder.compress(FramedInput::from(items.as_slice()))?;

    let mut decoder = FramedDecompressor::new(Default::default())?;
    let mut reader = decoder.framed_seek_reader(Cursor::new(container))?;
    assert_eq!(reader.resources().len(), 2);
    let mut selected = Vec::new();
    reader.resource(ResourceIndex(1))?.read_to_end(&mut selected)?;
    assert_eq!(selected, b"second");
    Ok(())
}

Resources are identified by zero-based ResourceIndex, independent of metadata names. A resource that references earlier dictionary content can require decoding its dependencies. A selected resource reader implements Read; the enclosing reader uses Seek to locate container content. See indexed decoder mechanics.

Limits and streaming decoding

FramingConfig bounds encoder chunks, metadata, resource/chunk counts, and framing storage. FramedDecodeConfig / FramedDecodeLimits control decoder budgets; raw DecoderConfig limits apply within compressed resources. Choose limits for the workload before decoding untrusted containers.

For arriving input, FramedDecompressor::start exposes incremental events; framed_reader adapts a BufRead source. InputMode::Auto also accepts raw Brotli; the default is FramedOnly. External dictionaries need a caller-supplied resolver. See decoder APIs, limits, and events and dictionaries.

Dictionaries and extended formats

Prefix dictionaries

A PreparedDictionary owns immutable dictionary bytes and search indexes. Prepare it once and borrow it from multiple compressors, including across threads. Prefix compression supports qualities 5–11.

use mbrotli::dictionary::DictionaryBuilder;
use mbrotli::{Compressor, EncoderConfig, Quality};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let dictionary = DictionaryBuilder::new()
        .add_prefix(&b"HTTP/1.1 200 OK\r\nContent-Type: "[..])
        .build()?;
    let mut encoder = Compressor::new(
        EncoderConfig::default().with_quality(Quality::Q5),
    )?;
    let input = b"HTTP/1.1 200 OK\r\nContent-Type: text/plain\r\n";
    let compressed = encoder.compress_with_dictionary(&dictionary, input)?;
    assert!(!compressed.is_empty());
    Ok(())
}

Attachment order is significant. The decoder must receive matching dictionary bytes in the same order; a raw Brotli stream does not embed those external bytes or resolve dictionary identifiers.

Dictionary overloads are available for vector, slice, session, reader, and writer output. Passing a dictionary below quality 5 returns EncodeError::DictionaryUnsupportedForQuality.

DictionaryBuilder::with_limits accepts DictionaryLimits to bound source bytes, prefix bytes, attachment count, and prepared storage. Preparation returns either a complete dictionary or an error. Inspect source_bytes(), attachment_count(), and retained_bytes() for its stored sizes.

Large Window

Use Window::large(bits) in EncoderConfig to select the extended header. Values range from 10 to 62, and compressor construction requires quality 3–11. Window::standard(bits) selects ordinary Brotli with 10–24 bits.

The declared window controls the header. The encoder retains at most 30 bits of history, even with a wider declaration. Consumers must support the extended format. The repository’s C decoder checks original streams through 30 bits; wider declarations have header and payload checks but no independent end-to-end decoder validation here.

Feature flags

The experimental API may change in a patch release.

Serialized and custom static dictionaries

With experimental, SerializedDictionary parses and writes shared dictionary descriptions containing an LZ77 prefix, word lists, transform lists, combinations, and a 64-entry context map. DictionaryBuilder::add_serialized prepares that description for compression at qualities 5–11.

Parsing validates structure and rejects trailing bytes. Serialization emits a canonical representation. Preparation applies limits to the owned description, prefix indexes, transformed words, static entries, and temporary storage. Use the additional serialized, word, transform, combination, and expansion ceilings in DictionaryLimits when processing external descriptions.

Custom search supports transformed words and context combinations. Tests require Rust backend/API identity and independent C decoding. Extended search does not have a blanket byte-identity guarantee with C’s experimental encoder.

See serialized format mechanics and custom dictionary encoding.

Headerless continuations

With experimental, StreamConfig::with_stream_offset accepts nonzero offsets at qualities 2–11. Logical positions, including new input, must fit in 63 bits. A continuation has no stream header and is not independently decodable.

The caller joins it after a compatible stream’s byte-aligned flush boundary. The encoder uses a restart prefix and does not invent prior history from the offset. Use parallel compression for the API that plans and assembles independent parts of one input.

Framing containers

FramedCompressor::framed_writer creates an experimental Shared Brotli container writer over a non-seekable Write sink. It supports compressed and uncompressed resources, dictionary references, metadata, padding, repeated metadata, a central directory, and a footer.

Start a resource with resource, resource_with_dictionary, or uncompressed_resource. Write its input, call the resource’s try_finish, then drop that borrow before starting another resource. Finish the container explicitly. Resource and container finalization retain pending bytes for I/O retries; dropping either performs no I/O. Dropping an unfinished resource abandons the container.

The caller supplies dictionary IDs, matching dictionary references, and optional checksums. The writer does not calculate hashes or fetch dictionaries. FramingConfig bounds chunk input, metadata, framing storage, resources, and chunk count. The single-resource profile has no metadata or directory.

mbrotli::framing::FramedDecompressor reads these containers with decompression,experimental enabled. decompress returns resources and container structure; start exposes incremental events, and framed_reader adapts a BufRead source. The default input mode is FramedOnly; InputMode::Auto also accepts a raw Brotli member. Raw Decompressor entry points do not parse containers.

The framed owner, one-shot encoder and native sessions support alloc builds. The framing writer and encoded reader require std APIs. The decoder’s owned and Sans I/O APIs also work with no_std and alloc; FramedReader requires std APIs. External dictionaries use a caller-supplied resolver, and resource checksums are recorded without verification. Tests check independent wire fixtures, writer/decoder round trips and compressed payload decoding with C; the pinned C library has no container codec.

See framed compressor mechanics and framed decoder APIs, validation and limits.

The experimental writer constructor moved from the raw owner:

use mbrotli::{EncoderConfig, framing::{FramedCompressor, FramedEncodeConfig, FramingConfig}};
let config = FramedEncodeConfig::default()
    .with_encoder_config(EncoderConfig::default())
    .with_framing_config(FramingConfig::default());
let mut encoder = FramedCompressor::new(config)?;
let writer = encoder.framed_writer(Vec::new(), Default::default())?;
Ok::<(), Box<dyn std::error::Error>>(())

The second writer argument is now a per-container FramedEncodeStreamConfig. See runnable API examples for borrowed inputs, native output buffers, metadata and owner reuse.

Compatibility and validation

This page describes the contracts checked by the repository. Tests, coverage, fuzzing and memory tools provide bounded evidence, not formal verification. For commands, use the development guide.

What is claimed

Output compatibility

Serial API identity requires the same encoder configuration, dictionary, declared size, flush boundaries, and offset. For one-shot equivalence, declare the exact input size, keep offset zero, and avoid explicit flushes. Chunk size, destination shape, workspace reuse, and SIMD selection do not change bytes. Unknown size can change match-finder selection: like C’s streaming API, a session of unknown length infers its size hint from the bytes it holds plus the current call’s input when it first encodes, so a body passed in one call compresses as if its length had been declared.

The ordinary encoder differential uses the pinned C encoder’s streaming API with matching settings and block scheduling. C’s native one-shot API can rewrite empty or expanded output, and its fast streaming APIs can emit fragments at caller chunk boundaries. Those schedules are not interchangeable byte oracles.

Validation layers

flowchart LR
    Tests[unit, integration and doc tests] --> Oracles[C differential and round-trip checks]
    Tests --> Identity[API, chunking, reuse and backend identity]
    Oracles --> Fuzz[AFL targets and committed regressions]
    Identity --> Fuzz
    Tests --> Coverage[inspect function coverage]
    Tests --> Memory[Miri and AddressSanitizer]

Differential tests

Internal identity tests

tests/streaming.rs, tests/flush.rs, tests/reuse.rs, tests/simd_backends.rs, tests/track_a_lifecycle.rs, and tests/writer_faults.rs check that chunk boundaries, destination shapes, workspace reuse, backend selection, and misbehaving sinks never change the bytes. tests/compressor_memory.rs and tests/dictionary_memory.rs check the retention and preparation budgets with an accounting allocator.

Feature and fuzz coverage

Run std and alloc-backed configurations separately, with and without experimental. --all-features enables no_std and therefore excludes std-only I/O and parallel APIs; it does not replace a std test run. Feature consumer scripts check both accepted imports and APIs that must be absent.

The isolated AFL package reuses engine-neutral target bodies for fuzzing and committed regression replay. campaign.sh covers encoder boundaries and the C-to-native round trip; decoder-campaign.sh covers decoder boundaries. Both stable and experimental builds are needed. See the AFL guide and target mechanics.

Dated records of completed campaigns, with hosts, durations and execution counts, are kept in fuzz campaign records.

Limits of the evidence

• C byte identity requires equivalent streaming settings. Native C one-shot shortcuts and arbitrary chunk schedules can differ.
• C validates extended windows through 30 bits. Wider declarations use independent header and distance-model tests; they have no equivalent C end-to-end oracle.
• Experimental custom static encoding and framing use parser/decoder checks and fixtures; they have no blanket C-encoder byte-identity guarantee.
• A bug shared with the reference implementation can escape differential tests.
• Fuzz budgets cap payload, decoded output and workspace. Large histories and cumulative counters rely on separate integration and ignored heavy tests.
• Coverage measures executed functions, not all paths or possible inputs. Backend execution tests cover only instruction sets available on their host.
• A saved AFL timeout needs standalone reproduction and resource profiling before classification. A bounded campaign cannot establish absence of bugs.

See decoder verification for wire-format, dictionary, resource-limit and large-history checks.

Benchmark results

Current library comparison — 2026-10-30

Full serial sweeps on the AMD Ryzen 9 7950X Linux VDS compare five encoders (432 cases) and four decoders (384 cases). Both use ordinary release builds, 20 samples, 1 s warmup and 3 s requested measurement per case, one process at a time on logical CPU 1. The reports identify the measured checkout and binaries.

Compression

Across all 96 corpus/quality pairs, mbrotli’s median speed / C is 1.099×; its mean latency is lower in 67/96 cases. Burli supports q0–q5 and the other encoders q0–q11. Each plotted value is a median of eight per-dataset ratios to C. Higher speed and lower output size are better. Equal numeric quality does not imply equal compressed size.

Decompression

Across all 96 corpus/quality pairs, mbrotli’s median speed is 2.588× C and 1.006× Burli. Its mean latency is lower in 80/96 C comparisons and 53/96 Burli comparisons. All decoders restore the same C-produced bytes; quality belongs to their source encoder. SIMD Brotli shares the Rust Brotli decoder project and is omitted. Throughput counts restored bytes.

How to interpret the results

Generic mode, window 22, cold native APIs: construction, allocation, transformation and disposal are timed. Inputs and complete matrices are validated before timing. Empty and tiny inputs carry the same weight as large inputs. Medians describe this corpus, not a production workload distribution; point counts do not imply statistical significance. Confidence bounds and every workload remain in the quality pages. Fixed implementation order and an uncontrolled virtual host can affect timings beyond sampling uncertainty. No build, test, fuzzing or other benchmark ran concurrently with either sweep.

Use benchmarking and profiling for reproduction and page/chart generation. Root API suites separately measure reuse, streaming, slices, parallel tasks and dictionaries; their results are not mixed into these native-API medians. Superseded local reports and intermediate snapshots have been removed from the published result set.

lzbench — 2026-11-08

lzbench master a6fa8aa (2.4.1), gcc 15.2 with -march=native, silesia.tar on one vCPU of the AMD Ryzen 9 7950X VDS: mbrotli 0.5.20 compresses 41% and 54% faster than Google Brotli 1.2.0 at qualities 8 and 11 and 10% faster at 5, within run-to-run noise at 0 and 2, and decompresses 22–31% faster at every quality. Sizes match at 0–8; at 11 mbrotli’s output is 0.031% larger. Command, environment and raw output.

lzbench (independent)

lzbench is a long-running open-source in-memory benchmark: every codec is built from source into one binary with the same compiler and flags and runs on the same data and machine. Its maintainer ran these results, not us: lzbench 2.4 (gcc 15.2), the 211 MB Silesia corpus, one thread of an AMD EPYC 9555P with turbo disabled. Full table.

mbrotli 0.5.2 against Google Brotli 1.2.0; bold marks the faster result. Ratio is the compressed size as a percentage of the input and matches for both.

Summary: the same compressed size as Google Brotli (+0.005% at -11), 14–20% faster compression at -8 and -11, within 9% at lower levels, and decompression 3–10% behind C.

This external historical result covers mbrotli 0.5.2 on its maintainer’s host; it is separate from the current local library comparison above.

Encoder comparison

Benchmark index

Recorded run: enc-2026-10-30-amd (2026-10-30). Raw results · Environment · Run analysis.

All eight datasets contribute equally to each median, including empty and tiny input. For each dataset, speed / C = C mean latency / implementation mean latency; output / C = implementation bytes / C bytes. Medians are taken over those ratios. Qualities are ordered by mbrotli median speed / C, highest first. Burli supports q0–q5 only.

Quality 9

Quality 11

Quality 0

Quality 10

Quality 4

Quality 1

Quality 3

Quality 8

Quality 2

Quality 5

Quality 6

Quality 7

Compression quality 0

Benchmark index · Median overview · Quality 1 →

Recorded run: enc-2026-10-30-amd (2026-10-30). Raw results · Environment · Run analysis.

Median across all datasets

Each of the eight datasets has equal weight, including empty and tiny input. Speed / C = C mean latency / implementation mean latency; output / C = implementation bytes / C bytes. We take the median of these eight per-dataset ratios separately for speed and size. 1× matches C; higher speed and lower output are better. These are medians across datasets, not median sample latencies, and do not imply equal compressed size or statistical significance.

Dataset details

Ordered by mbrotli speed / fastest competing implementation, highest first; all eight datasets are shown. This order uses recorded mean latency, not statistical significance. Bars start at zero.

binary-64k · alice29 · random-1m · random-64k · empty · repeated-1m · tiny-text · text-1m

binary-64k

64 KiB of structured binary bytes: ((i / 16) XOR i) modulo 256. Input: 65,536 bytes.

mbrotli speed / fastest peer (Burli): 1.301×; output: 3,369 / 3,433 bytes.

alice29

Vendored Alice in Wonderland text. Input: 152,089 bytes.

mbrotli speed / fastest peer (Burli): 0.745×; output: 65,795 / 74,802 bytes.

random-1m

1 MiB of deterministic xorshift64 pseudorandom bytes. Input: 1,048,576 bytes.

mbrotli speed / fastest peer (Burli): 0.659×; output: 1,048,581 / 1,048,581 bytes.

random-64k

64 KiB prefix of the deterministic pseudorandom corpus. Input: 65,536 bytes.

mbrotli speed / fastest peer (Burli): 0.511×; output: 65,540 / 65,540 bytes.

empty

Empty input; measures API overhead. Input: 0 bytes.

mbrotli speed / fastest peer (Google C): 0.509×; output: 1 / 1 bytes.

repeated-1m

1 MiB of repeated a bytes. Input: 1,048,576 bytes.

mbrotli speed / fastest peer (Burli): 0.395×; output: 712 / 21 bytes.

tiny-text

44-byte quick-brown-fox sentence. Input: 44 bytes.

mbrotli speed / fastest peer (Burli): 0.390×; output: 48 / 48 bytes.

text-1m

Alice text repeated cyclically to 1 MiB. Input: 1,048,576 bytes.

mbrotli speed / fastest peer (Burli): 0.126×; output: 190,491 / 74,828 bytes.

Compression quality 1

Benchmark index · Median overview · ← Quality 0 · Quality 2 →

Recorded run: enc-2026-10-30-amd (2026-10-30). Raw results · Environment · Run analysis.

Median across all datasets

Each of the eight datasets has equal weight, including empty and tiny input. Speed / C = C mean latency / implementation mean latency; output / C = implementation bytes / C bytes. We take the median of these eight per-dataset ratios separately for speed and size. 1× matches C; higher speed and lower output are better. These are medians across datasets, not median sample latencies, and do not imply equal compressed size or statistical significance.

Dataset details

Ordered by mbrotli speed / fastest competing implementation, highest first; all eight datasets are shown. This order uses recorded mean latency, not statistical significance. Bars start at zero.

repeated-1m · binary-64k · random-1m · random-64k · tiny-text · alice29 · empty · text-1m

repeated-1m

1 MiB of repeated a bytes. Input: 1,048,576 bytes.

mbrotli speed / fastest peer (Burli): 2.087×; output: 190 / 21 bytes.

binary-64k

64 KiB of structured binary bytes: ((i / 16) XOR i) modulo 256. Input: 65,536 bytes.

mbrotli speed / fastest peer (Google C): 1.455×; output: 3,202 / 3,202 bytes.

random-1m

1 MiB of deterministic xorshift64 pseudorandom bytes. Input: 1,048,576 bytes.

mbrotli speed / fastest peer (Google C): 1.236×; output: 1,048,581 / 1,048,581 bytes.

random-64k

64 KiB prefix of the deterministic pseudorandom corpus. Input: 65,536 bytes.

mbrotli speed / fastest peer (Google C): 1.190×; output: 65,540 / 65,540 bytes.

tiny-text

44-byte quick-brown-fox sentence. Input: 44 bytes.

mbrotli speed / fastest peer (Google C): 1.057×; output: 48 / 48 bytes.

alice29

Vendored Alice in Wonderland text. Input: 152,089 bytes.

mbrotli speed / fastest peer (Burli): 0.733×; output: 60,292 / 63,139 bytes.

empty

Empty input; measures API overhead. Input: 0 bytes.

mbrotli speed / fastest peer (Google C): 0.511×; output: 1 / 1 bytes.

text-1m

Alice text repeated cyclically to 1 MiB. Input: 1,048,576 bytes.

mbrotli speed / fastest peer (Burli): 0.333×; output: 138,777 / 63,156 bytes.

Compression quality 2

Benchmark index · Median overview · ← Quality 1 · Quality 3 →

Recorded run: enc-2026-10-30-amd (2026-10-30). Raw results · Environment · Run analysis.

Median across all datasets

Each of the eight datasets has equal weight, including empty and tiny input. Speed / C = C mean latency / implementation mean latency; output / C = implementation bytes / C bytes. We take the median of these eight per-dataset ratios separately for speed and size. 1× matches C; higher speed and lower output are better. These are medians across datasets, not median sample latencies, and do not imply equal compressed size or statistical significance.

Dataset details

Ordered by mbrotli speed / fastest competing implementation, highest first; all eight datasets are shown. This order uses recorded mean latency, not statistical significance. Bars start at zero.

repeated-1m · binary-64k · text-1m · random-64k · random-1m · alice29 · tiny-text · empty

repeated-1m

1 MiB of repeated a bytes. Input: 1,048,576 bytes.

mbrotli speed / fastest peer (Burli): 2.676×; output: 23 / 23 bytes.

binary-64k

64 KiB of structured binary bytes: ((i / 16) XOR i) modulo 256. Input: 65,536 bytes.

mbrotli speed / fastest peer (Burli): 1.208×; output: 2,673 / 2,688 bytes.

text-1m

Alice text repeated cyclically to 1 MiB. Input: 1,048,576 bytes.

mbrotli speed / fastest peer (Burli): 1.103×; output: 57,403 / 58,006 bytes.

random-64k

64 KiB prefix of the deterministic pseudorandom corpus. Input: 65,536 bytes.

mbrotli speed / fastest peer (Google C): 1.032×; output: 65,540 / 65,540 bytes.

random-1m

1 MiB of deterministic xorshift64 pseudorandom bytes. Input: 1,048,576 bytes.

mbrotli speed / fastest peer (Google C): 1.008×; output: 1,048,581 / 1,048,581 bytes.

alice29

Vendored Alice in Wonderland text. Input: 152,089 bytes.

mbrotli speed / fastest peer (Google C): 0.995×; output: 57,383 / 57,383 bytes.

tiny-text

44-byte quick-brown-fox sentence. Input: 44 bytes.

mbrotli speed / fastest peer (Google C): 0.989×; output: 48 / 48 bytes.

empty

Empty input; measures API overhead. Input: 0 bytes.

mbrotli speed / fastest peer (Google C): 0.509×; output: 1 / 1 bytes.

Compression quality 3

Benchmark index · Median overview · ← Quality 2 · Quality 4 →

Recorded run: enc-2026-10-30-amd (2026-10-30). Raw results · Environment · Run analysis.

Median across all datasets

Each of the eight datasets has equal weight, including empty and tiny input. Speed / C = C mean latency / implementation mean latency; output / C = implementation bytes / C bytes. We take the median of these eight per-dataset ratios separately for speed and size. 1× matches C; higher speed and lower output are better. These are medians across datasets, not median sample latencies, and do not imply equal compressed size or statistical significance.

Dataset details

Ordered by mbrotli speed / fastest competing implementation, highest first; all eight datasets are shown. This order uses recorded mean latency, not statistical significance. Bars start at zero.

repeated-1m · text-1m · binary-64k · random-64k · random-1m · tiny-text · alice29 · empty

repeated-1m

1 MiB of repeated a bytes. Input: 1,048,576 bytes.

mbrotli speed / fastest peer (Burli): 4.353×; output: 13 / 13 bytes.

text-1m

Alice text repeated cyclically to 1 MiB. Input: 1,048,576 bytes.

mbrotli speed / fastest peer (Burli): 1.347×; output: 56,879 / 57,517 bytes.

binary-64k

64 KiB of structured binary bytes: ((i / 16) XOR i) modulo 256. Input: 65,536 bytes.

mbrotli speed / fastest peer (Burli): 1.301×; output: 2,687 / 2,760 bytes.

random-64k

64 KiB prefix of the deterministic pseudorandom corpus. Input: 65,536 bytes.

mbrotli speed / fastest peer (Google C): 1.099×; output: 65,540 / 65,540 bytes.

random-1m

1 MiB of deterministic xorshift64 pseudorandom bytes. Input: 1,048,576 bytes.

mbrotli speed / fastest peer (Google C): 1.079×; output: 1,048,581 / 1,048,581 bytes.

tiny-text

44-byte quick-brown-fox sentence. Input: 44 bytes.

mbrotli speed / fastest peer (Google C): 1.009×; output: 46 / 46 bytes.

alice29

Vendored Alice in Wonderland text. Input: 152,089 bytes.

mbrotli speed / fastest peer (Burli): 0.976×; output: 56,863 / 58,702 bytes.

empty

Empty input; measures API overhead. Input: 0 bytes.

mbrotli speed / fastest peer (Google C): 0.516×; output: 1 / 1 bytes.

Compression quality 4

Benchmark index · Median overview · ← Quality 3 · Quality 5 →

Recorded run: enc-2026-10-30-amd (2026-10-30). Raw results · Environment · Run analysis.

Median across all datasets

Each of the eight datasets has equal weight, including empty and tiny input. Speed / C = C mean latency / implementation mean latency; output / C = implementation bytes / C bytes. We take the median of these eight per-dataset ratios separately for speed and size. 1× matches C; higher speed and lower output are better. These are medians across datasets, not median sample latencies, and do not imply equal compressed size or statistical significance.

Dataset details

Ordered by mbrotli speed / fastest competing implementation, highest first; all eight datasets are shown. This order uses recorded mean latency, not statistical significance. Bars start at zero.

repeated-1m · text-1m · random-64k · tiny-text · alice29 · binary-64k · random-1m · empty

repeated-1m

1 MiB of repeated a bytes. Input: 1,048,576 bytes.

mbrotli speed / fastest peer (Burli): 3.002×; output: 13 / 13 bytes.

text-1m

Alice text repeated cyclically to 1 MiB. Input: 1,048,576 bytes.

mbrotli speed / fastest peer (Burli): 1.245×; output: 55,915 / 57,773 bytes.

random-64k

64 KiB prefix of the deterministic pseudorandom corpus. Input: 65,536 bytes.

mbrotli speed / fastest peer (Google C): 1.100×; output: 65,540 / 65,540 bytes.

tiny-text

44-byte quick-brown-fox sentence. Input: 44 bytes.

mbrotli speed / fastest peer (Burli): 1.026×; output: 48 / 48 bytes.

alice29

Vendored Alice in Wonderland text. Input: 152,089 bytes.

mbrotli speed / fastest peer (Burli): 0.971×; output: 55,504 / 57,813 bytes.

binary-64k

64 KiB of structured binary bytes: ((i / 16) XOR i) modulo 256. Input: 65,536 bytes.

mbrotli speed / fastest peer (Burli): 0.863×; output: 2,554 / 2,593 bytes.

random-1m

1 MiB of deterministic xorshift64 pseudorandom bytes. Input: 1,048,576 bytes.

mbrotli speed / fastest peer (Burli): 0.766×; output: 1,048,581 / 1,048,625 bytes.

empty

Empty input; measures API overhead. Input: 0 bytes.

mbrotli speed / fastest peer (Google C): 0.522×; output: 1 / 1 bytes.

Compression quality 5

Benchmark index · Median overview · ← Quality 4 · Quality 6 →

Recorded run: enc-2026-10-30-amd (2026-10-30). Raw results · Environment · Run analysis.

Median across all datasets

Each of the eight datasets has equal weight, including empty and tiny input. Speed / C = C mean latency / implementation mean latency; output / C = implementation bytes / C bytes. We take the median of these eight per-dataset ratios separately for speed and size. 1× matches C; higher speed and lower output are better. These are medians across datasets, not median sample latencies, and do not imply equal compressed size or statistical significance.

Dataset details

Ordered by mbrotli speed / fastest competing implementation, highest first; all eight datasets are shown. This order uses recorded mean latency, not statistical significance. Bars start at zero.

repeated-1m · text-1m · binary-64k · alice29 · tiny-text · random-1m · random-64k · empty

repeated-1m

1 MiB of repeated a bytes. Input: 1,048,576 bytes.

mbrotli speed / fastest peer (Google C): 5.073×; output: 13 / 13 bytes.

text-1m

Alice text repeated cyclically to 1 MiB. Input: 1,048,576 bytes.

mbrotli speed / fastest peer (Google C): 1.167×; output: 51,228 / 51,228 bytes.

binary-64k

64 KiB of structured binary bytes: ((i / 16) XOR i) modulo 256. Input: 65,536 bytes.

mbrotli speed / fastest peer (Google C): 0.975×; output: 1,588 / 1,588 bytes.

alice29

Vendored Alice in Wonderland text. Input: 152,089 bytes.

mbrotli speed / fastest peer (Burli): 0.967×; output: 52,809 / 54,228 bytes.

tiny-text

44-byte quick-brown-fox sentence. Input: 44 bytes.

mbrotli speed / fastest peer (Burli): 0.924×; output: 48 / 48 bytes.

random-1m

1 MiB of deterministic xorshift64 pseudorandom bytes. Input: 1,048,576 bytes.

mbrotli speed / fastest peer (Burli): 0.581×; output: 1,048,581 / 1,048,625 bytes.

random-64k

64 KiB prefix of the deterministic pseudorandom corpus. Input: 65,536 bytes.

mbrotli speed / fastest peer (Burli): 0.567×; output: 65,540 / 65,540 bytes.

empty

Empty input; measures API overhead. Input: 0 bytes.

mbrotli speed / fastest peer (Google C): 0.518×; output: 1 / 1 bytes.

Compression quality 6

Benchmark index · Median overview · ← Quality 5 · Quality 7 →

Recorded run: enc-2026-10-30-amd (2026-10-30). Raw results · Environment · Run analysis.

Median across all datasets

Each of the eight datasets has equal weight, including empty and tiny input. Speed / C = C mean latency / implementation mean latency; output / C = implementation bytes / C bytes. We take the median of these eight per-dataset ratios separately for speed and size. 1× matches C; higher speed and lower output are better. These are medians across datasets, not median sample latencies, and do not imply equal compressed size or statistical significance.

Dataset details

Ordered by mbrotli speed / fastest competing implementation, highest first; all eight datasets are shown. This order uses recorded mean latency, not statistical significance. Bars start at zero.

repeated-1m · tiny-text · text-1m · alice29 · random-1m · binary-64k · empty · random-64k

repeated-1m

1 MiB of repeated a bytes. Input: 1,048,576 bytes.

mbrotli speed / fastest peer (Google C): 4.036×; output: 13 / 13 bytes.

tiny-text

44-byte quick-brown-fox sentence. Input: 44 bytes.

mbrotli speed / fastest peer (Google C): 1.410×; output: 48 / 48 bytes.

text-1m

Alice text repeated cyclically to 1 MiB. Input: 1,048,576 bytes.

mbrotli speed / fastest peer (Google C): 1.166×; output: 50,823 / 50,823 bytes.

alice29

Vendored Alice in Wonderland text. Input: 152,089 bytes.

mbrotli speed / fastest peer (Google C): 1.043×; output: 51,967 / 51,967 bytes.

random-1m

1 MiB of deterministic xorshift64 pseudorandom bytes. Input: 1,048,576 bytes.

mbrotli speed / fastest peer (Google C): 0.972×; output: 1,048,581 / 1,048,581 bytes.

binary-64k

64 KiB of structured binary bytes: ((i / 16) XOR i) modulo 256. Input: 65,536 bytes.

mbrotli speed / fastest peer (Google C): 0.715×; output: 1,588 / 1,588 bytes.

empty

Empty input; measures API overhead. Input: 0 bytes.

mbrotli speed / fastest peer (Google C): 0.518×; output: 1 / 1 bytes.

random-64k

64 KiB prefix of the deterministic pseudorandom corpus. Input: 65,536 bytes.

mbrotli speed / fastest peer (Google C): 0.485×; output: 65,540 / 65,540 bytes.

Compression quality 7

Benchmark index · Median overview · ← Quality 6 · Quality 8 →

Recorded run: enc-2026-10-30-amd (2026-10-30). Raw results · Environment · Run analysis.

Median across all datasets

Each of the eight datasets has equal weight, including empty and tiny input. Speed / C = C mean latency / implementation mean latency; output / C = implementation bytes / C bytes. We take the median of these eight per-dataset ratios separately for speed and size. 1× matches C; higher speed and lower output are better. These are medians across datasets, not median sample latencies, and do not imply equal compressed size or statistical significance.

Dataset details

Ordered by mbrotli speed / fastest competing implementation, highest first; all eight datasets are shown. This order uses recorded mean latency, not statistical significance. Bars start at zero.

repeated-1m · tiny-text · text-1m · random-1m · alice29 · random-64k · binary-64k · empty

repeated-1m

1 MiB of repeated a bytes. Input: 1,048,576 bytes.

mbrotli speed / fastest peer (Google C): 2.958×; output: 13 / 13 bytes.

tiny-text

44-byte quick-brown-fox sentence. Input: 44 bytes.

mbrotli speed / fastest peer (Google C): 1.361×; output: 48 / 48 bytes.

text-1m

Alice text repeated cyclically to 1 MiB. Input: 1,048,576 bytes.

mbrotli speed / fastest peer (Google C): 1.160×; output: 50,580 / 50,580 bytes.

random-1m

1 MiB of deterministic xorshift64 pseudorandom bytes. Input: 1,048,576 bytes.

mbrotli speed / fastest peer (Google C): 1.029×; output: 1,048,581 / 1,048,581 bytes.

alice29

Vendored Alice in Wonderland text. Input: 152,089 bytes.

mbrotli speed / fastest peer (Google C): 0.979×; output: 51,451 / 51,451 bytes.

random-64k

64 KiB prefix of the deterministic pseudorandom corpus. Input: 65,536 bytes.

mbrotli speed / fastest peer (Google C): 0.750×; output: 65,540 / 65,540 bytes.

binary-64k

64 KiB of structured binary bytes: ((i / 16) XOR i) modulo 256. Input: 65,536 bytes.

mbrotli speed / fastest peer (Google C): 0.699×; output: 1,588 / 1,588 bytes.

empty

Empty input; measures API overhead. Input: 0 bytes.

mbrotli speed / fastest peer (Google C): 0.508×; output: 1 / 1 bytes.

Compression quality 8

Benchmark index · Median overview · ← Quality 7 · Quality 9 →

Recorded run: enc-2026-10-30-amd (2026-10-30). Raw results · Environment · Run analysis.

Median across all datasets

Each of the eight datasets has equal weight, including empty and tiny input. Speed / C = C mean latency / implementation mean latency; output / C = implementation bytes / C bytes. We take the median of these eight per-dataset ratios separately for speed and size. 1× matches C; higher speed and lower output are better. These are medians across datasets, not median sample latencies, and do not imply equal compressed size or statistical significance.

Dataset details

Ordered by mbrotli speed / fastest competing implementation, highest first; all eight datasets are shown. This order uses recorded mean latency, not statistical significance. Bars start at zero.

repeated-1m · tiny-text · random-64k · text-1m · random-1m · alice29 · binary-64k · empty

repeated-1m

1 MiB of repeated a bytes. Input: 1,048,576 bytes.

mbrotli speed / fastest peer (Google C): 6.266×; output: 13 / 13 bytes.

tiny-text

44-byte quick-brown-fox sentence. Input: 44 bytes.

mbrotli speed / fastest peer (Google C): 1.361×; output: 48 / 48 bytes.

random-64k

64 KiB prefix of the deterministic pseudorandom corpus. Input: 65,536 bytes.

mbrotli speed / fastest peer (Google C): 1.206×; output: 65,540 / 65,540 bytes.

text-1m

Alice text repeated cyclically to 1 MiB. Input: 1,048,576 bytes.

mbrotli speed / fastest peer (Google C): 1.058×; output: 50,473 / 50,473 bytes.

random-1m

1 MiB of deterministic xorshift64 pseudorandom bytes. Input: 1,048,576 bytes.

mbrotli speed / fastest peer (Google C): 0.985×; output: 1,048,581 / 1,048,581 bytes.

alice29

Vendored Alice in Wonderland text. Input: 152,089 bytes.

mbrotli speed / fastest peer (Google C): 0.958×; output: 51,187 / 51,187 bytes.

binary-64k

64 KiB of structured binary bytes: ((i / 16) XOR i) modulo 256. Input: 65,536 bytes.

mbrotli speed / fastest peer (Google C): 0.734×; output: 1,588 / 1,588 bytes.

empty

Empty input; measures API overhead. Input: 0 bytes.

mbrotli speed / fastest peer (Google C): 0.518×; output: 1 / 1 bytes.

Compression quality 9

Benchmark index · Median overview · ← Quality 8 · Quality 10 →

Recorded run: enc-2026-10-30-amd (2026-10-30). Raw results · Environment · Run analysis.

Median across all datasets

Each of the eight datasets has equal weight, including empty and tiny input. Speed / C = C mean latency / implementation mean latency; output / C = implementation bytes / C bytes. We take the median of these eight per-dataset ratios separately for speed and size. 1× matches C; higher speed and lower output are better. These are medians across datasets, not median sample latencies, and do not imply equal compressed size or statistical significance.

Dataset details

Ordered by mbrotli speed / fastest competing implementation, highest first; all eight datasets are shown. This order uses recorded mean latency, not statistical significance. Bars start at zero.

tiny-text · repeated-1m · binary-64k · random-64k · alice29 · text-1m · random-1m · empty

tiny-text

44-byte quick-brown-fox sentence. Input: 44 bytes.

mbrotli speed / fastest peer (SIMD Brotli): 6.522×; output: 48 / 48 bytes.

repeated-1m

1 MiB of repeated a bytes. Input: 1,048,576 bytes.

mbrotli speed / fastest peer (Google C): 5.634×; output: 13 / 13 bytes.

binary-64k

64 KiB of structured binary bytes: ((i / 16) XOR i) modulo 256. Input: 65,536 bytes.

mbrotli speed / fastest peer (SIMD Brotli): 2.028×; output: 1,349 / 1,349 bytes.

random-64k

64 KiB prefix of the deterministic pseudorandom corpus. Input: 65,536 bytes.

mbrotli speed / fastest peer (SIMD Brotli): 1.853×; output: 65,540 / 65,540 bytes.

alice29

Vendored Alice in Wonderland text. Input: 152,089 bytes.

mbrotli speed / fastest peer (SIMD Brotli): 1.201×; output: 51,054 / 51,056 bytes.

text-1m

Alice text repeated cyclically to 1 MiB. Input: 1,048,576 bytes.

mbrotli speed / fastest peer (Google C): 1.001×; output: 50,608 / 50,608 bytes.

random-1m

1 MiB of deterministic xorshift64 pseudorandom bytes. Input: 1,048,576 bytes.

mbrotli speed / fastest peer (Google C): 0.992×; output: 1,048,581 / 1,048,581 bytes.

empty

Empty input; measures API overhead. Input: 0 bytes.

mbrotli speed / fastest peer (Google C): 0.516×; output: 1 / 1 bytes.

Compression quality 10

Benchmark index · Median overview · ← Quality 9 · Quality 11 →

Recorded run: enc-2026-10-30-amd (2026-10-30). Raw results · Environment · Run analysis.

Median across all datasets

Each of the eight datasets has equal weight, including empty and tiny input. Speed / C = C mean latency / implementation mean latency; output / C = implementation bytes / C bytes. We take the median of these eight per-dataset ratios separately for speed and size. 1× matches C; higher speed and lower output are better. These are medians across datasets, not median sample latencies, and do not imply equal compressed size or statistical significance.

Dataset details

Ordered by mbrotli speed / fastest competing implementation, highest first; all eight datasets are shown. This order uses recorded mean latency, not statistical significance. Bars start at zero.

repeated-1m · random-64k · text-1m · alice29 · random-1m · binary-64k · tiny-text · empty

repeated-1m

1 MiB of repeated a bytes. Input: 1,048,576 bytes.

mbrotli speed / fastest peer (Google C): 1.805×; output: 14 / 14 bytes.