TTSKitConfig

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)

WhisperKit

TTSKit

Core Types

Overview

Initialization

Properties

Model Selection

Model Location

Tokenizer

Authentication

Component Variants

Compute

Logging

Download Options

Lifecycle Flags

Generation

Component Overrides

Instance Methods

modelURL(component:variant:)

tokenizerSource

componentDirectories(in:)

downloadPatterns

Static Properties

componentNames

Expected Directory Layout

Example Usage

Minimal Usage (Auto-download)

Local Models (Skip Download)

Custom Compute Options

Component Override

Reproducible Generation

Build docs developers (and LLMs) love

WhisperKit

TTSKit

Core Types

​Overview

​Initialization

​Properties

​Model Selection

​Model Location

​Tokenizer

​Authentication

​Component Variants

​Compute

​Logging

​Download Options

​Lifecycle Flags

​Generation

​Component Overrides

​Instance Methods

​modelURL(component:variant:)

​tokenizerSource

​componentDirectories(in:)

​downloadPatterns

​Static Properties

​componentNames

​Expected Directory Layout

​Example Usage

​Minimal Usage (Auto-download)

​Local Models (Skip Download)

​Custom Compute Options

​Component Override

​Reproducible Generation

Build docs developers (and LLMs) love

Overview

Initialization

Properties

Model Selection

Model Location

Tokenizer

Authentication

Component Variants

Compute

Logging

Download Options

Lifecycle Flags

Generation

Component Overrides

Instance Methods

modelURL(component:variant:)

tokenizerSource

componentDirectories(in:)

downloadPatterns

Static Properties

componentNames

Expected Directory Layout

Example Usage

Minimal Usage (Auto-download)

Local Models (Skip Download)

Custom Compute Options

Component Override

Reproducible Generation