main 9e7f6af

Go bindings for FFmpeg C API using purego (no cgo), Linux only

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

Keyboard shortcuts

Single-key shortcuts are on. ctrl k and esc work whatever this says.

ctrl k :
go to a section, branch, tag, file or repository
?
this list
j k
move the row cursor down / up
enter
open the row under the cursor; on Files, a directory opens or closes in place
↑ ↓ ← → home end
in the file tree (focus on a row): previous / next row, close / open a directory or go to its parent / first entry, first / last row. They never open a file
l h
on Files: open a directory or a file / close a directory or go up to its parent, then to the parent page. On pages with a side panel: into the panel (on a merge request, its files) / back to the content; there j k move between its controls
g g G
first / last row
/
filter the list; on Files, find a file anywhere in the repository (esc clears, enter opens the best match)
b
switch branch or tag
g s g f g c g b g m g i g r g a
tabs: summary, files, commits, branches & tags, merge requests, issues, releases, actions (when available)
g h
home
w
wide mode: use the whole width of the screen, or not (remembered)
y
copy a permalink pinned to the commit; in a file, click a line number to select it, shift-click for a range
d u x
diff: split / unified / collapse or expand all
e E
diff: the whole file in view / every file, with the lines the hunks hide
n
merge request: next note in the diff
esc
close a dialog, leave a field

Branches 2

Tags 4

↑↓ moveenter openesc close