supersonic-tts 0.1.0__tar.gz

supersonic_tts-0.1.0/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: supersonic-tts
+Version: 0.1.0
+Summary: Stdin-friendly CLI + Python API wrapper for Supertonic — lightning-fast, on-device, multilingual TTS
+Project-URL: Homepage, https://github.com/jxsprt/supersonic-tts
+Project-URL: Repository, https://github.com/jxsprt/supersonic-tts
+Author-email: Jaspreet Singh <jaspreetsinghintp@gmail.com>
+License: MIT
+Keywords: on-device,onnx,supertonic,text-to-speech,tts
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Requires-Dist: supertonic>=1.0.0
+Description-Content-Type: text/markdown
+
+# supersonic-tts
+
+**Stdin-friendly CLI + Python API wrapper for [Supertonic](https://github.com/supertone-inc/supertonic)** — lightning-fast, on-device, multilingual TTS via ONNX Runtime.
+
+No cloud API. No data leaves your machine. 31 languages. 10 voices.
+
+## Why supersonic-tts?
+
+Supertonic's official CLI takes text as a positional argument — awkward for piped input, shell scripts, and AI agents. `supersonic-tts` wraps it with:
+
+- **Stdin support** — pipe text directly: `echo "hello" | supersonic-tts -o out.wav`
+- **Hermes Agent integration** — drop-in command-based TTS provider
+- **Same engine** — uses supertonic under the hood (supertonic-3, ONNX)
+
+## Install
+
+```bash
+pip install supersonic-tts
+```
+
+First run auto-downloads the model (~305MB) from HuggingFace.
+
+## Usage
+
+### CLI
+
+```bash
+# Read from argument
+supersonic-tts "Hello world" -o output.wav
+
+# Read from stdin (piped)
+echo "Hello from stdin" | supersonic-tts -o output.wav
+
+# Read from file
+cat long_text.txt | supersonic-tts -o output.wav
+
+# Choose voice
+supersonic-tts "Crisp and confident" -o output.wav --voice F4
+
+# Multilingual
+supersonic-tts "Bonjour le monde" -o french.wav --lang fr --voice F1
+
+# Adjust speed
+supersonic-tts "Fast talk" -o fast.wav --speed 1.5
+
+# Higher quality
+supersonic-tts "Premium quality" -o premium.wav --steps 10
+```
+
+### Python API
+
+```python
+from supersonic_tts import SupersonicTTS
+
+tts = SupersonicTTS()
+wav, duration = tts.synthesize("Hello world", voice="F4", lang="en")
+tts.save("output.wav")
+```
+
+### Hermes Agent Integration
+
+Add to `~/.hermes/config.yaml`:
+
+```yaml
+tts:
+  provider: supersonic-tts
+  supersonic-tts:
+    type: command
+    command: supersonic-tts -o {output_path} --voice {voice} < {input_path}
+    voice: F4
+    model: supertonic-3
+    output_format: wav
+    voice_compatible: true
+    timeout: 60
+```
+
+## Voices
+
+| Voice | Style |
+|-------|-------|
+| M1 | Lively, upbeat male |
+| M2 | Deep, calm male |
+| M3 | Authoritative male |
+| M4 | Soft, friendly male |
+| M5 | Warm, storytelling male |
+| F1 | Calm, composed female |
+| F2 | Bright, cheerful female |
+| F3 | Professional announcer female |
+| **F4** | **Crisp, confident female** |
+| F5 | Gentle, soothing female |
+
+## Languages
+
+31 languages (supertonic-3): 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 (fallback)
+
+## License
+
+MIT (code) — supertonic model uses OpenRAIL-M

supersonic_tts-0.1.0/README.md

@@ -0,0 +1,98 @@
+# supersonic-tts
+
+**Stdin-friendly CLI + Python API wrapper for [Supertonic](https://github.com/supertone-inc/supertonic)** — lightning-fast, on-device, multilingual TTS via ONNX Runtime.
+
+No cloud API. No data leaves your machine. 31 languages. 10 voices.
+
+## Why supersonic-tts?
+
+Supertonic's official CLI takes text as a positional argument — awkward for piped input, shell scripts, and AI agents. `supersonic-tts` wraps it with:
+
+- **Stdin support** — pipe text directly: `echo "hello" | supersonic-tts -o out.wav`
+- **Hermes Agent integration** — drop-in command-based TTS provider
+- **Same engine** — uses supertonic under the hood (supertonic-3, ONNX)
+
+## Install
+
+```bash
+pip install supersonic-tts
+```
+
+First run auto-downloads the model (~305MB) from HuggingFace.
+
+## Usage
+
+### CLI
+
+```bash
+# Read from argument
+supersonic-tts "Hello world" -o output.wav
+
+# Read from stdin (piped)
+echo "Hello from stdin" | supersonic-tts -o output.wav
+
+# Read from file
+cat long_text.txt | supersonic-tts -o output.wav
+
+# Choose voice
+supersonic-tts "Crisp and confident" -o output.wav --voice F4
+
+# Multilingual
+supersonic-tts "Bonjour le monde" -o french.wav --lang fr --voice F1
+
+# Adjust speed
+supersonic-tts "Fast talk" -o fast.wav --speed 1.5
+
+# Higher quality
+supersonic-tts "Premium quality" -o premium.wav --steps 10
+```
+
+### Python API
+
+```python
+from supersonic_tts import SupersonicTTS
+
+tts = SupersonicTTS()
+wav, duration = tts.synthesize("Hello world", voice="F4", lang="en")
+tts.save("output.wav")
+```
+
+### Hermes Agent Integration
+
+Add to `~/.hermes/config.yaml`:
+
+```yaml
+tts:
+  provider: supersonic-tts
+  supersonic-tts:
+    type: command
+    command: supersonic-tts -o {output_path} --voice {voice} < {input_path}
+    voice: F4
+    model: supertonic-3
+    output_format: wav
+    voice_compatible: true
+    timeout: 60
+```
+
+## Voices
+
+| Voice | Style |
+|-------|-------|
+| M1 | Lively, upbeat male |
+| M2 | Deep, calm male |
+| M3 | Authoritative male |
+| M4 | Soft, friendly male |
+| M5 | Warm, storytelling male |
+| F1 | Calm, composed female |
+| F2 | Bright, cheerful female |
+| F3 | Professional announcer female |
+| **F4** | **Crisp, confident female** |
+| F5 | Gentle, soothing female |
+
+## Languages
+
+31 languages (supertonic-3): 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 (fallback)
+
+## License
+
+MIT (code) — supertonic model uses OpenRAIL-M

supersonic_tts-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "supersonic-tts"
+version = "0.1.0"
+description = "Stdin-friendly CLI + Python API wrapper for Supertonic — lightning-fast, on-device, multilingual TTS"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+authors = [
+  { name = "Jaspreet Singh", email = "jaspreetsinghintp@gmail.com" },
+]
+keywords = ["tts", "text-to-speech", "supertonic", "on-device", "onnx"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Multimedia :: Sound/Audio :: Speech",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+dependencies = [
+  "supertonic>=1.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/jxsprt/supersonic-tts"
+Repository = "https://github.com/jxsprt/supersonic-tts"
+
+[project.scripts]
+supersonic-tts = "supersonic_tts.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/supersonic_tts"]

supersonic_tts-0.1.0/src/supersonic_tts/__init__.py

@@ -0,0 +1,5 @@
+"""supersonic-tts — Stdin-friendly CLI + Python API for Supertonic TTS."""
+
+from .core import SupersonicTTS, __version__
+
+__all__ = ["SupersonicTTS", "__version__"]

supersonic_tts-0.1.0/src/supersonic_tts/cli.py

@@ -0,0 +1,168 @@
+#!/usr/bin/env python3
+"""CLI entry point for supersonic-tts.
+
+Reads text from:
+  1. First positional argument
+  2. Stdin (piped text)
+  3. A file via --input
+
+Usage:
+  supersonic-tts "Hello world" -o out.wav
+  echo "Hello" | supersonic-tts -o out.wav
+  cat file.txt | supersonic-tts -o out.wav --voice F4
+  supersonic-tts -o out.wav --input input.txt
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import Optional
+
+from .core import SupersonicTTS
+
+
+def resolve_text(
+    args_text: Optional[str],
+    args_input: Optional[str],
+) -> Optional[str]:
+    """Resolve input text from argument, file, or stdin. Returns None if empty."""
+    # 1. From --input file
+    if args_input:
+        with open(args_input, "r", encoding="utf-8") as f:
+            return f.read().strip()
+
+    # 2. From positional argument
+    if args_text:
+        return args_text.strip()
+
+    # 3. From stdin (only if stdin is not a TTY — i.e. piped)
+    if not sys.stdin.isatty():
+        try:
+            data = sys.stdin.read()
+            if data.strip():
+                return data.strip()
+        except KeyboardInterrupt:
+            return None
+
+    return None
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="supersonic-tts",
+        description="Lightning-fast, on-device, multilingual TTS",
+    )
+    parser.add_argument(
+        "text",
+        nargs="?",
+        default=None,
+        help="Text to synthesize (omit to read from stdin or --input)",
+    )
+    parser.add_argument(
+        "-o", "--output",
+        help="Output WAV file path",
+    )
+    parser.add_argument(
+        "--input",
+        help="Read input text from a file",
+    )
+    parser.add_argument(
+        "--voice",
+        default="M1",
+        choices=sorted(SupersonicTTS.list_voices().keys()),
+        help="Voice style (default: M1)",
+    )
+    parser.add_argument(
+        "--lang",
+        default="en",
+        help="Language code (default: en). Use --list-langs to see all.",
+    )
+    parser.add_argument(
+        "--steps",
+        type=int,
+        default=5,
+        help="Synthesis quality steps (default: 5, higher = better)",
+    )
+    parser.add_argument(
+        "--speed",
+        type=float,
+        default=1.05,
+        help="Speech speed (0.7-2.0, default: 1.05)",
+    )
+    parser.add_argument(
+        "--list-voices",
+        action="store_true",
+        help="List available voice styles and exit",
+    )
+    parser.add_argument(
+        "--list-langs",
+        action="store_true",
+        help="List supported language codes and exit",
+    )
+    parser.add_argument(
+        "-v", "--verbose",
+        action="store_true",
+        help="Show generation timing info",
+    )
+    return parser
+
+
+def main() -> None:
+    parser = build_parser()
+    args = parser.parse_args()
+
+    # Handle info commands
+    if args.list_voices:
+        print("Available voices:")
+        for name, desc in SupersonicTTS.list_voices().items():
+            print(f"  {name}: {desc}")
+        return
+
+    if args.list_langs:
+        print("Supported languages:")
+        for code in SupersonicTTS.list_languages():
+            print(f"  {code}")
+        return
+
+    # Validate -o is present for synthesis
+    if not args.output:
+        parser.print_help()
+        print("\nERROR: --output/-o is required for synthesis", file=sys.stderr)
+        sys.exit(1)
+
+    # Resolve text
+    text = resolve_text(args.text, args.input)
+    if not text:
+        parser.print_help()
+        print("\nERROR: No input text provided. Pass text as argument, pipe to stdin, or use --input.", file=sys.stderr)
+        sys.exit(1)
+
+    # Synthesize
+    tts = SupersonicTTS(verbose=args.verbose)
+
+    try:
+        wav, _duration = tts.synthesize(
+            text,
+            voice=args.voice,
+            lang=args.lang,
+            steps=args.steps,
+            speed=args.speed,
+        )
+    except Exception as e:
+        print(f"ERROR: Synthesis failed: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    # Save
+    try:
+        tts.save(wav, args.output)
+    except Exception as e:
+        print(f"ERROR: Failed to save audio: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    if args.verbose:
+        print(f"Audio saved to {args.output}", file=sys.stderr)
+
+
+if __name__ == "__main__":
+    main()

supersonic_tts-0.1.0/src/supersonic_tts/core.py

@@ -0,0 +1,118 @@
+"""Core Python API for SupersonicTTS."""
+
+from __future__ import annotations
+
+import time
+from typing import Optional, Tuple
+
+import numpy as np
+
+try:
+    from supertonic import TTS as _TTS
+except ImportError:
+    _TTS = None
+
+__version__ = "0.1.0"
+
+# Available voice styles
+VOICES = {
+    "M1": "Lively, upbeat male",
+    "M2": "Deep, calm male",
+    "M3": "Authoritative male",
+    "M4": "Soft, friendly male",
+    "M5": "Warm, storytelling male",
+    "F1": "Calm, composed female",
+    "F2": "Bright, cheerful female",
+    "F3": "Professional announcer female",
+    "F4": "Crisp, confident female",
+    "F5": "Gentle, soothing female",
+}
+
+# Available languages
+LANGUAGES = [
+    "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 SupersonicTTS:
+    """High-level Python wrapper for Supertonic TTS.
+
+    Usage:
+        tts = SupersonicTTS()
+        wav, duration = tts.synthesize("Hello world", voice="F4", lang="en")
+        tts.save(wav, "output.wav")
+    """
+
+    def __init__(self, auto_download: bool = True, verbose: bool = False):
+        if _TTS is None:
+            raise ImportError(
+                "supertonic is not installed. Run: pip install supertonic"
+            )
+        self._tts = _TTS(auto_download=auto_download)
+        self._verbose = verbose
+
+    def synthesize(
+        self,
+        text: str,
+        voice: str = "M1",
+        lang: str = "en",
+        steps: int = 5,
+        speed: float = 1.05,
+    ) -> Tuple[np.ndarray, np.ndarray]:
+        """Synthesize speech from text.
+
+        Args:
+            text: Text to synthesize.
+            voice: Voice style name (M1-M5, F1-F5). Default: M1.
+            lang: Language code. Default: en.
+            steps: Synthesis quality steps. Default: 5.
+            speed: Speech speed multiplier (0.7-2.0). Default: 1.05.
+
+        Returns:
+            Tuple of (waveform, duration) where waveform has shape (1, n_samples).
+        """
+        style = self._tts.get_voice_style(voice_name=voice)
+
+        t0 = time.time()
+        wav, duration = self._tts.synthesize(
+            text,
+            voice_style=style,
+            lang=lang,
+            total_steps=steps,
+            speed=speed,
+        )
+        elapsed = time.time() - t0
+
+        if self._verbose:
+            print(
+                f"Generated {float(duration[0]):.2f}s of audio "
+                f"in {elapsed:.2f}s (voice={voice})",
+                file=__import__("sys").stderr,
+            )
+
+        return wav, duration
+
+    def save(self, waveform: np.ndarray, path: str) -> None:
+        """Save waveform to a WAV file.
+
+        Args:
+            waveform: Audio array from synthesize().
+            path: Output file path (should end in .wav).
+        """
+        self._tts.save_audio(waveform, path)
+
+    @staticmethod
+    def list_voices() -> dict:
+        """Return dict of {voice_name: description}."""
+        return dict(VOICES)
+
+    @staticmethod
+    def list_languages() -> list:
+        """Return list of supported language codes."""
+        return list(LANGUAGES)
+
+    def __repr__(self) -> str:
+        return f"SupersonicTTS(voices={len(VOICES)}, languages={len(LANGUAGES)})"