react-native-facefusion 0.1.0

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

@@ -0,0 +1,351 @@
+package com.facefusion
+
+import android.content.Context
+import android.net.ConnectivityManager
+import android.net.NetworkCapabilities
+import android.util.Log
+import java.io.File
+import java.io.FileOutputStream
+import java.io.IOException
+import java.net.HttpURLConnection
+import java.net.URL
+import java.security.MessageDigest
+
+/** One file in the hosted manifest. */
+data class ModelFile(val name: String, val bytes: Long, val sha256: String)
+
+/** The best tier the manifest actually publishes for this chip, and its files. */
+data class ModelManifest(val tier: String, val files: List<ModelFile>)
+
+/** A snapshot of a download in flight. Bytes are across the whole set, not the current file. */
+data class DownloadProgress(
+  val tier: String,
+  val fileIndex: Int,
+  val fileCount: Int,
+  val name: String,
+  val doneBytes: Long,
+  val totalBytes: Long,
+)
+
+/** Thrown by [ModelDownload.run] when [ModelDownload.cancel] was called. The `.part` files stay. */
+class DownloadCancelled : IOException("Cancelled")
+
+/**
+ * Fetching the NPU context binaries for this device's tier.
+ *
+ * The models are not in the APK and never will be: the set is ~317 MB, and several of the
+ * models carry licences that are not ours to sublicense (`docs/04-models.md`). They are
+ * hosted on Hugging Face and pulled on first run — the same thing FaceFusion itself does.
+ *
+ * Two properties this has to have, both of which upstream learned the hard way:
+ *
+ *  * **Resumable.** A 206 MB file over a phone link is not an atomic operation. Bytes land
+ *    in `<name>.part` and a retry continues from its length with an HTTP Range request.
+ *  * **Verified.** A context binary that is short does not fail loudly — it fails at load,
+ *    four layers away from the cause, inside Qualcomm's runtime. So every file is SHA-256'd
+ *    against the manifest before it is allowed to take its real name.
+ */
+object ModelDownload {
+
+  /**
+   * Versioned per *model* revision, not per app version — the `-0.1.0` is upstream's model
+   * revision and stays put while the app moves, so an old build keeps resolving the files
+   * it was tested against.
+   */
+  const val REPO = "AbrahamPJ/facefusion-mobile-models-0.1.0"
+
+  private const val BASE = "https://huggingface.co/$REPO/resolve/main/"
+  private const val TAG = "ffmodels"
+
+  /**
+   * What a manifest entry's `name` is allowed to be: a bare `.bin` filename, nothing else.
+   *
+   * The name arrives from a **remote** JSON and is then used both as a URL suffix and as
+   * `File(dir, name)`. Without this, a `name` of `../../shared_prefs/something` would write
+   * outside the models directory — and SHA-256 verification is no defence at all here,
+   * because the same manifest that supplies the path also supplies the expected hash.
+   *
+   * This is not a hypothetical about upstream's intentions; it is that this is a library
+   * other people ship, the host is a third party neither they nor we control, and the check
+   * costs one regex. A rejected entry throws rather than being skipped: a downloader that
+   * quietly ignores part of the set produces a half-tier that fails later inside Qualcomm's
+   * runtime, which is the exact failure mode this file's header says to avoid.
+   */
+  private val SAFE_NAME = Regex("""^[A-Za-z0-9][A-Za-z0-9._-]*\.bin$""")
+  private const val CONNECT_TIMEOUT_MS = 30_000
+  private const val READ_TIMEOUT_MS = 60_000
+  private const val BUFFER = 1 shl 16
+
+  /** How often progress is reported. The UI cannot use more, and each tick crosses to JS. */
+  private const val TICK_MS = 250L
+
+  @Volatile
+  private var cancelled = false
+
+  /** Asks the run in flight to stop. Idempotent, and safe to call when nothing is running. */
+  fun cancel() {
+    cancelled = true
+  }
+
+  /** True when the connection is metered, so a caller can warn before spending ~317 MB. */
+  fun isMetered(context: Context): Boolean {
+    val cm = context.getSystemService(ConnectivityManager::class.java) ?: return false
+    val caps = cm.getNetworkCapabilities(cm.activeNetwork) ?: return false
+    return !caps.hasCapability(NetworkCapabilities.NET_CAPABILITY_NOT_METERED)
+  }
+
+  /**
+   * Which files to fetch, from the hosted manifest. Network call; never on the main thread.
+   *
+   * Takes the whole tier **chain** rather than one tier and returns the best entry the
+   * manifest actually publishes. The two differ whenever the app knows about an arch whose
+   * binaries are not hosted — which is the normal state for a while after a new chip lands,
+   * and is not hypothetical: v81 is in the chain of every 8 Elite Gen 5 and was withheld
+   * from the manifest on 2026-08-30 because the binaries had never been run on v81 silicon.
+   * Resolving against the manifest turns that from "no models published for tier v81" into
+   * a working v73 install. See ADR-0007.
+   */
+  fun manifestFor(chain: List<String>): ModelManifest {
+    require(chain.isNotEmpty()) { "no tier requested" }
+
+    val tiers = org.json.JSONObject(get(BASE + "manifest.json")).getJSONObject("tiers")
+
+    // The best tier that is both published AND actually usable. "Published" is not enough:
+    // as of 2026-09-11 upstream publishes v81 whose only gate-shaped file is `nsfwq2`,
+    // which `Pipeline::init` never opens -- so an 8 Elite Gen 5 that downloaded v81 would
+    // fetch 305 MB and then fail init outright with "no content gate", which is a hard
+    // failure and not a recoverable one.
+    //
+    // Falling through to the next tier in the chain instead is exactly the machinery
+    // ADR-0007 exists for, keyed on "can the pipeline use this" rather than the weaker
+    // "does the manifest mention it". The native side then picks the same tier on its own,
+    // because it probes which tier's files are actually on disk.
+    val tier = chain.firstOrNull { tiers.has(it) && hasUsableGate(tiers, it) }
+      ?: throw IOException(
+        "no usable models published for any of ${chain.joinToString(", ")} — a tier must " +
+          "ship ${ModelPaths.GATE.joinToString(" or ")} for the content gate to run"
+      )
+
+    val files = tiers.getJSONObject(tier).getJSONArray("files")
+    return ModelManifest(
+      tier = tier,
+      files = (0 until files.length()).map {
+        val o = files.getJSONObject(it)
+        val name = o.getString("name")
+        // Validated here, at the parse boundary, so nothing downstream can ever hold an
+        // unsafe name -- see [SAFE_NAME].
+        if (!SAFE_NAME.matches(name)) {
+          throw IOException("manifest for $tier names an unacceptable file: '$name'")
+        }
+        ModelFile(name, o.getLong("bytes"), o.getString("sha256"))
+      }
+        // Only what `Pipeline::init` actually opens -- see [ModelPaths.OPENED_BY_PIPELINE].
+        // Filtered here, at the one place the manifest is read, so the byte totals, the
+        // progress events, `notPresent` and the log line below all agree about what this
+        // run is for. Filtering later would have the progress bar counting files nothing
+        // fetches.
+        .filter { isOpenedByPipeline(it.name, tier) },
+    )
+  }
+
+  /**
+   * Whether [tier]'s published file list includes a content gate the native layer opens.
+   *
+   * A tier without one cannot start at all — see the call site in [manifestFor] — so this
+   * is a precondition for choosing a tier, not a detail of what to download from it.
+   */
+  private fun hasUsableGate(tiers: org.json.JSONObject, tier: String): Boolean {
+    val files = tiers.getJSONObject(tier).optJSONArray("files") ?: return false
+    val names = (0 until files.length()).map { files.getJSONObject(it).optString("name") }
+    return ModelPaths.GATE.any { "${it}_$tier.bin" in names }
+  }
+
+  /**
+   * Whether `name` is one of the models the native pipeline opens, for this [tier].
+   *
+   * Manifest names are `<base>_<tier>.bin`, so the tier suffix is stripped and the base
+   * checked against [ModelPaths.OPENED_BY_PIPELINE]. A file for a *different* tier would
+   * not match and is skipped, which is correct — the manifest only lists one tier's files
+   * per tier object, but being explicit costs nothing and makes a malformed manifest
+   * under-fetch rather than fetch the wrong tier's 206 MB swapper.
+   */
+  private fun isOpenedByPipeline(name: String, tier: String): Boolean {
+    val suffix = "_$tier.bin"
+    if (!name.endsWith(suffix)) return false
+    return name.removeSuffix(suffix) in ModelPaths.OPENED_BY_PIPELINE
+  }
+
+  /**
+   * Which of [files] are not already present at their full length in [dir].
+   *
+   * Length only, not hash: re-reading 317 MB to decide whether to download it would cost
+   * seconds on every launch. The hash is checked once, when the file is committed, and a
+   * file that is the right length but wrong content would have failed that check and never
+   * been renamed.
+   */
+  fun notPresent(dir: File, files: List<ModelFile>): List<ModelFile> =
+    files.filter { f ->
+      val onDisk = File(dir, f.name)
+      !onDisk.canRead() || onDisk.length() != f.bytes
+    }
+
+  /**
+   * Download everything missing for the best published tier in [chain].
+   *
+   * Blocking — call it from a worker thread. Returns the tier that was fetched. Throws
+   * [DownloadCancelled] if cancelled, or an [IOException] naming the file that failed.
+   */
+  fun run(dir: File, chain: List<String>, onProgress: (DownloadProgress) -> Unit): String {
+    cancelled = false
+
+    val manifest = manifestFor(chain)
+    val todo = notPresent(dir, manifest.files)
+
+    // Say what is about to be fetched and what was kept. A resumed download that re-fetches
+    // a 206 MB file it already had and one that fetches only what is missing look identical
+    // from outside -- a progress bar and a wait.
+    Log.i(
+      TAG,
+      "tier ${manifest.tier}: ${manifest.files.size} files, fetching ${todo.map { it.name }}, " +
+        "keeping ${manifest.files.filterNot { f -> todo.any { it.name == f.name } }.map { it.name }}",
+    )
+
+    val totalBytes = todo.sumOf { it.bytes }
+    var doneBytes = 0L
+
+    for ((i, file) in todo.withIndex()) {
+      throwIfCancelled()
+      val startedAt = doneBytes
+      fetch(dir, file) { fileBytes ->
+        doneBytes = startedAt + fileBytes
+        onProgress(
+          DownloadProgress(manifest.tier, i + 1, todo.size, file.name, doneBytes, totalBytes)
+        )
+      }
+      doneBytes = startedAt + file.bytes
+    }
+
+    // One final tick so a caller that only ever sees ticks lands on 100% rather than on
+    // whatever the last 250 ms boundary happened to be.
+    onProgress(
+      DownloadProgress(manifest.tier, todo.size, todo.size, "", totalBytes, totalBytes)
+    )
+    return manifest.tier
+  }
+
+  /**
+   * One file, resuming its `.part` if there is one.
+   *
+   * [onBytes] is called with the bytes transferred *for this file*, throttled; the caller
+   * adds the running total. The temp file only takes its real name after the hash matches,
+   * so a partial or corrupt download can never present itself to the loader as a model.
+   */
+  private fun fetch(dir: File, file: ModelFile, onBytes: (Long) -> Unit) {
+    val part = File(dir, file.name + ".part")
+    val dest = File(dir, file.name)
+
+    // A .part longer than the target is left over from a different revision of the file;
+    // resuming from it would append good bytes onto wrong ones.
+    if (part.exists() && part.length() > file.bytes) part.delete()
+
+    var from = if (part.exists()) part.length() else 0L
+    if (from == file.bytes) {
+      // Fully transferred last time but the process died before it was verified.
+      verifyAndCommit(part, dest, file)
+      return
+    }
+
+    val conn = (URL(BASE + file.name).openConnection() as HttpURLConnection).apply {
+      connectTimeout = CONNECT_TIMEOUT_MS
+      readTimeout = READ_TIMEOUT_MS
+      if (from > 0) setRequestProperty("Range", "bytes=$from-")
+    }
+    try {
+      val code = conn.responseCode
+      if (from > 0 && code != HttpURLConnection.HTTP_PARTIAL) {
+        // The server ignored the Range, so the bytes coming back start at zero. Appending
+        // them to the .part would corrupt it silently -- the length would look plausible.
+        part.delete()
+        from = 0
+      }
+      if (code != HttpURLConnection.HTTP_OK && code != HttpURLConnection.HTTP_PARTIAL) {
+        throw IOException("${file.name}: HTTP $code")
+      }
+
+      var written = from
+      onBytes(written)
+      conn.inputStream.use { input ->
+        FileOutputStream(part, from > 0).use { out ->
+          val buf = ByteArray(BUFFER)
+          var lastTick = 0L
+          while (true) {
+            throwIfCancelled()
+            val n = input.read(buf)
+            if (n < 0) break
+            out.write(buf, 0, n)
+            written += n
+            val now = System.currentTimeMillis()
+            if (now - lastTick > TICK_MS) {
+              lastTick = now
+              onBytes(written)
+            }
+          }
+        }
+      }
+    } finally {
+      // The .part is deliberately kept on failure: it is exactly what a resume needs.
+      conn.disconnect()
+    }
+
+    throwIfCancelled()
+    verifyAndCommit(part, dest, file)
+  }
+
+  private fun verifyAndCommit(part: File, dest: File, file: ModelFile) {
+    if (part.length() != file.bytes) {
+      part.delete()
+      throw IOException("${file.name}: expected ${file.bytes} bytes, got ${part.length()}")
+    }
+    val actual = sha256(part)
+    if (!actual.equals(file.sha256, ignoreCase = true)) {
+      // Not resumable: a hash mismatch means the bytes are wrong, not that they are short.
+      part.delete()
+      throw IOException("${file.name}: checksum mismatch")
+    }
+    dest.delete()
+    if (!part.renameTo(dest)) throw IOException("${file.name}: could not be saved")
+  }
+
+  private fun sha256(file: File): String {
+    val md = MessageDigest.getInstance("SHA-256")
+    file.inputStream().use { stream ->
+      val buf = ByteArray(1 shl 20)
+      while (true) {
+        val n = stream.read(buf)
+        if (n < 0) break
+        md.update(buf, 0, n)
+      }
+    }
+    return md.digest().joinToString("") { "%02x".format(it) }
+  }
+
+  /** A small GET with timeouts. `URL.readText()` has none and can hang for minutes. */
+  private fun get(url: String): String {
+    val conn = (URL(url).openConnection() as HttpURLConnection).apply {
+      connectTimeout = CONNECT_TIMEOUT_MS
+      readTimeout = READ_TIMEOUT_MS
+    }
+    try {
+      if (conn.responseCode != HttpURLConnection.HTTP_OK) {
+        throw IOException("HTTP ${conn.responseCode} for $url")
+      }
+      return conn.inputStream.bufferedReader().readText()
+    } finally {
+      conn.disconnect()
+    }
+  }
+
+  private fun throwIfCancelled() {
+    if (cancelled) throw DownloadCancelled()
+  }
+}

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

@@ -0,0 +1,120 @@
+package com.facefusion
+
+import android.content.Context
+import java.io.File
+
+/**
+ * Where the model files live, and which tier this install will actually load.
+ *
+ * There is exactly one rule for both answers because the native side has its own copy of
+ * it: `Pipeline::init` in `ffpipe.cpp` resolves the tier against disk the same way. If
+ * this file names a tier the pipeline will not open, "models missing" and "model loaded"
+ * disagree on the same device and the result reads like a download bug rather than a
+ * mismatch. Any change here is a change to `ffpipe.cpp:88-95` as well.
+ */
+object ModelPaths {
+
+  /** The swap model. Upstream's `Pipeline::init` takes this as a parameter; we ship one. */
+  const val SWAPPER = "hyperswap"
+
+  /**
+   * The models the pipeline refuses to start without, by base name.
+   *
+   * `gpen` (the face enhancer) is deliberately absent — `Pipeline::init` opens it without
+   * checking, so a missing enhancer is a feature that is off, not a broken install.
+   */
+  private val REQUIRED = listOf("yoloface", "fan2d", "arcface", SWAPPER)
+
+  /**
+   * The content gate, in the native layer's preference order: fp32 first, quantised second.
+   *
+   * These two names exactly — `Pipeline::init` tries `nsfw_<tier>` then `nsfwq_<tier>` and
+   * treats neither being present as a fatal init error, by design, because a gate that
+   * silently does not run is worse than no gate. Anything else the manifest may publish
+   * (`nsfwq2`) is not opened, so it does not count as a gate here no matter how much it
+   * looks like one. See [ModelDownload.manifestFor], which refuses a tier on this basis.
+   */
+  val GATE = listOf("nsfw", "nsfwq")
+
+  /**
+   * Every model `Pipeline::init` actually opens — the download allowlist.
+   *
+   * **This exists because the manifest lists more than the pipeline uses.** As of
+   * 2026-09-11 upstream publishes `wav2lip` (43.73 MB) and `edtalk` (60.37 MB) for
+   * lip-sync work this port does not do, plus `nsfwq2` (~6.6 MB) on the lower tiers that
+   * `Pipeline::init` never reaches because it tries `nsfw_` then `nsfwq_` and stops. That
+   * was **104 MB of every user's first run spent on files nothing opens.**
+   *
+   * This reverses an earlier deliberate stance (`docs/04-models.md`: "we fetch exactly
+   * what the manifest lists and staying in lockstep with upstream is worth more than
+   * 6.6 MB"). That reasoning held at 6.6 MB. It does not hold at 104 MB on a mobile
+   * connection, which is a quarter of the download.
+   *
+   * `fan685` is here even though no tier currently publishes it: `Pipeline::init` opens it
+   * optionally and falls back to geometry when absent, so it should be fetched the day it
+   * appears rather than needing a code change to notice.
+   *
+   * The cost of an allowlist is that a genuinely new *required* model would be skipped
+   * until this list learns about it — which surfaces as `init` failing by name
+   * ("no content gate: neither ..."), loudly, not as a silent wrong answer.
+   */
+  val OPENED_BY_PIPELINE: List<String> = REQUIRED + GATE + listOf("gpen", "fan685")
+
+  /**
+   * The models directory, created by us.
+   *
+   * App-specific external storage: no permission is needed on any supported Android
+   * version, the OS deletes it with the app, and — unlike internal storage — it can be
+   * listed over adb while debugging. `getExternalFilesDir` returns null when external
+   * storage is not mounted, which is rare but real, so internal storage is the fallback.
+   *
+   * `mkdirs()` here matters more than it looks: a directory created by `adb push` is owned
+   * by the `shell` user and this app cannot traverse it, which surfaces as `open()` failing
+   * with a bare ENOENT on a file that is plainly there. Creating it ourselves first avoids
+   * inheriting someone else's ownership.
+   */
+  fun dir(context: Context): File {
+    val base = context.getExternalFilesDir(null) ?: context.filesDir
+    return File(base, "models").apply { mkdirs() }
+  }
+
+  /**
+   * The tier this install will load: the best one whose files are on disk, else the best
+   * this chip could load.
+   *
+   * **Never cache this**, and never substitute the probe's `tier` for it. That one is
+   * `tierChain().first()` — what the *silicon* can load, with no reference to disk. The two
+   * differ on exactly the devices whose best arch is not published yet: an 8 Elite Gen 5
+   * resolves the chain `v81,v73,v68`, the manifest currently publishes no v81, the
+   * downloader correctly fetches **v73**, and anything that then names files `_v81` reports
+   * a complete download as missing. That shipped in upstream's 0.2.0. Recomputing is a
+   * handful of `canRead()` calls; the chain is what was expensive, and that is cached.
+   */
+  fun tier(context: Context): String {
+    val chain = DeviceProbe.tierChain(context)
+    val dir = dir(context)
+    // The detector is the probe because it is mandatory and the smallest file in the set.
+    // A tier is never half present: the downloader writes `<name>.part` and renames only
+    // after the SHA-256 matches, so yoloface being there means the rest of that tier is.
+    return chain.firstOrNull { File(dir, "yoloface_$it.bin").canRead() } ?: chain.first()
+  }
+
+  /**
+   * Which required models are absent for [tier], by base name. Empty means ready to run.
+   *
+   * The content gate counts as required because it *blocks*: without it there is nothing to
+   * refuse with, and a run that cannot check is a run that must not happen. Either build
+   * satisfies it — fp32 `nsfw_`, or the quantised `nsfwq_` that every tier below v79
+   * carries because the fp32 GELU will not compile for them.
+   */
+  fun missing(context: Context, tier: String): List<String> {
+    val dir = dir(context)
+    val absent = REQUIRED.filterNot { File(dir, "${it}_$tier.bin").canRead() }.toMutableList()
+    if (GATE.none { File(dir, "${it}_$tier.bin").canRead() }) absent += "nsfw"
+    return absent
+  }
+
+  /** Whether the optional face enhancer is on disk for [tier]. */
+  fun hasEnhancer(context: Context, tier: String): Boolean =
+    File(dir(context), "gpen_$tier.bin").canRead()
+}

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

@@ -0,0 +1,125 @@
+package com.facefusion
+
+import android.content.Context
+import android.graphics.Bitmap
+import android.graphics.BitmapFactory
+import com.facefusion.mobile.NativePipe
+import java.io.File
+import java.io.FileOutputStream
+
+/** The result of one still-photo swap. */
+data class PhotoSwapResult(
+  val outputPath: String,
+  /** Faces found in the target, per [NativePipe.processFrame]. `0` means the swap ran but
+   *  found nothing to swap — [outputPath] is then an untouched copy of the target. */
+  val faceCount: Int,
+  /** The tier that ran, from [ModelPaths.tier] — see that file for why it, not the chip's
+   *  raw probe, is the one that matters here. */
+  val tier: String,
+)
+
+/**
+ * Swaps a face from [sourcePath] into every face found in [targetPath], writing the result
+ * to [outputPath].
+ *
+ * Paths in, path out (`docs/01-architecture.md`) — this is the only place in the Kotlin
+ * layer that touches pixels, and it does so only to get them into and out of [NativePipe]'s
+ * flat BGR arrays. Everything between is native.
+ */
+object PhotoSwap {
+
+  /** The tier's required models are not on disk. Distinct from a native/runtime failure so
+   *  the TurboModule can give it its own rejection code — see [FacefusionModule.swapPhoto]. */
+  class ModelsMissing(message: String) : Exception(message)
+
+  fun run(
+    context: Context,
+    sourcePath: String,
+    targetPath: String,
+    outputPath: String,
+    cfg: SwapConfig,
+    /** `[left, top, right, bottom]` from [SourceFaces.detect], or `null` for the default
+     *  "largest face in the source" that [NativePipe.setSource] already picks on its own. */
+    sourceFaceBox: FloatArray? = null,
+    /** `[left, top, right, bottom]` from [TargetFaces.detect], or `null` to swap every face
+     *  found in the target (subject to [SwapConfig.largestFaceOnly]), same as before this
+     *  option existed. See [FaceCrop]. */
+    targetFaceBox: FloatArray? = null,
+  ): PhotoSwapResult {
+    NativePipe.loadError?.let {
+      throw IllegalStateException("libffnative.so did not load: $it")
+    }
+
+    val tier = ModelPaths.tier(context)
+    val missing = ModelPaths.missing(context, tier)
+    if (missing.isNotEmpty()) {
+      throw ModelsMissing(
+        "Models missing for $tier: ${missing.joinToString(", ")} — call downloadModels() first"
+      )
+    }
+
+    // Capped during decode -- see [BitmapDecode] for why, and why the source's cap is
+    // lower than the target's. `sourceFaceBox` is in the source's ORIGINAL pixel
+    // coordinates (it came from SourceFaces.detect on the same path, decoded with the same
+    // cap), so the crop below stays consistent with it.
+    val decodedSource = BitmapDecode.decode(sourcePath, BitmapDecode.SOURCE_MAX)
+    val source = sourceFaceBox?.let { SourceFaces.cropToFace(decodedSource, it) } ?: decodedSource
+    val target = BitmapDecode.decode(targetPath, BitmapDecode.TARGET_MAX)
+
+    return PipeGuard.run(context, tier, cfg) {
+      val sourceBgr = NativePipe.argbToBgr(pixelsOf(source), source.width, source.height)
+      if (!NativePipe.setSource(sourceBgr, source.width, source.height)) {
+        throw IllegalStateException(NativePipe.lastError())
+      }
+
+      val targetBgr = NativePipe.argbToBgr(pixelsOf(target), target.width, target.height)
+      ContentGate.checkFrame(targetBgr, target.width, target.height)
+      val faceCount = if (targetFaceBox != null) {
+        // Swap only inside a crop around the chosen face, then paste it back -- the same
+        // "crop, call the unchanged native function, paste/re-encode" trick SourceFaces
+        // uses on the source side. Whatever processFrame finds outside the crop is never
+        // touched, so this needs no native "pick face N" support.
+        val rect = FaceCrop.rect(targetFaceBox, target.width, target.height)
+        val cropped = FaceCrop.crop(targetBgr, target.width, rect)
+        val cw = rect[2] - rect[0]
+        val ch = rect[3] - rect[1]
+        val count = NativePipe.processFrame(cropped, cw, ch)
+        if (count > 0) FaceCrop.paste(targetBgr, target.width, cropped, rect)
+        count
+      } else {
+        NativePipe.processFrame(targetBgr, target.width, target.height)
+      }
+      if (faceCount < 0) throw IllegalStateException(NativePipe.lastError())
+
+      // One frame, not a loop -- shows the result on any mounted <FacefusionPreview />
+      // immediately, before the encode-to-file below even starts.
+      PreviewSurfaceHolder.draw(targetBgr, target.width, target.height)
+
+      val outArgb = NativePipe.bgrToArgb(targetBgr, target.width, target.height, target.width, target.height)
+      val outBitmap = Bitmap.createBitmap(target.width, target.height, Bitmap.Config.ARGB_8888)
+      outBitmap.setPixels(outArgb, 0, target.width, 0, 0, target.width, target.height)
+      write(outBitmap, outputPath)
+
+      PhotoSwapResult(outputPath, faceCount, tier)
+    }
+  }
+
+  private fun pixelsOf(bitmap: Bitmap): IntArray {
+    val pixels = IntArray(bitmap.width * bitmap.height)
+    bitmap.getPixels(pixels, 0, bitmap.width, 0, 0, bitmap.width, bitmap.height)
+    return pixels
+  }
+
+  private fun write(bitmap: Bitmap, path: String) {
+    val file = File(path)
+    file.parentFile?.mkdirs()
+    FileOutputStream(file).use { out ->
+      val format = if (path.endsWith(".png", ignoreCase = true)) {
+        Bitmap.CompressFormat.PNG
+      } else {
+        Bitmap.CompressFormat.JPEG
+      }
+      bitmap.compress(format, 92, out)
+    }
+  }
+}

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

@@ -0,0 +1,74 @@
+package com.facefusion
+
+import android.content.Context
+import com.facefusion.mobile.NativePipe
+import java.util.concurrent.atomic.AtomicBoolean
+
+/**
+ * Owns the single native pipeline (`g_pipe`, a C++ global in `ffjni.cpp`) and the fact that
+ * only one job can use it at a time.
+ *
+ * Ported from upstream's `PipeGuard.kt` (see `docs/02-upstream.md`) — not copied, since only
+ * the C++ is vendored (ADR-0005) and upstream's Kotlin was never fetched. This reproduces the
+ * *behaviour* upstream's class docs describe: a video swap can run for minutes, and a second
+ * caller queued behind that on the same lock would look indistinguishable from a hang. So a
+ * second job is rejected immediately with [Busy] instead of waiting, the same shape as
+ * [ModelDownload]'s `E_BUSY` check.
+ *
+ * Re-initialising the pipeline is expensive — it `dlopen`s the QNN backend and finalises
+ * every graph — so it is kept warm across calls and only reloaded when [SwapConfig] or the
+ * resolved tier actually changed. See ADR-0008.
+ */
+object PipeGuard {
+  class Busy : Exception("A face-swap job is already running")
+
+  private val busy = AtomicBoolean(false)
+
+  @Volatile
+  private var initedSignature: String? = null
+
+  /**
+   * Runs [block] with the native pipeline initialised for [tier]/[cfg], holding the single
+   * job slot for the duration.
+   *
+   * @throws Busy immediately if another job already holds the slot.
+   * @throws IllegalStateException if `initEx` fails; [NativePipe.lastError] names why.
+   */
+  fun <T> run(context: Context, tier: String, cfg: SwapConfig, block: () -> T): T {
+    if (!busy.compareAndSet(false, true)) throw Busy()
+    try {
+      ensureInit(context, tier, cfg)
+      return block()
+    } finally {
+      busy.set(false)
+    }
+  }
+
+  private fun ensureInit(context: Context, tier: String, cfg: SwapConfig) {
+    val signature = "$tier|${cfg.signature()}"
+    if (signature == initedSignature) return
+
+    val libDir = context.applicationInfo.nativeLibraryDir
+    val modelDir = ModelPaths.dir(context).absolutePath
+    val ok = NativePipe.initEx(
+      libDir,
+      libDir,
+      modelDir,
+      ModelPaths.SWAPPER,
+      cfg.swapperWeight,
+      cfg.maskBlur,
+      cfg.maskPadding.toIntArray(),
+      cfg.detectorScore,
+      cfg.landmarkerScore,
+      cfg.pixelBoost,
+      cfg.largestFaceOnly,
+      cfg.faceEnhance,
+      cfg.faceEnhancerBlend,
+    )
+    if (!ok) {
+      initedSignature = null
+      throw IllegalStateException(NativePipe.lastError())
+    }
+    initedSignature = signature
+  }
+}