superclonica-cpu 0.6.25__py3-none-any.whl

superclonica/__init__.py

@@ -0,0 +1,5 @@
+"""Superclonica: Supertonic 3 speech with chat-ready text cleanup, learned finishing and fast inference."""
+from .engine import Superclonica
+
+__all__ = ["Superclonica", "__version__"]
+__version__ = "0.6.25"

superclonica/__main__.py

@@ -0,0 +1,59 @@
+"""Command line: superclonica --text "Hello." --voice F3 --lang en --output hello.wav"""
+import argparse
+import json
+from pathlib import Path
+
+
+def main(argv=None):
+    from . import __version__
+    p = argparse.ArgumentParser(prog='superclonica', description='Superclonica text to speech (Supertonic 3)')
+    p.add_argument('--version', action='version', version=f'%(prog)s {__version__}')
+    source = p.add_mutually_exclusive_group(required=True)
+    source.add_argument('--text')
+    source.add_argument('--text-file', type=Path)
+    p.add_argument('--output', type=Path, required=True)
+    p.add_argument('--voice', default='M1', help='M1..M5, F1..F5 or a voice-style JSON file')
+    p.add_argument('--lang', default='en')
+    p.add_argument('--seed', type=int)
+    p.add_argument('--model-dir', type=Path, help='an existing Supertonic 3 copy (default: download once)')
+    p.add_argument('--steps', type=int, help='model steps (default 8)')
+    p.add_argument('--speed', type=float, default=1.05)
+    p.add_argument('--device', choices=['auto', 'cpu', 'cuda'], default='auto')
+    p.add_argument('--device-id', type=int, default=0)
+    p.add_argument('--threads', type=int, help='CPU threads (default: one per physical core)')
+    p.add_argument('--lanes', type=int, default=1, help='parallel model copies for the pieces of a long text')
+    p.add_argument('--gpu-memory-mb', type=int, default=1024, help='CUDA arena limit per model session')
+    p.add_argument('--cuda-graph', choices=('auto', 'on', 'off'), default='auto',
+                   help='auto = when there is GPU memory and a start-up check shows they are faster here')
+    p.add_argument('--effect', choices=['auto', 'off'], default='auto', help='ending effects (cleanup always runs)')
+    p.add_argument('--normalize', action='store_true', help='loudness -18 LUFS')
+    p.add_argument('--no-denoise', action='store_true', help='keep the model hiss and pause residue')
+    p.add_argument('--no-chunking', action='store_true')
+    p.add_argument('--no-numbers', action='store_true', help='do not spell digits as words')
+    p.add_argument('--no-slang', action='store_true', help='do not write out chat shorthand ("гг вп", "pls", "xD")')
+    p.add_argument('--keep-silence', action='store_true', help="keep the model's silence before and after the phrase")
+    p.add_argument('--report', type=Path, help='write a JSON report of the synthesis')
+    a = p.parse_args(argv)
+    if a.threads is not None and a.threads < 1:
+        p.error('--threads must be positive')
+    if not 1 <= a.lanes <= 8:
+        p.error('--lanes must be from 1 to 8')
+    text = a.text if a.text is not None else a.text_file.read_text('utf-8-sig')
+    from . import Superclonica
+    tts = Superclonica(model_dir=a.model_dir, total_steps=a.steps, speed=a.speed, device=a.device,
+                       device_id=a.device_id, threads=a.threads, lanes=a.lanes, gpu_memory_mb=a.gpu_memory_mb,
+                       cuda_graph={'auto': 'auto', 'on': True, 'off': False}[a.cuda_graph],
+                       chunking=not a.no_chunking, numbers=not a.no_numbers, denoise=not a.no_denoise,
+                       trim_silence=not a.keep_silence, slang=not a.no_slang)
+    wave, sr, report = tts.synthesize(text, a.voice, a.lang, seed=a.seed, effect=a.effect,
+                                      normalize=a.normalize, return_report=True)
+    a.output.parent.mkdir(parents=True, exist_ok=True)
+    tts.save(a.output, wave)
+    if a.report:
+        a.report.parent.mkdir(parents=True, exist_ok=True)
+        a.report.write_text(json.dumps(report, ensure_ascii=False, indent=2, default=str), 'utf-8')
+    print(str(a.output))
+
+
+if __name__ == '__main__':
+    main()

superclonica/_supertonic/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Supertone Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

superclonica/_supertonic/__init__.py

@@ -0,0 +1,3 @@
+from .pipeline import TTS
+from .core import Style, UnicodeProcessor
+from .config import *

superclonica/_supertonic/config.py

@@ -0,0 +1,247 @@
+"""Configuration and constants for Supertonic TTS package.
+
+This module centralizes all configuration values, magic numbers, and default
+settings used throughout the package.
+"""
+
+import logging
+import os
+from pathlib import Path
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+# Available models
+AVAILABLE_MODELS = ["supertonic", "supertonic-2", "supertonic-3"]
+DEFAULT_MODEL = "supertonic-3"
+
+# Model configuration mapping.
+#
+# `revision` pins the HuggingFace Hub commit each Supertonic release was
+# tested against. Pinning by SHA (instead of `"main"`) keeps a `pip install`
+# of a given package version reproducible even if the HF repo later
+# changes. To upgrade the model, bump the SHA here and ship a new package
+# release. Power users can still override with the
+# `SUPERTONIC_MODEL_REVISION` environment variable.
+MODEL_CONFIGS = {
+    "supertonic": {
+        "repo": "Supertone/supertonic",
+        "cache_dir": "supertonic",
+        "multilingual": False,
+        "revision": "b6856d033f622c63ea29441795be266a1133e227",
+    },
+    "supertonic-2": {
+        "repo": "Supertone/supertonic-2",
+        "cache_dir": "supertonic2",
+        "multilingual": True,
+        "revision": "75e6727618a02f323c720cba9478152d4bc16ca4",
+    },
+    "supertonic-3": {
+        "repo": "Supertone/supertonic-3",
+        "cache_dir": "supertonic3",
+        "multilingual": True,
+        "revision": "724fb5abbf5502583fb520898d45929e62f02c0b",
+    },
+}
+
+# Default model settings (can be overridden by environment variables)
+DEFAULT_MODEL_REPO = os.getenv("SUPERTONIC_MODEL_REPO", MODEL_CONFIGS[DEFAULT_MODEL]["repo"])
+# ``SUPERTONIC_CACHE_DIR`` is intentionally not snapshotted to a module-level
+# constant here — it is consulted at call time inside
+# :func:`get_model_cache_dir` so the override is honored on every code path
+# (notably ``TTS(model="…")``, the default and most common entry) and
+# late-set env vars (test fixtures, late configuration) take effect.
+# Optional revision override. When unset (the common case), each model is
+# downloaded at its pinned SHA from `MODEL_CONFIGS`. When set, the override
+# applies to every model — primarily a debugging / development knob.
+MODEL_REVISION_ENV_OVERRIDE = os.getenv("SUPERTONIC_MODEL_REVISION")
+
+
+def get_model_config(model_name: str) -> dict:
+    """Get configuration for a specific model.
+
+    Args:
+        model_name: Model name (one of ``AVAILABLE_MODELS``)
+
+    Returns:
+        Dictionary with model configuration (repo, cache_dir, multilingual)
+
+    Raises:
+        ValueError: If model_name is not valid
+    """
+    if model_name not in MODEL_CONFIGS:
+        raise ValueError(
+            f"Invalid model: '{model_name}'. " f"Available models: {', '.join(AVAILABLE_MODELS)}"
+        )
+    return MODEL_CONFIGS[model_name]
+
+
+def get_model_cache_dir(model_name: str) -> Path:
+    """Get cache directory for a specific model.
+
+    ``$SUPERTONIC_CACHE_DIR`` overrides the directory for *every* model when
+    set — matching the documented contract and the historical
+    ``DEFAULT_CACHE_DIR`` spelling. Users running two models from the same
+    process and wanting them separated should leave the env var unset (each
+    model then falls back to its own ``~/.cache/<cache_dir>``).
+
+    Args:
+        model_name: Model name (one of ``AVAILABLE_MODELS``)
+
+    Returns:
+        Path to the model's cache directory
+    """
+    env = os.environ.get("SUPERTONIC_CACHE_DIR")
+    if env:
+        return Path(env).expanduser()
+    config = get_model_config(model_name)
+    return Path.home() / ".cache" / config["cache_dir"]
+
+
+def get_model_repo(model_name: str) -> str:
+    """Get HuggingFace repo ID for a specific model.
+
+    Args:
+        model_name: Model name (one of ``AVAILABLE_MODELS``)
+
+    Returns:
+        HuggingFace repository ID
+    """
+    config = get_model_config(model_name)
+    return config["repo"]
+
+
+def get_model_revision(model_name: str) -> str:
+    """Get the HuggingFace Hub revision to download for a model.
+
+    Priority: ``SUPERTONIC_MODEL_REVISION`` env var (if set) → the
+    per-model pinned SHA in ``MODEL_CONFIGS``. Pinning by SHA keeps a
+    given package version reproducible across HF Hub updates.
+
+    Args:
+        model_name: Model name (one of ``AVAILABLE_MODELS``)
+
+    Returns:
+        Commit SHA (or whatever ref the env override points at).
+    """
+    if MODEL_REVISION_ENV_OVERRIDE:
+        return MODEL_REVISION_ENV_OVERRIDE
+    return get_model_config(model_name)["revision"]
+
+
+def is_multilingual_model(model_name: str) -> bool:
+    """Check if a model supports multilingual synthesis.
+
+    Args:
+        model_name: Model name (one of ``AVAILABLE_MODELS``)
+
+    Returns:
+        True if model supports multiple languages
+    """
+    config = get_model_config(model_name)
+    return config["multilingual"]
+
+
+# Model paths
+ONNX_DIR = Path("onnx")
+VOICE_STYLES_DIR = Path("voice_styles")
+
+CFG_REL_PATH = ONNX_DIR / "tts.json"
+UNICODE_INDEXER_REL_PATH = ONNX_DIR / "unicode_indexer.json"
+DP_ONNX_REL_PATH = ONNX_DIR / "duration_predictor.onnx"
+TEXT_ENC_ONNX_REL_PATH = ONNX_DIR / "text_encoder.onnx"
+VECTOR_EST_ONNX_REL_PATH = ONNX_DIR / "vector_estimator.onnx"
+VOCODER_ONNX_REL_PATH = ONNX_DIR / "vocoder.onnx"
+
+# Language configuration (multilingual support)
+# supertonic-3 supports 31 languages plus the special "na" fallback for unknown.
+# supertonic-2 supports a subset (en, ko, es, pt, fr) — language validation
+# only enforces membership in this list; mismatches between a model and a
+# language outside its training set are not blocked here.
+SUPPORTED_LANGUAGES = [
+    "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
+]
+# Special fallback code for unknown / unsupported language.
+# Wraps text with the <na>...</na> token so the model can still synthesize.
+UNKNOWN_LANGUAGE = "na"
+AVAILABLE_LANGUAGES = SUPPORTED_LANGUAGES + [UNKNOWN_LANGUAGE]
+DEFAULT_LANGUAGE = "en"
+
+# TTS parameters - defaults
+DEFAULT_TOTAL_STEPS = 8
+DEFAULT_SPEED = 1.05
+DEFAULT_MAX_CHUNK_LENGTH = 300
+DEFAULT_MAX_CHUNK_LENGTH_KO = 120  # Korean requires shorter chunks
+DEFAULT_SILENCE_DURATION = 0.3  # seconds
+
+# TTS parameters - constraints
+MIN_SPEED = 0.7
+MAX_SPEED = 2.0
+MIN_TOTAL_STEPS = 1
+MAX_TOTAL_STEPS = 100
+
+# ONNX Runtime configuration
+# TODO: Add parsing of SUPERTONIC_ONNX_PROVIDERS environment variable
+DEFAULT_ONNX_PROVIDERS = ["CPUExecutionProvider"]  # GPU support can be added by extending this list
+
+
+def _parse_env_int(env_var: str, default: Optional[int] = None) -> Optional[int]:
+    """Parse integer from environment variable with validation.
+
+    Args:
+        env_var: Environment variable name
+        default: Default value if not set or invalid
+
+    Returns:
+        Parsed integer or default value
+    """
+    value = os.getenv(env_var)
+    if value is None:
+        return default
+    try:
+        return int(value)
+    except ValueError:
+        logger.warning(f"Invalid value for {env_var}: '{value}'. Using default: {default}")
+        return default
+
+
+# Thread configuration - None means let ONNX Runtime decide automatically
+DEFAULT_INTRA_OP_NUM_THREADS = _parse_env_int("SUPERTONIC_INTRA_OP_THREADS")
+DEFAULT_INTER_OP_NUM_THREADS = _parse_env_int("SUPERTONIC_INTER_OP_THREADS")
+
+# Text processing
+MAX_TEXT_LENGTH = 100_000  # Maximum characters per single synthesis call
+
+# Logging configuration
+LOG_FORMAT = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+LOG_LEVEL = os.getenv("SUPERTONIC_LOG_LEVEL", "INFO")