effectcraft/crates/hevcenc/README.md

effectcraft-hevcenc

Clean-room, pure-Rust HEVC / H.265 encoder for EffectCraft's MP4 export (layer L0, std only, no unsafe, builds for wasm32-unknown-unknown).

What it produces

• Profiles: Main (8-bit) and Main 10 (10-bit), 4:2:0, Main tier. general_level_idc is taken from the config or chosen as the lowest level whose MaxLumaPs, MaxLumaSr (and, in bitrate mode, MaxBR) fit (Table A.8).
• Parameter sets: VPS, SPS (with VUI: BT.709 colour description, video_full_range_flag, timing info from the frame rate) and PPS, as raw NAL units (Encoder::parameter_sets) and as an hvcC record (ISO/IEC 14496-15 §8.3.3.1, lengthSizeMinusOne 3, complete VPS / SPS / PPS arrays, Encoder::hvcc).
• Pictures: one slice per picture; IDR_N_LP every keyint pictures (1 = all intra, 0 = only the first), TRAIL_R P pictures otherwise, each referencing the previous picture (one short-term RPS in the SPS, num_ref_idx_l0_active 1, no reordering, pts = dts). Packets are length-prefixed (4-byte big-endian) NAL units without parameter sets.
• Picture size: any even width / height; the coded size is padded to a multiple of 8 by edge replication and cropped with the conformance window. Odd sizes are rejected with Error::InvalidConfig (4:2:0 conformance-window offsets are in units of two luma samples).

Coding tools

• 64x64 CTUs, coding units 64x64 .. 8x8 chosen by rate-distortion optimisation: every candidate is actually predicted, transformed, quantised and reconstructed, and its rate is measured with a CABAC bit estimator that evolves the same context states as the real coder. Split decisions compare the best unsplit candidate with the recursively coded children (early exit after a skip).
• Intra: all 35 modes (SATD search on a coarse grid plus refinement and the MPMs), 2Nx2N at 8..32 and NxN (four 4x4 PUs) at 8x8, chroma in DM mode, MPM / remaining-mode coding, reference substitution, [1 2 1] and strong (32x32) smoothing, DC / angular boundary filters.
• Inter (P): skip and merge (spatial candidates + zero candidates, MaxNumMergeCand 5) and AMVP with mvd coding; integer motion search (predictor starts + square pattern, steps 16..1) and half / quarter-sample refinement on pre-interpolated half-sample planes; the coded prediction uses the normative 8-tap / 4-tap interpolation filters and reference-picture edge clamping.
• Transforms: DST-VII 4x4 (intra luma) and DCT 4..32 (inverse by even/odd decomposition, bit-identical to the matrix form), dead-zone quantisation (1/3 intra, 1/6 inter), flat scaling, sign data hiding, inferred transform splits only (max_transform_hierarchy_depth_* 0, so 64x64 CUs use four 32x32 TUs).
• Entropy coding: CABAC (context initialisation by slice QP and init type, decision / bypass / terminate bins, flush), end_of_slice_segment_flag, byte alignment, emulation prevention.
• In-loop filters: the deblocking filter is on (the encoder deblocks its own reconstruction, so references match the decoder); SAO is disabled.
• Rate control: ConstantQp(qp) or Bitrate { kbps }, a per-picture QP from a bits-x-Qstep model per picture type (I pictures get roughly 4x the bits of a P picture) with a buffer that spreads over- and undershoot over the following pictures.

Not implemented: B pictures / reordering, multiple references, TMVP, AMP and other inter partition shapes, residual quadtree splits, transform skip, scaling lists, PCM, SAO, RDOQ, cu_qp_delta / adaptive quantisation, tiles / WPP / multiple slices, range extensions (4:2:2, 4:4:4, > 10 bits).

Measurements

On a shared, heavily loaded machine, opt-level 3: about 0.45 s of CPU per 1920x1080 picture (ffmpeg testsrc2, QP 22 / 32). On ffmpeg's mandelbrot 1080p source (8 pictures, IPPP, QP 32) the stream is about 12 % larger at about 0.2 dB lower mean PSNR-Y than x265 --preset medium at the same QP without psy tuning (110.5 kB / 42.3 dB vs 98.3 kB / 42.5 dB). The synthetic test image reaches 45.8 dB PSNR-Y at QP 22.

Tests

cargo test -p effectcraft-hevcenc:

• every stream is decoded with the first-party filmcraft-hevc decoder and compared bit-exactly with the encoder's reconstruction (Encoder::last_reconstruction, hidden API);
• when ffmpeg is on PATH, the Annex-B elementary stream is decoded with ffmpeg -v error -xerror (no stderr output allowed) and compared bit-exactly as well (skipped otherwise). ffmpeg is used only as an external test oracle;
• covered: 8-bit and 10-bit, all-intra and IP, QP 0 noise (escape codes), QP 0..51, strong deblocking at high QP, sizes 8x8 .. 200x136 with cropping, POC wrap (300 pictures without IDR), bitrate mode within 2x of the target, hvcC layout;
• bench_1080p (ignored) reports speed, size and PSNR on 1080p content generated by ffmpeg.

Specifications

• ITU-T H.265 (V8, 08/2021) | ISO/IEC 23008-2, High efficiency video coding: 7 (syntax and semantics), 8.4 - 8.7 (intra / inter prediction, scaling and transforms, deblocking), 9.3 (CABAC, including the informative encoder description of 9.3.4), Annex A (profiles, tiers and levels), Annex E (VUI).
• ISO/IEC 14496-15 (2019), §8.3.3.1 HEVCDecoderConfigurationRecord.

Implemented from the specification text. Constant tables (CABAC context layout and initValues, rangeTabLPS / transIdx, scan orders, the DCT / DST matrices, intra angles, interpolation filters, the chroma QP table, the deblocking beta / tC tables) and the decoder-side reconstruction arithmetic (intra reference substitution / filtering / prediction, fractional interpolation, deblocking) are mirrored from FilmCraft's first-party, spec-derived filmcraft-hevc decoder (same organisation, MIT OR Apache-2.0), so that encoder and decoder reconstruct identically. No third-party encoder or decoder source (x265, libde265, ffmpeg, HM, ...) was consulted.