ffmpeg-static

ffmpeg-static is a small Node.js package that hands your code an absolute filesystem path to a static ffmpeg (and, via the companion @derhuerst/ffprobe-static package, ffprobe) binary for the current platform and architecture. Rather than shipping the binaries inside the npm tarball, an install-time script downloads the correct prebuilt binary from GitHub Releases — sourced from well-known static-build providers for Windows, Linux, and macOS — caches it on disk, and makes it executable, so require('ffmpeg-static') just returns a ready-to-spawn path.

Because the API surface is a single exported string (or null if the platform/arch combination isn’t supported), it slots into any Node.js media pipeline that already shells out to ffmpeg — video transcoding services, audio extraction scripts, thumbnail generators — without requiring ffmpeg to be preinstalled on the host, in CI, or inside a Docker image. Advanced users can override the binary release tag, source binary, or a custom binaries URL entirely via environment variables when the defaults don’t fit (e.g. air-gapped installs or pinning a specific ffmpeg build).

What You Get

• A single require('ffmpeg-static') call that returns an absolute path to a static ffmpeg binary for the running platform/architecture (darwin x64/arm64, linux x64/ia32/arm64/arm, win32 x64/ia32, freebsd x64)
• A companion @derhuerst/ffprobe-static package with the identical resolution pattern for ffprobe
• An install-time downloader (install.js) that fetches the correct binary from GitHub Releases, caches it on disk via env-paths, decompresses gzip’d assets, and marks the file executable
• Environment-variable overrides per binary (e.g. FFMPEG_BIN, FFMPEG_BINARY_RELEASE, FFMPEG_BINARIES_URL) for custom sourcing, release pinning, or air-gapped installs
• Shipped TypeScript type declarations (string | null) and a runnable example.js showing a minimal ffmpeg CLI wrapper

Common Use Cases

• Transcoding or converting audio/video files in a Node.js backend service without requiring ffmpeg to be preinstalled on the host or in the Docker image
• Extracting audio tracks, generating thumbnails, or probing media metadata inside serverless functions or CI pipelines where system package installs are inconvenient
• Providing a portable, version-pinned ffmpeg binary for cross-platform Electron or desktop-adjacent Node apps that need consistent behavior across macOS, Linux, and Windows

Under The Hood

Architecture — index.js resolves the platform/arch of the running machine, reads config keys embedded under the package’s own name in package.json (binary-path-env-var, executable-base-name), and returns either an environment-variable override or a computed filesystem path next to the module, or null if the platform/arch pair isn’t in the supported matrix. install.js (the actual postinstall script in the published sub-packages) downloads the matching static binary from GitHub Releases via @derhuerst/http-basic with disk caching (env-paths), gzip decompression, retry/redirect handling, and a progress bar, then chmods it executable; it also normalizes S3 presigned-URL query strings so cache keys stay stable across signature rotations. build-packages.js is a workspace publish-time script that copies index.js/install.js/LICENSE into two generated npm sub-packages (ffmpeg-static and @derhuerst/ffprobe-static) and stamps a per-package package.json — meaning the root repo is a monorepo that generates the actual published packages rather than being published directly. test.js is a single integration test that requires both resolved binaries, asserts they’re absolute, executable files, and spawns each with --help to confirm a zero exit code.

Tech Stack — CommonJS Node.js (engines: >=16), managed as an npm workspaces monorepo with zero build step required by consumers. Runtime dependencies are deliberately minimal: @derhuerst/http-basic (HTTP client with disk caching, gzip and redirect support), env-paths (XDG-style cache directory resolution), https-proxy-agent (corporate proxy support for the download step), and progress (CLI download progress bar). Binaries themselves are sourced externally at install time from gyan.dev and a community Win32 fork (Windows), johnvansickle.com (Linux), and evermeet.cx/osxexperts.net (macOS) rather than bundled in the npm tarball, keeping the published package small.

Code Quality — The single test (test.js), run via a pretest step that rebuilds workspaces and installs them, is integration-style rather than unit-level: it verifies real binary resolution and execution end-to-end but doesn’t isolate index.js’s platform/arch matching logic. install.js’s error handling is explicit and fails loudly — exitOnError calls process.exit(1) on any hard download failure, with a softer 404-tolerant warning path for the optional README/LICENSE sidecar downloads. ESLint (eslint:recommended) is configured for style, though the codebase is plain, unannotated JavaScript with no internal TypeScript.

API Design — The consumer-facing surface is intentionally tiny: require('ffmpeg-static') returns a single string path (or null), with zero required configuration and zero wrapping abstraction around ffmpeg’s own CLI — the shipped example.js explicitly notes it’s just a thin demonstration and that “it wouldn’t make sense to hide a flexible tool behind a limited wrapper script.” Power-user configuration (custom binary source, release pinning, alternate download host) is exposed via environment variables documented directly in package.json rather than a separate config API, keeping day-to-day usage to a single require statement.