@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

package/pipeline/skills/shared/external/speech-recognition/SKILL.md

@@ -1,500 +1,296 @@
 ---
 name: speech-recognition
-description: "Transcribe speech to text using Apple's Speech framework. Use when implementing live microphone transcription with AVAudioEngine, recognizing recorded audio files, handling speech and microphone authorization, choosing on-device vs server-backed SFSpeechRecognizer behavior, or adopting SpeechAnalyzer, SpeechTranscriber, DictationTranscriber, AssetInventory, and async result streams on iOS 26+."
+description: "Speech framework speech-to-text: live microphone transcription with AVAudioEngine, recorded audio files, speech and microphone permission, on-device versus server SFSpeechRecognizer, iOS 26 SpeechAnalyzer with SpeechTranscriber, DictationTranscriber, SpeechDetector, AssetInventory and async results. Use when transcribing live or recorded speech or migrating to SpeechAnalyzer."
 metadata:
-  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
+  source: multi-agent-pipeline
 ---
-# Speech Recognition
-
-Transcribe live and pre-recorded audio to text using Apple's Speech framework.
-Covers `SpeechAnalyzer` / `SpeechTranscriber` (iOS 26+) and
-`SFSpeechRecognizer` (iOS 10+). Targets Swift 6.3 / iOS 26+ while preserving
-fallback guidance for apps that support older OS versions.
-
-**Scope boundary:** Use this skill for speech-to-text recognition, speech
-authorization, microphone capture plumbing, and result handling. Hand off text
-analysis, language identification after transcription, sentiment, embeddings,
-and translation to `natural-language`; hand off audio playback UI to `avkit`;
-hand off summarization or generation over transcripts to `apple-on-device-ai`.
-
-## Contents
-
-- [SpeechAnalyzer Strategy (iOS 26+)](#speechanalyzer-strategy-ios-26)
-- [SFSpeechRecognizer Setup](#sfspeechrecognizer-setup)
-- [Authorization](#authorization)
-- [Live Microphone Transcription](#live-microphone-transcription)
-- [Pre-Recorded Audio File Recognition](#pre-recorded-audio-file-recognition)
-- [On-Device vs Server Recognition](#on-device-vs-server-recognition)
-- [Handling Results](#handling-results)
-- [Common Mistakes](#common-mistakes)
-- [Review Checklist](#review-checklist)
-- [References](#references)
-
-## SpeechAnalyzer Strategy (iOS 26+)
-
-Use `SpeechAnalyzer` for modern iOS 26+ speech analysis, especially long-form
-recordings, live transcription, time-indexed transcripts, and fully on-device
-flows. Keep `SFSpeechRecognizer` for iOS 10+ deployment targets, server-backed
-locale coverage, or existing callback/delegate implementations.
-
-Read [SpeechAnalyzer patterns](references/speechanalyzer-patterns.md) when
-implementing an iOS 26+ transcription pipeline, model asset handling, volatile
-results, or file/buffer examples.
-
-### SpeechAnalyzer setup checklist
-
-1. Choose the module:
-   - `SpeechTranscriber` for the newer general-purpose on-device model.
-   - `DictationTranscriber` when `SpeechTranscriber` is unavailable for the
-     current device or locale and dictation-compatible support is acceptable.
-   - `SpeechDetector` only in conjunction with a transcriber when voice
-     activity detection is worth the accuracy/power tradeoff.
-2. Check support before creating the session:
-   - `SpeechTranscriber.isAvailable`
-   - `SpeechTranscriber.supportedLocale(equivalentTo:)`
-   - `SpeechTranscriber.installedLocales` / `supportedLocales` when showing
-     language choices.
-3. Pick a documented preset:
-   - `.transcription` for basic accurate transcription.
-   - `.progressiveTranscription` for live UI updates.
-   - `.timeIndexedProgressiveTranscription` when playback highlighting needs
-     `audioTimeRange`.
-4. Install required assets with `AssetInventory.assetInstallationRequest`.
-5. Convert live audio buffers to
-   `SpeechAnalyzer.bestAvailableAudioFormat(compatibleWith:)` before yielding
-   `AnalyzerInput`.
-6. Consume module results from their `AsyncSequence` in a separate task.
-7. Finish explicitly with `finalizeAndFinish(through:)`,
-   `finalizeAndFinishThroughEndOfInput()`, or `cancelAndFinishNow()`.
-
-Do not use an `offlineTranscription` preset; Apple does not document one.
-Finishing an `AsyncStream` input sequence does not finish the analyzer session.
-
-## SFSpeechRecognizer Setup
-
-### Creating a recognizer with locale
+
+# Speech recognition
+
+The Speech framework has two generations. `SpeechAnalyzer` with
+`SpeechTranscriber` arrived in iOS 26 and runs entirely on device with async
+result streams. `SFSpeechRecognizer` dates back to iOS 10 and uses callbacks.
+Code here assumes Swift 6.3 and an iOS 26 deployment target, with notes for
+older targets.
+
+## Scope
+
+This skill covers speech permissions, microphone capture plumbing,
+transcription and result handling. Hand off:
+
+| Need | Skill |
+|---|---|
+| Analyzing the transcript: language, sentiment, entities, embeddings, translation | `natural-language` |
+| Playback UI and captions | `avkit` |
+| Summaries or other generation over a transcript | `apple-on-device-ai` |
+
+## Which API
+
+Choose `SpeechAnalyzer` on iOS 26+ for long recordings, live transcription,
+transcripts indexed by time, and flows that must stay on the device.
+
+Keep `SFSpeechRecognizer` when the app still supports older systems, when a
+locale is only covered by server recognition, or when a working
+callback-based implementation does not need to change yet.
+
+### SpeechAnalyzer checklist
+
+1. **Pick the module.** `SpeechTranscriber` is the newer general-purpose
+   on-device model. Fall back to `DictationTranscriber` when the transcriber
+   is unavailable for the device or locale and dictation-style output is
+   acceptable. Add `SpeechDetector` (voice activity detection) only alongside
+   a transcriber, and only if the power saving is worth the risk to accuracy.
+2. **Check support.** `SpeechTranscriber.isAvailable` and
+   `SpeechTranscriber.supportedLocale(equivalentTo:)`; language pickers read
+   `installedLocales` and `supportedLocales`.
+3. **Pick a preset.** `.transcription` for plain accurate text,
+   `.progressiveTranscription` for live UI, `.timeIndexedProgressiveTranscription`
+   when playback should highlight words through `audioTimeRange`.
+4. **Install assets** with `AssetInventory.assetInstallationRequest(supporting:)`.
+5. **Convert live audio** to `SpeechAnalyzer.bestAvailableAudioFormat(compatibleWith:)`
+   before yielding `AnalyzerInput` values.
+6. **Read results** from the module's async sequence in a separate task.
+7. **Finish on purpose** with `finalizeAndFinish(through:)`,
+   `finalizeAndFinishThroughEndOfInput()` or `cancelAndFinishNow()`.
+
+There is no `.offlineTranscription` preset, whatever some samples claim.
+Closing your `AsyncStream` of input does not finish the analyzer either.
+Full code is in [analyzer recipes](references/speechanalyzer-patterns.md).
+
+## SFSpeechRecognizer setup
 
 ```swift
 import Speech
 
-// Default locale (user's current language)
-let recognizer = SFSpeechRecognizer()
+let deviceLocale = SFSpeechRecognizer()                               // current locale
+let british = SFSpeechRecognizer(locale: Locale(identifier: "en-GB"))  // specific locale
 
-// Specific locale
-let recognizer = SFSpeechRecognizer(locale: Locale(identifier: "en-US"))
-
-// Check if recognition is available for this locale
-guard let recognizer, recognizer.isAvailable else {
-    print("Speech recognition not available")
+guard let recognizer = british, recognizer.isAvailable else {
+    // show "speech input unavailable"
     return
 }
 ```
 
-### Monitoring availability changes
+The initializer is failable. Availability also changes at runtime (network
+loss, locale switch), so adopt `SFSpeechRecognizerDelegate`. The callback runs
+on the recognizer's `queue`, the main queue unless you change it, so a
+main-actor model can conform with `@preconcurrency`; without it Swift 6
+rejects the conformance as crossing into main-actor code.
 
 ```swift
-final class SpeechManager: NSObject, SFSpeechRecognizerDelegate {
-    private let recognizer = SFSpeechRecognizer()!
-
-    override init() {
-        super.init()
-        recognizer.delegate = self
-    }
+@MainActor
+final class DictationModel: NSObject, @preconcurrency SFSpeechRecognizerDelegate {
+    var recordButtonEnabled = false
 
-    func speechRecognizer(
-        _ speechRecognizer: SFSpeechRecognizer,
-        availabilityDidChange available: Bool
-    ) {
-        // Update UI  -  disable record button when unavailable
+    func speechRecognizer(_ source: SFSpeechRecognizer, availabilityDidChange isUsable: Bool) {
+        recordButtonEnabled = isUsable
     }
 }
 ```
 
 ## Authorization
 
-Request **both** speech recognition and microphone permissions before starting
-live transcription. Add these keys to `Info.plist`:
+Live transcription needs **two** permissions: speech recognition and the
+microphone. Add both Info.plist strings:
 
 - `NSSpeechRecognitionUsageDescription`
 - `NSMicrophoneUsageDescription`
 
 ```swift
-import Speech
-import AVFoundation
-
-func requestPermissions() async -> Bool {
-    let speechStatus = await withCheckedContinuation { continuation in
+func speechAllowed() async -> Bool {
+    await withCheckedContinuation { continuation in
         SFSpeechRecognizer.requestAuthorization { status in
-            continuation.resume(returning: status)
-        }
-    }
-    guard speechStatus == .authorized else { return false }
-
-    let micStatus: Bool
-    if #available(iOS 17, *) {
-        micStatus = await AVAudioApplication.requestRecordPermission()
-    } else {
-        micStatus = await withCheckedContinuation { continuation in
-            AVAudioSession.sharedInstance().requestRecordPermission { granted in
-                continuation.resume(returning: granted)
-            }
+            continuation.resume(returning: status == .authorized)
         }
     }
-    return micStatus
+}
+
+func microphoneAllowed() async -> Bool {
+    await AVAudioApplication.requestRecordPermission()   // iOS 17+
 }
 ```
 
-## Live Microphone Transcription
+Before iOS 17, ask through `AVAudioSession.sharedInstance().requestRecordPermission(_:)`.
 
-The standard pattern: `AVAudioEngine` captures microphone audio → buffers are
-appended to `SFSpeechAudioBufferRecognitionRequest` → results stream in.
+## Live microphone transcription
+
+`AVAudioEngine` captures audio, a tap appends each buffer to an
+`SFSpeechAudioBufferRecognitionRequest`, and the recognition task reports
+results.
 
 ```swift
-import Speech
 import AVFoundation
+import Speech
 
-final class LiveTranscriber {
-    private let recognizer = SFSpeechRecognizer(locale: Locale(identifier: "en-US"))!
-    private let audioEngine = AVAudioEngine()
-    private var recognitionRequest: SFSpeechAudioBufferRecognitionRequest?
-    private var recognitionTask: SFSpeechRecognitionTask?
+@MainActor
+final class LiveCaptioner {
+    private let engine = AVAudioEngine()
+    private let recognizer = SFSpeechRecognizer(locale: Locale(identifier: "en-AU"))
+    private var request: SFSpeechAudioBufferRecognitionRequest?
+    private var task: SFSpeechRecognitionTask?
+    private(set) var caption = ""
 
-    func startTranscribing() throws {
-        // Cancel any in-progress task
-        recognitionTask?.cancel()
-        recognitionTask = nil
+    func begin() throws {
+        task?.cancel()
+        task = nil
 
-        // Configure audio session
-        let audioSession = AVAudioSession.sharedInstance()
-        try audioSession.setCategory(.record, mode: .measurement, options: .duckOthers)
-        try audioSession.setActive(true, options: .notifyOthersOnDeactivation)
+        let session = AVAudioSession.sharedInstance()
+        try session.setCategory(.record, mode: .measurement, options: [.duckOthers])
+        try session.setActive(true, options: .notifyOthersOnDeactivation)
 
-        // Create request
         let request = SFSpeechAudioBufferRecognitionRequest()
         request.shouldReportPartialResults = true
-        self.recognitionRequest = request
-
-        // Start recognition task
-        recognitionTask = recognizer.recognitionTask(with: request) { result, error in
-            if let result {
-                let text = result.bestTranscription.formattedString
-                print("Transcription: \(text)")
-
-                if result.isFinal {
-                    self.stopTranscribing()
-                }
-            }
-            if let error {
-                print("Recognition error: \(error)")
-                self.stopTranscribing()
+        self.request = request
+
+        task = recognizer?.recognitionTask(with: request) { [weak self] result, error in
+            let text = result?.bestTranscription.formattedString
+            let done = error != nil || (result?.isFinal ?? false)
+            Task { @MainActor in
+                guard let self else { return }
+                if let text { self.caption = text }
+                if done { self.end() }
             }
         }
 
-        // Install audio tap
-        let inputNode = audioEngine.inputNode
-        let recordingFormat = inputNode.outputFormat(forBus: 0)
-        inputNode.installTap(onBus: 0, bufferSize: 1024, format: recordingFormat) {
-            buffer, _ in
+        feedMicrophone(engine.inputNode, into: request)
+        engine.prepare()
+        try engine.start()
+    }
+
+    // nonisolated so the tap closure is not main-actor isolated: it runs on the audio thread
+    private nonisolated func feedMicrophone(_ mic: AVAudioInputNode,
+                                            into request: SFSpeechAudioBufferRecognitionRequest) {
+        let native = mic.outputFormat(forBus: 0)
+        mic.installTap(onBus: 0, bufferSize: 2048, format: native) { buffer, _ in
             request.append(buffer)
         }
-
-        audioEngine.prepare()
-        try audioEngine.start()
     }
 
-    func stopTranscribing() {
-        audioEngine.stop()
-        audioEngine.inputNode.removeTap(onBus: 0)
-        recognitionRequest?.endAudio()
-        recognitionRequest = nil
-        recognitionTask?.cancel()
-        recognitionTask = nil
+    func end() {
+        engine.stop()
+        engine.inputNode.removeTap(onBus: 0)
+        request?.endAudio()
+        request = nil
+        task?.cancel()
+        task = nil
     }
 }
 ```
 
-## Pre-Recorded Audio File Recognition
+The tap block runs on a real-time audio thread. Under Swift 6 a closure
+written inside a `@MainActor` method inherits that isolation and traps when
+called elsewhere, which is why the tap is installed from a `nonisolated`
+helper.
 
-Use `SFSpeechURLRecognitionRequest` for audio files on disk:
+## Transcribing a recorded file
 
 ```swift
-func transcribeFile(at url: URL) async throws -> String {
-    guard let recognizer = SFSpeechRecognizer(), recognizer.isAvailable else {
-        throw SpeechError.unavailable
-    }
+func transcribeFile(at url: URL, with recognizer: SFSpeechRecognizer) async throws -> String {
     let request = SFSpeechURLRecognitionRequest(url: url)
     request.shouldReportPartialResults = false
 
-    return try await withCheckedThrowingContinuation { continuation in
-        var didResume = false
-        recognizer.recognitionTask(with: request) { result, error in
-            guard !didResume else { return }
-            if let error {
-                didResume = true
-                continuation.resume(throwing: error)
-            } else if let result, result.isFinal {
-                didResume = true
-                continuation.resume(
-                    returning: result.bestTranscription.formattedString
-                )
+    let text: String = try await withCheckedThrowingContinuation { continuation in
+        var settled = false
+        recognizer.recognitionTask(with: request) { outcome, failure in
+            guard !settled else { return }
+            if let failure {
+                settled = true
+                continuation.resume(throwing: failure)
+            } else if let outcome, outcome.isFinal {
+                settled = true
+                continuation.resume(returning: outcome.bestTranscription.formattedString)
             }
         }
     }
+    return text
 }
 ```
 
-## On-Device vs Server Recognition
-
-`SFSpeechRecognizer` can use on-device recognition for supported locales on
-iOS 13+. If `supportsOnDeviceRecognition` is false, the recognizer requires a
-network connection. `requiresOnDeviceRecognition` only has effect when the
-recognizer supports it.
+The `settled` flag stops a second resume if the handler fires again.
 
-```swift
-let recognizer = SFSpeechRecognizer(locale: Locale(identifier: "en-US"))!
+## On device or on the server
 
-// Check if on-device is supported for this locale
-if recognizer.supportsOnDeviceRecognition {
-    let request = SFSpeechAudioBufferRecognitionRequest()
-    request.requiresOnDeviceRecognition = true  // Force on-device
-}
-```
-
-`SFSpeechRecognizer` requests may still be a poor fit for long-form capture.
-Apple documents a roughly one-minute task limit for speech recognition and
-other service limits. For long recordings on iOS 26+, prefer `SpeechAnalyzer`;
-otherwise chunk or restart recognition before the limit and preserve transcript
-state across tasks.
-
-## Handling Results
-
-### Partial vs final results
+- Since iOS 13 many locales can be recognized on the device. When
+  `supportsOnDeviceRecognition` is `false`, recognition needs the network.
+- `requiresOnDeviceRecognition = true` is only honoured when the recognizer
+  supports it, so check first:
 
 ```swift
-let request = SFSpeechAudioBufferRecognitionRequest()
-request.shouldReportPartialResults = true  // default is true
-
-recognizer.recognitionTask(with: request) { result, error in
-    guard let result else { return }
-
-    if result.isFinal {
-        // Final transcription  -  recognition is complete
-        let final = result.bestTranscription.formattedString
-    } else {
-        // Partial result  -  may change as more audio is processed
-        let partial = result.bestTranscription.formattedString
-    }
-}
-```
-
-### Accessing alternative transcriptions and confidence
-
-```swift
-recognizer.recognitionTask(with: request) { result, error in
-    guard let result else { return }
-
-    // Best transcription
-    let best = result.bestTranscription
-
-    // All alternatives (sorted by confidence, descending)
-    for transcription in result.transcriptions {
-        for segment in transcription.segments {
-            print("\(segment.substring): \(segment.confidence)")
-        }
-    }
-}
-```
-
-### Adding punctuation (iOS 16+)
-
-```swift
-let request = SFSpeechAudioBufferRecognitionRequest()
-request.addsPunctuation = true
-```
-
-### Contextual strings
-
-Improve recognition of domain-specific terms:
-
-```swift
-let request = SFSpeechAudioBufferRecognitionRequest()
-request.contextualStrings = ["SwiftUI", "Xcode", "CloudKit"]
-```
-
-## Common Mistakes
-
-### Not requesting both speech and microphone authorization
-
-```swift
-// ❌ DON'T: Only request speech authorization for live audio
-SFSpeechRecognizer.requestAuthorization { status in
-    // Missing microphone permission  -  audio engine will fail
-    self.startRecording()
-}
-
-// ✅ DO: Request both permissions before recording
-SFSpeechRecognizer.requestAuthorization { status in
-    guard status == .authorized else { return }
-    AVAudioSession.sharedInstance().requestRecordPermission { granted in
-        guard granted else { return }
-        self.startRecording()
-    }
-}
-```
-
-### Not handling availability changes
-
-```swift
-// ❌ DON'T: Assume recognizer stays available after initial check
-let recognizer = SFSpeechRecognizer()!
-// Recognition may fail if network drops or locale changes
-
-// ✅ DO: Monitor availability via delegate
-recognizer.delegate = self
-func speechRecognizer(
-    _ speechRecognizer: SFSpeechRecognizer,
-    availabilityDidChange available: Bool
-) {
-    recordButton.isEnabled = available
-}
-```
-
-### Not stopping the audio engine when recognition ends
-
-```swift
-// ❌ DON'T: Leave audio engine running after recognition finishes
-recognizer.recognitionTask(with: request) { result, error in
-    if result?.isFinal == true {
-        // Audio engine still running, wasting resources and battery
-    }
-}
-
-// ✅ DO: Clean up all audio resources
-recognizer.recognitionTask(with: request) { result, error in
-    if result?.isFinal == true || error != nil {
-        self.audioEngine.stop()
-        self.audioEngine.inputNode.removeTap(onBus: 0)
-        self.recognitionRequest?.endAudio()
-        self.recognitionRequest = nil
-    }
-}
-```
-
-### Assuming on-device recognition is available for all locales
-
-```swift
-// ❌ DON'T: Force on-device without checking support
-let request = SFSpeechAudioBufferRecognitionRequest()
-request.requiresOnDeviceRecognition = true // Ignored unless the recognizer supports it
-
-// ✅ DO: Check support before requiring on-device
 if recognizer.supportsOnDeviceRecognition {
     request.requiresOnDeviceRecognition = true
 } else {
-    // Fall back to server-based or inform user
-}
-```
-
-### Not handling the one-minute recognition limit
-
-```swift
-// ❌ DON'T: Start one long continuous recognition session
-func startRecording() {
-    // SFSpeechRecognizer tasks can be cut off after about 60 seconds
-}
-
-// ✅ DO: roll the segment before the limit and let cleanup end audio once
-func scheduleRecognitionRollover() {
-    recognitionTimer = Timer.scheduledTimer(withTimeInterval: 55, repeats: false) { [weak self] _ in
-        self?.commitLatestPartialText()
-        self?.stopTranscribing()     // owns endAudio(), tap removal, and task cancellation
-        try? self?.startTranscribing()
-    }
-}
-```
-`SFSpeechRecognitionTask` exposes `finish()`, `cancel()`, `state`, and `error`;
-do not invent task properties such as `recognitionTask` to restart work. Keep
-the active `SFSpeechAudioBufferRecognitionRequest` in your manager and call
-`endAudio()` from one cleanup path only.
-
-### Treating SpeechAnalyzer input completion as session completion
-
-```swift
-// ❌ DON'T: Only finish the AsyncStream and expect result streams to close
-inputBuilder.finish()
-
-// ✅ DO: explicitly finish or cancel the analyzer session
-let lastSampleTime = try await analyzer.analyzeSequence(inputSequence)
-if let lastSampleTime {
-    try await analyzer.finalizeAndFinish(through: lastSampleTime)
-} else {
-    try analyzer.cancelAndFinishNow()
-}
-```
-
-### Duplicating volatile SpeechAnalyzer results
-
-```swift
-// ✅ Replace volatile text with the finalized result for the same audio range
-for try await result in transcriber.results {
-    if result.isFinal {
-        volatileTranscript = AttributedString()
-        finalizedTranscript.append(result.text)
-    } else {
-        volatileTranscript = result.text
-    }
-}
-```
-
-### Creating multiple simultaneous recognition tasks
-
-```swift
-// ❌ DON'T: Start a new task without canceling the previous one
-func startRecording() {
-    recognitionTask = recognizer.recognitionTask(with: request) { ... }
-    // Previous task is still running  -  undefined behavior
-}
-
-// ✅ DO: Cancel existing task before creating a new one
-func startRecording() {
-    recognitionTask?.cancel()
-    recognitionTask = nil
-    recognitionTask = recognizer.recognitionTask(with: request) { ... }
+    // tell the user audio will be sent for recognition, or pick another locale
 }
 ```
 
-## Review Checklist
-
-- [ ] `NSSpeechRecognitionUsageDescription` is in Info.plist
-- [ ] `NSMicrophoneUsageDescription` is in Info.plist (if using live audio)
-- [ ] Authorization is requested before starting recognition
-- [ ] `SFSpeechRecognizerDelegate` is set to handle `availabilityDidChange`
-- [ ] Audio engine is stopped and tap removed when recognition ends
-- [ ] `recognitionRequest.endAudio()` is called when done recording
-- [ ] Previous `recognitionTask` is canceled before starting a new one
-- [ ] `supportsOnDeviceRecognition` is checked before requiring on-device mode
-- [ ] Partial results are handled separately from final (`isFinal`) results
-- [ ] `SFSpeechRecognizer` one-minute/service limits are accounted for
-- [ ] For iOS 26+: `AssetInventory` assets are installed before using `SpeechAnalyzer`
-- [ ] For iOS 26+: `SpeechTranscriber.isAvailable` and locale support are checked
-- [ ] For iOS 26+: live buffers are converted to the analyzer-compatible format
-- [ ] For iOS 26+: analyzer sessions are explicitly finalized or canceled
-- [ ] For iOS 26+: volatile results are replaced by finalized results, not duplicated
+- Server-backed recognition has limits, including roughly one minute of
+  audio per task. On iOS 26+ prefer `SpeechAnalyzer` for long recordings;
+  otherwise split the audio and restart before the limit, carrying the
+  transcript forward.
+
+## Results
+
+- `shouldReportPartialResults` defaults to `true`. Partial text can still
+  change; `isFinal` marks the last result of a task.
+- `result.transcriptions` holds alternatives, most confident first. Each
+  transcription's `segments` expose `substring` and `confidence`.
+- `request.addsPunctuation = true` (iOS 16+) inserts punctuation.
+- `request.contextualStrings = ["Kubernetes", "Grafana"]` nudges the
+  recognizer toward domain vocabulary.
+
+## Common mistakes
+
+- **Asking only for speech permission.** Live audio also needs the
+  microphone, or the engine fails to start. Request both before recording.
+- **Ignoring availability changes.** Watch the delegate; network loss or a
+  locale change can make the recognizer unavailable.
+- **Leaving the engine running.** On a final result or an error, stop the
+  engine, remove the tap and end the audio.
+- **Forcing on-device without support.** The flag is ignored; check
+  `supportsOnDeviceRecognition` and fall back or inform the user.
+- **Running into the one-minute ceiling.** Roll over before it, for example
+  with a timer at 55 seconds: keep the latest partial text, stop through the
+  single cleanup path (the only place that calls `endAudio()`, removes the tap
+  and cancels), then start a fresh task.
+- **Inventing task APIs.** `SFSpeechRecognitionTask` offers `finish()`,
+  `cancel()`, `state` and `error`, nothing to restart itself. Hold the live
+  request as a property of the owning object, and let exactly one code path
+  call `endAudio()`.
+- **Assuming the analyzer finishes when input ends.** Finishing your input
+  builder does not close result streams. After `analyzeSequence(_:)` returns
+  the last sample time, call `finalizeAndFinish(through:)`; if there is none,
+  `cancelAndFinishNow()`.
+- **Duplicating volatile text.** When a result is final, clear the volatile
+  part and append the final text; otherwise replace the volatile part.
+- **Overlapping tasks.** Cancel the previous recognition task before creating
+  a new one; concurrent tasks behave unpredictably.
+
+## Review checklist
+
+- [ ] `NSSpeechRecognitionUsageDescription` present, plus `NSMicrophoneUsageDescription` for live audio
+- [ ] Authorization requested before any recognition
+- [ ] Delegate reacts to `availabilityDidChange`
+- [ ] Engine stopped, tap removed and `endAudio()` called when finished
+- [ ] Previous task cancelled before a new one starts
+- [ ] `supportsOnDeviceRecognition` checked before requiring on-device
+- [ ] Partial and final results handled differently
+- [ ] Task duration and service limits planned for
+- [ ] iOS 26+: assets installed through `AssetInventory`, `isAvailable` and locale support checked, live buffers converted, sessions finalized or cancelled, volatile text replaced rather than duplicated
 
 ## References
 
-- [Speech framework](https://sosumi.ai/documentation/speech)
-- [SpeechAnalyzer](https://sosumi.ai/documentation/speech/speechanalyzer)
-- [SpeechTranscriber](https://sosumi.ai/documentation/speech/speechtranscriber)
-- [SpeechTranscriber.Preset](https://sosumi.ai/documentation/speech/speechtranscriber/preset)
-- [DictationTranscriber](https://sosumi.ai/documentation/speech/dictationtranscriber)
-- [SpeechDetector](https://sosumi.ai/documentation/speech/speechdetector)
-- [SFSpeechRecognizer](https://sosumi.ai/documentation/speech/sfspeechrecognizer)
-- [SFSpeechAudioBufferRecognitionRequest](https://sosumi.ai/documentation/speech/sfspeechaudiobufferrecognitionrequest)
-- [SFSpeechURLRecognitionRequest](https://sosumi.ai/documentation/speech/sfspeechurlrecognitionrequest)
-- [SFSpeechRecognitionResult](https://sosumi.ai/documentation/speech/sfspeechrecognitionresult)
-- [SFSpeechRecognitionRequest](https://sosumi.ai/documentation/speech/sfspeechrecognitionrequest)
-- [AssetInventory](https://sosumi.ai/documentation/speech/assetinventory)
-- [Asking Permission to Use Speech Recognition](https://sosumi.ai/documentation/speech/asking-permission-to-use-speech-recognition)
-- [Recognizing Speech in Live Audio](https://sosumi.ai/documentation/speech/recognizing-speech-in-live-audio)
-- [Bring advanced speech-to-text to your app with SpeechAnalyzer](https://sosumi.ai/videos/play/wwdc2025/277)
+- [analyzer recipes](references/speechanalyzer-patterns.md)
+- https://developer.apple.com/documentation/speech
+- https://developer.apple.com/documentation/speech/speechanalyzer
+- https://developer.apple.com/documentation/speech/speechtranscriber
+- https://developer.apple.com/documentation/speech/speechtranscriber/preset
+- https://developer.apple.com/documentation/speech/dictationtranscriber
+- https://developer.apple.com/documentation/speech/speechdetector
+- https://developer.apple.com/documentation/speech/assetinventory
+- https://developer.apple.com/documentation/speech/sfspeechrecognizer
+- https://developer.apple.com/documentation/speech/sfspeechrecognitionrequest
+- https://developer.apple.com/documentation/speech/sfspeechaudiobufferrecognitionrequest
+- https://developer.apple.com/documentation/speech/sfspeechurlrecognitionrequest
+- https://developer.apple.com/documentation/speech/sfspeechrecognitionresult
+- Apple articles on requesting speech-recognition permission and on recognizing live audio, in the Speech documentation
+- WWDC25 session 277 (SpeechAnalyzer introduction)