Project

go-264

experimental

Decoder-first H.264/AVC implementation in pure Go, with tracing and FFmpeg comparison tools.

Overview

go-264 is a decoder-first H.264/AVC implementation in Go. It parses Annex B streams, reconstructs YUV420 frames for the implemented paths and includes tracing and comparison tooling for FFmpeg-grounded debugging.

This is not a finished general-purpose codec. Baseline CAVLC streams decode through the implemented paths; CABAC is partial, B-slice reconstruction still has major quality gaps, and SIMD coverage is incomplete.

How it works

Annex B scanning and NAL parsing feed the slice syntax layer, which dispatches residual data through CAVLC or the partial CABAC path. Intra and inter prediction, integer transforms and reconstruction write into YUV420 frame storage; the decode pipeline also applies in-loop deblocking and maintains reference-frame state for the DPB.

The command-line tools can emit PNG or raw YUV, trace syntax and compare traces. Regression checks use FFmpeg-derived syntax, motion and YUV comparisons, with PSNR gates rather than any claim of full conformance.

Features
Annex B and syntax parsing

Start-code scanning, emulation-prevention removal, SPS/PPS handling and I/P/B slice-header parsing.

CAVLC and CABAC paths

Baseline CAVLC decoding is implemented. CABAC has useful syntax and reconstruction coverage, but is still incomplete.

Frame reconstruction

Intra and inter prediction, 4x4 and 8x8 integer transforms, deblocking, YUV420 storage and reference-frame tracking for the implemented decode paths.

Inspection tools

Decode to PNG or YUV, record syntax traces and compare decoder output against FFmpeg-derived references.

Assembly hooks

Scalar kernels have amd64 and arm64 dispatch hooks for prediction and transform-related hot paths. GPU code is experimental scaffolding only.

Explicit limits

Weighted prediction and FMO reconstruction are not implemented, B-slice reconstruction has known quality gaps, and there is no encoder.

Architecture
Annex B stream NAL · SPS · PPS Slice syntax I · P · B headers Entropy decode CAVLC · partial CABAC Reconstruction predict · transform · deblock Frame + DPB YUV420 · references Decode + compare PNG · YUV · traces · PSNR H.264 decode path with trace and validation tools