react-native-nitro-onnx 0.1.1 → 0.1.2

package/cpp/SpeakerEngine.cpp

@@ -4,12 +4,13 @@
 #include "SpeakerEngine.hpp"
 
 #include "AudioFileReader.hpp"
+#include "ResourceDir.hpp"
+#include "SpeakerRecord.hpp"
 #include "sherpa-onnx/c-api/c-api.h"
 
 #include <cstring>
 #include <filesystem>
 #include <fstream>
-#include <sstream>
 #include <stdexcept>
 
 namespace margelo::nitro::onnx::speech {
@@ -36,8 +37,9 @@ ModelSingleton<const SherpaOnnxSpeakerEmbeddingExtractor> gExtractorCache;
 
 }  // namespace
 
-SpeakerEngine::SpeakerEngine(std::shared_ptr<ThreadPool> threadPool, std::string cacheDir)
-    : threadPool_(std::move(threadPool)), cacheDir_(std::move(cacheDir)) {}
+std::string speakerFilePath(const std::string& id) {
+  return joinPath(joinPath(getDocumentDir(), "speakers"), id + ".bin");
+}
 
 SpeakerEngine::~SpeakerEngine() {
   unload();
@@ -47,8 +49,7 @@ void SpeakerEngine::load(const SpeakerEngineConfig& config) {
   unload();
   config_ = config;
 
-  const std::string key = config_.modelDir + "|speaker";
-  auto cached = gExtractorCache.getOrCreate(key, [this](const std::string&) {
+  auto cached = gExtractorCache.getOrCreate(config_.cacheSignature(), [this](const std::string&) {
     SherpaOnnxSpeakerEmbeddingExtractorConfig c;
     std::memset(&c, 0, sizeof(c));
 
@@ -98,18 +99,19 @@ SpeakerEngineRegisteredSpeaker SpeakerEngine::registerSpeaker(
     const std::string& id,
     const std::string& name,
     const std::vector<float>& embedding) {
-  const std::string speakersDir = joinPath(cacheDir_, "speakers");
-  std::filesystem::create_directories(speakersDir);
-  const std::string path = joinPath(speakersDir, id + ".bin");
-  std::ofstream file(path, std::ios::binary);
-  if (!file) {
-    throw std::runtime_error("Failed to write speaker embedding: " + path);
+  if (id.empty()) {
+    throw std::invalid_argument("Speaker id must not be empty");
   }
-  const auto nameLen = static_cast<uint32_t>(name.size());
-  file.write(reinterpret_cast<const char*>(&nameLen), sizeof(nameLen));
-  file.write(name.data(), name.size());
-  file.write(reinterpret_cast<const char*>(embedding.data()), embedding.size() * sizeof(float));
-  return {id, name, path};
+  const std::string speakersDir = joinPath(getDocumentDir(), "speakers");
+  std::filesystem::create_directories(speakersDir);
+  const std::string path = speakerFilePath(id);
+  writeSpeakerRecord(path, name, embedding, nullptr, 0);
+  SpeakerEngineRegisteredSpeaker result;
+  result.id = id;
+  result.name = name;
+  result.embeddingPath = path;
+  result.embedding = embedding;
+  return result;
 }
 
 SpeakerEngineRegisteredSpeaker SpeakerEngine::registerSpeakerFromFile(
@@ -126,11 +128,24 @@ SpeakerEngineRegisteredSpeaker SpeakerEngine::registerSpeakerFromFile(
     samples = readRawPcmFile(path);
   }
   auto embedding = computeEmbedding(samples);
-  return registerSpeaker(id, name, embedding);
+
+  const std::string speakersDir = joinPath(getDocumentDir(), "speakers");
+  std::filesystem::create_directories(speakersDir);
+  const std::string outPath = speakerFilePath(id);
+  writeSpeakerRecord(outPath, name, embedding, &samples, 16000);
+
+  SpeakerEngineRegisteredSpeaker result;
+  result.id = id;
+  result.name = name;
+  result.embeddingPath = outPath;
+  result.embedding = std::move(embedding);
+  result.referenceAudio = std::move(samples);
+  result.referenceSampleRate = 16000;
+  return result;
 }
 
 std::vector<SpeakerEngineRegisteredSpeaker> SpeakerEngine::listSpeakers() {
-  const std::string speakersDir = joinPath(cacheDir_, "speakers");
+  const std::string speakersDir = joinPath(getDocumentDir(), "speakers");
   std::vector<SpeakerEngineRegisteredSpeaker> result;
   if (!std::filesystem::exists(speakersDir)) {
     return result;
@@ -140,22 +155,17 @@ std::vector<SpeakerEngineRegisteredSpeaker> SpeakerEngine::listSpeakers() {
     const auto& filePath = entry.path();
     if (filePath.extension() != ".bin") continue;
     const std::string id = filePath.stem().string();
-    std::ifstream file(filePath, std::ios::binary);
-    if (!file) continue;
-    uint32_t nameLen = 0;
-    file.read(reinterpret_cast<char*>(&nameLen), sizeof(nameLen));
-    std::string name;
-    if (nameLen > 0 && nameLen < 1024) {
-      name.resize(nameLen);
-      file.read(name.data(), nameLen);
+    try {
+      result.push_back(readSpeakerRecord(id, filePath.string()));
+    } catch (...) {
+      // Skip unreadable / legacy records.
     }
-    result.push_back({id, name, filePath.string()});
   }
   return result;
 }
 
 void SpeakerEngine::removeSpeaker(const std::string& id) {
-  const std::string path = joinPath(cacheDir_, "speakers/" + id + ".bin");
+  const std::string path = speakerFilePath(id);
   std::error_code ec;
   std::filesystem::remove(path, ec);
   if (ec) {

package/cpp/SpeakerEngine.hpp

@@ -10,7 +10,8 @@
 
 #include "AudioUtils.hpp"
 #include "ModelSingleton.hpp"
-#include "ThreadPool.hpp"
+#include "ResourceDir.hpp"
+#include "SpeakerRecord.hpp"
 
 #include <memory>
 #include <string>
@@ -26,19 +27,19 @@ struct SpeakerEngineConfig {
   std::string modelDir;
   std::string model;
   int32_t numThreads = 4;
-};
 
-/** Native registered speaker metadata before conversion to the generated type. */
-struct SpeakerEngineRegisteredSpeaker {
-  std::string id;
-  std::string name;
-  std::string embeddingPath;
+  std::string cacheSignature() const {
+    return modelDir + "|speaker|" + model + "|" + std::to_string(numThreads);
+  }
 };
 
+/** Return the on-disk path for a registered speaker id under the document dir. */
+std::string speakerFilePath(const std::string& id);
+
 /** Speaker manager engine. */
 class SpeakerEngine final {
  public:
-  explicit SpeakerEngine(std::shared_ptr<ThreadPool> threadPool, std::string cacheDir);
+  SpeakerEngine() = default;
   ~SpeakerEngine();
 
   SpeakerEngine(const SpeakerEngine&) = delete;
@@ -51,18 +52,18 @@ class SpeakerEngine final {
   std::vector<float> computeEmbedding(const std::vector<float>& samples);
 
   /** Register a speaker embedding for later TTS use. */
-  SpeakerEngineRegisteredSpeaker registerSpeaker(const std::string& id, const std::string& name, const std::vector<float>& embedding);
+  SpeakerEngineRegisteredSpeaker registerSpeaker(
+      const std::string& id, const std::string& name, const std::vector<float>& embedding);
 
-  /** Register a speaker from a reference audio file. */
-  SpeakerEngineRegisteredSpeaker registerSpeakerFromFile(const std::string& id, const std::string& name, const std::string& path);
+  /** Register a speaker from a reference audio file (stores embedding + reference audio). */
+  SpeakerEngineRegisteredSpeaker registerSpeakerFromFile(
+      const std::string& id, const std::string& name, const std::string& path);
 
   std::vector<SpeakerEngineRegisteredSpeaker> listSpeakers();
   void removeSpeaker(const std::string& id);
   void unload();
 
  private:
-  std::shared_ptr<ThreadPool> threadPool_;
-  std::string cacheDir_;
   SpeakerEngineConfig config_;
   std::shared_ptr<const SherpaOnnxSpeakerEmbeddingExtractor> extractor_;
 };

package/cpp/SpeakerManager.cpp

@@ -26,20 +26,20 @@ std::vector<RegisteredSpeaker> toRegisteredSpeakers(const std::vector<SpeakerEng
 
 }  // namespace
 
-SpeakerManager::SpeakerManager(std::shared_ptr<ThreadPool> threadPool, std::string cacheDir)
-    : HybridObject(TAG), engine_(std::move(threadPool), std::move(cacheDir)) {}
+SpeakerManager::SpeakerManager()
+    : HybridObject(TAG) {}
 
 SpeakerManager::~SpeakerManager() {
   engine_.unload();
 }
 
 std::shared_ptr<Promise<void>> SpeakerManager::load(const SpeakerEmbeddingConfig& config) {
-  return Promise<void>::async([this, config]() {
+  return Promise<void>::async([self = shared_cast<SpeakerManager>(), config]() {
     SpeakerEngineConfig native;
     native.modelDir = config.modelDir;
     native.model = config.model;
     native.numThreads = config.numThreads;
-    engine_.load(native);
+    self->engine_.load(native);
   });
 }
 
@@ -49,9 +49,9 @@ bool SpeakerManager::isLoaded() {
 
 std::shared_ptr<Promise<std::shared_ptr<ArrayBuffer>>> SpeakerManager::computeEmbedding(
     const std::shared_ptr<ArrayBuffer>& samples) {
-  return Promise<std::shared_ptr<ArrayBuffer>>::async([this, samples]() {
+  return Promise<std::shared_ptr<ArrayBuffer>>::async([self = shared_cast<SpeakerManager>(), samples]() {
     auto floatSamples = bytesToFloatVector(samples->data(), samples->size());
-    auto embedding = engine_.computeEmbedding(floatSamples);
+    auto embedding = self->engine_.computeEmbedding(floatSamples);
     auto bytes = floatVectorToBytes(embedding);
     return ArrayBuffer::move(std::move(bytes));
   });
@@ -61,9 +61,9 @@ std::shared_ptr<Promise<RegisteredSpeaker>> SpeakerManager::registerSpeaker(
     const std::string& id,
     const std::string& name,
     const std::shared_ptr<ArrayBuffer>& embedding) {
-  return Promise<RegisteredSpeaker>::async([this, id, name, embedding]() {
+  return Promise<RegisteredSpeaker>::async([self = shared_cast<SpeakerManager>(), id, name, embedding]() {
     auto floatEmbedding = bytesToFloatVector(embedding->data(), embedding->size());
-    return toRegisteredSpeaker(engine_.registerSpeaker(id, name, floatEmbedding));
+    return toRegisteredSpeaker(self->engine_.registerSpeaker(id, name, floatEmbedding));
   });
 }
 
@@ -71,23 +71,25 @@ std::shared_ptr<Promise<RegisteredSpeaker>> SpeakerManager::registerSpeakerFromF
     const std::string& id,
     const std::string& name,
     const std::string& path) {
-  return Promise<RegisteredSpeaker>::async([this, id, name, path]() {
-    return toRegisteredSpeaker(engine_.registerSpeakerFromFile(id, name, path));
+  return Promise<RegisteredSpeaker>::async([self = shared_cast<SpeakerManager>(), id, name, path]() {
+    return toRegisteredSpeaker(self->engine_.registerSpeakerFromFile(id, name, path));
   });
 }
 
 std::shared_ptr<Promise<std::vector<RegisteredSpeaker>>> SpeakerManager::listSpeakers() {
-  return Promise<std::vector<RegisteredSpeaker>>::async([this]() {
-    return toRegisteredSpeakers(engine_.listSpeakers());
+  return Promise<std::vector<RegisteredSpeaker>>::async([self = shared_cast<SpeakerManager>()]() {
+    return toRegisteredSpeakers(self->engine_.listSpeakers());
   });
 }
 
 std::shared_ptr<Promise<void>> SpeakerManager::removeSpeaker(const std::string& id) {
-  return Promise<void>::async([this, id]() { engine_.removeSpeaker(id); });
+  return Promise<void>::async([self = shared_cast<SpeakerManager>(), id]() {
+    self->engine_.removeSpeaker(id);
+  });
 }
 
 std::shared_ptr<Promise<void>> SpeakerManager::unload() {
-  return Promise<void>::async([this]() { engine_.unload(); });
+  return Promise<void>::async([self = shared_cast<SpeakerManager>()]() { self->engine_.unload(); });
 }
 
 }  // namespace margelo::nitro::onnx::speech

package/cpp/SpeakerManager.hpp

@@ -10,6 +10,7 @@
 #include <HybridSpeakerManagerSpec.hpp>
 
 #include <memory>
+#include <string>
 
 namespace margelo::nitro::onnx::speech {
 
@@ -17,7 +18,7 @@ class SpeakerManager : public HybridSpeakerManagerSpec {
  public:
   static constexpr auto TAG = "SpeakerManager";
 
-  SpeakerManager(std::shared_ptr<ThreadPool> threadPool, std::string cacheDir);
+  SpeakerManager();
   ~SpeakerManager() override;
 
   std::shared_ptr<Promise<void>> load(const SpeakerEmbeddingConfig& config) override;

package/cpp/SpeakerRecord.cpp

@@ -0,0 +1,125 @@
+// ------------------------------------------------------------------------------
+// SpeakerRecord.cpp
+// ------------------------------------------------------------------------------
+#include "SpeakerRecord.hpp"
+
+#include <cctype>
+#include <cstring>
+#include <fstream>
+#include <limits>
+#include <stdexcept>
+
+namespace margelo::nitro::onnx::speech {
+
+namespace {
+
+constexpr char kSpeakerMagic[4] = {'S', 'P', 'K', '2'};
+constexpr uint32_t kFlagHasReferenceAudio = 1u;
+
+}  // namespace
+
+bool tryParseSpeakerIndex(const std::string& speakerId, int32_t& outIndex) {
+  if (speakerId.empty() || speakerId.size() > 10) {
+    return false;
+  }
+  for (char ch : speakerId) {
+    if (!std::isdigit(static_cast<unsigned char>(ch))) {
+      return false;
+    }
+  }
+  try {
+    const long value = std::stol(speakerId);
+    if (value < 0 || value > std::numeric_limits<int32_t>::max()) {
+      return false;
+    }
+    outIndex = static_cast<int32_t>(value);
+    return true;
+  } catch (...) {
+    return false;
+  }
+}
+
+void writeSpeakerRecord(
+    const std::string& path,
+    const std::string& name,
+    const std::vector<float>& embedding,
+    const std::vector<float>* referenceAudio,
+    int32_t referenceSampleRate) {
+  std::ofstream file(path, std::ios::binary);
+  if (!file) {
+    throw std::runtime_error("Failed to write speaker embedding: " + path);
+  }
+  file.write(kSpeakerMagic, sizeof(kSpeakerMagic));
+  const auto nameLen = static_cast<uint32_t>(name.size());
+  file.write(reinterpret_cast<const char*>(&nameLen), sizeof(nameLen));
+  file.write(name.data(), name.size());
+  const auto dim = static_cast<uint32_t>(embedding.size());
+  file.write(reinterpret_cast<const char*>(&dim), sizeof(dim));
+  if (!embedding.empty()) {
+    file.write(reinterpret_cast<const char*>(embedding.data()), embedding.size() * sizeof(float));
+  }
+  const uint32_t flags =
+      (referenceAudio != nullptr && !referenceAudio->empty()) ? kFlagHasReferenceAudio : 0u;
+  file.write(reinterpret_cast<const char*>(&flags), sizeof(flags));
+  if (flags & kFlagHasReferenceAudio) {
+    const auto sampleRate = static_cast<uint32_t>(referenceSampleRate > 0 ? referenceSampleRate : 16000);
+    const auto count = static_cast<uint32_t>(referenceAudio->size());
+    file.write(reinterpret_cast<const char*>(&sampleRate), sizeof(sampleRate));
+    file.write(reinterpret_cast<const char*>(&count), sizeof(count));
+    file.write(reinterpret_cast<const char*>(referenceAudio->data()), count * sizeof(float));
+  }
+  if (!file) {
+    throw std::runtime_error("Failed to write speaker embedding: " + path);
+  }
+}
+
+SpeakerEngineRegisteredSpeaker readSpeakerRecord(const std::string& id, const std::string& path) {
+  std::ifstream file(path, std::ios::binary);
+  if (!file) {
+    throw std::runtime_error("Speaker not found: " + id);
+  }
+  char magic[4] = {0};
+  file.read(magic, sizeof(magic));
+  if (std::memcmp(magic, kSpeakerMagic, sizeof(kSpeakerMagic)) != 0) {
+    throw std::runtime_error("Unsupported speaker record format for id: " + id);
+  }
+
+  SpeakerEngineRegisteredSpeaker result;
+  result.id = id;
+  result.embeddingPath = path;
+
+  uint32_t nameLen = 0;
+  file.read(reinterpret_cast<char*>(&nameLen), sizeof(nameLen));
+  if (nameLen > 0 && nameLen < 1024) {
+    result.name.resize(nameLen);
+    file.read(result.name.data(), nameLen);
+  }
+
+  uint32_t dim = 0;
+  file.read(reinterpret_cast<char*>(&dim), sizeof(dim));
+  if (dim > 0 && dim < 100000) {
+    result.embedding.resize(dim);
+    file.read(reinterpret_cast<char*>(result.embedding.data()), dim * sizeof(float));
+  }
+
+  uint32_t flags = 0;
+  file.read(reinterpret_cast<char*>(&flags), sizeof(flags));
+  if (flags & kFlagHasReferenceAudio) {
+    uint32_t sampleRate = 0;
+    uint32_t count = 0;
+    file.read(reinterpret_cast<char*>(&sampleRate), sizeof(sampleRate));
+    file.read(reinterpret_cast<char*>(&count), sizeof(count));
+    if (count > 0 && count < 16000u * 60u * 10u) {
+      result.referenceSampleRate = static_cast<int32_t>(sampleRate);
+      result.referenceAudio.resize(count);
+      file.read(reinterpret_cast<char*>(result.referenceAudio.data()), count * sizeof(float));
+    }
+  }
+
+  if (!file) {
+    throw std::runtime_error("Corrupt speaker record for id: " + id);
+  }
+  return result;
+}
+
+}  // namespace margelo::nitro::onnx::speech

package/cpp/SpeakerRecord.hpp

@@ -0,0 +1,42 @@
+// ------------------------------------------------------------------------------
+// SpeakerRecord.hpp
+// On-disk speaker record I/O (embedding + optional reference audio).
+// Pure file-format helpers with no model / sherpa-onnx dependency.
+// ------------------------------------------------------------------------------
+#pragma once
+
+#include <cstdint>
+#include <string>
+#include <vector>
+
+namespace margelo::nitro::onnx::speech {
+
+/** On-disk speaker record (embedding + optional reference audio). */
+struct SpeakerEngineRegisteredSpeaker {
+  std::string id;
+  std::string name;
+  std::string embeddingPath;
+  std::vector<float> embedding;
+  std::vector<float> referenceAudio;
+  int32_t referenceSampleRate = 0;
+};
+
+/** True when speakerId is a non-negative integer (model speaker index). */
+bool tryParseSpeakerIndex(const std::string& speakerId, int32_t& outIndex);
+
+/**
+ * Persist a speaker record. Format v2:
+ *   magic "SPK2" | nameLen | name | dim | embedding[dim] | flags |
+ *   [refSampleRate | refCount | refSamples[refCount]]
+ */
+void writeSpeakerRecord(
+    const std::string& path,
+    const std::string& name,
+    const std::vector<float>& embedding,
+    const std::vector<float>* referenceAudio,
+    int32_t referenceSampleRate);
+
+/** Load a speaker record. Throws if the file is missing or corrupt. */
+SpeakerEngineRegisteredSpeaker readSpeakerRecord(const std::string& id, const std::string& path);
+
+}  // namespace margelo::nitro::onnx::speech

package/cpp/StreamingAsr.cpp

@@ -28,15 +28,14 @@ AsrResult toAsrResult(const AsrEngineResult& native) {
 
 }  // namespace
 
-StreamingAsr::StreamingAsr(std::shared_ptr<ThreadPool> threadPool)
-    : HybridObject(TAG), engine_(std::move(threadPool)) {}
+StreamingAsr::StreamingAsr() : HybridObject(TAG) {}
 
 StreamingAsr::~StreamingAsr() {
   engine_.unload();
 }
 
 std::shared_ptr<Promise<void>> StreamingAsr::load(const AsrModelConfig& config) {
-  return Promise<void>::async([this, config]() {
+  return Promise<void>::async([self = shared_cast<StreamingAsr>(), config]() {
     AsrEngineConfig native;
     native.type = config.type;
     native.modelDir = config.modelDir;
@@ -48,14 +47,16 @@ std::shared_ptr<Promise<void>> StreamingAsr::load(const AsrModelConfig& config)
     native.decodingMethod = config.decodingMethod.value_or("greedy_search");
     native.maxActivePaths = static_cast<int32_t>(config.maxActivePaths.value_or(4));
     native.debug = config.debug.value_or(false);
-#ifdef __ANDROID__
+#if defined(__ANDROID__) && defined(SHERPA_ONNX_ENABLE_QNN)
     native.provider = config.provider.value_or("qnn");
+#elif defined(__ANDROID__)
+    native.provider = config.provider.value_or("nnapi");
 #elif defined(__APPLE__)
     native.provider = config.provider.value_or("coreml");
 #else
     native.provider = config.provider.value_or("cpu");
 #endif
-    engine_.load(native, shared_cast<StreamingAsr>());
+    self->engine_.load(native, self);
   });
 }
 
@@ -65,22 +66,24 @@ bool StreamingAsr::isLoaded() {
 
 std::shared_ptr<Promise<void>> StreamingAsr::acceptWaveform(
     const std::shared_ptr<ArrayBuffer>& samples) {
-  return Promise<void>::async([this, samples]() {
+  return Promise<void>::async([self = shared_cast<StreamingAsr>(), samples]() {
     auto floatSamples = bytesToFloatVector(samples->data(), samples->size());
-    engine_.acceptWaveform(floatSamples);
+    self->engine_.acceptWaveform(floatSamples);
   });
 }
 
 std::shared_ptr<Promise<AsrResult>> StreamingAsr::finalize() {
-  return Promise<AsrResult>::async([this]() { return toAsrResult(engine_.finalize()); });
+  return Promise<AsrResult>::async([self = shared_cast<StreamingAsr>()]() {
+    return toAsrResult(self->engine_.finalize());
+  });
 }
 
 std::shared_ptr<Promise<void>> StreamingAsr::reset() {
-  return Promise<void>::async([this]() { engine_.reset(); });
+  return Promise<void>::async([self = shared_cast<StreamingAsr>()]() { self->engine_.reset(); });
 }
 
 std::shared_ptr<Promise<void>> StreamingAsr::unload() {
-  return Promise<void>::async([this]() { engine_.unload(); });
+  return Promise<void>::async([self = shared_cast<StreamingAsr>()]() { self->engine_.unload(); });
 }
 
 std::optional<std::function<void(const AsrResult& /* result */)>> StreamingAsr::getOnPartialResult() {

package/cpp/StreamingAsr.hpp

@@ -20,7 +20,7 @@ class StreamingAsr : public HybridStreamingAsrSpec,
  public:
   static constexpr auto TAG = "StreamingAsr";
 
-  explicit StreamingAsr(std::shared_ptr<ThreadPool> threadPool);
+  StreamingAsr();
   ~StreamingAsr() override;
 
   std::shared_ptr<Promise<void>> load(const AsrModelConfig& config) override;

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;
@@ -63,7 +66,7 @@ std::shared_ptr<Promise<void>> Tts::load(const TtsModelConfig& config) {
 #else
     native.provider = config.provider.value_or("cpu");
 #endif
-    engine_.load(native);
+    self->engine_.load(native);
   });
 }
 
@@ -72,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));
   });
 }
 
@@ -82,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.");
   });
 }
 
@@ -132,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;