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.

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

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.

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

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

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.