oxideav

A pure-Rust media transcoding and streaming framework. Every codec, container, and filter is implemented from the spec — no C libraries, no *-sys crates, no Rust wrappers around a userspace codec library.

The only place we use FFI is the optional hardware-acceleration crates (oxideav-videotoolbox / -audiotoolbox / -vaapi / -vdpau / -nvidia / -vulkan-video), which are thin bridges to the OS-provided HW engines — there's no other way to talk to GPU/ASIC encoder blocks. Those bridges load the system frameworks at runtime via libloading (no compile-time link, no *-sys build dep, no header shipped); the framework still builds and runs without any of them present. Disable hardware entirely with --no-hwaccel or by not enabling the hwaccel feature.

• Pure-Rust codec implementations. No C codec library is wrapped, linked, or depended on — directly or transitively. Every codec, container, and filter is implemented from the spec.
• Clean abstractions for codecs, containers, timestamps, and streaming formats.
• Composable pipelines: media input → demux → decode → transform → encode → mux → output, with pass-through mode for remuxing without re-encoding.
• Modular workspace: per-format crates for complex modern codecs/containers, a shared crate for simple standard formats, and an oxideav-meta aggregator that wires them together behind Cargo features (preset bundles audio / video / image / subtitles / hwaccel / source-drivers / all; pure-rust = all minus hwaccel for zero-FFI builds; plus per-crate flags for fine slimming).
• Hardware acceleration via the OS: oxideav-videotoolbox / -audiotoolbox / -vaapi / -vdpau / -nvidia / -vulkan-video open the host OS's HW engine through libloading (runtime-loaded, no *-sys build dep). The OS's driver stack is the only path to GPU/ASIC codec blocks; we wrap the smallest possible surface (encode/decode session lifecycle + buffer in/out) and never re-implement OS APIs.

• Wrapping or linking userspace C codec libraries (ffmpeg, x264/x265, libvpx, libaom, libvorbis, libopus, libjxl, OpenJPEG, …).
• Perfect feature parity with FFmpeg on day one. Codec and container coverage grows incrementally.
• Re-implementing the GPU driver stack — for HW codecs we go through the OS, never around it.

This is the strict and universal rule every contributor and every automated agent must follow. It is not a list of named libraries — it is a categorical prohibition:

No external library source code may be consulted, quoted, paraphrased, or used as a cross-check oracle while implementing any codec, container, protocol, or filter in this workspace.

The rule applies to every external implementation, not a specific blocklist. That includes (but is in no way limited to): ffmpeg / libav*, x264, x265, libvpx, libaom, dav1d, SVT-AV1, libvorbis, libopus, libspeex, fdk-aac, LAME, libjxl, jxlatte, jxl-rs, FUIF, brunsli, OpenJPEG, OpenJPH, Kakadu, schroedinger, xeve / xevd, VTM, JM, mp4v2, every reference implementation distributed alongside a spec, and every third-party Rust crate that wraps or implements the same format (lewton, claxon, image's codec submodules, png, jpeg-decoder, anything else of similar shape).

"Cross-checking" counts. Reading an external implementation "just to verify a table value" or "just to see how they handle this edge case" still contaminates the code. If you couldn't have written it without that reference, the resulting code is no longer clean-room.

Allowed references:

• Spec PDFs (ISO, ITU, ATSC, ETSI, RFC, IETF drafts, Annex documents)
• Clean-room behavioural-trace docs commissioned for this project (these are explicitly source-quote-free; the strict-isolation cleanroom workspace pattern at docs/video/msmpeg4/, docs/video/magicyuv/, docs/audio/tta-cleanroom/ is the bar — Specifier role never reads the reference implementation source. Earlier behavioural-trace doc-only formats were retired 2026-05-06 under fruits-of-poisonous-tree)
• Reverse-engineered docs derived from disassembly of binary codecs whose source is unavailable (see docs/video/msmpeg4/spec/01..13)
• Public test corpora (raw fixture files: .jxl, .j2k, .opus, .flac etc.)

Allowed validators (black-box only): Decoder/encoder binaries — ffmpeg, cjxl / djxl, ojph_compress / ojph_expand, opusdec, etc. — may be invoked as opaque processes for output comparison. Feed input, compare output bytes. Their source stays off-limits.

What to do when stuck: If the spec PDF is ambiguous and no clean-room trace doc covers your case, the right move is to ask the docs collaborator to commission a behavioural-trace writeup, not to peek at the reference implementation. Park the work and document the gap.

This policy exists for legal and provenance reasons. Violations have to be expunged from history (force-push), not just reverted, because git blame would still tie the contaminated commit to the project.

The workspace is a set of Cargo crates under crates/, grouped by role:

• Infrastructure — oxideav-core (primitives: Packet / Frame / Rational / Timestamp / PixelFormat (incl. 16-bit planar YUV + deep Yuva 4:2:2/4:4:4 at 10/12/16-bit; VideoFrame palette + per-plane significant-bits side-channels for mixed-depth streams; r429: deep Yuva 4:2:0 + 8/16-bit planar GBR(A) formats + Ogg BOS-magic codec resolution; r449: 4:4:0 YUV ladder + scene-referred F32 family + plane-geometry/sizing helpers — 70 formats) / ExecutionContext + DoS framework: DecoderLimits caps, arena::ArenaPool (Rc-based, single-threaded) + arena::sync::ArenaPool (Arc-based, Send + Sync) refcounted bump-allocator pools, refcounted Frame whose drop returns the buffer to the pool, Decoder::receive_arena_frame() trait method with default impl that wraps receive_frame() for true zero-copy per-decoder opt-in (h261, h263, vp6 ports done) — Decoder / Encoder / Demuxer / Muxer traits + their registries also live here, in oxideav_core::registry::*; numeric core is overflow-total (checked + rounding-mode Rational/rescale), LSB/MSB bit-I/O parity, property-tested + benched, 100% rustdoc under missing_docs), oxideav-pipeline (source → transforms → sink composition; r449 error-recovery contract — typed RunFailure attribution incl. partial stats + opt-in failed-output disposal down to partial-file deletion).
• I/O — oxideav-source (generic SourceRegistry + 5 scheme drivers (file/mem/data/slice/concat) with a typed URI triad + open_bytes dispatch + sticky-error prefetch ring; openers register as bytes / packets / frames and SourceRegistry::open returns the matching SourceOutput::{Bytes, Packets, Frames} variant so the executor can branch per shape; conformance + differential + fuzz suites, benched), oxideav-http (HTTP/HTTPS bytes driver, opt-in via feature — RFC 9110 Range-seek with span accounting, If-Range-guarded transparent resume, forward-seek drain + GET range-probe for HEAD-hostile origins + driver-owned RFC 9110 §15.4 redirects with RFC 3986 resolution; lacks cookies/auth), oxideav-rtmp (rtmp:// packet driver — registers via oxideav_rtmp::register(&mut sources), default-on in oxideav-cli).
• Effects + conversions — oxideav-audio-filter (Volume / NoiseGate / Echo / Resample / Spectrogram), oxideav-image-filter (stateless single-frame Blur / Edge / Resize), oxideav-pixfmt (pixel-format conversion matrix — 3224/3306 ordered pairs (912 direct) via direct rows + staged fallback + the computed planar-family tier (full 24-member Yuv/Yuva + 9-member GBR families), reference-model + black-box-validated matrices + palette generation + dither).
• Containers — one crate each for oxideav-ogg / -mkv / -mp4 / -avi / -iff. Simple containers (WAV, raw PCM, slin) live inside oxideav-basic.
• Codec crates — one crate per codec family; see the Codecs table below for the per-codec status. Tracker formats (oxideav-mod, oxideav-s3m) are decoder-only by design. Recent sibling crates: oxideav-evc (MPEG-5 EVC, ISO/IEC 23094-1), oxideav-jpegxs (JPEG XS, ISO/IEC 21122), oxideav-midi (Standard MIDI File + soft-synth + UMP/MIDI 2.0 packet container & protocol), oxideav-pbm (Netpbm: PBM/PGM/PPM/PNM/PAM), oxideav-nsf (NES Sound Format — 6502 emu + 2A03 APU); image-format bootstrap wave: oxideav-dds, oxideav-openexr, oxideav-farbfeld, oxideav-hdr (Radiance RGBE), oxideav-qoi, oxideav-tga, oxideav-icer (JPL Mars-rover), oxideav-wbmp, oxideav-pcx, oxideav-pict (Apple QuickDraw); oxideav-iff extended with ILBM; oxideav-embroidery (machine-embroidery stitch formats — Tajima DST + Brother PEC/PES + Melco EXP + Janome JEF family (JEF/JEF+/JPX/PTN)
  • Husqvarna HUS/VIP decode+encode over an in-house GL bitstream decoder, PHC/PHB decode, .edr/.inf companions; typed stitch-design model + registry/probe framework fit (13-extension map, dual API); r440 corpus-pinned encoder choices, 33/33 real GL streams exact; lacks a real PHX sample + VP3/XXX stitch docs — ART is a documented no-grant). AVIF decodes end-to-end via oxideav-av1 (pixel fidelity tracks the AV1 intra decoder).
• Vector graphics + text — oxideav-svg (read+write SVG; rounds 1-3 ship full shape set + text/filters/masks/clipPath + use/symbol + svgz + animate/set@t=0), oxideav-pdf (multi-page writer + Scene metadata via /Info dict; reader: bytes → Scene with xref + FlateDecode + content-stream operator parser + the full §8.9 image model (any BPC / colour space / Decode, stencil + colour-key + SMask masking, inline-image splicing; gs-validated) + r418 navigation surface (outline/links/named-dests/page-labels/article-threads) + embedded-CMap Type0 text extraction + vertical writing; lacks predefined CJK CMap tables), oxideav-raster (vector→raster rendering kernel — scanline AA, bilinear/Lanczos2/Lanczos3 + Mitchell/Catmull-Rom/B-spline cubic image resampling, trapezoidal coverage, soft masks, patterns, filter primitives, ICC pipeline, bitmap cache keyed by Group::cache_key, SVG2 stroke-linejoin miter-clip/arcs §13.5.5; r449 byte-exact perf pass — 1.79× geo-mean over 32 benches, caption-heavy scene 32.5×), oxideav-ttf (TrueType parser — cmap 0/4/6/12/14 incl. Variation Sequences, GSUB ligatures, GPOS kerning + per-script feature selection + coherent Font::shape() engine (all GSUB+GPOS lookup types, IGNORE_MARKS-aware, Arabic joining + mark attachment validated) + v1.1 FeatureVariations, COLR + CPAL + sbix tables + r369 CFF/CFF2 PostScript+variable outlines (Type 2 charstrings, CID-keyed, blend per-instance) + MATH + JSTF, TTC subfont selection, AGL glyph-name→Unicode, full name-table accessor API + gvar IUP inferred-delta variable-glyph interpolation + set-axis-by-tag/named-instance API), oxideav-otf (CFF / Type 2 charstrings incl. CID-keyed ROS/FDArray/FDSelect + arithmetic/stack/storage/conditional ops + Top-DICT FontMatrix/PaintType/CharstringType/StrokeWidth, ISOAdobe/Expert/ExpertSubset predefined charsets, cubic outlines; r222 GDEF + Coverage + ClassDef common-layout primitives + GlyphClass enum + GPOS ValueRecord/ValueFormat + Lookup Type 1 single-adjustment + CFF2 §12 ItemVariationStore for variable fonts; r352 GPOS Lookup Types 1-9 + GSUB Types 1-7 incl. mark-to-ligature + contextual/chained via shared module; r369 CFF2 variation-aware outlines (blend/vsindex) + GSUB Type 8 reverse-chaining + Device/VariationIndex tables + cmap formats 2/13/14+UVS; r372 variable-font GPOS/GDEF/BASE VariationIndex resolution — Device/VariationIndex deltas applied to kerning/marks/cursive/carets/baselines + CFF2 blend; r375 §6.3.6.2.1 MATH variable-font MathValueRecord resolution + BASE BaseCoordFormat3 VariationIndex baseline coordinates; r380 full OFF variable-font table set (fvar/avar/STAT/MVAR/HVAR/VVAR/BASE + ItemVariationStore/DeltaSetIndexMap + Font::normalize_coords axis→region-scalar) + vertical metrics (vhea/vmtx/VORG) + legacy kern formats 0/2; r394 Font::shape TEXT-SHAPING pipeline — GSUB 1–8 + GPOS 1–9 + FeatureVariations + variable-instance deltas, black-box byte-validated; r407 COLR v0+v1 paint graph (all 32 paint formats, ColorLine/ClipList, varIndexBase resolution) + avar v2 cross-axis deltas + 243-tag feature registry + UAX #24 Script_Extensions, r413 full colour-font surface: CPAL v0/v1 + COLR paint-graph→concrete-RGBA, sbix, EBLC/EBDT/EBSC, CBLC/CBDT, SVG table — real-font black-box validated; r418 COLR v1 paint-graph decode (all 32 formats, variable, budget-capped validator) + avar v2 cross-axis normalisation; r435 UAX #24 itemized shaping over vendored UCD 17 (Font::shape_runs per-run script tags) + script/language/baseline tag registries + CPAL linear-light gradient interpolation + IVS LONG_WORDS + CJK em-box/ICF; r443 OFF common-formats completion — DeltaSetIndexMap format 1, LONG_WORDS delta rows, NULL IVD offsets, variable-COLR conformance fixture end-to-end + gvar repeated-point accumulation fix), oxideav-scribe (shaper with vector-first Shaper::shape_to_paths API — no rasterizer dep; trapezoidal horizontal AA, GPOS mark-to-mark, COLR/CBDT colour glyphs via raster bilinear/composer; bidi UAX #9 data-complete at Unicode 16.0 — Bidi_Class ranges + bracket pairs + mirror table; r445 full UAX #24 §5 itemisation — Script_Extensions sets + paired-bracket refinement + universal §5.2 cluster model + cluster-atomic font fallback; lacks per-script USE syllable grammars — docs-gapped).
• 3D scenes & assets — typed oxideav-mesh3d (Scene3D / Mesh / Material PBR / Skin / Animation / Camera / Light / AudioEmitter + area-weighted vertex-normal recompute + MikkTSpace-style tangent-space basis (Lengyel 2001) + full skeletal pipeline (joint matrices + linear-blend skinning + weight repair + pose sampling + animated/rest instantiation + skin-root LCA) + r448 morph model complete (typed target names, USD in-between stations, sampled-MorphWeights synthesis) + Mesh3DRegistry parallel to CodecRegistry + AssetSource lazy-bytes trait with raw_storage pass-through for archive-backed sources). Per-format codecs oxideav-stl / -obj / -gltf / -usdz register into the registry; oxideav-meta::populate_mesh3d_registry walks every enabled format. See the 3D scenes & assets table below for per-format status. oxideav convert in.obj out.gltf (or --probe in.gltf) is the CLI entry point. Cross-format integration tests live under crates/oxideav-tests/tests/mesh3d_*.rs.
• Facade — oxideav is a thin re-exporter over oxideav-core + oxideav-pipeline + oxideav-source. Holds no codec deps; the high-level invoke API will live here.
• Aggregator — oxideav-meta exposes register_all(&mut RuntimeContext) which explicitly invokes every enabled sibling's register(ctx) fn. Each sibling is a Cargo feature; default = ["all"] pulls everything. Preset bundles available: audio, video, image, subtitles, hwaccel, source-drivers, all, and pure-rust (= all minus hwaccel, for builds that avoid all FFI to OS HW-engine APIs). Slim builds via oxideav-meta = { default-features = false, features = ["image"] } (or any per-crate combo). register_all body is auto-generated by oxideav-meta's build.rs from its own Cargo.toml — adding a sibling means adding one line to Cargo.toml; the build script regenerates the call list. (Earlier attempt at a linkme-based distributed-slice approach was dropped: linkme has open issues on wasm32 targets, and its DCE workaround required a manual ensure_linked() call from main anyway.)
• Binaries — oxideav-cli (the oxideav CLI: list / probe / remux / transcode / run / validate / dry-run / convert) and oxideplay (reference SDL2 + TUI player). Windows-codec forensic debugging now lives in KarpelesLab/univdreams via ud vfw {probe,decode,encode} — see Windows codec sandbox below.

(oxideav-job and oxideav-tracevfw are retired — oxideav-job's functionality moved into oxideav-pipeline; oxideav-tracevfw's debugger CLI moved into ud-cli from univdreams, which also hosts the underlying x86/PE/Win32 sandbox. Both archived on GitHub.)

Use cargo run --release -p oxideav-cli -- list to enumerate the codec and container matrix actually compiled into the release binary.

• Packet — a chunk of compressed (encoded) data belonging to one stream, with timestamps.
• Frame — a chunk of uncompressed data (audio samples or a video picture).
• Stream — one media track inside a container (audio, video, subtitle…).
• TimeBase / Timestamp — rational time base per stream; timestamps are integers in that base.
• Demuxer — reads a container, emits Packets per stream.
• Decoder — turns Packets of a given codec into Frames.
• Encoder — turns Frames into Packets.
• Muxer — writes Packets into an output container.
• Pipeline — connects these pieces. A pipeline can pass Packets straight from Demuxer to Muxer (remux, no quality loss) or route through Decoder → [Filter] → Encoder.
• Scene — a time-based composition of objects (images, videos, text, shapes, audio cues) on a canvas, animated over a timeline via keyframed properties. One model covers three workloads that would otherwise be separate stacks: a single-frame document layout (e.g. a PDF page — text stays selectable, vectors stay crisp), a long-running live compositor driven by external operations (add/move/fade — the shape an RTMP overlay control plane needs), and an NLE timeline with tracks, transitions, and per-object effect chains. A Scene feeds the pipeline as a Source: the renderer rasterises a frame at a given timestamp, so scenes can be encoded, streamed, or re-exported like any other media stream. Lives in oxideav-scene — type model is in place; rendering backends live in oxideav-render (scanline rasteriser + Whitted raycast).

Every codec crate in OxideAV is designed to be usable on its own. Pull only oxideav-core (types + the Decoder / Encoder traits + CodecRegistry) and the codec itself:

[dependencies]
oxideav-core = "0.1"
oxideav-g711 = "0.0"   # or any other codec crate

use oxideav_core::{CodecId, CodecParameters, CodecRegistry, Frame, Packet, TimeBase};

let mut reg = CodecRegistry::new();
oxideav_g711::register(&mut reg);

let mut params = CodecParameters::audio(CodecId::new("pcm_mulaw"));
params.sample_rate = Some(8_000);
params.channels = Some(1);

let mut dec = reg.make_decoder(&params)?;
dec.send_packet(&Packet::new(0, TimeBase::new(1, 8_000), ulaw_bytes))?;
let Frame::Audio(a) = dec.receive_frame()? else { unreachable!() };
// `a.data[0]` is S16 PCM.

Each codec crate's README has a concrete example tailored to its payload shape.

oxideav list (via the CLI) prints the live, build-time-accurate codec + container matrix with per-implementation capability flags — that's the source of truth at any point. The tables below are the human-readable summary, grouped + collapsible so the page stays scannable.

Legend: ✅ = working end-to-end at the scope described. 🚧 = scaffold or partial — the row spells out what is present and what is still pending. — = not implemented.

Each row below is a current-state summary. For round-by-round history, design notes, and per-feature trade-offs, see the per-crate README.md and CHANGELOG.md in crates/oxideav-<codec>/.

The oxideav-id3 crate parses ID3v2.2 / v2.3 / v2.4 tags + typed ID3v1/1.1 and Enhanced TAG+ trailers + CHAP/CTOC chapter frames (read+write symmetric, cycle-safe TOC walkers) (v2.2: complete §4 frame table with typed v2.2-only walkers + §3.1 compression-bit skip since r283; whole-tag and per-frame unsync, extended header with CRC-32 [ISO-3309] verification and emission since r153, v2.4 data-length indicator, encrypted/compressed frames recorded as Unknown (v2.2 §4.20 CRM encrypted-meta frame now typed decode/encode/round-trip), r161 v2.4 §3.4 footer emission + strict trailer-validation on read composable with whole-tag/per-frame unsync + extended-header CRC) plus the legacy 128-byte ID3v1 trailer. Text frames (T*, TXXX), URLs (W*, WXXX), COMM / USLT, and APIC / PIC picture frames are handled structurally; less-common frames (SYLT, RGAD/RVA2, PRIV, GEOB, UFID, POPM, MCDI, …) survive as Unknown with their raw bytes available.

The oxideav-flac container surfaces the extracted fields via the standard Demuxer::metadata() (Vorbis-comment-style keys: title, artist, album, date, genre, track, composer, …) and cover art via a new Demuxer::attached_pictures() method returning &[AttachedPicture] (MIME type + one-of-21 picture-type enum + description + raw image bytes). FLAC's native METADATA_BLOCK_PICTURE is handled natively; FLAC wrapped in ID3 (a few oddball taggers) works via the fallback path.

oxideav probe file.mp3 prints a Metadata: section and an Attached pictures: section with per-picture summary.

The oxideav-audio-filter crate provides:

• Volume — gain adjustment with configurable scale factor
• NoiseGate — threshold-based gate with attack/hold/release
• Echo — delay line with feedback
• Resample — polyphase windowed-sinc sample rate conversion
• Spectrogram — STFT → image (Viridis/Magma colormaps, RGB + PNG output)

The oxideav-pixfmt crate is the shared conversion layer for video codecs. The PixelFormat enum covers ~30 first-tier formats (ffmpeg equivalent names in parentheses):

• RGB family: Rgb24, Bgr24, Rgba, Bgra, Argb, Abgr, plus 16-bit-per-channel Rgb48Le / Rgba64Le.
• YUV planar: Yuv420P / Yuv422P / Yuv444P at 8 / 10 / 12-bit, plus JPEG-full-range variants (YuvJ420P, YuvJ422P, YuvJ444P).
• YUV semi-planar: Nv12, Nv21. YUV packed: Yuyv422, Uyvy422.
• Grayscale: Gray8, Gray10Le, Gray12Le, Gray16Le.
• Alpha-bearing: Ya8, Yuva420P.
• Palette: Pal8. 1-bit: MonoBlack, MonoWhite.

oxideav_pixfmt::convert(src, dst_format, &ConvertOptions) handles the live conversion matrix (RGB all-to-all swizzles, YUV↔RGB under BT.601 / BT.709 × limited / full range, NV12/NV21 ↔ Yuv420P, Gray ↔ RGB, Rgb48 ↔ Rgb24, Pal8 ↔ RGB with optional dither). Palette generation via generate_palette() offers MedianCut and Uniform strategies. Dither options: None, 8×8 ordered Bayer, Floyd-Steinberg.

Codecs declare accepted_pixel_formats on their CodecCapabilities; the job graph (below) auto-inserts conversion when the upstream format doesn't match.

The JSON job graph (executed by oxideav-pipeline via oxideav run; the former oxideav-job crate was folded into the pipeline) is a declarative way to describe multi-output transcode pipelines. A job is a JSON object: keys are output filenames (or reserved sinks like @null / @display), values describe tracks grouped by audio / video / subtitle / all, and each track carries a recursive input tree of source refs and filter / convert nodes.

{
  "threads": 8,
  "@in":       {"all": [{"from": "movie.mp4"}]},
  "out.mkv":   {
    "video": [{"from": "@in", "codec": "h264", "codec_params": {"crf": 23}}],
    "audio": [{"from": "@in", "codec": "flac"}]
  },
  "out.png":   {"video": [{"from": "@in", "convert": "rgba"}]}
}

The executor has two modes: serial (threads == 1) runs one packet at a time; pipelined (threads ≥ 2, default when available_parallelism() ≥ 2) spawns one worker thread per stage per track connected by bounded mpsc channels. The mux/sink loop runs on the caller's thread so JobSink implementations don't need to be Send (the SDL2 player sink in oxideplay stays a single-threaded object). Both modes produce byte-identical output for deterministic jobs.

Decoder / Encoder trait hook: set_execution_context(&ExecutionContext) (default no-op) lets codecs opt into slice- / GOP-parallel work later without trait churn.

Explicit pixel-format conversion nodes ({"convert": "yuv420p", "input": ...}) fit anywhere in the input tree; the resolver also auto-inserts a PixConvert stage between Decode and Encode when a codec's accepted_pixel_formats list excludes the upstream format.

The source layer decouples I/O from container parsing. Container demuxers receive an already-opened Box<dyn ReadSeek> and never touch the filesystem directly. The SourceRegistry resolves URIs to readers:

The HTTP and RTMP drivers are off by default in the library (http / rtmp cargo features) and on by default in oxideav-cli. oxideplay keeps http on; RTMP isn't player-relevant.

BufferedSource wraps any ReadSeek with a prefetch ring buffer (64 MiB default in oxideplay, configurable via --buffer-mib). A worker thread fills the ring ahead of the read cursor; seeks inside the window are free.

$ oxideav probe https://download.blender.org/peach/bigbuckbunny_movies/BigBuckBunny_320x180.mp4
Input: https://download.blender.org/peach/bigbuckbunny_movies/BigBuckBunny_320x180.mp4
Format: mp4
Duration: 00:09:56.46
  Stream #0 [Video]  codec=h264  video 320x180
  Stream #1 [Audio]  codec=aac  audio 2ch @ 48000 Hz

An opt-in binary crate oxideplay implements a reference player with SDL2 (audio + video) and a crossterm TUI. SDL2 is loaded at runtime via libloading — oxideplay doesn't link against SDL2 at build time, so the binary builds and ships without requiring SDL2 dev headers. If SDL2 isn't installed on the target machine, the player exits cleanly with a "library not found" message instead of failing to start. The core oxideav library and every codec/container/filter crate stays pure Rust; the only FFI in the framework lives in the optional HW-engine crates (oxideav-videotoolbox / -audiotoolbox / -vaapi / -vdpau / -nvidia / -vulkan-video), each also runtime-loaded via libloading.

cargo run -p oxideplay -- /path/to/file.mkv
cargo run -p oxideplay -- https://example.com/video.mp4

Keybinds: q quit, space pause, ← / → seek ±10 s, ↑ / ↓ seek ±1 min (up = forward, down = back), pgup / pgdn seek ±10 min, * volume up, / volume down. Works from the SDL window (when a video stream is present) or from the TTY.

When the winit + wgpu video output is selected (--vo winit), oxideplay ships an egui on-screen overlay UI (auto-hide after ~3 s of mouse idle during playback; stays visible while paused). Mouse-driven controls cover play/pause, draggable seek bar, time display, volume slider, mute, ±10 s skip, and a toggleable stats panel. egui (0.34) + egui-wgpu + egui-winit are pure-Rust deps gated behind the winit cargo feature, so SDL2 builds are unaffected.

oxideav command-line verbs: list, probe, remux, transcode, run, validate, dry-run, convert. Inputs can be local paths or HTTP(S) URLs.

$ oxideav list                           # print registered codecs + containers
$ oxideav probe song.flac
$ oxideav transcode song.flac song.wav
$ oxideav remux input.ogg output.mkv
$ oxideav probe https://example.com/video.mp4

# JSON job graph
$ oxideav run job.json
$ oxideav run - < job.json
$ oxideav run --inline '{"out.mkv":{"audio":[{"from":"in.mp3"}]}}'
$ oxideav run --threads 4 job.json        # override thread budget
$ oxideav validate job.json               # check without running
$ oxideav dry-run job.json                # print the resolved DAG

# ImageMagick-style convert (chains filters; accepts generator shorthands)
$ oxideav convert in.png -resize 800x600 out.jpg
$ oxideav convert "xc:red" red.png                      # solid colour
$ oxideav convert "label:Hello world" greeting.png      # text → image
$ oxideav convert "gradient:red-blue" gradient.png

# PDF input + page selectors + Scene-aware fan-out (printf template)
$ oxideav convert -density 300 in.pdf -background white \
                  -alpha remove -alpha off page-%03d.png
$ oxideav convert in.pdf[0] cover.png                   # single-page extraction
$ oxideav convert in.pdf[2-5] excerpt.pdf               # page-range slice (vector preserved)
$ oxideav convert in.pdf      page-%d.svg               # one SVG per page

# 3D scene conversion via oxideav_meta::populate_mesh3d_registry
$ oxideav convert in.obj  out.gltf                      # OBJ → glTF
$ oxideav convert cube.stl cube.obj                     # STL → OBJ
$ oxideav convert scene.gltf scene.glb                  # JSON glTF → binary .glb

# Throughput bench across HW + SW backends (1080p default; --all walks every codec)
$ oxideav bench h264 --duration 3
$ oxideav bench --all --width 1280 --height 720 --side encode

Two global flags help diagnose startup or codec issues:

• --debug enables debug log output to stderr through the log facade. Every crate that emits log::debug! flows through here.
• --no-hwaccel sets CodecPreferences { no_hardware: true, .. } on the pipeline so the resolution layer skips hardware-accelerated factories at dispatch time. The runtime context still registers every backend (oxideav list shows them all regardless of the flag); only the per-route choice is biased toward the pure-Rust path. Useful for byte-deterministic output, regression bisection, or when the hardware encoder produces a worse stream than the pure-Rust path for a specific bitrate target.
• --debug-output FILE redirects debug log output to a file instead of stderr (implies --debug; stderr stays clean).

oxideplay --job <file> runs a job where @display / @out binds to the SDL2 player sink; other outputs (file paths) write to disk in the same run.

First clone? Run ./scripts/update-crates.sh before cargo build. The workspace tracks only the integration glue (oxideav-cli, oxideplay, oxideav-tests, the oxideav facade, the oxideav-meta aggregator); every per-format codec lives in its own OxideAV/oxideav{,-*} GitHub repo and must be cloned into crates/ first. cargo build on a bare checkout fails with failed to load manifest for workspace member until you do.

git clone https://github.com/OxideAV/oxideav-workspace.git
cd oxideav-workspace

gh auth login                 # one-time: update-crates.sh uses gh API to list siblings
./scripts/update-crates.sh     # populates crates/ with every OxideAV/oxideav{,-*} repo

cargo build --workspace
cargo test --workspace

The oxideav binary is produced by the oxideav-cli crate:

cargo run -p oxideav-cli -- --help

Every per-format codec — plus oxideav (facade) and oxideav-meta (aggregator) — lives in its own OxideAV/oxideav{,-*} repository. The root Cargo.toml globs crates/* as members and points every [patch.crates-io] entry at those local paths, so once the siblings are cloned the workspace resolves entirely without crates.io round-trips for any oxideav-* dep during local dev or CI.

• scripts/update-crates.sh — clones every missing OxideAV sibling AND fast-forwards already-cloned siblings to upstream tip via a single GraphQL call. Skips siblings whose upstream is already an ancestor of local HEAD and refuses to fast-forward when local commits have diverged, so in-progress work is preserved. Idempotent; safe to re-run.

./scripts/update-crates.sh    # clone + fast-forward all OxideAV crates

CI runs update-crates.sh at the top of each job (see .github/workflows/ci.yml), so no crates.io resolution is needed there either — the workspace builds whether or not a given crate has been published yet.

.gitignore hides the cloned crate working copies so git status in this repo only shows changes to the native members (oxideav-cli, oxideplay, oxideav-tests). Changes inside a cloned crate are committed against that crate's own repo, not this one.

MIT — see LICENSE. Copyright © 2026 Karpelès Lab Inc.