GETTING_STARTED.md

# Getting Started

This guide explains how to reproduce the ASR-only iPhone package from a fresh
checkout.

## 1. Install Xcode and XcodeGen

Install the full Xcode app from the Mac App Store. Command Line Tools alone are
not enough for iPhone signing, Simulator runtimes, or the full Swift test stack.

```bash
sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
sudo xcodebuild -runFirstLaunch
sudo xcodebuild -license accept
xcodebuild -version

brew install xcodegen
xcodegen --version
```

## 2. Check the Swift Package

```bash
cd SpeechKit
swift package resolve
swift build
swift run dev-check
swift test
cd ..
```

`dev-check` is intentionally lightweight. It validates asset-manifest logic,
mel bucket selection, and audio-token accounting without loading the 400 MB
model bundle.

## 3. Run File Transcription on macOS

`asrkit-cli --file` uses the same public `ASRTranscriber` API as apps.

```bash
cd SpeechKit
swift run -c release asrkit-cli .. --file /path/to/audio.wav
swift run -c release asrkit-cli .. --file /path/to/audio.wav --repeat 10
cd ..
```

The model bundle is expected at `dist/ASRModels.bundle`.

## 4. Generate the iOS Demo

```bash
cd ASRDemo
xcodegen generate
open ASRDemo.xcodeproj
```

`ASRDemo/project.yml` is the source of truth. Regenerate the project after
changing resources, build settings, or dependencies.

## 5. Configure Signing

In Xcode:

1. Open the navigator with `Cmd+1`.
2. Select the top-level blue `ASRDemo` project item.
3. Select the `ASRDemo` target.
4. Open `Signing & Capabilities`.
5. Choose your Apple Developer team.
6. Change the bundle identifier from `com.example.asrdemo` to a unique value.

The generated Info.plist includes `NSMicrophoneUsageDescription`, so the
microphone permission prompt is available when recording.

## 6. Test on Simulator

Choose an iOS Simulator destination and press Run. Simulator is useful for:

- Launch and resource packaging checks.
- Basic UI validation.
- Smoke-testing model loading and transcription.
- Watching memory trends during repeated runs.

Simulator memory footprint is not equivalent to a real iPhone. The Simulator is
a macOS process and does not follow iOS memory pressure and Jetsam rules. Use a
physical iPhone for final footprint, thermal, and power validation.

## 7. Test on iPhone

1. Connect the iPhone with USB.
2. Trust the Mac on the iPhone.
3. Enable Developer Mode if iOS asks for it.
4. In Xcode, open `Window` -> `Devices and Simulators` and confirm the phone is paired.
5. Select the physical iPhone as the run destination.
6. Run the `ASRDemo` scheme.

First launch can be slow because Core ML loads and compiles ANE programs. Later
launches usually reuse the system cache.

## 8. Use the Demo

The public demo is ASR-only:

- `Record`: captures microphone audio, then transcribes once after stop.
- `Repeat Last 10x`: re-runs the last recording ten times for quick stability
  checks on a physical iPhone.

The public package does not include sample media; use `asrkit-cli --file` for
file tests without modifying the app target.

The demo also shows:

- Stage timings for mel extraction, audio tower, decoder, and total latency.
- Token diagnostics for short-output debugging.
- Process memory footprint, peak footprint, CPU, thermal state, battery state,
  and a rough whole-device power estimate.

Streaming and VAD are not included in this ASR-only build.

## 9. Run the ANE Benchmark

```bash
cd ANEBench
xcodegen generate
open ANEBench.xcodeproj
```

Sign the `ANEBench` target the same way as `ASRDemo`, then run it on a physical
iPhone. The benchmark loads `dist/ASRModels.bundle/tower.mlmodelc` and measures
the `tower_5s`, `tower_10s`, and `tower_30s` Core ML functions with
`.cpuAndNeuralEngine`.

The sustained-load button is intended for Instruments Energy / Power profiling.
It is not representative of normal one-shot ASR duty cycle.