react-native-sherpa-onnx 0.3.2 → 0.3.4

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

@@ -2,19 +2,79 @@
  * sherpa-onnx-model-detect-stt.mm
  *
  * Purpose: Detects STT (speech-to-text) model type and fills SttModelPaths from a model directory.
- * Supports transducer, paraformer, whisper, and other STT variants. Used by the STT wrapper on iOS.
+ * Used by the STT wrapper on iOS. Supports transducer, paraformer, whisper, moonshine, etc.
+ *
+ * --- Detection pipeline (overview) ---
+ *
+ * 1. Gather files in modelDir (recursive), then:
+ *    - SttCandidatePaths: map file names to logical paths (encoder, decoder, joiner, moonshine
+ *      preprocessor/encoder/mergedDecoder, paraformer/ctc model, tokens, etc.).
+ *    - SttPathHints: from directory name only (isLikelyMoonshine, isLikelyNemo, ...).
+ *    - SttCapabilities: which model types are *possible* given paths + hints (hasWhisper,
+ *      hasMoonshineV2, hasTransducer, ...). Multiple can be true at once (e.g. same files
+ *      can satisfy both Whisper and Moonshine v2).
+ *
+ * 2. detectedModels (for UI "Select model type"): built from capabilities only. Every kind
+ *    with has* == true is added. So the list shows all types that could work with the files,
+ *    not the single chosen type.
+ *
+ * 3. selectedKind (which type we actually use): from ResolveSttKind():
+ *    - If modelType is explicit (e.g. "whisper"): use it if capabilities allow.
+ *    - If modelType == "auto": Priority 1 = folder name (GetKindsFromDirName: tokens like
+ *      "moonshine", "whisper" in dir name --> candidate kinds). Priority 2 = among those
+ *      candidates, pick the first that CapabilitySupportsKind(). Fallback = if no name
+ *      candidates, use file-only order (transducer --> moonshine v2/v1 --> CTC --> paraformer -->
+ *      whisper --> ...).
+ *
+ * 4. paths: ApplyPathsForSttKind(selectedKind) copies the relevant candidate paths into
+ *    SttModelPaths (encoder/decoder, moonshine encoder/mergedDecoder, etc.) for the chosen kind.
+ *
+ * Result to caller: ok, error, detectedModels (list), selectedKind (single), paths (for selectedKind).
  */
 
+#import <Foundation/Foundation.h>
 #include "sherpa-onnx-model-detect.h"
 #include "sherpa-onnx-model-detect-helper.h"
+#include "sherpa-onnx-validate-stt.h"
 
+#include <algorithm>
 #include <string>
 
+#define LOGI(fmt, ...) NSLog(@"[SttModelDetect] " fmt, ##__VA_ARGS__)
+
 namespace sherpaonnx {
 namespace {
 
 using namespace model_detect;
 
+static const char* KindToName(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 "sense_voice";
+        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* EmptyOrPath(const std::string& s) {
+    return s.empty() ? "(empty)" : s.c_str();
+}
+
 SttModelKind ParseSttModelType(const std::string& modelType) {
     if (modelType == "transducer" || modelType == "zipformer") return SttModelKind::kTransducer;
     if (modelType == "nemo_transducer") return SttModelKind::kNemoTransducer;
@@ -27,6 +87,7 @@ SttModelKind ParseSttModelType(const std::string& modelType) {
     if (modelType == "funasr_nano") return SttModelKind::kFunAsrNano;
     if (modelType == "fire_red_asr") return SttModelKind::kFireRedAsr;
     if (modelType == "moonshine") return SttModelKind::kMoonshine;
+    if (modelType == "moonshine_v2") return SttModelKind::kMoonshineV2;
     if (modelType == "dolphin") return SttModelKind::kDolphin;
     if (modelType == "canary") return SttModelKind::kCanary;
     if (modelType == "omnilingual") return SttModelKind::kOmnilingual;
@@ -36,324 +97,625 @@ SttModelKind ParseSttModelType(const std::string& modelType) {
     return SttModelKind::kUnknown;
 }
 
-} // namespace
-
-SttDetectResult DetectSttModel(
-    const std::string& modelDir,
-    const std::optional<bool>& preferInt8,
-    const std::optional<std::string>& modelType,
-    bool debug /* = false */
+/** Returns true if \p cap and hints/paths support the given \p kind (required files present). */
+static bool CapabilitySupportsKind(
+    SttModelKind kind,
+    const SttCapabilities& cap,
+    const SttPathHints& hints,
+    const SttCandidatePaths& paths
 ) {
-    using namespace model_detect;
+    switch (kind) {
+        case SttModelKind::kTransducer:
+            return cap.hasTransducer && !(hints.isLikelyNemo || hints.isLikelyTdt);
+        case SttModelKind::kNemoTransducer:
+            return cap.hasTransducer;
+        case SttModelKind::kParaformer:
+            return cap.hasParaformer;
+        case SttModelKind::kNemoCtc:
+            return !paths.ctcModel.empty() && hints.isLikelyNemo;
+        case SttModelKind::kWenetCtc:
+            return !paths.ctcModel.empty() && hints.isLikelyWenetCtc;
+        case SttModelKind::kSenseVoice:
+            return !paths.ctcModel.empty() && hints.isLikelySenseVoice;
+        case SttModelKind::kZipformerCtc:
+            return !paths.ctcModel.empty() && hints.isLikelyZipformer;
+        case SttModelKind::kWhisper:
+            return cap.hasWhisper;
+        case SttModelKind::kFunAsrNano:
+            return cap.hasFunAsrNano;
+        case SttModelKind::kFireRedAsr:
+            return cap.hasFireRedAsr;
+        case SttModelKind::kMoonshine:
+            return cap.hasMoonshine;
+        case SttModelKind::kMoonshineV2:
+            return cap.hasMoonshineV2;
+        case SttModelKind::kDolphin:
+            return cap.hasDolphin;
+        case SttModelKind::kCanary:
+            return cap.hasCanary;
+        case SttModelKind::kOmnilingual:
+            return cap.hasOmnilingual;
+        case SttModelKind::kMedAsr:
+            return cap.hasMedAsr;
+        case SttModelKind::kTeleSpeechCtc:
+            return cap.hasTeleSpeechCtc;
+        case SttModelKind::kToneCtc:
+            return cap.hasToneCtc;
+        default:
+            return false;
+    }
+}
 
-    SttDetectResult result;
+/**
+ * Priority 1: Collect candidate STT kinds from the model directory name (last path component).
+ * Tokens like "moonshine", "whisper", "paraformer" are matched case-insensitively. Returns
+ * candidates in a fixed priority order so that when multiple kinds match the name, file-based
+ * disambiguation picks the first supported one.
+ */
+static std::vector<SttModelKind> GetKindsFromDirName(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<SttModelKind> out;
+    auto add = [&out](SttModelKind k) {
+        if (std::find(out.begin(), out.end(), k) == out.end())
+            out.push_back(k);
+    };
 
-    if (modelDir.empty()) {
-        result.error = "Model directory is empty";
-        return result;
+    if (lower.find("moonshine") != std::string::npos) {
+        add(SttModelKind::kMoonshineV2);
+        add(SttModelKind::kMoonshine);
     }
-
-    if (!FileExists(modelDir) || !IsDirectory(modelDir)) {
-        result.error = "Model directory does not exist or is not a directory: " + modelDir;
-        return result;
+    if (lower.find("whisper") != std::string::npos)
+        add(SttModelKind::kWhisper);
+    if (lower.find("paraformer") != std::string::npos)
+        add(SttModelKind::kParaformer);
+    if (lower.find("nemo") != std::string::npos || lower.find("parakeet") != std::string::npos) {
+        add(SttModelKind::kNemoTransducer);
+        add(SttModelKind::kNemoCtc);
+    }
+    if (lower.find("tdt") != std::string::npos)
+        add(SttModelKind::kNemoTransducer);
+    if (lower.find("wenet") != std::string::npos)
+        add(SttModelKind::kWenetCtc);
+    if (lower.find("sense") != std::string::npos || lower.find("sensevoice") != std::string::npos)
+        add(SttModelKind::kSenseVoice);
+    if (lower.find("zipformer") != std::string::npos) {
+        add(SttModelKind::kTransducer);
+        add(SttModelKind::kZipformerCtc);
+    }
+    if (lower.find("funasr") != std::string::npos)
+        add(SttModelKind::kFunAsrNano);
+    if (lower.find("canary") != std::string::npos)
+        add(SttModelKind::kCanary);
+    if (lower.find("fire_red") != std::string::npos || lower.find("fire-red") != std::string::npos)
+        add(SttModelKind::kFireRedAsr);
+    if (lower.find("dolphin") != std::string::npos)
+        add(SttModelKind::kDolphin);
+    if (lower.find("omnilingual") != std::string::npos)
+        add(SttModelKind::kOmnilingual);
+    if (lower.find("medasr") != std::string::npos)
+        add(SttModelKind::kMedAsr);
+    if (lower.find("telespeech") != std::string::npos)
+        add(SttModelKind::kTeleSpeechCtc);
+    if (lower.find("t-one") != std::string::npos || lower.find("t_one") != std::string::npos ||
+        ContainsWord(lower, "tone"))
+        add(SttModelKind::kToneCtc);
+    if (lower.find("transducer") != std::string::npos) {
+        add(SttModelKind::kTransducer);
+        add(SttModelKind::kNemoTransducer);
     }
 
-    const int kMaxSearchDepth = 4;
-    const std::vector<FileEntry> files = ListFilesRecursive(modelDir, kMaxSearchDepth);
-
-    std::string encoderPath = FindOnnxByAnyToken(files, {"encoder"}, preferInt8);
-    std::string decoderPath = FindOnnxByAnyToken(files, {"decoder"}, preferInt8);
-    std::string joinerPath = FindOnnxByAnyToken(files, {"joiner"}, preferInt8);
-    std::string tokensPath = FindFileEndingWith(files, "tokens.txt");
+    return out;
+}
 
-    std::vector<std::string> modelExcludes = {
+static SttCandidatePaths GatherSttCandidatePaths(
+    const std::vector<FileEntry>& files,
+    const std::string& modelDir,
+    int maxDepth,
+    const std::optional<bool>& preferInt8
+) {
+    SttCandidatePaths p;
+    p.encoder = FindOnnxByAnyToken(files, {"encoder"}, preferInt8);
+    p.decoder = FindOnnxByAnyToken(files, {"decoder"}, preferInt8);
+    p.joiner = FindOnnxByAnyToken(files, {"joiner"}, preferInt8);
+    p.funasrEncoderAdaptor = FindOnnxByAnyToken(files, {"encoder_adaptor", "encoder-adaptor"}, preferInt8);
+    p.funasrLLM = FindOnnxByAnyToken(files, {"llm"}, preferInt8);
+    p.funasrEmbedding = FindOnnxByAnyToken(files, {"embedding"}, preferInt8);
+    {
+        std::string vocabInSubdir;
+        const std::string vocabName = "vocab.json";
+        for (const auto& entry : files) {
+            if (entry.nameLower != vocabName) continue;
+            const std::string& path = entry.path;
+            if (path.size() >= modelDir.size() && path.compare(0, modelDir.size(), modelDir) == 0 &&
+                (modelDir.empty() || path[modelDir.size()] == '/')) {
+                if (path.size() == modelDir.size() + 12 && path.compare(modelDir.size(), 12, "/vocab.json") == 0) {
+                    p.funasrTokenizerDir = modelDir;
+                    break;
+                }
+                if (vocabInSubdir.empty())
+                    vocabInSubdir = path;
+            }
+        }
+        if (p.funasrTokenizerDir.empty() && !vocabInSubdir.empty()) {
+            size_t lastSlash = vocabInSubdir.find_last_of("/\\");
+            if (lastSlash != std::string::npos)
+                p.funasrTokenizerDir = vocabInSubdir.substr(0, lastSlash);
+        }
+    }
+    p.moonshinePreprocessor = FindOnnxByAnyToken(files, {"preprocess", "preprocessor"}, preferInt8);
+    p.moonshineEncoder = FindOnnxByAnyToken(files, {"encode", "encoder_model"}, preferInt8);
+    p.moonshineUncachedDecoder = FindOnnxByAnyToken(files, {"uncached_decode", "uncached"}, preferInt8);
+    p.moonshineCachedDecoder = FindOnnxByAnyTokenExcluding(
+        files, std::vector<std::string>{"cached_decode", "cached"}, std::vector<std::string>{"uncached"}, preferInt8);
+    p.moonshineMergedDecoder = FindOnnxByAnyToken(files, {"merged_decode", "merged_decoder", "decoder_model_merged", "merged"}, preferInt8);
+    static const std::vector<std::string> modelExcludes = {
         "encoder", "decoder", "joiner", "vocoder", "acoustic", "embedding", "llm",
-        "encoder_adaptor", "encoder-adaptor"
+        "encoder_adaptor", "encoder-adaptor", "encoder_model", "decoder_model",
+        "merged_decoder", "decoder_model_merged", "preprocess", "encode", "uncached", "cached"
     };
-    std::string paraformerModelPath = FindOnnxByAnyToken(files, {"model"}, preferInt8);
-    if (paraformerModelPath.empty()) {
-        paraformerModelPath = FindLargestOnnxExcludingTokens(files, modelExcludes);
+    p.paraformerModel = FindOnnxByAnyToken(files, {"model"}, preferInt8);
+    if (!p.paraformerModel.empty()) {
+        std::string lower = ToLower(p.paraformerModel);
+        if (lower.find("encoder_model") != std::string::npos ||
+            lower.find("decoder_model") != std::string::npos ||
+            lower.find("merged_decoder") != std::string::npos)
+            p.paraformerModel.clear();
     }
-    std::string ctcModelPath = FindOnnxByAnyToken(files, {"model"}, preferInt8);
-    if (ctcModelPath.empty()) {
-        ctcModelPath = FindLargestOnnxExcludingTokens(files, modelExcludes);
+    if (p.paraformerModel.empty())
+        p.paraformerModel = FindLargestOnnxExcludingTokens(files, modelExcludes);
+    p.ctcModel = FindOnnxByAnyToken(files, {"model"}, preferInt8);
+    if (!p.ctcModel.empty()) {
+        std::string lower = ToLower(p.ctcModel);
+        if (lower.find("encoder_model") != std::string::npos ||
+            lower.find("decoder_model") != std::string::npos ||
+            lower.find("merged_decoder") != std::string::npos)
+            p.ctcModel.clear();
     }
+    if (p.ctcModel.empty())
+        p.ctcModel = FindLargestOnnxExcludingTokens(files, modelExcludes);
+    if (!p.paraformerModel.empty() &&
+        (p.paraformerModel == p.encoder || p.paraformerModel == p.decoder || p.paraformerModel == p.joiner))
+        p.paraformerModel.clear();
+    if (!p.ctcModel.empty() &&
+        (p.ctcModel == p.encoder || p.ctcModel == p.decoder || p.ctcModel == p.joiner))
+        p.ctcModel.clear();
+    p.tokens = FindFileEndingWith(files, "tokens.txt");
+    p.bpeVocab = FindFileByName(files, "bpe.vocab");
+    p.encoderForV2 = p.encoder.empty() ? FindOnnxByAnyToken(files, {"encoder", "encoder_model"}, preferInt8) : p.encoder;
+
+    return p;
+}
 
-    std::string funasrEncoderAdaptor = FindOnnxByAnyToken(files, {"encoder_adaptor", "encoder-adaptor"}, preferInt8);
-    std::string funasrLLM = FindOnnxByAnyToken(files, {"llm"}, preferInt8);
-    std::string funasrEmbedding = FindOnnxByAnyToken(files, {"embedding"}, preferInt8);
-    std::string funasrTokenizerDir = ResolveTokenizerDir(modelDir);
-
-    std::string moonshinePreprocess = FindOnnxByAnyToken(files, {"preprocess", "preprocessor"}, preferInt8);
-    std::string moonshineEncode = FindOnnxByAnyToken(files, {"encode"}, preferInt8);
-    std::string moonshineUncachedDecode = FindOnnxByAnyToken(files, {"uncached_decode", "uncached"}, preferInt8);
-    std::string moonshineCachedDecode = FindOnnxByAnyToken(files, {"cached_decode", "cached"}, preferInt8);
-
-    bool hasTransducer = !encoderPath.empty() && !decoderPath.empty() && !joinerPath.empty();
-
-    bool hasWhisperEncoder = !encoderPath.empty();
-    bool hasWhisperDecoder = !decoderPath.empty();
-    bool hasWhisper = hasWhisperEncoder && hasWhisperDecoder && joinerPath.empty();
-
-    bool hasFunAsrEncoderAdaptor = !funasrEncoderAdaptor.empty();
-    bool hasFunAsrLLM = !funasrLLM.empty();
-    bool hasFunAsrEmbedding = !funasrEmbedding.empty();
-    bool hasFunAsrTokenizer = !funasrTokenizerDir.empty() && FileExists(funasrTokenizerDir + "/vocab.json");
-    bool hasFunAsrNano = hasFunAsrEncoderAdaptor && hasFunAsrLLM && hasFunAsrEmbedding && hasFunAsrTokenizer;
-
-    std::string modelDirLower = ToLower(modelDir);
-    bool isLikelyNemo = modelDirLower.find("nemo") != std::string::npos ||
-                        modelDirLower.find("parakeet") != std::string::npos;
-    bool isLikelyTdt = modelDirLower.find("tdt") != std::string::npos;
-    bool isLikelyWenetCtc = modelDirLower.find("wenet") != std::string::npos;
-    bool isLikelySenseVoice = modelDirLower.find("sense") != std::string::npos ||
-                              modelDirLower.find("sensevoice") != std::string::npos;
-    bool isLikelyFunAsrNano = modelDirLower.find("funasr") != std::string::npos ||
-                              modelDirLower.find("funasr-nano") != std::string::npos;
-    bool isLikelyZipformer = modelDirLower.find("zipformer") != std::string::npos;
-    bool isLikelyMoonshine = modelDirLower.find("moonshine") != std::string::npos;
-    bool isLikelyDolphin = modelDirLower.find("dolphin") != std::string::npos;
-    bool isLikelyFireRedAsr = modelDirLower.find("fire_red") != std::string::npos ||
-                              modelDirLower.find("fire-red") != std::string::npos;
-    bool isLikelyCanary = modelDirLower.find("canary") != std::string::npos;
-    bool isLikelyOmnilingual = modelDirLower.find("omnilingual") != std::string::npos;
-    bool isLikelyMedAsr = modelDirLower.find("medasr") != std::string::npos;
-    bool isLikelyTeleSpeech = modelDirLower.find("telespeech") != std::string::npos;
-    // Tone CTC: match "tone" only as standalone word (not e.g. "cantonese"); also accept "t-one" / "t_one"
-    bool isLikelyToneCtc = modelDirLower.find("t-one") != std::string::npos ||
-                           modelDirLower.find("t_one") != std::string::npos ||
-                           ContainsWord(modelDirLower, "tone");
-
-    bool hasMoonshine = !moonshinePreprocess.empty() && !moonshineUncachedDecode.empty() &&
-                        !moonshineCachedDecode.empty() && !moonshineEncode.empty();
-    bool hasDolphin = isLikelyDolphin && !ctcModelPath.empty();
-    bool hasFireRedAsr = hasTransducer && isLikelyFireRedAsr;
-    bool hasCanary = hasWhisperEncoder && hasWhisperDecoder && joinerPath.empty() && isLikelyCanary;
-    bool hasOmnilingual = !ctcModelPath.empty() && isLikelyOmnilingual;
-    bool hasMedAsr = !ctcModelPath.empty() && isLikelyMedAsr;
-    bool hasTeleSpeechCtc = (!ctcModelPath.empty() || !paraformerModelPath.empty()) && isLikelyTeleSpeech;
-    bool hasToneCtc = !ctcModelPath.empty() && isLikelyToneCtc;
-
-    if (hasTransducer) {
-        if (isLikelyNemo || isLikelyTdt) {
-            result.detectedModels.push_back({"nemo_transducer", modelDir});
-        } else {
-            result.detectedModels.push_back({isLikelyZipformer ? "zipformer" : "transducer", modelDir});
-        }
-    }
+static SttPathHints GetSttPathHints(const std::string& modelDir) {
+    SttPathHints h;
+    std::string lower = ToLower(modelDir);
+    h.isLikelyNemo = lower.find("nemo") != std::string::npos || lower.find("parakeet") != std::string::npos;
+    h.isLikelyTdt = lower.find("tdt") != std::string::npos;
+    h.isLikelyWenetCtc = lower.find("wenet") != std::string::npos;
+    h.isLikelySenseVoice = lower.find("sense") != std::string::npos || lower.find("sensevoice") != std::string::npos;
+    h.isLikelyFunAsrNano = lower.find("funasr") != std::string::npos || lower.find("funasr-nano") != std::string::npos;
+    h.isLikelyZipformer = lower.find("zipformer") != std::string::npos;
+    h.isLikelyMoonshine = lower.find("moonshine") != std::string::npos;
+    h.isLikelyDolphin = lower.find("dolphin") != std::string::npos;
+    h.isLikelyFireRedAsr = lower.find("fire_red") != std::string::npos || lower.find("fire-red") != std::string::npos;
+    h.isLikelyCanary = lower.find("canary") != std::string::npos;
+    h.isLikelyOmnilingual = lower.find("omnilingual") != std::string::npos;
+    h.isLikelyMedAsr = lower.find("medasr") != std::string::npos;
+    h.isLikelyTeleSpeech = lower.find("telespeech") != std::string::npos;
+    // tone_ctc is for T-One models only (e.g. streaming-t-one-russian). WeNetSpeech CTC (yue, wu, etc.) uses wenet_ctc per sherpa-onnx docs.
+    h.isLikelyToneCtc = lower.find("t-one") != std::string::npos || lower.find("t_one") != std::string::npos ||
+                        ContainsWord(lower, "tone");
+    h.isLikelyParaformer = lower.find("paraformer") != std::string::npos;
+    h.isLikelyVad = lower.find("vad") != std::string::npos || lower.find("silero") != std::string::npos ||
+                    lower.find("ten-vad") != std::string::npos;
+    h.isLikelyTdnn = lower.find("tdnn") != std::string::npos;
+    return h;
+}
 
-    if (!ctcModelPath.empty() && (isLikelyNemo || isLikelyWenetCtc || isLikelySenseVoice)) {
-        if (isLikelyNemo) {
-            result.detectedModels.push_back({"nemo_ctc", modelDir});
-        } else if (isLikelyWenetCtc) {
-            result.detectedModels.push_back({"wenet_ctc", modelDir});
-        } else if (isLikelySenseVoice) {
-            result.detectedModels.push_back({"sense_voice", modelDir});
-        } else {
-            result.detectedModels.push_back({"ctc", modelDir});
-        }
-    } else if (!paraformerModelPath.empty()) {
-        result.detectedModels.push_back({"paraformer", modelDir});
-    }
+/** Error message when model is for unsupported hardware (RK35xx, Ascend, etc.). */
+static const char* kHardwareSpecificUnsupportedMessage =
+    "This model is built for hardware-specific acceleration (e.g. RK35xx, Ascend, CANN) and is not supported by the React Native SDK. Use an ONNX model for CPU/GPU or a QNN-capable model on supported devices.";
 
-    if (hasWhisper) {
-        result.detectedModels.push_back({"whisper", modelDir});
+/** True if model dir name indicates a hardware-specific build (e.g. RK3588, Ascend). Not runnable on generic host. QNN is supported by the SDK. */
+static bool IsHardwareSpecificModelDir(const std::string& modelDir) {
+    std::string lower = ToLower(modelDir);
+    const char* tokens[] = {
+        "rk3588", "rk3576", "rk3568", "rk3566", "rk3562", "rknn",
+        "ascend", "cann", "910b", "910b2", "310p3"
+    };
+    for (const char* t : tokens) {
+        if (lower.find(t) != std::string::npos)
+            return true;
     }
+    return false;
+}
 
-    if (hasFunAsrNano) {
-        result.detectedModels.push_back({"funasr_nano", modelDir});
-    }
-    if (hasMoonshine) {
-        result.detectedModels.push_back({"moonshine", modelDir});
-    }
-    if (hasDolphin) {
-        result.detectedModels.push_back({"dolphin", modelDir});
-    }
-    if (hasFireRedAsr) {
-        result.detectedModels.push_back({"fire_red_asr", modelDir});
-    }
-    if (hasCanary) {
-        result.detectedModels.push_back({"canary", modelDir});
-    }
-    if (hasOmnilingual) {
-        result.detectedModels.push_back({"omnilingual", modelDir});
+static SttCapabilities ComputeSttCapabilities(const SttCandidatePaths& paths, const SttPathHints& hints) {
+    SttCapabilities c;
+    c.hasTransducer = !paths.encoder.empty() && !paths.decoder.empty() && !paths.joiner.empty();
+    bool hasWhisperEnc = !paths.encoder.empty();
+    bool hasWhisperDec = !paths.decoder.empty();
+    c.hasWhisper = hasWhisperEnc && hasWhisperDec && paths.joiner.empty();
+    bool hasFunAsrTok = !paths.funasrTokenizerDir.empty();
+    c.hasFunAsrNano = !paths.funasrEncoderAdaptor.empty() && !paths.funasrLLM.empty() &&
+                      !paths.funasrEmbedding.empty() && hasFunAsrTok;
+    c.hasMoonshine = !paths.moonshinePreprocessor.empty() && !paths.moonshineUncachedDecoder.empty() &&
+                     !paths.moonshineCachedDecoder.empty() && !paths.moonshineEncoder.empty();
+    c.hasMoonshineV2 = !paths.moonshineMergedDecoder.empty() && !paths.encoderForV2.empty() && paths.joiner.empty();
+    c.hasParaformer = !paths.paraformerModel.empty();
+    c.hasDolphin = hints.isLikelyDolphin && !paths.ctcModel.empty();
+    // Fire Red ASR: only encoder+decoder (two files). Single-file Fire Red (e.g. fire-red-asr2-ctc) uses CTC path to avoid native crash.
+    c.hasFireRedAsr = (c.hasTransducer || (hasWhisperEnc && hasWhisperDec && paths.joiner.empty())) && hints.isLikelyFireRedAsr;
+    c.hasFireRedCtc = hints.isLikelyFireRedAsr && paths.encoder.empty() && paths.decoder.empty() &&
+        (!paths.ctcModel.empty() || !paths.paraformerModel.empty());
+    c.hasCanary = hasWhisperEnc && hasWhisperDec && paths.joiner.empty() && hints.isLikelyCanary;
+    c.hasOmnilingual = !paths.ctcModel.empty() && hints.isLikelyOmnilingual;
+    c.hasMedAsr = !paths.ctcModel.empty() && hints.isLikelyMedAsr;
+    c.hasTeleSpeechCtc = (!paths.ctcModel.empty() || !paths.paraformerModel.empty()) && hints.isLikelyTeleSpeech;
+    c.hasToneCtc = !paths.ctcModel.empty() && hints.isLikelyToneCtc;
+    return c;
+}
+
+static void CollectDetectedModels(
+    std::vector<DetectedModel>& out,
+    const SttCapabilities& cap,
+    const SttPathHints& hints,
+    const SttCandidatePaths& paths,
+    const std::string& modelDir
+) {
+    if (cap.hasTransducer) {
+        out.push_back({(hints.isLikelyNemo || hints.isLikelyTdt) ? "nemo_transducer" : "transducer", modelDir});
     }
-    if (hasMedAsr) {
-        result.detectedModels.push_back({"medasr", modelDir});
+    if (!paths.ctcModel.empty() && (hints.isLikelyNemo || hints.isLikelyWenetCtc || hints.isLikelySenseVoice || hints.isLikelyZipformer)) {
+        if (hints.isLikelyNemo) out.push_back({"nemo_ctc", modelDir});
+        else if (hints.isLikelyWenetCtc) out.push_back({"wenet_ctc", modelDir});
+        else if (hints.isLikelySenseVoice) out.push_back({"sense_voice", modelDir});
+        else out.push_back({"zipformer_ctc", modelDir});
+    } else if (!paths.paraformerModel.empty()) {
+        out.push_back({"paraformer", modelDir});
     }
-    if (hasTeleSpeechCtc) {
-        result.detectedModels.push_back({"telespeech_ctc", modelDir});
+    if (cap.hasWhisper) out.push_back({"whisper", modelDir});
+    if (cap.hasFunAsrNano) out.push_back({"funasr_nano", modelDir});
+    if (cap.hasMoonshine) out.push_back({"moonshine", modelDir});
+    if (cap.hasMoonshineV2) out.push_back({"moonshine_v2", modelDir});
+    if (cap.hasDolphin) out.push_back({"dolphin", modelDir});
+    if (cap.hasFireRedAsr) out.push_back({"fire_red_asr", modelDir});
+    if (cap.hasCanary) out.push_back({"canary", modelDir});
+    if (cap.hasOmnilingual) out.push_back({"omnilingual", modelDir});
+    if (cap.hasMedAsr) out.push_back({"medasr", modelDir});
+    if (cap.hasTeleSpeechCtc) out.push_back({"telespeech_ctc", modelDir});
+    if (cap.hasToneCtc) out.push_back({"tone_ctc", modelDir});
+}
+
+static SttModelKind ResolveSttKind(
+    const std::optional<std::string>& modelType,
+    const SttCapabilities& cap,
+    const SttPathHints& hints,
+    const SttCandidatePaths& paths,
+    const std::string& modelDir,
+    std::string& outError
+) {
+    outError.clear();
+    if (hints.isLikelyVad) {
+        outError = "VAD models are not yet supported by the React Native SDK.";
+        return SttModelKind::kUnknown;
     }
-    if (hasToneCtc) {
-        result.detectedModels.push_back({"tone_ctc", modelDir});
+    if (hints.isLikelyTdnn) {
+        outError = "TDNN (keyword/yesno) models are not yet supported by the React Native SDK.";
+        return SttModelKind::kUnknown;
     }
-
-    SttModelKind selected = SttModelKind::kUnknown;
-
     if (modelType.has_value() && modelType.value() != "auto") {
-        selected = ParseSttModelType(modelType.value());
+        SttModelKind selected = ParseSttModelType(modelType.value());
         if (selected == SttModelKind::kUnknown) {
-            result.error = "Unknown model type: " + modelType.value();
-            return result;
+            outError = "Unknown model type: " + modelType.value();
+            return SttModelKind::kUnknown;
         }
-
-        if (selected == SttModelKind::kTransducer && !hasTransducer) {
-            result.error = "Transducer model requested but files not found in " + modelDir;
-            return result;
+        if (selected == SttModelKind::kTransducer && !cap.hasTransducer) {
+            outError = "Transducer model requested but files not found in " + modelDir;
+            return SttModelKind::kUnknown;
         }
-        if (selected == SttModelKind::kNemoTransducer && !hasTransducer) {
-            result.error = "NeMo Transducer model requested but encoder/decoder/joiner not found in " + modelDir;
-            return result;
+        if (selected == SttModelKind::kNemoTransducer && !cap.hasTransducer) {
+            outError = "NeMo Transducer model requested but encoder/decoder/joiner not found in " + modelDir;
+            return SttModelKind::kUnknown;
         }
-        if (selected == SttModelKind::kParaformer && paraformerModelPath.empty()) {
-            result.error = "Paraformer model requested but model.onnx not found in " + modelDir;
-            return result;
+        if (selected == SttModelKind::kParaformer && paths.paraformerModel.empty()) {
+            outError = "Paraformer model requested but model file not found in " + modelDir;
+            return SttModelKind::kUnknown;
         }
         if ((selected == SttModelKind::kNemoCtc || selected == SttModelKind::kWenetCtc ||
              selected == SttModelKind::kSenseVoice || selected == SttModelKind::kZipformerCtc ||
-             selected == SttModelKind::kToneCtc) &&
-            ctcModelPath.empty()) {
-            result.error = "CTC model requested but model.onnx not found in " + modelDir;
-            return result;
+             selected == SttModelKind::kToneCtc) && paths.ctcModel.empty()) {
+            outError = "CTC model requested but model file not found in " + modelDir;
+            return SttModelKind::kUnknown;
         }
-        if (selected == SttModelKind::kWhisper && !hasWhisper) {
-            result.error = "Whisper model requested but encoder/decoder not found in " + modelDir;
-            return result;
+        if (selected == SttModelKind::kWhisper && !cap.hasWhisper) {
+            outError = "Whisper model requested but encoder/decoder not found in " + modelDir;
+            return SttModelKind::kUnknown;
         }
-        if (selected == SttModelKind::kFunAsrNano && !hasFunAsrNano) {
-            result.error = "FunASR Nano model requested but required files not found in " + modelDir;
-            return result;
+        if (selected == SttModelKind::kFunAsrNano && !cap.hasFunAsrNano) {
+            outError = "FunASR Nano model requested but required files not found in " + modelDir;
+            return SttModelKind::kUnknown;
         }
-        if (selected == SttModelKind::kMoonshine && !hasMoonshine) {
-            result.error = "Moonshine model requested but preprocess/encode/uncached_decode/cached_decode not found in " + modelDir;
-            return result;
+        if (selected == SttModelKind::kMoonshine && !cap.hasMoonshine) {
+            outError = "Moonshine v1 model requested but preprocess/encode/uncached_decode/cached_decode not found in " + modelDir;
+            return SttModelKind::kUnknown;
         }
-        if (selected == SttModelKind::kDolphin && !hasDolphin) {
-            result.error = "Dolphin model requested but model not found in " + modelDir;
-            return result;
+        if (selected == SttModelKind::kMoonshineV2 && !cap.hasMoonshineV2) {
+            outError = "Moonshine v2 model requested but encoder/merged_decode not found in " + modelDir;
+            return SttModelKind::kUnknown;
         }
-        if (selected == SttModelKind::kFireRedAsr && !hasFireRedAsr) {
-            result.error = "FireRed ASR model requested but encoder/decoder not found in " + modelDir;
-            return result;
+        if (selected == SttModelKind::kDolphin && !cap.hasDolphin) {
+            outError = "Dolphin model requested but model not found in " + modelDir;
+            return SttModelKind::kUnknown;
         }
-        if (selected == SttModelKind::kCanary && !hasCanary) {
-            result.error = "Canary model requested but encoder/decoder not found in " + modelDir;
-            return result;
+        if (selected == SttModelKind::kFireRedAsr && !cap.hasFireRedAsr) {
+            outError = "FireRed ASR model requested but encoder/decoder not found in " + modelDir;
+            return SttModelKind::kUnknown;
         }
-        if (selected == SttModelKind::kOmnilingual && !hasOmnilingual) {
-            result.error = "Omnilingual model requested but model not found in " + modelDir;
-            return result;
+        if (selected == SttModelKind::kCanary && !cap.hasCanary) {
+            outError = "Canary model requested but encoder/decoder not found in " + modelDir;
+            return SttModelKind::kUnknown;
         }
-        if (selected == SttModelKind::kMedAsr && !hasMedAsr) {
-            result.error = "MedASR model requested but model not found in " + modelDir;
-            return result;
+        if (selected == SttModelKind::kOmnilingual && !cap.hasOmnilingual) {
+            outError = "Omnilingual model requested but model not found in " + modelDir;
+            return SttModelKind::kUnknown;
         }
-        if (selected == SttModelKind::kTeleSpeechCtc && !hasTeleSpeechCtc) {
-            result.error = "TeleSpeech CTC model requested but model not found in " + modelDir;
-            return result;
+        if (selected == SttModelKind::kMedAsr && !cap.hasMedAsr) {
+            outError = "MedASR model requested but model not found in " + modelDir;
+            return SttModelKind::kUnknown;
         }
-        if (selected == SttModelKind::kToneCtc && !hasToneCtc) {
-            result.error = "Tone CTC model requested but path does not contain 'tone' (as a word), 't-one', or 't_one' (e.g. sherpa-onnx-streaming-t-one-*) in " + modelDir;
-            return result;
+        if (selected == SttModelKind::kTeleSpeechCtc && !cap.hasTeleSpeechCtc) {
+            outError = "TeleSpeech CTC model requested but model not found in " + modelDir;
+            return SttModelKind::kUnknown;
         }
-    } else {
-        if (hasTransducer) {
-            selected = (isLikelyNemo || isLikelyTdt) ? SttModelKind::kNemoTransducer : SttModelKind::kTransducer;
-        } else if (!ctcModelPath.empty() && (isLikelyNemo || isLikelyWenetCtc || isLikelySenseVoice)) {
-            if (isLikelyNemo) {
-                selected = SttModelKind::kNemoCtc;
-            } else if (isLikelyWenetCtc) {
-                selected = SttModelKind::kWenetCtc;
-            } else {
-                selected = SttModelKind::kSenseVoice;
-            }
-        } else if (hasFunAsrNano && isLikelyFunAsrNano) {
-            selected = SttModelKind::kFunAsrNano;
-        } else if (!paraformerModelPath.empty()) {
-            selected = SttModelKind::kParaformer;
-        } else if (hasCanary) {
-            selected = SttModelKind::kCanary;
-        } else if (hasFireRedAsr) {
-            selected = SttModelKind::kFireRedAsr;
-        } else if (hasWhisper) {
-            selected = SttModelKind::kWhisper;
-        } else if (hasFunAsrNano) {
-            selected = SttModelKind::kFunAsrNano;
-        } else if (hasMoonshine && isLikelyMoonshine) {
-            selected = SttModelKind::kMoonshine;
-        } else if (hasDolphin) {
-            selected = SttModelKind::kDolphin;
-        } else if (hasFireRedAsr) {
-            selected = SttModelKind::kFireRedAsr;
-        } else if (hasCanary) {
-            selected = SttModelKind::kCanary;
-        } else if (hasOmnilingual) {
-            selected = SttModelKind::kOmnilingual;
-        } else if (hasMedAsr) {
-            selected = SttModelKind::kMedAsr;
-        } else if (hasTeleSpeechCtc) {
-            selected = SttModelKind::kTeleSpeechCtc;
-        } else if (hasToneCtc) {
-            selected = SttModelKind::kToneCtc;
-        } else if (!ctcModelPath.empty()) {
-            selected = SttModelKind::kZipformerCtc;
+        if (selected == SttModelKind::kToneCtc && !cap.hasToneCtc) {
+            outError = "Tone CTC model requested but path does not contain 'tone' (as a word), 't-one', or 't_one' (e.g. sherpa-onnx-streaming-t-one-*) in " + modelDir;
+            return SttModelKind::kUnknown;
         }
+        return selected;
     }
 
-    if (selected == SttModelKind::kUnknown) {
-        result.error = "No compatible model type detected in " + modelDir;
+    // Auto: Priority 1 – resolve from folder name candidates; Priority 2 – file-based disambiguation.
+    std::vector<SttModelKind> nameCandidates = GetKindsFromDirName(modelDir);
+    if (!nameCandidates.empty()) {
+        for (SttModelKind k : nameCandidates) {
+            if (CapabilitySupportsKind(k, cap, hints, paths))
+                return k;
+        }
+        // Name hinted at a model type but no candidate had required files; fall through to file-only.
+    }
+
+    // Fallback: no name-based candidates, or none supported – use file-only detection order.
+    if (cap.hasTransducer) {
+        return (hints.isLikelyNemo || hints.isLikelyTdt) ? SttModelKind::kNemoTransducer : SttModelKind::kTransducer;
+    }
+    if (hints.isLikelyMoonshine && cap.hasMoonshineV2) return SttModelKind::kMoonshineV2;
+    if (hints.isLikelyMoonshine && cap.hasMoonshine) return SttModelKind::kMoonshine;
+    if (!paths.ctcModel.empty() && (hints.isLikelyToneCtc || hints.isLikelyNemo || hints.isLikelyWenetCtc || hints.isLikelySenseVoice)) {
+        if (hints.isLikelyToneCtc) return SttModelKind::kToneCtc;
+        if (hints.isLikelyNemo) return SttModelKind::kNemoCtc;
+        if (hints.isLikelyWenetCtc) return SttModelKind::kWenetCtc;
+        return SttModelKind::kSenseVoice;
+    }
+    if (cap.hasFunAsrNano && hints.isLikelyFunAsrNano) return SttModelKind::kFunAsrNano;
+    if (cap.hasFireRedCtc) return SttModelKind::kZipformerCtc;
+    if (!paths.paraformerModel.empty()) return SttModelKind::kParaformer;
+    if (cap.hasCanary) return SttModelKind::kCanary;
+    if (cap.hasFireRedAsr) return SttModelKind::kFireRedAsr;
+    if (cap.hasWhisper) return SttModelKind::kWhisper;
+    if (cap.hasFunAsrNano) return SttModelKind::kFunAsrNano;
+    if (cap.hasMoonshineV2) return SttModelKind::kMoonshineV2;
+    if (cap.hasDolphin) return SttModelKind::kDolphin;
+    if (cap.hasOmnilingual) return SttModelKind::kOmnilingual;
+    if (cap.hasMedAsr) return SttModelKind::kMedAsr;
+    if (cap.hasTeleSpeechCtc) return SttModelKind::kTeleSpeechCtc;
+    if (cap.hasToneCtc) return SttModelKind::kToneCtc;
+    if (!paths.ctcModel.empty()) return SttModelKind::kZipformerCtc;
+    return SttModelKind::kUnknown;
+}
+
+static void ApplyPathsForSttKind(SttModelKind kind, const SttCandidatePaths& candidate, SttModelPaths& resultPaths) {
+    switch (kind) {
+        case SttModelKind::kTransducer:
+        case SttModelKind::kNemoTransducer:
+            resultPaths.encoder = candidate.encoder;
+            resultPaths.decoder = candidate.decoder;
+            resultPaths.joiner = candidate.joiner;
+            break;
+        case SttModelKind::kParaformer:
+            resultPaths.paraformerModel = candidate.paraformerModel;
+            break;
+        case SttModelKind::kNemoCtc:
+        case SttModelKind::kWenetCtc:
+        case SttModelKind::kSenseVoice:
+        case SttModelKind::kZipformerCtc:
+        case SttModelKind::kToneCtc:
+            resultPaths.ctcModel = candidate.ctcModel;
+            break;
+        case SttModelKind::kWhisper:
+            resultPaths.whisperEncoder = candidate.encoder;
+            resultPaths.whisperDecoder = candidate.decoder;
+            break;
+        case SttModelKind::kFireRedAsr: {
+            std::string singleModel = candidate.paraformerModel.empty() ? candidate.ctcModel : candidate.paraformerModel;
+            resultPaths.fireRedEncoder = candidate.encoder.empty() ? singleModel : candidate.encoder;
+            resultPaths.fireRedDecoder = candidate.decoder.empty() ? singleModel : candidate.decoder;
+            break;
+        }
+        case SttModelKind::kFunAsrNano:
+            resultPaths.funasrEncoderAdaptor = candidate.funasrEncoderAdaptor;
+            resultPaths.funasrLLM = candidate.funasrLLM;
+            resultPaths.funasrEmbedding = candidate.funasrEmbedding;
+            resultPaths.funasrTokenizer = candidate.funasrTokenizerDir;
+            break;
+        case SttModelKind::kMoonshine:
+            resultPaths.moonshinePreprocessor = candidate.moonshinePreprocessor;
+            resultPaths.moonshineEncoder = candidate.moonshineEncoder;
+            resultPaths.moonshineUncachedDecoder = candidate.moonshineUncachedDecoder;
+            resultPaths.moonshineCachedDecoder = candidate.moonshineCachedDecoder;
+            break;
+        case SttModelKind::kMoonshineV2:
+            resultPaths.moonshineEncoder = candidate.encoderForV2;
+            resultPaths.moonshineMergedDecoder = candidate.moonshineMergedDecoder;
+            break;
+        case SttModelKind::kDolphin:
+            resultPaths.dolphinModel = candidate.ctcModel.empty() ? candidate.paraformerModel : candidate.ctcModel;
+            break;
+        case SttModelKind::kCanary:
+            resultPaths.canaryEncoder = candidate.encoder;
+            resultPaths.canaryDecoder = candidate.decoder;
+            break;
+        case SttModelKind::kOmnilingual:
+            resultPaths.omnilingualModel = candidate.ctcModel;
+            break;
+        case SttModelKind::kMedAsr:
+            resultPaths.medasrModel = candidate.ctcModel;
+            break;
+        case SttModelKind::kTeleSpeechCtc:
+            resultPaths.telespeechCtcModel = candidate.ctcModel.empty() ? candidate.paraformerModel : candidate.ctcModel;
+            break;
+        default:
+            break;
+    }
+}
+
+} // namespace
+
+SttDetectResult DetectSttModel(
+    const std::string& modelDir,
+    const std::optional<bool>& preferInt8,
+    const std::optional<std::string>& modelType,
+    bool debug /* = false */
+) {
+    using namespace model_detect;
+
+    SttDetectResult result;
+
+    if (modelDir.empty()) {
+        result.error = "Model directory is empty";
         return result;
     }
 
-    result.selectedKind = selected;
-    result.tokensRequired = (selected != SttModelKind::kFunAsrNano);
-
-    if (selected == SttModelKind::kTransducer || selected == SttModelKind::kNemoTransducer) {
-        result.paths.encoder = encoderPath;
-        result.paths.decoder = decoderPath;
-        result.paths.joiner = joinerPath;
-    } else if (selected == SttModelKind::kParaformer) {
-        result.paths.paraformerModel = paraformerModelPath;
-    } else if (selected == SttModelKind::kNemoCtc || selected == SttModelKind::kWenetCtc ||
-               selected == SttModelKind::kSenseVoice || selected == SttModelKind::kZipformerCtc ||
-               selected == SttModelKind::kToneCtc) {
-        result.paths.ctcModel = ctcModelPath;
-    } else if (selected == SttModelKind::kWhisper) {
-        result.paths.whisperEncoder = encoderPath;
-        result.paths.whisperDecoder = decoderPath;
-    } else if (selected == SttModelKind::kFunAsrNano) {
-        result.paths.funasrEncoderAdaptor = funasrEncoderAdaptor;
-        result.paths.funasrLLM = funasrLLM;
-        result.paths.funasrEmbedding = funasrEmbedding;
-        result.paths.funasrTokenizer = funasrTokenizerDir;
-    } else if (selected == SttModelKind::kMoonshine) {
-        result.paths.moonshinePreprocessor = moonshinePreprocess;
-        result.paths.moonshineEncoder = moonshineEncode;
-        result.paths.moonshineUncachedDecoder = moonshineUncachedDecode;
-        result.paths.moonshineCachedDecoder = moonshineCachedDecode;
-    } else if (selected == SttModelKind::kDolphin) {
-        result.paths.dolphinModel = ctcModelPath.empty() ? paraformerModelPath : ctcModelPath;
-    } else if (selected == SttModelKind::kFireRedAsr) {
-        result.paths.fireRedEncoder = encoderPath;
-        result.paths.fireRedDecoder = decoderPath;
-    } else if (selected == SttModelKind::kCanary) {
-        result.paths.canaryEncoder = encoderPath;
-        result.paths.canaryDecoder = decoderPath;
-    } else if (selected == SttModelKind::kOmnilingual) {
-        result.paths.omnilingualModel = ctcModelPath;
-    } else if (selected == SttModelKind::kMedAsr) {
-        result.paths.medasrModel = ctcModelPath;
-    } else if (selected == SttModelKind::kTeleSpeechCtc) {
-        result.paths.telespeechCtcModel = ctcModelPath.empty() ? paraformerModelPath : ctcModelPath;
+    if (!FileExists(modelDir) || !IsDirectory(modelDir)) {
+        result.error = "Model directory does not exist or is not a directory: " + modelDir;
+        return result;
     }
 
-    if (!tokensPath.empty() && FileExists(tokensPath)) {
-        result.paths.tokens = tokensPath;
+    const int kMaxSearchDepth = 4;
+    const std::vector<FileEntry> files = ListFilesRecursive(modelDir, kMaxSearchDepth);
+
+    SttCandidatePaths candidate = GatherSttCandidatePaths(files, modelDir, kMaxSearchDepth, preferInt8);
+    SttPathHints hints = GetSttPathHints(modelDir);
+    SttCapabilities cap = ComputeSttCapabilities(candidate, hints);
+
+    if (debug) {
+        LOGI("DetectSttModel: tokens=%s", EmptyOrPath(candidate.tokens));
+        LOGI("DetectSttModel: transducer encoder=%s decoder=%s joiner=%s",
+            EmptyOrPath(candidate.encoder), EmptyOrPath(candidate.decoder), EmptyOrPath(candidate.joiner));
+        LOGI("DetectSttModel: paraformerModel=%s ctcModel=%s tokens=%s bpeVocab=%s",
+            EmptyOrPath(candidate.paraformerModel), EmptyOrPath(candidate.ctcModel), EmptyOrPath(candidate.tokens), EmptyOrPath(candidate.bpeVocab));
+        LOGI("DetectSttModel: moonshine preprocessor=%s encoder=%s uncachedDecoder=%s cachedDecoder=%s mergedDecoder=%s",
+            EmptyOrPath(candidate.moonshinePreprocessor), EmptyOrPath(candidate.moonshineEncoder), EmptyOrPath(candidate.moonshineUncachedDecoder),
+            EmptyOrPath(candidate.moonshineCachedDecoder), EmptyOrPath(candidate.moonshineMergedDecoder));
+        LOGI("DetectSttModel: whisper encoder=%s decoder=%s (same as transducer; joiner empty => whisper)",
+            EmptyOrPath(candidate.encoder), EmptyOrPath(candidate.decoder));
+        LOGI("DetectSttModel: funasr encoderAdaptor=%s llm=%s embedding=%s tokenizerDir=%s",
+            EmptyOrPath(candidate.funasrEncoderAdaptor), EmptyOrPath(candidate.funasrLLM), EmptyOrPath(candidate.funasrEmbedding), EmptyOrPath(candidate.funasrTokenizerDir));
+        LOGI("DetectSttModel: hasTransducer=%d hasWhisper=%d hasMoonshine=%d hasMoonshineV2=%d hasParaformer=%d hasFunAsrNano=%d hasDolphin=%d hasFireRedAsr=%d hasFireRedCtc=%d hasCanary=%d hasOmnilingual=%d hasMedAsr=%d hasTeleSpeechCtc=%d hasToneCtc=%d",
+            (int)cap.hasTransducer, (int)cap.hasWhisper, (int)cap.hasMoonshine, (int)cap.hasMoonshineV2,
+            (int)cap.hasParaformer, (int)cap.hasFunAsrNano, (int)cap.hasDolphin, (int)cap.hasFireRedAsr, (int)cap.hasFireRedCtc,
+            (int)cap.hasCanary, (int)cap.hasOmnilingual, (int)cap.hasMedAsr, (int)cap.hasTeleSpeechCtc, (int)cap.hasToneCtc);
+        LOGI("DetectSttModel: hints isLikelyNemo=%d isLikelyTdt=%d isLikelyWenetCtc=%d isLikelySenseVoice=%d isLikelyFunAsrNano=%d isLikelyZipformer=%d isLikelyMoonshine=%d isLikelyDolphin=%d isLikelyFireRedAsr=%d isLikelyCanary=%d isLikelyOmnilingual=%d isLikelyMedAsr=%d isLikelyTeleSpeech=%d isLikelyToneCtc=%d isLikelyParaformer=%d isLikelyVad=%d isLikelyTdnn=%d",
+             (int)hints.isLikelyNemo, (int)hints.isLikelyTdt, (int)hints.isLikelyWenetCtc, (int)hints.isLikelySenseVoice,
+             (int)hints.isLikelyFunAsrNano, (int)hints.isLikelyZipformer, (int)hints.isLikelyMoonshine, (int)hints.isLikelyDolphin,
+             (int)hints.isLikelyFireRedAsr, (int)hints.isLikelyCanary, (int)hints.isLikelyOmnilingual, (int)hints.isLikelyMedAsr,
+             (int)hints.isLikelyTeleSpeech, (int)hints.isLikelyToneCtc, (int)hints.isLikelyParaformer, (int)hints.isLikelyVad, (int)hints.isLikelyTdnn);
+    }
+
+    CollectDetectedModels(result.detectedModels, cap, hints, candidate, modelDir);
+
+    result.selectedKind = ResolveSttKind(modelType, cap, hints, candidate, modelDir, result.error);
+    if (result.selectedKind == SttModelKind::kUnknown) {
+        if (IsHardwareSpecificModelDir(modelDir)) {
+            result.ok = false;
+            result.isHardwareSpecificUnsupported = true;
+            result.error = kHardwareSpecificUnsupportedMessage;
+            return result;
+        }
+        if (!result.error.empty()) {
+            return result;
+        }
+        result.error = "No compatible model type detected in " + modelDir;
+        return result;
+    }
+
+    LOGI("DetectSttModel: selected kind=%d (%s)", static_cast<int>(result.selectedKind), KindToName(result.selectedKind));
+    result.tokensRequired = (result.selectedKind != SttModelKind::kFunAsrNano);
+    ApplyPathsForSttKind(result.selectedKind, candidate, result.paths);
+
+    if (!candidate.tokens.empty() && FileExists(candidate.tokens)) {
+        result.paths.tokens = candidate.tokens;
     } else if (result.tokensRequired) {
         result.error = "Tokens file not found in " + modelDir;
         return result;
     }
+    if (!candidate.bpeVocab.empty() && FileExists(candidate.bpeVocab)) {
+        result.paths.bpeVocab = candidate.bpeVocab;
+    }
+
+    auto validation = ValidateSttPaths(result.selectedKind, result.paths, modelDir);
+    if (!validation.ok) {
+        result.ok = false;
+        result.error = validation.error;
+        return result;
+    }
 
+    switch (result.selectedKind) {
+        case SttModelKind::kTransducer:
+        case SttModelKind::kNemoTransducer:
+            LOGI("DetectSttModel: paths set encoder=%s decoder=%s joiner=%s",
+                 EmptyOrPath(result.paths.encoder), EmptyOrPath(result.paths.decoder), EmptyOrPath(result.paths.joiner));
+            break;
+        case SttModelKind::kParaformer:
+            LOGI("DetectSttModel: paths set paraformerModel=%s", EmptyOrPath(result.paths.paraformerModel));
+            break;
+        case SttModelKind::kWhisper:
+            LOGI("DetectSttModel: paths set whisperEncoder=%s whisperDecoder=%s",
+                 EmptyOrPath(result.paths.whisperEncoder), EmptyOrPath(result.paths.whisperDecoder));
+            break;
+        case SttModelKind::kMoonshine:
+            LOGI("DetectSttModel: paths set moonshine preprocessor=%s encoder=%s uncachedDecoder=%s cachedDecoder=%s",
+                 EmptyOrPath(result.paths.moonshinePreprocessor), EmptyOrPath(result.paths.moonshineEncoder),
+                 EmptyOrPath(result.paths.moonshineUncachedDecoder), EmptyOrPath(result.paths.moonshineCachedDecoder));
+            break;
+        case SttModelKind::kMoonshineV2:
+            LOGI("DetectSttModel: paths set moonshine_v2 encoder=%s mergedDecoder=%s",
+                 EmptyOrPath(result.paths.moonshineEncoder), EmptyOrPath(result.paths.moonshineMergedDecoder));
+            break;
+        case SttModelKind::kNemoCtc:
+        case SttModelKind::kWenetCtc:
+        case SttModelKind::kSenseVoice:
+        case SttModelKind::kZipformerCtc:
+        case SttModelKind::kToneCtc:
+            LOGI("DetectSttModel: paths set ctcModel=%s", EmptyOrPath(result.paths.ctcModel));
+            break;
+        case SttModelKind::kFireRedAsr:
+            LOGI("DetectSttModel: paths set fireRedEncoder=%s fireRedDecoder=%s",
+                 EmptyOrPath(result.paths.fireRedEncoder), EmptyOrPath(result.paths.fireRedDecoder));
+            break;
+        case SttModelKind::kFunAsrNano:
+            LOGI("DetectSttModel: paths set funasr adaptor=%s llm=%s embedding=%s tokenizer=%s",
+                 EmptyOrPath(result.paths.funasrEncoderAdaptor), EmptyOrPath(result.paths.funasrLLM),
+                 EmptyOrPath(result.paths.funasrEmbedding), EmptyOrPath(result.paths.funasrTokenizer));
+            break;
+        default:
+            break;
+    }
+    LOGI("DetectSttModel: tokens=%s (required=%d)", EmptyOrPath(result.paths.tokens), (int)result.tokensRequired);
+    LOGI("DetectSttModel: detection OK for %s", modelDir.c_str());
     result.ok = true;
     return result;
 }