OneArchive is a free, open-source (MIT or Apache-2.0) archive and compression library for .NET from Recursive AI. Its OneCompress package reads LZ4 frames. NuGet · GitHub · Docs.
Quick start
For a plain file round trip, see compress and decompress LZ4 in C#.
From an empty directory with the .NET 10 SDK:
dotnet new console -f net10.0 dotnet add package \ RecursiveAI.OneCompress \ --version 1.2.0
This input puts an empty skippable member between two standard frames for hi. The skippable member adds no output.
Replace Program.cs with the following and run dotnet run.
using System.Text; using RecursiveAI.OneCompress.Lz4; byte[] frame = Lz4.Compress("hi"u8.ToArray()); // Skippable magic, then a 4-byte length of 0. byte[] skip = [0x50, 0x2A, 0x4D, 0x18, 0, 0, 0, 0]; byte[] input = [..frame, ..skip, ..frame]; Console.WriteLine(Encoding.UTF8.GetString(Lz4.Decompress(input)));
hihiIdentify the bytes before choosing a decoder
Look at the first four bytes at a known frame boundary, not the filename extension. A standard LZ4 frame starts with a magic number and settings, then holds compressed or uncompressed data blocks and can include optional checksums. A raw LZ4 block has no frame header; the enclosing format must tell you where it ends and supply a bound on its decoded size. In OneCompress 1.2.0, Lz4 handles frames and Lz4Block handles raw blocks. An unrecognized magic number does not by itself prove the input is a raw block.
Standard frame
04 22 4D 18, followed by a descriptor and length-prefixed blocks. Check the descriptor for the checksum flags, dictionary ID, and whether blocks share history. A zero block-size field marks the end of blocks; a flagged content checksum still follows it.
Legacy frame
02 21 4C 18, followed by length-prefixed compressed blocks. No standard descriptor, dictionaries, or checksums. Look for the next recognized frame magic or end of input at a block boundary.
Skippable frame
50 2A 4D 18 through 5F 2A 4D 18, followed by a length and that many bytes. Produces no decoded payload. Set SkippableFrameHandler if you need its bytes. MaxSkippableFrameSize defaults to 1 MiB.
Concatenated frames
Another frame starts at the boundary after the previous one; no separate magic for the sequence. Decode members in order. Block history does not carry from one member to the next. Bytes after the last valid member must form another frame, not arbitrary padding.
The byte order above is the order on disk. See the LZ4 frame specification for the format and the OneCompress decoder reference for reader behavior.
Why the same payload may need different reader settings
- Checksum failure: the standard header checksum covers the descriptor. Optional block checksums cover the stored block bytes, before decoding; the optional content checksum covers the decoded content. OneCompress checks block and content checksums by default.
VerifyChecksum = falsedoes not disable the header check. - Missing dictionary: the frame can carry an ID, not the dictionary bytes. OneCompress looks up a nonzero ID in
Dictionaries, then falls back toDictionaryif its ID matches or is zero. For a known dictionary-compressed stream without a nonzero ID, supplyDictionaryexplicitly. Only the last 64 KiB of dictionary bytes are used. - Only the first member is decoded: a streaming
Lz4DecoderreturningDoneat a frame boundary does not mean the input is exhausted. Keep track of bytes consumed and pass the remaining bytes to the decoder. A skippable member can reach a boundary with zero output. A legacy frame may end at input EOF without producing a separateDone; see the streaming contract.
A mixed-frame input decoded in one call
Replace the quick-start program with this example. It builds the entire input in memory: a standard frame for one, a skippable member carrying !, a legacy member with a literal-only block for two, and the original standard frame again. The legacy block’s 0x30 token means three literal bytes and no match. The second standard magic marks the end of the legacy member.
using System.Text; using RecursiveAI.OneCompress.Lz4; byte[] standard = Lz4.Compress("one"u8.ToArray()); byte[] skip = [0x53, 0x2A, 0x4D, 0x18, 1, 0, 0, 0, (byte)'!']; byte[] legacy = [0x02, 0x21, 0x4C, 0x18, 4, 0, 0, 0, 0x30, (byte)'t', (byte)'w', (byte)'o']; byte[] input = [..standard, ..skip, ..legacy, ..standard]; Console.WriteLine($"Standard: {Convert.ToHexString(standard.AsSpan(0, 4))}"); Console.WriteLine($"Skippable: {Convert.ToHexString(skip.AsSpan(0, 4))}"); Console.WriteLine($"Legacy: {Convert.ToHexString(legacy.AsSpan(0, 4))}"); Console.WriteLine($"Decoded: {Encoding.UTF8.GetString(Lz4.Decompress(input))}");
Standard: 04224D18 Skippable: 532A4D18 Legacy: 02214C18 Decoded: onetwoone
The output contains both copies of one and the legacy two, but not the skippable byte.