Recursive AI

Brotli decoder in C#

OneArchive is a free, open-source archive library for .NET from Recursive AI. MIT or Apache-2.0, no native dependencies.

Decode a Brotli stream. input.br is in the zip.

Terminal
dotnet add package RecursiveAI.OneCompress

Requires .NET 10 (net10.0); .NET 9 and earlier aren’t supported.

C#
using RecursiveAI.OneCompress.Brotli;
using var input = File.OpenRead("input.br");
using var decoder = new BrotliStream(input);
using var text = new StreamReader(decoder);
Console.Write(text.ReadToEnd());
Text
Hello from Brotli!

Unzip the example, then dotnet run.

The full program

The sample contains only Hello from Brotli! followed by a newline. Its compressed bytes, in hexadecimal, are:

Text
0B098048656C6C6F2066726F6D2042726F746C69210A03

The program caps decoded output at 1,024 bytes, checks its content, and writes message.txt only after decoding succeeds.

C#
using RecursiveAI.OneCompress.Brotli;
using var input = File.OpenRead("input.br");
using var decoder = new BrotliStream(input,
    new BrotliDecompressionOptions { MaxOutputSize = 1024 });
using var decoded = new MemoryStream();
decoder.CopyTo(decoded);
byte[] bytes = decoded.ToArray();
if (!bytes.AsSpan().SequenceEqual("Hello from Brotli!\n"u8))
    throw new InvalidDataException("Unexpected decoded content.");
File.WriteAllBytes("message.txt", bytes);
Console.WriteLine($"Decoded {bytes.Length} bytes to message.txt");
Console.Write(System.Text.Encoding.UTF8.GetString(bytes));
Text
Decoded 19 bytes to message.txt
Hello from Brotli!

Incomplete input raises CompressionFormatException with IsTruncated set; excessive output raises CompressionLimitException, before this program writes the destination file.

Variations

Decode a byte array

For the same included input, the one-call API returns the decoded bytes:

C#
using RecursiveAI.OneCompress.Brotli;
byte[] source = File.ReadAllBytes("input.br");
byte[] decoded = Brotli.Decompress(source,
    new BrotliDecompressionOptions { MaxOutputSize = 1024 });
Console.Write(System.Text.Encoding.UTF8.GetString(decoded));
Text
Hello from Brotli!

Catch truncated input and excessive output

This uses the included file, first removing its last byte, then imposing an eight-byte output cap:

C#
using RecursiveAI.OneCompress;
using RecursiveAI.OneCompress.Brotli;
byte[] source = File.ReadAllBytes("input.br");
try { Brotli.Decompress(source.AsSpan(0, source.Length - 1)); }
catch (CompressionFormatException error)
{
    Console.WriteLine($"Truncated: {error.IsTruncated}");
}
try
{
    Brotli.Decompress(source,
        new BrotliDecompressionOptions { MaxOutputSize = 8 });
}
catch (CompressionLimitException)
{
    Console.WriteLine("Output limit exceeded");
}
Text
Truncated: True
Output limit exceeded

The short answer

Use BrotliStream from RecursiveAI.OneCompress.Brotli to decode a readable stream. Use Brotli.Decompress when you already have the complete compressed bytes in memory. Both decode Brotli as defined by RFC 7932. The package is RecursiveAI.OneCompress; you do not need the archive-container package for this task.

The snippet at the top treats the decoded content as text. For an image, executable, or other binary payload, do not use StreamReader: copy decoded bytes instead. The full program demonstrates that byte-preserving path with a MemoryStream. It verifies the complete result before opening the destination, so a decoding error does not leave a partial destination file. Buffering the result is appropriate for this small, explicitly bounded example.

How do I decompress a Brotli file?

Open the compressed file as a readable stream, wrap it in the package’s BrotliStream, and read until the decoded stream ends. For larger files, you can copy directly to a destination stream instead of accumulating a byte array; account for partial output if decoding later fails. A stream wrapper does not mean the entire input must arrive in one read: the decoder retains unfinished header bytes and resumes when more input arrives.

Set BrotliDecompressionOptions.MaxOutputSize for the largest decoded payload your application accepts. The full program’s 1,024-byte cap is an example policy, not a Brotli format limit. MaxWindowSize separately bounds the history window declared in the stream. The decoder documentation describes both checks: output is checked against each meta-block’s declared length before that block is produced.

The decoder reads exactly one Brotli stream. Trailing bytes are rejected by default, and an early end is reported as truncation rather than successful completion. Keep those defaults when one file is supposed to contain exactly one payload. The failure-handling variation shows the exception types separately so you can distinguish incomplete input from a configured resource limit.

Where can I download a Brotli decoder for C#?

Install RecursiveAI.OneCompress from the NuGet link above. The downloadable example includes a project pinned to version 1.2.0, the program, and the tiny .br fixture; unzipping it and running dotnet run needs no sample download or encoder tool.

The package exposes three decoding shapes: a one-call byte-array API, a span-based BrotliDecoder with OperationStatus, and a read-only decoding stream. Choose the one-call API for a complete bounded buffer, the stream for normal file I/O, or the span API when your application controls input and output chunks. These type names also exist in System.IO.Compression, but those are different types. If you import both namespaces, qualify or alias the names rather than accidentally selecting another implementation.

What is Brotli compression?

Brotli is a lossless compressed-data format specified in RFC 7932. A decoded result is bytes, not necessarily text and not necessarily an archive containing named files. This example knows its original bytes are UTF-8 text; that knowledge comes from the sample, not from Brotli.

Brotli has no magic number. In OneArchive’s single-stream archive facade, .br recognition therefore depends on the file name. The codec APIs on this page do not detect formats: calling BrotliStream or Brotli.Decompress explicitly selects Brotli, regardless of the file extension. Renaming another format to .br does not convert it. Large-window Brotli is outside RFC 7932 and is rejected by this decoder.

All onearchive recipes