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记录的自定义语言模型选项不同，两者都不保证正确识别每个名称。 选择并测试您的应用程序所需的模块和语言。

对于诊断，从阶段定时、帧数、区域设置和错误信息开始。 每个日志条目都不需要原始录音和可识别的文本。 如果使用者共享复制品，請要求提供簡短的非敏感测试短语和相关配置，而不是私人对话。