Struct ModelFiles 

pub struct ModelFiles {
    pub config: Option<ModelAsset>,
    pub tokenizer: Option<ModelAsset>,
    pub weights: Vec<ModelAsset>,
    pub voices_dir: Option<ModelAssetDir>,
    pub speech_tokenizer_weights: Vec<ModelAsset>,
    pub speech_tokenizer_config: Option<ModelAsset>,
    pub generation_config: Option<ModelAsset>,
    pub preprocessor_config: Option<ModelAsset>,
}

Resolved model assets for loading.

Each model type requires a specific set of files. You can provide them individually using the builder methods on TtsConfig, set TtsConfig::model_path to a directory that contains all of them, or rely on automatic HuggingFace Hub download (if the download feature is enabled).

File resolution order (per file)

1. Explicit path — set via with_*_file() / with_*_dir() on TtsConfig. Use this when your project has its own download manager (e.g. flow-like hash-based local caching).
2. Auto-discovery — if model_path is set, the library looks for well-known filenames inside that directory.
3. HuggingFace Hub download — if the download feature is enabled and the file is still missing, it is fetched from the Hub. This is the convenient fallback for quick prototyping.

Fields

config: Option<ModelAsset>

Path to config.json — model architecture configuration.

Expected format: JSON object describing the neural-network hyperparameters (hidden size, number of layers, vocab size, …). This is the standard HuggingFace config.json format. Each backend stores its architecture metadata here, such as transformer dimensions, tokenizer sizes, sample rates, or auxiliary decoder configuration.

tokenizer: Option<ModelAsset>

Path to tokenizer.json — BPE text tokenizer definition.

Expected format: HuggingFace Tokenizers self-contained JSON file. Contains the full vocabulary, merge rules, special tokens, and pre/post-processing steps. No separate vocab.json or merges.txt required when this file is present.

Used by both models to convert input text into token IDs before feeding them to the transformer backbone.

weights: Vec<ModelAsset>

Paths to model weight files (.safetensors).

Expected format: One or more SafeTensors files containing the neural-network parameters.

• Single file — model.safetensors (for models < ~5 GB).
• Sharded — model-00001-of-00004.safetensors, … When sharded, the library also expects model.safetensors.index.json in the same directory (auto-discovered or downloaded).
• Other formats — some backends use consolidated.safetensors or .pth files instead of the standard filename.

voices_dir: Option<ModelAssetDir>

Path to a voice asset directory for backends that ship preset voices.

Supported layouts include:

voices/                ← Kokoro preset voices (`*.pt`)
voice_embedding/       ← Voxtral preset voices (`*.pt`)

The exact file format depends on the backend.

speech_tokenizer_weights: Vec<ModelAsset>

Paths to the speech/audio tokenizer decoder weight files.

Expected format: SafeTensors files for the auxiliary decoder used by models that emit discrete audio codec tokens.

Contains:

• Residual VQ codebooks (16 groups × 2048 codes × dim)

• Pre-conv + pre-transformer layers

• Upsampling layers (transposed convolutions + SnakeBeta)

• Final decoder convolution

• Qwen3-TTS uses the separate Qwen/Qwen3-TTS-Tokenizer-12Hz repository.

• OmniVoice uses the audio_tokenizer/ subdirectory inside the main model snapshot.

speech_tokenizer_config: Option<ModelAsset>

Path to config.json of the speech/audio tokenizer.

Expected format: JSON config for the speech tokenizer decoder model, including codebook dimensions, upsampling ratios, and activation parameters.

If not provided, will be auto-discovered from a nested audio_tokenizer/ directory or downloaded from HuggingFace.

generation_config: Option<ModelAsset>

Path to generation_config.json (optional).

Expected format: Standard HuggingFace generation configuration with fields like max_new_tokens, top_p, temperature, do_sample, repetition_penalty, etc.

If not provided, sensible per-model defaults are used.

preprocessor_config: Option<ModelAsset>

Path to preprocessor_config.json (optional).

Used by backends such as VibeVoice that publish prompt-building and audio-normalization defaults separately from config.json.

Implementations

impl ModelFiles

pub fn fill_from_directory(&mut self, dir: &Path)

Scan a directory for well-known model files and fill any that are still None / empty.

pub fn fill_from_asset_bundle(&mut self, bundle: &ModelAssetBundle)

Scan an in-memory asset bundle for well-known model files.

pub fn load_safetensors_vb( assets: &[ModelAsset], dtype: DType, device: &Device, ) -> Result<VarBuilder<'static>, TtsError>

Build a VarBuilder by reading safetensors files fully into memory.

This is the safe alternative to VarBuilder::from_mmaped_safetensors which requires unsafe due to memory-mapping. The trade-off is a brief peak in memory while the raw bytes and parsed tensors coexist, but for model loading this is negligible compared to the final tensor footprint.

pub fn fill_from_hf( &mut self, model_id: &str, model_type: ModelType, bearer_token: Option<&str>, ) -> Result<(), TtsError>

Download missing files from HuggingFace Hub.

model_type determines which files are required.

pub fn validate(&self, model_type: ModelType) -> Result<(), TtsError>

Check whether all required files for the given model type are present.

pub fn missing_files(&self, model_type: ModelType) -> Vec<&'static str>

Return the list of files that are required but not yet set.

Trait Implementations

impl Clone for ModelFiles

fn clone(&self) -> ModelFiles

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ModelFiles

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for ModelFiles

fn default() -> ModelFiles

Returns the “default value” for a type.