oximedia-codec

Video and audio codec implementations for the OxiMedia multimedia framework. Pure-Rust, royalty-free codecs with image I/O support.

Part of the oximedia workspace — a comprehensive pure-Rust media processing framework.

Version: 0.1.6 — 2026-04-26 — 3,063 tests

Overview

oximedia-codec provides encoding and decoding for royalty-free video codecs plus image I/O. Decoder rows use the project-wide four-tier honesty taxonomy; see docs/codec_status.md for per-decoder details, what is missing per codec, and the effort required to close each gap.

Usage

Add to your Cargo.toml:

[dependencies]
oximedia-codec = "0.1.6"
# or with additional codecs:
oximedia-codec = { version = "0.1.6", features = ["av1", "vp9", "vp8", "opus"] }

AV1 / VP9 / VP8 / Theora Bitstream Parsing

These decoders currently parse bitstreams but do not reconstruct pixel data (see the matrix above). They are useful for format inspection, extradata handling, and container-side work. The API shape below matches what the crate exposes today; the returned frames have allocated planes but do not contain reconstructed pixels until the work tracked in GitHub issue #9 lands.

use oximedia_codec::{Av1Decoder, DecoderConfig, VideoDecoder};
use oximedia_core::CodecId;

let config = DecoderConfig {
    codec: CodecId::Av1,
    extradata: None,
    threads: 0,
    low_latency: false,
};
let mut decoder = Av1Decoder::new(config)?;
decoder.send_packet(&packet_bytes, pts)?;
while let Some(_frame) = decoder.receive_frame()? {
    // Frame metadata (width/height/format/timestamp) is populated;
    // pixel planes are not reconstructed in 0.1.6.
}

Vp9Decoder, Vp8Decoder, and TheoraDecoder follow the same VideoDecoder trait shape. See docs/codec_status.md for the honest per-decoder status.

Opus Decoding

use oximedia_codec::opus::OpusDecoder;

let mut decoder = OpusDecoder::new(48000, 2)?;
let audio_frame = decoder.decode_packet(&packet_data)?;

JPEG-XL: ISOBMFF Container Output

AnimatedJxlEncoder (feature jpegxl) supports two output modes:

finish() — bare codestream

Produces a raw JPEG-XL codestream starting with the 0xFF 0x0A magic bytes.

finish_isobmff() — ISOBMFF container

Wraps the codestream in the standard ISOBMFF box structure:

ftyp  (major brand: "jxl ", compatible: ["jxl ", "isom"])
jxll  (JXL level 5)
jxlp  (codestream packet with is_last flag set)

The resulting bytes are decodable by JxlStreamingDecoder:

# // no_run — requires jpegxl feature and runtime data
use std::io::Cursor;
// let bytes = encoder.finish_isobmff()?;
// let decoder = oximedia_codec::jpegxl::JxlStreamingDecoder::new(Cursor::new(bytes));
// for frame_result in decoder? { ... }

Streaming Decode — JxlStreamingDecoder<R: Read>

JxlStreamingDecoder is a lazy Iterator<Item = CodecResult<JxlFrame>> that yields frames one at a time without buffering the entire sequence. It auto-detects the format:

# // no_run — requires jpegxl feature and runtime data
// use oximedia_codec::jpegxl::JxlStreamingDecoder;
// use std::io::Cursor;
//
// for frame_result in JxlStreamingDecoder::new(Cursor::new(data))? {
//     let frame = frame_result?;
//     println!("{}x{} ticks={}", frame.width, frame.height, frame.duration_ticks);
// }

MJPEG: Baseline JPEG Spec Compliance

The mjpeg module (feature mjpeg) wraps oximedia-image's pure-Rust JPEG baseline encoder and decoder. The encoder:

• Emits DQT (Define Quantization Table) segments with quantization values in the standard JPEG zigzag scan order
• Achieves ≥28 dB PSNR at quality setting 85 for natural images (verified by round-trip tests)
• Produces fully self-contained JFIF-compliant JPEG frames suitable for AVI and MP4 containers

Architecture

Unified Traits

All codecs implement unified traits:

pub trait VideoDecoder {
    fn send_packet(&mut self, packet: &EncodedPacket) -> CodecResult<()>;
    fn receive_frame(&mut self) -> CodecResult<Option<VideoFrame>>;
    fn flush(&mut self) -> CodecResult<()>;
}

pub trait VideoEncoder {
    fn send_frame(&mut self, frame: &VideoFrame) -> CodecResult<()>;
    fn receive_packet(&mut self) -> CodecResult<Option<EncodedPacket>>;
    fn flush(&mut self) -> CodecResult<Vec<EncodedPacket>>;
}

Rate Control Modes

SIMD Support

The codec includes a SIMD abstraction layer:

• Scalar fallback (always available)
• SSE/AVX support (x86/x64)
• NEON support (ARM)

Module Structure (194 source files, 3046 public items)

src/
├── lib.rs              # Crate root with re-exports
├── error.rs            # CodecError and CodecResult
├── frame.rs            # VideoFrame, Plane, ColorInfo
├── traits.rs           # VideoDecoder, VideoEncoder traits
├── av1/                # AV1 codec (OBU parsing, symbol coding, entropy)
├── vp9/                # VP9 codec (frame, context)
├── vp8/                # VP8 codec (DCT, motion, loop filter)
├── theora/             # Theora codec (VP3-based)
├── opus/               # Opus audio (SILK, CELT, range decoder)
├── intra/              # Shared intra prediction
├── motion/             # Motion estimation
├── rate_control/       # Rate control framework
├── reconstruct/        # Reconstruction pipeline
├── entropy_coding/     # Entropy coding
├── tile_encoder/       # Tile-based encoding
└── simd/               # SIMD abstraction (scalar, SSE/AVX, NEON)

Patent Policy

All codecs are royalty-free:

Supported codecs: AV1, VP9, VP8, Theora, Opus

Rejected codecs: H.264, H.265, AAC, AC-3, DTS

When a patent-encumbered codec is detected in a container, a PatentViolation error is returned.

Policy

• No unsafe code (#![deny(unsafe_code)])
• Apache-2.0 license

License

Apache-2.0 — Copyright 2024-2026 COOLJAPAN OU (Team Kitasan)