faster-tts 0.0.1__py3-none-any.whl

faster_tts/__init__.py

@@ -0,0 +1,9 @@
+"""CTranslate2 text-to-speech through the public Model and SynthesisResult API.
+
+See README.md for setup and examples. Engine-specific helpers are internal.
+Importing the package does not download checkpoints or initialize a model.
+"""
+
+from .model import Model, SynthesisResult
+
+__all__ = ["Model", "SynthesisResult"]

faster_tts/__main__.py

@@ -0,0 +1,121 @@
+"""Speech synthesis: python -m faster_tts [MODEL] --text TEXT --output out.wav.
+
+MODEL defaults to jordimas/drama-3-ct2. Accepts drama-3, a converted Hub repository
+ID (optionally prefixed with hf://), or a local converted directory.
+"""
+
+import argparse
+import time
+from pathlib import Path
+
+from .cache import DEFAULT_MODEL
+from .model import Model, _save_wav
+
+
+def _cache_budget(value):
+    if value in ("auto", "uncapped"):
+        return value
+    try:
+        from .memory import validate_cache_budget
+
+        result = float(value)
+        validate_cache_budget(result)
+        return result
+    except ValueError as exc:
+        raise argparse.ArgumentTypeError(
+            'expected "auto", "uncapped", or a finite positive GB budget'
+        ) from exc
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "model",
+        nargs="?",
+        default=DEFAULT_MODEL,
+        help="model name, Hub repository ID, or local directory (default: %(default)s)",
+    )
+    parser.add_argument("--revision", help="Hub revision; prefer a pinned commit")
+    parser.add_argument(
+        "--cache-dir", type=Path, help="Hugging Face snapshot cache directory"
+    )
+    parser.add_argument(
+        "--local-files-only",
+        action="store_true",
+        help="resolve Hub assets only from the local cache",
+    )
+    parser.add_argument("--text", required=True)
+    parser.add_argument("--output", required=True, type=Path)
+    parser.add_argument("--max-duration-s", type=float, default=24.0)
+    parser.add_argument("--threads", type=int, default=8)
+    parser.add_argument("--device", choices=("cpu", "cuda", "auto"), default="cpu")
+    parser.add_argument("--device-index", type=int, default=0)
+    parser.add_argument("--compute-type", default="default")
+    parser.add_argument(
+        "--gpu-expert-cache-gb",
+        type=_cache_budget,
+        help='GPU expert cache: decimal GB, "auto", or "uncapped"; defaults to environment or auto',
+    )
+    parser.add_argument("--temperature", type=float, default=0.7)
+    parser.add_argument("--top-k", type=int, default=30)
+    parser.add_argument("--top-p", type=float, default=0.7)
+    parser.add_argument("--seed", type=int, default=0)
+    parser.add_argument(
+        "--no-split-sentences",
+        action="store_true",
+        help="diagnostic single-pass generation",
+    )
+    parser.add_argument(
+        "--greedy",
+        action="store_true",
+        help="diagnostic greedy decoding instead of sampling",
+    )
+    parser.add_argument(
+        "--directed-spans",
+        action="store_true",
+        help="opt-in Drama 3 cue/turn splitting and bounded breathing events",
+    )
+    args = parser.parse_args()
+    if args.directed_spans and args.no_split_sentences:
+        parser.error("--directed-spans requires sentence splitting")
+    engine_options = {}
+    if args.gpu_expert_cache_gb is not None:
+        engine_options["gpu_expert_cache_gb"] = args.gpu_expert_cache_gb
+    model = Model(
+        args.model,
+        intra_threads=args.threads,
+        compute_type=args.compute_type,
+        device=args.device,
+        device_index=args.device_index,
+        revision=args.revision,
+        cache_dir=args.cache_dir,
+        local_files_only=args.local_files_only,
+        engine_options=engine_options or None,
+    )
+    started = time.perf_counter()
+    result = model.synthesize(
+        args.text,
+        max_duration_s=args.max_duration_s,
+        temperature=args.temperature,
+        top_k=args.top_k,
+        top_p=args.top_p,
+        seed=args.seed,
+        greedy=args.greedy,
+        split_sentences=not args.no_split_sentences,
+        **({"engine_options": {"directed_spans": True}} if args.directed_spans else {}),
+    )
+    inference_seconds = time.perf_counter() - started
+    _save_wav(result, args.output)
+    print(
+        f"Saved {result.audio.size / result.sample_rate:.3f}s to {args.output}; "
+        f"finish_reason={result.finish_reason}; decoding={'greedy' if args.greedy else 'sampled'}"
+    )
+    print(f"Inference time (excluding model loading): {inference_seconds:.3f}s")
+    if result.finish_reason != "eos":
+        raise SystemExit(
+            "Incomplete synthesis: frame limit reached; the saved audio may be truncated."
+        )
+
+
+if __name__ == "__main__":
+    main()

faster_tts/base.py

@@ -0,0 +1,82 @@
+"""Engine registration and shared helpers; engine-specific code lives in engines/."""
+
+from copy import deepcopy
+from importlib import import_module
+
+import numpy as np
+
+_ENGINE_REGISTRY: dict[str, type] = {}
+
+
+def register_engine(model_type):
+    """Decorator that registers a :class:`BaseModel` subclass by ``model_type``.
+
+    ``model_type`` is matched against the ``model_type`` field of the converted
+    checkpoint's ``config.json``. Re-registering an existing key replaces the
+    previous binding so engines can be reloaded during tests.
+    """
+    if not isinstance(model_type, str) or not model_type:
+        raise ValueError("model_type must be a nonempty string")
+
+    def decorator(cls):
+        _ENGINE_REGISTRY[model_type] = cls
+        cls.engine_model_type = model_type
+        return cls
+
+    return decorator
+
+
+def get_engine_class(model_type):
+    """Look up the engine class previously registered for ``model_type``."""
+    import_module(".engines.drama3", __package__)
+    if not isinstance(model_type, str):
+        raise ValueError("Converted checkpoint must specify a string model_type")  # noqa: TRY004 - invalid checkpoint data
+    try:
+        return _ENGINE_REGISTRY[model_type]
+    except KeyError:
+        raise ValueError(
+            f"No CT2 TTS engine registered for model_type={model_type!r}; "
+            f"known engines: {sorted(_ENGINE_REGISTRY)}"
+        ) from None
+
+
+def _positive_int(value, name):
+    if (
+        not isinstance(value, int)
+        or isinstance(value, bool)
+        or not 1 <= value <= np.iinfo(np.int32).max
+    ):
+        raise ValueError(f"{name} must be a positive int32 integer")
+
+
+class BaseModel:
+    """Shared surface across CT2 TTS engines.
+
+    Subclasses set ``self._info`` in their constructor and implement
+    ``validate_checkpoint(directory, config)`` and ``synthesize``. Constructors
+    receive a resolved directory, checkpoint metadata, and the public loader's
+    settings. Engine-specific knobs are declared in ``init_options`` and
+    ``synthesize_options`` as frozensets of accepted keys; the dispatcher
+    validates ``engine_options`` against these and raises ``ValueError`` on
+    unknown keys. Return a SynthesisResult with engine-specific codec
+    dimensions. Declare supported features in ``capabilities``. The base class
+    adds engine identity and capabilities to an independent copy of ``_info``.
+    """
+
+    engine_model_type: str
+    capabilities = ("synthesis",)
+    init_options: frozenset = frozenset()
+    synthesize_options: frozenset = frozenset()
+
+    def info(self):
+        """Copy engine metadata and add its registered identity and capabilities.
+
+        Returns:
+            dict: Independent deep copy of `_info`, plus `engine` and
+                `capabilities`. Public fields are documented in `Model.info`.
+        """
+        return dict(
+            deepcopy(self._info),
+            engine=self.engine_model_type,
+            capabilities=self.capabilities,
+        )

faster_tts/cache.py

@@ -0,0 +1,123 @@
+"""Resolve local converted models, model names, or Hugging Face snapshots.
+
+Repository IDs accept an optional ``hf://`` prefix. Explicit local paths never
+trigger downloads. This module does not load an inference engine.
+"""
+
+import json
+import os
+import re
+from importlib import import_module
+from pathlib import Path
+
+from .base import get_engine_class
+
+DEFAULT_MODEL = "jordimas/drama-3-ct2"
+MODEL_ALIASES = {"drama-3": DEFAULT_MODEL}
+
+
+ALLOW_PATTERNS = (
+    "model.bin",
+    "config.json",
+    "tokenizer.json",
+    "tokenizer_config.json",
+    "special_tokens_map.json",
+    "conversion.json",
+    "LICENSE",
+    "LICENSE.*",
+    "LICENCE",
+    "LICENCE.*",
+    "NOTICE",
+    "NOTICE.*",
+    "README.md",
+)
+
+
+def _validate(directory):
+    directory = Path(directory).expanduser().resolve()
+    for name in ("model.bin", "config.json"):
+        path = directory / name
+        if not path.is_file() or path.stat().st_size == 0:
+            raise FileNotFoundError(
+                f"Missing or empty converted model asset: {path}. "
+                "Provide a complete CTranslate2-converted checkpoint; official "
+                "safetensors and GGUF checkpoints cannot be loaded directly."
+            )
+    try:
+        config = json.loads((directory / "config.json").read_text(encoding="utf-8"))
+    except (ValueError, UnicodeError) as exc:
+        raise ValueError(
+            f"Invalid converted model config: {directory / 'config.json'}"
+        ) from exc
+    if not isinstance(config, dict):
+        raise ValueError(f"Invalid converted model config: {directory / 'config.json'}")  # noqa: TRY004 - invalid checkpoint data
+    engine_class = get_engine_class(config.get("model_type"))
+    engine_class.validate_checkpoint(directory, config)
+    return directory
+
+
+def resolve_model_path(
+    model=DEFAULT_MODEL, *, revision=None, cache_dir=None, local_files_only=False
+):
+    """Return a validated local converted checkpoint directory as a ``Path``.
+
+    Accept a local directory, ``drama-3``, or a Hub repository ID (with optional
+    ``hf://`` prefix). Existing directories take precedence. Path objects and
+    explicit paths (absolute, ./, ../, ~/) stay local. revision, cache_dir and
+    local_files_only pass to snapshot_download; no fallback model is loaded.
+
+    Validation checks required nonempty assets and the supported config envelope,
+    not the full binary payload, tokenizer vocabulary, or numerical correctness;
+    the matching native loader performs those checks when loading the model.
+    """
+    if not isinstance(model, (str, os.PathLike)):
+        raise TypeError(
+            "model must be a local path, model name, or organization/repository string"
+        )
+    if not isinstance(local_files_only, bool):
+        raise TypeError("local_files_only must be a bool")
+    if revision is not None and (not isinstance(revision, str) or not revision.strip()):
+        raise ValueError("revision must be a nonempty string when provided")
+    local = Path(model).expanduser()
+    if local.exists():
+        if not local.is_dir():
+            raise NotADirectoryError(f"Model path is not a directory: {local}")
+        return _validate(local)
+    if not isinstance(model, str) or model.startswith(("/", "./", "../", "~/")):
+        raise FileNotFoundError(f"Local model directory does not exist: {local}")
+    explicit_hub = model.startswith("hf://")
+    repository = (
+        model[len("hf://") :] if explicit_hub else MODEL_ALIASES.get(model, model)
+    )
+    if not re.fullmatch(
+        r"[A-Za-z0-9][A-Za-z0-9_.-]*/[A-Za-z0-9][A-Za-z0-9_.-]*", repository
+    ):
+        raise ValueError(
+            "Use a known model name (drama-3), organization/repository "
+            "with revision supplied separately, or an explicit local path"
+        )
+    try:
+        hub = import_module("huggingface_hub")
+    except ImportError as exc:
+        raise ImportError(
+            "Hub model resolution requires the huggingface-hub package. "
+            "Install it with: pip install huggingface-hub ; or provide an existing local converted model."
+        ) from exc
+    try:
+        snapshot = hub.snapshot_download(
+            repo_id=repository,
+            revision=revision,
+            cache_dir=os.fspath(Path(cache_dir).expanduser())
+            if cache_dir is not None
+            else None,
+            local_files_only=local_files_only,
+            allow_patterns=list(ALLOW_PATTERNS),
+        )
+    except Exception as exc:
+        mode = "local cache" if local_files_only else "Hugging Face Hub"
+        raise RuntimeError(
+            f"Cannot resolve converted model {model} from {mode} "
+            f"at revision {revision or 'default'}. Check the repository, access, "
+            "revision and cache availability; no fallback model was loaded."
+        ) from exc
+    return _validate(snapshot)

faster_tts/chunking.py

@@ -0,0 +1,252 @@
+"""Conservative Unicode sentence and clause boundaries for synthesis."""
+
+import re
+from itertools import pairwise
+
+_ABBREVIATIONS = frozenset(
+    (
+        "mr",
+        "mrs",
+        "ms",
+        "dr",
+        "dra",
+        "sr",
+        "sra",
+        "srta",
+        "prof",
+        "jr",
+        "vs",
+        "etc",
+        "approx",
+        "no",
+        "núm",
+        "ud",
+        "uds",
+    )
+)
+# Period abbreviations are inherently ambiguous without language context. Keep
+# familiar forms and short initials together; unknown forms remain heuristic.
+_ABBREVIATIONS = _ABBREVIATIONS | frozenset(
+    (
+        "mme",
+        "mmes",
+        "mlle",
+        "mlles",
+        "ém",
+        "av",
+        "bd",
+        "bzw",
+        "ca",
+        "dipl",
+        "ing",
+        "nr",
+        "str",
+        "vgl",
+        "z.b",
+        "d.h",
+        "sig",
+        "sig.ra",
+        "dott",
+        "dott.ssa",
+        "ecc",
+        "ex",
+        "p.ex",
+        "sra",
+        "sta",
+        "sant",
+        "pàg",
+        "pág",
+        "tel",
+        "г",
+        "гг",
+        "ул",
+        "д",
+        "им",
+        "рис",
+        "стр",
+        "т.д",
+        "т.п",
+    )
+)
+_CLOSERS = r"[\"\'”’»）)\]}」』】》]*"
+# These marks can end sentences without whitespace (e.g. Chinese and Japanese).
+_TERMINALS = "。！？؟۔।॥።፧፨։။᙮꓿"
+_END = re.compile(
+    r"[.!?]+" + _CLOSERS + r"(?=\s|$)|[" + _TERMINALS + r"]+" + _CLOSERS + r"|\n+"
+)
+_CLAUSE = re.compile(r"[,;:](?=\s)|[，、；：،؛]")
+
+
+def split_text(text):
+    """Keep abbreviations together and preserve a single leading speaker tag.
+
+    This is a Unicode punctuation heuristic, not a linguistic parser. Text in
+    any language is accepted; text without clear boundaries stays together.
+    Long sentences group at clause punctuation with a 200-character soft target.
+    Sentence-attached bracket cues are kept when every sentence has its own cue.
+    Other markup stays intact. Spoken spans retain their punctuation and internal
+    whitespace; a leading speaker tag is repeated on each generated chunk.
+    """
+    if not isinstance(text, str):
+        raise TypeError("text must be a string")
+    original = text
+    speaker = re.match(r"[ \t\r\n]*(<\|speaker:(?:[0-9]|1[0-5])\|>)[ \t\r\n]*", text)
+    if speaker:
+        text = text[speaker.end() :]
+    if any(mark in text for mark in ("<", ">")):
+        return [original]
+    cued = "[" in text or "]" in text
+    boundaries = text
+    if cued:
+        if speaker:
+            return [original]
+        boundaries = re.sub(r"\[[^\[\]<>]+\]", lambda match: " " * len(match[0]), text)
+        if "[" in boundaries or "]" in boundaries:
+            return [original]
+    chunks, start = [], 0
+    for match in _END.finditer(boundaries):
+        if match.group().startswith("."):
+            prefix = boundaries[: match.start()]
+            word = re.search(r"([\w.]+)$", prefix)
+            word = word.group(1) if word else ""
+            if (
+                word.casefold() in _ABBREVIATIONS
+                or len(word) == 1
+                and word.isalpha()
+                or re.fullmatch(r"(?:[^\W\d_]\.)+[^\W\d_]", word)
+            ):
+                continue
+        chunk = text[start : match.end()].strip()
+        if chunk:
+            chunks.append(chunk)
+        start = match.end()
+    tail = text[start:].strip()
+    if tail:
+        chunks.append(tail)
+    if cued:
+        # A cue's scope across sentences is unspecified: only split when each
+        # sentence carries exactly one leading cue of its own.
+        if not all(
+            re.match(r"^\[[^\[\]<>]+\]\s+[^\[\]]", chunk) and chunk.count("[") == 1
+            for chunk in chunks
+        ):
+            return [original]
+        return chunks if len(chunks) > 1 else [original]
+    bounded = []
+    for chunk in chunks:
+        start = previous = 0
+        ends = [match.end() for match in _CLAUSE.finditer(chunk)] + [len(chunk)]
+        for end in ends:
+            if end - start > 200 and previous > start:
+                bounded.append(chunk[start:previous].strip())
+                start = previous
+            previous = end
+        bounded.append(chunk[start:].strip())
+    chunks = bounded
+    if speaker:
+        return (
+            [speaker[1] + " " + chunk for chunk in chunks]
+            if len(chunks) > 1
+            else [original]
+        )
+    return chunks or [text]
+
+
+_CUE = re.compile(r"\[[^\[\]<>\n]+\]")
+_SPEAKER = re.compile(r"<\|speaker:(?:[0-9]|1[0-5])\|>")
+_BREATH = re.compile(r"\[breathing\]", re.IGNORECASE)
+_TERMINAL = re.compile(r"[.!?" + _TERMINALS + r"]" + _CLOSERS + r"$")
+
+
+def _terminal_boundary(text):
+    if "\n" in text[len(text.rstrip()) :]:
+        return True
+    value = text.rstrip()
+    terminal = _TERMINAL.search(value)
+    if terminal is None:
+        return False
+    if value[terminal.start()] == ".":
+        word = re.search(r"([\w.]+)$", value[: terminal.start()])
+        word = word[1] if word else ""
+        if (
+            word.casefold() in _ABBREVIATIONS
+            or len(word) == 1
+            and word.isalpha()
+            or re.fullmatch(r"(?:[^\W\d_]\.)+[^\W\d_]", word)
+        ):
+            return False
+    return True
+
+
+def _directed_chunks(text):
+    # Retain ambiguous scopes and malformed directions as a single span.
+    cues = list(_CUE.finditer(text))
+    masked = _CUE.sub("", text)
+    if "<" in text or ">" in text or "[" in masked or "]" in masked:
+        return [text]
+    if not cues:
+        return split_text(text)
+    prefix = text[: cues[0].start()]
+    if prefix.strip() and (
+        not any(c.isalnum() for c in prefix) or not _terminal_boundary(prefix)
+    ):
+        return [text]
+    if len(cues) < 2 and not prefix.strip():
+        return split_text(text)
+    for index, cue in enumerate(cues):
+        end = cues[index + 1].start() if index + 1 < len(cues) else len(text)
+        spoken = text[cue.end() : end]
+        if (
+            not any(c.isalpha() for c in cue[0][1:-1])
+            or not any(c.isalnum() for c in spoken)
+            or index + 1 < len(cues)
+            and not _terminal_boundary(spoken)
+        ):
+            return [text]
+    starts = [c.start() for c in cues] + [len(text)]
+    return ([prefix.strip()] if prefix.strip() else []) + [
+        text[a:b].strip() for a, b in pairwise(starts)
+    ]
+
+
+def directed_segments(text):
+    """Plan opt-in speech/event spans, retaining ambiguous markup intact.
+
+    Only explicit breathing between complete speech clauses is an event.
+    Speaker turns keep their original tag; cue scopes are never inferred.
+    Returns a list of `(kind, text)` pairs without generating audio.
+    """
+    if not isinstance(text, str):
+        raise TypeError("text must be a string")
+    # Unknown angle markup must be validated by the prompt builder unchanged.
+    if "<" in _SPEAKER.sub("", text) or ">" in _SPEAKER.sub("", text):
+        return [("speech", text)]
+    turns = [
+        t.strip()
+        for t in re.split(r"(?=<\|speaker:(?:[0-9]|1[0-5])\|>)", text)
+        if t.strip()
+    ]
+    segments = []
+    for turn in turns:
+        leading = _SPEAKER.match(turn)
+        tag = leading[0] + " " if leading else ""
+        body = turn[leading.end() :].strip() if leading else turn
+        events = list(_BREATH.finditer(body))
+        if events:
+            masked = _CUE.sub("", body)
+            clauses = _BREATH.split(body)
+            if (
+                "[" not in masked
+                and "]" not in masked
+                and all(
+                    any(c.isalnum() for c in _CUE.sub("", clause)) for clause in clauses
+                )
+                and all(_terminal_boundary(clause) for clause in clauses[:-1])
+            ):
+                for index, clause in enumerate(clauses):
+                    segments.append(("speech", tag + clause.strip()))
+                    if index < len(events):
+                        segments.append(("event", tag + events[index][0]))
+                continue
+        segments.extend(("speech", tag + chunk) for chunk in _directed_chunks(body))
+    return segments or [("speech", text)]

faster_tts/engines/__init__.py

@@ -0,0 +1 @@
+"""Internal model engines; public calls go through faster_tts.Model."""