react-native-facefusion 0.1.0

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2026 Saad
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,259 @@
+# react-native-facefusion
+
+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.
+
+## Requirements — read this first
+
+- **Android only.** There is no iOS implementation. This runs on Qualcomm's Hexagon
+  DSP via QNN, which Apple silicon has no equivalent path for.
+- **Android 12+ (`minSdk 31`), `arm64-v8a` only.**
+- **A Snapdragon chip with a Hexagon NPU**, and one whose Hexagon architecture your
+  build actually bundles a runtime for. The example app ships **v68, v69, v73, v75, v79
+  and v81** — roughly Snapdragon 888 through 8 Elite Gen 5. The architecture is a
+  property of the silicon and is chosen independently of the model tier, so a build
+  missing that pair cannot reach the DSP on that phone at all; `probeDevice()` reports
+  which ones the build contains. v66 and older cannot be supported: that generation
+  predates the HTP backend entirely and QAIRT ships it only as a `QnnDsp` build.
+- On anything else — an emulator included, since no emulator has a Hexagon DSP — every
+  call still resolves, but the NPU-backed ones report `ok: false` rather than hanging or
+  crashing.
+- **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).
+
+## Install
+
+Three steps, not one — a plain `npm install` is not enough on its own.
+
+```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.
+./node_modules/react-native-facefusion/scripts/fetch-upstream.sh
+```
+
+```sh
+# 2. 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
+# the headers relative to its own source dir, so they have to live here:
+#
+#   PKG=node_modules/react-native-facefusion/android/src/main
+#
+#   include/QNN/                                -> $PKG/cpp/include/QNN/
+#   lib/aarch64-android/libQnnHtp.so            -> $PKG/jniLibs/arm64-v8a/
+#   lib/aarch64-android/libQnnSystem.so         -> $PKG/jniLibs/arm64-v8a/
+#   lib/aarch64-android/libQnnHtpV*Stub.so      -> $PKG/jniLibs/arm64-v8a/   (ALL of them)
+#   lib/hexagon-v*/unsigned/libQnnHtpV*Skel.so  -> $PKG/jniLibs/arm64-v8a/   (ALL of them)
+#
+# Copy EVERY architecture, not a chosen few. libQnnHtp.so picks the Stub/Skel pair from
+# the chip's own Hexagon architecture, not from the model tier -- so a missing pair means
+# "deviceCreate failed -- the DSP is not reachable from this process" on every phone of
+# that generation, however many models are downloaded. ~12 MB per architecture.
+#
+# Leave out libQnnHtpPrepare.so -- it's the on-device graph compiler (82 MB) and the
+# 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
+missing piece.
+
+**Your app's `android/build.gradle` needs `minSdkVersion = 31`.** A fresh React Native
+app is `24`, and this package builds against your value, not its own — so leaving it at
+24 produces an APK that installs on Android 7 and crashes there instead of reporting an
+unsupported device. The library refuses to build below 31, so the manifest merge fails
+with a message naming it rather than building something that cannot work:
+
+```groovy
+// android/build.gradle
+buildscript {
+    ext {
+        minSdkVersion = 31 // required -- the default 24 is below what this package supports
+    }
+}
+```
+
+Your app's `android/app/build.gradle` also needs:
+
+```groovy
+android {
+    packagingOptions {
+        jniLibs {
+            useLegacyPackaging = true // required -- the QNN backend is dlopen'd by
+                                       // absolute path, which needs real files on
+                                       // disk, not compressed inside the APK
+        }
+    }
+}
+```
+
+### Why the extra steps
+
+Neither piece can legally ship inside this package:
+
+- **The QNN runtime** is Qualcomm's, under a licence that permits redistribution
+  "as incorporated in your software application" but not "on a standalone basis" —
+  an app may bundle it, an npm package may not.
+- **The C++ engine** this module wraps ([`AbrahamPaulJ/facefusion-mobile`](https://github.com/AbrahamPaulJ/facefusion-mobile))
+  ships no LICENSE file, which defaults to all-rights-reserved. It is vendored
+  unmodified and fetched at a pinned commit by `scripts/fetch-upstream.sh`, never
+  committed to git history.
+
+## Usage
+
+```ts
+import {
+  probeDevice,
+  getModelStatus,
+  downloadModels,
+  onModelDownloadProgress,
+  swapPhoto,
+  swapVideo,
+  detectSourceFaces,
+  detectTargetFaces,
+  saveToGallery,
+  FacefusionPreview,
+} from 'react-native-facefusion';
+
+// Check the chip and see what's already on disk.
+const device = await probeDevice();       // { ok, tier, tierChain, arch, vtcmMb, ... }
+const status = await getModelStatus();    // { ready, missing, tier, hasEnhancer, ... }
+
+// Download the model set for this device's tier (~300+ MB, resumable, SHA256-verified).
+if (!status.ready) {
+  const sub = onModelDownloadProgress((p) => console.log(p.fileIndex, p.fileCount));
+  await downloadModels();
+  sub.remove();
+}
+
+// Swap a face into a photo. Paths in, path out -- no pixels cross the JS bridge.
+const result = await swapPhoto(sourcePath, targetPath, outputPath, {
+  faceEnhance: true,
+});
+// { outputPath, faceCount, tier }
+
+// Same call shape for video -- runs behind a foreground service.
+const videoResult = await swapVideo(sourcePath, targetPath, outputPath, {
+  targetFps: 15, // cap the frame rate to trade quality for speed
+});
+// { outputPath, frameCount, faceFrameCount, tier, fps, hasAudio }
+
+// Multiple faces in the source or target? Detect first, let the user pick, then pass
+// the chosen box back into swapPhoto/swapVideo as sourceFaceBox / targetFaceBox.
+// Pass the SAME options you pass to the swap. A picker that finds a face the swap then
+// rejects is a picker that lies -- and these thresholds reach the pipeline through its
+// init, so detecting at different values re-opens every model graph twice per swap.
+const sourceFaces = await detectSourceFaces(sourcePath, { detectorScore: 0.5 });
+const targetFaces = await detectTargetFaces(targetPath, { detectorScore: 0.5 });
+
+// Copy an output into the Photos app -- swapPhoto/swapVideo write to your own
+// app's private storage, not somewhere the user can see without this.
+const uri = await saveToGallery(result.outputPath, 'image/jpeg');
+```
+
+```tsx
+// Watch the swap happen live -- a native Surface the pipeline draws into directly,
+// not a stream of frames sent over the bridge.
+<FacefusionPreview style={{ width: '100%', aspectRatio: 16 / 9 }} />
+```
+
+Full option/result shapes (`SwapOptions`, `DeviceProbeResult`, `ModelStatus`, …) are
+documented on the TypeScript types themselves — your editor will show them.
+
+Only one swap or video job runs at a time; a second call rejects with `E_BUSY` rather
+than queuing. `swapVideo` can be stopped mid-run with `cancelVideoSwap()`.
+
+## Content gate
+
+Every swap checks its target against upstream FaceFusion's NSFW content gate before
+processing it, and refuses with `E_CONTENT` if it's flagged. This is not optional or
+configurable from JS — a safeguard a caller can turn off is not a safeguard.
+
+Known limits of this port, stated plainly rather than hidden:
+
+- It gates on one model (`nsfw_2`) where upstream votes across three — the other two
+  total 461 MB against this package's ~266 MB, and which way a single model errs
+  against the full ensemble is unmeasured.
+- On every chip tier except v79, the gate itself runs quantised, which measured
+  ~0.087 mean closer to flagging than the full-precision model, 16 of 16 held-out
+  frames in the same direction. Not compensated for — reported here instead.
+- A still image is one check; a video samples one frame per second and refuses if
+  more than 10% of samples are flagged.
+- A failure to run the check (a native error, not a flagged result) is always treated
+  as a refusal, never as "allow."
+
+Both branches are verified on real hardware (Snapdragon 8 Elite, tier v79): every
+clean test swap passes the same check, and an NSFW test image scored ~0.8 against the
+0.25 threshold and was refused with `E_CONTENT` before the swap ran or any output file
+was written (2026-09-11). Not yet exercised on hardware: a video refused on the
+aggregate 10% rate, and the native-error-means-refusal path.
+
+## Known issues
+
+- **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
+  once, so an uncapped 50 MP photo — the main camera on the phones this library
+  requires — needs ~950 MB and cannot run at all. Videos are unaffected; they process
+  at the clip's own resolution.
+- **The same photo can be detected on one chip and not on another.** Every tier ships the
+  same 4.0 MB `yoloface` detector, but as a *separately compiled QNN context binary per
+  Hexagon architecture* — the weights are identical, the compiled graph is not. The same
+  face therefore scores differently on a v68 chip than on a v79 one, and `detectorScore`
+  is a hard cutoff (`score <= detectorScore` is dropped outright), so a face scoring 0.46
+  on a Snapdragon 8 Gen 1 and 0.58 on an 8 Elite is found on exactly one of the two.
+  Observed 2026-09-14: the same photo detected and swapped on an S25 (tier v79) and was
+  not detected on an S22 (tier v68); other photos worked on both.
+
+  This is not something the library can normalise away — there is no per-tier calibration
+  to apply and no ground truth on the device to calibrate against. What it does instead is
+  make the threshold reachable: `detectorScore` is an option on `swapPhoto`, `swapVideo`,
+  `detectSourceFaces` and `detectTargetFaces` alike. **Expose it in your UI rather than
+  treating an empty detection result as final** — around `0.3` recovers most of the gap,
+  at the cost of more false positives on busy backgrounds. The example app shows the
+  pattern: zero faces is reported with the current threshold named, not as silence.
+
+- **Qualcomm's Hexagon skel libraries are not 16 KB page-size aligned.** Android 15+ warns when
+  an APK contains a native library aligned to the old 4 KB page assumption. Measured
+  across all 25 libraries in a release build: 19 are aligned correctly, including this
+  package's own `libffnative.so` and every React Native and Hermes library. The six
+  that are not are `libQnnHtpV*Skel.so` — one per Hexagon architecture — which ship
+  prebuilt in Qualcomm's
+  QAIRT SDK and can only be fixed upstream. They are Hexagon DSP images loaded over
+  fastrpc rather than mapped into the app's address space, so this is a packaging-check
+  warning rather than a loading failure — but the warning is shown to users on Android
+  15+, and it will not go away until Qualcomm ships aligned builds.
+
+## Performance
+
+Every number below is measured on real hardware, dated, and says exactly what was
+run. None of it is upstream's own figures, and nothing here is an estimate.
+
+| Device | Resolution | Face enhancer | fps | Date |
+|---|---|---|---|---|
+| Samsung SM-S931B (Snapdragon 8 Elite, tier v79) | 1280×720 | off | **9.8** | 2026-09-09 |
+
+This is one pipeline's own decode→swap→encode loop end to end, not a swap-graph-only
+figure. Expect it to vary by device tier, resolution, and whether the enhancer runs.
+
+## Contributing
+
+- [Development workflow](CONTRIBUTING.md#development-workflow)
+- [Sending a pull request](CONTRIBUTING.md#sending-a-pull-request)
+- [Code of conduct](CODE_OF_CONDUCT.md)
+
+## License
+
+MIT
+
+---
+
+Made with [create-react-native-library](https://github.com/callstack/react-native-builder-bob)

package/android/build.gradle

@@ -0,0 +1,129 @@
+buildscript {
+  ext.Facefusion = [
+    kotlinVersion: "2.0.21",
+    minSdkVersion: 31,
+    compileSdkVersion: 36,
+    ndkVersion: "27.1.12297006"
+  ]
+
+  ext.getExtOrDefault = { prop ->
+    if (rootProject.ext.has(prop)) {
+      return rootProject.ext.get(prop)
+    }
+
+    return Facefusion[prop]
+  }
+
+  repositories {
+    google()
+    mavenCentral()
+  }
+
+  dependencies {
+    classpath "com.android.tools.build:gradle:8.7.2"
+    // noinspection DifferentKotlinGradleVersion
+    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:${getExtOrDefault('kotlinVersion')}"
+  }
+}
+
+
+apply plugin: "com.android.library"
+apply plugin: "kotlin-android"
+
+apply plugin: "com.facebook.react"
+
+android {
+  namespace "com.facefusion"
+
+  compileSdkVersion getExtOrDefault("compileSdkVersion")
+  ndkVersion getExtOrDefault("ndkVersion")
+
+  // arm64 only. Every device this package supports is a 64-bit Snapdragon, and the QNN
+  // runtime we dlopen ships no other ABI -- building x86/armeabi would produce a
+  // libffnative.so that can never find a backend.
+  defaultConfig {
+    // A FLOOR, not a preference. getExtOrDefault checks rootProject.ext first, and every
+    // React Native app template defines ext.minSdkVersion -- so a consumer's value ALWAYS
+    // wins and the `minSdkVersion: 31` default above is dead in any real install. A fresh
+    // RN app is 24, which built this library silently at 24 in a clean-consumer test:
+    // no error, an APK that installs on Android 7, and API-31+ calls in our own Kotlin
+    // (startForeground's 3-arg overload, for one) waiting to throw NoSuchMethodError at
+    // runtime instead of ADR-0006's designed "unsupported device" answer.
+    //
+    // max() keeps a consumer's HIGHER floor and refuses a lower one. The consumer then
+    // fails at manifest merge with a message naming this library and the number to
+    // raise -- which is the outcome we want: loud, at build time, actionable.
+    minSdkVersion Math.max(getExtOrDefault("minSdkVersion") as int, 31)
+    ndk {
+      abiFilters "arm64-v8a"
+    }
+    externalNativeBuild {
+      cmake {
+        // c++_shared, not c++_static: several .so files in one process must share one
+        // copy of the STL, and libffnative.so is not the only native library here.
+        arguments "-DANDROID_STL=c++_shared"
+      }
+    }
+  }
+
+  externalNativeBuild {
+    cmake {
+      path "src/main/cpp/CMakeLists.txt"
+      version "3.22.1"
+    }
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_17
+    targetCompatibility JavaVersion.VERSION_17
+  }
+}
+
+dependencies {
+  implementation "com.facebook.react:react-android"
+}
+
+// ---------------------------------------------------------------------------
+// Content gate stub (ADR-0003). ContentGate.kt is the one file a personal, gate-free
+// build deletes. PhotoSwap.kt/VideoSwap.kt call it as an ordinary Kotlin symbol, so
+// deleting it without this task would just fail the library's own compile -- not
+// produce the working "-dev" build the ADR describes. When the real file is present
+// this generates nothing (and removes any stub from a previous build); when it is
+// absent it generates a no-op stand-in with the same public surface, in a directory
+// the real file's package never lives in, so there is never a duplicate-class clash.
+// ---------------------------------------------------------------------------
+def contentGateFile = file("src/main/java/com/facefusion/ContentGate.kt")
+def contentGateStubDir = file("$buildDir/generated/contentGateStub")
+
+tasks.register("generateContentGateStub") {
+  doLast {
+    def stubFile = new File(contentGateStubDir, "com/facefusion/ContentGate.kt")
+    if (contentGateFile.exists()) {
+      if (stubFile.exists()) stubFile.delete()
+      return
+    }
+    stubFile.parentFile.mkdirs()
+    stubFile.text = '''package com.facefusion
+
+// Generated by :react-native-facefusion's build.gradle because
+// src/main/java/com/facefusion/ContentGate.kt is absent -- the personal, gate-free
+// build (ADR-0003). A no-op with the real file's public surface, so callers need no
+// change either way.
+object ContentGate {
+  class Refused(message: String, val isQuantised: Boolean) : Exception(message)
+
+  fun checkFrame(bgr: ByteArray, w: Int, h: Int) {}
+
+  class VideoSampler {
+    fun sample(bgr: ByteArray, w: Int, h: Int) {}
+    fun finish() {}
+  }
+}
+'''
+  }
+}
+
+android.sourceSets.main.kotlin.srcDirs += contentGateStubDir
+tasks.matching { it.name ==~ /compile.*Kotlin/ }.configureEach {
+  dependsOn("generateContentGateStub")
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,66 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+
+    <!--
+      The models are ~317 MB and are not in the APK: several carry licences that are not
+      ours to sublicense, so they are downloaded on first run (docs/04-models.md). Declared
+      by the library rather than left to the app, because a consumer that forgets it gets a
+      SecurityException from deep inside the downloader instead of a clear failure.
+    -->
+    <uses-permission android:name="android.permission.INTERNET" />
+    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
+
+    <!--
+      A video swap runs for seconds to minutes (docs/plan/README.md, Phase 7), long enough
+      that Android kills a plain background process doing it. FOREGROUND_SERVICE is required
+      to start any foreground service at all from API 28; FOREGROUND_SERVICE_MEDIA_PROCESSING
+      is the specific type a foreground service must declare from targetSdk 34, and it is the
+      one that actually names what VideoSwapService is. POST_NOTIFICATIONS is a runtime
+      prompt from API 33: without it granted the service still runs (the OS does not revoke
+      startForeground over a missing notification permission), it just shows no notification.
+      A real consumer app should ask for it; this package's own example app does not yet
+      (Phase 9's picker/permissions UI), so this is a known, documented gap rather than a
+      silent one.
+    -->
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PROCESSING" />
+    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+
+    <application>
+
+        <!--
+          VideoSwapService is a notification shell, not the worker: see its class doc. It
+          never binds and is only ever started/stopped by FacefusionModule, hence
+          exported="false".
+        -->
+        <service
+            android:name=".VideoSwapService"
+            android:exported="false"
+            android:foregroundServiceType="mediaProcessing" />
+        <!--
+          The Hexagon DSP is reached over fastrpc through libcdsprpc.so, which lives on the
+          VENDOR partition and is listed in /vendor/etc/public.libraries.txt on Qualcomm
+          devices. From targetSdk 31 an app must ALSO name a vendor library here, or the
+          dynamic linker will not put it in the app's namespace, and the QNN stub that
+          needs it fails to load:
+
+              dlopen failed: library "libcdsprpc.so" not found:
+              needed by .../lib/arm64/libQnnHtpV79Stub.so in namespace clns-9
+
+          which surfaces four layers up as "Failed to load skel, error: 4000" and then a
+          failed deviceCreate, an error that says nothing about the actual cause.
+
+          required="false" on BOTH, which is where this differs from an app that only ever
+          ships to Snapdragon. required="true" makes the library absent = the app will not
+          install, and this package is a dependency inside somebody else's app that may
+          well also ship to Pixels and Exynos. Those devices should install, run, and be
+          told "no NPU here" by probeDevice() (ADR-0006), not fail at the Play Store.
+
+          Declared here rather than in the consumer's manifest for the same reason as the
+          permissions above: a consumer who does not know to add it gets a four-layer-deep
+          4000 instead of a working NPU. Manifest merging puts it in their app.
+        -->
+        <uses-native-library android:name="libcdsprpc.so" android:required="false" />
+        <uses-native-library android:name="libadsprpc.so" android:required="false" />
+    </application>
+
+</manifest>

package/android/src/main/cpp/CMakeLists.txt

@@ -0,0 +1,73 @@
+# Builds libffnative.so -- the on-device inference engine.
+#
+# The sources are upstream's, vendored unmodified under third_party/ (ADR-0004). This
+# file is ours because the paths differ in this repo: their sources sit beside their
+# CMakeLists, ours sit two directories away, and the QNN headers live under our
+# android/src/main/cpp/include/. The compile flags and the link line below are
+# identical to theirs on purpose -- see third_party/facefusion-mobile/NOTICE.
+cmake_minimum_required(VERSION 3.22.1)
+project(ffnative)
+
+set(FF_UPSTREAM "${CMAKE_CURRENT_SOURCE_DIR}/../../../../third_party/facefusion-mobile/cpp")
+
+# Both of these are fetched, not committed, and both fail here rather than 200 lines
+# into a compiler error nobody can read.
+#
+# These two messages point at README.md's "Install" section, NOT at docs/ -- docs/ is
+# the local engineering record and ships in zero files of the npm package, so a
+# consumer told to read docs/03-setup.md is told to read a file they do not have. This
+# is the likeliest error any new installer hits (a plain `npm install` leaves both
+# pieces absent, and a later `npm install` wipes them again), so it has to be
+# actionable from inside node_modules with nothing else to hand.
+if(NOT EXISTS "${FF_UPSTREAM}/ffjni.cpp")
+  message(FATAL_ERROR
+    "Upstream C++ engine is missing from third_party/facefusion-mobile/cpp/.\n"
+    "It is not shipped in this package: upstream publishes no licence.\n"
+    "Run:  ./node_modules/react-native-facefusion/scripts/fetch-upstream.sh\n"
+    "See README.md -> Install, step 1.")
+endif()
+
+if(NOT EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/include/QNN/QnnBackend.h")
+  message(FATAL_ERROR
+    "Qualcomm QNN headers are missing from android/src/main/cpp/include/QNN/.\n"
+    "The QAIRT SDK is proprietary and cannot be shipped in this package; copy it in\n"
+    "yourself, into THIS directory (not your app's).\n"
+    "See README.md -> Install, step 2, for the download and the exact file list.")
+endif()
+
+# The same four objects upstream's app and headless CLI both link.
+add_library(ffnative SHARED
+    "${FF_UPSTREAM}/ffjni.cpp"
+    "${FF_UPSTREAM}/ffpipe.cpp"
+    "${FF_UPSTREAM}/ffcv.cpp"
+    "${FF_UPSTREAM}/ffqnn.cpp")
+
+# Three roots: the vendored sources include their own headers unqualified ("ffcv.h");
+# ffqnn.cpp includes "QNN/QnnBackend.h"; and the SDK's own sub-headers include their
+# siblings unqualified, so include/QNN has to be on the path as well as include.
+target_include_directories(ffnative PRIVATE
+    "${FF_UPSTREAM}"
+    "${CMAKE_CURRENT_SOURCE_DIR}/include"
+    "${CMAKE_CURRENT_SOURCE_DIR}/include/QNN")
+
+# No QNN library is linked. libQnnHtp.so / libQnnSystem.so are dlopen'd at runtime by
+# absolute path out of the app's nativeLibraryDir, which is why this builds against the
+# headers alone and why useLegacyPackaging must stay true (docs/01-architecture.md).
+target_link_libraries(ffnative android log dl)
+target_compile_options(ffnative PRIVATE -O3 -fvisibility=hidden -Wall)
+
+# 16 KB page size (Android 15+). Devices with 16 KB pages cannot load a library whose
+# LOAD segments are aligned to the old 4 KB assumption, and Android 15 shows the user a
+# compatibility warning for any APK containing one.
+#
+# Measured on the v0.1.0 release APK before this line existed: 15 of 19 libraries were
+# already aligned to 0x4000, INCLUDING every React Native and Hermes library -- so the
+# toolchain is not the problem and the note in docs/MEMORY.md claiming otherwise was
+# wrong. Exactly four were 0x1000: this library, and Qualcomm's three
+# libQnnHtpV{73,79,81}Skel.so.
+#
+# This flag fixes ours. The three Skel files are prebuilt binaries shipped in the QAIRT
+# SDK, so they can only be fixed by Qualcomm -- and they are Hexagon DSP images loaded
+# over fastrpc rather than mapped into the app's own address space, so the host-side
+# alignment is about the packaging check rather than about whether they can run.
+target_link_options(ffnative PRIVATE "-Wl,-z,max-page-size=16384")

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

@@ -0,0 +1,112 @@
+package com.facefusion
+
+import android.graphics.Bitmap
+import android.graphics.BitmapFactory
+
+/**
+ * Decoding a photo without letting a big one kill the process.
+ *
+ * Every image path in this library used to call `BitmapFactory.decodeFile` with no size
+ * limit, which crashes on photos that modern phones actually take. The arithmetic is the
+ * whole reason this file exists, so it is written down rather than left to be rediscovered:
+ *
+ * [PhotoSwap] holds, simultaneously, for a `w x h` target — the decoded `Bitmap`
+ * (`w*h*4`), the `IntArray` of pixels handed to `argbToBgr` (`w*h*4`), the packed BGR
+ * buffer (`w*h*3`), the `IntArray` coming back from `bgrToArgb` (`w*h*4`) and the output
+ * `Bitmap` (`w*h*4`). That is **~19 bytes per pixel**, against a heap this project has
+ * measured topping out near 220 MB on a Snapdragon 8 Elite.
+ *
+ * | Photo | Pixels | Peak at ~19 B/px |
+ * |---|---|---|
+ * | 2560x1920 | 4.9 MP | ~93 MB — fine |
+ * | 4096x3072 | 12.6 MP | ~239 MB — **crashes** |
+ * | 8160x6120 (a 50 MP phone) | 50 MP | ~950 MB — **crashes immediately** |
+ *
+ * So this is not an exotic-input problem: a 50 MP main camera is standard on the exact
+ * phones this library requires, and a user picking a photo their own phone took was
+ * enough to kill it.
+ *
+ * **The downscale has to happen during decode, not after.** `inSampleSize` tells
+ * `BitmapFactory` to subsample as it reads, so the full-size bitmap is never allocated.
+ * Decoding first and calling `createScaledBitmap` afterwards would OOM on the decode
+ * itself, which is exactly where the original crash was.
+ */
+object BitmapDecode {
+
+  /**
+   * Cap for an image that only contributes an **identity**, never pixels to the output.
+   *
+   * The source face is warped down to 112x112 for the recogniser (`ffpipe.cpp`, the
+   * `arcface` stage), so resolution beyond a point contributes literally nothing — this
+   * is free, not a tradeoff.
+   */
+  const val SOURCE_MAX = 1920
+
+  /**
+   * Cap for an image that **becomes** the output, where resolution is real quality.
+   *
+   * Deliberately higher than [SOURCE_MAX] for that reason, and still comfortably inside
+   * the budget above. A swap output at 2560 on the long edge is past what any phone screen
+   * or social upload will show; the alternative on a 50 MP input is not "sharper", it is
+   * "crash".
+   */
+  const val TARGET_MAX = 2560
+
+  /**
+   * Decodes the image at [path], subsampled during decode so its long edge does not
+   * greatly exceed [maxDimension].
+   *
+   * `inSampleSize` only takes powers of two, so the result can be up to ~2x under the cap
+   * rather than landing exactly on it. That is the right trade: powers of two are the case
+   * `BitmapFactory` decodes without an extra resample step, and being under the cap is
+   * never the failure.
+   *
+   * ARGB_8888 is forced explicitly — `decodeFile` already defaults to it, but leaving it
+   * implicit invites a HARDWARE bitmap the moment someone switches this to `ImageDecoder`,
+   * and `getPixels()` throws on those.
+   */
+  fun decode(path: String, maxDimension: Int): Bitmap =
+    decodeOrNull(path, maxDimension)
+      ?: throw IllegalArgumentException("Could not decode image: $path")
+
+  /**
+   * As [decode], but answers `null` instead of throwing when [path] is not a decodable
+   * image.
+   *
+   * [TargetFaces] needs this distinction: a target may legitimately be a *video*, and it
+   * tells the two apart by trying a still decode first and falling through on failure. A
+   * throwing decode would abort before the video path was ever reached.
+   */
+  fun decodeOrNull(path: String, maxDimension: Int): Bitmap? {
+    // Pass one: read the header only. `inJustDecodeBounds` allocates no pixels, so this is
+    // safe on an image far too big to actually decode -- which is the entire point.
+    val bounds = BitmapFactory.Options().apply { inJustDecodeBounds = true }
+    BitmapFactory.decodeFile(path, bounds)
+    if (bounds.outWidth <= 0 || bounds.outHeight <= 0) return null
+
+    val options = BitmapFactory.Options().apply {
+      inPreferredConfig = Bitmap.Config.ARGB_8888
+      inSampleSize = sampleSizeFor(bounds.outWidth, bounds.outHeight, maxDimension)
+    }
+    return BitmapFactory.decodeFile(path, options)
+  }
+
+  /**
+   * The smallest power of two that brings `max(w, h)` to [maxDimension] **or below**.
+   *
+   * Note the "or below", and that it is not the idiom most Android samples use. The common
+   * one is `while (longest / 2 >= requested) sample *= 2`, which deliberately stops at the
+   * last size still *larger* than the request, so the caller can scale down afterwards
+   * with a good-quality resample. That leaves a result up to 2x the request — and here
+   * that is the difference between working and not: a 50 MP photo against a 2560 cap comes
+   * out 4080 wide under that idiom, which is ~237 MB peak and the exact crash this class
+   * exists to prevent. We want a memory ceiling, not a quality floor.
+   */
+  fun sampleSizeFor(width: Int, height: Int, maxDimension: Int): Int {
+    require(maxDimension > 0) { "maxDimension must be positive" }
+    var sample = 1
+    val longest = maxOf(width, height)
+    while (longest / sample > maxDimension) sample *= 2
+    return sample
+  }
+}