Node.js support: FFmpeg runs ffmpeg-core in a worker_threads worker

@ffmpeg/ffmpeg's "node" export used to be a stub whose constructor threw
"ffmpeg.wasm does not support nodejs" (#659, #773), which also broke server
rendering and test runners. It is now the same FFmpeg class, with the core in
a worker_threads worker instead of a Web Worker (#897):

- src/node/index.ts: FFmpeg with createWorker() overridden to adapt a
  worker_threads Worker to the Web Worker interface the class uses.
- src/node/worker.ts (+ globals.ts): gives worker.js its self/postMessage
  globals and defaults coreURL to the installed @ffmpeg/core.
- The core is built for web, worker and node, with NODEFS to mount host
  directories; in Node its threads start from the core module itself.
- It works from the main thread and from inside a worker_threads worker.
- dist/esm is marked "type": "module" so Node loads it as ESM.
- tests/node (node --test, part of npm test): load with the default core,
  exec, files, ffprobe, NODEFS, terminate, and from a worker thread.

Author: lucasgelfond

.github/workflows/CI.yml

@@ -50,10 +50,10 @@ jobs:
         with:
           name: ffmpeg-core
           path: packages/core/dist
-      - name: Use Node.js 20
+      - name: Use Node.js 22
         uses: actions/setup-node@v4
         with:
-          node-version: 20.x
+          node-version: 22.x
       - name: Cache dependencies
         id: cache-dependencies
         uses: actions/cache@v4
@@ -68,6 +68,30 @@ jobs:
         run: npm run test:install
       - name: Run tests
         run: npm test
+  node:
+    # The Node.js API on every supported Node.js version.
+    runs-on: ubuntu-latest
+    needs:
+      - build-core
+    strategy:
+      matrix:
+        node: [20, 22, 24]
+    steps:
+      - name: Checkout Source Code
+        uses: actions/checkout@v4
+      - name: Download ffmpeg-core
+        uses: actions/download-artifact@v4
+        with:
+          name: ffmpeg-core
+          path: packages/core/dist
+      - name: Use Node.js ${{ matrix.node }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node }}
+      - name: Install dependencies
+        run: npm install
+      - name: Run Node.js tests
+        run: npm run test:node
   heavy:
     # FATE samples + benchmarks: nightly, on demand, or with the "heavy" PR label.
     if: github.event_name != 'pull_request' || contains(github.event.pull_request.labels.*.name, 'heavy')

apps/website/docs/faq.md

@@ -1,15 +1,22 @@
 # FAQ
 
-### Why ffmpeg.wasm doesn't support nodejs?
+### Does ffmpeg.wasm work in Node.js?
 
-ffmpeg.wasm did support nodejs before 0.12.0, but decided to discontinue nodejs support due to:
+Yes, since @ffmpeg/ffmpeg 0.13: the same `FFmpeg` class runs ffmpeg-core in a
+`worker_threads` worker, loads the installed `@ffmpeg/core` by default, and can
+mount host directories with `NODEFS`:
 
-- It takes extra effort to maintain nodejs support
-- If you are not in browser, there are a lot of better choices than using WebAssembly for a better performance, ex:
-  - nodejs: https://www.npmjs.com/package/fluent-ffmpeg
-  - react-native: https://github.com/arthenica/ffmpeg-kit
+```js
+import { FFmpeg } from "@ffmpeg/ffmpeg";
 
-Of course, it is still highly welcome to contribute a nodejs version of ffmpeg.wasm.
+const ffmpeg = new FFmpeg();
+await ffmpeg.load();
+await ffmpeg.createDir("/host");
+await ffmpeg.mount("NODEFS", { root: process.cwd() }, "/host");
+await ffmpeg.exec(["-i", "/host/input.webm", "/host/output.mp4"]);
+```
+
+A native `ffmpeg` binary is still faster if you can ship one.
 
 ### Why ffmpeg.wasm is so slow comparing to ffmpeg?
 

build/ffmpeg-wasm.sh

@@ -41,7 +41,7 @@ CONF_FLAGS=(
   -lavutil
   $LDFLAGS
   -sDEFAULT_TO_CXX                         # x265, zimg and harfbuzz are C++
-  -sENVIRONMENT=web,worker
+  -sENVIRONMENT=web,worker,node           # node: @ffmpeg/ffmpeg runs the core in worker_threads
   -sSTACK_SIZE=5MB                         # increase stack size to support libopus
   -sDEFAULT_PTHREAD_STACK_SIZE=2MB         # the 64KB default overflows in x264 and decoder threads
   -sMODULARIZE                             # modularized to use as a library
@@ -53,6 +53,7 @@ CONF_FLAGS=(
   -sEXPORTED_FUNCTIONS=$(node src/bind/ffmpeg/export.js) # exported functions
   -sEXPORTED_RUNTIME_METHODS=$(node src/bind/ffmpeg/export-runtime.js) # exported built-in functions
   -lworkerfs.js
+  -lnodefs.js                              # mount host directories in Node.js
   --pre-js src/bind/ffmpeg/bind.js        # extra bindings, contains most of the ffmpeg.wasm javascript code
   --js-library src/bind/ffmpeg/library.js # overrides of emscripten library functions
   '-sDEFAULT_LIBRARY_FUNCS_TO_INCLUDE=$holdRuntime' # see library.js

package.json

@@ -9,7 +9,8 @@
     "build:wasm": "bash scripts/build-wasm.sh",
     "serve": "http-server -c-1 -s -p 3000 . --cors --headers '{\"Cross-Origin-Embedder-Policy\":\"require-corp\",\"Cross-Origin-Opener-Policy\":\"same-origin\",\"Cross-Origin-Resource-Policy\":\"cross-origin\",\"Origin-Agent-Cluster\":\"?1\"}'",
     "pretest": "npm run build",
-    "test": "node tests/run.mjs",
+    "test": "node tests/run.mjs && npm run test:node",
+    "test:node": "node --test tests/node/*.test.mjs",
     "test:install": "node node_modules/playwright/cli.js install --with-deps chromium",
     "test:heavy": "node tests/heavy/fate.mjs",
     "bench": "node tests/heavy/bench.mjs",

packages/ffmpeg/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@ffmpeg/ffmpeg",
   "version": "0.12.15",
-  "description": "FFmpeg WebAssembly version for browser",
+  "description": "FFmpeg WebAssembly version for browsers and Node.js",
   "main": "./dist/umd/ffmpeg.js",
   "types": "./dist/esm/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/esm/index.d.ts",
-      "node": "./dist/esm/empty.mjs",
+      "node": "./dist/esm/node/index.js",
       "default": {
         "import": "./dist/esm/index.js",
         "require": "./dist/umd/ffmpeg.js"
@@ -22,7 +22,7 @@
     "dev": "webpack -w --mode development",
     "lint": "eslint src",
     "clean": "rimraf dist",
-    "build:esm": "tsc -p tsconfig.esm.json",
+    "build:esm": "tsc -p tsconfig.esm.json && node -e \"require('fs').writeFileSync('dist/esm/package.json', '{\\\"type\\\": \\\"module\\\"}')\"",
     "build:umd": "webpack",
     "build": "npm run clean && npm run build:esm && npm run build:umd",
     "prepublishOnly": "npm run build"
@@ -48,7 +48,7 @@
     "url": "https://github.com/ffmpegwasm/ffmpeg.wasm/issues"
   },
   "engines": {
-    "node": ">=18.x"
+    "node": ">=20"
   },
   "homepage": "https://github.com/ffmpegwasm/ffmpeg.wasm#readme",
   "publishConfig": {

packages/ffmpeg/src/classes.ts

@@ -183,6 +183,17 @@ export class FFmpeg {
     }
   }
 
+  /**
+   * Starts the worker that runs ffmpeg-core (`FFmpeg` from the `node` export
+   * overrides it with a worker_threads worker).
+   */
+  protected createWorker(classWorkerURL?: string): Worker {
+    return classWorkerURL
+      ? new Worker(new URL(classWorkerURL, import.meta.url), { type: "module" })
+      : // Keep the literal URL here so bundlers pick up worker.js.
+        new Worker(new URL("./worker.js", import.meta.url), { type: "module" });
+  }
+
   /**
    * Loads ffmpeg-core inside web worker. It is required to call this method first
    * as it initializes WebAssembly and other essential variables.
@@ -195,15 +206,7 @@ export class FFmpeg {
     { signal }: FFMessageOptions = {}
   ): Promise<IsFirst> => {
     if (!this.#worker) {
-      this.#worker = classWorkerURL ?
-        new Worker(new URL(classWorkerURL, import.meta.url), {
-          type: "module",
-        }) :
-        // We need to duplicated the code here to enable webpack
-        // to bundle worker.js here.
-        new Worker(new URL("./worker.js", import.meta.url), {
-          type: "module",
-        });
+      this.#worker = this.createWorker(classWorkerURL);
       this.#registerHandlers();
     }
     return this.#send(

packages/ffmpeg/src/empty.mts

@@ -0,0 +1,9 @@
+// The Web Worker globals ../worker.js uses, on a worker_threads worker.
+import { parentPort } from "node:worker_threads";
+
+const scope = globalThis as unknown as {
+  self: unknown;
+  postMessage: (message: unknown, transfer?: Transferable[]) => void;
+};
+scope.self = globalThis;
+scope.postMessage = (message, transfer = []) => parentPort!.postMessage(message, transfer as never[]);

packages/ffmpeg/src/node/globals.ts

@@ -0,0 +1,35 @@
+// Node.js entry of @ffmpeg/ffmpeg (the "node" export condition): the same
+// FFmpeg class, with ffmpeg-core running in a worker_threads worker.
+import { Worker as ThreadWorker } from "node:worker_threads";
+import { FFmpeg as BaseFFmpeg } from "../classes.js";
+
+export * from "../types.js";
+export * from "../const.js";
+
+/** The subset of the Web Worker interface the FFmpeg class uses. */
+class NodeWorker {
+  onmessage: ((event: { data: unknown }) => void) | null = null;
+  onerror: ((event: { error: unknown; preventDefault(): void }) => void) | null = null;
+  #worker: ThreadWorker;
+
+  constructor(url: URL) {
+    this.#worker = new ThreadWorker(url);
+    this.#worker.on("message", (data) => this.onmessage?.({ data }));
+    this.#worker.on("error", (error) => this.onerror?.({ error, preventDefault() {} }));
+  }
+
+  postMessage(message: unknown, transfer: Transferable[] = []) {
+    this.#worker.postMessage(message, transfer as never[]);
+  }
+
+  terminate() {
+    void this.#worker.terminate();
+  }
+}
+
+export class FFmpeg extends BaseFFmpeg {
+  protected createWorker(classWorkerURL?: string): Worker {
+    const url = new URL(classWorkerURL ?? "./worker.js", import.meta.url);
+    return new NodeWorker(url) as unknown as Worker;
+  }
+}

packages/ffmpeg/src/node/index.ts

@@ -0,0 +1,23 @@
+// worker_threads entry: runs ../worker.js with the Web Worker globals it
+// uses, and defaults coreURL to the installed @ffmpeg/core.
+import "./globals.js";
+import "../worker.js";
+import { parentPort } from "node:worker_threads";
+import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
+import type { FFMessageEvent, FFMessageLoadConfig } from "../types.js";
+
+const scope = globalThis as unknown as { onmessage: (event: { data: unknown }) => void };
+
+const defaultCoreURL = () => {
+  const umd = createRequire(import.meta.url).resolve("@ffmpeg/core");
+  return pathToFileURL(umd.replace(/[\\/]umd[\\/]/, "/esm/")).href;
+};
+
+parentPort!.on("message", (data: FFMessageEvent["data"]) => {
+  if (data.type === "LOAD") {
+    const config = (data.data ?? {}) as FFMessageLoadConfig;
+    data.data = { ...config, coreURL: config.coreURL ?? defaultCoreURL() };
+  }
+  scope.onmessage({ data });
+});