h4m
A pure Rust HVQM4 1.3/1.5 (.h4m) video decoder with a library and frame
extraction CLI. No dependencies or unsafe code.
Supports I, P, and B pictures, adaptive orthogonal transforms, literal blocks, weighted DC reconstruction, run-length/Huffman coding, half-pixel motion, and 4:2:0, 4:2:2, and 4:4:4 sampling. Audio packets are skipped. Dimensions must be nonzero multiples of eight. Other HVQM versions and chroma layouts are rejected.
Use the library
use ;
use Decoder;
let mut decoder = new?;
println!;
let mut rgb = Vecnew;
while let Some = decoder.next_frame?
# Ok::
Decoder<R: Read> streams the container and reuses its packet and three frame
buffers. Frames arrive in decoding order, which can differ from presentation
order (I0, P3, B1, B2, for example). Use display_index to order frames or
calculate timestamps (index * header.microseconds_per_frame). For playback,
copy/reorder frames in your application. The CLI names frames by presentation index.
VideoDecoder accepts demuxed packets: pass the frame type and display index
separately, and omit the packet's initial four-byte display ID. Start with an I
frame. Decoder instances are independent and can run on separate threads.
Decoder::with_limits and VideoDecoder::with_limits accept Limits; defaults
are 16,777,216 luma pixels and 64 MiB per compressed frame. Malformed data returns
an error; construct a new decoder to continue.
Container body-size metadata is exposed but not enforced, matching the reference;
individual block sizes and frame counts are checked. Trailing data after the
last declared block is left unread.
Extract frames
The default output is frame_0000000000.ppm, etc. --yuv writes one tightly
packed Y/U/V file per frame, using the file's native chroma sampling. Existing
output files are not overwritten. RGB conversion reproduces the reference's
full-range coefficients and truncation; the reference CLI's RGB output supports
only 4:2:0, while this CLI also converts 4:2:2 and 4:4:4 correctly.
Develop and test
Development and CI use stable Rust from Fenix and nixpkgs unstable, pinned in
flake.lock. Update both with nix flake update nixpkgs fenix.
Nix fetches mbcgh/h4m-video-decoder
at the fixed revision 02d66526e62e346c3ef7f92eac49cc07356a2c62
as the reference decoder to test.
To compare a local collection of original movies, including every disc, run:
H4M_ORIGINALS=/path/to/extracted/discs
This recursively discovers every .h4m file (case insensitive), checks every
Y/U/V byte and presentation index against the pinned C decoder, and verifies
frame counts. Both decoders stream frames, so it needs no decoded-movie files.
The test fails if the directory contains no movies. Original assets are supplied
locally and are never included in the repository or crate; this opt-in test is
separate from the synthetic reference comparisons run in CI.
Release instructions are in RELEASING.md.
License
Licensed under LGPL-2.0-or-later; see LICENSE. Based on Tilka's HVQM4 decoder, via the mbcgh fork, retaining its original license. Upstream credits Tilka and flacs/hcs (container/audio). Rust rewrite and synthetic tests by h4m contributors, 2026.