@qvac/tts-ggml 0.11.1 → 0.12.0

package/README.md

@@ -54,8 +54,9 @@ validated on Apple/Metal.
   iOS, picked up when staged next to the model (see
   [Core ML sidecars on Apple](#core-ml-sidecars-on-apple)).
 - **Dynamic backend loading on Android** — per-arch CPU + Vulkan +
-  OpenCL `.so` files ship under `prebuilds/<bare-target>/qvac__tts-ggml/`
-  and are picked up at runtime via the new `backendsDir` option (see
+  OpenCL `.so` files ship under
+  `prebuilds/<bare-target>/qvac__tts-ggml-android-arm64/` and the addon picks
+  them up at runtime from next to its native module (see
   [Backends & GPU acceleration](#backends--gpu-acceleration)).
 - **Cancellation** via `model.cancel()` — stops T3 decode on the next
   token; in-flight S3Gen chunk runs to completion.
@@ -150,11 +151,10 @@ package selected at install time through `os`/`cpu` filtered
 
 Do not depend on desktop platform packages directly. Supported installers are
 npm 7+, pnpm, bun, and Yarn Berry. Yarn v1 and `--omit=optional` installs skip
-the platform package and fail at require time with an error naming the missing
-package; a locally built `prebuilds/` directory in the package root always
-takes precedence. Use `require('@qvac/tts-ggml').resolveBackendsDir()` to
-locate the directory holding the host's prebuilt binaries and dynamically
-loaded ggml backends. Unsupported targets must
+the platform package and fail at require time, and at `bare-pack` time, naming
+the missing package. Each platform package is an ordinary Bare addon whose
+`prebuilds/<host>/` holds the native module and, next to it, the dynamically
+loaded ggml backends the module finds on its own. Unsupported targets must
 [build from source](#build-from-source); installation does not automatically
 compile a local addon.
 
@@ -805,13 +805,13 @@ registration and the addon falls back to Vulkan or CPU.
 
 Android prebuilds enable `GGML_BACKEND_DL=ON` and ship per-arch
 backend `.so` files under
-`prebuilds/<bare-target>/qvac__tts-ggml/`.
+`prebuilds/android-arm64/qvac__tts-ggml-android-arm64/` of
+`@qvac/tts-ggml-android-arm64`; `bare-link` puts them next to the module in
+the app, where the addon looks when `backendsDir` is unset.
 
 The engine `dlopen()`s the highest-tier CPU variant the device's
 HWCAPs support and one of the GPU `.so` files based on the policy
-table above.  Hosts must pass `backendsDir: path.join(__dirname,
-'prebuilds')` (or rely on the default fallback the package ships)
-so the runtime knows where to look.  `openclCacheDir` is also
+table above.  `openclCacheDir` is
 Android-specific; setting it to a writable path lets the OpenCL
 backend persist its compiled program cache across launches.
 `vulkanCacheDir` is the Vulkan analogue (Supertonic + `useGPU: true`):
@@ -1228,7 +1228,7 @@ instance.  Runtime stats add `promptTokens`, `generatedTokens`, `replyTokens`,
 | `promptText`              | string     | —          | CosyVoice3-only: verbatim transcript of `referenceAudio` — set for zero-shot cloning, omit for cross-lingual; without a reference it overrides the baked voice's transcript |
 | `mecabDictDir`            | string     | —          | Chatterbox MTL Japanese (`ja`): compiled MeCab/IPAdic dictionary directory |
 | `cangjieTsvPath`          | string     | —          | Chatterbox MTL Chinese (`zh`): `Cangjie5_TC` TSV path |
-| `backendsDir`             | string     | `resolveBackendsDir()` | Root dir the addon scans for dynamically-loaded ggml backend `.so` files.  Defaults to the package's own `prebuilds/` when present, otherwise the installed platform package.  Required on Android when backends ship elsewhere (e.g. inside the APK); ignored on platforms that statically link the backend |
+| `backendsDir`             | string     | the module's own | Directory the addon scans, as given, for dynamically-loaded ggml backend `.so` / `.dll` files.  Unset scans the directory the native module was loaded from (`prebuilds/<host>/qvac__tts-ggml-<suffix>/` in a platform package, the app's native library directory after `bare-link`); ignored on platforms that statically link the backend |
 | `openclCacheDir`          | string     | unset      | Android-only: directory where the OpenCL backend persists its compiled program-binary cache.  Setting it across runs avoids re-JITing the kernels on every fresh process |
 | `vulkanCacheDir`          | string     | unset      | Supertonic + `useGPU: true` only: writable directory where the Vulkan backend persists its compiled pipeline cache (`GGML_VK_PIPELINE_CACHE_DIR`).  Moves the one-time first-dispatch pipeline-compile cost (seconds on Mali) off the first `run()` — paid once per install instead of once per process — and enables a load-time pre-warm.  Fully opt-in: unset -> no cross-process cache, no pre-warm, behaviour unchanged |
 | `config.language`         | string     | `"en"`     | Chatterbox MTL accepts `es/fr/de/pt/it/zh/ja/ko/...`; turbo & Supertonic are English; MOSS takes it as a prompt hint (`en`, `zh`, ...) |
@@ -1571,8 +1571,14 @@ npm install
 npx bare-make generate      # configures + fetches the tts-cpp port
 npx bare-make build
 npx bare-make install       # copies the .bare into prebuilds/<triple>/
+npm run link:platform       # stages node_modules/@qvac/tts-ggml-<host>
 ```
 
+`require('#host-addon')` only ever loads a platform package, so a source
+build becomes loadable once `npm run link:platform` (run by
+`npm run build:native`) wraps `prebuilds/<host>/` as that host's
+`@qvac/tts-ggml-<host>` package in `node_modules/`.
+
 The vcpkg port is hosted in
 [`tetherto/qvac-registry-vcpkg`][registry] and pulls
 [`qvac-tts.cpp`][qvac-tts-cpp] at a pinned REF.  See

package/addon-unavailable.js

@@ -1,31 +1,15 @@
-const { hostPlatformPackage, PREBUILT_HOSTS } = require('./lib/backends.js')
+'use strict'
 
-const META_PACKAGE = '@qvac/tts-ggml'
-const UNKNOWN_HOST = 'unknown'
+// "#host-addon" target for hosts with no platform package. Hosts that have one
+// map straight to it with no fallback, so a missing install fails bare-pack (and
+// fails at run time naming the package) instead of producing a bundle that only
+// throws once launched.
+const host = require.addon ? require.addon.host : 'unknown'
 
-throw new Error(buildMessage(currentHost()))
-
-function currentHost() {
-  return require.addon ? require.addon.host : null
-}
-
-function buildMessage(host) {
-  if (!host || !PREBUILT_HOSTS.includes(host)) {
-    return (
-      META_PACKAGE +
-      ' has no prebuilt binaries for host ' +
-      (host || UNKNOWN_HOST) +
-      '. Prebuilt hosts: ' +
-      PREBUILT_HOSTS.join(', ') +
-      '. Build from source with bare-make.'
-    )
-  }
-  return (
-    META_PACKAGE +
-    ' found no native prebuild for ' +
+throw new Error(
+  '@qvac/tts-ggml has no prebuilt binaries for host ' +
     host +
-    ': the platform package ' +
-    hostPlatformPackage(host) +
-    ' is not installed. It ships as an os/cpu filtered optional dependency, which Yarn v1 and installs using --omit=optional drop. Reinstall with npm 7+, pnpm, bun, or Yarn Berry, or build from source with bare-make.'
-  )
-}
+    '. Platform packages exist for linux-x64, linux-arm64, darwin-arm64, ' +
+    'darwin-x64, win32-x64, android-arm64 and ios (ios-arm64, ' +
+    'ios-arm64-simulator, ios-x64-simulator). Build from source with bare-make.'
+)

package/binding.js

@@ -1,52 +1 @@
-module.exports = loadAddon()
-
-// `require.addon()` reads the prebuild shipped inside this package. Since the
-// per-platform split (0.9.0) there is none, so the real binding almost always
-// comes from the `#host-addon` platform package. Runtimes have been seen to
-// answer `require.addon()` with this package's own JavaScript entry instead of
-// failing, which used to be returned verbatim: callers then got a module with
-// no `createInstance`, and the first symptom was an unrelated TypeError deep in
-// a model load. Anything that is not the native binding is treated as a miss.
-function loadAddon() {
-  let cause = null
-
-  try {
-    const addon = require.addon()
-    if (isNativeBinding(addon)) return addon
-    cause = new Error(
-      '@qvac/tts-ggml: require.addon() answered with a module that is not the native binding ' +
-        '(no createInstance function), so the prebuild in this package was treated as absent.'
-    )
-  } catch (err) {
-    cause = err
-  }
-
-  return loadPlatformPackageAddon(cause)
-}
-
-function loadPlatformPackageAddon(cause) {
-  let addon
-
-  try {
-    addon = require('#host-addon')
-  } catch (err) {
-    if (err.cause === undefined) err.cause = cause
-    throw err
-  }
-
-  if (!isNativeBinding(addon)) {
-    const err = new Error(
-      '@qvac/tts-ggml resolved #host-addon to a module that is not the native binding: ' +
-        'it has no createInstance function. Check that the platform package for this host ' +
-        'is installed and is not shadowed by another module of the same name.'
-    )
-    err.cause = cause
-    throw err
-  }
-
-  return addon
-}
-
-function isNativeBinding(addon) {
-  return addon !== null && typeof addon === 'object' && typeof addon.createInstance === 'function'
-}
+module.exports = require('#host-addon')

package/index.d.ts

@@ -1,6 +1,5 @@
 import { type QvacResponse } from "@qvac/infer-base";
 import * as errorModule from "./lib/error";
-import { resolveBackendsDir as resolveBackendsDirImpl } from "./lib/backends";
 import { assessFit as assessFitImpl, type Audio8FitRequest, type MossFitRequest, type MossSoundEffectFitRequest, type ChatterboxFitRequest, type CosyvoiceFitRequest, type ParlerFitRequest, type SupertonicFitRequest, type TtsFitEngine, type TtsFitRequest, type TtsFitResult, type TtsFitStatus } from "./lib/fit";
 import { type SentenceDelimiterPreset } from "./lib/textStreamAccumulator";
 declare const ENGINE_CHATTERBOX = "chatterbox";
@@ -607,7 +606,11 @@ interface TTSGgmlOptions extends ParlerDescriptionFields, Audio8VoiceFields, TTS
      * streaming (batch synthesis only).
      */
     denoiser?: LavaSRDenoiserOptions;
-    /** Directory the addon scans for dynamically loaded ggml backends. */
+    /**
+     * Directory the addon scans for dynamically loaded ggml backends, as given.
+     * Unset scans the addon's own: the one its platform package or the app
+     * installed next to the native module.
+     */
     backendsDir?: string;
     /** Directory where ggml-opencl persists its compiled program binary. */
     openclCacheDir?: string;
@@ -1211,7 +1214,6 @@ declare namespace TTSGgml {
     type MossFitRequest = NamespaceMossFit;
     type MossSoundEffectFitRequest = NamespaceMossSoundEffectFit;
     type CosyvoiceFitRequest = NamespaceCosyvoiceFit;
-    const resolveBackendsDir: typeof resolveBackendsDirImpl;
     const assessFit: typeof assessFitImpl;
 }
 export = TTSGgml;

package/index.js

@@ -46,7 +46,6 @@ const infer_base_1 = require("@qvac/infer-base");
 const tts_1 = require("./tts");
 const errorModule = __importStar(require("./lib/error"));
 const pocketConfig_1 = require("./lib/pocketConfig");
-const backends_1 = require("./lib/backends");
 const fit_1 = require("./lib/fit");
 const textChunker_1 = require("./lib/textChunker");
 const textStreamAccumulator_1 = require("./lib/textStreamAccumulator");
@@ -1293,7 +1292,7 @@ class TTSGgml {
         this._assignSynthesisOptions(options);
         this._enhancerGgufPath = resolveEnhancerGgufPath(normalizedFiles, options.enhancer);
         this._denoiserGgufPath = resolveDenoiserGgufPath(normalizedFiles, options.denoiser);
-        this._backendsDir = firstNonEmpty(options.backendsDir, this._config.backendsDir, (0, backends_1.resolveBackendsDir)());
+        this._backendsDir = firstNonEmpty(options.backendsDir, this._config.backendsDir);
         this._openclCacheDir = firstNonEmpty(options.openclCacheDir, this._config.openclCacheDir);
         this._vulkanCacheDir = firstNonEmpty(options.vulkanCacheDir, this._config.vulkanCacheDir);
         assertGpuIntentConsistent(this._config.useGPU, this._nGpuLayers);
@@ -3311,7 +3310,6 @@ class TTSGgml {
 (function (TTSGgml) {
     TTSGgml.QvacErrorAddonTTSGgml = errorModule.QvacErrorAddonTTSGgml;
     TTSGgml.ERR_CODES = errorModule.ERR_CODES;
-    TTSGgml.resolveBackendsDir = backends_1.resolveBackendsDir;
     TTSGgml.assessFit = fit_1.assessFit;
 })(TTSGgml || (TTSGgml = {}));
 module.exports.QvacErrorAddonTTSGgml =

package/lib/fit.js

@@ -1,7 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.assessFit = assessFit;
-const backends_1 = require("./backends");
 /**
  * Projects one voice against the memory free right now, reading GGUF metadata
  * and never weight data. The registry's weightless copy of each file answers
@@ -18,12 +17,7 @@ const backends_1 = require("./backends");
  * throws.
  */
 function assessFit(request) {
-    // eslint-disable-next-line @typescript-eslint/no-require-imports -- native binding is resolved lazily from package prebuilds.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports -- the native binding loads on first use.
     const binding = require('../binding.js');
-    return binding.assessFit({
-        ...request,
-        backendsDir: typeof request.backendsDir === 'string' && request.backendsDir.length > 0
-            ? request.backendsDir
-            : (0, backends_1.resolveBackendsDir)()
-    });
+    return binding.assessFit(request);
 }

package/package.json

@@ -1,8 +1,7 @@
 {
   "name": "@qvac/tts-ggml",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "description": "Text to Speech (TTS) addon for qvac (ggml backend, wrapping the chatterbox + supertonic + parler + cosyvoice3 + audio8 + moss + moss-sfx + moss-speech + Pocket engines from tts-cpp)",
-  "addon": true,
   "qvac": {
     "ggml-speech": "2026-10-07#1"
   },
@@ -12,52 +11,32 @@
   "imports": {
     "#host-addon": {
       "linux": {
-        "x64": [
-          "@qvac/tts-ggml-linux-x64",
-          "./addon-unavailable.js"
-        ],
-        "arm64": [
-          "@qvac/tts-ggml-linux-arm64",
-          "./addon-unavailable.js"
-        ],
+        "x64": "@qvac/tts-ggml-linux-x64",
+        "arm64": "@qvac/tts-ggml-linux-arm64",
         "default": "./addon-unavailable.js"
       },
       "darwin": {
-        "arm64": [
-          "@qvac/tts-ggml-darwin-arm64",
-          "./addon-unavailable.js"
-        ],
-        "x64": [
-          "@qvac/tts-ggml-darwin-x64",
-          "./addon-unavailable.js"
-        ],
+        "arm64": "@qvac/tts-ggml-darwin-arm64",
+        "x64": "@qvac/tts-ggml-darwin-x64",
         "default": "./addon-unavailable.js"
       },
       "win32": {
-        "x64": [
-          "@qvac/tts-ggml-win32-x64",
-          "./addon-unavailable.js"
-        ],
+        "x64": "@qvac/tts-ggml-win32-x64",
         "default": "./addon-unavailable.js"
       },
       "android": {
-        "arm64": [
-          "@qvac/tts-ggml-android-arm64",
-          "./addon-unavailable.js"
-        ],
+        "arm64": "@qvac/tts-ggml-android-arm64",
         "default": "./addon-unavailable.js"
       },
-      "ios": [
-        "@qvac/tts-ggml-ios",
-        "./addon-unavailable.js"
-      ],
+      "ios": "@qvac/tts-ggml-ios",
       "default": "./addon-unavailable.js"
     }
   },
   "scripts": {
     "build": "npm run build:ts && npm run build:native",
-    "build:native": "bare-make generate -D BUILD_FUZZING=OFF && bare-make build && bare-make install",
-    "build:native:cuda": "bare-make generate -D ENABLE_CUDA=ON -D BUILD_FUZZING=OFF && bare-make build && bare-make install",
+    "build:native": "bare-make generate -D BUILD_FUZZING=OFF && bare-make build && bare-make install && npm run link:platform",
+    "build:native:cuda": "bare-make generate -D ENABLE_CUDA=ON -D BUILD_FUZZING=OFF && bare-make build && bare-make install && npm run link:platform",
+    "link:platform": "node ../../scripts/ci/slice-platform-packages.mjs --link-local --workdir .",
     "build:cuda": "npm run build:ts && npm run build:native:cuda",
     "build:ts": "tsc -p tsconfig.build.json",
     "build:pack": "npm run build:ts && mkdir -p dist && npm pack --pack-destination dist",
@@ -86,10 +65,10 @@
     "example:moss-sfx": "bare examples/moss-sound-effect.js \"Heavy rain falling on a tin roof with distant thunder.\" 5",
     "example:moss-speech": "bare examples/moss-speech.js test/reference-audio/jfk.wav",
     "lint": "npm run lint:js && npm run lint:ts && npm run test:types",
-    "lint:js": "prettier --check \"test/**/*.js\" \"scripts/run-cpp-fuzz.js\" \"scripts/__tests__/package-contract.test.js\" \"scripts/__tests__/binding-loader.test.js\" \"scripts/__tests__/run-cpp-fuzz.test.js\" \"binding.js\" \"addon-unavailable.js\" && lunte \"test/**/*.js\" \"scripts/run-cpp-fuzz.js\" \"scripts/__tests__/package-contract.test.js\" \"scripts/__tests__/binding-loader.test.js\" \"scripts/__tests__/run-cpp-fuzz.test.js\" \"binding.js\" \"addon-unavailable.js\"",
+    "lint:js": "prettier --check \"test/**/*.js\" \"scripts/run-cpp-fuzz.js\" \"scripts/__tests__/package-contract.test.js\" \"scripts/__tests__/run-cpp-fuzz.test.js\" \"binding.js\" \"addon-unavailable.js\" && lunte \"test/**/*.js\" \"scripts/run-cpp-fuzz.js\" \"scripts/__tests__/package-contract.test.js\" \"scripts/__tests__/run-cpp-fuzz.test.js\" \"binding.js\" \"addon-unavailable.js\"",
     "lint:ts": "eslint \"src/**/*.ts\" --max-warnings=0",
     "lint:ts:fix": "eslint \"src/**/*.ts\" --fix",
-    "format": "prettier --write \"test/**/*.js\" \"scripts/__tests__/package-contract.test.js\" \"scripts/__tests__/binding-loader.test.js\" \"binding.js\" \"addon-unavailable.js\"",
+    "format": "prettier --write \"test/**/*.js\" \"scripts/__tests__/package-contract.test.js\" \"binding.js\" \"addon-unavailable.js\"",
     "test:unit": "npm run build:ts && brittle-bare test/unit/**/*.test.js && npm run test:node",
     "test:node": "node --test scripts/__tests__/*.test.js",
     "test": "npm run test:types && npm run test:unit && npm run test:integration",
@@ -232,12 +211,24 @@
     "bare-stream": "^2.7.0",
     "bare-url": "^2.4.3"
   },
-  "types": "index.d.ts",
   "optionalDependencies": {
-    "@qvac/tts-ggml-linux-x64": "0.11.1",
-    "@qvac/tts-ggml-linux-arm64": "0.11.1",
-    "@qvac/tts-ggml-darwin-arm64": "0.11.1",
-    "@qvac/tts-ggml-darwin-x64": "0.11.1",
-    "@qvac/tts-ggml-win32-x64": "0.11.1"
+    "@qvac/tts-ggml-linux-x64": "0.12.0",
+    "@qvac/tts-ggml-linux-arm64": "0.12.0",
+    "@qvac/tts-ggml-darwin-arm64": "0.12.0",
+    "@qvac/tts-ggml-darwin-x64": "0.12.0",
+    "@qvac/tts-ggml-win32-x64": "0.12.0"
+  },
+  "types": "index.d.ts",
+  "peerDependencies": {
+    "@qvac/tts-ggml-android-arm64": "0.12.0",
+    "@qvac/tts-ggml-ios": "0.12.0"
+  },
+  "peerDependenciesMeta": {
+    "@qvac/tts-ggml-android-arm64": {
+      "optional": true
+    },
+    "@qvac/tts-ggml-ios": {
+      "optional": true
+    }
   }
 }

package/lib/backends.d.ts

@@ -1,10 +0,0 @@
-export declare const PREBUILT_HOSTS: string[];
-export interface BackendsDirSources {
-    localPrebuildsDir: string;
-    host: string | null;
-    directoryExists: (dir: string) => boolean;
-    resolveManifest: (specifier: string) => string | null;
-}
-export declare function hostPlatformPackage(host: string): string;
-export declare function resolveBackendsDirFrom(sources: BackendsDirSources): string;
-export declare function resolveBackendsDir(): string;

package/lib/backends.js

@@ -1,76 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.PREBUILT_HOSTS = void 0;
-exports.hostPlatformPackage = hostPlatformPackage;
-exports.resolveBackendsDirFrom = resolveBackendsDirFrom;
-exports.resolveBackendsDir = resolveBackendsDir;
-/* eslint-disable @typescript-eslint/no-require-imports -- Bare modules expose CommonJS export shapes. */
-const fs = require("bare-fs");
-const path = require("bare-path");
-/* eslint-enable @typescript-eslint/no-require-imports */
-const PACKAGE_ROOT = path.join(__dirname, "..");
-const PREBUILDS_DIR_NAME = "prebuilds";
-const PLATFORM_ADDON_DIR_NAME = "addon";
-const PLATFORM_PACKAGE_PREFIX = "@qvac/tts-ggml-";
-const PLATFORM_MANIFEST_SUBPATH = "/package";
-const IOS_PLATFORM = "ios";
-const HOST_SEPARATOR = "-";
-exports.PREBUILT_HOSTS = [
-    "linux-x64",
-    "linux-arm64",
-    "darwin-arm64",
-    "darwin-x64",
-    "win32-x64",
-    "android-arm64",
-    "ios-arm64",
-    "ios-arm64-simulator",
-    "ios-x64-simulator",
-];
-function hostPlatformPackage(host) {
-    const platform = host.split(HOST_SEPARATOR)[0];
-    const suffix = platform === IOS_PLATFORM ? IOS_PLATFORM : host;
-    return PLATFORM_PACKAGE_PREFIX + suffix;
-}
-function resolveBackendsDirFrom(sources) {
-    if (sources.directoryExists(sources.localPrebuildsDir)) {
-        return sources.localPrebuildsDir;
-    }
-    return platformPackagePrebuildsDir(sources) ?? sources.localPrebuildsDir;
-}
-function platformPackagePrebuildsDir(sources) {
-    if (!sources.host) {
-        return null;
-    }
-    const manifestPath = sources.resolveManifest(hostPlatformPackage(sources.host) + PLATFORM_MANIFEST_SUBPATH);
-    if (!manifestPath) {
-        return null;
-    }
-    return path.join(path.dirname(manifestPath), PLATFORM_ADDON_DIR_NAME, PREBUILDS_DIR_NAME);
-}
-function resolveBackendsDir() {
-    return resolveBackendsDirFrom({
-        localPrebuildsDir: path.join(PACKAGE_ROOT, PREBUILDS_DIR_NAME),
-        host: currentHost(),
-        directoryExists: safeDirectoryExists,
-        resolveManifest: safeResolveManifest,
-    });
-}
-function currentHost() {
-    return require.addon ? require.addon.host : null;
-}
-function safeDirectoryExists(dir) {
-    try {
-        return fs.existsSync(dir);
-    }
-    catch {
-        return false;
-    }
-}
-function safeResolveManifest(specifier) {
-    try {
-        return require.resolve(specifier);
-    }
-    catch {
-        return null;
-    }
-}