Author: Michael Lauzon qdrv2026@gmail.com

Version: 1.0.0 (First Public Release)
Licence: GNU General Public Licence v2.0 or later (GPLv2+)
Language: Rust (edition = "2024", rust-version = "1.96.0")

QDRV (Quantum Dynamic Range Video) is an open, floating-point dynamic-range video format and toolchain — designed as a successor to integer HDR (HDR10, HDR10+) and to proprietary Dolby Vision packaging. It has two operational tiers:

• .qdrv64 mastering tier (Float64 linear-light RGB)
• .qdrv32 delivery tier (Float32 PQ RGB at API boundary, AV1-compressed payloads)

The "Quantum" in the name refers to the fine perceptual quantisation steps of the format's signal domain — the SMPTE ST 2084 Perceptual Quantizer (PQ) — not to quantum computing.

QDRV itself is specified and implemented here as a fully open, royalty-free format and tooling stack. Unlike branded HDR10-family ecosystem variants and Dolby Vision packaging programmes, which may impose separate trademark, certification, or licensing requirements, the core QDRV format does not require proprietary programme participation.

QDRV exists to address a recurring gap in floating-point video mastering and delivery work: teams often need a format that is mathematically transparent enough for mastering and validation, while still producing delivery artefacts that can interoperate with practical downstream systems. Existing HDR pipelines — including HDR10, HDR10+, and Dolby Vision packaging — force an early compromise between precision, observability, and interchange because they quantise to integer code values before the colourist has finished decision-making. QDRV is intended to keep precision and observability concerns explicit at every stage, rather than hiding them behind opaque integer-domain processing assumptions.

The project follows an implementation-first documentation style. In practical terms, that means this README and companion docs describe behaviour that is currently implemented, tested, and validated in this repository, not aspirational roadmap claims. This is deliberate, because predictability and auditability are more useful than broad promises when teams are integrating format tooling into CI, verification, or production pre-flight checks.

• Overview and Goals
• Key Features and Capabilities
• Architecture and Crate Map
• Format and Version Compatibility Matrix
• Installation and Prerequisites
• CLI Usage
• Conformance and Test Vectors
• Interoperability, DV Adapter Boundary, and Loss Reporting
• ACES OpenEXR Export
• Deterministic Mode and Fidelity Contracts
• Performance Notes
• Limitations and Non-Goals
• Troubleshooting
• Development Workflow
• Docs Map
• Licence

QDRV aims to provide a practical, open floating-point video workflow built on public standards (Rec. 2100 / Rec. 2020, SMPTE ST 2084, SMPTE ST 2094 framework) while preserving implementation clarity and deterministic validation paths. The immediate problem space is not only "store dynamic-range frames at higher precision than integer HDR formats allow", but also "make conversion, metadata decisions, and quality gates inspectable enough that engineers can reason about them under real release pressure".

The two-tier model reflects that split of responsibilities. .qdrv64 is the high-precision mastering tier, where preserving intent and analytical headroom is more important than bit-rate efficiency. .qdrv32 is the delivery-facing tier, where the data contract becomes PQ-at-boundary plus compressed payloads suitable for practical exchange and downstream processing. Keeping both tiers first-class in one toolchain reduces hidden format jumps and simplifies traceability between source and delivery outputs.

The design philosophy is conservative and explicit: when there is a trade-off between permissive behaviour and predictable behaviour, QDRV generally chooses predictable behaviour and surfaces why. This is visible in strict version checks, schema enforcement, deterministic options, and machine-readable loss reporting. The cost of that choice is that some workflows are intentionally less permissive than ad hoc scripts, but the benefit is lower ambiguity in CI and operator tooling.

Current goals in this repository:

1. Preserve high-precision mastering data in .qdrv64.
2. Produce interoperable delivery content in .qdrv32.
3. Keep read/write and metadata compatibility rules explicit.
4. Support reproducible engineering workflows (conformance, manifest signing, fidelity contracts, interop reporting).

The feature set is organised around operational reliability rather than one-off conversions. Most commands and APIs are designed to be scriptable, machine-checkable, and clear about degradation boundaries, because those qualities matter most when integrating floating-point video processing into automated pipelines.

Another guiding choice is to keep metadata and container evolution visible instead of implicit. That is why compatibility rules are encoded directly in read/write paths and schema validation, and why interop export includes explicit loss semantics. This can feel stricter than "best effort" tools, but it gives teams a dependable baseline for reproducibility.

• Two-tier floating-point pipeline — Float64 linear-light mastering (.qdrv64), Float32 PQ delivery (.qdrv32) with AV1 payloads.
• Both BT.2100 transfer functions — SMPTE ST 2084 PQ and Hybrid Log-Gamma (HLG).
• Broad HDR signalling — HDR10 static metadata, HDR10+ profiles, and open Dolby Vision profile signalling (proprietary RPU left to a licensed adapter).
• Display-target tone mapping — LED-LCD/OLED panels and the VESA DisplayHDR 400–1400 / True Black 400–600 tiers.
• Per-region & 360°/immersive tone mapping — rectilinear and spherical regions (equirectangular / cubemap / EAC).
• Open Dynamic Metadata v2 — per-frame metadata carried in-bitstream as ITU-T T.35 AV1 OBUs, surviving any container.
• Public-key & post-quantum signing — HMAC-SHA256 and FIPS 204 ML-DSA (post-quantum) signatures on metadata manifests, an additive QSIG container trailer, and signed delivery AV1 stream manifests with per-frame Merkle inclusion proofs that survive muxing; verify-only helpers in wasm builds, built-in default keys fail closed unless opted in.
• Standards-based AV1 muxing — progressive/fragmented MP4, CMAF (DASH/HLS), IVF, raw OBU, with explicit loss reporting.
• Streaming, deterministic, contract-gated — memory-bounded reader, pinned deterministic conversion, PSNR/SSIM/ΔE/VMAF-HDR gates.
• In-browser playback (experimental) — codec-free qdrv-decode-wasm via WebCodecs/AVIF + WebGPU.

QDRV separates mastering from delivery so each stage keeps the precision it actually needs. The mastering tier (.qdrv64) stores Float64 linear-light RGB — enough analytical headroom to grade, validate, and round-trip without quantisation creeping into decision-making. The delivery tier (.qdrv32) carries Float32 PQ RGB at the API boundary with AV1-compressed payloads, so output stays compact and exchangeable. Keeping both tiers first-class in one toolchain removes the hidden format jumps that usually sit between source and delivery.

Container and schema evolution is handled as a compatibility contract rather than best-effort guessing. QDRV reads both v1 and v2 containers, writes v2 by default, and can emit v1 on request for legacy consumers. Metadata rules are enforced at read/write time — static and dynamic schema versions must match, v2 must carry open_dynamic_v2, and v1 must not — so migrations are deliberate and ambiguous combinations fail loudly instead of drifting silently.

Beyond the global per-frame curve, QDRV can apply tone-mapping curves to specific regions of a frame. Flat content uses rectilinear object regions (normalised bounding boxes); 360°/immersive content uses spherical regions located by azimuth and elevation, interpreted under an equirectangular, cubemap, or equi-angular cubemap projection. Overlaps resolve by priority, longitude wraps across the antimeridian, and latitude is pole-bounded — so a bright window or a forward-facing subject can be graded independently of the rest of the scene.

QDRV's core covers both ITU-R BT.2100 transfer functions — SMPTE ST 2084 PQ and Hybrid Log-Gamma (HLG) — exposed through the pq and hlg commands. Alongside the existing HDR10+ export, the toolchain emits HDR10 static metadata (hdr10) and open Dolby Vision profile signalling (dolby-vision), with the proprietary DV RPU left to a licensed adapter. For playback adaptation, inspect --target-display renders toward named display targets — nominal LED-LCD and OLED panels, and the VESA DisplayHDR 400–1400 and DisplayHDR True Black 400–600 certification tiers — which feed the tone mapper's luminance envelope.

QdrvStreamReader decodes frame-by-frame without materialising the whole file, keeping inspection, conformance, and interop work bounded on large inputs. The reader and writer enforce strict size limits before allocating (metadata, frame payloads, frame area, frame count), and the AV1 decode path reuses decoder state and scratch buffers to keep allocation churn low.

The qdrv-decode-wasm crate compiles QDRV's metadata parsing and tone mapping to WebAssembly so a delivery-tier .qdrv32 file (or a qdrv mux --format ivf stream) can play in a browser with no installation. The crate is codec-free by design - the browser supplies the AV1 decode through WebCodecs VideoDecoder for IVF streams and through AVIF still-image decoding for direct .qdrv32 payloads - while the wasm core validates the container, recovers the per-frame metadata, and tone-maps each frame, preferring a WebGPU compute shader with a wasm CPU fallback. With --features public-key-verify, the same wasm crate adds verify-only public-key helpers for signed stream manifests; no secret-key generation or signing code is exposed to browser builds. A runnable demonstration page lives in examples/web/; the path is experimental and depends on the browser's AV1 Professional profile (12-bit 4:4:4) support, with a clearly labelled metadata preview when that support is absent.

qdrv convert --deterministic pins the processing choices (including AV1 threading) that otherwise vary run-to-run, so outputs are comparable across machines and CI runs. Fidelity contracts turn quality intent into objective pass/fail gates: psnr_db_min, ssim_min, delta_e_max, and optional vmaf_hdr_min are checked during conversion and conformance, and a contract failure aborts the operation rather than shipping a silent regression.

A small checked-in vector corpus with pinned SHA-256 hashes gives fast regression detection on every change, while conformance-generate-open / conformance-run build and replay larger corpora for release-gate coverage.

Authenticity is first-class and quantum-ready. Metadata manifests can be HMAC-SHA256 signed and can also carry FIPS 204 ML-DSA post-quantum public-key signatures. Whole QDRV containers can carry an additive QSIG trailer, and delivery AV1 streams can carry a signed stream manifest plus per-frame Merkle inclusion proofs inside QDRV T.35 metadata OBUs so authenticity survives muxing into MP4, fMP4, CMAF, IVF, raw OBU, and single-frame AVIF. Built-in public default keys fail closed: signing or verifying against them is never treated as authenticity evidence unless explicitly opted in.

qdrv export-interop emits HDR10, HDR10+, and DV-compatible artefacts alongside machine-readable loss reports that enumerate exactly what was dropped, approximated, or unsupported per target — interop is a reported trade-off, not a silent success/failure. The muxer writes standards-based AV1 into progressive/fragmented MP4, CMAF, IVF, and raw OBU (with HDR colr nclx signalling and large-payload stco/co64 + mdat largesize handling), so output interoperates with the existing AV1 ecosystem (ffmpeg, dav1d, GPAC MP4Box, Shaka Packager) rather than requiring QDRV-specific players.

QDRV is split into focused crates so that colour science, metadata policy, container IO, codecs, and operator tooling evolve with clearer boundaries. The intent is architectural clarity rather than abstraction for its own sake: each crate corresponds to a distinct concern that frequently changes at a different pace in real projects.

This separation has practical trade-offs. It improves auditability and test targeting (for example, validating schema logic independently from codec behaviour), but it also requires stronger API contracts across crate boundaries and slightly more coordination when changing cross-cutting behaviour. The repository chooses that trade-off because explicit dependency boundaries reduce accidental coupling over time.

High-level flow:

1. Mastering ingest or generation (.qdrv64)
2. Optional conversion (qdrv convert) to delivery (.qdrv32)
3. Inspect / object-metadata authoring / export interop / conformance / manifest workflows

Workspace crates:

The repository also ships a test-vectors/ data directory holding the checked-in deterministic vector corpus and its expected SHA-256 hashes (consumed by qdrv-io's integration tests). It is not a Cargo crate.

The crate map also reflects an interoperability strategy: qdrv-meta defines and validates metadata semantics, qdrv-io enforces container contracts, and qdrv-tool exposes those decisions through operator-visible commands. That layering helps ensure that policy and compatibility decisions are not hidden in CLI glue code alone.

Container and schema evolution is treated as a compatibility management problem, not just a file-format problem. QDRV currently supports reading both v1 and v2 containers, writes v2 by default, and permits explicit v1 output for compatibility workflows. This lets teams move forward incrementally while still serving legacy consumers where required.

The v1/v2 behaviour is intentionally strict at boundaries. Old or unknown versions are rejected rather than guessed, and future versions are rejected rather than interpreted optimistically. That decision favours deterministic failure modes: operators can identify mismatch causes early, instead of accepting silent behaviour drift that is difficult to diagnose later.

Schema handling follows the same approach. v2 containers support both metadata schema v1 and v2 to provide a transition path, while v1 containers remain locked to schema v1 to avoid ambiguous interpretation. This distinction keeps compatibility behaviour explicit for integrators who need predictable migration planning.

Additional metadata rules enforced:

• Static/dynamic metadata_schema_version values must match.
• Schema v2 (METADATA_SCHEMA_V2) must include open_dynamic_v2.
• Schema v1 must not include open_dynamic_v2.

Taken together, these rules form a practical evolution contract: you can migrate format versions deliberately, but combinations that would blur semantic meaning are rejected early. That makes compatibility failures louder, but it substantially reduces ambiguity during long-lived deployment transitions.

The build requirements are intentionally conventional for Rust projects with native codec dependencies. Most installation issues come from system package discovery (pkg-config and dav1d) rather than Rust itself, so validating native toolchain visibility early is usually the fastest path to a clean setup.

• Rust stable 1.96.0 or newer
• Cargo (bundled with Rust)
• C toolchain suitable for native crates
• nasm (recommended for AV1 build performance)
• dav1d development libraries discoverable by pkg-config

Recommended path is MSVC Rust toolchain plus MSYS2 packages for dav1d and pkg-config.

Typical requirements:

• Visual Studio C++ Build Tools (or full Visual Studio with C++ workload)
• MSYS2 UCRT toolchain packages (for example dav1d, pkgconf, nasm)
• pkg-config available in PATH
• If detection fails, set PKG_CONFIG_PATH to the folder containing dav1d.pc

If your environment already resolves dav1d through pkg-config, no additional configuration is needed.

Install Rust, pkg-config, nasm, and libdav1d-dev (package names vary by distro).

Install Rust plus nasm, pkg-config, and dav1d (for example via Homebrew).

# Build all crates
cargo build --workspace

# Install CLI binary (`qdrv`)
cargo install --path qdrv-tool

Optional: enable ZFP mastering compression support.

cargo build --workspace --features zfp

The CLI is designed as an operator surface over crate-level capabilities: inspection, conversion, metadata export, interop analysis, manifest handling, and conformance execution. Commands are structured so they can be used interactively during debugging and non-interactively in CI pipelines.

Where possible, command outputs are shaped for downstream automation (for example JSON reports and deterministic vector workflows) rather than only human-readable logs. That design helps teams move from exploratory usage to repeatable validation without rewriting tooling around the CLI.

The qdrv binary groups its commands by workflow stage. Each is summarised below; runnable examples follow in Representative commands.

• info — print a summary of the build, format, and tier defaults.
• pq {--nits <NITS> | --pq <PQ>} — convert between nits and PQ signal values (the two flags are mutually exclusive).
• hlg {--scene <E> | --signal <S>} [--peak-nits <NITS>] — convert between normalised scene-linear light and ITU-R BT.2100 HLG signal values; with --signal --peak-nits, also report the display luminance via the HLG OOTF.
• inspect <file> [--render-frame-time-ms <MS>] [--target-display <PRESET>] — report the static and per-frame dynamic metadata of a .qdrv file, with an optional render preview toward a named display target (led-hdr, oled-hdr, or a VESA display-hdr400–1400 / display-hdr-true-black400–600 tier).
• probe-stream <input> — read the per-frame dynamic metadata back out of an exported stream (.mp4/fMP4/CMAF, .ivf, or raw .obu).

• write-test <output> — generate a deterministic sample .qdrv32/.qdrv64 fixture for testing and demos.
• convert <input> <output> — transcode a mastering-tier .qdrv64 into a delivery-tier .qdrv32; this is where deterministic mode, fidelity contracts, and metadata-v2 policy apply.

• aces-export <input> <output_dir> — export a delivery or mastering QDRV stream as a numbered OpenEXR sequence through the ACES2065-1 interchange path or through the ACES RRT/ODT target selected by --target {aces2065-1|rec709-100nit|rec2020-1000nit|rec2020-4000nit}.

• meta-static, meta-dynamic, meta-dynamic-v2 — emit example static and dynamic metadata documents (including the Open Dynamic Metadata v2 shape).
• object-motion <input> <output> --region-id <ID> — add bounded static, translated, or piecewise-linear motion to a rectilinear ObjectMeta region.
• hdr10 <input> <output> — export HDR10 static metadata (SMPTE ST 2086 mdcv + CTA-861.3 clli) as JSON.
• hdr10plus <input> <output> — export HDR10+ profile JSON in basic (default), advanced, adaptive, or gaming mode.
• dolby-vision <input> <output> [--level <0-13>] — export the open Dolby Vision compatibility signalling (single-layer AV1 Profile 10.1, HDR10-compatible base). The proprietary DV RPU is never generated.
• export-interop <input> <output_dir> — emit the HDR10 / HDR10+ / DV-compatible bundle plus machine-readable loss and adapter reports.

• mux <input.qdrv32> <output> [--format {mp4|fmp4|cmaf|ivf|obu}] — re-encode a delivery stream into a standards-based AV1 container: progressive MP4 (default), fragmented MP4 / CMAF for DASH/HLS, or IVF / raw OBU elementary streams for codec tooling.
• still <input.qdrv32|input.qdrv64> <output.avif> [--frame-index <N>] — export one QDRV frame as an AVIF still image with HDR colr nclx signalling and a QDRV JSON metadata item.

• manifest-keygen --secret-key-out <path> --public-key-out <path> - generate a hex-encoded ML-DSA keypair for public-key manifest, container, and stream signatures.
• manifest-sign <input> <output> {--key <key> | --key-file <path>} [--secret-key-file <path>] [--deterministic] [--signer <signer>] - HMAC-SHA256-sign a metadata document and optionally add an ML-DSA public-key block.
• manifest-verify <input> <manifest> {--key <key> | --key-file <path>} [--public-key-file <path> | --expected-fingerprint <hex>] [--require-public-key] - verify HMAC and, when present or required, the public-key block.
• sign <input.qdrv> <output.qdrv> --secret-key-file <path> {--key <key> | --key-file <path>} [--bitstream] [--deterministic] - append a QSIG container trailer and optionally embed a signed AV1 stream manifest plus per-frame inclusion proofs for delivery-tier streams.
• verify <input> {--key <key> | --key-file <path>} [--public-key-file <path> | --expected-fingerprint <hex>] [--require-public-key] - verify .qdrv container signatures and signed delivery bitstreams in QDRV, MP4/fMP4/CMAF, IVF, raw OBU, or AVIF.
• conformance-generate-open <output_dir> {--key <key> | --key-file <path> | --allow-public-default-key} [--secret-key-file <path>] - build a signed conformance corpus with optional deterministic public-key manifest signatures.
• conformance-run <manifest> <output_dir> {--key <key> | --key-file <path>} [--public-key-file <path> | --expected-fingerprint <hex>] - replay and validate a conformance corpus.

Manifest, container signing, verification, and conformance commands accept the HMAC signing key from three mutually exclusive sources, listed in precedence-friendly order:

1. QDRV_SIGNING_KEY environment variable — preferred for CI/automation; never appears in process listings or shell history.
2. --key-file <path> — preferred for production use with on-disk key files; reads raw bytes (no UTF-8 requirement) and strips one trailing \r?\n.
3. --key <value> — convenient for ad-hoc local use; avoid in shared shells, CI logs, or anywhere ps/history could capture the argument.

conformance-generate-open can sign with a built-in public default key so the open-vectors workflow is reproducible across machines, but the default key path is fail-closed: it only fires when the operator explicitly passes --allow-public-default-key and no --key, QDRV_SIGNING_KEY, or --key-file value is supplied. Without the opt-in flag the command fails with a message listing all four ways to supply a key. Empty values from any source (--key "", QDRV_SIGNING_KEY="") are treated as unset for the same fail-closed check. All other commands require one of the three explicit sources.

Important: signatures produced with the built-in default key are not authenticity evidence. They exist so the open-vectors corpus reproduces byte-for-byte across machines that have not been configured with a private key. Production callers must supply their own key via QDRV_SIGNING_KEY or --key-file.

Public-key signing uses ML-DSA key material generated by manifest-keygen. Store the --secret-key-out file as private signing material and distribute the --public-key-out file or its SHA-256 fingerprint for verification. The CLI signing default is ml-dsa-65; ml-dsa-87 is selectable with --algorithm ml-dsa-87. --deterministic makes ML-DSA output byte-reproducible for test vectors; the default signing path uses OS randomness for hedged signing.

Verification without --public-key-file, --expected-fingerprint, or --require-public-key reports a valid public-key block as unpinned. That is useful for corruption detection but is not production authenticity evidence. Production workflows should pin the public key or expected fingerprint and use --require-public-key.

Quantum resistance: the HMAC layer uses HMAC-SHA256, a symmetric construction that is not known to be materially weakened by quantum algorithms; Grover's search at most halves the effective key strength, leaving an ample security margin with a 256-bit key. Public-key authenticity uses FIPS 204 ML-DSA rather than a classical signature scheme.

hdr10plus mode options: --mode basic (default), --mode advanced, --mode adaptive, --mode gaming (legacy --advanced remains supported).

# Inspect format summary
qdrv info

# Generate test files
qdrv write-test sample.qdrv32 --width 256 --height 64 --frames 1
qdrv write-test sample.qdrv64 --mastering --mastering-codec fpzip
qdrv write-test sample-v1.qdrv32 --container-version v1

# Mastering -> delivery conversion
qdrv convert master.qdrv64 delivery.qdrv32 --quantizer 40 --speed 6

# Export an ACES/OpenEXR image sequence. ACES2065-1 is scene-linear interchange;
# the Rec.709 and Rec.2020 targets apply the ACES RRT/ODT display transform.
qdrv aces-export delivery.qdrv32 aces-out --target aces2065-1 --reference-white-nits 203 --prefix shot --start-number 1
qdrv aces-export master.qdrv64 rec709-out --target rec709-100nit --prefix grade

# Export HDR10+ profile metadata (basic/advanced/adaptive/gaming)
qdrv hdr10plus delivery.qdrv32 hdr10plus-basic.json --mode basic
qdrv hdr10plus delivery.qdrv32 hdr10plus-adaptive.json --mode adaptive
qdrv hdr10plus delivery.qdrv32 hdr10plus-gaming.json --mode gaming

# Deterministic conversion + metadata v2 policy tags
qdrv convert master.qdrv64 delivery.qdrv32 --deterministic --metadata-v2 --ambient-lux 120 --display-model oled --frame-time-ms 8.3

# Compatibility output in v1 container
qdrv convert master.qdrv64 delivery-v1.qdrv32 --container-version v1

# Export HDR10 / HDR10+ / DV-compatible interop bundle
qdrv export-interop delivery.qdrv32 out/

# Mux a delivery-tier .qdrv32 into a standards-compliant container (AV1 + HDR `colr nclx`).
# --format selects the target: mp4 (default, progressive), fmp4/cmaf (fragmented, keyframe-segmented
# for DASH/HLS streaming), or ivf/obu (AV1 elementary streams for codec tooling).
qdrv mux delivery.qdrv32 delivery.mp4 --frame-rate 24 --quantizer 40 --speed 6 --keyframe-interval 120
qdrv mux delivery.qdrv32 delivery.cmaf --format cmaf --keyframe-interval 48

# Export one delivery or mastering frame as AVIF. Mastering inputs are transcoded
# through the delivery path before the AV1 still-image encode.
qdrv still delivery.qdrv32 frame.avif --frame-index 0 --quantizer 40 --speed 6
qdrv still master.qdrv64 frame-from-master.avif --frame-index 0 --deterministic

# Add bounded object motion to a rectilinear ObjectMeta JSON document.
qdrv object-motion objectmeta.json objectmeta.motion.json --region-id 7 --kind translate --frame-count 12 --to-x 0.45 --to-y 0.20
qdrv object-motion objectmeta.json objectmeta.path.json --region-id 7 --kind piecewise-linear --keyframe 0:0:0 --keyframe 12:0.1:0.0 --keyframe 24:0.05:0.08

# Read the embedded per-frame dynamic metadata back out of an exported stream.
# QDRV carries it in-bitstream as ITU-T T.35 AV1 metadata OBUs, so it survives any container.
qdrv probe-stream delivery.cmaf

# Public-key manifest/container workflow.
qdrv manifest-keygen --secret-key-out qdrv.ml-dsa.seed.hex --public-key-out qdrv.ml-dsa.pub.hex
qdrv manifest-sign meta.json meta.manifest.json \
    --key-file /etc/qdrv/signing.key \
    --secret-key-file qdrv.ml-dsa.seed.hex \
    --deterministic \
    --signer qdrv-tool
qdrv manifest-verify meta.json meta.manifest.json \
    --key-file /etc/qdrv/signing.key \
    --public-key-file qdrv.ml-dsa.pub.hex \
    --require-public-key

# Sign and verify a QDRV container. Add --bitstream for delivery-tier AV1
# signatures that survive qdrv mux and single-frame AVIF wrapping.
qdrv sign delivery.qdrv32 delivery.signed.qdrv32 \
    --secret-key-file qdrv.ml-dsa.seed.hex \
    --key-file /etc/qdrv/signing.key \
    --bitstream \
    --deterministic
qdrv verify delivery.signed.qdrv32 \
    --key-file /etc/qdrv/signing.key \
    --public-key-file qdrv.ml-dsa.pub.hex \
    --require-public-key

# Conformance generate: production callers should supply their own HMAC and
# optional ML-DSA key.
qdrv conformance-generate-open conformance/ \
    --key-file /etc/qdrv/signing.key \
    --secret-key-file qdrv.ml-dsa.seed.hex
qdrv conformance-run conformance/conformance-manifest.json conformance-results/ \
    --key-file /etc/qdrv/signing.key \
    --public-key-file qdrv.ml-dsa.pub.hex

# Open-vectors reproducible run uses the built-in public default HMAC key
# (signatures are NOT authenticity evidence; opt-in is required):
qdrv conformance-generate-open conformance-open/ --allow-public-default-key

The streams qdrv mux produces are standard AV1 with no QDRV-proprietary container framing — progressive ISOBMFF (mp4), fragmented MP4 / CMAF (fmp4/cmaf), and AV1 elementary streams (ivf/obu) — so they interoperate with the existing AV1 ecosystem rather than requiring QDRV-specific players. The per-frame QDRV dynamic metadata rides inside the AV1 bitstream as ITU-T T.35 metadata OBUs, so it travels with the stream through demuxing and repackaging untouched. qdrv still emits a single-image AVIF file with avif as the major brand and mif1, miaf, and avis as compatible brands. The primary item is an AV1 image item with the same HDR colr nclx signalling; QDRV static and dynamic metadata are preserved in an application/qdrv+json MIME metadata item linked to the primary item from the AVIF meta box.

When a delivery-tier QDRV file has been signed with qdrv sign --bitstream, qdrv mux preserves the exact signed AV1 temporal-unit bytes instead of re-encoding them, so the stream signature verifies after MP4, fMP4, CMAF, IVF, and raw OBU export, including the per-frame inclusion proofs. qdrv still preserves the signed AV1 payload for single-frame delivery inputs when wrapping as AVIF.

Observed acceptance against standard tooling:

• ffmpeg / ffprobe decode and identify every format as AV1 (Professional profile, 12-bit 4:4:4, BT.2020 primaries, SMPTE ST 2084 transfer).
• dav1d decodes the IVF and raw-OBU elementary streams. The raw .obu is a low-overhead (size-delimited) OBU stream, so ffmpeg auto-detects it or decodes it with -f obu; the Annex-B -f av1 demuxer does not apply.
• GPAC MP4Box parses the MP4, fMP4, and CMAF outputs (av01.2.04M.00; the CMAF output carries the cmfc brand).
• GPAC MP4Box parses AVIF still-image output, reports the primary av01 image item and the application/qdrv+json metadata item, and can dump both items for independent inspection.
• dav1d decodes the AV1 image item dumped from AVIF still-image output.
• Shaka Packager repackages the output into MPEG-DASH (.mpd) and HLS (.m3u8) without re-encoding.

These are manual interoperability checks against generated output, not part of the automated test gates.

Conformance support exists to answer a practical question: can the same content and pipeline produce repeatable outcomes across time, environments, and dependency updates? Checked-in vectors provide a stable baseline that can be validated in routine CI runs before teams spend effort on deeper investigation.

The deterministic corpus and manifest-driven workflows are intentionally complementary. Fixed vectors are useful for fast regression detection, while generated conformance corpora are useful for broader scenario coverage when preparing releases or validating environmental changes.

Checked-in deterministic vectors live in test-vectors/:

• ramp-delivery.qdrv32
SHA-256: 2a17a0333260c93476111f162ca8f1e72fc22d745f4cb3bd33e47c3fae548c79
• ramp-mastering.qdrv64
SHA-256: 0ea98a2e05db07427c9189b30281d76c20ff87670d3c768785ffd7e99e697498

Core validation commands:

# Static/build checks
cargo check --workspace

# Full workspace tests
cargo test --workspace

# Checked-in vector validation
cargo test -p qdrv-io --test checked_in_vectors

# Optional fresh conformance corpus with production-owned HMAC and ML-DSA keys.
qdrv manifest-keygen --secret-key-out scratch/qdrv.ml-dsa.seed.hex --public-key-out scratch/qdrv.ml-dsa.pub.hex
qdrv conformance-generate-open scratch/conformance \
    --key-file /path/to/hmac.key \
    --secret-key-file scratch/qdrv.ml-dsa.seed.hex
qdrv conformance-run scratch/conformance/conformance-manifest.json scratch/conformance-out \
    --key-file /path/to/hmac.key \
    --public-key-file scratch/qdrv.ml-dsa.pub.hex

# Open-vector reproduction can opt in to the built-in public HMAC key.
# That path is not authenticity evidence.
qdrv conformance-generate-open scratch/conformance-open --allow-public-default-key

In production-oriented workflows, a common pattern is to run checked-in vector validation on every change, then run broader conformance jobs at release gates or dependency bump checkpoints. This balances turnaround time with confidence depth.

Interoperability in QDRV is designed to be explicit about what is preserved, transformed, approximated, or dropped when targeting downstream formats and ecosystems. Rather than presenting interop as a binary success/failure state, QDRV exports structured reports so operators can decide whether the resulting trade-offs are acceptable for their delivery context.

This boundary is particularly important around Dolby Vision-adjacent workflows. The repository provides open, inspectable export paths and reporting, but it does not claim certified proprietary packaging in open code. Keeping this boundary explicit avoids accidental assumptions in production pipelines that require certification-grade artefacts.

qdrv export-interop emits:

• HDR10 raw payload (RGB10LE)
• HDR10+ profile JSON (mode=basic in interop bundle)
• Open DV-compatible sidecar JSON
• Combined loss report JSON
• DV adapter report JSON

The open exporter intentionally reports dropped, approximated, and unsupported fields per target. This is a design feature, not a warning-only path.

qdrv hdr10plus exports profile-aware JSON for basic, advanced, adaptive, and gaming modes. Every export includes a machine-readable compatibility report with strict certification_status: not_certified markers and missing certification capabilities.

Certified Dolby Vision packaging is out of scope for open code in this repository. Optional integration is provided via --dv-tool-cmd placeholders:

• {sidecar}
• {rpu}
• {report}

In practical production use, this means teams can integrate open interop exports as pre-flight artefacts, then hand off to proprietary toolchains where certification or closed packaging is required. The reporting layer is intended to make that hand-off auditable instead of implicit.

qdrv aces-export closes the ACES output side of the workflow. It reads delivery-tier .qdrv32 PQ frames or mastering-tier .qdrv64 linear-nits frames, converts Rec. 2020 RGB into ACES AP0, and writes a numbered OpenEXR sequence through the pure-Rust exr crate. Output files use the same .part.<pid> atomic-replace pattern as other QDRV writers.

Supported targets:

• aces2065-1 — scene-linear ACES AP0 interchange, with no RRT or ODT applied.
• rec709-100nit — ACES RRT plus Rec.709 100 nit dim-surround ODT.
• rec2020-1000nit — ACES v1.3 Rec.2020 ST2084 1000 nit published RRT+ODT transform.
• rec2020-4000nit — ACES v1.3 Rec.2020 ST2084 4000 nit published RRT+ODT transform.

--reference-white-nits defines the absolute QDRV luminance that maps to ACES scene-linear 1.0; it must be positive and finite. --prefix controls the filename stem and is restricted to a filename prefix rather than a path. --start-number sets the first six-digit frame number.

The ACES2065-1 interchange path has regression coverage that writes OpenEXR, reads it back through the same pure-Rust EXR stack, converts back to delivery PQ, and checks QDRV's existing PSNR and DeltaE76 fidelity metrics. Display-rendered Rec.709 and Rec.2020 ODT outputs are intentionally not treated as reversible interchange.

Determinism and fidelity gates exist because many dynamic-range regressions are subtle: they can pass visual spot checks yet fail quality or compatibility expectations over time. QDRV therefore supports deterministic conversion controls and contract-based thresholds so teams can encode quality intent directly into automation.

Deterministic mode is most useful when you need stable comparisons across runs (for example CI, reproducibility investigations, or release sign-off baselines). Fidelity contracts are most useful when you need objective pass/fail criteria rather than manual judgement alone.

Deterministic conversion:

• qdrv convert --deterministic enables stable processing choices (including deterministic AV1 threading configuration and deterministic encode path behaviour).

Fidelity contract enforcement:

• qdrv convert --fidelity-contract <path> enables threshold-based gating.
• Supported contract metrics include psnr_db_min, ssim_min, delta_e_max, and optional vmaf_hdr_min.

VMAF-HDR backend resolution order:

1. External command template via QDRV_VMAF_HDR_CMD
2. ffmpeg/libvmaf autodetection path
3. Deterministic approximation fallback

When enabling vmaf_hdr_min, treat backend selection as an explicit operational decision. If your release process requires high-fidelity scoring from a specific toolchain, configure and validate that backend explicitly.

Surrogate-acceptance opt-in. When neither a QDRV_VMAF_HDR_CMD template nor a working ffmpeg/libvmaf is available, QDRV can score frames with a deterministic in-repo approximation. To prevent a vmaf_hdr_min contract gate from silently passing on the surrogate, the approximation is fail-closed by default: the score is withheld and the contract evaluator reports "metric unavailable", failing the gate. Operators who accept the surrogate explicitly (for example, when running on synthetic fixtures below the libvmaf 33-pixel minimum) must opt in by setting QDRV_VMAF_HDR_ALLOW_APPROX=1 (or true). The acceptance note recorded with each measurement makes the opt-in visible in the fidelity_notes of the conformance summary.

Performance work in QDRV focuses on predictable memory behaviour and safer large-file handling in addition to raw throughput. In practical terms, this means favouring stream-oriented reads, buffer reuse patterns, and allocation guards in hotspots that are common in inspection, conformance, and interop tasks.

• QdrvStreamReader avoids mandatory full-file materialisation in inspect/conformance/interop paths.
• AV1 decode path reuses Av1Decoder state and scratch buffers to reduce allocation churn.
• upsample_420_into supports caller-managed output buffers for reuse-heavy workflows.
• Reader and writer enforce strict size bounds before allocation (metadata, frame payloads, frame area, frame count).
• MP4 mux path handles large file offsets correctly via stco/co64 and mdat largesize logic.

These optimisations are intentionally pragmatic and implementation-oriented. They are meant to reduce avoidable overhead and failure risk in real workloads, not to imply that every pipeline stage is globally optimised for every hardware profile.

QDRV intentionally scopes itself to open, inspectable functionality and explicit compatibility behaviour. Some constraints are technical, while others are governance choices about what can be implemented and validated in an open repository. Being explicit about these limits helps prevent incorrect production assumptions.

Several non-goals also protect implementation clarity. For example, keeping conversion input restricted to mastering-tier data and keeping metadata v2 authoring policy-driven both reduce ambiguous behaviour surfaces. This can feel narrower than general-purpose media tooling, but it makes format and quality contracts easier to reason about and test.

• Open code does not generate certified Dolby Vision bitstreams.
• qdrv convert currently accepts mastering input only (.qdrv64).
• Metadata v2 CLI authoring is policy-driven (--metadata-v2 plus policy flags), not a full arbitrary scene/object editor.
• Mastering-tier (.qdrv64) streams cannot carry delivery-side v2 adaptation policy — the writer rejects DynamicMeta.inverse_tone_mapping_hint, OpenDynamicMetadataV2.adaptation_layer, .ambient_policy, .gaming_profile, and .inverse_tone_mapping_hint on mastering files. Creative-intent v2 fields (scene/object constraints, temporal controls, local tone-map grid) remain allowed on both tiers; only adaptation fields are gated. Mastering files written before this rule was added that happened to carry these fields will fail to load with IoError::InvalidMetadata; regenerate them from source if encountered.
• ZFP mastering compression is optional and feature-gated (--features zfp).
• High-fidelity VMAF-HDR scoring may require external tooling; deterministic fallback remains available.
• Raw codec mode is intended for tests/diagnostics, not production interchange.

Most setup and usage issues resolve quickly once dependency visibility and compatibility rules are checked explicitly. The list below highlights the most common failure modes and the expected corrective path.

• cannot find library dav1d or pkg-config errors:
  • Ensure dav1d development files are installed.
  • Ensure pkg-config is installed and in PATH.
  • On Windows, ensure your pkg-config environment can resolve dav1d.pc (set PKG_CONFIG_PATH if needed).
• --container-version v1 with --metadata-v2 fails:
  • Expected behaviour; container v1 requires metadata schema v1.
• qdrv convert rejects input as non-mastering:
  • Expected behaviour; input must be a mastering-tier .qdrv64 file.
• Interop output does not include proprietary DV artefacts:
  • Expected without an external --dv-tool-cmd adapter.
• Fidelity contract vmaf_hdr_min backend notes mention fallback:
  • Install/configure external backend tools if you need non-fallback scoring.

A practical local routine is to run quick structural checks first, then full tests, then vector validation, and finally optional conformance generation/runs when broader coverage is needed. This order usually gives fast feedback for everyday changes while still supporting deeper release-oriented validation.

Suggested routine from repository root:

# 1) Build quickly
cargo check --workspace

# 2) Format and lint (workspace lint policy is enforced as hard errors)
cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo clippy --workspace --all-targets --features qdrv-codec/zfp -- -D warnings

# 3) Run tests
cargo test --workspace
cargo test --workspace --features qdrv-codec/zfp
cargo test -p qdrv-meta --features public-key-signatures
cargo test -p qdrv-io --features public-key-signatures
cargo test -p qdrv-codec --features public-key-signatures
cargo test -p qdrv-decode-wasm --features public-key-verify
cargo check -p qdrv-decode --features public-key-verify

# 4) Validate checked-in vectors
cargo test -p qdrv-io --test checked_in_vectors

# 5) Optional production-style conformance run with public-key signatures
qdrv manifest-keygen --secret-key-out scratch/qdrv.ml-dsa.seed.hex --public-key-out scratch/qdrv.ml-dsa.pub.hex
qdrv conformance-generate-open scratch/conformance --key-file /path/to/hmac.key --secret-key-file scratch/qdrv.ml-dsa.seed.hex
qdrv conformance-run scratch/conformance/conformance-manifest.json scratch/conformance-out --key-file /path/to/hmac.key --public-key-file scratch/qdrv.ml-dsa.pub.hex

The workspace lint policy is defined under [workspace.lints] in the root Cargo.toml and is enforced by every member crate via [lints]\nworkspace = true. Run cargo fmt --all -- --check and cargo clippy --workspace --all-targets -- -D warnings (and the same with --features qdrv-codec/zfp) before publishing changes; both must finish warning-free for the project's verification gates to remain green.

Common local tasks:

• Use qdrv write-test to generate deterministic sample fixtures.
• Use qdrv inspect to inspect static and per-frame metadata.
• Use qdrv export-interop to validate downstream conversion and loss-report surfaces.
• Use qdrv sign --bitstream and qdrv verify --require-public-key to test signed delivery artefacts before muxing.

The documents below provide deeper implementation and operational detail than this README. They are useful when you need precise format semantics, container layout, or operational behaviour references.

Primary project documentation:

• docs/QDRV_SPEC.md — implementation-aligned specification profile
• docs/QDRV_TECHNICAL_REFERENCE.md — implementation details and operational behaviour
• docs/ROADMAP.md — proposed future work, ordered by expected operator impact
• test-vectors/README_TEST_VECTORS.md — checked-in corpus details and regeneration commands
• qdrv-decode-wasm/README.md — WebAssembly build design, exported API, and browser integration pipeline
• examples/web/README.md — in-browser playback demo: build, serve, and known limitations

GNU General Public Licence v2.0 or later (GPLv2+).