go264
H.264/AVC encoder and decoder in pure Go. No cgo, ever.
- CGO-free. Builds and passes its full test suite with
CGO_ENABLED=0 on
every supported platform. No C toolchain, no shared-library link step.
- Verified against a reference implementation. The decoder reproduces
ffmpeg's output bit for bit on the checked-in conformance streams, and
ffmpeg decodes the encoder's output bit for bit to what our own decoder
produces. Both directions are measured, not assumed.
- Hardware acceleration when present. The encoder and decoder probe for
platform video engines at construction time and use them when available,
falling back to the CPU path transparently. Bindings go through syscalls
and
dlopen, never cgo.
Status
Working today:
| Area |
State |
| Decoder, Main profile |
complete, bit-exact against ffmpeg |
| Encoder, Constrained Baseline |
complete, bit-exact against ffmpeg |
| Intra prediction, all block sizes |
complete |
| Inter prediction |
all P partitions both directions, 8x8 sub-macroblocks, multiple references |
| B slices |
bi-prediction, spatial and temporal direct, output reordered by picture order count |
| Weighted prediction |
explicit for predictive slices, explicit and implicit for bi-predictive |
| CAVLC |
complete, both directions |
| CABAC |
complete on the decoding side |
| In-loop deblocking filter |
complete, shared by encoder and decoder |
| Reference picture management |
sliding window and MMCO, up to sixteen references in the encoder |
| Hardware acceleration |
encoding on Windows through Media Foundation, chosen automatically; Linux not yet |
| Bitrate targeted rate control |
complete, within about a fifth of the request |
| Mode decision |
rate-distortion, trial encoding each candidate |
| SIMD kernels |
sum of absolute differences on amd64, about thirty times faster |
| High profile |
not started; the 8x8 transform, scaling matrices and lossless bypass are rejected explicitly |
See docs/PLAN.md for the phase breakdown and
docs/ARCHITECTURE.md for the design.
Install
go get github.com/oops1/go.264
Library
enc, err := go264.NewEncoder(go264.EncoderConfig{
Width: 1920,
Height: 1080,
FPSNum: 30, FPSDen: 1,
GOPSize: 60,
QP: 26,
})
if err != nil {
return err
}
defer enc.Close()
packet, err := enc.Encode(i420Frame)
dec := go264.NewDecoder()
defer dec.Close()
frames, err := dec.Decode(annexB)
for _, f := range frames {
i420 = f.AppendI420(i420[:0])
}
Encoder.Backend() and Decoder.Backend() report which implementation is
actually in use, and ForceSoftware pins the CPU path for reproducibility.
Command line
go install github.com/oops1/go.264/cmd/go264@latest
go264 encode -s 1280x720 -qp 24 -gop 30 -i input.yuv -o output.264
Or aim at a bitrate instead of a fixed quantiser:
go264 encode -s 1280x720 -b 2500 -gop 30 -i input.yuv -o output.264
go264 decode -i input.264 -o output.yuv
Input and output default to standard input and output, so the tool composes
with ffmpeg:
ffmpeg -i movie.mp4 -pix_fmt yuv420p -f rawvideo - | go264 encode -s 1280x720 -o out.264
Verification
Every numeric table taken from the specification is transcribed from an
authoritative source and then validated structurally rather than trusted.
For the CAVLC tables that means asserting each is a prefix free code whose
Kraft sum is at or just below one, which caught seven wrong entries in one
table and a chroma table whose sum exceeded one, an arithmetic
impossibility for any prefix code.
The decoder is measured against frames ffmpeg produces from the same
streams, sample for sample. The encoder is measured the other way: ffmpeg
must decode its output to exactly what our own decoder produces. Assembly
kernels are compared against their pure Go twins on randomised inputs.
The arithmetic decoder is held to the same standard from the other side.
Its tests carry a CABAC encoder written from the specification and round
trip randomised bin sequences through it, along with every syntax element
the Main profile needs, so that a stream that fails to decode points at
the surrounding code rather than at the arithmetic.
Prediction and interpolation are compared against independent reference
implementations written from the specification formulas rather than from
the production code.
Testing
go test ./...
The conformance suite decodes the streams under testdata/conformance and
compares every sample against frames produced by ffmpeg. testdata/regen.sh
regenerates that corpus. Tests that shell out to ffmpeg skip themselves when
it is not installed.
License
BSD 2-Clause. See LICENSE.