How to Load Models Using TTSModel.load_model() in Pocket‑TTS

TTSModel.load_model() is the factory method that instantiates a fully‑initialized text‑to‑speech model, downloads required weights from HuggingFace, and optionally applies int‑8 quantisation for faster CPU inference.

The load_model() class method in the kyutai-labs/pocket-tts repository serves as the primary entry point for initializing the TTSModel. Located in pocket_tts/models/tts_model.py, this method handles configuration resolution, weight downloading, and model assembly in a single call.

Understanding the TTSModel.load_model() Method Signature

The method signature defined in [pocket_tts/models/tts_model.py](https://github.com/kyutai-labs/pocket-tts/blob/main/pocket_tts/models/tts_model.py#L32-L65) accepts the following parameters:

@classmethod
def load_model(
    cls,
    language: str | None = None,
    config: str | Path | None = None,
    temp: float | int = DEFAULT_TEMPERATURE,
    lsd_decode_steps: int = DEFAULT_LSD_DECODE_STEPS,
    noise_clamp: float | int | None = DEFAULT_NOISE_CLAMP,
    eos_threshold: float = DEFAULT_EOS_THRESHOLD,
    quantize: bool = False,
) -> Self:

Key parameters:

• language – A predefined language identifier (e.g., "english", "french_24l") that maps to YAML files in pocket_tts/config/.
• config – Path to a custom YAML configuration file for experimental setups.
• temp – Sampling temperature controlling output diversity (default: 0.7).
• lsd_decode_steps – Number of Lagrangian Self‑Distillation steps affecting quality versus speed (default: 4).
• quantize – Boolean flag to enable dynamic int‑8 quantisation via apply_dynamic_int8 in pocket_tts/quantization.py.

The Internal Loading Pipeline

When you invoke TTSModel.load_model(), the method executes a five‑stage pipeline defined in lines 86‑108 of pocket_tts/models/tts_model.py:

1. Argument validation – Ensures you provide either language or config, but never both.
2. Configuration resolution – Maps the language string to a YAML file in pocket_tts/config/ (defaulting to english.yaml if neither is specified).
3. Schema validation – Parses the YAML using the Pydantic model in pocket_tts/utils/config.py via the load_config utility.
4. Model instantiation – Calls the private helper _from_pydantic_config_with_weights to construct the FlowLM and Mimi encoder/decoder, downloading weights via download_if_necessary from HuggingFace if required.
5. Optional quantisation – Applies Torch‑AO dynamic int‑8 conversion to the transformer when quantize=True, reducing memory usage by approximately 48%.

The resulting instance forces torch.set_num_threads(1) for optimal CPU performance.

Practical Code Examples for TTSModel.load_model()

Load the Default English Model

To quickly initialise the model with default settings:

from pocket_tts import TTSModel

model = TTSModel.load_model()

This defaults to language="english", resolving to pocket_tts/config/english.yaml.

Load a Specific Language Configuration

For multilingual inference, specify the language identifier:

from pocket_tts import TTSModel

model = TTSModel.load_model(language="french_24l")

This loads the configuration from pocket_tts/config/french_24l.yaml and fetches the corresponding pre‑trained weights.

Use a Custom YAML Config File

For experiments with modified hyper‑parameters, pass a path to your own config:

from pocket_tts import TTSModel
from pathlib import Path

custom_config = Path("./experiments/high_quality.yaml")
model = TTSModel.load_model(
    config=custom_config,
    temp=0.8,
    lsd_decode_steps=6
)

Enable Int‑8 Quantisation for Optimised Inference

To reduce memory footprint and increase inference speed on CPU:

from pocket_tts import TTSModel

model = TTSModel.load_model(quantize=True)

This triggers apply_dynamic_int8 from pocket_tts/quantization.py, wrapping the FlowLM transformer with dynamic int‑8 quantisation.

Combine Custom Config with Quantisation

You can mix custom configurations with quantisation for production deployments:

from pocket_tts import TTSModel

model = TTSModel.load_model(
    config="pocket_tts/config/english.yaml",
    temp=0.9,
    quantize=True
)

Critical Source Files in the Loading Process

Understanding these files helps debug loading issues:

• pocket_tts/models/tts_model.py – Contains the load_model class method and _from_pydantic_config_with_weights helper.
• pocket_tts/utils/config.py – Defines the Pydantic schema that validates YAML configurations.
• pocket_tts/config/ – Directory containing predefined language configs like english.yaml and french_24l.yaml.
• pocket_tts/quantization.py – Implements apply_dynamic_int8 for the optional quantisation step.
• pocket_tts/utils/weights_loading.py – Handles downloading and caching of FlowLM and Mimi weights from HuggingFace via download_if_necessary.

Summary

• TTSModel.load_model() is the sole entry point for model initialisation in pocket‑tts, located in pocket_tts/models/tts_model.py.
• You must provide either a language identifier or a config path, but never both.
• The method automatically downloads weights from HuggingFace and supports dynamic int‑8 quantisation via the quantize parameter.
• Configuration files follow the Pydantic schema defined in pocket_tts/utils/config.py and reside in pocket_tts/config/.
• For CPU inference, the model automatically optimises thread usage, and int‑8 quantisation can reduce memory usage by ~48% while improving speed.

Frequently Asked Questions

What is the difference between using language and config in TTSModel.load_model()?

The language parameter accepts a string (e.g., "english") that maps to a predefined YAML file in pocket_tts/config/, while config accepts a file path to a custom YAML configuration. You cannot use both simultaneously; if language is omitted and config is not provided, it defaults to DEFAULT_LANGUAGE ("english").

How does int‑8 quantisation affect model performance?

When quantize=True, the method calls apply_dynamic_int8 from pocket_tts/quantization.py to wrap the FlowLM transformer with Torch‑AO dynamic int‑8 conversion. This reduces memory consumption by approximately 48% and increases inference speed by roughly 27% on CPU, with minimal impact on audio quality.

Where are the pre‑trained weights downloaded from?

The _from_pydantic_config_with_weights helper function downloads weights from the HuggingFace Hub using utilities in pocket_tts/utils/weights_loading.py. Files are cached locally after the first download, so subsequent initialisations load from disk.

Can I use TTSModel.load_model() on GPU?

The current implementation in pocket_tts/models/tts_model.py forces torch.set_num_threads(1) and is optimised for CPU inference. While the underlying PyTorch tensors could technically reside on GPU, the load_model() method and associated helpers are designed specifically for CPU‑based text‑to‑speech generation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}