rav1d-safe

A safe Rust AV1 decoder. Forked from rav1d, with 160k lines of hand-written x86/ARM assembly replaced by safe Rust SIMD intrinsics.

Quick Start

Add to your Cargo.toml:

[dependencies]
rav1d-safe = "0.1"

Decode an AV1 bitstream:

use rav1d_safe::{Decoder, Planes};

fn decode(obu_data: &[u8]) -> Result<(), Box<dyn std::error::Error>> {
    let mut decoder = Decoder::new()?;

    // Feed raw OBU data (not IVF/WebM containers)
    if let Some(frame) = decoder.decode(obu_data)? {
        println!("{}x{} @ {}bpc", frame.width(), frame.height(), frame.bit_depth());

        match frame.planes() {
            Planes::Depth8(planes) => {
                for row in planes.y().rows() {
                    // row is &[u8] — zero-copy, no allocation
                }
            }
            Planes::Depth16(planes) => {
                let px = planes.y().pixel(0, 0); // 10 or 12-bit value
            }
        }
    }

    // Drain any buffered frames
    for frame in decoder.flush()? {
        // ...
    }
    Ok(())
}

API Overview

The public API lives in src/managed.rs and is re-exported at the crate root.

Core types:

Metadata types: ColorInfo, ColorPrimaries, TransferCharacteristics, MatrixCoefficients, ColorRange, ContentLightLevel, MasteringDisplay, PixelLayout

Input Format

The decoder expects raw AV1 Open Bitstream Unit (OBU) data. If you have IVF or WebM containers, strip the container framing first and pass the OBU payload. See tests/ivf_parser.rs for an IVF parser example. For AVIF images, use zenavif-parse to extract the OBU data from the ISOBMFF container.

Threading

use rav1d_safe::{Decoder, Settings, CpuLevel};

// Single-threaded (default) — synchronous, deterministic
let decoder = Decoder::new()?;

// Multi-threaded — frame threading, better throughput
let decoder = Decoder::with_settings(Settings {
    threads: 0, // auto-detect core count
    ..Default::default()
})?;

// Constrained decoding — limit frame size and CPU features
let decoder = Decoder::with_settings(Settings {
    frame_size_limit: 3840 * 2160, // reject frames larger than 4K
    cpu_level: CpuLevel::Native,   // use best available SIMD
    ..Default::default()
})?;

With threads >= 2 or threads == 0, the decoder uses frame threading. decode() may return None for complete frames because processing is asynchronous — call it repeatedly or use flush() to drain.

HDR Metadata

if let Some(cll) = frame.content_light() {
    println!("MaxCLL: {} nits", cll.max_content_light_level);
}
if let Some(mdcv) = frame.mastering_display() {
    println!("Peak: {} nits", mdcv.max_luminance_nits());
}
let color = frame.color_info();
// color.primaries, color.transfer_characteristics, color.matrix_coefficients

Error Handling

All fallible operations return Result<T, rav1d_safe::Error>. Error variants: InvalidData, OutOfMemory, NeedMoreData, InitFailed, InvalidSettings, Other.

Safety Model

The default build (forbid(unsafe_code) crate-wide) contains zero unsafe in the main crate. The only unsafe code lives in the rav1d-disjoint-mut workspace sub-crate, a provably sound RefCell-for-ranges abstraction with always-on bounds checking.

The SIMD path uses:

• archmage for token-based target-feature dispatch (no manual #[target_feature])
• safe_unaligned_simd for reference-based SIMD load/store (no raw pointers)
• Value-type SIMD intrinsics, which are safe functions since Rust 1.93
• Slice-based APIs throughout — no pointer arithmetic in SIMD code

Verify at runtime with rav1d_safe::enabled_features() — returns a comma-delimited list including the active safety level (e.g. "bitdepth_8, bitdepth_16, safety:forbid-unsafe").

What's Been Ported

The default build compiles under forbid(unsafe_code) in the main crate. All SIMD work lives in src/safe_simd/ (59k lines of safe Rust replacing 233k lines of hand-written assembly across x86 and ARM).

Ported: All DSP Kernels (AVX2 + NEON)

Every DSP kernel family has a safe Rust SIMD implementation that compiles under forbid(unsafe_code):

Skipped (With Rationale)

msac small-symbol functions (symbol_adapt4, symbol_adapt8, bool_adapt, bool_equi, hi_tok) — The ASM versions exist for SSE2 and NEON (~1,200 lines total across x86+ARM), but profiling shows SIMD overhead exceeds the benefit for these small-n operations. The scalar Rust fallback is used. These functions are hot (msac is 32% of unchecked decode time), but the bottleneck is branch prediction and serial dependency chains, not data parallelism.

SSE-only paths — 14 files, ~52k lines. The safe SIMD dispatch jumps straight to AVX2 when available. On pre-AVX2 hardware (pre-Haswell, 2013), the decoder falls back to scalar Rust rather than SSE intrinsics. This is a deliberate tradeoff: SSE-only x86 hardware is rare enough that maintaining a second intrinsics tier isn't worth the code.

ARM SVE2, dotprod, i8mm extensions — mc_dotprod.S (1,880 lines) and mc16_sve.S (1,649 lines) are optional fast paths for newer ARM cores. The safe SIMD covers baseline NEON; these extension paths fall back to the NEON implementation.

ASM infrastructure files — x86inc.asm (1,983 lines), asm.S, util.S, *_tmpl.S, *_common.S are macro libraries and constants that only exist to support the raw assembly. No independent functionality to port.

TODO

AVX-512 — 12 files, ~26k lines across all DSP modules. Currently falls back to the AVX2 safe path. Porting these would improve throughput on Zen 4, Ice Lake, and later. The work is straightforward (same algorithms, wider vectors) but substantial.

Performance

Benchmarked on x86_64 (AVX2), single-threaded, 500 iterations via examples/profile_decode:

The unchecked feature disables DisjointMut runtime borrow tracking and slice bounds checks, giving ~27% speedup on 8bpc. The remaining gap vs ASM is function call and inlining differences — the safe SIMD uses the same AVX2 intrinsics but through Rust's calling conventions rather than hand-tuned register allocation.

Building

Requires Rust 1.93+ (stable). Install via rustup.rs.

# Default safe-SIMD build (recommended)
cargo build --release

# With original hand-written assembly (for benchmarking)
cargo build --features asm --release

# Run tests
cargo test --release

Feature Flags

Cross-Compilation

# aarch64
RUSTFLAGS="-C linker=aarch64-linux-gnu-gcc" \
  cargo build --target aarch64-unknown-linux-gnu --release

# Verify aarch64 NEON compiles
cargo check --target aarch64-unknown-linux-gnu

Supported targets: x86_64-unknown-linux-gnu, aarch64-unknown-linux-gnu, i686-unknown-linux-gnu, armv7-unknown-linux-gnueabihf, riscv64gc-unknown-linux-gnu.

License

New code in this fork (safe SIMD implementations, managed API, tooling) is dual-licensed:

• AGPL-3.0-or-later for open-source use
• Commercial license available from Imazen for proprietary use

The upstream rav1d/dav1d code retains its original BSD-2-Clause license.

Upstream Contribution

This fork exists because maintaining a separate safe SIMD implementation is the fastest path to getting safe Rust AV1 decoding into production. If the rav1d maintainers are interested in upstreaming any of this work under the original BSD-2-Clause license, we'd be happy to contribute. Open an issue or reach out.

Acknowledgments

Built on the work of the dav1d team (VideoLAN) and the rav1d team (ISRG/Prossimo). The original C and assembly implementations are exceptional — this fork just proves you can match that performance in safe Rust.