Something went wrong. Try again.
A sans-I/O reader and writer for RIFF, the container underneath WAV, AVI and WebP.
Something went wrong. Try again.
Files
- Zig 94%
- Nix 6%
README.md
<!--
SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie <jeff@ocjtech.us>
SPDX-License-Identifier: MIT
-->
# zig-riff
A sans-I/O reader and writer for **RIFF**, the container underneath WAV, AVI,
WebP, DLS, RMID and a good deal else.
RIFF is a container and not a format. A file is twelve bytes of header —
`RIFF`, a length, and a four-character *form type* saying what kind of file
this is — and then a sequence of chunks, each a four-character identifier, a
length, and that many bytes. Everything that makes a WAV a WAV is in the
chunks; everything in this library is the walk between them.
The [API documentation](https://jeff.jcollie.page/zig-riff/) is generated from
the doc comments in the source, which is where the reasoning lives.
## Using it
```zig
var reader: riff.Reader = try .init(&stream);
if (!reader.form.is("WEBP")) return error.NotWebp;
while (try reader.next()) |chunk| {
if (chunk.is("VP8L")) {
var buf: [64]u8 = undefined;
try decodeLossless(reader.payload(&buf));
}
// Anything left unread is stepped over by the next `next`.
}
```
Sans-I/O: everything reads through a caller-supplied `std.Io.Reader` and
writes through a `std.Io.Writer`. Nothing here opens a file, so a walk over a
network stream is the same code as one over memory, and the whole library is
testable without touching a disk.
Add it with:
```console
zig fetch --save git+https://git.jcollie.dev/jeff/zig-riff.git
```
and depend on the module named `riff`.
`main` builds with Zig 0.17. The `zig-0.16` branch, from tag `v0.2.0`, is the
last that builds with Zig 0.16 and takes only critical fixes.
## What it handles, and why each is worth saying
### The pad byte
**A chunk is padded to an even length, and the pad byte is not counted in the
chunk's length.** This is the single most common way to write a RIFF parser
that works on most files and desynchronises on some, because a file whose
chunks all happen to have even lengths never exercises it. Every length here
goes through `Chunk.padded`, and the walk steps o…