Skip to content

Obtain an ffmpeg.wasm module

afmpeg does not embed or bundle the ffmpeg WebAssembly module, and it never downloads one behind your back. You supply it — deliberately, so the module's licence (a full/GPL build links x264) never attaches to afmpeg's permissively licensed Go package (spec 0001 D-C). New returns ErrNoModule if none is given.

There are several ways to provide it. For the project's own releases, prefer the certified path; for your own builds, supply them directly.

WithModuleRelease fetches a published ffmpeg-wasi release by (tag, variant) and verifies it before it runs — the release's checksums.txt carries a detached signature made by a key held in AWS KMS (signable only by ffmpeg-wasi's tag pipeline), and afmpeg checks that signature against a public key pinned inside afmpeg, then the module's and provenance's checksums, then that the provenance names the variant you asked for:

var prov afmpeg.Provenance
rt, err := afmpeg.New(ctx, afmpeg.WithModuleRelease(
    "n8.1.2-3", afmpeg.VariantLGPL,
    afmpeg.WithReleaseProvenance(&prov), // optional: what was loaded
))
// prov.FFmpegVersion, prov.Variants[...] — verified, not just downloaded.

Verification is mandatory and offline (the key is embedded — there is no skip flag). Any tamper fails with a typed error: ErrSignatureInvalid, ErrChecksumMismatch, or ErrProvenanceMismatch. The verified module is cached, so later runs skip the download.

Options: WithReleaseProvenance (capture the verified provenance), WithReleaseBaseURL (fetch from a mirror / internal store — still verified against the pinned key), WithReleaseBundleDir (air-gapped: verify a local directory of pre-downloaded assets), WithReleaseCacheDir, WithReleaseHTTPClient. See the trust model in verifying a release.

VariantLGPL is the default, proprietary-compatible build (H.264 via openh264); VariantGPL adds libx264. This path is for our releases — we can only certify what we publish; for your own builds use WithModuleURL or a file below.

From a file or bytes

If you already have the .wasm on disk or in memory:

rt, err := afmpeg.New(ctx, afmpeg.WithModuleFile("ffmpeg.wasm"))
// or afmpeg.WithModuleBytes(b)
// or afmpeg.WithModuleFS(fs, "ffmpeg.wasm")  // from any afero.Fs

From a URL, with caching (no manual wrangling)

WithModuleURL downloads the module once and caches it under your OS cache dir, so subsequent runs are offline. You choose the URL and accept its licence. Because the module is executable code, pair it with WithSHA256:

rt, err := afmpeg.New(ctx, afmpeg.WithModuleURL(
    "https://gitlab.com/api/v4/projects/83847809/packages/generic/ffmpeg-wasi/n8.1.2-2/ffmpeg-wasi-lgpl.wasm",
    afmpeg.WithSHA256("b2925737383f3c68c70e8f2df9e40c2339dd8ff03f0f20691b059e82b636d428"),
))

Options: WithSHA256 (verify), WithGunzip (decompress a .wasm.gz), WithCacheDir (override the cache location), WithHTTPClient (your own client, e.g. for proxies or timeouts). A checksum mismatch returns ErrChecksumMismatch and the bytes are never executed.

Where do I get a module?

  • ffmpeg-wasi (the route) — the companion libav-direct engine: current FFmpeg, published as lgpl (default) and gpl WASI modules, each with a checksum and provenance. Both encode H.264 — the lgpl module via openh264, the gpl module via libx264. Pin a release asset + its SHA-256 (the example above is the lgpl module from n8.1.2-2). It speaks the structured job spec — drive it with Command.JobSpec() / RunJob and Probe.

A GPL module makes the combined running program GPL; afmpeg keeps it at arm's length (a separate artifact you fetch), but your obligations follow the variant you choose. The lgpl module's self-compiled openh264 carries an AVC patent caveat. - Build your own — any current FFmpeg compiled to wasm32-wasi with the feature set afmpeg's runtime enables (spec 0004 R-0004-9). afmpeg runs it.