av1-obu-parser is a bitstream analysis tool for AV1. It parses AV1 Open Bitstream Units (OBUs), keeps the cross-frame context required by frame headers, and can also unpack IVF containers before feeding their payloads to the OBU parser.

This is not a video decoder. It does not reconstruct pixels. The goal of this project is to inspect AV1 syntax structures and print useful stream metadata for debugging, learning, and tooling.

Features

• Parse AV1 OBU headers and payloads in pure Rust
• Keep parser context across Sequence Header, Frame Header, and Frame OBUs
• Read IVF file headers and iterate frame payloads with IvfReader
• Ship with a runnable example for inspecting DEMO.ivf
• Include focused unit and integration tests

License

This project is licensed under the MIT License. See LICENSE.

Quick Start

Clone the repository and run the test suite:

cargo test

The repository includes a sample IVF file at the project root:

DEMO.ivf

Example Program

Run the bundled example against DEMO.ivf:

cargo run --example simple

Limit the output to the first 10 OBUs:

cargo run --example simple -- --oubs 10

Show TemporalDelimiter OBUs as well so the numbering matches other analyzers:

cargo run --example simple -- --oubs 10 --show-delimiter

Use a different input file:

cargo run --example simple -- --input path/to/sample.ivf --oubs 20 --show-delimiter

Library Usage

Parse a raw OBU payload

use av1_obu_parser::{buffer::Buffer, obu::ObuParser};

let data: Vec<u8> = vec![];
let mut parser = ObuParser::default();
let mut buffer = Buffer::from_slice(&data);

while buffer.bytes_remaining() > 0 {
    match parser.parse(&mut buffer) {
        Ok(obu) => println!("{obu:?}"),
        Err(err) => {
            eprintln!("parse error: {err}");
            break;
        }
    }
}

Parse an IVF container first

use av1_obu_parser::{buffer::Buffer, IvfReader, obu::ObuParser};

let file_data = std::fs::read("DEMO.ivf")?;
let ivf = IvfReader::new(&file_data)?;

println!(
    "codec={}, resolution={}x{}",
    ivf.header().codec_string(),
    ivf.header().width,
    ivf.header().height
);

let mut parser = ObuParser::default();
for frame in ivf.frames() {
    let frame = frame?;
    let mut buffer = Buffer::from_slice(frame.data);

    while buffer.bytes_remaining() > 0 {
        match parser.parse(&mut buffer) {
            Ok(obu) => println!("frame {}: {obu:?}", frame.index),
            Err(err) => {
                eprintln!("frame {}: {err}", frame.index);
                break;
            }
        }
    }
}
# Ok::<(), Box<dyn std::error::Error>>(())

Project Layout

• src/buffer.rs: bit-level AV1 syntax reader
• src/obu/: AV1 OBU parsing logic
• examples/simple.rs: command-line inspection example
• tests/integration_test.rs: parser and IVF integration coverage

Notes

• The example output is intended for debugging and comparison with other AV1 analyzers.
• --show-delimiter is useful when you want local output to line up with tools that display every OBU, including temporal delimiters.