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

@@ -57,7 +57,7 @@ jobs:
           node-version: ${{ matrix.node }}
           cache: pnpm
       - run: pnpm install --frozen-lockfile
-      - run: pnpm test --project core
+      - run: pnpm test --project core --project node
   browser:
     # @ffmpeg/ffmpeg and @ffmpeg/util in Chromium.
     runs-on: ubuntu-latest

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,node           # node: the core tests run in Node.js
+  -sENVIRONMENT=web,worker,node           # node: @ffmpeg/ffmpeg's node export, and the core tests
   -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

packages/core/package.json

@@ -33,7 +33,7 @@
     "url": "https://github.com/ffmpegwasm/ffmpeg.wasm/issues"
   },
   "engines": {
-    "node": ">=16.x"
+    "node": ">=22"
   },
   "homepage": "https://github.com/ffmpegwasm/ffmpeg.wasm#readme",
   "publishConfig": {

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": "pnpm clean && pnpm build:esm && pnpm build:umd",
     "prepublishOnly": "pnpm build"
@@ -48,13 +48,15 @@
     "url": "https://github.com/ffmpegwasm/ffmpeg.wasm/issues"
   },
   "engines": {
-    "node": ">=18.x"
+    "node": ">=22"
   },
   "homepage": "https://github.com/ffmpegwasm/ffmpeg.wasm#readme",
   "publishConfig": {
     "access": "public"
   },
   "devDependencies": {
+    "@ffmpeg/core": "workspace:*",
+    "@types/node": "^22.20.4",
     "@typescript-eslint/eslint-plugin": "^6.1.0",
     "@typescript-eslint/parser": "^6.1.0",
     "eslint": "^8.45.0",
@@ -65,5 +67,13 @@
   },
   "dependencies": {
     "@ffmpeg/types": "workspace:*"
+  },
+  "peerDependencies": {
+    "@ffmpeg/core": "workspace:^"
+  },
+  "peerDependenciesMeta": {
+    "@ffmpeg/core": {
+      "optional": true
+    }
   }
 }

packages/ffmpeg/src/classes.ts

@@ -182,6 +182,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.
@@ -194,15 +205,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 });
+});