purego-ffmpeg
Go bindings for the FFmpeg C API using purego — no cgo required.
Linux only. CGO_ENABLED=0.
[!WARNING] This is early stage. API is not stable. Currently targets FFmpeg 7.x on Linux.
Architecture
The binding layer is generated from FFmpeg C headers. The generator parses headers and produces:
- purego function bindings for all bound FFmpeg functions across 6 libraries
- Outbound port interfaces grouped by domain (Format, Codec, Packet, Frame, Swscale, Swresample, Dict, Util, HWAccel, Stream, Filter)
- A composite CAPI interface embedding all port groups
- Inbound port interfaces exposing struct field accessors and lifecycle methods
- Public API wrappers with typed constructors and domain helpers
- Per-domain adapter structs aggregated in a Bridge for CAPI wiring
A hand-written core layer handles error codes (AVERROR → Go errors), C string conversion, and the tryRegisterLibFunc helper for graceful symbol loading.
Mocks for all interfaces are generated by Mockery v3 and shipped in ffmpeg/mocks/.
Libraries bound
- libavutil — error codes, frame, pixel/sample formats, dictionary, logging, rationals, hardware acceleration
- libavcodec — codec context, encoder/decoder lookup, packet send/receive
- libavformat — format context, demuxing, muxing, stream info
- libswscale — video scaling/conversion
- libswresample — audio resampling
- libavfilter — filter graphs, buffersrc/buffersink
Usage
package main
import (
"fmt"
"github.com/bnema/purego-ffmpeg/ffmpeg"
)
func main() {
if err := ffmpeg.Init(); err != nil {
panic(err)
}
ctx := ffmpeg.AllocFormatContext()
defer ctx.Free()
fmt.Println("FFmpeg initialized")
}
Requirements
- Go 1.26+
- FFmpeg 7.x shared libraries (
libavutil.so.60,libavcodec.so.62, etc.) - Linux (for now)
- Override search path:
FFMPEG_DIR=/custom/path
Building
CGO_ENABLED=0 go build ./...
CGO_ENABLED=0 go test ./...
Integration tests need FFmpeg shared libraries:
go test -tags=ffmpeg_integration ./integration/ -v
Regenerating bindings
go generate ./...
Or manually:
go run ./cmd/ffmpeggen
mockery
Project layout
ffmpeg/ public API (generated) + mocks
types.go hand-written: type aliases (AVRational)
errors.go hand-written: error type re-exports
internal/
ports/in/ inbound port interfaces (generated)
ports/out/ outbound port interfaces (generated) + composite CAPI (generated) + mocks
core/ error handling, C string conversion (hand-written)
capi/ purego bindings + bridge + per-domain adapters (generated + hand-written)
loader/ dlopen FFmpeg libraries with version handling (hand-written)
cmd/ffmpeggen/ binding generator (parser, model, overrides, emitter, templates)
integration/ integration tests (require FFmpeg runtime)
License
MIT