Zig FFI bindings for FFmpeg multimedia libraries (libavformat, libavcodec, libavutil, swresample, swscale), with formally verified ABI definitions in Idris2.

Overview

ffmpeg-ffi provides a high-level Zig interface for FFmpeg operations (media file probing, metadata extraction, stream information) without subprocess calls to ffprobe/ffmpeg. It replaces the typical C header approach with direct extern"C" declarations and a thin Rust shim for opaque struct field access.

Architecture

The repository follows the hyperpolymath ABI/FFI Universal Standard:

• Idris2 ABI (src/abi/) — Formal type definitions with dependent type proofs for memory layout, alignment, and C ABI compliance

• Zig FFI (ffi/zig/) — Generic C-compatible FFI implementation template

• Core wrapper (src/main.zig) — Production FFmpeg bindings with C FFI exports

• Rust shim (shim/) — Thin accessor layer for FFmpeg opaque struct fields

Prerequisites

FFmpeg development libraries must be installed on your system:

# Fedora
sudo dnf install ffmpeg-free-devel
# Ubuntu / Debian
sudo apt install libavformat-dev libavcodec-dev libavutil-dev libswresample-dev libswscale-dev
# macOS
brew install ffmpeg

Building

# Build static and shared libraries
zig build
# Build and run the example probe tool
zig build run -- /path/to/video.mp4
# Run tests
zig build test

The Rust shim (required for opaque struct field access) is built separately:

cd shim
cargo build --release

Usage

Zig API

constffmpeg=@import("ffmpeg");
varinfo=tryffmpeg.probe(allocator, "video.mp4");
deferinfo.deinit();
std.debug.print("Format: {s}\n", .{info.format_nameorelse"unknown"});
std.debug.print("Duration: {d:.2}s\n", .{info.duration_seconds});
std.debug.print("Streams: {}\n", .{info.streams.len});

C FFI

The library exports a stable C ABI for use from any language:

// Probe a fileFFIMediaInfo*info=ffmpeg_probe("video.mp4");
if (info) {
doubleduration=ffmpeg_get_duration(info);
uint32_tstreams=ffmpeg_get_stream_count(info);
ffmpeg_free(info);
}

Project Structure

ffmpeg-ffi/
├── src/
│ ├── main.zig # Core Zig FFmpeg bindings + C FFI exports
│ └── abi/ # Idris2 ABI definitions (formally verified)
│ ├── Types.idr # Core types, handles, result codes
│ ├── Layout.idr # Memory layout proofs
│ └── Foreign.idr # FFI function declarations
├── ffi/zig/ # Generic Zig FFI template implementation
│ ├── build.zig
│ ├── src/main.zig
│ └── test/integration_test.zig
├── shim/ # Rust shim for FFmpeg opaque struct access
│ ├── Cargo.toml
│ └── src/lib.rs
├── examples/
│ └── probe.zig # Example: probe media file metadata
├── .machine_readable/ # SCM checkpoint files
├── .bot_directives/ # gitbot-fleet directives
└── .well-known/ # security.txt, humans.txt, ai.txt

License

Palimpsest License (MPL-2.0)

Copyright (c) 2025-2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>

Contributing

See CONTRIBUTING for guidelines.

Security

See SECURITY for reporting vulnerabilities.