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

# CLI Usage

> Command-line interface for transcription, translation, and streaming

WhisperKit provides a powerful command-line interface for transcribing audio files, streaming from microphone, and testing models outside of Xcode.

## Installation

<Tabs>
  <Tab title="Homebrew">
    ```bash theme={null}
    brew install whisperkit-cli
    ```
  </Tab>

  <Tab title="From Source">
    ```bash theme={null}
    git clone https://github.com/argmaxinc/whisperkit.git
    cd whisperkit
    make setup
    make download-model MODEL=large-v3
    swift run whisperkit-cli transcribe --help
    ```
  </Tab>
</Tabs>

## Available Commands

WhisperKit CLI provides three main commands:

<CardGroup cols={3}>
  <Card title="transcribe" icon="microphone">
    Transcribe audio files or streams
  </Card>

  <Card title="tts" icon="volume">
    Text-to-speech generation
  </Card>

  <Card title="serve" icon="server">
    Start local server (requires BUILD\_ALL=1)
  </Card>
</CardGroup>

## Transcribe Command

### Basic Usage

Transcribe an audio file:

```bash theme={null}
swift run whisperkit-cli transcribe \
  --model-path "Models/whisperkit-coreml/openai_whisper-large-v3" \
  --audio-path "audio.wav"
```

### Command-Line Options

<ParamField path="--audio-path" type="string[]">
  Paths to audio files to transcribe
</ParamField>

<ParamField path="--audio-folder" type="string">
  Path to folder containing audio files (will transcribe all supported formats)
</ParamField>

<ParamField path="--model-path" type="string">
  Path to local model files
</ParamField>

<ParamField path="--model" type="string">
  Model to download if no model-path provided (e.g., `tiny`, `base`, `small`, `medium`, `large-v3`)
</ParamField>

<ParamField path="--model-prefix" type="string" default="openai">
  Model variant prefix: `openai` or `distil`
</ParamField>

<ParamField path="--task" type="string" default="transcribe">
  Task to perform: `transcribe` or `translate`
</ParamField>

<ParamField path="--language" type="string">
  Source language code (e.g., `en`, `es`, `ja`, `zh`)
</ParamField>

<ParamField path="--verbose" type="boolean">
  Enable verbose output with progress tracking
</ParamField>

### Audio Processing Options

<ParamField path="--temperature" type="float" default="0.0">
  Sampling temperature (0.0-1.0). Higher values increase randomness.
</ParamField>

<ParamField path="--temperature-increment-on-fallback" type="float" default="0.2">
  Temperature increase on decoding failures
</ParamField>

<ParamField path="--temperature-fallback-count" type="int" default="5">
  Number of times to increase temperature
</ParamField>

<ParamField path="--best-of" type="int" default="5">
  Number of candidates when sampling with non-zero temperature (topK)
</ParamField>

### Prompt and Prefix Options

<ParamField path="--prompt" type="string">
  Text to condition the model on. Useful for guiding transcription style.
</ParamField>

<ParamField path="--prefix" type="string">
  Force prefix text when decoding
</ParamField>

<ParamField path="--use-prefill-prompt" type="boolean">
  Force initial prompt tokens based on language, task, and timestamp options
</ParamField>

<ParamField path="--use-prefill-cache" type="boolean">
  Use decoder prefill data for faster initial decoding
</ParamField>

### Timestamp Options

<ParamField path="--word-timestamps" type="boolean">
  Add timestamps for each word in output
</ParamField>

<ParamField path="--without-timestamps" type="boolean">
  Force no timestamps when decoding
</ParamField>

<ParamField path="--clip-timestamps" type="float[]">
  List of timestamps to split audio into segments
</ParamField>

### Quality Thresholds

<ParamField path="--compression-ratio-threshold" type="float" default="2.4">
  Gzip compression ratio threshold for decoding failure
</ParamField>

<ParamField path="--logprob-threshold" type="float" default="-1.0">
  Average log probability threshold for decoding failure
</ParamField>

<ParamField path="--first-token-logprob-threshold" type="float" default="-1.5">
  Log probability threshold for first token decoding failure
</ParamField>

<ParamField path="--no-speech-threshold" type="float" default="0.6">
  Probability threshold to consider segment as silence
</ParamField>

### Performance Options

<ParamField path="--audio-encoder-compute-units" type="string" default="cpuAndNeuralEngine">
  Compute units for audio encoder: `all`, `cpuOnly`, `cpuAndGPU`, `cpuAndNeuralEngine`
</ParamField>

<ParamField path="--text-decoder-compute-units" type="string" default="cpuAndNeuralEngine">
  Compute units for text decoder: `all`, `cpuOnly`, `cpuAndGPU`, `cpuAndNeuralEngine`
</ParamField>

<ParamField path="--concurrent-worker-count" type="int" default="4">
  Maximum concurrent inference workers (0 = unlimited)
</ParamField>

<ParamField path="--chunking-strategy" type="string" default="vad">
  Audio chunking strategy: `none` or `vad` (voice activity detection)
</ParamField>

### Streaming Options

<ParamField path="--stream" type="boolean">
  Process audio directly from microphone in real-time
</ParamField>

<ParamField path="--stream-simulated" type="boolean">
  Simulate streaming transcription using input audio file
</ParamField>

### Output Options

<ParamField path="--report" type="boolean">
  Generate SRT and JSON report files
</ParamField>

<ParamField path="--report-path" type="string" default=".">
  Directory to save reports
</ParamField>

<ParamField path="--skip-special-tokens" type="boolean">
  Skip special tokens in output
</ParamField>

## Usage Examples

### Basic Transcription

<CodeGroup>
  ```bash Single File theme={null}
  swift run whisperkit-cli transcribe \
    --model-path "Models/whisperkit-coreml/openai_whisper-large-v3" \
    --audio-path "audio.wav"
  ```

  ```bash Multiple Files theme={null}
  swift run whisperkit-cli transcribe \
    --model-path "Models/whisperkit-coreml/openai_whisper-base" \
    --audio-path "audio1.wav" "audio2.mp3" "audio3.m4a"
  ```

  ```bash Entire Folder theme={null}
  swift run whisperkit-cli transcribe \
    --model-path "Models/whisperkit-coreml/openai_whisper-tiny" \
    --audio-folder "recordings/"
  ```

  ```bash With Language theme={null}
  swift run whisperkit-cli transcribe \
    --model-path "Models/whisperkit-coreml/openai_whisper-medium" \
    --audio-path "audio.wav" \
    --language "es" \
    --verbose
  ```
</CodeGroup>

### Translation

```bash theme={null}
swift run whisperkit-cli transcribe \
  --model-path "Models/whisperkit-coreml/openai_whisper-large-v3" \
  --audio-path "french_audio.wav" \
  --task "translate" \
  --verbose
```

### Streaming Transcription

<CodeGroup>
  ```bash Microphone Input theme={null}
  swift run whisperkit-cli transcribe \
    --model-path "Models/whisperkit-coreml/openai_whisper-large-v3" \
    --stream
  ```

  ```bash Simulated Streaming theme={null}
  swift run whisperkit-cli transcribe \
    --model-path "Models/whisperkit-coreml/openai_whisper-base" \
    --audio-path "audio.wav" \
    --stream-simulated \
    --verbose
  ```
</CodeGroup>

### Word Timestamps

```bash theme={null}
swift run whisperkit-cli transcribe \
  --model-path "Models/whisperkit-coreml/openai_whisper-large-v3" \
  --audio-path "audio.wav" \
  --word-timestamps \
  --report \
  --report-path "outputs/"
```

### Using Prompts

```bash theme={null}
swift run whisperkit-cli transcribe \
  --model-path "Models/whisperkit-coreml/openai_whisper-large-v3" \
  --audio-path "meeting.wav" \
  --prompt "This is a technical discussion about machine learning and neural networks." \
  --language "en"
```

### Clipping Audio

```bash theme={null}
swift run whisperkit-cli transcribe \
  --model-path "Models/whisperkit-coreml/openai_whisper-base" \
  --audio-path "long_audio.wav" \
  --clip-timestamps 0 30.5 60.0 90.5 \
  --verbose
```

### Performance Tuning

<CodeGroup>
  ```bash GPU Acceleration theme={null}
  swift run whisperkit-cli transcribe \
    --model-path "Models/whisperkit-coreml/openai_whisper-small" \
    --audio-path "audio.wav" \
    --audio-encoder-compute-units cpuAndGPU \
    --text-decoder-compute-units cpuAndGPU
  ```

  ```bash Neural Engine (macOS 14+) theme={null}
  swift run whisperkit-cli transcribe \
    --model-path "Models/whisperkit-coreml/openai_whisper-large-v3" \
    --audio-path "audio.wav" \
    --audio-encoder-compute-units cpuAndNeuralEngine \
    --text-decoder-compute-units cpuAndNeuralEngine
  ```

  ```bash Parallel Processing theme={null}
  swift run whisperkit-cli transcribe \
    --model-path "Models/whisperkit-coreml/openai_whisper-tiny" \
    --audio-folder "recordings/" \
    --concurrent-worker-count 8
  ```
</CodeGroup>

### Using Distil Models

```bash theme={null}
swift run whisperkit-cli transcribe \
  --model "large-v3" \
  --model-prefix "distil" \
  --audio-path "audio.wav" \
  --verbose
```

## Model Management

### Downloading Models

```bash theme={null}
# Download specific model
make download-model MODEL=large-v3

# Download all available models
make download-models
```

### Model Locations

Downloaded models are stored in:

```
Models/whisperkit-coreml/openai_whisper-{MODEL_NAME}/
```

Supported formats: `wav`, `mp3`, `m4a`, `flac`, `aiff`, `aac`

## Progress Tracking

When using `--verbose`, the CLI displays:

* Model loading time (encoder, decoder, tokenizer)
* Real-time progress bar with ETA
* Tokens per second
* Real-time factor (audio duration / transcription time)
* Speed factor (inverse of real-time factor)

```
[==========================] 100% | Elapsed Time: 12.45 s | Remaining: 0.00 s

Transcription Performance:
  - Tokens per second: 124.56
  - Real-time factor: 0.31
  - Speed factor: 3.22
```

## Output Formats

### Console Output

By default, prints transcription text to stdout:

```bash theme={null}
swift run whisperkit-cli transcribe --audio-path audio.wav
# Output: "This is the transcribed text."
```

### Report Files

With `--report` flag, generates:

#### SRT Subtitle Format

```srt theme={null}
1
00:00:00,000 --> 00:00:03,450
This is the transcribed text.

2
00:00:03,450 --> 00:00:07,890
With timestamps for each segment.
```

#### JSON Metadata

```json theme={null}
{
  "text": "Complete transcription...",
  "segments": [
    {
      "id": 0,
      "start": 0.0,
      "end": 3.45,
      "text": "This is the transcribed text.",
      "tokens": [1234, 5678],
      "words": [
        {"word": "This", "start": 0.0, "end": 0.34},
        {"word": "is", "start": 0.34, "end": 0.56}
      ]
    }
  ],
  "timings": {
    "modelLoading": 2.34,
    "tokensPerSecond": 124.56,
    "realTimeFactor": 0.31
  }
}
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Model not found">
    Download the model first:

    ```bash theme={null}
    make download-model MODEL=large-v3
    ```

    Then use the full path:

    ```bash theme={null}
    --model-path "Models/whisperkit-coreml/openai_whisper-large-v3"
    ```
  </Accordion>

  <Accordion title="Invalid language code">
    Check supported languages in the error message or see [Constants.swift](https://github.com/argmaxinc/WhisperKit/blob/main/Sources/WhisperKit/Core/Constants.swift) for valid codes.
  </Accordion>

  <Accordion title="Microphone permission denied">
    Grant microphone access in System Settings → Privacy & Security → Microphone
  </Accordion>

  <Accordion title="Out of memory errors">
    * Use smaller models (tiny, base)
    * Reduce concurrent worker count: `--concurrent-worker-count 1`
    * Use CPU-only compute units: `--audio-encoder-compute-units cpuOnly`
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Local Server" icon="server" href="/advanced/local-server">
    Run WhisperKit as an API server
  </Card>

  <Card title="Performance Optimization" icon="gauge-high" href="/advanced/performance-optimization">
    Optimize transcription speed
  </Card>
</CardGroup>