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

# Local Server

> Run WhisperKit as an OpenAI-compatible local transcription server

WhisperKit includes a local server that implements the OpenAI Audio API, allowing you to use existing OpenAI SDK clients or generate new ones. The server supports transcription and translation with **output streaming** capabilities for real-time transcription results.

<Note>
  **For real-time transcription server with full-duplex streaming capabilities**, check out [WhisperKit Pro Local Server](https://www.argmaxinc.com/blog/argmax-local-server) which provides live audio streaming and real-time transcription for applications requiring continuous audio processing.
</Note>

## Building the Server

The local server requires a special build flag to include server dependencies:

<CodeGroup>
  ```bash Makefile theme={null}
  make build-local-server
  ```

  ```bash Manual Build theme={null}
  BUILD_ALL=1 swift build --product whisperkit-cli
  ```
</CodeGroup>

## Starting the Server

### Basic Usage

Start the server with default settings (localhost:50060):

```bash theme={null}
BUILD_ALL=1 swift run whisperkit-cli serve
```

### Configuration Options

<ParamField path="--host" type="string" default="localhost">
  Host address to bind the server to. Use `0.0.0.0` to accept connections from any network interface.
</ParamField>

<ParamField path="--port" type="int" default="50060">
  Port number for the server to listen on.
</ParamField>

<ParamField path="--model" type="string">
  Specific model to use (e.g., `tiny`, `base`, `small`, `medium`, `large-v3`).
</ParamField>

<ParamField path="--model-path" type="string">
  Path to local model files if you don't want to download them.
</ParamField>

<ParamField path="--verbose" type="boolean">
  Enable verbose logging for debugging.
</ParamField>

### Examples

<CodeGroup>
  ```bash Default Server theme={null}
  # Start with default tiny model on localhost:50060
  BUILD_ALL=1 swift run whisperkit-cli serve
  ```

  ```bash Custom Host and Port theme={null}
  # Accept connections from any interface
  BUILD_ALL=1 swift run whisperkit-cli serve --host 0.0.0.0 --port 8080
  ```

  ```bash Specific Model theme={null}
  # Use large-v3 model with verbose logging
  BUILD_ALL=1 swift run whisperkit-cli serve --model large-v3 --verbose
  ```

  ```bash Local Model Path theme={null}
  # Use locally stored model
  BUILD_ALL=1 swift run whisperkit-cli serve --model-path "Models/whisperkit-coreml/openai_whisper-large-v3"
  ```
</CodeGroup>

## API Endpoints

The server implements the OpenAI Audio API specification:

### POST /v1/audio/transcriptions

Transcribe audio to text in the original language.

**Request:**

<ParamField body="file" type="file" required>
  Audio file to transcribe (wav, mp3, m4a, flac)
</ParamField>

<ParamField body="model" type="string" required>
  Model identifier (required by API spec, uses server's loaded model)
</ParamField>

<ParamField body="language" type="string">
  Source language code (e.g., `en`, `es`, `ja`). Auto-detects if not specified.
</ParamField>

<ParamField body="prompt" type="string">
  Text to guide transcription style and context
</ParamField>

<ParamField body="response_format" type="string" default="verbose_json">
  Output format: `json` or `verbose_json`
</ParamField>

<ParamField body="temperature" type="float" default="0.0">
  Sampling temperature (0.0-1.0)
</ParamField>

<ParamField body="timestamp_granularities[]" type="array" default="[segment]">
  Timing detail: `word`, `segment`, or both
</ParamField>

<ParamField body="stream" type="boolean" default="false">
  Enable Server-Sent Events (SSE) streaming
</ParamField>

### POST /v1/audio/translations

Translate audio to English text.

**Accepts the same parameters as `/v1/audio/transcriptions`**

### GET /health

Health check endpoint that returns server status.

## Client Examples

### Python Client

Using the OpenAI Python SDK:

<CodeGroup>
  ```python Basic Transcription theme={null}
  from openai import OpenAI

  client = OpenAI(base_url="http://localhost:50060/v1")

  with open("audio.wav", "rb") as audio_file:
      result = client.audio.transcriptions.create(
          file=audio_file,
          model="tiny",  # Required parameter
          language="en"
      )
      print(result.text)
  ```

  ```python Translation theme={null}
  from openai import OpenAI

  client = OpenAI(base_url="http://localhost:50060/v1")

  with open("audio.wav", "rb") as audio_file:
      result = client.audio.translations.create(
          file=audio_file,
          model="tiny"
      )
      print(result.text)
  ```

  ```python Streaming Response theme={null}
  from openai import OpenAI

  client = OpenAI(base_url="http://localhost:50060/v1")

  with open("audio.wav", "rb") as audio_file:
      stream = client.audio.transcriptions.create(
          file=audio_file,
          model="tiny",
          stream=True
      )
      
      for chunk in stream:
          print(chunk.text, end="", flush=True)
  ```

  ```python Word Timestamps theme={null}
  from openai import OpenAI

  client = OpenAI(base_url="http://localhost:50060/v1")

  with open("audio.wav", "rb") as audio_file:
      result = client.audio.transcriptions.create(
          file=audio_file,
          model="tiny",
          response_format="verbose_json",
          timestamp_granularities=["word", "segment"]
      )
      
      for word in result.words:
          print(f"{word.word} [{word.start:.2f}s - {word.end:.2f}s]")
  ```
</CodeGroup>

### Command Line with curl

<CodeGroup>
  ```bash Transcribe theme={null}
  curl -X POST http://localhost:50060/v1/audio/transcriptions \
    -F "file=@audio.wav" \
    -F "model=tiny" \
    -F "language=en"
  ```

  ```bash Translate theme={null}
  curl -X POST http://localhost:50060/v1/audio/translations \
    -F "file=@audio.wav" \
    -F "model=tiny"
  ```

  ```bash Streaming theme={null}
  curl -X POST http://localhost:50060/v1/audio/transcriptions \
    -F "file=@audio.wav" \
    -F "model=tiny" \
    -F "stream=true" \
    --no-buffer
  ```

  ```bash Word Timestamps theme={null}
  curl -X POST http://localhost:50060/v1/audio/transcriptions \
    -F "file=@audio.wav" \
    -F "model=tiny" \
    -F "response_format=verbose_json" \
    -F "timestamp_granularities[]=word" \
    -F "timestamp_granularities[]=segment"
  ```
</CodeGroup>

### Swift Client

Generate a Swift client from the OpenAPI specification:

```bash theme={null}
cd Examples/ServeCLIClient/Swift
swift run whisperkit-client transcribe audio.wav --language en
swift run whisperkit-client translate audio.wav
```

See the [Swift client README](https://github.com/argmaxinc/WhisperKit/tree/main/Examples/ServeCLIClient/Swift) for more details.

## Client Generation

You can generate clients for any language using the OpenAPI specification:

<CodeGroup>
  ```bash Python Client theme={null}
  swift run swift-openapi-generator generate scripts/specs/localserver_openapi.yaml \
    --output-directory python-client \
    --mode client \
    --mode types
  ```

  ```bash TypeScript Client theme={null}
  npx @openapitools/openapi-generator-cli generate \
    -i scripts/specs/localserver_openapi.yaml \
    -g typescript-fetch \
    -o typescript-client
  ```

  ```bash Java Client theme={null}
  npx @openapitools/openapi-generator-cli generate \
    -i scripts/specs/localserver_openapi.yaml \
    -g java \
    -o java-client
  ```
</CodeGroup>

To regenerate the OpenAPI specification from the latest OpenAI API:

```bash theme={null}
make generate-server
```

## Supported Features

<CardGroup cols={2}>
  <Card title="Streaming" icon="stream">
    Server-Sent Events (SSE) for real-time transcription results
  </Card>

  <Card title="Timestamps" icon="clock">
    Word-level and segment-level timing information
  </Card>

  <Card title="Log Probabilities" icon="chart-line">
    Token-level confidence scores via `logprobs` parameter
  </Card>

  <Card title="Language Detection" icon="language">
    Automatic language detection or manual specification
  </Card>

  <Card title="Temperature Control" icon="temperature-half">
    Sampling temperature for transcription randomness
  </Card>

  <Card title="Prompt Text" icon="message">
    Text guidance for transcription style and context
  </Card>
</CardGroup>

## API Limitations

Compared to the official OpenAI API:

<Warning>
  * **Response formats**: Only `json` and `verbose_json` supported (no plain text, SRT, VTT formats)
  * **Model selection**: Server must be launched with desired model via `--model` flag. The `model` parameter in API requests is required but uses the server's loaded model.
</Warning>

## Example Projects

Explore complete example implementations:

<CardGroup cols={3}>
  <Card title="Python Client" icon="python" href="https://github.com/argmaxinc/WhisperKit/tree/main/Examples/ServeCLIClient/Python">
    OpenAI SDK-based Python client
  </Card>

  <Card title="Swift Client" icon="swift" href="https://github.com/argmaxinc/WhisperKit/tree/main/Examples/ServeCLIClient/Swift">
    Generated from OpenAPI spec
  </Card>

  <Card title="Curl Scripts" icon="terminal" href="https://github.com/argmaxinc/WhisperKit/tree/main/Examples/ServeCLIClient/Curl">
    Lightweight shell script examples
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Server won't start - BUILD_ALL=1 required">
    The server requires special build flags. Always use:

    ```bash theme={null}
    BUILD_ALL=1 swift run whisperkit-cli serve
    ```

    Or build once with `make build-local-server` then run normally.
  </Accordion>

  <Accordion title="Connection refused errors">
    * Check the server is running: `curl http://localhost:50060/health`
    * Verify the port isn't in use: `lsof -i :50060`
    * Try binding to all interfaces: `--host 0.0.0.0`
  </Accordion>

  <Accordion title="Model not loading">
    * Ensure model files are downloaded: `make download-model MODEL=tiny`
    * Check model path is correct: `--model-path Models/whisperkit-coreml/openai_whisper-tiny`
    * Try verbose mode: `--verbose`
  </Accordion>

  <Accordion title="Slow transcription performance">
    * Use smaller models for faster inference (tiny, base, small)
    * Check compute units configuration (see Performance Optimization)
    * Ensure audio encoder uses Neural Engine on macOS 14+
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="CLI Usage" icon="terminal" href="/advanced/cli-usage">
    Learn about command-line transcription
  </Card>

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