Extend model manager for new TTS models

Author: MuoDoo

README.md

@@ -62,13 +62,17 @@ The `vox` CLI can list, download, verify, repair, and remove known local models:
 ```sh
 ./build/bin/vox model list
 ./build/bin/vox model download qwen3-asr-1.7b
+./build/bin/vox model download kokoro-tts
+./build/bin/vox model download qwen3-tts
 ./build/bin/vox model verify qwen3-asr-1.7b
 ./build/bin/vox model repair qwen3-asr-1.7b
 ```
 
 Model verification checks that expected files exist, are non-empty, and do not
 have leftover partial downloads. Checksums are reported when metadata is
-available; the current bundled manifests rely on file presence and size.
+available; the current bundled manifests rely on file presence and size. Common
+aliases such as `kokoro`, `cosyvoice`, and `qwen3-tts` resolve to their
+canonical model entries.
 
 ### Whisper ASR
 
@@ -142,7 +146,7 @@ CosyVoice3 remains the default TTS engine.
 Download the minimum baked-voice CosyVoice3 GGUF set:
 
 ```sh
-scripts/download-cosyvoice3-tts-gguf.sh
+./build/bin/vox model download cosyvoice3-tts
 ```
 
 That creates:
@@ -159,7 +163,7 @@ Pass the LLM GGUF with `--tts-model`. The runtime auto-discovers sibling flow, H
 Kokoro-82M is available with `--tts-engine kokoro`:
 
 ```sh
-scripts/download-kokoro-tts-gguf.sh
+./build/bin/vox model download kokoro-tts
 ```
 
 On Windows PowerShell:
@@ -180,7 +184,7 @@ Pass the Kokoro model with `--tts-model`. The runtime auto-discovers `kokoro-voi
 Qwen3-TTS 0.6B is available with `--tts-engine qwen3-tts`. The recommended quick-test path is CustomVoice Q8_0 because it has built-in speakers and does not need a reference WAV:
 
 ```sh
-scripts/download-qwen3-tts-gguf.sh
+./build/bin/vox model download qwen3-tts
 ```
 
 On Windows PowerShell:
@@ -196,7 +200,7 @@ models/tts/qwen3-tts-0.6b-customvoice/qwen3-tts-12hz-0.6b-customvoice-q8_0.gguf
 models/tts/qwen3-tts-0.6b-customvoice/qwen3-tts-tokenizer-12hz.gguf
 ```
 
-Pass the talker GGUF with `--tts-model`. The runtime auto-discovers `qwen3-tts-tokenizer-12hz.gguf` in the same directory, or use `--tts-codec-model PATH`. CustomVoice speakers include `aiden`, `dylan`, `eric`, `ono_anna`, `ryan`, `serena`, `sohee`, `uncle_fu`, and `vivian`; use `dylan` or `eric` for Chinese output tests. The Base variant can also be downloaded with `scripts/download-qwen3-tts-gguf.sh models/tts/qwen3-tts-0.6b-base base q8_0`; it requires `--tts-voice-model` pointing to a baked voice GGUF or a reference WAV plus `--tts-ref-text`.
+Pass the talker GGUF with `--tts-model`. The runtime auto-discovers `qwen3-tts-tokenizer-12hz.gguf` in the same directory, or use `--tts-codec-model PATH`. CustomVoice speakers include `aiden`, `dylan`, `eric`, `ono_anna`, `ryan`, `serena`, `sohee`, `uncle_fu`, and `vivian`; use `dylan` or `eric` for Chinese output tests. The Base variant can also be downloaded with `./build/bin/vox model download qwen3-tts-0.6b-base`; it requires `--tts-voice-model` pointing to a baked voice GGUF or a reference WAV plus `--tts-ref-text`.
 
 ## Run
 

apps/model_manager.cpp

@@ -1,5 +1,6 @@
 #include "model_manager.h"
 
+#include <algorithm>
 #include <cstdlib>
 #include <cstdio>
 #include <iostream>
@@ -93,6 +94,13 @@ void print_model_details(const ManagedModel & model, const ManagedModelStatus &
         << "  source: " << model.source << "\n"
         << "  version: " << model.version << "\n"
         << "  checksum: " << (model.checksum.empty() ? "unavailable" : model.checksum) << "\n";
+    if (!model.aliases.empty()) {
+        out << "  aliases:";
+        for (const std::string & alias : model.aliases) {
+            out << " " << alias;
+        }
+        out << "\n";
+    }
     for (size_t i = 0; i < model.files.size(); ++i) {
         const ManagedModelFile & file = model.files[i];
         const ManagedModelFileStatus & file_status = status.files[i];
@@ -122,6 +130,42 @@ int require_model_name(const std::vector<std::string> & args, std::ostream & err
     return 0;
 }
 
+bool name_matches_model(const ManagedModel & model, const std::string & name) {
+    if (model.name == name) {
+        return true;
+    }
+    return std::find(model.aliases.begin(), model.aliases.end(), name) != model.aliases.end();
+}
+
+bool contains_token(const std::string & haystack, const std::string & needle) {
+    return !needle.empty() && haystack.find(needle) != std::string::npos;
+}
+
+void append_unique(std::vector<std::string> & values, const std::string & value) {
+    if (std::find(values.begin(), values.end(), value) == values.end()) {
+        values.push_back(value);
+    }
+}
+
+std::vector<std::string> suggest_models(const std::string & name) {
+    std::vector<std::string> suggestions;
+    for (const ManagedModel & model : supported_models()) {
+        if (contains_token(model.name, name) || contains_token(name, model.name)) {
+            append_unique(suggestions, model.name);
+        }
+        for (const std::string & alias : model.aliases) {
+            if (contains_token(alias, name) || contains_token(name, alias)) {
+                append_unique(suggestions, model.name);
+                break;
+            }
+        }
+        if (suggestions.size() >= 5) {
+            break;
+        }
+    }
+    return suggestions;
+}
+
 } // namespace
 
 const std::vector<ManagedModel> & supported_models() {
@@ -137,6 +181,7 @@ const std::vector<ManagedModel> & supported_models() {
                 {"models/asr/qwen3-asr-1.7b/mmproj-Qwen3-ASR-1.7B-Q8_0.gguf", "about 356 MB"},
             },
             "scripts/download-qwen3-asr-gguf.sh",
+            {"qwen3-asr", "qwen3-asr-default", "default-asr"},
         },
         {
             "qwen3-asr-0.6b",
@@ -149,6 +194,7 @@ const std::vector<ManagedModel> & supported_models() {
                 {"models/asr/qwen3-asr-0.6b/mmproj-Qwen3-ASR-0.6B-Q8_0.gguf", ""},
             },
             "scripts/download-qwen3-asr-gguf.sh 0.6B Q8_0 models/asr/qwen3-asr-0.6b",
+            {"qwen3-asr-small", "small-asr"},
         },
         {
             "whisper-base",
@@ -158,6 +204,7 @@ const std::vector<ManagedModel> & supported_models() {
             "",
             {{"models/ggml-base.bin", ""}},
             "./external/whisper.cpp/models/download-ggml-model.sh base models",
+            {"whisper", "whisper.cpp"},
         },
         {
             "hymt-translate",
@@ -167,6 +214,7 @@ const std::vector<ManagedModel> & supported_models() {
             "",
             {{"models/translate/HY-MT1.5-1.8B-Q4_K_M.gguf", "about 1.13 GB"}},
             "scripts/download-hymt-gguf.sh",
+            {"hymt", "hy-mt", "translate"},
         },
         {
             "cosyvoice3-tts",
@@ -181,14 +229,66 @@ const std::vector<ManagedModel> & supported_models() {
                 {"models/tts/cosyvoice3/cosyvoice3-voices.gguf", ""},
             },
             "scripts/download-cosyvoice3-tts-gguf.sh",
+            {"cosyvoice3", "cosyvoice", "cosy"},
+        },
+        {
+            "kokoro-tts",
+            "Kokoro-82M TTS GGUF model and default af_heart voice pack",
+            "cstr/kokoro-82m-GGUF + cstr/kokoro-voices-GGUF",
+            "82M q8_0 / af_heart",
+            "",
+            {
+                {"models/tts/kokoro/kokoro-82m-q8_0.gguf", "about 135 MiB"},
+                {"models/tts/kokoro/kokoro-voice-af_heart.gguf", "about 510 KiB"},
+            },
+#ifdef _WIN32
+            "powershell -ExecutionPolicy Bypass -File scripts/download-kokoro-tts-gguf.ps1",
+#else
+            "scripts/download-kokoro-tts-gguf.sh",
+#endif
+            {"kokoro", "kokoro-82m"},
+        },
+        {
+            "qwen3-tts-0.6b-customvoice",
+            "Qwen3-TTS 0.6B CustomVoice talker and tokenizer/codec",
+            "cstr/qwen3-tts-0.6b-customvoice-GGUF + cstr/qwen3-tts-tokenizer-12hz-GGUF",
+            "0.6B CustomVoice q8_0",
+            "",
+            {
+                {"models/tts/qwen3-tts-0.6b-customvoice/qwen3-tts-12hz-0.6b-customvoice-q8_0.gguf", "about 923 MiB"},
+                {"models/tts/qwen3-tts-0.6b-customvoice/qwen3-tts-tokenizer-12hz.gguf", "about 342 MiB"},
+            },
+#ifdef _WIN32
+            "powershell -ExecutionPolicy Bypass -File scripts/download-qwen3-tts-gguf.ps1",
+#else
+            "scripts/download-qwen3-tts-gguf.sh",
+#endif
+            {"qwen3-tts", "qwen3tts", "qwen3-tts-customvoice", "qwen3-tts-cv"},
+        },
+        {
+            "qwen3-tts-0.6b-base",
+            "Qwen3-TTS 0.6B Base talker and tokenizer/codec; requires a separate voice reference at runtime",
+            "cstr/qwen3-tts-0.6b-base-GGUF + cstr/qwen3-tts-tokenizer-12hz-GGUF",
+            "0.6B Base q8_0",
+            "",
+            {
+                {"models/tts/qwen3-tts-0.6b-base/qwen3-tts-12hz-0.6b-base-q8_0.gguf", ""},
+                {"models/tts/qwen3-tts-0.6b-base/qwen3-tts-tokenizer-12hz.gguf", "about 342 MiB"},
+            },
+#ifdef _WIN32
+            "powershell -ExecutionPolicy Bypass -File scripts/download-qwen3-tts-gguf.ps1 models/tts/qwen3-tts-0.6b-base base q8_0",
+#else
+            "scripts/download-qwen3-tts-gguf.sh models/tts/qwen3-tts-0.6b-base base q8_0",
+#endif
+            {"qwen3-tts-base"},
         },
     };
     return models;
 }
 
 const ManagedModel * find_model(const std::string & name) {
     for (const ManagedModel & model : supported_models()) {
-        if (model.name == name) {
+        if (name_matches_model(model, name)) {
             return &model;
         }
     }
@@ -268,8 +368,16 @@ int run_model_command(
 
     const ManagedModel * model = find_model(args[1]);
     if (!model) {
-        err << "Unknown model: " << args[1] << "\n"
-            << "Run 'vox model list' to see supported models.\n";
+        err << "Unknown model: " << args[1] << "\n";
+        const std::vector<std::string> suggestions = suggest_models(args[1]);
+        if (!suggestions.empty()) {
+            err << "Did you mean:";
+            for (const std::string & suggestion : suggestions) {
+                err << " " << suggestion;
+            }
+            err << "\n";
+        }
+        err << "Run 'vox model list' to see supported models.\n";
         return 1;
     }
 

apps/model_manager.h

@@ -21,6 +21,7 @@ struct ManagedModel {
     std::string checksum;
     std::vector<ManagedModelFile> files;
     std::string download_command;
+    std::vector<std::string> aliases;
 };
 
 struct ManagedModelFileStatus {

apps/vox.cpp

@@ -175,16 +175,16 @@ const char * tts_engine_name(TtsEngine engine) {
     return "unknown";
 }
 
-const char * tts_download_script(TtsEngine engine) {
+const char * tts_model_manager_name(TtsEngine engine) {
     switch (engine) {
     case TtsEngine::CosyVoice3:
-        return "scripts/download-cosyvoice3-tts-gguf.sh";
+        return "cosyvoice3-tts";
     case TtsEngine::Kokoro:
-        return "scripts/download-kokoro-tts-gguf.sh";
+        return "kokoro-tts";
     case TtsEngine::Qwen3Tts:
-        return "scripts/download-qwen3-tts-gguf.sh";
+        return "qwen3-tts-0.6b-customvoice";
     }
-    return "scripts/download-cosyvoice3-tts-gguf.sh";
+    return "cosyvoice3-tts";
 }
 
 std::string default_tts_language(const CliOptions & options,
@@ -707,7 +707,7 @@ int main(int argc, char ** argv) {
             tts_model_path = resolve_model_path(cli.tts_model_path);
             if (!file_exists(tts_model_path)) {
                 std::cerr << "Missing TTS model: " << tts_model_path << "\n"
-                          << "Download: vox model download cosyvoice3-tts\n";
+                          << "Download: vox model download " << tts_model_manager_name(tts_engine) << "\n";
                 return 1;
             }
 

tests/model_manager_test.cpp

@@ -31,6 +31,12 @@ int main() {
 
     const vox::app::model::ManagedModel * model = vox::app::model::find_model("whisper-base");
     ok = expect(model != nullptr, "whisper-base should be supported") && ok;
+    const vox::app::model::ManagedModel * kokoro = vox::app::model::find_model("kokoro");
+    ok = expect(kokoro != nullptr && kokoro->name == "kokoro-tts", "kokoro alias should resolve") && ok;
+    const vox::app::model::ManagedModel * qwen3_tts = vox::app::model::find_model("qwen3-tts");
+    ok = expect(qwen3_tts != nullptr && qwen3_tts->name == "qwen3-tts-0.6b-customvoice",
+                "qwen3-tts alias should resolve to CustomVoice") &&
+         ok;
     ok = expect(vox::app::model::find_model("missing-model") == nullptr, "unknown model should not resolve") && ok;
     if (!model) {
         return 1;
@@ -48,7 +54,40 @@ int main() {
 
     std::ostringstream out;
     std::ostringstream err;
-    int result = vox::app::model::run_model_command({"list", "--installed"}, root, out, err);
+    int result = vox::app::model::run_model_command({"list"}, root, out, err);
+    ok = expect(result == 0, "list should succeed") && ok;
+    ok = expect(out.str().find("kokoro-tts") != std::string::npos, "list should include Kokoro") && ok;
+    ok = expect(out.str().find("qwen3-tts-0.6b-customvoice") != std::string::npos,
+                "list should include Qwen3-TTS CustomVoice") &&
+         ok;
+    ok = expect(out.str().find("qwen3-tts-0.6b-base") != std::string::npos, "list should include Qwen3-TTS Base") &&
+         ok;
+
+    out.str("");
+    out.clear();
+    err.str("");
+    err.clear();
+    result = vox::app::model::run_model_command({"verify", "kokoro"}, root, out, err);
+    ok = expect(result == 1, "verify should fail for missing Kokoro files") && ok;
+    ok = expect(out.str().find("kokoro-tts (missing)") != std::string::npos,
+                "verify should print canonical Kokoro model details") &&
+         ok;
+
+    out.str("");
+    out.clear();
+    err.str("");
+    err.clear();
+    result = vox::app::model::run_model_command({"verify", "qwen3-tts-custom"}, root, out, err);
+    ok = expect(result == 1, "unknown similar model should fail") && ok;
+    ok = expect(err.str().find("Did you mean: qwen3-tts-0.6b-customvoice") != std::string::npos,
+                "unknown model should include suggestions") &&
+         ok;
+
+    out.str("");
+    out.clear();
+    err.str("");
+    err.clear();
+    result = vox::app::model::run_model_command({"list", "--installed"}, root, out, err);
     ok = expect(result == 0, "list --installed should succeed for incomplete models") && ok;
     ok = expect(out.str().find("whisper-base") != std::string::npos, "installed list should include incomplete model") && ok;