iOS 26 SpeechAnalyzer 라이브 마이크: 설정, 결과 및 문제 해결

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을 반환합니다; 그렇지 않으면 로케일을 예약하고 다운로드를 시작할 수 있습니다. 예약 제한은 오류를 일으킬 수도 있습니다. 앱의 기능 전반에 걸쳐 예약을 관리하고, 앱 내 다른 곳에서 아직 사용 중인 모델을 공개하는 대신 더 이상 필요하지 않을 때 로케일을 해제하십시오.

오프라인에 가기 전에 필요한 로케일을 준비하고 준비 상태를 확인하십시오. 모델 자산은 앱 번들 외부에 저장되어 있지만, 여전히 시스템 저장 공간을 차지하며 시간이 지남에 따라 변경될 수 있습니다. 호스트 UI에서 다운로드 진행 상황 및 취소를 표시합니다. “On-device recognition”은 “준비나 네트워크 접근이 전혀 필요하지 않다”는 의미가 아닙니다.

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을 사용합니다. 불일치 형식에 대해서는 변환이 필요하며, 모든 버퍼에 대한 포괄적인 추가 단계가 아닙니다. 출력 프레임 길이를 확인하고 변환 오류를 보고하십시오; 모든 실패 버퍼를 조용히 삭제하면 녹음 UI가 정상으로 보이지만 텍스트가 생성되지 않습니다.

큐된 오디오에 명시적인 소유권 정책을 적용하십시오. 업데이트된 샘플 변환기는 형식이 이미 일치하더라도 독립적인 PCM 저장소를 반환하므로, 나중에 입력을 재사용하면 대기 중인 오디오를 덮어쓰지 않습니다. 오디오 콜백이 제공하는 버퍼는 콜백이 반환된 후에도 불변 상태로 유지된다고 가정해서는 안 됩니다. 나중에 사용하도록 대기열에 넣을 경우, 적절한 소유 복사본이나 버퍼 수명이 제어되는 파이프라인을 배치하십시오. 버퍼별 UI 변이를 오디오 콜백에서 제외하십시오. 프로덕션의 경우, 큐 작업을 어떻게 바인딩할지 결정하고 과부하 또는 라우트 변경을 처리하십시오.

Swift 6에서는 로컬 변수를 캡처하는 것만으로는 파이프라인이 스레드 안전하다는 것을 증명하지 못합니다. 현재 샘플의 변환기는 단일 처리 스레드 계약과 하나의 변환기 콜백을 위한 개인 잠금 보호 @unchecked Sendable 홀더를 가지고 있습니다. 모든 PCM 버퍼나 변환기가 일반적으로 스레드 간에 공유하기에 안전하도록 만들지는 않습니다. 샘플을 적용하기 전에 해당 계약서를 읽어 주세요.

새로운 Speech API에 맥락 어휘 지원이 없다고 말하는 것은 부정확합니다. Apple 문서 AnalysisContext.contextualStrings를 DictationTranscriber에 사용합니다. 문서에서는 짧은 구문과 태그 전반에 걸쳐 최대 100 구문을 권장합니다. 그것은 동일한 힌트가 SpeechTranscriber를 맞춤화한다는 약속이 아닙니다.

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

setContext(_:)은 현재 컨텍스트를 대체하므로 필요할 때 기존 애플리케이션 컨텍스트를 보존하거나 병합하십시오. 다운로드 가능한 도우미는 100 구문을 더 이상 거부하고, 이를 조용히 잘라버리는 대신 거부합니다. 구절 힌트는 DictationTranscriber에 문서화된 맞춤형 언어 모델 옵션과 구별되며, 두 옵션 모두 모든 이름을 올바르게 인식한다는 보장을 하지 않습니다. 앱에 필요한 모듈과 언어를 선택하고 테스트하십시오.

진단을 위해서는 단계 타이밍, 프레임 수, 로케일 및 오류 정보를 시작하십시오. 모든 로그 항목마다 원시 녹음 및 인식된 텍스트가 필요하지 않습니다. 사용자가 복제본을 공유하는 경우, 개인 대화 대신 짧고 민감하지 않은 테스트 문구와 관련 구성을 요청하십시오.