react-native-sherpa-onnx 0.3.2 → 0.3.4

package/ios/model_detect/sherpa-onnx-model-detect-tts.mm

@@ -2,13 +2,42 @@
  * sherpa-onnx-model-detect-tts.mm
  *
  * Purpose: Detects TTS (text-to-speech) model type and fills TtsModelPaths from a model directory.
- * Supports Vits, Piper, Kokoro, Zipvoice, Pocket, etc. Used by the TTS wrapper on iOS.
+ * Used by the TTS wrapper on iOS. Supports Vits, Matcha, Kokoro, Kitten, Pocket, Zipvoice.
+ *
+ * --- Detection pipeline (overview) ---
+ *
+ * 1. Gather files in modelDir (recursive), then map file names to logical paths (ttsModel,
+ *    acousticModel, vocoder, encoder, decoder, lmFlow, lmMain, textConditioner, tokens, lexicon,
+ *    dataDir, voices, vocabJson, tokenScoresJson). Path hints from directory name (isLikelyVits,
+ *    isLikelyKitten, isLikelyKokoro).
+ *
+ * 2. Capabilities (hasVits, hasMatcha, hasPocket, hasZipvoice, hasVoicesFile, hasDataDir): which
+ *    model types are *possible* given the paths. Multiple can be true (e.g. voices.bin can satisfy
+ *    both Kokoro and Kitten).
+ *
+ * 3. detectedModels (for UI "Select model type"): built from capabilities only. Every kind with
+ *    the corresponding has* == true is added (with existing rules: zipvoice only if !hasMatcha,
+ *    vits when hasVits and no voices or ambiguous folder name).
+ *
+ * 4. selectedKind: from ResolveTtsKind(). If modelType is explicit, use it if capabilities allow.
+ *    If modelType == "auto": Priority 1 = folder name (GetKindsFromDirNameTts: tokens like "vits",
+ *    "matcha", "kokoro" in dir name --> candidate kinds). Priority 2 = among those candidates, pick
+ *    the first that CapabilitySupportsTtsKind(). Fallback = file-only order (matcha --> pocket -->
+ *    zipvoice --> kokoro/kitten --> vits).
+ *
+ * 5. paths: all gathered paths are written into result.paths; the selected kind determines which
+ *    engine is used at runtime.
+ *
+ * Result to caller: ok, error, detectedModels (list), selectedKind (single), paths.
  */
 
 #include "sherpa-onnx-model-detect.h"
 #include "sherpa-onnx-model-detect-helper.h"
+#include "sherpa-onnx-validate-tts.h"
 
+#include <algorithm>
 #include <string>
+#include <vector>
 
 namespace sherpaonnx {
 namespace {
@@ -25,6 +54,61 @@ TtsModelKind ParseTtsModelType(const std::string& modelType) {
     return TtsModelKind::kUnknown;
 }
 
+/** Returns true if the given kind is supported by the current paths and hints (required files present).
+ *  data_dir (espeak-ng-data) is required only for Kitten and Kokoro (sherpa-onnx config Validate());
+ *  VITS, Matcha, Zipvoice use it optionally; Pocket does not use it. */
+static bool CapabilitySupportsTtsKind(
+    TtsModelKind kind,
+    bool hasVits,
+    bool hasMatcha,
+    bool hasPocket,
+    bool hasZipvoice,
+    bool hasVoicesFile,
+    bool hasDataDir
+) {
+    switch (kind) {
+        case TtsModelKind::kVits:
+            return hasVits;
+        case TtsModelKind::kMatcha:
+            return hasMatcha;
+        case TtsModelKind::kKokoro:
+        case TtsModelKind::kKitten:
+            return hasVoicesFile && hasDataDir;
+        case TtsModelKind::kPocket:
+            return hasPocket;
+        case TtsModelKind::kZipvoice:
+            return hasZipvoice;
+        default:
+            return false;
+    }
+}
+
+/**
+ * Priority 1: Collect candidate TTS kinds from the model directory name (last path component).
+ * Tokens like "vits", "matcha", "kokoro" are matched case-insensitively. Returns candidates in a
+ * fixed priority order for file-based disambiguation when multiple names match.
+ */
+static std::vector<TtsModelKind> GetKindsFromDirNameTts(const std::string& modelDir) {
+    size_t pos = modelDir.find_last_of("/\\");
+    std::string base = (pos == std::string::npos) ? modelDir : modelDir.substr(pos + 1);
+    std::string lower = ToLower(base);
+
+    std::vector<TtsModelKind> out;
+    auto add = [&out](TtsModelKind k) {
+        if (std::find(out.begin(), out.end(), k) == out.end())
+            out.push_back(k);
+    };
+
+    if (lower.find("matcha") != std::string::npos) add(TtsModelKind::kMatcha);
+    if (lower.find("pocket") != std::string::npos) add(TtsModelKind::kPocket);
+    if (lower.find("zipvoice") != std::string::npos) add(TtsModelKind::kZipvoice);
+    if (lower.find("kokoro") != std::string::npos) add(TtsModelKind::kKokoro);
+    if (lower.find("kitten") != std::string::npos) add(TtsModelKind::kKitten);
+    if (lower.find("vits") != std::string::npos) add(TtsModelKind::kVits);
+
+    return out;
+}
+
 } // namespace
 
 TtsDetectResult DetectTtsModel(const std::string& modelDir, const std::string& modelType) {
@@ -45,10 +129,10 @@ TtsDetectResult DetectTtsModel(const std::string& modelDir, const std::string& m
     const int kMaxSearchDepth = 4;
     const std::vector<FileEntry> files = ListFilesRecursive(modelDir, kMaxSearchDepth);
 
-    std::string tokensFile = FindFileByName(modelDir, "tokens.txt", kMaxSearchDepth);
-    std::string lexiconFile = FindFileByName(modelDir, "lexicon.txt", kMaxSearchDepth);
-    std::string dataDirPath = FindDirectoryByName(modelDir, "espeak-ng-data", kMaxSearchDepth);
-    std::string voicesFile = FindFileByName(modelDir, "voices.bin", kMaxSearchDepth);
+    std::string tokensFile = FindFileByName(files, "tokens.txt");
+    std::vector<LexiconCandidate> lexiconCandidates = FindLexiconCandidates(files, modelDir);
+    std::string dataDirPath = FindDirectoryUnderRoot(files, modelDir, "espeak-ng-data");
+    std::string voicesFile = FindFileByName(files, "voices.bin");
 
     std::string acousticModel = FindOnnxByAnyToken(files, {"acoustic_model", "acoustic-model"}, std::nullopt);
     std::string vocoder = FindOnnxByAnyToken(files, {"vocoder", "vocos"}, std::nullopt);
@@ -57,8 +141,8 @@ TtsDetectResult DetectTtsModel(const std::string& modelDir, const std::string& m
     std::string lmFlow = FindOnnxByAnyToken(files, {"lm_flow", "lm-flow"}, std::nullopt);
     std::string lmMain = FindOnnxByAnyToken(files, {"lm_main", "lm-main"}, std::nullopt);
     std::string textConditioner = FindOnnxByAnyToken(files, {"text_conditioner", "text-conditioner"}, std::nullopt);
-    std::string vocabJsonFile = FindFileByName(modelDir, "vocab.json", kMaxSearchDepth);
-    std::string tokenScoresJsonFile = FindFileByName(modelDir, "token_scores.json", kMaxSearchDepth);
+    std::string vocabJsonFile = FindFileByName(files, "vocab.json");
+    std::string tokenScoresJsonFile = FindFileByName(files, "token_scores.json");
 
     std::vector<std::string> modelExcludes = {"acoustic", "vocoder", "encoder", "decoder", "joiner"};
     std::string ttsModel = FindOnnxByAnyToken(files, {"model"}, std::nullopt);
@@ -67,15 +151,24 @@ TtsDetectResult DetectTtsModel(const std::string& modelDir, const std::string& m
     }
 
     bool hasVits = !ttsModel.empty();
-    bool hasMatcha = !acousticModel.empty() && !vocoder.empty();
-    bool hasVoicesFile = !voicesFile.empty() && FileExists(voicesFile);
+    std::string modelDirLower = ToLower(modelDir);
+    bool isLikelyMatcha = modelDirLower.find("matcha") != std::string::npos;
+    bool hasMatcha = (!acousticModel.empty() && !vocoder.empty())
+        || (isLikelyMatcha && !ttsModel.empty() && !tokensFile.empty());
+    if (hasMatcha && acousticModel.empty())
+        acousticModel = ttsModel;  // single-file Matcha: model.onnx is the acoustic model
+    bool hasVoicesFile = !voicesFile.empty();
+    bool isLikelyZipvoice = modelDirLower.find("zipvoice") != std::string::npos;
     bool hasZipvoice = !encoder.empty() && !decoder.empty() && !vocoder.empty();
+    if (isLikelyZipvoice && !encoder.empty() && !decoder.empty() && vocoder.empty()) {
+        result.ok = false;
+        result.error = "TTS: Zipvoice distill variant (no vocoder) is not supported. Use a full Zipvoice model with vocoder or add vocos_24khz.onnx separately.";
+        return result;
+    }
     bool hasPocket = !lmFlow.empty() && !lmMain.empty() && !encoder.empty() && !decoder.empty() &&
-                     !textConditioner.empty() && !vocabJsonFile.empty() && FileExists(vocabJsonFile) &&
-                     !tokenScoresJsonFile.empty() && FileExists(tokenScoresJsonFile);
-    bool hasDataDir = !dataDirPath.empty() && IsDirectory(dataDirPath);
+                     !textConditioner.empty() && !vocabJsonFile.empty() && !tokenScoresJsonFile.empty();
+    bool hasDataDir = !dataDirPath.empty();
 
-    std::string modelDirLower = ToLower(modelDir);
     bool isLikelyKitten = modelDirLower.find("kitten") != std::string::npos;
     bool isLikelyKokoro = modelDirLower.find("kokoro") != std::string::npos;
 
@@ -120,22 +213,36 @@ TtsDetectResult DetectTtsModel(const std::string& modelDir, const std::string& m
             return result;
         }
     } else {
-        if (hasMatcha) {
-            selected = TtsModelKind::kMatcha;
-        } else if (hasPocket) {
-            selected = TtsModelKind::kPocket;
-        } else if (hasZipvoice) {
-            selected = TtsModelKind::kZipvoice;
-        } else if (hasVoicesFile) {
-            if (isLikelyKitten && !isLikelyKokoro) {
-                selected = TtsModelKind::kKitten;
-            } else if (isLikelyKokoro && !isLikelyKitten) {
-                selected = TtsModelKind::kKokoro;
-            } else {
-                selected = TtsModelKind::kKokoro;
+        // Auto: Priority 1 – folder name candidates; Priority 2 – file-based disambiguation.
+        std::vector<TtsModelKind> nameCandidates = GetKindsFromDirNameTts(modelDir);
+        if (!nameCandidates.empty()) {
+            for (TtsModelKind k : nameCandidates) {
+                if (CapabilitySupportsTtsKind(k, hasVits, hasMatcha, hasPocket, hasZipvoice,
+                                              hasVoicesFile, hasDataDir)) {
+                    selected = k;
+                    break;
+                }
+            }
+        }
+        // Fallback: no name-based candidates or none supported – use file-only order.
+        if (selected == TtsModelKind::kUnknown) {
+            if (hasMatcha) {
+                selected = TtsModelKind::kMatcha;
+            } else if (hasPocket) {
+                selected = TtsModelKind::kPocket;
+            } else if (hasZipvoice) {
+                selected = TtsModelKind::kZipvoice;
+            } else if (hasVoicesFile) {
+                if (isLikelyKitten && !isLikelyKokoro) {
+                    selected = TtsModelKind::kKitten;
+                } else if (isLikelyKokoro && !isLikelyKitten) {
+                    selected = TtsModelKind::kKokoro;
+                } else {
+                    selected = TtsModelKind::kKokoro;
+                }
+            } else if (hasVits) {
+                selected = TtsModelKind::kVits;
             }
-        } else if (hasVits) {
-            selected = TtsModelKind::kVits;
         }
     }
 
@@ -144,39 +251,22 @@ TtsDetectResult DetectTtsModel(const std::string& modelDir, const std::string& m
         return result;
     }
 
-    if (selected == TtsModelKind::kVits && !hasVits) {
-        result.error = "TTS: VITS model requested but model file not found in " + modelDir;
-        return result;
+    std::string lexiconPath;
+    for (const auto& c : lexiconCandidates) {
+        result.lexiconLanguageCandidates.push_back(c.languageId);
     }
-    if (selected == TtsModelKind::kMatcha && !hasMatcha) {
-        result.error = "TTS: Matcha model requested but required files not found in " + modelDir;
-        return result;
+    if (!lexiconCandidates.empty()) {
+        lexiconPath = lexiconCandidates[0].path;
     }
-    if ((selected == TtsModelKind::kKokoro || selected == TtsModelKind::kKitten) && (!hasVits || !hasVoicesFile)) {
-        result.error = "TTS: Kokoro/Kitten model requested but required files not found in " + modelDir;
-        return result;
-    }
-    if (selected == TtsModelKind::kPocket && !hasPocket) {
-        result.error = "TTS: Pocket model requested but required files not found in " + modelDir;
-        return result;
-    }
-    if (selected == TtsModelKind::kZipvoice && !hasZipvoice) {
-        result.error = "TTS: Zipvoice model requested but required files not found in " + modelDir;
-        return result;
-    }
-    if ((selected == TtsModelKind::kVits || selected == TtsModelKind::kMatcha ||
-         selected == TtsModelKind::kKokoro || selected == TtsModelKind::kKitten ||
-         selected == TtsModelKind::kZipvoice) &&
-        !hasDataDir) {
-        result.error = "TTS: espeak-ng-data not found in " + modelDir +
-                       ". Copy espeak-ng-data into the model directory.";
-        return result;
+
+    if (selected == TtsModelKind::kMatcha && !acousticModel.empty() && vocoder.empty()) {
+        vocoder = acousticModel;
     }
 
     result.selectedKind = selected;
     result.paths.ttsModel = ttsModel;
     result.paths.tokens = tokensFile;
-    result.paths.lexicon = (!lexiconFile.empty() && FileExists(lexiconFile)) ? lexiconFile : "";
+    result.paths.lexicon = lexiconPath;
     result.paths.dataDir = dataDirPath;
     result.paths.voices = voicesFile;
     result.paths.acousticModel = acousticModel;
@@ -189,8 +279,10 @@ TtsDetectResult DetectTtsModel(const std::string& modelDir, const std::string& m
     result.paths.vocabJson = vocabJsonFile;
     result.paths.tokenScoresJson = tokenScoresJsonFile;
 
-    if (selected != TtsModelKind::kPocket && (tokensFile.empty() || !FileExists(tokensFile))) {
-        result.error = "TTS: tokens.txt not found in " + modelDir;
+    auto validation = ValidateTtsPaths(selected, result.paths, modelDir);
+    if (!validation.ok) {
+        result.ok = false;
+        result.error = validation.error;
         return result;
     }
 

package/ios/model_detect/sherpa-onnx-model-detect.h

@@ -21,6 +21,7 @@ enum class SttModelKind {
     kFunAsrNano,
     kFireRedAsr,
     kMoonshine,
+    kMoonshineV2,
     kDolphin,
     kCanary,
     kOmnilingual,
@@ -48,6 +49,8 @@ struct SttModelPaths {
     std::string whisperEncoder;
     std::string whisperDecoder;
     std::string tokens;
+    /** BPE vocabulary for hotwords tokenization (sentencepiece export bpe.vocab). Optional. */
+    std::string bpeVocab;
     std::string funasrEncoderAdaptor;
     std::string funasrLLM;
     std::string funasrEmbedding;
@@ -56,6 +59,8 @@ struct SttModelPaths {
     std::string moonshineEncoder;
     std::string moonshineUncachedDecoder;
     std::string moonshineCachedDecoder;
+    /** Moonshine v2: encoder + mergedDecoder (reuse moonshineEncoder for encoder path). */
+    std::string moonshineMergedDecoder;
     std::string dolphinModel;
     std::string omnilingualModel;
     std::string medasrModel;
@@ -66,6 +71,69 @@ struct SttModelPaths {
     std::string canaryDecoder;
 };
 
+/** All candidate paths gathered before model kind selection (used by STT detection steps). */
+struct SttCandidatePaths {
+    std::string encoder;
+    std::string decoder;
+    std::string joiner;
+    std::string paraformerModel;
+    std::string ctcModel;
+    std::string tokens;
+    std::string bpeVocab;
+    std::string funasrEncoderAdaptor;
+    std::string funasrLLM;
+    std::string funasrEmbedding;
+    std::string funasrTokenizerDir;
+    std::string moonshinePreprocessor;
+    std::string moonshineEncoder;
+    std::string moonshineUncachedDecoder;
+    std::string moonshineCachedDecoder;
+    std::string moonshineMergedDecoder;
+    std::string encoderForV2;
+};
+
+/** Path hints derived from model directory name (isLikely* flags). */
+struct SttPathHints {
+    bool isLikelyNemo = false;
+    bool isLikelyTdt = false;
+    bool isLikelyWenetCtc = false;
+    bool isLikelySenseVoice = false;
+    bool isLikelyFunAsrNano = false;
+    bool isLikelyZipformer = false;
+    bool isLikelyMoonshine = false;
+    bool isLikelyDolphin = false;
+    bool isLikelyFireRedAsr = false;
+    bool isLikelyCanary = false;
+    bool isLikelyOmnilingual = false;
+    bool isLikelyMedAsr = false;
+    bool isLikelyTeleSpeech = false;
+    bool isLikelyToneCtc = false;
+    bool isLikelyParaformer = false;
+    /** VAD (silero, ten-vad, etc.): not yet supported; when true, detection returns unsupported. */
+    bool isLikelyVad = false;
+    /** TDNN (keyword/yesno): not yet supported; when true, detection returns unsupported. */
+    bool isLikelyTdnn = false;
+};
+
+/** Which model types are possible given paths and hints (has* flags). */
+struct SttCapabilities {
+    bool hasTransducer = false;
+    bool hasWhisper = false;
+    bool hasMoonshine = false;
+    bool hasMoonshineV2 = false;
+    bool hasParaformer = false;
+    bool hasFunAsrNano = false;
+    bool hasDolphin = false;
+    bool hasFireRedAsr = false;
+    /** True when dir name suggests Fire Red but only a single CTC/paraformer model (no encoder/decoder). Use zipformer_ctc. */
+    bool hasFireRedCtc = false;
+    bool hasCanary = false;
+    bool hasOmnilingual = false;
+    bool hasMedAsr = false;
+    bool hasTeleSpeechCtc = false;
+    bool hasToneCtc = false;
+};
+
 struct TtsModelPaths {
     std::string ttsModel;
     std::string tokens;
@@ -87,6 +155,8 @@ struct TtsModelPaths {
 struct SttDetectResult {
     bool ok = false;
     std::string error;
+    /** True when detection failed because the model is for unsupported hardware (RK35xx, Ascend, CANN, etc.). */
+    bool isHardwareSpecificUnsupported = false;
     std::vector<DetectedModel> detectedModels;
     SttModelKind selectedKind = SttModelKind::kUnknown;
     bool tokensRequired = true;
@@ -99,6 +169,8 @@ struct TtsDetectResult {
     std::vector<DetectedModel> detectedModels;
     TtsModelKind selectedKind = TtsModelKind::kUnknown;
     TtsModelPaths paths;
+    /** Language ids from detected lexicon files (e.g. "default", "us-en", "zh") for multi-lang Kokoro/Kitten. Empty when not applicable. */
+    std::vector<std::string> lexiconLanguageCandidates;
 };
 
 SttDetectResult DetectSttModel(

package/ios/model_detect/sherpa-onnx-validate-stt.h

@@ -0,0 +1,38 @@
+/**
+ * sherpa-onnx-validate-stt.h
+ *
+ * Declares ValidateSttPaths(): after model detection resolves a kind and populates
+ * SttModelPaths, this function checks that every *required* path field for that kind
+ * is non-empty. Returns a validation result with ok/error and the list of missing
+ * fields so the caller can surface a specific error instead of crashing at init time.
+ */
+#ifndef SHERPA_ONNX_VALIDATE_STT_H
+#define SHERPA_ONNX_VALIDATE_STT_H
+
+#include "sherpa-onnx-model-detect.h"
+#include <string>
+#include <vector>
+
+namespace sherpaonnx {
+
+struct SttFieldRequirement {
+    const char* fieldName;
+    std::string SttModelPaths::* field;
+    bool required;
+};
+
+struct SttValidationResult {
+    bool ok = true;
+    std::vector<std::string> missingRequired;
+    std::string error;
+};
+
+SttValidationResult ValidateSttPaths(
+    SttModelKind kind,
+    const SttModelPaths& paths,
+    const std::string& modelDir
+);
+
+} // namespace sherpaonnx
+
+#endif // SHERPA_ONNX_VALIDATE_STT_H

package/ios/model_detect/sherpa-onnx-validate-stt.mm

@@ -0,0 +1,229 @@
+/**
+ * sherpa-onnx-validate-stt.mm
+ *
+ * Validates that all required file paths are set for a given SttModelKind.
+ * Requirements are declared in static tables at the top of this file —
+ * edit them when adding a new model type or changing what is required.
+ */
+#include "sherpa-onnx-validate-stt.h"
+#include <cstddef>
+#include <cstring>
+
+namespace sherpaonnx {
+namespace {
+
+// ============================================================
+// REQUIREMENT TABLES — one entry per SttModelKind (or group).
+// Edit here when adding a new model type or changing requirements.
+// ============================================================
+
+static const SttFieldRequirement kTransducerReqs[] = {
+    {"encoder",  &SttModelPaths::encoder,  true},
+    {"decoder",  &SttModelPaths::decoder,  true},
+    {"joiner",   &SttModelPaths::joiner,   true},
+    {"tokens",   &SttModelPaths::tokens,   true},
+    {"bpeVocab", &SttModelPaths::bpeVocab, false},
+};
+
+// Offline paraformer uses paraformerModel; streaming paraformer uses encoder+decoder.
+// Both are valid — validated via custom logic in ValidateSttPaths, not via this table.
+static const SttFieldRequirement kParaformerReqs[] = {
+    {"paraformerModel", &SttModelPaths::paraformerModel, false},
+    {"encoder",         &SttModelPaths::encoder,         false},
+    {"decoder",         &SttModelPaths::decoder,         false},
+    {"tokens",          &SttModelPaths::tokens,          true},
+};
+
+static const SttFieldRequirement kCtcReqs[] = {
+    {"ctcModel", &SttModelPaths::ctcModel, true},
+    {"tokens",   &SttModelPaths::tokens,   true},
+};
+
+static const SttFieldRequirement kWhisperReqs[] = {
+    {"whisperEncoder", &SttModelPaths::whisperEncoder, true},
+    {"whisperDecoder", &SttModelPaths::whisperDecoder, true},
+    {"tokens",         &SttModelPaths::tokens,         true},
+};
+
+static const SttFieldRequirement kFunAsrNanoReqs[] = {
+    {"funasrEncoderAdaptor", &SttModelPaths::funasrEncoderAdaptor, true},
+    {"funasrLLM",            &SttModelPaths::funasrLLM,            true},
+    {"funasrEmbedding",      &SttModelPaths::funasrEmbedding,      true},
+    {"funasrTokenizer",      &SttModelPaths::funasrTokenizer,      true},
+};
+
+static const SttFieldRequirement kMoonshineReqs[] = {
+    {"moonshinePreprocessor",    &SttModelPaths::moonshinePreprocessor,    true},
+    {"moonshineEncoder",         &SttModelPaths::moonshineEncoder,         true},
+    {"moonshineUncachedDecoder", &SttModelPaths::moonshineUncachedDecoder, true},
+    {"moonshineCachedDecoder",   &SttModelPaths::moonshineCachedDecoder,   true},
+};
+
+static const SttFieldRequirement kMoonshineV2Reqs[] = {
+    {"moonshineEncoder",       &SttModelPaths::moonshineEncoder,       true},
+    {"moonshineMergedDecoder", &SttModelPaths::moonshineMergedDecoder, true},
+};
+
+static const SttFieldRequirement kFireRedReqs[] = {
+    {"fireRedEncoder", &SttModelPaths::fireRedEncoder, true},
+    {"fireRedDecoder", &SttModelPaths::fireRedDecoder, true},
+    {"tokens",         &SttModelPaths::tokens,         true},
+};
+
+static const SttFieldRequirement kCanaryReqs[] = {
+    {"canaryEncoder", &SttModelPaths::canaryEncoder, true},
+    {"canaryDecoder", &SttModelPaths::canaryDecoder, true},
+    {"tokens",        &SttModelPaths::tokens,        true},
+};
+
+static const SttFieldRequirement kDolphinReqs[] = {
+    {"dolphinModel", &SttModelPaths::dolphinModel, true},
+    {"tokens",       &SttModelPaths::tokens,       true},
+};
+
+static const SttFieldRequirement kOmnilingualReqs[] = {
+    {"omnilingualModel", &SttModelPaths::omnilingualModel, true},
+    {"tokens",           &SttModelPaths::tokens,           true},
+};
+
+static const SttFieldRequirement kMedAsrReqs[] = {
+    {"medasrModel", &SttModelPaths::medasrModel, true},
+    {"tokens",      &SttModelPaths::tokens,      true},
+};
+
+static const SttFieldRequirement kTeleSpeechReqs[] = {
+    {"telespeechCtcModel", &SttModelPaths::telespeechCtcModel, true},
+    {"tokens",             &SttModelPaths::tokens,             true},
+};
+
+// ============================================================
+
+static const SttFieldRequirement* GetRequirements(SttModelKind kind, size_t& count) {
+    switch (kind) {
+        case SttModelKind::kTransducer:
+        case SttModelKind::kNemoTransducer:
+            count = std::size(kTransducerReqs);
+            return kTransducerReqs;
+        case SttModelKind::kParaformer:
+            count = std::size(kParaformerReqs);
+            return kParaformerReqs;
+        case SttModelKind::kNemoCtc:
+        case SttModelKind::kWenetCtc:
+        case SttModelKind::kSenseVoice:
+        case SttModelKind::kZipformerCtc:
+        case SttModelKind::kToneCtc:
+            count = std::size(kCtcReqs);
+            return kCtcReqs;
+        case SttModelKind::kWhisper:
+            count = std::size(kWhisperReqs);
+            return kWhisperReqs;
+        case SttModelKind::kFunAsrNano:
+            count = std::size(kFunAsrNanoReqs);
+            return kFunAsrNanoReqs;
+        case SttModelKind::kMoonshine:
+            count = std::size(kMoonshineReqs);
+            return kMoonshineReqs;
+        case SttModelKind::kMoonshineV2:
+            count = std::size(kMoonshineV2Reqs);
+            return kMoonshineV2Reqs;
+        case SttModelKind::kFireRedAsr:
+            count = std::size(kFireRedReqs);
+            return kFireRedReqs;
+        case SttModelKind::kCanary:
+            count = std::size(kCanaryReqs);
+            return kCanaryReqs;
+        case SttModelKind::kDolphin:
+            count = std::size(kDolphinReqs);
+            return kDolphinReqs;
+        case SttModelKind::kOmnilingual:
+            count = std::size(kOmnilingualReqs);
+            return kOmnilingualReqs;
+        case SttModelKind::kMedAsr:
+            count = std::size(kMedAsrReqs);
+            return kMedAsrReqs;
+        case SttModelKind::kTeleSpeechCtc:
+            count = std::size(kTeleSpeechReqs);
+            return kTeleSpeechReqs;
+        default:
+            count = 0;
+            return nullptr;
+    }
+}
+
+static const char* SttKindToName(SttModelKind k) {
+    switch (k) {
+        case SttModelKind::kTransducer:    return "Transducer";
+        case SttModelKind::kNemoTransducer: return "NeMo Transducer";
+        case SttModelKind::kParaformer:    return "Paraformer";
+        case SttModelKind::kNemoCtc:       return "NeMo CTC";
+        case SttModelKind::kWenetCtc:      return "WeNet CTC";
+        case SttModelKind::kSenseVoice:    return "SenseVoice";
+        case SttModelKind::kZipformerCtc:  return "Zipformer CTC";
+        case SttModelKind::kWhisper:       return "Whisper";
+        case SttModelKind::kFunAsrNano:    return "FunASR Nano";
+        case SttModelKind::kFireRedAsr:    return "Fire Red ASR";
+        case SttModelKind::kMoonshine:     return "Moonshine";
+        case SttModelKind::kMoonshineV2:   return "Moonshine v2";
+        case SttModelKind::kDolphin:       return "Dolphin";
+        case SttModelKind::kCanary:        return "Canary";
+        case SttModelKind::kOmnilingual:   return "Omnilingual";
+        case SttModelKind::kMedAsr:        return "MedASR";
+        case SttModelKind::kTeleSpeechCtc: return "TeleSpeech CTC";
+        case SttModelKind::kToneCtc:       return "Tone CTC";
+        default:                           return "Unknown";
+    }
+}
+
+static const char* GetFieldHint(const char* fieldName) {
+    if (std::strcmp(fieldName, "tokens") == 0)
+        return "Ensure tokens.txt is present in the model directory.";
+    return nullptr;
+}
+
+} // namespace
+
+SttValidationResult ValidateSttPaths(
+    SttModelKind kind,
+    const SttModelPaths& paths,
+    const std::string& modelDir
+) {
+    SttValidationResult result;
+    size_t count = 0;
+    const auto* reqs = GetRequirements(kind, count);
+    if (!reqs) return result;
+
+    for (size_t i = 0; i < count; ++i) {
+        if (reqs[i].required && (paths.*(reqs[i].field)).empty()) {
+            result.missingRequired.push_back(reqs[i].fieldName);
+        }
+    }
+
+    // Paraformer: offline uses paraformerModel, streaming uses encoder+decoder.
+    // At least one variant must be present.
+    if (kind == SttModelKind::kParaformer) {
+        bool hasOffline = !paths.paraformerModel.empty();
+        bool hasStreaming = !paths.encoder.empty() && !paths.decoder.empty();
+        if (!hasOffline && !hasStreaming) {
+            result.missingRequired.push_back("paraformerModel (or encoder+decoder for streaming)");
+        }
+    }
+
+    if (!result.missingRequired.empty()) {
+        result.ok = false;
+        result.error = std::string("STT ") + SttKindToName(kind)
+                     + ": missing required files in " + modelDir + ": ";
+        for (size_t i = 0; i < result.missingRequired.size(); ++i) {
+            if (i > 0) result.error += ", ";
+            result.error += result.missingRequired[i];
+            const char* hint = GetFieldHint(result.missingRequired[i].c_str());
+            if (hint) {
+                result.error += " (";
+                result.error += hint;
+                result.error += ")";
+            }
+        }
+    }
+    return result;
+}
+
+} // namespace sherpaonnx