Brotli Compression

This page explains how to compress and decompress data using Brotli.

Code snippets assume using namespace boost::capy; is in effect.

What is Brotli?

Brotli is a modern compression algorithm developed by Google. It offers:

  • Excellent compression ratios, especially for text

  • Good decompression speed

  • Support for shared dictionaries

  • Wide browser support for web content

Brotli typically achieves 20-25% better compression than gzip on text content.

Setup

#include <boost/capy/brotli.hpp>
#include <boost/capy/datastore.hpp>

datastore ctx;

// Install encoder and decoder services
auto& encoder = brotli::install_encode_service(ctx);
auto& decoder = brotli::install_decode_service(ctx);

The services manage internal state and can be reused for multiple operations.

Encoding (Compression)

std::vector<char> input = get_data();
std::vector<char> output;

// Compress with default quality
brotli::encode_result result = encoder.encode(
    input.data(), input.size(),
    output
);

if (result.ec)
    handle_error(result.ec);

// output now contains compressed data

Quality Settings

Brotli quality ranges from 0 (fastest) to 11 (best compression):

Quality Speed Ratio

0-4

Fast

Lower

5-6

Balanced

Good

7-9

Slow

Better

10-11

Very slow

Best

Quality 6 is a good default for most applications.

Decoding (Decompression)

std::vector<char> compressed = get_compressed();
std::vector<char> output;

// Decompress
brotli::decode_result result = decoder.decode(
    compressed.data(), compressed.size(),
    output
);

if (result.ec)
    handle_error(result.ec);

// output now contains original data

Decompression is typically much faster than compression.

Shared Dictionaries

Shared dictionaries improve compression for similar content by providing a common reference:

// Load a pre-computed dictionary
brotli::shared_dictionary dict = load_dictionary();

// Install services with dictionary
auto& encoder = brotli::install_encode_service(ctx, dict);
auto& decoder = brotli::install_decode_service(ctx, dict);

Both encoder and decoder must use the same dictionary.

When to Use Shared Dictionaries

  • Compressing many similar files (e.g., HTML pages from same site)

  • Delta compression between versions

  • Protocol messages with common structure

Dictionaries are most effective when the content is similar to the dictionary content.

Error Handling

brotli::encode_result result = encoder.encode(input, output);

if (result.ec == brotli::error::invalid_input)
{
    // Input data is malformed
}
else if (result.ec)
{
    std::cerr << "Brotli error: " << result.ec.message() << "\n";
}

When to Use Brotli

Use Brotli when:

  • Compression ratio is important

  • Content is text-heavy (HTML, CSS, JS, JSON)

  • Compressing once, decompressing many times

  • Target supports Brotli (modern browsers, HTTP/2)

Avoid Brotli when:

  • Compatibility with older systems is required

  • Compression speed is critical

  • Content is already compressed (images, video)

Summary

Function Purpose

brotli::install_encode_service

Create compression service

brotli::install_decode_service

Create decompression service

encoder.encode

Compress data

decoder.decode

Decompress data

brotli::shared_dictionary

Shared dictionary for improved compression

Next Steps

  • ZLib — DEFLATE/gzip compression

  • Containers — Service container (datastore)

Edit this Page