nwjs-ffmpeg-prebuilt and the problem of shipping proprietary codecs with NW.js

The gap this fills: browsers without proprietary codecs

Chromium, and the NW.js runtime built on it, ships without the AAC and H.264 codecs that most commercial media uses. A video application built on NW.js can therefore play WebM and VP8 but will stall on an MP4 or an AAC stream, and no amount of application code fixes that because the decoder is not in the build.

nwjs-ffmpeg-prebuilt addresses exactly that hole. The project publishes FFmpeg prebuilt binaries with proprietary codecs for NW.js and Chromium, and pairs them with build instructions for Windows, Linux and macOS. The repository topics list the codecs directly, including h264 and proprietary-codecs.

The alternatives are the familiar ones and none of them are comfortable. An application can ship its own WebAssembly or native decoder, which means writing or bundling a media stack that the browser will not give it. It can bundle the codecs into its own Chromium fork, which means maintaining a fork. Or it can accept the limitation and restrict its content to open formats. This project takes the third path of a separate FFmpeg that an application can call instead.

The binary is not itself the integration. It is the decoder that the application loads.

Downloads come from the releases, not from npm

The distribution split is worth understanding before anything else, because it is unusual for a project with a package.json.

The compiled FFmpeg binaries are published as GitHub releases, and the project guide points at the releases page for downloads. The npm package is not the FFmpeg build. It is the tooling that produces one.

The package.json names the package nwjs-ffmpeg-prebuilt with version 0.0.5, declares type as module, points main at build.js, and registers a single binary called build-ffmpeg pointing at that same file. Its runtime dependencies are commander for argument parsing, fs-extra for filesystem work, got for HTTP requests and yazl for creating zip archives. The project is written in JavaScript.

So the workflow is: install the tooling, use it to fetch and compile FFmpeg, and pick up the resulting binaries from the releases. A consumer that only wants a prebuilt decoder downloads a release asset and never touches npm at all.

The version numbers tell two different stories worth keeping straight. The npm package sits at 0.0.5, a pre-1.0 number for the tool. The releases move fast and independently, at 0.118.0 on 2026-10-11, 0.117.0 on 2026-09-30 and 0.116.0 on 2026-09-14, which is the numbering that matters if you are tracking a specific build.

The build script is a thin CLI over commander

The tool exposes one script with a small option set, and the guide lists both invocation forms:

node build[-h] [-c] [--version NW_VERSION] [--arch TARGET_ARCH]

or, equivalently:

npx nwjs-ffmpeg-prebuilt [-h] [-c] [-d] [--get-download-url] [--version NW_VERSION] [--arch TARGET_ARCH]

The argument list is short enough to read in full. Help is shown with -h or --help. The workspace is cleaned, removing downloaded source code, with -c or --clean. A specific NW.js version is selected with -v or --version, and if none is given the latest is taken from the NW.js versions.json file. The target architecture is set with -a or --arch, with x86, x64 and arm listed as the choices. Prebuilt binaries are downloaded with -d or --download, and --get-download-url prints the download URL for those binaries without fetching them. A platform is chosen with -p or --platform, with darwin, win and linux as the values, and an output directory is set with -o or --out.

Two of these options exist purely to save time. --get-download-url lets a script discover where a published binary lives without pulling it, and -c keeps a workspace clean between runs. The platform and architecture pair is what determines which build you end up with.

Per-platform guides sit beside the script

The script handles the common path, and the project acknowledges that the platform specifics need separate documents. Three guides are linked: a Windows guide at guides/build_windows.md, a Linux guide at guides/build_linux.md and a Mac guide at guides/build_mac.md, all under the guides/ directory of the repository.

That split reflects the real state of affairs for FFmpeg builds. Chromium's FFmpeg configuration is not a vanilla FFmpeg configuration, and each platform brings its own toolchain expectations, its own naming for the output library and its own packaging decisions. A build that works on Linux is not guaranteed to be the same build on Windows.

The FFmpeg source itself comes from the Chromium third-party mirror, at the chromium.googlesource.com third_party/ffmpeg location, not from the upstream FFmpeg project. That is an important detail. The build has to match the version and configuration Chromium expects, otherwise the codecs will not be loadable by the runtime, and the Chromium mirror is the only copy that is guaranteed to be aligned.

The repository is otherwise small: .github/, .gitignore, .vscode/, LICENSE, README.md, build.js, guides/, package-lock.json and package.json. There is no test suite, since the test script in package.json is the placeholder that reports no test specified.

The patent warning is the most useful paragraph in the guide

The section on licence and patent fee contains a warning that deserves to be read before any of this is deployed.

It says that using AAC and H.264 codecs requires paying attention to the patent royalties and the licence of the source code, and instructs the reader to consult a lawyer if they do not understand the licensing constraints of using patented media formats in their application. It points to Chromium's own FFmpeg CREDITS file for more information about the licence of the source code.

This is the honest centre of the project. The codecs exist in these binaries because the build deliberately enables them, and enabling them is precisely what creates the patent exposure that a plain FFmpeg build without proprietary codecs does not have. Anyone using this project to ship AAC or H.264 playback is making a licensing decision, not just a technical one, and the project says so in the first line of the section rather than in a footnote.

None of that is legal advice, and the guide is explicit about that by telling you to find a lawyer. What it does is make the question unavoidable at the point where you would otherwise have assumed the codecs were free because Chromium was free.

Two different licences are recorded, which is a thing to check

The licence situation in this repository is inconsistent, and that inconsistency is worth resolving before you rely on it.

The repository is recorded under GPL-2.0, and the badge row and the LICENSE file at the root correspond to that. The package.json, however, declares a different identifier: the license field reads ISC, and the author field is left empty. So the tooling that builds FFmpeg is declared ISC in its manifest, while the repository as a whole is licensed under GPL-2.0.

Which one governs what depends on which artefact you are looking at. The build script is a small Node program, and its declared licence is the one written in package.json. The FFmpeg binaries it produces carry the licence of the Chromium FFmpeg source they were built from, which is a separate matter again and is what the patent section is about.

For an organisation that runs a licence scanner across its dependencies, this is exactly the kind of finding that gets a ticket. The practical step is to read both the LICENSE file at the root and the licensing terms of the Chromium FFmpeg source before shipping anything.

Where this project is the wrong tool

The clearest wrong-tool case is an application that only needs open formats. If your media is WebM or VP8 or AV1, the codecs that justify this whole exercise are not needed, and shipping them creates patent exposure without creating capability.

The second case is a project that has already solved the problem by maintaining a Chromium or NW.js fork with the codecs enabled. If you control the runtime build, adding FFmpeg yourself is more work than adopting a prebuilt one, and you avoid depending on somebody else's release cadence.

The third is a project that needs to move fast on NW.js version bumps. The build is tied to a specific NW.js version, and the version comes either from an explicit flag or from the latest entry in the NW.js versions file. When NW.js moves, someone has to run the build again and publish a new release, and the release numbering here moves on a schedule measured in days rather than months, which suggests that work is happening, but it also means your dependency on a specific binary version is a moving target.

The fourth limitation is the narrowness of the tooling. There is one script, no test suite, and the platform specifics are pushed into three markdown documents. For a build task that is genuinely hard to get right, that is a small amount of support, and it is why the per-platform guides exist.

Editorial conclusion

nwjs-ffmpeg-prebuilt suits a team shipping an NW.js or Chromium application that needs AAC or H.264 playback and cannot wait for the browser to gain those codecs, and it suits anyone who needs to rebuild FFmpeg against a specific NW.js version rather than take whatever the runtime ships. It does not suit a project that only needs an open-codec build, since the entire point of these binaries is the proprietary codecs they add. Before using the output, read the patent note in the project guide and take your own legal advice, and check the licence files carefully, because the repository is recorded under GPL-2.0 while package.json declares ISC.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-2.0
3. nwjs-ffmpeg-prebuilt/nwjs-ffmpeg-prebuilt on GitHub
4. README
5. Releases