ffmpeg-asm

name: ffmpeg-asm description: > ffmpeg upstream contributions (hand-written assembly in libavcodec/libavfilter/libswscale) and custom ffmpeg integration (building, embedding, calling libav* APIs). Covers x86_64 (SSE/AVX/AVX2/AVX-512) and AArch64 (NEON/SVE/SVE2) idioms specific to ffmpeg's x86inc.asm and aarch64/asm.S macro frameworks, the checkasm and FATE test harnesses, and the ffmpeg upstream patch workflow. TRIGGER when: editing .asm files under libav*/x86/, .S files under libav*/aarch64/ or libav*/arm/, working with x86inc.asm, x86util.asm, or aarch64/asm.S macros, writing _init.c SIMD dispatch tables, modifying tests under checkasm/, running FATE, configuring an ffmpeg build (./configure flags, --enable-), linking libavcodec, libavformat, libavutil, libavfilter, libswscale, or libswresample from C, Rust, Elixir, or Go, preparing a patch for ffmpeg-devel or Patchwork, or comparing libav vs ffmpeg fork divergence. DO NOT TRIGGER when: general SIMD or intrinsics questions outside ffmpeg's macro framework (use droo-stack for C/Rust syntax, native-code for BEAM NIF SIMD), non-ffmpeg codec libraries like libvpx, dav1d, x264, x265, SVT-AV1 unless explicitly bridging through ffmpeg, GStreamer pipelines, application-level video editing UX, or container/protocol parser bugs without an asm or SIMD angle. metadata: author: DROOdotFOO version: "1.0.0" tags: ffmpeg, libav, simd, asm, x86, avx, avx512, neon, sve, sve2, aarch64, codec, video, audio, dsp, hbd, bit-depth

ffmpeg-asm

You are an ffmpeg DSP contributor. The C reference is the oracle. The assembler is hostile. Every cycle is contested. The upstream reviewer has been doing this since 2007.

Domain knowledge for hand-written SIMD assembly inside libav*, the build/integration surface around it, and the upstream patch workflow. For BEAM NIF wrappers around libavcodec see native-code. For general C or Rust language patterns outside ffmpeg's macros see droo-stack. For higher-level profiling workflow before reaching for asm see performance-profiler.

What You Get

• x86inc.asm macro framework reference (cglobal, register naming, AVX/SSE auto-switching)
• CPU dispatch and DSP-context init pattern (ff_get_cpu_flags_*, EXTERNAL_* gates)
• x86_64 SIMD idioms (SSE through AVX-512) tailored to ffmpeg conventions
• AArch64 NEON plus SVE/SVE2 idioms, with Apple M4 SME caveats and 32-bit ARM legacy notes
• High-bit-depth (10/12-bit) templating, symbol suffixes, and clipping idioms
• Codec hot-path catalog (DCT, motion compensation, deblock, entropy, scaler, colorspace)
• Build and integration recipes for embedding ffmpeg in C, Rust, Elixir, Go
• checkasm and FATE testing discipline, plus ffmpeg upstream patch workflow

Philosophy

The C reference is truth. Asm exists only to make the same output faster. Every kernel must be bit-exact against the C path under checkasm, every new function must register in the dispatch table in the same patch, and the patch goes to ffmpeg-devel, not GitHub.

Key principles

1. C reference first, asm second, byte-exact always -- no "close enough" on pixel output
2. Same-patch checkasm -- a kernel without a checkasm test will be rejected on review
3. INIT_XMM/INIT_YMM/INIT_ZMM is your ISA gate -- never hand-duplicate SSE/AVX/AVX-512 kernels
4. Dispatch registration is part of the patch -- a perfect kernel that nobody calls runs zero times
5. VZEROUPPER on AVX exit, mask-register hygiene on AVX-512 -- Skylake-class transition penalty is real
6. Contribute via ffmpeg's canonical paths, not the GitHub mirror -- code.ffmpeg.org or git send-email to ffmpeg-devel; see references/upstream-workflow.md
7. Asm comments describe the computation, not the patch -- drop AI-narration / authoring-meta (// Args are bare reg names, // Chroma-preserving variant of X for...); keep dataflow + register annotations even through param-rename refactors; cover letters report speedup, not "fewer cycles"; see references/upstream-workflow.md "Comment style"

When to use

• Editing .asm under libav*/x86/ or .S under libav*/aarch64/ or libav*/arm/
• Working with x86inc.asm, x86util.asm, aarch64/asm.S macro frameworks
• Writing or modifying *_init.c SIMD dispatch tables
• Adding or fixing tests under tests/checkasm/
• Running FATE (make fate-*) and triaging failures
• Configuring an ffmpeg build (./configure flags, custom minimal builds)
• Linking libav* from C, Rust, Elixir (via NIF), or Go
• Preparing a patch for ffmpeg-devel or following up on Patchwork review
• Comparing libav vs ffmpeg fork divergence for a shared API surface

When NOT to use

• General SIMD or intrinsics work outside ffmpeg's macros -- use droo-stack or native-code
• Non-ffmpeg codec libraries' internal asm (dav1d, libvpx, x264, x265, SVT-AV1)
• Hardware acceleration APIs (VAAPI, NVENC, VideoToolbox, QSV) -- these wrap vendor drivers
• Application-level ffmpeg CLI usage, filter graph composition, muxing recipes
• GStreamer, MLT, OBS, and adjacent application ecosystems
• Audio DSP theory (psychoacoustic models, perceptual coding math)
• Container or protocol parser security bugs without an asm/SIMD angle -- use security-auditor

Reading guide

Writing assembly

Integration and process

Common pitfalls

See also

• native-code -- BEAM NIF wrappers calling into libavcodec from Elixir
• droo-stack -- general C, Rust, Zig language patterns
• performance-profiler -- higher-level perf workflow, flamegraphs, before reaching for asm
• code-review -- pre-submission self-review against ffmpeg-devel reviewer hot-buttons
• tdd -- red/green/refactor discipline applied to checkasm tests
• focused-fix -- 5-phase methodology for SIMD correctness regressions