vidr

Where the work happens

• Hardware codecs: NVDEC and NVENC on NVIDIA, and Vulkan Video, through numr's CUDA and WebGPU backends.
• Native libraries: CPU H.264 wraps OpenH264, and CPU AV1 decode wraps libdav1d. Both are C or C++ code that Rust calls.
• Rust: CPU HEVC decode, CPU VP9 decode, and CPU AV1 encode (through rav1r) run in Rust.
• Containers: MP4, MOV, Matroska, and WebM go through containr.

Not supported yet

• VA-API, and any AMD or Intel GPU run of Vulkan Video.
• H.264 on the CPU above Baseline, and any CPU HEVC encode.
• VP9 encode, on any path.
• Vulkan Video AV1 encode. It is written and has never run on a GPU.
• Fragmented MP4 input, HDR, interlaced video, and a filter graph.

Scope and Refusals hold the full lists.

Install

cargo add vidr --features dav1d,mp4

dav1d needs libdav1d 1.3.0 or newer, found through pkg-config. For a runnable library example, see crates/vidr/examples/hevc_decode.rs. Run it with cargo run --release -p vidr --features cpu-hevc --example hevc_decode -- FILE.h265.

Status

In development. See Build.

Decode

All paths are 4:2:0.

Encode

All paths are 4:2:0.

Vulkan Video encode uses one previous frame as the reference, and an IDR picture at gop_length. It refuses B-frames by name.

What has run

All of this ran on one NVIDIA GPU with NVIDIA's driver. No AMD or Intel GPU has run any of it.

Limits of the Vulkan Video runs:

• Streams past a driver limit, and AV1 monochrome, are refused by name.
• Only one driver mode has run: reference and output pictures sharing one image.
• No validation layer has run.

Times are wall-clock. --from-upscaled also ran on WebGPU, with Vulkan decode and a CPU encoder.

Also working

AGENTS.md holds the full implemented-vs-roadmap table.

Crates

vidr-remaster

vidr-remaster runs a restoration model over a whole video, resizes it, and encodes it. One command writes one output.

Build

Cargo fetches numr, boostr, containr, and rav1r from crates.io.

Pick one row, then run cargo build --release -p vidr-remaster --features <features>.

• CPU codecs. A CPU build holds only the codecs its features name. Add cpu-hevc, cpu-vp9, or openh264 to read other sources. See CPU codecs.
• Mixed builds. Add a CPU codec to a hardware build to cover what the hardware leaves out.
• Incomplete builds. A build with no container, decoder, or encoder reports which features it lacks.

Run

Put the model directories under one root, named as in Models. Pass the root with --models-dir, or set VIDR_MODELS_DIR.

# NVIDIA or Vulkan Video build
target/release/vidr-remaster clip.mp4 --model fast --models-dir ~/models

# No-GPU build: no CPU HEVC encoder exists, so pass --codec av1
target/release/vidr-remaster clip.mp4 --model fast --models-dir ~/models --codec av1

The default --model is purevision, and its licence forbids commercial use. See Models.

The output is clip.fast.restored.mp4 beside the source. It keeps the source's frame count, frame timing, last-frame duration, rotation, and aspect ratio. Audio, text subtitles, chapters, and metadata copy with no transcode. A mismatch in the output check is an error, and no output publishes.

Flags

--resolution sets the shorter edge. auto takes the largest standard edge at or below the source's. The shorter edge never falls below 480.

Reusing an earlier output

Without --force-ai or --from-upscaled, a run looks beside the source for <stem>.<model>.2x and <stem>.<model>.restored, .mp4 or .mkv.

Execution

How auto chooses:

• Order. CUDA, then WebGPU, then the CPU. A hardware codec comes before a CPU codec.
• Missing library or device. auto falls through, with the reason in the report.
• Hardware refusal. auto falls through. This covers H.264 slice groups, data partitioning, a frame_num gap, field coding, and bit depth.
• Stalled GPU queue. The run ends. The error names the stall.

Other choices:

• Explicit hardware codec. --decoder nvdec, --decoder vulkan, --encoder nvenc, or --encoder vulkan never falls through. The error names what is missing.
• Pair outside the table. The run is refused. The error names both sides and the pair that works.

The output check decodes the output, in this order:

1. The run's decoder, when it reads the output codec.
2. The runtime's hardware decoder.
3. The CPU decoder of that codec.

With no such decoder, the run stops before any work.

A CPU codec on any runtime copies each frame through host memory. A run states its copies on one line of stdout.

report.json holds frame_path:

• the runtime
• each codec and route
• the output check's decoder
• the host copies of the encode pass and of the scans
• why each part was chosen

Models

Each directory under the model root holds one .pth file.

The purevision licence forbids commercial use and requires share-alike. The default model is purevision, so pass --model for commercial work. A run's report states this notice. A missing model's error names the expected path and the download URL. The command downloads nothing.

Refusals

Each refusal ends the run with exit code 1 and leaves no output.

The source

The output

Vulkan Video encode

Vulkan Video decode

Use another decoder for every row. A further option appears where one exists.

Results

The first Ctrl-C, SIGTERM, or SIGHUP asks the run to stop at the next frame. A second one removes the temporary output and ends the process.

report.json goes under $XDG_STATE_HOME/vidr-remaster/upscale-<run id>/, else ~/.local/state. Every run past validation writes one.

CPU codecs

A CPU codec works in host memory, so each frame takes one copy through it. The run report states the copy. In library code, FrameRoute on the decoder or encoder declares it.

Every feature here is off by default. vidr-remaster has a feature of the same name for each codec. Select the codec with --decoder cpu, --encoder cpu, or auto.

cpu-av1-asm needs NASM 2.15 or newer on x86_64, or a C compiler on aarch64.

Shipping a binary

These notes state what a binary distribution needs. They are not legal advice.

• rav1r. rav1r is a fork of rav1e, under the BSD-2-Clause licence and the Alliance for Open Media Patent License 1.0. rav1r's PATENTS file holds the patent licence. Section 1.3 ends it for a licensee that sues over an Implementation, with two stated exceptions.
• Notices. vidr-remaster --notices prints the text of each codec in the build. crates/vidr-remaster/notices/ holds each text unchanged, and the crate package includes that directory.
• rusty_vp9. It stays pinned to one release. CONTRIBUTING.md holds the libvpx conformance run.

Scope

These are planned, and none of them works yet.

Minimum Rust version

1.95.

Contributing

Contributions are welcome. See CONTRIBUTING.md for conventions and checks.

Questions and design discussion happen on Discord.

License

Licensed under Apache-2.0. See LICENSE.