Skip to content

How-to guides

Goal-oriented, practical recipes for someone who already knows the basics. Each guide solves one specific problem.

Available:

  • Obtain a wasm module — supply the ffmpeg-wasi module: a signature-verified certified release (WithModuleRelease, recommended), or a file, bytes, an afero fs, or a URL with checksum-verified caching (WithModuleURL).
  • Verify a release by hand — check a release with just gpg, curl, and sha256sum: WKD key → OpenPGP signature over checksums.txt → per-asset SHA-256.
  • Run ffmpeg over an in-memory filesystem — build a Runtime, supply the module (WithModuleFile / WithModuleBytes / WithModuleFS), transcode against an afero.MemMapFs, probe a file, and cancel a render.
  • Remux without re-encoding (stream copy) — change a container, mix copy with transcode, or join like-codec segments packet-for-packet with the CodecCopy sentinel — no decode, no encode, no quality loss.
  • Extract a clip (seek and time ranges) — cut a time window without decoding from the file start: a cheap keyframe cut, a frame-accurate one, or a no-re-encode copy-trim.
  • Read a raw or headerless input — decode raw .yuv/.pcm or a mislabelled file by forcing the demuxer and supplying its geometry via demuxer options.
  • Package for streaming (MPEG-TS, HLS, fragmented MP4) — write broadcast/adaptive-streaming containers and HLS segment sets to the in-memory fs, no network (needs the intermediate-profile module).
  • Work with subtitle tracks — extract, convert, copy, or burn in subtitle streams: sidecar .srt/.vtt, embedded tracks (SubtitleCodec), and hard-subs via the subtitles/drawtext filters (needs the intermediate-profile module).
  • Read & write metadata and chapters — read container/stream tags and chapters with Probe, and set Metadata/StreamMetadata/Chapters on an output (rides the mux, so it pairs with a copy).
  • Extract frames and thumbnails — pull stills with the frames op (FrameJob/Runtime.Frames): a single frame, an interval, scene changes, or thumbnails.
  • Read analysis-filter measurements — get cropdetect / ebur128 / silencedetect / … data back as structured ProcessResult.Analysis (ParseResult), not scraped from the log.
  • Compose a command with the builder — assemble any invocation (inputs / filtergraph / outputs) as typed data and run it with RunJob (JobSpec()).
  • Watch job progress — receive live progress for a running job on a channel with WithProgress: a completion Fraction with the Source it was derived from, plus byte counters observed at the filesystem boundary and — on a v9+ engine — the engine's own Frame / OutTime / Speed. Best-effort; never blocks the job.
  • Reuse a Runtime across many invocations — compile the module once at startup, share one Runtime for the process lifetime, and parallelise with a fleet (invocations serialise one-at-a-time per Runtime).
  • Use the native backend — swap the sandboxed WASM module for the signed native driver (native.NewFromRelease + WithBackend): native-speed software encode (48–58×) and the full profile's HEVC/AV1 encoders. linux/amd64, opt-in, CGO-free.

New to afmpeg? Do your first in-memory transcode first — these guides assume you already have a Runtime.

Looking for a fact rather than a task — a default, a field, an error, or whether something is supported at all? That is the reference, and in particular limitations.

The WASM engine itself — current FFmpeg compiled to wasm32-wasi, with its process/probe job spec — is the companion ffmpeg-wasi project; grab a released module via obtain a module.