[BCI] Enable dynamic backend loading for Android (QVAC-19235) (#2326)

* bci-whispercpp: thread backendsDir + Android dynamic-backend loader (QVAC-19235)

PR 1 of 3 for the BCI GPU rollout. Behaviour on every platform is
unchanged today because `bci-whispercpp` still pins
`whisper-cpp@1.8.4.2`, whose port builds ggml with the static-backend
registry (`GGML_BACKEND_DL=OFF`). This PR is the safety net that lets
the follow-up `whisper-cpp@1.8.5` bump (QVAC-19009) flip
`GGML_BACKEND_DL=ON` on Android without reproducing the `SIGABRT` on
model load that hit `transcription-whispercpp` on its PR #2124 -- see
`aiDocs/15-android-mobile-test-crash-fix.md` for the post-mortem.

What changes:

- BCIConfig gains a `backendsDir` string field. JSAdapter reads
  the top-level `configurationParams.backendsDir` directly (not
  via `loadMap`) to avoid polluting any of the BCI handler
  namespaces.
- index.js threads `BCIWhispercppConfig.backendsDir` into
  `configurationParams`, defaulting to `<addon>/prebuilds`
  resolved via `bare-path`. Surfaced in `index.d.ts`.
- BCIModel::load() now calls `ensureBackendsLoadedAndroid()` (gated
  on `__ANDROID__`, idempotent via `std::call_once`) BEFORE
  `whisper_init_from_file_with_params()`. Joins `backendsDir` with
  the compile-time `BACKENDS_SUBDIR` and dispatches to
  `ggml_backend_load_all_from_path()`. Inactive today (no MODULE
  backends produced at 1.8.4.2); the call still runs because it's
  cheap and we want symmetry with transcription/parakeet.
- BCIModel::captureActiveBackendInfo() snapshots the active backend
  identity + device-memory after backend registration. New
  `RuntimeStats` keys: `backendDevice`, `backendId`, `gpuMemTotalMb`,
  `gpuMemFreeMb`. Numeric mapping (CPU=0 / Metal=1 / CUDA=2 /
  Vulkan=3 / OpenCL=4 / other=99) lock-stepped with
  transcription-whispercpp 0.9.0 + transcription-parakeet for
  cross-addon Device Farm comparability.
- CMakeLists.txt: `bare_target` + `bare_module_target` discovery,
  `BACKENDS_SUBDIR` compile define, `BACKEND_DL_LIBS` (IMPORTED
  `ggml::*` targets) + `BACKEND_DL_LOOSE_SOS` (loose
  `libqvac-speech-ggml-*.so` staging) plumbing. Parity with
  transcription-whispercpp / transcription-parakeet.

Test-then-implementation: GoogleTest additions guard the new
config field round-trip and the new RuntimeStats key contract +
default-CPU values (mirrors `WhisperModel`'s `BackendInfo` unit-
test contract). All 22 GTests, 21 brittle unit tests, 6 integration
tests pass locally on Linux.

Version bump: 0.1.0 -> 0.1.1 (additive plumbing only, no behaviour
change; the minor bump is reserved for PR 3 / GPU enablement).

Co-authored-by: Cursor <cursoragent@cursor.com>

* bci-whispercpp: derive backend stats from actual whisper_context_params (review)

Addresses jpgaribotti's review on #2326: captureActiveBackendInfo()
treated a missing contextParams.use_gpu as false, but
toWhisperContextParams() leaves whisper_context_default_params() intact
(use_gpu=true). So with no explicit use_gpu, whisper could initialise a
GPU while runtimeStats reported backendDevice=0/backendId=0.

Fix: pass the exact whisper_context_params used by
whisper_init_from_file_with_params() into captureActiveBackendInfo() and
read use_gpu / gpu_device from it, instead of re-deriving from the
BCIConfig map with a (wrong) false default. Reported backend identity is
now in lock-step with the context whisper actually built.

Also corrects the GPU device selection to mirror whisper's
whisper_backend_init_gpu(): gpu_device is an index AMONG GPU devices
(default 0), not an index into all devices (device 0 is normally the
CPU). Removed the now-unused configUseGpu()/configGpuDeviceIndex()
helpers.

Validated: host build + test:cpp (22/22) + test:integration (6/6) green;
clang-tidy + clang-format clean on the changed file; android-arm64
cross-build compiles.

Co-authored-by: Cursor <cursoragent@cursor.com>

* bci-whispercpp: report IGPU backends + Adreno OpenCL guard (port transcription #2343)

Ports the transcription-whispercpp fix merged in #2343
("report IGPU backends (fix Mali silent CPU mislabel)") into the BCI
addon so the two stay faithful mirrors and the BCI Android GPU path
(QVAC-19234) behaves correctly on real devices:

- captureActiveBackendInfo() now walks BOTH GGML_BACKEND_DEVICE_TYPE_GPU
  and _IGPU. ggml-vulkan reports integrated GPUs (Mali, Adreno-via-
  Vulkan, Intel iGPU) as IGPU; skipping IGPU made every Vulkan-on-mobile
  device look like a silent CPU fallback even while whisper ran on the
  GPU. gpu_device is treated as an index into the filtered GPU/IGPU list,
  matching whisper_backend_init_gpu()'s `cnt`.
- New adrenoOpenclGpuDeviceIndex() + an Adreno guard in load(): when an
  Adreno OpenCL device is registered (Android registers both Vulkan and
  OpenCL for the same GPU, Vulkan first), steer whisper to OpenCL. The
  Adreno Vulkan driver SIGSEGVs in ggml compute (vkCmdBindPipeline);
  OpenCL is the supported Adreno backend. No-op on Mali/desktop.
- captureActiveBackendInfo() signature is now (bool useGpu, int
  gpuDeviceIndex), fed the exact post-guard whisper_context_params, and
  the fallback WARNING text matches #2343.

All behaviour-neutral on this PR's whisper-cpp@1.8.4.2 (no GPU/IGPU
devices register, adrenoOpenclGpuDeviceIndex()=-1). Validated: host
build + test:cpp (22/22) + test:integration (6/6) + lint + test:dts;
clang-format-20 + clang-tidy-19 clean on the changed files;
android-arm64 NDK cross-build compiles.

Co-authored-by: Cursor <cursoragent@cursor.com>

---------

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: Zbig9000

packages/bci-whispercpp/CHANGELOG.md

@@ -5,6 +5,57 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.2]
+
+Android dynamic-backend-loading infrastructure (QVAC-19235). Behaviour
+on every platform is unchanged today because `bci-whispercpp` still
+pins `whisper-cpp@1.8.4.2`, whose port builds ggml with the static-
+backend registry (`GGML_BACKEND_DL=OFF`). This PR is the "safety net"
+that lets the follow-up `whisper-cpp@1.8.5` bump (QVAC-19009) flip
+`GGML_BACKEND_DL=ON` on Android without reproducing the `SIGABRT` on
+model load that hit `transcription-whispercpp` on its PR #2124. See
+`aiDocs/15-android-mobile-test-crash-fix.md` for the post-mortem.
+
+### Added
+
+- Native `BCIConfig::backendsDir` field plus JS-side `configurationParams.backendsDir`
+  pass-through (defaults to `<addon>/prebuilds` resolved via
+  `bare-path`). Surfaces on `BCIWhispercppConfig.backendsDir`.
+- Android-only `ensureBackendsLoadedAndroid()` in `BCIModel::load()`
+  (process-local `std::call_once`); resolves the per-arch backend
+  subdir from `backendsDir / BACKENDS_SUBDIR` and dispatches to
+  `ggml_backend_load_all_from_path()`.
+- `captureActiveBackendInfo(useGpu, gpuDevice)` in `BCIModel::load()`:
+  enumerates `ggml_backend_dev_*` after backend registration and
+  snapshots the active backend identity + device memory. New
+  `RuntimeStats` keys: `backendDevice`, `backendId`, `gpuMemTotalMb`,
+  `gpuMemFreeMb`. The numeric mapping (CPU=0 / Metal=1 / CUDA=2 /
+  Vulkan=3 / OpenCL=4 / other=99) is lock-stepped with
+  `transcription-whispercpp 0.9.0` and `transcription-parakeet` for
+  cross-addon Device Farm comparability. Backend selection is sourced
+  from the exact `whisper_context_params` the context was built with
+  (use_gpu/gpu_device), walks the `whisper_backend_init_gpu()`-filtered
+  GPU **and IGPU** device list (Mali / Adreno-via-Vulkan / Intel iGPU
+  report as IGPU), and applies the Adreno OpenCL preference — mirroring
+  `transcription-whispercpp` PR #2270 + #2343. Inert on
+  `whisper-cpp@1.8.4.2` (no GPU backends registered).
+- `CMakeLists.txt`: `bare_target` + `bare_module_target` discovery,
+  `BACKENDS_SUBDIR` compile define, `BACKEND_DL_LIBS` (IMPORTED
+  `ggml::*` targets) + `BACKEND_DL_LOOSE_SOS` (loose
+  `libqvac-speech-ggml-*.so` staging) plumbing, parity with
+  `transcription-whispercpp` / `transcription-parakeet`. Inactive
+  today (no MODULE backends produced at `whisper-cpp@1.8.4.2`);
+  activates on the QVAC-19009 bump.
+
+### Added (tests)
+
+- `BCIConfig.backendsDirDefaultsEmpty`, `BCIConfig.backendsDirRoundTrip`:
+  guard the new config field's defaults and copy semantics.
+- `BCIModel.runtimeStatsExposesBackendIdentityKeys`,
+  `BCIModel.backendIdentityDefaultsToCPU`: guard the new
+  `RuntimeStats` keys + default-CPU contract without requiring a
+  loaded model (mirrors transcription-whispercpp's `BackendInfo`
+  unit-test pattern).
 ## [0.1.1] - 2026-06-02
 
 ### Changed

packages/bci-whispercpp/CMakeLists.txt

@@ -45,7 +45,63 @@ if(WIN32)
   add_definitions(-DNOMINMAX -DWIN32_LEAN_AND_MEAN -DNOGDI)
 endif()
 
-add_bare_module(bci-whispercpp EXPORTS)
+# Subdir bare's runtime installs the dlopen-able backend modules into
+# (<addon>/prebuilds/<bare_target>/<module_name>/); BCIModel joins it
+# with the runtime-supplied backendsDir before
+# ggml_backend_load_all_from_path(). Mirrors transcription-whispercpp.
+bare_target(bare_target_value)
+bare_module_target("." _unused_target NAME module_name VERSION _unused_version)
+set(BACKENDS_SUBDIR_VALUE "${bare_target_value}/${module_name}")
+
+# Collect every dynamically-loadable ggml backend that the `ggml-speech`
+# port produced ($CURRENT_PACKAGES_DIR/lib/libqvac-speech-ggml-*.so on
+# Android; nothing on Apple/static-only platforms). Mirrors
+# qvac/packages/transcription-whispercpp/CMakeLists.txt verbatim --
+# two branches:
+#   1. IMPORTED targets that `find_package(ggml)` already surfaced
+#      (CPU on Android, all backends on Linux desktop).
+#   2. Loose `libqvac-speech-ggml-*.so` MODULE files that ggml-config
+#      deliberately omits from GGML_AVAILABLE_BACKENDS' IMPORTED set
+#      (Vulkan + OpenCL on Android -- the loader picks them up at
+#      runtime via `ggml_backend_load_all_from_path()`).
+set(BACKEND_DL_LIBS "")
+if((ANDROID OR UNIX) AND NOT APPLE)
+  foreach(_backend ${GGML_AVAILABLE_BACKENDS})
+    if(TARGET ggml::${_backend})
+      list(APPEND BACKEND_DL_LIBS INSTALL TARGET ggml::${_backend})
+    endif()
+  endforeach()
+endif()
+
+set(BACKEND_DL_LOOSE_SOS "")
+if((ANDROID OR UNIX) AND NOT APPLE)
+  if(NOT VCPKG_INSTALLED_PATH OR NOT EXISTS "${VCPKG_INSTALLED_PATH}/lib")
+    message(WARNING "bci-whispercpp: VCPKG_INSTALLED_PATH "
+      "('${VCPKG_INSTALLED_PATH}') has no lib/ dir; skipping loose "
+      "ggml backend .so pickup -- the runtime may fail to find "
+      "Vulkan / OpenCL backends.")
+  else()
+    file(GLOB BACKEND_DL_LOOSE_SOS
+      "${VCPKG_INSTALLED_PATH}/lib/libqvac-speech-ggml-*.so")
+    foreach(_lib IN LISTS BACKEND_DL_LOOSE_SOS)
+      message(STATUS "bci-whispercpp: will stage ggml backend ${_lib}")
+    endforeach()
+  endif()
+endif()
+
+add_bare_module(bci-whispercpp EXPORTS ${BACKEND_DL_LIBS})
+
+# Stage every loose MODULE backend (Vulkan / OpenCL on Android, ...)
+# into the same per-host/per-module subdir cmake-bare's INSTALL TARGET
+# branch uses for IMPORTED targets -- keeping destinations identical so
+# `ggml_backend_load_all_from_path(backendsDir / BACKENDS_SUBDIR)`
+# discovers IMPORTED-target CPU + loose-file GPU backends in one scan.
+if(BACKEND_DL_LOOSE_SOS)
+  install(
+    FILES ${BACKEND_DL_LOOSE_SOS}
+    DESTINATION ${bare_target_value}/${module_name}
+  )
+endif()
 
 if(CMAKE_SYSTEM_NAME STREQUAL "Linux")
   target_link_options(${bci-whispercpp}_module PRIVATE -Wl,--exclude-libs,ALL)
@@ -77,6 +133,7 @@ target_link_libraries(
 )
 
 target_compile_definitions(${bci-whispercpp} PUBLIC JS_LOGGER)
+target_compile_definitions(${bci-whispercpp} PRIVATE BACKENDS_SUBDIR="${BACKENDS_SUBDIR_VALUE}")
 
 if(WIN32)
   target_link_libraries(

packages/bci-whispercpp/addon/src/js-interface/JSAdapter.cpp

@@ -105,6 +105,16 @@ BCIConfig JSAdapter::loadFromJSObject(Object jsObject, js_env_t* env) {
     loadBCIParams(bciConfigObj.value(), env, config);
   }
 
+  // Top-level `configurationParams.backendsDir`. Read directly (not through
+  // `loadMap` / handler dispatch) because routing it through any of the
+  // sub-section maps would either throw on an unrecognised key or pollute
+  // a config namespace the BCI handlers don't own. Consumed by
+  // `BCIModel::load()` on Android only; ignored on other platforms.
+  auto backendsDirJs = jsObject.getOptionalProperty<String>(env, "backendsDir");
+  if (backendsDirJs.has_value()) {
+    config.backendsDir = backendsDirJs.value().as<std::string>(env);
+  }
+
   return config;
 }
 

packages/bci-whispercpp/addon/src/model-interface/bci/BCIConfig.hpp

@@ -27,6 +27,13 @@ struct BCIConfig {
   std::map<std::string, JSValueVariant> whisperContextCfg;
   std::map<std::string, JSValueVariant> bciConfig;
 
+  // Addon prebuilds folder (`configurationParams.backendsDir` from JS).
+  // Combined with the compile-time `BACKENDS_SUBDIR` to locate the
+  // per-arch ggml `.so` modules for `ggml_backend_load_all_from_path()`.
+  // Android-only; empty elsewhere. Mirrors WhisperConfig::backendsDir
+  // in transcription-whispercpp 0.9.0.
+  std::string backendsDir;
+
   // Owned storage for string values that whisper_full_params references by
   // pointer (e.g. p.language = lang_.c_str()). Must outlive the params struct.
   mutable std::string lang_;