Getting Started

Install the speech CLI to transcribe and generate audio on your Apple Silicon Mac. Use the Swift SDK to add speech processing to macOS and iOS apps.

CLI requirements

• macOS 15+ (Sequoia or later)
• Apple Silicon (arm64)
• 8 GB RAM minimum (16 GB recommended for larger models)

Install the CLI

Homebrew (CLI)

Use native ARM Homebrew (/opt/homebrew) to install speech and the speech-server HTTP/WebSocket server.

brew install speech
speech --help

First task: transcribe an M4A file

Download the sample recording, then transcribe it in your terminal:

Connect to the internet for the first run. The selected model downloads from HuggingFace and stays cached on your Mac. After setup, you can transcribe local recordings offline with that model.

curl -fL https://soniqo.audio/audio/samples/cli/transcription-sample.m4a -o transcription-sample.m4a
speech transcribe transcription-sample.m4a --engine parakeet

Continue with the M4A-to-text guide.

Quick Start: Text-to-Speech

speech speak "Hello, world!" --output hello.wav

Run a local speech API

Start the HTTP/WebSocket server for local API requests:

speech-server --port 8080

Swift SDK

Add the Swift modules to your macOS 15+ or iOS 18+ app with Swift Package Manager.

Swift Package Manager

Add speech-swift to your Package.swift dependencies:

dependencies: [
    .package(url: "https://github.com/soniqo/speech-swift", branch: "main")
]

Then add the modules you need to your target:

.target(
    name: "MyApp",
    dependencies: [
        .product(name: "Qwen3ASR", package: "speech-swift"),
        .product(name: "Qwen3TTS", package: "speech-swift"),
        .product(name: "SpeechVAD", package: "speech-swift"),
        // ... add any modules you need
    ]
)

Available Modules

Transcribe audio with Swift

import Qwen3ASR

let model = try await Qwen3ASRModel.fromPretrained()
// audioSamples: [Float] PCM at 16 kHz (e.g. decoded from a WAV)
let text = model.transcribe(audio: audioSamples, sampleRate: 16000)
print(text)

Generate speech with Swift

import Qwen3TTS
import AudioCommon

let model = try await Qwen3TTSModel.fromPretrained()
let audio = model.synthesize(text: "Hello, world!", language: "english")
try WAVWriter.write(samples: audio, sampleRate: 24000, to: URL(filePath: "hello.wav"))

Building from Source

For a source build, install Xcode 16.3+ with the Metal Toolchain and Swift 6+. Clone the repository, build the CLI, then check the binary in the checkout:

git clone https://github.com/soniqo/speech-swift.git
cd speech-swift
make build
.build/release/speech --help

Shader builds default to macOS 15.0 and Metal 3.2, even with newer SDKs. Override these with MACOSX_DEPLOYMENT_TARGET and MLX_METAL_LANGUAGE_VERSION for custom builds; higher targets may exclude older systems. Compiler, SDK, flag, script, or source changes invalidate the cache. Failed compilation or linking preserves the previous library and cache hash.

Model Downloads

Models are downloaded automatically from HuggingFace on first use and cached in ~/Library/Caches/qwen3-speech/.

All models are downloaded from HuggingFace on first use. Approximate sizes:

Next Steps

• Continue with the M4A-to-text guide
• CLI Reference — all available commands and options
• Qwen3-ASR Guide — detailed speech-to-text documentation
• Qwen3-TTS Guide — detailed text-to-speech documentation
• API & Protocols — shared protocols and types