> ## 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.

# GenerationOptions

> Options that control the speech synthesis pipeline

## Overview

`GenerationOptions` controls all aspects of the speech synthesis pipeline, including sampling parameters, chunking strategy, and concurrency. All fields have sensible defaults, so the zero-argument initializer works for most use cases.

```swift theme={null}
public struct GenerationOptions: Codable, Sendable
```

## Initialization

```swift theme={null}
public init(
    temperature: Float = GenerationOptions.defaultTemperature,
    topK: Int = GenerationOptions.defaultTopK,
    repetitionPenalty: Float = GenerationOptions.defaultRepetitionPenalty,
    maxNewTokens: Int = GenerationOptions.defaultMaxNewTokens,
    concurrentWorkerCount: Int = 0,
    chunkingStrategy: TextChunkingStrategy? = nil,
    targetChunkSize: Int? = nil,
    minChunkSize: Int? = nil,
    instruction: String? = nil,
    forceLegacyEmbedPath: Bool = false
)
```

<ParamField path="temperature" type="Float" default="0.9">
  Sampling temperature. Higher values (e.g., 1.0) make output more random; lower values (e.g., 0.5) make it more deterministic.
</ParamField>

<ParamField path="topK" type="Int" default="50">
  Top-K sampling parameter. Only the K most likely tokens are considered at each step.
</ParamField>

<ParamField path="repetitionPenalty" type="Float" default="1.05">
  Repetition penalty to discourage repeating tokens. Values > 1.0 penalize repetition.
</ParamField>

<ParamField path="maxNewTokens" type="Int" default="245">
  Maximum number of tokens to generate in the autoregressive loop.
</ParamField>

<ParamField path="concurrentWorkerCount" type="Int" default="0">
  Number of concurrent workers for multi-chunk generation:

  * `0`: all chunks run concurrently in one batch (default, fastest for non-streaming use cases)
  * `1`: sequential - one chunk at a time; required for real-time `play` streaming
  * `N`: at most N chunks run concurrently
</ParamField>

<ParamField path="chunkingStrategy" type="TextChunkingStrategy?" default="nil">
  How to split long text into chunks. Defaults to `.sentence`. Set to `.none` to force a single-pass generation without sentence splitting.
</ParamField>

<ParamField path="targetChunkSize" type="Int?" default="nil">
  Target chunk size in tokens for sentence chunking. `nil` resolves to `TextChunker.defaultTargetChunkSize` at the call site.
</ParamField>

<ParamField path="minChunkSize" type="Int?" default="nil">
  Minimum chunk size in tokens. `nil` resolves to `TextChunker.defaultMinChunkSize` at the call site.
</ParamField>

<ParamField path="instruction" type="String?" default="nil">
  Optional style instruction for controlling speech characteristics (e.g., `"Very happy"`). Prepended as a text-only user prompt before the main TTS segment. For Qwen3, this is only supported by the 1.7B model variant.
</ParamField>

<ParamField path="forceLegacyEmbedPath" type="Bool" default="false">
  Force the legacy `[FloatType]` inference path even on macOS 15+ / iOS 18+. When `false` (default), the MLTensor path is taken on supported OS versions. Set to `true` in tests to exercise the pre-macOS-15 code path on current hardware.
</ParamField>

## Properties

### Sampling Parameters

<ResponseField name="temperature" type="Float">
  Sampling temperature. Default: `0.9`
</ResponseField>

<ResponseField name="topK" type="Int">
  Top-K sampling parameter. Default: `50`
</ResponseField>

<ResponseField name="repetitionPenalty" type="Float">
  Repetition penalty to discourage repeating tokens. Default: `1.05`
</ResponseField>

<ResponseField name="maxNewTokens" type="Int">
  Maximum number of tokens to generate. Default: `245`
</ResponseField>

### Chunking and Concurrency

<ResponseField name="concurrentWorkerCount" type="Int">
  Number of concurrent workers for multi-chunk generation. Default: `0` (all chunks concurrently)
</ResponseField>

<ResponseField name="chunkingStrategy" type="TextChunkingStrategy?">
  How to split long text into chunks. Default: `nil` (resolves to `.sentence`)
</ResponseField>

<ResponseField name="targetChunkSize" type="Int?">
  Target chunk size in tokens for sentence chunking. Default: `nil` (uses `TextChunker.defaultTargetChunkSize`)
</ResponseField>

<ResponseField name="minChunkSize" type="Int?">
  Minimum chunk size in tokens. Default: `nil` (uses `TextChunker.defaultMinChunkSize`)
</ResponseField>

### Style Control

<ResponseField name="instruction" type="String?">
  Optional style instruction for controlling speech characteristics. Default: `nil`

  Only supported by the Qwen3 1.7B model variant.
</ResponseField>

### Advanced

<ResponseField name="forceLegacyEmbedPath" type="Bool">
  Force the legacy `[FloatType]` inference path. Default: `false`
</ResponseField>

## Static Properties

### defaultTemperature

```swift theme={null}
public static let defaultTemperature: Float = 0.9
```

<ResponseField name="value" type="Float">
  Default sampling temperature: `0.9`
</ResponseField>

### defaultTopK

```swift theme={null}
public static let defaultTopK: Int = 50
```

<ResponseField name="value" type="Int">
  Default Top-K sampling parameter: `50`
</ResponseField>

### defaultRepetitionPenalty

```swift theme={null}
public static let defaultRepetitionPenalty: Float = 1.05
```

<ResponseField name="value" type="Float">
  Default repetition penalty: `1.05`
</ResponseField>

### defaultMaxNewTokens

```swift theme={null}
public static let defaultMaxNewTokens: Int = 245
```

<ResponseField name="value" type="Int">
  Default maximum number of tokens to generate: `245`
</ResponseField>

## Example Usage

### Default Options

```swift theme={null}
let result = try await tts.generate(
    text: "Hello, world!",
    voice: "ryan"
)
```

### Custom Sampling

```swift theme={null}
var options = GenerationOptions(
    temperature: 0.7,
    topK: 30,
    maxNewTokens: 500
)
let result = try await tts.generate(
    text: "A longer piece of text.",
    voice: "ryan",
    options: options
)
```

### Sequential Generation (for Streaming)

```swift theme={null}
var options = GenerationOptions(
    concurrentWorkerCount: 1  // Required for play() streaming
)
let result = try await tts.play(
    text: "This will stream audio chunk by chunk.",
    voice: "ryan",
    options: options,
    playbackStrategy: .auto
)
```

### With Style Instruction (1.7B only)

```swift theme={null}
var options = GenerationOptions(
    instruction: "Very happy and excited"
)
let result = try await tts.generate(
    text: "I'm so glad to meet you!",
    voice: "ryan",
    options: options
)
```

### Disable Chunking

```swift theme={null}
var options = GenerationOptions(
    chunkingStrategy: .none
)
let result = try await tts.generate(
    text: "Generate this as a single chunk.",
    voice: "ryan",
    options: options
)
```

### Custom Chunk Sizes

```swift theme={null}
var options = GenerationOptions(
    targetChunkSize: 100,
    minChunkSize: 20
)
let result = try await tts.generate(
    text: "A very long piece of text that will be split into chunks...",
    voice: "ryan",
    options: options
)
```

### Parallel Generation

```swift theme={null}
var options = GenerationOptions(
    concurrentWorkerCount: 4  // Up to 4 chunks in parallel
)
let result = try await tts.generate(
    text: "Long text with multiple sentences. Each sentence becomes a chunk. They generate in parallel.",
    voice: "ryan",
    options: options
)
```