react-native-nitro-onnx 0.1.0 → 0.1.2

package/cpp/Tts.cpp

@@ -4,8 +4,10 @@
 #include "Tts.hpp"
 
 #include "AudioUtils.hpp"
+#include "SpeakerEngine.hpp"
 
 #include <NitroModules/ArrayBuffer.hpp>
+#include <bit>
 #include <fstream>
 #include <stdexcept>
 
@@ -13,6 +15,8 @@ namespace margelo::nitro::onnx::speech {
 
 namespace {
 
+static_assert(std::endian::native == std::endian::little, "WAV writer assumes little-endian targets");
+
 TtsResult toTtsResult(const TtsEngineResult& native) {
   std::vector<uint8_t> bytes = floatVectorToBytes(native.samples);
   return TtsResult(
@@ -23,15 +27,14 @@ TtsResult toTtsResult(const TtsEngineResult& native) {
 
 }  // namespace
 
-Tts::Tts(std::shared_ptr<ThreadPool> threadPool)
-    : HybridObject(TAG), engine_(std::move(threadPool)) {}
+Tts::Tts() : HybridObject(TAG) {}
 
 Tts::~Tts() {
   engine_.unload();
 }
 
 std::shared_ptr<Promise<void>> Tts::load(const TtsModelConfig& config) {
-  return Promise<void>::async([this, config]() {
+  return Promise<void>::async([self = shared_cast<Tts>(), config]() {
     TtsEngineConfig native;
     native.type = static_cast<TtsModelType>(config.type);
     native.modelDir = config.modelDir;
@@ -57,7 +60,13 @@ std::shared_ptr<Promise<void>> Tts::load(const TtsModelConfig& config) {
     native.outputSampleRate = static_cast<int32_t>(config.outputSampleRate.value_or(16000.0));
     native.speakerId = static_cast<int32_t>(config.speakerId.value_or(0.0));
     native.speed = static_cast<float>(config.speed.value_or(1.0));
-    engine_.load(native);
+    native.debug = config.debug.value_or(false);
+#ifdef __APPLE__
+    native.provider = config.provider.value_or("coreml");
+#else
+    native.provider = config.provider.value_or("cpu");
+#endif
+    self->engine_.load(native);
   });
 }
 
@@ -66,9 +75,9 @@ bool Tts::isLoaded() {
 }
 
 std::shared_ptr<Promise<TtsResult>> Tts::synthesize(const std::string& text, std::optional<double> speed) {
-  return Promise<TtsResult>::async([this, text, speed]() {
+  return Promise<TtsResult>::async([self = shared_cast<Tts>(), text, speed]() {
     float spd = speed.has_value() ? static_cast<float>(speed.value()) : -1.0f;
-    return toTtsResult(engine_.synthesize(text, -1, spd));
+    return toTtsResult(self->engine_.synthesize(text, -1, spd));
   });
 }
 
@@ -76,10 +85,35 @@ std::shared_ptr<Promise<TtsResult>> Tts::synthesizeWithSpeaker(
     const std::string& text,
     const std::string& speakerId,
     std::optional<double> speed) {
-  return Promise<TtsResult>::async([this, text, speakerId, speed]() {
-    int32_t sid = std::stoi(speakerId);
+  return Promise<TtsResult>::async([self = shared_cast<Tts>(), text, speakerId, speed]() {
+    if (text.empty()) {
+      throw std::invalid_argument("TTS text must not be empty");
+    }
+    if (speakerId.empty()) {
+      throw std::invalid_argument("speakerId must not be empty");
+    }
     float spd = speed.has_value() ? static_cast<float>(speed.value()) : -1.0f;
-    return toTtsResult(engine_.synthesize(text, sid, spd));
+
+    // Numeric IDs are model-internal speaker indices (Kokoro / VITS multi-speaker).
+    int32_t sid = -1;
+    if (tryParseSpeakerIndex(speakerId, sid)) {
+      return toTtsResult(self->engine_.synthesize(text, sid, spd));
+    }
+
+    // String IDs refer to registered speakers (voice-cloning path).
+    const SpeakerEngineRegisteredSpeaker record =
+        readSpeakerRecord(speakerId, speakerFilePath(speakerId));
+    if (!record.referenceAudio.empty()) {
+      TtsReferenceAudio reference;
+      reference.samples = record.referenceAudio;
+      reference.sampleRate = record.referenceSampleRate > 0 ? record.referenceSampleRate : 16000;
+      return toTtsResult(self->engine_.synthesize(text, -1, spd, &reference));
+    }
+
+    throw std::invalid_argument(
+        "Speaker \"" + speakerId + "\" was registered from an embedding only. "
+        "Zero-shot TTS needs reference audio — use registerSpeakerFromFile(). "
+        "For multi-speaker models (kokoro/vits), pass a numeric speaker index instead.");
   });
 }
 
@@ -126,7 +160,7 @@ std::shared_ptr<Promise<void>> Tts::saveWav(const TtsResult& result, const std::
 }
 
 std::shared_ptr<Promise<void>> Tts::unload() {
-  return Promise<void>::async([this]() { engine_.unload(); });
+  return Promise<void>::async([self = shared_cast<Tts>()]() { self->engine_.unload(); });
 }
 
 }  // namespace margelo::nitro::onnx::speech

package/cpp/Tts.hpp

@@ -11,6 +11,7 @@
 
 #include <memory>
 #include <optional>
+#include <string>
 
 namespace margelo::nitro::onnx::speech {
 
@@ -18,7 +19,7 @@ class Tts : public HybridTtsSpec {
  public:
   static constexpr auto TAG = "Tts";
 
-  explicit Tts(std::shared_ptr<ThreadPool> threadPool);
+  Tts();
   ~Tts() override;
 
   std::shared_ptr<Promise<void>> load(const TtsModelConfig& config) override;

package/cpp/TtsEngine.cpp

@@ -51,9 +51,6 @@ ModelSingleton<const SherpaOnnxOfflineTts> gTtsCache;
 
 }  // namespace
 
-TtsEngine::TtsEngine(std::shared_ptr<ThreadPool> threadPool)
-    : threadPool_(std::move(threadPool)) {}
-
 TtsEngine::~TtsEngine() {
   unload();
 }
@@ -62,8 +59,7 @@ void TtsEngine::load(const TtsEngineConfig& config) {
   unload();
   config_ = config;
 
-  const std::string key = config_.modelDir + "|" + std::to_string(static_cast<int>(config_.type));
-  auto cached = gTtsCache.getOrCreate(key, [this](const std::string&) {
+  auto cached = gTtsCache.getOrCreate(config_.cacheSignature(), [this](const std::string&) {
     SherpaOnnxOfflineTtsConfig c;
     std::memset(&c, 0, sizeof(c));
 
@@ -75,7 +71,6 @@ void TtsEngine::load(const TtsEngineConfig& config) {
     std::string voices = joinPath(config_.modelDir, config_.voices);
     std::string espeakNgData = joinPath(config_.modelDir, config_.espeakNgData);
     std::string dictDir = joinPath(config_.modelDir, config_.dictDir);
-    std::string configPath = joinPath(config_.modelDir, config_.config);
 
     std::string lmMain = joinPath(config_.modelDir, config_.lmMain);
     std::string lmFlow = joinPath(config_.modelDir, config_.lmFlow);
@@ -146,8 +141,8 @@ void TtsEngine::load(const TtsEngineConfig& config) {
     }
 
     c.model.num_threads = config_.numThreads;
-    c.model.debug = 1;
-    c.model.provider = "cpu";
+    c.model.debug = config_.debug ? 1 : 0;
+    c.model.provider = config_.provider.c_str();
     c.rule_fsts = "";
     c.rule_fars = "";
     c.max_num_sentences = 1;
@@ -171,10 +166,17 @@ bool TtsEngine::isLoaded() const {
   return tts_ != nullptr;
 }
 
-TtsEngineResult TtsEngine::synthesize(const std::string& text, int32_t speakerId, float speed) {
+TtsEngineResult TtsEngine::synthesize(
+    const std::string& text,
+    int32_t speakerId,
+    float speed,
+    const TtsReferenceAudio* referenceAudio) {
   if (tts_ == nullptr) {
     throw std::runtime_error("TTS not loaded");
   }
+  if (text.empty()) {
+    throw std::invalid_argument("TTS text must not be empty");
+  }
 
   const int32_t sid = speakerId >= 0 ? speakerId : config_.speakerId;
   const float playbackSpeed = speed > 0.0f ? speed : config_.speed;
@@ -183,6 +185,12 @@ TtsEngineResult TtsEngine::synthesize(const std::string& text, int32_t speakerId
   std::memset(&genConfig, 0, sizeof(genConfig));
   genConfig.sid = sid;
   genConfig.speed = playbackSpeed;
+  if (referenceAudio != nullptr && !referenceAudio->samples.empty()) {
+    genConfig.reference_audio = referenceAudio->samples.data();
+    genConfig.reference_audio_len = static_cast<int32_t>(referenceAudio->samples.size());
+    genConfig.reference_sample_rate =
+        referenceAudio->sampleRate > 0 ? referenceAudio->sampleRate : 16000;
+  }
 
   const SherpaOnnxGeneratedAudio* audio = SherpaOnnxOfflineTtsGenerateWithConfig(
       tts_.get(), text.c_str(), &genConfig, nullptr, nullptr);

package/cpp/TtsEngine.hpp

@@ -1,13 +1,12 @@
 // ------------------------------------------------------------------------------
 // TtsEngine.hpp
 // Text-to-speech wrapper backed by sherpa-onnx OfflineTts.
-// Supports Kokoro, VITS, Matcha, Pocket and ZipVoice (placeholder) models.
+// Supports Kokoro, VITS, Matcha, Pocket and ZipVoice models.
 // ------------------------------------------------------------------------------
 #pragma once
 
 #include "AudioUtils.hpp"
 #include "ModelSingleton.hpp"
-#include "ThreadPool.hpp"
 
 #include "TtsModelType.hpp"
 
@@ -45,6 +44,17 @@ struct TtsEngineConfig {
   int32_t outputSampleRate = 16000;
   int32_t speakerId = 0;
   float speed = 1.0f;
+  bool debug = false;
+#ifdef __APPLE__
+  std::string provider = "coreml";
+#else
+  std::string provider = "cpu";
+#endif
+
+  std::string cacheSignature() const {
+    return modelDir + "|" + std::to_string(static_cast<int>(type)) + "|" + provider + "|" +
+           std::to_string(numThreads) + "|" + std::to_string(outputSampleRate);
+  }
 };
 
 /** Native synthesis result (samples are kept as a float vector). */
@@ -54,10 +64,16 @@ struct TtsEngineResult {
   double durationMs = 0.0;
 };
 
+/** Optional zero-shot reference audio for voice-cloning models (e.g. Pocket). */
+struct TtsReferenceAudio {
+  std::vector<float> samples;
+  int32_t sampleRate = 16000;
+};
+
 /** Text-to-speech engine. */
 class TtsEngine final {
  public:
-  explicit TtsEngine(std::shared_ptr<ThreadPool> threadPool);
+  TtsEngine() = default;
   ~TtsEngine();
 
   TtsEngine(const TtsEngine&) = delete;
@@ -65,11 +81,14 @@ class TtsEngine final {
 
   void load(const TtsEngineConfig& config);
   bool isLoaded() const;
-  TtsEngineResult synthesize(const std::string& text, int32_t speakerId, float speed);
+  TtsEngineResult synthesize(
+      const std::string& text,
+      int32_t speakerId,
+      float speed,
+      const TtsReferenceAudio* referenceAudio = nullptr);
   void unload();
 
  private:
-  std::shared_ptr<ThreadPool> threadPool_;
   TtsEngineConfig config_;
   std::shared_ptr<const SherpaOnnxOfflineTts> tts_;
 };

package/cpp/Vad.cpp

@@ -32,8 +32,7 @@ std::vector<VadSegment> toVadSegments(const std::vector<VadEngineSegment>& nativ
 
 }  // namespace
 
-Vad::Vad(std::shared_ptr<ThreadPool> threadPool)
-    : HybridObject(TAG), engine_(std::move(threadPool)) {}
+Vad::Vad() : HybridObject(TAG) {}
 
 Vad::~Vad() {
   engine_.dispose();
@@ -41,20 +40,21 @@ Vad::~Vad() {
 
 std::shared_ptr<Promise<void>> Vad::initialize(const VadConfig& config) {
   currentConfig_ = config;
-  return Promise<void>::async([this, config]() {
+  return Promise<void>::async([self = shared_cast<Vad>(), config]() {
     // Use the bundled silero_vad.onnx when no custom path is provided.
     const std::string& resDir = getResourceDir();
     const std::string modelPath = config.modelPath.value_or(
         resDir.empty() ? "silero_vad.onnx" : resDir + "/silero_vad.onnx");
-    engine_.initialize(
+    self->engine_.initialize(
         {
             .modelPath = modelPath,
             .threshold = static_cast<float>(config.threshold.value_or(0.5)),
             .minSilenceDuration = static_cast<float>(config.minSilenceDurationMs.value_or(500.0)) / 1000.0f,
             .minSpeechDuration = static_cast<float>(config.minSpeechDurationMs.value_or(250.0)) / 1000.0f,
             .preBufferMs = static_cast<int32_t>(config.preBufferMs.value_or(300.0)),
+            .debug = config.debug.value_or(false),
         },
-        shared_cast<Vad>());
+        self);
   });
 }
 
@@ -63,19 +63,20 @@ bool Vad::isInitialized() {
 }
 
 std::shared_ptr<Promise<void>> Vad::process(const std::shared_ptr<ArrayBuffer>& samples) {
-  return Promise<void>::async([this, samples]() {
-    const auto data = samples->data();
-    auto floatSamples = bytesToFloatVector(data, samples->size());
-    engine_.acceptWaveform(floatSamples);
+  return Promise<void>::async([self = shared_cast<Vad>(), samples]() {
+    auto floatSamples = bytesToFloatVector(samples->data(), samples->size());
+    self->engine_.acceptWaveform(std::move(floatSamples));
   });
 }
 
 std::shared_ptr<Promise<std::vector<VadSegment>>> Vad::pullSegments() {
-  return Promise<std::vector<VadSegment>>::async([this]() { return toVadSegments(engine_.pullSegments()); });
+  return Promise<std::vector<VadSegment>>::async([self = shared_cast<Vad>()]() {
+    return toVadSegments(self->engine_.pullSegments());
+  });
 }
 
 std::shared_ptr<Promise<void>> Vad::reset() {
-  return Promise<void>::async([this]() { engine_.reset(); });
+  return Promise<void>::async([self = shared_cast<Vad>()]() { self->engine_.reset(); });
 }
 
 std::optional<std::function<void(const VadSegment& /* segment */)>> Vad::getOnSpeechStart() {

package/cpp/Vad.hpp

@@ -25,7 +25,7 @@ class Vad : public HybridVadSpec,
  public:
   static constexpr auto TAG = "Vad";
 
-  explicit Vad(std::shared_ptr<ThreadPool> threadPool);
+  Vad();
   ~Vad() override;
 
   std::shared_ptr<Promise<void>> initialize(const VadConfig& config) override;

package/cpp/VadEngine.cpp

@@ -5,7 +5,6 @@
 
 #include "sherpa-onnx/c-api/c-api.h"
 
-#include <algorithm>
 #include <cstring>
 #include <stdexcept>
 
@@ -17,9 +16,6 @@ constexpr int32_t kSampleRate = 16000;
 
 }  // namespace
 
-VadEngine::VadEngine(std::shared_ptr<ThreadPool> threadPool)
-    : threadPool_(std::move(threadPool)) {}
-
 VadEngine::~VadEngine() {
   dispose();
 }
@@ -30,7 +26,7 @@ void VadEngine::initialize(const VadEngineConfig& config, std::shared_ptr<VadLis
   config_ = config;
   listener_ = std::move(listener);
   preBufferCapacity_ = static_cast<size_t>(msToSamples(config_.preBufferMs));
-  preBuffer_.reserve(preBufferCapacity_);
+  preBuffer_.clear();
   streamMs_ = 0.0f;
   inSpeech_ = false;
 
@@ -42,6 +38,7 @@ void VadEngine::initialize(const VadEngineConfig& config, std::shared_ptr<VadLis
   vadConfig.silero_vad.min_speech_duration = config_.minSpeechDuration;
   vadConfig.sample_rate = kSampleRate;
   vadConfig.num_threads = 1;
+  vadConfig.debug = config_.debug ? 1 : 0;
 
   // The second argument is the buffer size in milliseconds used internally by
   // sherpa-onnx. We reuse the configured pre-buffer duration.
@@ -52,6 +49,7 @@ void VadEngine::initialize(const VadEngineConfig& config, std::shared_ptr<VadLis
 
   initialized_ = true;
   stop_ = false;
+  resetRequested_ = false;
   processorThread_ = std::thread(&VadEngine::processLoop, this);
 }
 
@@ -59,10 +57,10 @@ bool VadEngine::isInitialized() const {
   return initialized_.load();
 }
 
-void VadEngine::acceptWaveform(const std::vector<float>& samples) {
+void VadEngine::acceptWaveform(std::vector<float> samples) {
   {
     std::lock_guard<std::mutex> lock(inputMutex_);
-    inputQueue_.emplace(samples);
+    inputQueue_.emplace(std::move(samples));
   }
   inputCv_.notify_one();
 }
@@ -89,12 +87,9 @@ void VadEngine::reset() {
     pendingSegments_.clear();
   }
 
-  if (vad_) {
-    SherpaOnnxVoiceActivityDetectorClear(vad_);
-  }
-
-  // Defer speech-state clearing to the processor thread to avoid a data race.
+  // Clear the sherpa VAD on the processor thread to avoid racing with accept.
   resetRequested_ = true;
+  inputCv_.notify_one();
 }
 
 void VadEngine::dispose() {
@@ -116,10 +111,21 @@ void VadEngine::processLoop() {
     std::vector<float> chunk;
     {
       std::unique_lock<std::mutex> lock(inputMutex_);
-      inputCv_.wait(lock, [this]() { return stop_ || !inputQueue_.empty(); });
+      inputCv_.wait(lock, [this]() { return stop_ || resetRequested_ || !inputQueue_.empty(); });
       if (stop_) {
         break;
       }
+      if (resetRequested_.exchange(false)) {
+        if (vad_) {
+          SherpaOnnxVoiceActivityDetectorClear(vad_);
+        }
+        inSpeech_ = false;
+        currentSpeechSamples_.clear();
+        streamMs_ = 0.0f;
+      }
+      if (inputQueue_.empty()) {
+        continue;
+      }
       chunk = std::move(inputQueue_.front());
       inputQueue_.pop();
     }
@@ -128,20 +134,13 @@ void VadEngine::processLoop() {
       continue;
     }
 
-    if (resetRequested_.exchange(false)) {
-      inSpeech_ = false;
-      currentSpeechSamples_.clear();
-      streamMs_ = 0.0f;
-    }
-
     // Update the sliding pre-buffer with the newest chunk. This is the key
     // mechanism that preserves leading audio for onSpeechStart/onSpeechEnd.
     {
       std::lock_guard<std::mutex> lock(preBufferMutex_);
       preBuffer_.insert(preBuffer_.end(), chunk.begin(), chunk.end());
-      if (preBuffer_.size() > preBufferCapacity_) {
-        const size_t excess = preBuffer_.size() - preBufferCapacity_;
-        preBuffer_.erase(preBuffer_.begin(), preBuffer_.begin() + excess);
+      while (preBuffer_.size() > preBufferCapacity_) {
+        preBuffer_.pop_front();
       }
     }
 
@@ -150,6 +149,7 @@ void VadEngine::processLoop() {
     streamMs_ += samplesToMs(static_cast<int32_t>(chunk.size()));
 
     const bool speechDetected = SherpaOnnxVoiceActivityDetectorDetected(vad_) != 0;
+    std::shared_ptr<VadListener> listener = listener_.lock();
 
     if (speechDetected && !inSpeech_) {
       // Transition to speech: capture the sliding pre-buffer as the start of
@@ -159,15 +159,15 @@ void VadEngine::processLoop() {
       currentSpeechStartMs_ = streamMs_ - samplesToMs(static_cast<int32_t>(chunk.size()));
       {
         std::lock_guard<std::mutex> lock(preBufferMutex_);
-        currentSpeechSamples_ = preBuffer_;
+        currentSpeechSamples_.assign(preBuffer_.begin(), preBuffer_.end());
       }
 
       VadEngineSegment startSegment;
       startSegment.startMs = currentSpeechStartMs_ - samplesToMs(static_cast<int32_t>(currentSpeechSamples_.size()));
       startSegment.endMs = currentSpeechStartMs_;
       startSegment.samples = currentSpeechSamples_;
-      if (listener_) {
-        listener_->onSpeechStart(startSegment);
+      if (listener) {
+        listener->onSpeechStart(startSegment);
       }
     }
 
@@ -199,8 +199,8 @@ void VadEngine::processLoop() {
         std::lock_guard<std::mutex> lock(outputMutex_);
         pendingSegments_.push_back(endSegment);
       }
-      if (listener_) {
-        listener_->onSpeechEnd(endSegment);
+      if (listener) {
+        listener->onSpeechEnd(endSegment);
       }
 
       inSpeech_ = false;
@@ -208,10 +208,4 @@ void VadEngine::processLoop() {
   }
 }
 
-void VadEngine::flushPreBuffer(std::vector<float>& target) {
-  std::lock_guard<std::mutex> lock(preBufferMutex_);
-  target.insert(target.end(), preBuffer_.begin(), preBuffer_.end());
-  preBuffer_.clear();
-}
-
 }  // namespace margelo::nitro::onnx::speech

package/cpp/VadEngine.hpp

@@ -12,9 +12,10 @@
 #pragma once
 
 #include "AudioUtils.hpp"
-#include "ThreadPool.hpp"
 
+#include <atomic>
 #include <condition_variable>
+#include <deque>
 #include <memory>
 #include <mutex>
 #include <optional>
@@ -34,6 +35,7 @@ struct VadEngineConfig {
   float minSilenceDuration = 0.5f;
   float minSpeechDuration = 0.25f;
   int32_t preBufferMs = 300;
+  bool debug = false;
 };
 
 /** One buffered or emitted speech segment with raw float samples. */
@@ -61,7 +63,7 @@ class VadListener {
  */
 class VadEngine final {
  public:
-  explicit VadEngine(std::shared_ptr<ThreadPool> threadPool);
+  VadEngine() = default;
   ~VadEngine();
 
   VadEngine(const VadEngine&) = delete;
@@ -73,8 +75,8 @@ class VadEngine final {
   /** Return true if the VAD has been initialized. */
   bool isInitialized() const;
 
-  /** Feed a chunk of 16 kHz mono f32 PCM audio. Non-blocking. */
-  void acceptWaveform(const std::vector<float>& samples);
+  /** Feed a chunk of 16 kHz mono f32 PCM audio. Non-blocking. Takes ownership. */
+  void acceptWaveform(std::vector<float> samples);
 
   /** Return any buffered segments without waiting for speech end. */
   std::vector<VadEngineSegment> pullSegments();
@@ -87,11 +89,8 @@ class VadEngine final {
 
  private:
   void processLoop();
-  void flushPreBuffer(std::vector<float>& target);
-  void emitSegment();
 
-  std::shared_ptr<ThreadPool> threadPool_;
-  std::shared_ptr<VadListener> listener_;
+  std::weak_ptr<VadListener> listener_;
 
   const SherpaOnnxVoiceActivityDetector* vad_ = nullptr;
   VadEngineConfig config_;
@@ -106,7 +105,7 @@ class VadEngine final {
 
   // Sliding pre-buffer. Always holds the most recent N milliseconds of audio.
   std::mutex preBufferMutex_;
-  std::vector<float> preBuffer_;
+  std::deque<float> preBuffer_;
   size_t preBufferCapacity_ = 0;
 
   // Output segments waiting to be pulled.
@@ -116,7 +115,7 @@ class VadEngine final {
   // Processor thread.
   std::thread processorThread_;
 
-  // Stream time tracking.
+  // Stream time tracking. Only touched by the processor thread.
   float streamMs_ = 0.0f;
   bool inSpeech_ = false;
   float currentSpeechStartMs_ = 0.0f;

package/cpp/Version.hpp

@@ -0,0 +1,7 @@
+// ------------------------------------------------------------------------------
+// Version.hpp
+// Generated from package.json by scripts/generate-version.js. DO NOT EDIT.
+// ------------------------------------------------------------------------------
+#pragma once
+
+#define NITRO_ONNX_SPEECH_VERSION "0.1.2"

package/ios/OnnxSpeechInitializer.mm

@@ -1,7 +1,7 @@
 // ------------------------------------------------------------------------------
 // OnnxSpeechInitializer.mm
 // ------------------------------------------------------------------------------
-// Sets up resource and cache directories for the C++ layer on iOS.
+// Sets up resource and document directories for the C++ layer on iOS.
 // Runs at +load time so paths are available before any HybridObject is created.
 // ------------------------------------------------------------------------------
 #import <Foundation/Foundation.h>
@@ -26,12 +26,24 @@
     margelo::nitro::onnx::speech::setResourceDir([[mainBundle resourcePath] UTF8String]);
   }
 
-  NSArray<NSString*>* cachePaths = NSSearchPathForDirectoriesInDomains(
-      NSCachesDirectory, NSUserDomainMask, YES);
-  NSString* cacheDir = cachePaths.firstObject;
-  if (cacheDir) {
-    margelo::nitro::onnx::speech::setCacheDir([cacheDir UTF8String]);
+  // Application Support (not Documents): speaker embeddings are derived data
+  // and must not be backed up to iCloud.
+  NSArray<NSString*>* supportPaths = NSSearchPathForDirectoriesInDomains(
+      NSApplicationSupportDirectory, NSUserDomainMask, YES);
+  NSString* documentDir = supportPaths.firstObject;
+  if (documentDir == nil) {
+    return;
   }
+
+  NSError* error = nil;
+  [[NSFileManager defaultManager] createDirectoryAtPath:documentDir
+                            withIntermediateDirectories:YES
+                                             attributes:nil
+                                                  error:&error];
+  NSURL* dirURL = [NSURL fileURLWithPath:documentDir isDirectory:YES];
+  [dirURL setResourceValue:@YES forKey:NSURLIsExcludedFromBackupKey error:nil];
+
+  margelo::nitro::onnx::speech::setDocumentDir([documentDir UTF8String]);
 }
 
 @end