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.

open class TTSKitConfig

Initialization

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
)

model · TTSModelVariant · default: ".qwen3TTS_0_6b"

Model variant that determines default versionDir, component variants, and tokenizer.

modelFolder · URL? · default: "nil"

Local URL to the model repository directory. If nil, models are downloaded from modelRepo on HuggingFace Hub.

downloadBase · URL? · default: "nil"

Base URL for downloading and caching models. nil uses the Hub library’s default cache directory.

modelRepo · String · default: "Qwen3TTSConstants.defaultModelRepo"

HuggingFace repo ID for auto-downloading models.

tokenizerFolder · URL? · default: "nil"

HuggingFace repo ID or local folder path for the tokenizer (resolved from model by default).

modelToken · String? · default: "nil"

HuggingFace API token for private repos (or set the HF_TOKEN env var).

modelEndpoint · String · default: "Qwen3TTSConstants.defaultEndpoint"

HuggingFace Hub endpoint URL. Override to point at a regional mirror or an on-premise Hub instance.

versionDir · String? · default: "nil"

Version directory shared across all components (resolved from model by default).

codeDecoderVariant · String? · default: "nil"

Code decoder quantization variant (resolved from model by default).

multiCodeDecoderVariant · String? · default: "nil"

Multi-code decoder quantization variant (resolved from model by default).

codeEmbedderVariant · String? · default: "nil"

Code embedder quantization variant (resolved from model by default).

multiCodeEmbedderVariant · String? · default: "nil"

Multi-code embedder quantization variant (resolved from model by default).

textProjectorVariant · String? · default: "nil"

Text projector quantization variant (resolved from model by default).

speechDecoderVariant · String? · default: "nil"

Speech decoder quantization variant (resolved from model by default).

computeOptions · ComputeOptions · default: "ComputeOptions()"

Compute unit configuration per model component.

verbose · Bool · default: "true"

Whether to emit diagnostic logs during loading and generation.

logLevel · Logging.LogLevel · default: ".info"

Logging level when verbose is true.

downloadRevision · 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.

downloadAdditionalPatterns · [String] · default: "[]"

Additional glob patterns to include during model download, appended to the patterns generated from the configured component variants.

useBackgroundDownloadSession · Bool · default: "false"

Use a background URLSession for model downloads.

download · Bool · default: "true"

Download models if not already available locally. When true (default), loadModels() will trigger a download if modelFolder is nil.

prewarm · Bool? · default: "nil"

Enable model prewarming. Prewarming compiles each CoreML model sequentially then discards weights, minimizing peak memory during compilation.

load · Bool? · default: "nil"

Load models immediately after init. nil loads when modelFolder is non-nil.

seed · UInt64? · default: "nil"

Optional seed for reproducible generation. Each concurrent task receives a derived seed (seed ^ taskIndex).

Properties

Model Selection

model · TTSModelVariant

Model variant that determines default versionDir, component variants, and tokenizer.

Model Location

modelFolder · URL?

Local URL to the model repository directory. If nil, models are downloaded from modelRepo on HuggingFace Hub.

downloadBase · URL?

Base URL for downloading and caching models. nil uses the Hub library’s default cache directory.

modelRepo · String

HuggingFace repo ID for auto-downloading models.

Tokenizer

tokenizerFolder · URL?

HuggingFace repo ID or local folder path for the tokenizer (resolved from model by default).

Authentication

modelToken · String?

HuggingFace API token for private repos (or set the HF_TOKEN env var).

modelEndpoint · String

HuggingFace Hub endpoint URL.

Component Variants

versionDir · String

Version directory shared across all components (resolved from model by default).

codeDecoderVariant · String

Per-component quantization variant for the code decoder.

multiCodeDecoderVariant · String

Per-component quantization variant for the multi-code decoder.

codeEmbedderVariant · String

Per-component quantization variant for the code embedder.

multiCodeEmbedderVariant · String

Per-component quantization variant for the multi-code embedder.

textProjectorVariant · String

Per-component quantization variant for the text projector.

speechDecoderVariant · String

Per-component quantization variant for the speech decoder.

Compute

computeOptions · ComputeOptions

Compute unit configuration per model component.

Logging

verbose · Bool

Whether to emit diagnostic logs during loading and generation.

logLevel · Logging.LogLevel

Logging level when verbose is true. Defaults to .info.

Download Options

downloadRevision · String?

Specific git revision (commit SHA, tag, or branch) to download from the Hub.

downloadAdditionalPatterns · [String]

Additional glob patterns to include during model download.

useBackgroundDownloadSession · Bool

Use a background URLSession for model downloads.

download · Bool

Download models if not already available locally.

Lifecycle Flags

prewarm · Bool?

Enable model prewarming.

load · Bool?

Load models immediately after init. nil loads when modelFolder is non-nil.

Generation

seed · UInt64?

Optional seed for reproducible generation.

Component Overrides

textProjector · (any TextProjecting)?

Custom text projector implementation. nil means TTSKit will use the default Qwen3 TTS class.

codeEmbedder · (any CodeEmbedding)?

Custom code embedder implementation.

multiCodeEmbedder · (any MultiCodeEmbedding)?

Custom multi-code embedder implementation.

codeDecoder · (any CodeDecoding)?

Custom code decoder implementation.

multiCodeDecoder · (any MultiCodeDecoding)?

Custom multi-code decoder implementation.

speechDecoder · (any SpeechDecoding)?

Custom speech decoder implementation.

Instance Methods

modelURL(component:variant:)

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

public func modelURL(component: String, variant: String) -> URL?

component · String · required

Component name (e.g., “code_decoder”).

variant · String · required

Variant name (e.g., “W8A16-stateful”).

returns · URL?

URL to the component’s .mlmodelc bundle, or nil if modelFolder is not set.

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.

public var tokenizerSource: String { get }

returns · String

Path or repo ID for the tokenizer.

componentDirectories(in:)

Version-specific directory for each component inside modelFolder.

public func componentDirectories(in folder: URL? = nil) -> [URL]

folder · URL? · default: "nil"

Base folder. Uses modelFolder if nil.

returns · [URL]

Array of component directory URLs. Empty if modelFolder is not set.

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.

public var downloadPatterns: [String] { get }

returns · [String]

Array of glob patterns for the six model components.

Static Properties

componentNames

Component names in the model layout.

public static let componentNames: [String]

returns · [String]

["text_projector", "code_embedder", "multi_code_embedder", "code_decoder", "multi_code_decoder", "speech_decoder"]

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)

let tts = try await TTSKit()

Local Models (Skip Download)

let config = TTSKitConfig(
    modelFolder: URL(fileURLWithPath: "/path/to/models")
)
let tts = try await TTSKit(config)

Custom Compute Options

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

let config = TTSKitConfig()
config.codeDecoder = MyCustomCodeDecoder()
let tts = try await TTSKit(config)

Reproducible Generation

let config = TTSKitConfig(seed: 42)
let tts = try await TTSKit(config)