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

# Basic Transcription

> Learn how to transcribe audio files with WhisperKit

## Quick Start

WhisperKit makes it easy to transcribe audio files on-device. This example shows how to get started with basic transcription.

### Initialize WhisperKit

```swift theme={null}
import WhisperKit

// Initialize WhisperKit with default settings
let pipe = try await WhisperKit()
```

WhisperKit automatically downloads the recommended model for your device on first run.

### Transcribe an Audio File

```swift theme={null}
// Transcribe a local audio file
let transcription = try await pipe.transcribe(audioPath: "path/to/audio.wav")?.text
print(transcription)
```

Supported audio formats: `.wav`, `.mp3`, `.m4a`, `.flac`

## Selecting a Model

### Using a Specific Model

```swift theme={null}
// Load a specific model
let pipe = try await WhisperKit(WhisperKitConfig(model: "large-v3"))
```

### Using Wildcards

```swift theme={null}
// Use glob search to select a model
let pipe = try await WhisperKit(WhisperKitConfig(model: "distil*large-v3"))
```

<Note>
  The model search must return a single model from the source repo, otherwise an error will be thrown.
</Note>

### Available Models

For a complete list of available models, see the [HuggingFace repo](https://huggingface.co/argmaxinc/whisperkit-coreml).

## Custom Model Repository

If you've created your own fine-tuned model using [whisperkittools](https://github.com/argmaxinc/whisperkittools), you can load it by specifying your repo:

```swift theme={null}
let config = WhisperKitConfig(
    model: "large-v3",
    modelRepo: "username/your-model-repo"
)
let pipe = try await WhisperKit(config)
```

## Full Transcription Example

Here's a complete example with error handling:

```swift theme={null}
import WhisperKit

Task {
    do {
        // Initialize WhisperKit
        let pipe = try await WhisperKit()
        
        // Transcribe audio file
        guard let result = try await pipe.transcribe(
            audioPath: "path/to/your/audio.wav"
        ) else {
            print("Transcription returned nil")
            return
        }
        
        // Print the transcription
        print("Transcription: \(result.text)")
        
        // Access segments with timestamps
        for segment in result.segments {
            print("[\(segment.start)s - \(segment.end)s]: \(segment.text)")
        }
        
    } catch {
        print("Error: \(error)")
    }
}
```

## Command Line Usage

You can also use the WhisperKit CLI for quick testing:

```bash theme={null}
# Install via Homebrew
brew install whisperkit-cli

# Transcribe an audio file
whisperkit-cli transcribe --audio-path audio.wav
```

### Download Models First

If using the CLI from source:

```bash theme={null}
# Clone the repository
git clone https://github.com/argmaxinc/whisperkit.git
cd whisperkit

# Setup environment
make setup

# Download a specific model
make download-model MODEL=large-v3

# Or download all models
make download-models
```

<Note>
  Make sure [git-lfs](https://git-lfs.com) is installed before running `download-model`.
</Note>

### Transcribe from Command Line

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

## Configuration Options

### Model Compute Options

Optimize performance by selecting compute units:

```swift theme={null}
let computeOptions = ModelComputeOptions(
    audioEncoderCompute: .cpuAndNeuralEngine,
    textDecoderCompute: .cpuAndNeuralEngine
)

let config = WhisperKitConfig(
    model: "large-v3",
    computeOptions: computeOptions
)

let pipe = try await WhisperKit(config)
```

### Decoding Options

Customize the transcription behavior:

```swift theme={null}
var decodingOptions = DecodingOptions()
decodingOptions.task = .transcribe
decodingOptions.language = "en"
decodingOptions.temperature = 0.0
decodingOptions.wordTimestamps = true

let result = try await pipe.transcribe(
    audioPath: "audio.wav",
    decodeOptions: decodingOptions
)
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Real-Time Streaming" icon="signal-stream" href="/examples/real-time-streaming">
    Learn how to transcribe audio in real-time from a microphone
  </Card>

  <Card title="Local Server" icon="server" href="/examples/local-server-clients">
    Set up a local transcription server with API clients
  </Card>
</CardGroup>