Merge pull request #114 from fbdp1202/docs/update-readme-supertonic-3

docs: revamp README for Supertonic 3

README.md

@@ -1,16 +1,38 @@
 # Supertonic — Lightning Fast, On-Device, Accurate TTS
 
-[![v3 Demo](https://img.shields.io/badge/🤗%20v3-Demo-yellow)](https://huggingface.co/spaces/Supertone/supertonic-3)
-[![v3 Models](https://img.shields.io/badge/🤗%20v3-Models-blue)](https://huggingface.co/Supertone/supertonic-3)
-[![v2 Branch](https://img.shields.io/badge/v2-release%2Fsupertonic--2-lightgrey)](https://github.com/supertone-inc/supertonic/tree/release/supertonic-2)
-[![v1 Demo](https://img.shields.io/badge/🤗%20v1%20(old)-Demo-lightgrey)](https://huggingface.co/spaces/Supertone/supertonic#interactive-demo)
-[![v1 Models](https://img.shields.io/badge/🤗%20v1%20(old)-Models-lightgrey)](https://huggingface.co/Supertone/supertonic)
-
 <p align="center">
   <img src="img/Supertonic3_HeroImage.png" alt="Supertonic 3 Banner">
 </p>
 
-**Supertonic** is a lightning-fast, on-device text-to-speech system designed for local inference with minimal overhead. Powered by ONNX Runtime, it runs entirely on your device—no cloud, no API calls, no privacy concerns.
+[![GitHub | Official Repo](https://img.shields.io/badge/GitHub-Official%20Repo-black?logo=github)](https://github.com/supertone-inc/supertonic)
+[![Models](https://img.shields.io/badge/🤗%20Hugging%20Face-Models-blue)](https://huggingface.co/Supertone/supertonic-3)
+[![Runs Locally via WebGPU](https://img.shields.io/badge/🤗%20Hugging%20Face-Demo-yellow)](https://huggingface.co/spaces/Supertone/supertonic-3)
+[![DemoPage | Audio Samples](https://img.shields.io/badge/DemoPage-Audio%20Samples-F5D90A?labelColor=0B0C0E)](https://supertonic3.github.io/)
+[![Voice Builder | Cloning Demo](https://img.shields.io/badge/Voice%20Builder-Cloning%20Demo-3457D5?logo=soundcloud&logoColor=white)](https://supertonic.supertone.ai/voice_builder)
+[![GitHub | Python Package](https://img.shields.io/badge/GitHub-Python%20Package-black?logo=github)](https://github.com/supertone-inc/supertonic-py)
+[![Docs | Python PyPI](https://img.shields.io/badge/Docs-Python%20PyPI-blue?logo=readthedocs&logoColor=white)](https://supertone-inc.github.io/supertonic-py/)
+
+<p align="center">
+  <a href="https://trendshift.io/repositories/15657" target="_blank"><img src="https://trendshift.io/api/badge/repositories/15657" alt="supertone-inc%2Fsupertonic | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
+</p>
+
+**Supertonic** is a lightning-fast, on-device multilingual text-to-speech system designed for local inference with minimal overhead. Powered by ONNX Runtime, it runs entirely on your device—no cloud, no API calls, no privacy concerns.
+
+### ✨ Highlights
+
+- ⚡ **Blazingly Fast** — Low-latency, real-time synthesis across desktop, browser, mobile, and edge — fast enough to turn an entire webpage into audio in under a second
+- 🌍 **31-Language Multilingual** — Synthesize directly from text across 31 languages, or pass `lang="na"` to let Supertonic process the text language-agnostically when you don't know the input language — no separate language adapters needed
+- 🪶 **99M-Parameter Open-Weight Model** — A compact, fully open-weight checkpoint — a fraction of the size of 0.7B–2B class open TTS systems — for smaller downloads, faster cold starts, and lower memory footprint
+- 📱 **Edge-Device Ready** — Runs locally on desktop, mobile, browsers, and resource-constrained hardware like Raspberry Pi or e-readers, with zero network dependency, complete privacy, and no GPU required
+- 🔊 **44.1kHz High-Quality Audio** — Outputs studio-grade 44.1kHz 16-bit WAV directly, ready for production playback without any external upsampler
+- 🎭 **Expression Tags** — 10 inline tags (e.g. `<laugh>`, `<breath>`, `<sigh>`) bring natural human nuance into generated speech without prompt engineering or reference audio
+- 🛠️ **Multi-Runtime SDKs** — Ready-to-use examples through ONNX Runtime across Python, Node.js, Browser (WebGPU), Java, C++, C#, Go, Swift, iOS, Rust, and Flutter
+
+### 🌍 Supported Languages (31)
+
+Arabic (`ar`), Bulgarian (`bg`), Croatian (`hr`), Czech (`cs`), Danish (`da`), Dutch (`nl`), English (`en`), Estonian (`et`), Finnish (`fi`), French (`fr`), German (`de`), Greek (`el`), Hindi (`hi`), Hungarian (`hu`), Indonesian (`id`), Italian (`it`), Japanese (`ja`), Korean (`ko`), Latvian (`lv`), Lithuanian (`lt`), Polish (`pl`), Portuguese (`pt`), Romanian (`ro`), Russian (`ru`), Slovak (`sk`), Slovenian (`sl`), Spanish (`es`), Swedish (`sv`), Turkish (`tr`), Ukrainian (`uk`), Vietnamese (`vi`)
+
+> **Not sure which language your text is in?** Pass `lang="na"` and Supertonic will handle the input in a language-agnostic way — no explicit language tag required.
 
 ### 📰 Update News
 
@@ -22,6 +44,8 @@
 - **2025.12.08** - Optimized ONNX models via [OnnxSlim](https://github.com/inisis/OnnxSlim) now available on [Hugging Face Models](https://huggingface.co/Supertone/supertonic)
 - **2025.11.24** - Added Flutter SDK support with macOS compatibility
 
+---
+
 ## Quick Start
 
 Install the Python SDK and generate speech immediately. On the first run, Supertonic downloads the model assets from Hugging Face automatically.
@@ -40,11 +64,23 @@ tts = TTS(auto_download=True)
 
 style = tts.get_voice_style(voice_name="M1")
 
-text = "A gentle breeze moved through the open window while everyone listened to the story."
+text = "Supertonic is a lightning fast, on-device TTS system."
-wav, duration = tts.synthesize(text, voice_style=style, lang="en")
+
+wav, duration = tts.synthesize(
+    text=text,
+    lang="en",                      # Language code (e.g., "en", "ko", "na" for language-agnostic)
+    voice_style=style,              # Voice style object
+    total_steps=8,                  # Quality: 5 (low) to 12 (high), default 8 (medium)
+    speed=1.05,                     # Speed: 0.7 (slow) to 2.0 (fast)
+)
+# wav: numpy array of shape (1, num_samples,) with dtype=np.float32, sampled at 44100 Hz
+# duration: numpy array of shape (1,) containing the duration of the generated audio in seconds
 
 tts.save_audio(wav, "output.wav")
-print(f"Generated {duration:.2f}s of audio")
+# import soundfile as sf
+# sf.write("output.wav", wav.squeeze(), 44100)
+
+print(f"Generated {duration[0]:.2f}s of audio")
 ```
 
 ## Getting Started
@@ -157,13 +193,14 @@ In Xcode: Targets → ExampleiOSApp → Signing: select your Team, then choose y
 
 </details>
 
+---
 
 ### Technical Details
 
 - **Runtime**: ONNX Runtime for cross-platform inference
 - **Browser Support**: onnxruntime-web for client-side inference
 - **Batch Processing**: Supports batch inference for improved throughput
-- **Audio Output**: Outputs 16-bit WAV files
+- **Audio Output**: Outputs 44.1kHz 16-bit WAV files
 
 ## Performance Highlights
 
@@ -175,7 +212,40 @@ Supertonic 3 is designed for practical on-device inference: compact enough to ru
   <img src="img/metrics/s3_vs_measured_wer_range_voxcpm2.png" alt="Supertonic 3 reading accuracy compared with measured model ranges and VoxCPM2">
 </p>
 
-Across measured languages, Supertonic 3 stays within a competitive WER/CER range against much larger open TTS models such as VoxCPM2, while preserving a lightweight on-device deployment path. Asterisked languages use CER; the others use WER.
+Evaluated on the **[Minimax-MLS-test](https://huggingface.co/datasets/MiniMaxAI/TTS-MLS-Test) benchmark**, Supertonic 3 stays within a competitive WER/CER range against much larger open TTS models such as VoxCPM2, while preserving a lightweight on-device deployment path. Asterisked languages (`*`) use CER; the others use WER.
+
+<details>
+<summary><b>📊 Detailed per-language results (WER / CER*)</b></summary>
+
+<br>
+
+| Lang | VoxCPM2 | OmniVoice | Qwen3-TTS | Supertonic 2 | **Supertonic 3** |
+|---|:---:|:---:|:---:|:---:|:---:|
+| arabic\*   | 4.14  | 1.74  | —    | —    | **2.14**  |
+| czech      | 23.73 | 2.40  | —    | —    | **3.02**  |
+| dutch      | 0.84  | 0.77  | —    | —    | **1.47**  |
+| english    | 2.11  | 2.02  | 2.25 | 2.52 | **2.06**  |
+| finnish    | 2.29  | 3.94  | —    | —    | **5.40**  |
+| french     | 4.41  | 4.74  | 3.82 | 5.09 | **4.89**  |
+| german     | 0.85  | 0.96  | 0.52 | —    | **0.86**  |
+| greek      | 3.22  | 2.96  | —    | —    | **3.54**  |
+| hindi\*    | 5.85  | 5.14  | —    | —    | **5.34**  |
+| indonesian | 1.25  | 1.67  | —    | —    | **1.34**  |
+| italian    | 1.74  | 1.29  | 1.40 | —    | **1.75**  |
+| japanese\* | 3.35  | 3.81  | 3.67 | —    | **4.61**  |
+| korean\*   | 4.70  | 3.22  | 4.07 | 3.65 | **3.26**  |
+| polish     | 1.30  | 0.64  | —    | —    | **1.63**  |
+| portuguese | 1.74  | 1.40  | 1.21 | 1.52 | **2.48**  |
+| romanian   | 22.39 | 2.29  | —    | —    | **2.19**  |
+| russian    | 3.31  | 4.53  | 4.48 | —    | **3.99**  |
+| spanish    | 1.34  | 0.99  | 0.75 | 1.81 | **1.13**  |
+| turkish    | 0.88  | 2.18  | —    | —    | **1.00**  |
+| ukrainian  | 5.85  | 0.71  | —    | —    | **1.23**  |
+| vietnamese | 1.48  | 0.79  | —    | —    | **4.49**  |
+
+> Lower is better. `*` indicates CER (character error rate); all other rows use WER (word error rate). Dashes (`—`) indicate the model does not officially support the language or no result is available.
+
+</details>
 
 ### Supertonic 2 to Supertonic 3
 
@@ -223,29 +293,7 @@ Turns any webpage into audio in under one second, delivering lightning-fast, on-
 
 https://github.com/user-attachments/assets/cc8a45fc-5c3e-4b2c-8439-a14c3d00d91c
 
-## Why Supertonic?
+## Programming Language Support
-
-- **Blazingly Fast**: Optimized for low-latency, on-device speech generation across desktop, browser, and edge deployments
-- **Lightweight**: Compact ONNX assets designed for efficient local execution
-- **On-Device Capable**: Complete privacy and zero network dependency
-- **Accurate Reading**: Improved reading stability with fewer repeat and skip failures
-- **Expressive Tags**: Supports simple expression tags such as `<laugh>`, `<breath>`, and `<sigh>`
-- **Flexible Deployment**: Ready-to-use examples across Python, JavaScript, browser, mobile, and native runtimes
-
-## Language Support
-
-Supertonic 3 supports 31 languages:
-
-| Code | Language | Code | Language | Code | Language | Code | Language |
-|------|----------|------|----------|------|----------|------|----------|
-| `en` | English | `ko` | Korean | `ja` | Japanese | `ar` | Arabic |
-| `bg` | Bulgarian | `cs` | Czech | `da` | Danish | `de` | German |
-| `el` | Greek | `es` | Spanish | `et` | Estonian | `fi` | Finnish |
-| `fr` | French | `hi` | Hindi | `hr` | Croatian | `hu` | Hungarian |
-| `id` | Indonesian | `it` | Italian | `lt` | Lithuanian | `lv` | Latvian |
-| `nl` | Dutch | `pl` | Polish | `pt` | Portuguese | `ro` | Romanian |
-| `ru` | Russian | `sk` | Slovak | `sl` | Slovenian | `sv` | Swedish |
-| `tr` | Turkish | `uk` | Ukrainian | `vi` | Vietnamese | | |
 
 We provide ready-to-use TTS inference examples across multiple ecosystems:
 
@@ -373,6 +421,19 @@ Supertonic is designed to handle complex, real-world text inputs that contain na
 | **Transformers.js** | Hugging Face's JS library with Supertonic support | [GitHub PR](https://github.com/huggingface/transformers.js/pull/1459) · [Demo](https://huggingface.co/spaces/webml-community/Supertonic-TTS-WebGPU) |
 | **Pinokio** | 1-click localhost cloud for Mac, Windows, and Linux | [Pinokio](https://pinokio.co/) · [GitHub](https://github.com/SUP3RMASS1VE/SuperTonic-TTS) |
 
+## Models & Versions
+
+|  | **Supertonic 3** | Supertonic 2 | Supertonic 1 |
+|---|:---:|:---:|:---:|
+| **Status** | 🟢 Latest | Stable | Legacy |
+| **Parameters** | ~99M | ~66M | ~66M |
+| **Languages** | 31 | 5 | 1 (en) |
+| **Expression Tags** | ✅ 10 tags | — | — |
+| **Code** | [main](https://github.com/supertone-inc/supertonic) | [release/supertonic-2](https://github.com/supertone-inc/supertonic/tree/release/supertonic-2) | — |
+| **Weights** | [🤗 HF](https://huggingface.co/Supertone/supertonic-3) | [🤗 HF](https://huggingface.co/Supertone/supertonic-2) | [🤗 HF](https://huggingface.co/Supertone/supertonic) |
+| **Interactive Demo** | [🤗 Space](https://huggingface.co/spaces/Supertone/supertonic-3) | [🤗 Space](https://huggingface.co/spaces/Supertone/supertonic-2) | [🤗 Space](https://huggingface.co/spaces/Supertone/supertonic#interactive-demo) |
+| **Audio Samples** | [DemoPage](https://supertonic3.github.io/) | — | [DemoPage](https://supertonictts.github.io/) |
+
 ## Citation
 
 The following papers describe the core technologies used in Supertonic. If you use this system in your research or find these techniques useful, please consider citing the relevant papers:

cpp/helper.cpp

@@ -12,7 +12,7 @@
 using json = nlohmann::json;
 
 // Available languages for multilingual TTS
-const std::vector<std::string> AVAILABLE_LANGS = {"en", "ko", "ja", "ar", "bg", "cs", "da", "de", "el", "es", "et", "fi", "fr", "hi", "hr", "hu", "id", "it", "lt", "lv", "nl", "pl", "pt", "ro", "ru", "sk", "sl", "sv", "tr", "uk", "vi"};
+const std::vector<std::string> AVAILABLE_LANGS = {"en", "ko", "ja", "ar", "bg", "cs", "da", "de", "el", "es", "et", "fi", "fr", "hi", "hr", "hu", "id", "it", "lt", "lv", "nl", "pl", "pt", "ro", "ru", "sk", "sl", "sv", "tr", "uk", "vi", "na"};
 
 // Global tensor buffers for memory management
 static std::vector<std::vector<float>> g_tensor_buffers_float;

csharp/Helper.cs

@@ -13,7 +13,7 @@ namespace Supertonic
     // Available languages for multilingual TTS
     public static class Languages
     {
-        public static readonly string[] Available = { "en", "ko", "ja", "ar", "bg", "cs", "da", "de", "el", "es", "et", "fi", "fr", "hi", "hr", "hu", "id", "it", "lt", "lv", "nl", "pl", "pt", "ro", "ru", "sk", "sl", "sv", "tr", "uk", "vi" };
+        public static readonly string[] Available = { "en", "ko", "ja", "ar", "bg", "cs", "da", "de", "el", "es", "et", "fi", "fr", "hi", "hr", "hu", "id", "it", "lt", "lv", "nl", "pl", "pt", "ro", "ru", "sk", "sl", "sv", "tr", "uk", "vi", "na" };
     }
 
     // ============================================================================

flutter/lib/helper.dart

@@ -12,7 +12,7 @@ final logger = Logger(
 );
 
 // Available languages for multilingual TTS
-const List<String> availableLangs = ['en', 'ko', 'ja', 'ar', 'bg', 'cs', 'da', 'de', 'el', 'es', 'et', 'fi', 'fr', 'hi', 'hr', 'hu', 'id', 'it', 'lt', 'lv', 'nl', 'pl', 'pt', 'ro', 'ru', 'sk', 'sl', 'sv', 'tr', 'uk', 'vi'];
+const List<String> availableLangs = ['en', 'ko', 'ja', 'ar', 'bg', 'cs', 'da', 'de', 'el', 'es', 'et', 'fi', 'fr', 'hi', 'hr', 'hu', 'id', 'it', 'lt', 'lv', 'nl', 'pl', 'pt', 'ro', 'ru', 'sk', 'sl', 'sv', 'tr', 'uk', 'vi', 'na'];
 
 bool isValidLang(String lang) => availableLangs.contains(lang);
 

go/helper.go

@@ -19,7 +19,7 @@ import (
 )
 
 // Available languages for multilingual TTS
-var AvailableLangs = []string{"en", "ko", "ja", "ar", "bg", "cs", "da", "de", "el", "es", "et", "fi", "fr", "hi", "hr", "hu", "id", "it", "lt", "lv", "nl", "pl", "pt", "ro", "ru", "sk", "sl", "sv", "tr", "uk", "vi"}
+var AvailableLangs = []string{"en", "ko", "ja", "ar", "bg", "cs", "da", "de", "el", "es", "et", "fi", "fr", "hi", "hr", "hu", "id", "it", "lt", "lv", "nl", "pl", "pt", "ro", "ru", "sk", "sl", "sv", "tr", "uk", "vi", "na"}
 
 // Config structures
 type SpecProcessorConfig struct {

ios/ExampleiOSApp/TTSService.swift

@@ -35,6 +35,7 @@ final class TTSService {
         case tr = "tr"
         case uk = "uk"
         case vi = "vi"
+        case na = "na"
 
         var displayName: String {
             switch self {
@@ -69,6 +70,7 @@ final class TTSService {
             case .tr: return "Turkish"
             case .uk: return "Ukrainian"
             case .vi: return "Vietnamese"
+            case .na: return "Auto (language-agnostic)"
             }
         }
     }

java/Helper.java

@@ -22,7 +22,7 @@ import java.util.regex.Matcher;
  * Available languages for multilingual TTS
  */
 class Languages {
-    public static final List<String> AVAILABLE = Arrays.asList("en", "ko", "ja", "ar", "bg", "cs", "da", "de", "el", "es", "et", "fi", "fr", "hi", "hr", "hu", "id", "it", "lt", "lv", "nl", "pl", "pt", "ro", "ru", "sk", "sl", "sv", "tr", "uk", "vi");
+    public static final List<String> AVAILABLE = Arrays.asList("en", "ko", "ja", "ar", "bg", "cs", "da", "de", "el", "es", "et", "fi", "fr", "hi", "hr", "hu", "id", "it", "lt", "lv", "nl", "pl", "pt", "ro", "ru", "sk", "sl", "sv", "tr", "uk", "vi", "na");
     
     public static boolean isValid(String lang) {
         return AVAILABLE.contains(lang);

nodejs/helper.js

@@ -5,7 +5,7 @@ import * as ort from 'onnxruntime-node';
 
 const __filename = fileURLToPath(import.meta.url);
 
-const AVAILABLE_LANGS = ["en", "ko", "ja", "ar", "bg", "cs", "da", "de", "el", "es", "et", "fi", "fr", "hi", "hr", "hu", "id", "it", "lt", "lv", "nl", "pl", "pt", "ro", "ru", "sk", "sl", "sv", "tr", "uk", "vi"];
+const AVAILABLE_LANGS = ["en", "ko", "ja", "ar", "bg", "cs", "da", "de", "el", "es", "et", "fi", "fr", "hi", "hr", "hu", "id", "it", "lt", "lv", "nl", "pl", "pt", "ro", "ru", "sk", "sl", "sv", "tr", "uk", "vi", "na"];
 
 /**
  * Unicode text processor

py/example_pypi.py

@@ -14,3 +14,4 @@ wav, duration = tts.synthesize(text, voice_style=style)
 
 # Save to file
 tts.save_audio(wav, "results/example_pypi.wav")
+print(f"Generated {duration[0]:.2f}s of audio")

py/helper.py

@@ -10,7 +10,7 @@ import onnxruntime as ort
 
 import re
 
-AVAILABLE_LANGS = ["en", "ko", "ja", "ar", "bg", "cs", "da", "de", "el", "es", "et", "fi", "fr", "hi", "hr", "hu", "id", "it", "lt", "lv", "nl", "pl", "pt", "ro", "ru", "sk", "sl", "sv", "tr", "uk", "vi"]
+AVAILABLE_LANGS = ["en", "ko", "ja", "ar", "bg", "cs", "da", "de", "el", "es", "et", "fi", "fr", "hi", "hr", "hu", "id", "it", "lt", "lv", "nl", "pl", "pt", "ro", "ru", "sk", "sl", "sv", "tr", "uk", "vi", "na"]
 
 
 class UnicodeProcessor:

rust/src/helper.rs

@@ -15,7 +15,7 @@ use rand_distr::{Distribution, Normal};
 use regex::Regex;
 
 // Available languages for multilingual TTS
-pub const AVAILABLE_LANGS: &[&str] = &["en", "ko", "ja", "ar", "bg", "cs", "da", "de", "el", "es", "et", "fi", "fr", "hi", "hr", "hu", "id", "it", "lt", "lv", "nl", "pl", "pt", "ro", "ru", "sk", "sl", "sv", "tr", "uk", "vi"];
+pub const AVAILABLE_LANGS: &[&str] = &["en", "ko", "ja", "ar", "bg", "cs", "da", "de", "el", "es", "et", "fi", "fr", "hi", "hr", "hu", "id", "it", "lt", "lv", "nl", "pl", "pt", "ro", "ru", "sk", "sl", "sv", "tr", "uk", "vi", "na"];
 
 pub fn is_valid_lang(lang: &str) -> bool {
     AVAILABLE_LANGS.contains(&lang)

swift/Sources/Helper.swift

@@ -4,7 +4,7 @@ import OnnxRuntimeBindings
 
 // MARK: - Available Languages
 
-let AVAILABLE_LANGS = ["en", "ko", "ja", "ar", "bg", "cs", "da", "de", "el", "es", "et", "fi", "fr", "hi", "hr", "hu", "id", "it", "lt", "lv", "nl", "pl", "pt", "ro", "ru", "sk", "sl", "sv", "tr", "uk", "vi"]
+let AVAILABLE_LANGS = ["en", "ko", "ja", "ar", "bg", "cs", "da", "de", "el", "es", "et", "fi", "fr", "hi", "hr", "hu", "id", "it", "lt", "lv", "nl", "pl", "pt", "ro", "ru", "sk", "sl", "sv", "tr", "uk", "vi", "na"]
 
 func isValidLang(_ lang: String) -> Bool {
     return AVAILABLE_LANGS.contains(lang)

web/helper.js

@@ -1,7 +1,7 @@
 import * as ort from 'onnxruntime-web';
 
 // Available languages for multilingual TTS
-export const AVAILABLE_LANGS = ['en', 'ko', 'ja', 'ar', 'bg', 'cs', 'da', 'de', 'el', 'es', 'et', 'fi', 'fr', 'hi', 'hr', 'hu', 'id', 'it', 'lt', 'lv', 'nl', 'pl', 'pt', 'ro', 'ru', 'sk', 'sl', 'sv', 'tr', 'uk', 'vi'];
+export const AVAILABLE_LANGS = ['en', 'ko', 'ja', 'ar', 'bg', 'cs', 'da', 'de', 'el', 'es', 'et', 'fi', 'fr', 'hi', 'hr', 'hu', 'id', 'it', 'lt', 'lv', 'nl', 'pl', 'pt', 'ro', 'ru', 'sk', 'sl', 'sv', 'tr', 'uk', 'vi', 'na'];
 
 export function isValidLang(lang) {
     return AVAILABLE_LANGS.includes(lang);