react-native-facefusion 0.1.0 → 0.1.1

package/README.md

@@ -1,9 +1,23 @@
 # react-native-facefusion
 
+[![npm version](https://img.shields.io/npm/v/react-native-facefusion.svg)](https://www.npmjs.com/package/react-native-facefusion)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![platform: android](https://img.shields.io/badge/platform-android-3ddc84.svg)](#requirements--read-this-first)
+
 A React Native TurboModule that runs face swapping **entirely on the phone**, on
 Qualcomm's Hexagon NPU. No server, no upload, no network call for inference — the
 photo or video never leaves the device.
 
+```ts
+import { swapPhoto } from 'react-native-facefusion';
+
+const result = await swapPhoto(sourcePath, targetPath, outputPath);
+// { outputPath, faceCount, tier } -- inference ran on the phone's NPU, offline.
+```
+
+That's the shape of it. Whether it'll actually run on a given phone depends on the
+chip — read the requirements below before installing; they're not boilerplate.
+
 ## Requirements — read this first
 
 - **Android only.** There is no iOS implementation. This runs on Qualcomm's Hexagon
@@ -22,22 +36,44 @@ photo or video never leaves the device.
 - **A one-time native SDK step at install**, described below. It cannot be skipped
   and it cannot be bundled into this package — see [Install](#install).
 
+**Check a specific device before going further** — `probeDevice()` answers this at
+runtime, so you don't have to guess from a spec sheet:
+
+```ts
+import { probeDevice } from 'react-native-facefusion';
+
+const device = await probeDevice();
+console.log(device); // { ok, tier, tierChain, arch, vtcmMb, socModel, ... }
+// ok: false means this exact phone cannot run the NPU path -- not a crash, an answer.
+```
+
+This still needs the SDK step below to build at all; it's here so you know what to
+expect before spending time on that step.
+
 ## Install
 
-Three steps, not one — a plain `npm install` is not enough on its own.
+Two manual steps, not one — a plain `npm install` gets you most of the way, not
+all of it.
 
 ```sh
 npm install react-native-facefusion
 ```
 
 ```sh
-# 1. Fetch the upstream C++ engine this module wraps. Not committed to this repo or
-#    to the npm package — see "Why the extra steps" below.
+# Step 1 (fetching the upstream C++ engine) now runs AUTOMATICALLY as a postinstall --
+# nothing to do here in the common case. It's shown below only for when it's needed by
+# hand: your install had no network/git available (the postinstall warns rather than
+# failing your whole `npm install` when that happens), or scripts are disabled
+# (`npm ci --ignore-scripts`, some CI/lockfile-security setups). Not committed to this
+# repo or to the npm package either way — see "Why the extra steps" below.
 ./node_modules/react-native-facefusion/scripts/fetch-upstream.sh
 ```
 
 ```sh
-# 2. Get Qualcomm's QAIRT SDK (Community edition — a plain ZIP, no account needed):
+# Step 2 -- still manual, and can't be automated the same way: it's a real download
+# from Qualcomm's own site, not a script fetching a public git repo.
+#
+# Get Qualcomm's QAIRT SDK (Community edition — a plain ZIP, no account needed):
 #    https://www.qualcomm.com/developer/software/qualcomm-ai-runtime-sdk-qairt
 #
 # Copy out of the ZIP into THIS PACKAGE's directory (not your app's) -- CMake resolves
@@ -60,10 +96,13 @@ npm install react-native-facefusion
 # models arrive pre-compiled, so it is exactly the step this never performs.
 ```
 
-**Script steps 1 and 2.** Both write into `node_modules/`, so a fresh `npm install`
-or `npm ci` wipes them. Put them in a checked-in setup script (or a `postinstall`)
-rather than running them by hand once and forgetting — a CI machine or a new
-teammate's clone will otherwise fail at CMake configure with a message naming the
+**Both steps write into `node_modules/`, so a fresh `npm install` or `npm ci` wipes
+them out again.** Step 1 now re-runs itself automatically every time (it's this
+package's own `postinstall`), so a clean clone or CI machine gets it for free. Step
+2 does not and cannot — it's a manual download from Qualcomm, not something this
+package's install can reach out and fetch — so put IT in your own checked-in setup
+script if you want a new teammate's clone or CI machine to get it without a manual
+step. Skip it and a fresh clone fails at CMake configure with a message naming the
 missing piece.
 
 **Your app's `android/build.gradle` needs `minSdkVersion = 31`.** A fresh React Native
@@ -198,6 +237,11 @@ aggregate 10% rate, and the native-error-means-refusal path.
 
 ## Known issues
 
+Hitting an actual error (a QNN error code, a manifest merge failure, a decode
+failure) rather than a documented limitation below? See
+[TROUBLESHOOTING.md](TROUBLESHOOTING.md) first — it's real errors from this
+project's own history, most of them more misleading than they look.
+
 - **A photo swap's output is capped at 2560 px on the long edge** (and a source photo
   is subsampled to 1920, which costs nothing — it only contributes an identity, never
   output pixels). This is deliberate: the pipeline holds roughly 19 bytes per pixel at

package/TROUBLESHOOTING.md

@@ -0,0 +1,99 @@
+# Troubleshooting
+
+Real errors hit while building this package, kept here because the QNN/Hexagon
+error codes below are genuinely misleading on their own — the number rarely names
+the actual cause. If you hit one of these while integrating the library into your
+own app, start here before assuming it's your code.
+
+For "a face detects on one phone and not another", see [Known issues](README.md#known-issues)
+in the README — that one isn't an error at all, it's documented behaviour.
+
+## `Fail to get context blob with err 5000` / `Using newer context binary on old SDK`
+
+Your QAIRT SDK (step 2 of [Install](README.md#install)) is older than the one the
+model `.bin` files were compiled against. These files are QNN **context
+binaries** — a graph already compiled and scheduled for one Hexagon architecture,
+not portable weights — and the format they're serialized in
+(`QNN_HTP_CONTEXT_BLOB_VERSION`, a constant in Qualcomm's own `QnnHtpCommon.h`)
+has changed between SDK releases.
+
+**Fix:** get a newer QAIRT SDK. This project currently develops against
+**2.49.40.260810** (`QNN_HTP_CONTEXT_BLOB_VERSION 4.0.4`) — treat that as a floor,
+not a ceiling; if a future model update needs a newer blob version than whatever
+SDK you have, you'll see this exact error again.
+
+## `err 4000` (`QNN_BACKEND_ERROR_CANNOT_INITIALIZE`)
+
+This number on its own tells you almost nothing — it's shown up in this project's
+own history for at least two unrelated root causes (a missing vendor library, and,
+early on, a linking choice that was fixed before this ever became a public API).
+**Don't diagnose from the code. Read `adb logcat` for the actual line immediately
+around it** — in particular, any `dlopen failed:` line naming a specific missing
+library. That line, not the QNN error number, is the real error.
+
+## `14001` (`QNN_DEVICE_ERROR_INVALID_CONFIG`)
+
+Same advice as `err 4000`, and just as misleading: in this project's own history,
+this exact code showed up from a missing vendor library, and nothing about
+configuration was actually wrong. Read the log line above it.
+
+## `dlopen failed: library "libcdsprpc.so" not found: needed by .../libQnnHtpV*Stub.so`
+
+The real line behind both codes above, in this project's own case. `libcdsprpc.so`
+is Qualcomm's fastrpc client — the only transport to the Hexagon DSP at all — and
+from `targetSdk` 31+, an app's linker namespace can't see a vendor library unless
+the app's manifest explicitly names it with `<uses-native-library>`.
+
+This library's own `AndroidManifest.xml` already declares `libcdsprpc.so` and
+`libadsprpc.so` this way (`required="false"`, so it doesn't make your app
+uninstallable on non-Qualcomm phones), and that merges into your app's manifest
+automatically. **If you see this error anyway,** check your app's *merged*
+manifest — not the one you wrote by hand — for both entries:
+
+```sh
+./gradlew :app:processDebugManifest
+# then read app/build/intermediates/merged_manifests/debug/AndroidManifest.xml
+```
+
+Something in your own manifest, a manifest-merger `tools:` rule, or another
+dependency can suppress a merged-in entry; if it's missing there, that's the bug
+to chase, not this package.
+
+## `deviceCreate failed` / "the DSP is not reachable from this process" from `probeDevice()`
+
+Your own copy of the QAIRT runtime (step 2 of Install) is missing the Stub/Skel
+pair for *this specific phone's* Hexagon architecture. `libQnnHtp.so` picks that
+pair based on the chip's Hexagon generation, completely independent of which model
+tier got downloaded — so this can happen even with the right models fully
+downloaded and verified. Re-check the copy step: **every** architecture's
+Stub+Skel pair needs to be present (`libQnnHtpV*Stub.so` **and**
+`libQnnHtpV*Skel.so` for each), not a chosen few.
+
+## `Could not decode image` for a file `adb shell ls` plainly shows exists
+
+Scoped storage, not a bad path. From `targetSdk` 29+, an app with no storage
+permission can't read a file it doesn't own in shared storage (`/sdcard/Download/`
+and similar), even though the file is right there when you look from `adb shell`
+as `shell`, not as your app. Confirm with `run-as <your.app.id> ls <path>` — if
+that comes back empty while a plain `adb shell ls` shows the file, this is it.
+
+**Fix:** pass paths your app actually owns —
+`context.getExternalFilesDir(null)` and similar — rather than a raw shared-storage
+path or an unresolved `content://` URI. `swapPhoto`/`swapVideo`/`detectSourceFaces`/
+`detectTargetFaces` all take real filesystem paths, not URIs.
+
+## `INSTALL_FAILED_INSUFFICIENT_STORAGE` on a debug install
+
+`useLegacyPackaging = true` (required — see [Install](README.md#install)) stores
+the QNN runtime **uncompressed** inside the APK *and* extracts a second real copy
+on disk at install time, so budget for roughly double the runtime's size in actual
+device storage, not just APK size. `adb uninstall` the previous build and
+`pm trim-caches 4G` (or similar) before reinstalling on a tight test device.
+
+## Manifest merge fails with `MergeFailureException: Error parsing …` and no line number
+
+If you're editing your own `AndroidManifest.xml` near this library's
+`<uses-native-library>` entries and hit this with no useful location: check for a
+literal `--` inside an XML comment. It's illegal in XML, the manifest merger's
+error gives no line number for it, and it's an easy thing to type by accident in a
+comment describing what a permission is *for*.

package/android/src/main/java/com/facefusion/FacefusionModule.kt

@@ -10,6 +10,7 @@ import java.io.File
 import java.util.concurrent.Callable
 import java.util.concurrent.ExecutorService
 import java.util.concurrent.Executors
+import java.util.concurrent.TimeUnit
 import java.util.concurrent.atomic.AtomicBoolean
 
 class FacefusionModule(reactContext: ReactApplicationContext) :
@@ -170,8 +171,15 @@ class FacefusionModule(reactContext: ReactApplicationContext) :
       return
     }
     videoWorker.execute {
-      VideoSwapService.start(reactApplicationContext)
       try {
+        // Must be inside the try: on minSdk 31+, starting a foreground service from
+        // outside a foreground/allowed context throws
+        // ForegroundServiceStartNotAllowedException. Outside this try that exception had
+        // nowhere to go but off this Runnable entirely -- `promise` never settled (the JS
+        // call hung forever) and the `finally` below never ran, so `videoBusy` stayed
+        // `true` and every later swapVideo() call rejected E_BUSY for the rest of the
+        // process's life.
+        VideoSwapService.start(reactApplicationContext)
         val result = VideoSwap.run(
           reactApplicationContext, sourcePath, targetPath, outputPath, swapConfig(options),
           sourceFaceBox(options), targetFaceBox(options), targetFps(options),
@@ -232,13 +240,28 @@ class FacefusionModule(reactContext: ReactApplicationContext) :
   }
 
   override fun invalidate() {
+    // Cooperative cancellation first, so anything already running on `worker`/`videoWorker`
+    // gets to the next `throwIfCancelled()` check and exits quickly instead of running its
+    // full course.
     ModelDownload.cancel()
     VideoSwap.cancel()
-    NativePipe.release()
+
+    // `shutdown()` alone only stops NEW submissions -- a processFrame()/initEx() call
+    // already in flight keeps running on its own thread afterwards. `NativePipe.release()`
+    // used to run right after `shutdown()` with nothing in between, so a job that was
+    // mid-call when the module got invalidated (a JS reload while a swap is running, say)
+    // could still be touching `g_pipe` in native code the instant it was freed -- a
+    // use-after-free, which shows up as a native crash, not a catchable Kotlin exception.
+    // Waiting for real termination first closes that gap; the two executors that never
+    // touch `g_pipe` (`downloader`, `gallery`) don't need the same wait.
     worker.shutdown()
-    downloader.shutdown()
     videoWorker.shutdown()
+    downloader.shutdown()
     gallery.shutdown()
+    worker.awaitTermination(10, TimeUnit.SECONDS)
+    videoWorker.awaitTermination(10, TimeUnit.SECONDS)
+
+    NativePipe.release()
     super.invalidate()
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-facefusion",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "React Native TurboModule for on-device face swapping on Qualcomm Hexagon NPUs. Runs fully offline on the phone, no server and no uploads.",
   "main": "./lib/module/index.js",
   "types": "./lib/typescript/src/index.d.ts",
@@ -16,6 +16,7 @@
     "src",
     "lib",
     "android",
+    "TROUBLESHOOTING.md",
     "scripts/fetch-upstream.sh",
     "scripts/check-tarball.sh",
     "patches",
@@ -37,6 +38,7 @@
     "example": "npm run --workspace=example",
     "clean": "del-cli android/build example/android/build example/android/app/build example/ios/build lib",
     "prepare": "bob build",
+    "postinstall": "./scripts/fetch-upstream.sh || echo 'react-native-facefusion: could not auto-fetch the upstream C++ engine (see the error above). Run ./node_modules/react-native-facefusion/scripts/fetch-upstream.sh by hand before building Android -- most likely cause is no network/git at install time.'",
     "typecheck": "tsc",
     "lint": "eslint \"**/*.{js,ts,tsx}\"",
     "prepublishOnly": "./scripts/check-tarball.sh"