iOS 26 SpeechAnalyzer Live Mic：設定、結果和故障排除

SpeechTranscriber提供執行時裝置和區域設定檢查。 僅檢查iOS版本是不夠的。 以下幫助程式返回配置的轉錄器、分析器和音訊格式，或丟擲特定的準備錯誤。

下載完整的Swift準備助手。 完整的檔案包括匯入、結果和錯誤型別，以及下面討論的DictationTranscriber提示助手。 這是一個設定元件，而不是完整的錄音應用程式。

@available(iOS 26.0, *)
@MainActor
public func prepareSpeechAnalyzer(
    requestedLocale: Locale,
    naturalFormat: AVAudioFormat? = nil
) async throws -> PreparedSpeechAnalyzer {
    guard SpeechTranscriber.isAvailable else {
        throw SpeechPreparationError.deviceUnavailable
    }
    guard let locale = await SpeechTranscriber.supportedLocale(
        equivalentTo: requestedLocale
    ) else {
        throw SpeechPreparationError.unsupportedLocale
    }

    let transcriber = SpeechTranscriber(
        locale: locale,
        preset: .progressiveTranscription
    )
    // The system may already have the asset; nil means no install is needed.
    // A request can automatically reserve the locale or throw if no slot is free.
    if let request = try await AssetInventory.assetInstallationRequest(
        supporting: [transcriber]
    ) {
        try await request.downloadAndInstall()
    }
    try Task.checkCancellation()
    guard await AssetInventory.status(forModules: [transcriber]) == .installed else {
        throw SpeechPreparationError.assetsNotInstalled
    }
    guard let format = await SpeechAnalyzer.bestAvailableAudioFormat(
        compatibleWith: [transcriber], considering: naturalFormat
    ) else {
        throw SpeechPreparationError.noCompatibleFormat
    }

    let analyzer = SpeechAnalyzer(modules: [transcriber])
    try await analyzer.prepareToAnalyze(in: format)
    return PreparedSpeechAnalyzer(
        locale: locale, transcriber: transcriber,
        analyzer: analyzer, audioFormat: format
    )
}

AssetInventory管理共享系統模型。 系統或其他應用程式可能已經安裝了模型。安裝請求在不需要安裝時返回nil；否則，它可以保留區域設定並啟動下載。 預約限制也可能產生錯誤。 管理應用程式功能的預約，並在不再需要時釋出區域設定，而不是釋出應用程式中其他地方仍在使用的模型。

在下線之前，準備所需的區域設定並驗證準備情況。 模型資產在應用程式捆綁包之外，但仍然消耗系統儲存，並且可能會隨著時間的推移而變化。 在主機使用者介面中顯示下載進度和取消。 “裝置識別”並不意味著“不需要準備或網路訪問。”

AVAudioEngine microphone tap
  -> owned PCM / conversion for the selected format
  -> AsyncStream<AnalyzerInput>
  -> SpeechAnalyzer + SpeechTranscriber
  -> result consumer and UI state

啟用音訊會話後，檢查輸入節點的實際格式。 不要硬編碼取樣率，因為裝置或路由以前經常使用該速率。 適當時將自然格式傳遞給bestAvailableAudioFormat(compatibleWith:considering:)，並拆開其可選結果。 Apple記錄了分析儀沒有透明地重新取樣或轉換輸入。

儲存庫的AudioBufferConverter返回已匹配的緩衝區不變，並在格式不同時使用AVAudioConverter。 不匹配的格式需要轉換，而不是作為每個緩衝區的全面額外步驟。 檢查輸出幀長度並報告轉換錯誤；無聲刪除每個失敗的緩衝區可以使錄製使用者介面看起來健康，同時不產生文字。

為排隊的音訊提供明確的所有權政策。 即使格式已經匹配，更新後的樣本轉換器也會返回獨立的PCM儲存，因此以後重複使用輸入不會覆蓋排隊的音訊。 音訊回撥提供的緩衝區不得假定在回撥返回後保持不變。 如果您將其排隊供以後使用，請安排一個合適的自有副本或控制緩衝壽命的管道。 將每個緩衝區UI突變放在音訊回撥中。 對於生產，還要決定如何繫結排隊工作，並處理超載或路由更改。

在Swift 6中，捕獲區域性變數本身並不能證明管道是執行緒安全的。 當前樣本的轉換器有一個單處理執行緒合同和一個私有鎖保護的@unchecked Sendable支架，用於一個轉換器回撥。 它並不能使所有PCM緩衝區或轉換器普遍安全跨執行緒共享。 在調整樣品之前，請先閱讀該合同。

不能說新的 Speech API 不支援上下文詞彙。Apple 為 DictationTranscriber 提供了 AnalysisContext.contextualStrings 的文件。文件建議使用簡短短語，所有標籤下的短語總數最多為 100 個。這並不意味著同樣的提示也能用於定製 SpeechTranscriber。

// For an analyzer configured with DictationTranscriber.
let context = AnalysisContext()
context.contextualStrings[.general] = ["Obsidian", "Yurica"]
try await analyzer.setContext(context)

setContext(_:)替換了當前上下文，因此在需要時保留或合併任何現有的應用程式上下文。 可下載的助手拒絕超過100的短語，而不是默默地截斷它們。 短語提示與也為DictationTranscriber記錄的自定義語言模型選項不同，兩者都不保證正確識別每個名稱。 選擇並測試您的應用程式所需的模組和語言。

對於診斷，從階段定時、幀數、區域設定和錯誤資訊開始。 每個日誌條目都不需要原始錄音和可識別的文字。 如果使用者共享複製品，請要求提供簡短的非敏感測試短語和相關配置，而不是私人對話。