> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/argmaxinc/WhisperKit/llms.txt
> Use this file to discover all available pages before exploring further.

# TTSKitConfig

> Configuration class for initializing TTSKit instances

## Overview

`TTSKitConfig` is an open class that configures all aspects of a `TTSKit` instance, including model selection, paths, compute units, component overrides, and lifecycle flags. It follows the WhisperKit pattern of exposing configuration as a mutable class that can be subclassed for custom setups.

```swift theme={null}
open class TTSKitConfig
```

## Initialization

```swift theme={null}
public init(
    model: TTSModelVariant = .qwen3TTS_0_6b,
    modelFolder: URL? = nil,
    downloadBase: URL? = nil,
    modelRepo: String = Qwen3TTSConstants.defaultModelRepo,
    tokenizerFolder: URL? = nil,
    modelToken: String? = nil,
    modelEndpoint: String = Qwen3TTSConstants.defaultEndpoint,
    versionDir: String? = nil,
    codeDecoderVariant: String? = nil,
    multiCodeDecoderVariant: String? = nil,
    codeEmbedderVariant: String? = nil,
    multiCodeEmbedderVariant: String? = nil,
    textProjectorVariant: String? = nil,
    speechDecoderVariant: String? = nil,
    computeOptions: ComputeOptions = ComputeOptions(),
    verbose: Bool = true,
    logLevel: Logging.LogLevel = .info,
    downloadRevision: String? = nil,
    downloadAdditionalPatterns: [String] = [],
    useBackgroundDownloadSession: Bool = false,
    download: Bool = true,
    prewarm: Bool? = nil,
    load: Bool? = nil,
    seed: UInt64? = nil
)
```

<ParamField path="model" type="TTSModelVariant" default=".qwen3TTS_0_6b">
  Model variant that determines default versionDir, component variants, and tokenizer.
</ParamField>

<ParamField path="modelFolder" type="URL?" default="nil">
  Local URL to the model repository directory. If `nil`, models are downloaded from `modelRepo` on HuggingFace Hub.
</ParamField>

<ParamField path="downloadBase" type="URL?" default="nil">
  Base URL for downloading and caching models. `nil` uses the Hub library's default cache directory.
</ParamField>

<ParamField path="modelRepo" type="String" default="Qwen3TTSConstants.defaultModelRepo">
  HuggingFace repo ID for auto-downloading models.
</ParamField>

<ParamField path="tokenizerFolder" type="URL?" default="nil">
  HuggingFace repo ID or local folder path for the tokenizer (resolved from `model` by default).
</ParamField>

<ParamField path="modelToken" type="String?" default="nil">
  HuggingFace API token for private repos (or set the `HF_TOKEN` env var).
</ParamField>

<ParamField path="modelEndpoint" type="String" default="Qwen3TTSConstants.defaultEndpoint">
  HuggingFace Hub endpoint URL. Override to point at a regional mirror or an on-premise Hub instance.
</ParamField>

<ParamField path="versionDir" type="String?" default="nil">
  Version directory shared across all components (resolved from `model` by default).
</ParamField>

<ParamField path="codeDecoderVariant" type="String?" default="nil">
  Code decoder quantization variant (resolved from `model` by default).
</ParamField>

<ParamField path="multiCodeDecoderVariant" type="String?" default="nil">
  Multi-code decoder quantization variant (resolved from `model` by default).
</ParamField>

<ParamField path="codeEmbedderVariant" type="String?" default="nil">
  Code embedder quantization variant (resolved from `model` by default).
</ParamField>

<ParamField path="multiCodeEmbedderVariant" type="String?" default="nil">
  Multi-code embedder quantization variant (resolved from `model` by default).
</ParamField>

<ParamField path="textProjectorVariant" type="String?" default="nil">
  Text projector quantization variant (resolved from `model` by default).
</ParamField>

<ParamField path="speechDecoderVariant" type="String?" default="nil">
  Speech decoder quantization variant (resolved from `model` by default).
</ParamField>

<ParamField path="computeOptions" type="ComputeOptions" default="ComputeOptions()">
  Compute unit configuration per model component.
</ParamField>

<ParamField path="verbose" type="Bool" default="true">
  Whether to emit diagnostic logs during loading and generation.
</ParamField>

<ParamField path="logLevel" type="Logging.LogLevel" default=".info">
  Logging level when `verbose` is `true`.
</ParamField>

<ParamField path="downloadRevision" type="String?" default="nil">
  Specific git revision (commit SHA, tag, or branch) to download from the Hub. `nil` (default) resolves to the repo's default branch head.
</ParamField>

<ParamField path="downloadAdditionalPatterns" type="[String]" default="[]">
  Additional glob patterns to include during model download, appended to the patterns generated from the configured component variants.
</ParamField>

<ParamField path="useBackgroundDownloadSession" type="Bool" default="false">
  Use a background URLSession for model downloads.
</ParamField>

<ParamField path="download" type="Bool" default="true">
  Download models if not already available locally. When `true` (default), `loadModels()` will trigger a download if `modelFolder` is nil.
</ParamField>

<ParamField path="prewarm" type="Bool?" default="nil">
  Enable model prewarming. Prewarming compiles each CoreML model sequentially then discards weights, minimizing peak memory during compilation.
</ParamField>

<ParamField path="load" type="Bool?" default="nil">
  Load models immediately after init. `nil` loads when `modelFolder` is non-nil.
</ParamField>

<ParamField path="seed" type="UInt64?" default="nil">
  Optional seed for reproducible generation. Each concurrent task receives a derived seed (`seed ^ taskIndex`).
</ParamField>

## Properties

### Model Selection

<ResponseField name="model" type="TTSModelVariant">
  Model variant that determines default versionDir, component variants, and tokenizer.
</ResponseField>

### Model Location

<ResponseField name="modelFolder" type="URL?">
  Local URL to the model repository directory. If `nil`, models are downloaded from `modelRepo` on HuggingFace Hub.
</ResponseField>

<ResponseField name="downloadBase" type="URL?">
  Base URL for downloading and caching models. `nil` uses the Hub library's default cache directory.
</ResponseField>

<ResponseField name="modelRepo" type="String">
  HuggingFace repo ID for auto-downloading models.
</ResponseField>

### Tokenizer

<ResponseField name="tokenizerFolder" type="URL?">
  HuggingFace repo ID or local folder path for the tokenizer (resolved from `model` by default).
</ResponseField>

### Authentication

<ResponseField name="modelToken" type="String?">
  HuggingFace API token for private repos (or set the `HF_TOKEN` env var).
</ResponseField>

<ResponseField name="modelEndpoint" type="String">
  HuggingFace Hub endpoint URL.
</ResponseField>

### Component Variants

<ResponseField name="versionDir" type="String">
  Version directory shared across all components (resolved from `model` by default).
</ResponseField>

<ResponseField name="codeDecoderVariant" type="String">
  Per-component quantization variant for the code decoder.
</ResponseField>

<ResponseField name="multiCodeDecoderVariant" type="String">
  Per-component quantization variant for the multi-code decoder.
</ResponseField>

<ResponseField name="codeEmbedderVariant" type="String">
  Per-component quantization variant for the code embedder.
</ResponseField>

<ResponseField name="multiCodeEmbedderVariant" type="String">
  Per-component quantization variant for the multi-code embedder.
</ResponseField>

<ResponseField name="textProjectorVariant" type="String">
  Per-component quantization variant for the text projector.
</ResponseField>

<ResponseField name="speechDecoderVariant" type="String">
  Per-component quantization variant for the speech decoder.
</ResponseField>

### Compute

<ResponseField name="computeOptions" type="ComputeOptions">
  Compute unit configuration per model component.
</ResponseField>

### Logging

<ResponseField name="verbose" type="Bool">
  Whether to emit diagnostic logs during loading and generation.
</ResponseField>

<ResponseField name="logLevel" type="Logging.LogLevel">
  Logging level when `verbose` is `true`. Defaults to `.info`.
</ResponseField>

### Download Options

<ResponseField name="downloadRevision" type="String?">
  Specific git revision (commit SHA, tag, or branch) to download from the Hub.
</ResponseField>

<ResponseField name="downloadAdditionalPatterns" type="[String]">
  Additional glob patterns to include during model download.
</ResponseField>

<ResponseField name="useBackgroundDownloadSession" type="Bool">
  Use a background URLSession for model downloads.
</ResponseField>

<ResponseField name="download" type="Bool">
  Download models if not already available locally.
</ResponseField>

### Lifecycle Flags

<ResponseField name="prewarm" type="Bool?">
  Enable model prewarming.
</ResponseField>

<ResponseField name="load" type="Bool?">
  Load models immediately after init. `nil` loads when `modelFolder` is non-nil.
</ResponseField>

### Generation

<ResponseField name="seed" type="UInt64?">
  Optional seed for reproducible generation.
</ResponseField>

### Component Overrides

<ResponseField name="textProjector" type="(any TextProjecting)?">
  Custom text projector implementation. `nil` means TTSKit will use the default Qwen3 TTS class.
</ResponseField>

<ResponseField name="codeEmbedder" type="(any CodeEmbedding)?">
  Custom code embedder implementation.
</ResponseField>

<ResponseField name="multiCodeEmbedder" type="(any MultiCodeEmbedding)?">
  Custom multi-code embedder implementation.
</ResponseField>

<ResponseField name="codeDecoder" type="(any CodeDecoding)?">
  Custom code decoder implementation.
</ResponseField>

<ResponseField name="multiCodeDecoder" type="(any MultiCodeDecoding)?">
  Custom multi-code decoder implementation.
</ResponseField>

<ResponseField name="speechDecoder" type="(any SpeechDecoding)?">
  Custom speech decoder implementation.
</ResponseField>

## Instance Methods

### modelURL(component:variant:)

Resolve the full path to a component's model bundle.

```swift theme={null}
public func modelURL(component: String, variant: String) -> URL?
```

<ParamField path="component" type="String" required>
  Component name (e.g., "code\_decoder").
</ParamField>

<ParamField path="variant" type="String" required>
  Variant name (e.g., "W8A16-stateful").
</ParamField>

<ResponseField name="returns" type="URL?">
  URL to the component's `.mlmodelc` bundle, or `nil` if `modelFolder` is not set.
</ResponseField>

Requires `modelFolder` to be set (either directly or via download). Prefers a compiled `.mlmodelc` bundle and falls back to `.mlpackage`.

### tokenizerSource

The effective tokenizer source: local `tokenizerFolder` if set, otherwise the model's default HuggingFace repo ID.

```swift theme={null}
public var tokenizerSource: String { get }
```

<ResponseField name="returns" type="String">
  Path or repo ID for the tokenizer.
</ResponseField>

### componentDirectories(in:)

Version-specific directory for each component inside `modelFolder`.

```swift theme={null}
public func componentDirectories(in folder: URL? = nil) -> [URL]
```

<ParamField path="folder" type="URL?" default="nil">
  Base folder. Uses `modelFolder` if `nil`.
</ParamField>

<ResponseField name="returns" type="[URL]">
  Array of component directory URLs. Empty if `modelFolder` is not set.
</ResponseField>

Useful for targeted deletion or disk-size calculation of a single variant.

### downloadPatterns

Glob patterns used to download only the files needed for the configured variants.

```swift theme={null}
public var downloadPatterns: [String] { get }
```

<ResponseField name="returns" type="[String]">
  Array of glob patterns for the six model components.
</ResponseField>

## Static Properties

### componentNames

Component names in the model layout.

```swift theme={null}
public static let componentNames: [String]
```

<ResponseField name="returns" type="[String]">
  `["text_projector", "code_embedder", "multi_code_embedder", "code_decoder", "multi_code_decoder", "speech_decoder"]`
</ResponseField>

## Expected Directory Layout

When using local models, the `modelFolder` should contain the following structure:

```
modelFolder/
└── qwen3_tts/
    ├── code_decoder/<versionDir>/<variant>/*.mlmodelc
    ├── multi_code_decoder/<versionDir>/<variant>/*.mlmodelc
    ├── code_embedder/<versionDir>/<variant>/*.mlmodelc
    ├── multi_code_embedder/<versionDir>/<variant>/*.mlmodelc
    ├── text_projector/<versionDir>/<variant>/*.mlmodelc
    └── speech_decoder/<versionDir>/<variant>/*.mlmodelc
```

## Example Usage

### Minimal Usage (Auto-download)

```swift theme={null}
let tts = try await TTSKit()
```

### Local Models (Skip Download)

```swift theme={null}
let config = TTSKitConfig(
    modelFolder: URL(fileURLWithPath: "/path/to/models")
)
let tts = try await TTSKit(config)
```

### Custom Compute Options

```swift theme={null}
let computeOptions = ComputeOptions(
    embedderComputeUnits: .cpuOnly,
    codeDecoderComputeUnits: .cpuAndGPU,
    multiCodeDecoderComputeUnits: .all,
    speechDecoderComputeUnits: .cpuAndNeuralEngine
)

let config = TTSKitConfig(
    model: .qwen3TTS_1_7b,
    computeOptions: computeOptions,
    verbose: true
)
let tts = try await TTSKit(config)
```

### Component Override

```swift theme={null}
let config = TTSKitConfig()
config.codeDecoder = MyCustomCodeDecoder()
let tts = try await TTSKit(config)
```

### Reproducible Generation

```swift theme={null}
let config = TTSKitConfig(seed: 42)
let tts = try await TTSKit(config)
```