From 4523db999ea7ec152bc0bf4226908fa9fd866ea3 Mon Sep 17 00:00:00 2001
From: Xuan Son Nguyen <son@huggingface.co>
Date: Sat, 1 Aug 2026 16:35:17 +0200
Subject: [PATCH] add guide + docs

---
 common/arg.cpp                 |  3 ++-
 tools/mtmd/mtmd-helper-gen.cpp | 23 ++++++++++++++++++++++-
 tools/tts/README.md            | 29 ++++++++++++++++++++++++++++-
 tools/tts/tts.cpp              |  1 +
 4 files changed, 53 insertions(+), 3 deletions(-)

diff --git a/common/arg.cpp b/common/arg.cpp
index 1905c3e99c..79e9714837 100644
--- a/common/arg.cpp
+++ b/common/arg.cpp
@@ -4195,7 +4195,8 @@ common_params_context common_params_parser_init(common_params & params, llama_ex
 
     add_opt(common_arg(
         {"--tts-lang"}, "FNAME",
-        "language for audio generation",
+        "language (two-letter country code) for audio generation\n"
+        "see tts/README.md for per-model usage notes",
         [](common_params & params, const std::string & value) {
             params.tts_lang = value;
         }
diff --git a/tools/mtmd/mtmd-helper-gen.cpp b/tools/mtmd/mtmd-helper-gen.cpp
index 7c79180d0e..dcd802c6ad 100644
--- a/tools/mtmd/mtmd-helper-gen.cpp
+++ b/tools/mtmd/mtmd-helper-gen.cpp
@@ -8,6 +8,7 @@
 #include <cstring>
 #include <memory>
 #include <string>
+#include <unordered_map>
 #include <vector>
 
 #ifdef MTMD_INTERNAL_HEADER
@@ -18,6 +19,26 @@
 // Audio generation helpers
 //
 
+// maps the 2-letter --tts-lang codes (see tools/tts/README.md) to the language
+// names used by the codec_language special tokens
+static const std::unordered_map<std::string, std::string> tts_lang_codes = {
+    { "cn", "chinese"    },
+    { "en", "english"    },
+    { "ge", "german"     },
+    { "it", "italian"    },
+    { "po", "portuguese" },
+    { "sp", "spanish"    },
+    { "ja", "japanese"   },
+    { "ko", "korean"     },
+    { "fr", "french"     },
+    { "ru", "russian"    },
+};
+
+static std::string tts_resolve_lang(const std::string & lang) {
+    auto it = tts_lang_codes.find(lang);
+    return it != tts_lang_codes.end() ? it->second : lang;
+}
+
 static llama_token find_special_token(const llama_vocab * vocab, const std::string & piece) {
     const int32_t n = llama_vocab_n_tokens(vocab);
     for (llama_token t = 0; t < n; t++) {
@@ -97,7 +118,7 @@ public:
             return 1;
         }
 
-        const std::string lang   = (inp->lang && inp->lang[0]) ? inp->lang : "english";
+        const std::string lang   = tts_resolve_lang((inp->lang && inp->lang[0]) ? inp->lang : "english");
         const llama_token c_lang = find_special_token(vocab, ("<|codec_language_" + lang + "|>").c_str());
         if (c_lang == LLAMA_TOKEN_NULL) {
             LOG_ERR("mtmd_helper_gen_audio: unknown language '%s'\n", lang.c_str());
diff --git a/tools/tts/README.md b/tools/tts/README.md
index 92161b241b..970e5d5035 100644
--- a/tools/tts/README.md
+++ b/tools/tts/README.md
@@ -4,4 +4,31 @@ This is a tool to demonstrate audio generation capability in llama.cpp via `libm
 
 Note: this tool used to serve as a demo for OuteTTS, but it was converted to a more model-agnostic tool.
 
-TODO: write a per-model guide here
+## Common usage
+
+Simple usage:
+
+```sh
+llama-tts -hf ggml-org/Qwen3-TTS-12Hz-1.7B-Base-GGUF -p "Hello world" --output out.wav
+```
+
+Common params:
+- Sampling params such as `--top-k`, `--top-p`, `--temp`, etc.
+- `-n <number_of_frames>` limits the output length, e.g. `-n 500`. Note that how many milliseconds each frame represents varies by model
+- Core inference params such as `-ngl`, `-b`, `-ub`, etc.
+
+## Qwen3-TTS
+
+Available params:
+- `--tts-lang` can be `cn`, `en`, `ge`, `it`, `po`, `sp`, `ja`, `ko`, `fr`, `ru` (default: `en`)
+- `--tts-speaker-file` should point to a speaker reference audio file (wav, mp3)
+
+Example usage:
+
+```sh
+llama-tts -hf ggml-org/Qwen3-TTS-12Hz-1.7B-Base-GGUF \
+    -p "Hello world" \
+    --tts-lang english \
+    --tts-speaker-file speaker.mp3 \
+    --output out.wav
+```
diff --git a/tools/tts/tts.cpp b/tools/tts/tts.cpp
index 1f4f333a7c..cc2bca6a40 100644
--- a/tools/tts/tts.cpp
+++ b/tools/tts/tts.cpp
@@ -38,6 +38,7 @@ static void print_usage(int, char ** argv) {
     LOG("\n    %s -hf user/model -p \"text to speak\" -o output.wav\n", argv[0]);
     LOG("\nnote: --tts-lang and --tts-speaker-file may not be supported in all models");
     LOG("\n      use -n to limit the output length");
+    LOG("\n      see tts/README.md for per-model usage notes");
     LOG("\n\n");
 }