# SpeechKit ASR

On-device speech recognition SDK for iOS 18+ / macOS 15+. Runs
Audio8-ASR-0.1B locally: Apple Neural Engine for the audio encoder, CPU int4
for the language-model decoder. No network request is required by the SDK.

The public demo also exposes process memory footprint, peak footprint, CPU,
thermal state, battery state, and a rough whole-device power estimate for
device-side validation.

## Installation

### 1. Add the package

```swift
dependencies: [
    .package(path: "../SpeechKit"),   // or the git URL + version once hosted
]
targets: [
    .target(name: "YourApp", dependencies: [
        .product(name: "SpeechKit", package: "SpeechKit"),
    ]),
]
```

### 2. Add the model bundle

Build it once (`python3 Scripts/make_asset_bundle.py`) -> `dist/ASRModels.bundle`
(~437 MB, models pre-compiled to `.mlmodelc`). Drag the bundle into your app
target as a **folder reference** (blue icon), or download it on first launch
and pass its URL to `ASRTranscriber(bundleURL:)`.

### 3. Info.plist

Only needed if you capture the microphone yourself:
`NSMicrophoneUsageDescription`.

## Usage

### One-shot transcription

```swift
import SpeechKit

let transcriber = try ASRTranscriber()      // finds ASRModels.bundle in main bundle
transcriber.warmUp()                        // optional; off main thread

let result = try transcriber.transcribe(samples)   // [Float], 16 kHz mono
print(result.text, result.timings.total)

// Async, with cancellation:
let token = ASRTranscriber.CancellationToken()
let result = try await transcriber.transcribe(samples, cancellation: token)

// Any audio file:
let result = try transcriber.transcribeFile(url)
```

Streaming and VAD are not part of this ASR-only build. Capture an utterance,
convert it to 16 kHz mono Float32, then call `transcribe`.

## Error handling

Every API throws `SpeechError` (SpeechCore). Cases cover asset validation
(`assetCorrupted`, `assetSchemaUnsupported`), audio input (`audioTooShort`),
inference (`inferenceFailed`, `promptTooLong`), and `cancelled`.

Pass `Options.verifyAssets = true` on the first launch after install/update to
SHA-256-check every asset (~1-2 s), then persist a flag and skip it.

## Threading contract

- `ASRTranscriber` methods are thread-safe; inference is serialized internally.
- Synchronous `transcribe` blocks; never call from the main thread.
- Async callbacks resume from an internal queue; dispatch to main for UI.

## Constraints

| | |
|---|---|
| Language | Model-defined |
| Audio window | 30 s max per call |
| First launch | ANE compilation ~30-60 s (system-cached afterwards); `warmUp()` recommended |
| Memory | ~600 MB resident with models loaded |
| Min OS | iOS 18 / macOS 15 (multifunction Core ML models) |

## Regression testing

```bash
swift run dev-check                              # lightweight local smoke check
swift test                                       # full Xcode recommended
swift run -c release asrkit-cli <workspace-dir>   # numeric regression vs Python refs
swift run -c release asrkit-cli <workspace-dir> --stress   # 100-pass memory check
swift run -c release asrkit-cli <workspace-dir> --file /path/to/audio.wav --repeat 10
```

`dev-check` does not require model assets and is the recommended first check on
a fresh machine. Some Command Line Tools-only installations cannot expose the
Apple Testing/XCTest frameworks cleanly; install and select full Xcode before
using `swift test`.