faster-tts 0.0.1__tar.gz

faster_tts-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jordi Mas i Hernàndez
+
+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.

faster_tts-0.0.1/PKG-INFO

@@ -0,0 +1,199 @@
+Metadata-Version: 2.4
+Name: faster-tts
+Version: 0.0.1
+Summary: Text-to-speech library on CPU and GPU using CTranslate2
+Author-email: Jordi Mas <jmas@softcatala.org>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/jordimas/faster_tts
+Project-URL: Repository, https://github.com/jordimas/faster_tts
+Project-URL: Documentation, https://github.com/jordimas/faster_tts/blob/main/docs/api.md
+Project-URL: Issues, https://github.com/jordimas/faster_tts/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: ctranslate2>=4.8.4
+Requires-Dist: numpy>=1.23
+Requires-Dist: tokenizers>=0.20
+Requires-Dist: huggingface-hub>=0.24
+Provides-Extra: docs
+Requires-Dist: pre-commit>=4; extra == "docs"
+Dynamic: license-file
+
+# faster_tts
+
+Text-to-speech with **Drama 3 on CPU and GPU**, powered by CTranslate2.
+Provides a Python library API and the `faster-tts` command-line interface (CLI).
+Includes model downloading and caching, sentence splitting, speaker tags, and WAV output.
+Requires CTranslate2 **4.8.4+**.
+
+## Quick start
+
+Python API:
+
+```python
+from faster_tts import Model
+
+model = Model()
+result = model.synthesize(
+    "Hello! Welcome to our application.",
+    output="hello.wav",  # Save the audio as a WAV file.
+)
+```
+
+`Model()` downloads and caches
+[`jordimas/drama-3-ct2`](https://huggingface.co/jordimas/drama-3-ct2).
+Reuse it across calls.
+
+CLI (also available as `python -m faster_tts`):
+
+```bash
+faster-tts --text "Hello!" --output hello.wav
+```
+
+Generate emotion, dialogue, and multilingual audio with the
+[sample scripts](https://github.com/jordimas/faster_tts/blob/dev/samples/README.md), or narrate a UTF-8 article:
+
+```bash
+python samples/article_voice.py article.txt --output article.wav
+```
+
+The article sample selects the device automatically. Use `--device cpu` or
+`--device cuda` to override it. Its default audio budget is 120 seconds
+(`--max-duration-s`); reaching it saves partial narration.
+
+## Models and devices
+
+```python
+model = Model("drama-3")  # Default checkpoint
+model = Model("jordimas/drama-3-ct2", revision="main", cache_dir="./models")
+model = Model("/path/to/converted-model")
+model = Model(local_files_only=True)  # Cached assets only
+
+model = Model(device="cuda", device_index=0, compute_type="float16")
+model = Model(device="cpu", compute_type="int8")
+```
+
+The default `device="auto"` selects GPU when available, otherwise CPU.
+CUDA and ROCm both use `"cuda"` with a matching CT2 build. Compute types depend
+on the build; `"default"` lets CT2 choose. Inspect settings with `model.info()`.
+Set `CT2_DRAMA_GPU_WAVEFORM=0` to decode waveforms on CPU.
+
+The CLI accepts the same model and cache options. For local models, use explicit
+paths such as `./model` to avoid interpreting missing directories as Hub IDs.
+Custom checkpoints must match the engine's layout.
+
+## Memory
+
+GPU expert caches size automatically. Set a total budget in decimal GB:
+
+```python
+model = Model(
+    device="cuda", num_workers=2,
+    engine_options={"gpu_expert_cache_gb": 12},
+)
+```
+
+This gives each worker a 6 GB cache. Use `"auto"` or `"uncapped"` instead of a
+number, or CLI `--gpu-expert-cache-gb`. Without an explicit budget,
+`CT2_DRAMA3_GPU_EXPERT_CACHE_GB` sets the per-worker limit (`0` means uncapped).
+Automatic sizing reserves at least 2 GB and 30% of free memory and fails if
+memory cannot be queried or is insufficient. Cache budgets do not cap total VRAM.
+
+When `device="auto"` selects CPU, large checkpoints can use expert memory mapping
+on Linux/macOS with `compute_type="default"` or `"float32"`. Override with
+`CT2_DRAMA3_CPU_MMAP=0` or `1`. Explicit `device="cpu"` leaves it off by default.
+Keep the checkpoint unchanged while loaded; mapping does not cap RAM usage.
+Both memory features require a supporting CT2 build.
+
+## Synthesis options and results
+
+Pass engine options through `engine_options`. Experimental `directed_spans`
+splits explicit breathing events from speech:
+
+```python
+result = model.synthesize(
+    "Set the bag down. [breathing] We can continue now.",
+    engine_options={"directed_spans": True, "max_frames": 534},
+)
+```
+
+Speech spans are capped at 256 frames and breathing events at 22, within the
+overall budget. Events use empty history and do not condition later speech.
+Listen to check voice, prosody, and event quality. CLI: `--directed-spans`.
+
+[`SynthesisResult`](https://github.com/jordimas/faster_tts/blob/dev/docs/api.md#synthesisresult) includes audio, sample rate, and
+`finish_reason`. A `"length"` result may be truncated; the CLI saves it and exits
+with status 1. `"eos"` does not guarantee complete speech.
+Enable INFO logging for `faster_tts.engines.drama3` for device and segment details.
+
+See the [API reference](https://github.com/jordimas/faster_tts/blob/dev/docs/api.md), `python -m faster_tts --help`, and
+[CT2 Drama 3 guide](https://github.com/OpenNMT/CTranslate2/blob/master/docs/guides/drama3.md)
+for options and conversion instructions.
+
+## Benchmark
+
+Drama 3 only. See [benchmark instructions](https://github.com/jordimas/faster_tts/blob/dev/benchmark/README.md) to run your own measurements.
+
+<!-- current-benchmarks -->
+### Benchmark results (2026-10-24)
+
+#### CPU — AMD EPYC 7B13 (62 GiB RAM)
+
+Test text: `Hello! Welcome to our application.`
+
+Times in the CPU table are means. RTF is compute time divided by generated audio duration; lower is better, and 1 means real-time synthesis. Loading and warmup are excluded.
+
+| Implementation | Precision | Time (s) | Audio duration (s) | RTF | Peak RAM (GiB RSS) | Status |
+| --- | --- | ---: | ---: | ---: | ---: | --- |
+| HF / PyTorch | bfloat16 | 300.9 | 2.8 | 106.2 | 44.5 | success |
+| CT2 | bfloat16 | — | — | — | — | unsupported (no matching precision) |
+| HF / PyTorch | float16 | 351.5 | 3.2 | 109.7 | 44.7 | success |
+| CT2 | float16 | — | — | — | — | unsupported (no matching precision) |
+| HF / PyTorch | int8 | — | — | — | — | unsupported (no matching precision) |
+| CT2 | int8 | 18.4 | 2.4 | 7.6 | 44.7 | success |
+| HF / PyTorch | int8_float32 | — | — | — | — | unsupported (no matching precision) |
+| CT2 | int8_float32 | 17.9 | 2.4 | 7.4 | 44.7 | success |
+| HF / PyTorch | float32 | 155.2 | 3.0 | 52.2 | 51.3 | success |
+| CT2 | float32 | 37.7 | 2.5 | 15.0 | 45.5 | success |
+
+<!-- gpu-benchmarks-ci40090377176 -->
+#### GPU — NVIDIA Tesla T4 (15 GiB VRAM)
+
+CT2 4.8.4, 8 CPU threads, one warmup and three timed runs per successful configuration.
+Same test text as above. Times are means; peak RAM is process RSS and excludes VRAM.
+Expert cache: auto (10.874 GB), except the successful float16 run (8 GB).
+
+| Implementation | Precision | Time (s) | Audio duration (s) | RTF | Peak RAM (GiB RSS) | Status |
+| --- | --- | ---: | ---: | ---: | ---: | --- |
+| CT2 | float16 | — | — | — | — | CUDA OOM during warmup |
+| CT2 | float32 | 34.5 | 2.5 | 13.8 | 34.5 | success |
+| CT2 | int8 | 27.3 | 4.3 | 6.3 | 36.6 | success |
+| CT2 | int8_float16 | 26.9 | 3.0 | 9.0 | 35.9 | success |
+| CT2 | int8_float32 | 27.2 | 4.3 | 6.3 | 36.6 | success |
+| CT2 | float16 | 37.9 | 3.7 | 10.3 | 36.0 | success |
+<!-- /gpu-benchmarks-ci40090377176 -->
+
+<!-- gpu-benchmarks-l4-ci40090377176 -->
+#### GPU — NVIDIA L4
+
+CT2 4.8.4, 8 CPU threads, a 12 GB expert cache, one warmup and one timed run per configuration.
+Same test text as above. Loading and warmup are excluded; peak RAM is process RSS and excludes VRAM.
+Single runs do not measure timing variability.
+
+| Implementation | Precision | Time (s) | Audio duration (s) | RTF | Peak RAM (GiB RSS) | Status |
+| --- | --- | ---: | ---: | ---: | ---: | --- |
+| CT2 | bfloat16 | 26.5 | 2.8 | 9.5 | 35.5 | success |
+| CT2 | float16 | 27.6 | 3.1 | 8.9 | 35.6 | success |
+| CT2 | float32 | 29.4 | 2.5 | 11.7 | 34.6 | success |
+| CT2 | int8 | 22.1 | 4.3 | 5.1 | 36.6 | success |
+| CT2 | int8_bfloat16 | 21.4 | 2.8 | 7.6 | 35.1 | success |
+| CT2 | int8_float16 | 22.8 | 3.0 | 7.7 | 35.9 | success |
+| CT2 | int8_float32 | 22.1 | 4.3 | 5.1 | 36.7 | success |
+<!-- /gpu-benchmarks-l4-ci40090377176 -->
+
+Contact: Jordi Mas <jmas@softcatala.org>

faster_tts-0.0.1/README.md

@@ -0,0 +1,173 @@
+# faster_tts
+
+Text-to-speech with **Drama 3 on CPU and GPU**, powered by CTranslate2.
+Provides a Python library API and the `faster-tts` command-line interface (CLI).
+Includes model downloading and caching, sentence splitting, speaker tags, and WAV output.
+Requires CTranslate2 **4.8.4+**.
+
+## Quick start
+
+Python API:
+
+```python
+from faster_tts import Model
+
+model = Model()
+result = model.synthesize(
+    "Hello! Welcome to our application.",
+    output="hello.wav",  # Save the audio as a WAV file.
+)
+```
+
+`Model()` downloads and caches
+[`jordimas/drama-3-ct2`](https://huggingface.co/jordimas/drama-3-ct2).
+Reuse it across calls.
+
+CLI (also available as `python -m faster_tts`):
+
+```bash
+faster-tts --text "Hello!" --output hello.wav
+```
+
+Generate emotion, dialogue, and multilingual audio with the
+[sample scripts](https://github.com/jordimas/faster_tts/blob/dev/samples/README.md), or narrate a UTF-8 article:
+
+```bash
+python samples/article_voice.py article.txt --output article.wav
+```
+
+The article sample selects the device automatically. Use `--device cpu` or
+`--device cuda` to override it. Its default audio budget is 120 seconds
+(`--max-duration-s`); reaching it saves partial narration.
+
+## Models and devices
+
+```python
+model = Model("drama-3")  # Default checkpoint
+model = Model("jordimas/drama-3-ct2", revision="main", cache_dir="./models")
+model = Model("/path/to/converted-model")
+model = Model(local_files_only=True)  # Cached assets only
+
+model = Model(device="cuda", device_index=0, compute_type="float16")
+model = Model(device="cpu", compute_type="int8")
+```
+
+The default `device="auto"` selects GPU when available, otherwise CPU.
+CUDA and ROCm both use `"cuda"` with a matching CT2 build. Compute types depend
+on the build; `"default"` lets CT2 choose. Inspect settings with `model.info()`.
+Set `CT2_DRAMA_GPU_WAVEFORM=0` to decode waveforms on CPU.
+
+The CLI accepts the same model and cache options. For local models, use explicit
+paths such as `./model` to avoid interpreting missing directories as Hub IDs.
+Custom checkpoints must match the engine's layout.
+
+## Memory
+
+GPU expert caches size automatically. Set a total budget in decimal GB:
+
+```python
+model = Model(
+    device="cuda", num_workers=2,
+    engine_options={"gpu_expert_cache_gb": 12},
+)
+```
+
+This gives each worker a 6 GB cache. Use `"auto"` or `"uncapped"` instead of a
+number, or CLI `--gpu-expert-cache-gb`. Without an explicit budget,
+`CT2_DRAMA3_GPU_EXPERT_CACHE_GB` sets the per-worker limit (`0` means uncapped).
+Automatic sizing reserves at least 2 GB and 30% of free memory and fails if
+memory cannot be queried or is insufficient. Cache budgets do not cap total VRAM.
+
+When `device="auto"` selects CPU, large checkpoints can use expert memory mapping
+on Linux/macOS with `compute_type="default"` or `"float32"`. Override with
+`CT2_DRAMA3_CPU_MMAP=0` or `1`. Explicit `device="cpu"` leaves it off by default.
+Keep the checkpoint unchanged while loaded; mapping does not cap RAM usage.
+Both memory features require a supporting CT2 build.
+
+## Synthesis options and results
+
+Pass engine options through `engine_options`. Experimental `directed_spans`
+splits explicit breathing events from speech:
+
+```python
+result = model.synthesize(
+    "Set the bag down. [breathing] We can continue now.",
+    engine_options={"directed_spans": True, "max_frames": 534},
+)
+```
+
+Speech spans are capped at 256 frames and breathing events at 22, within the
+overall budget. Events use empty history and do not condition later speech.
+Listen to check voice, prosody, and event quality. CLI: `--directed-spans`.
+
+[`SynthesisResult`](https://github.com/jordimas/faster_tts/blob/dev/docs/api.md#synthesisresult) includes audio, sample rate, and
+`finish_reason`. A `"length"` result may be truncated; the CLI saves it and exits
+with status 1. `"eos"` does not guarantee complete speech.
+Enable INFO logging for `faster_tts.engines.drama3` for device and segment details.
+
+See the [API reference](https://github.com/jordimas/faster_tts/blob/dev/docs/api.md), `python -m faster_tts --help`, and
+[CT2 Drama 3 guide](https://github.com/OpenNMT/CTranslate2/blob/master/docs/guides/drama3.md)
+for options and conversion instructions.
+
+## Benchmark
+
+Drama 3 only. See [benchmark instructions](https://github.com/jordimas/faster_tts/blob/dev/benchmark/README.md) to run your own measurements.
+
+<!-- current-benchmarks -->
+### Benchmark results (2026-10-24)
+
+#### CPU — AMD EPYC 7B13 (62 GiB RAM)
+
+Test text: `Hello! Welcome to our application.`
+
+Times in the CPU table are means. RTF is compute time divided by generated audio duration; lower is better, and 1 means real-time synthesis. Loading and warmup are excluded.
+
+| Implementation | Precision | Time (s) | Audio duration (s) | RTF | Peak RAM (GiB RSS) | Status |
+| --- | --- | ---: | ---: | ---: | ---: | --- |
+| HF / PyTorch | bfloat16 | 300.9 | 2.8 | 106.2 | 44.5 | success |
+| CT2 | bfloat16 | — | — | — | — | unsupported (no matching precision) |
+| HF / PyTorch | float16 | 351.5 | 3.2 | 109.7 | 44.7 | success |
+| CT2 | float16 | — | — | — | — | unsupported (no matching precision) |
+| HF / PyTorch | int8 | — | — | — | — | unsupported (no matching precision) |
+| CT2 | int8 | 18.4 | 2.4 | 7.6 | 44.7 | success |
+| HF / PyTorch | int8_float32 | — | — | — | — | unsupported (no matching precision) |
+| CT2 | int8_float32 | 17.9 | 2.4 | 7.4 | 44.7 | success |
+| HF / PyTorch | float32 | 155.2 | 3.0 | 52.2 | 51.3 | success |
+| CT2 | float32 | 37.7 | 2.5 | 15.0 | 45.5 | success |
+
+<!-- gpu-benchmarks-ci40090377176 -->
+#### GPU — NVIDIA Tesla T4 (15 GiB VRAM)
+
+CT2 4.8.4, 8 CPU threads, one warmup and three timed runs per successful configuration.
+Same test text as above. Times are means; peak RAM is process RSS and excludes VRAM.
+Expert cache: auto (10.874 GB), except the successful float16 run (8 GB).
+
+| Implementation | Precision | Time (s) | Audio duration (s) | RTF | Peak RAM (GiB RSS) | Status |
+| --- | --- | ---: | ---: | ---: | ---: | --- |
+| CT2 | float16 | — | — | — | — | CUDA OOM during warmup |
+| CT2 | float32 | 34.5 | 2.5 | 13.8 | 34.5 | success |
+| CT2 | int8 | 27.3 | 4.3 | 6.3 | 36.6 | success |
+| CT2 | int8_float16 | 26.9 | 3.0 | 9.0 | 35.9 | success |
+| CT2 | int8_float32 | 27.2 | 4.3 | 6.3 | 36.6 | success |
+| CT2 | float16 | 37.9 | 3.7 | 10.3 | 36.0 | success |
+<!-- /gpu-benchmarks-ci40090377176 -->
+
+<!-- gpu-benchmarks-l4-ci40090377176 -->
+#### GPU — NVIDIA L4
+
+CT2 4.8.4, 8 CPU threads, a 12 GB expert cache, one warmup and one timed run per configuration.
+Same test text as above. Loading and warmup are excluded; peak RAM is process RSS and excludes VRAM.
+Single runs do not measure timing variability.
+
+| Implementation | Precision | Time (s) | Audio duration (s) | RTF | Peak RAM (GiB RSS) | Status |
+| --- | --- | ---: | ---: | ---: | ---: | --- |
+| CT2 | bfloat16 | 26.5 | 2.8 | 9.5 | 35.5 | success |
+| CT2 | float16 | 27.6 | 3.1 | 8.9 | 35.6 | success |
+| CT2 | float32 | 29.4 | 2.5 | 11.7 | 34.6 | success |
+| CT2 | int8 | 22.1 | 4.3 | 5.1 | 36.6 | success |
+| CT2 | int8_bfloat16 | 21.4 | 2.8 | 7.6 | 35.1 | success |
+| CT2 | int8_float16 | 22.8 | 3.0 | 7.7 | 35.9 | success |
+| CT2 | int8_float32 | 22.1 | 4.3 | 5.1 | 36.7 | success |
+<!-- /gpu-benchmarks-l4-ci40090377176 -->
+
+Contact: Jordi Mas <jmas@softcatala.org>

faster_tts-0.0.1/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-0.0.1/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-0.0.1/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,
+        )