SFSpeechRecognizer — o que é, API e integração com iOS

O que é SFSpeechRecognizer: visão geral dos recursos

SFSpeechRecognizer é uma classe do Speech.framework que representa um reconhecedor de fala para um idioma específico. É inicializado com um Locale (ru_RU, en_US, zh_CN). O SFSpeechRecognizer gerencia uma solicitação de reconhecimento (SFSpeechRecognitionRequest) e retorna um resultado (SFSpeechRecognitionResult) com transcrições e metadados. Suporta dois tipos de solicitações: SFSpeechAudioBufferRecognitionRequest (fluxo de áudio ao vivo) e SFSpeechURLRecognitionRequest (arquivo de áudio). Ambos retornam SFTranscription — uma matriz de hipóteses alternativas de reconhecimento.

SFSpeechRecognitionResult contém: bestTranscription (melhor hipótese, SFTranscription), transcriptions (todas as alternativas), isFinal (final/intermediário). SFTranscription contém: formattedString (texto), segments (matriz de SFTranscriptionSegment com timestamps, confiança, substringRange, alternativeSubstrings). A confiança para cada segmento (0..1) — permite filtrar fragmentos não confiáveis. Os segments são um recurso chave do Speech.framework: fornecem marcação palavra por palavra com pontuações de confiança.

Arquitetura do SFSpeechRecognizer: AVFoundation (captura de áudio) → Audio Buffer → SFSpeechAudioBufferRecognitionRequest → SFSpeechRecognizer (mecanismo ASR) → SFSpeechRecognitionResult → SFSpeechRecognitionTask (controle: cancel, finish, pause). O mecanismo ASR da Apple usa uma arquitetura híbrida: Conformer (encoder) + RNNT (decoder) para on-device, Transducer para cloud. Os modelos são otimizados para o Apple Neural Engine (ANE). No A17 Pro, o ASR on-device funciona com RTF 0.3–0.6 (mais rápido que o tempo real).

Requisitos de áudio: O SFSpeechRecognizer aceita LPCM (16 kHz, 16 bit, mono) ou Opus (iOS 17+). O AVFoundation pode capturar buffers de qualquer formato, a solicitação converte automaticamente. Comprimento mínimo: 0,5 segundos (detecção de silêncio). Máximo: 1 minuto (cloud) / 2 minutos (on-device) por solicitação. Para transcrição longa, divida o áudio em partes de 30–60 segundos com sobreposição de 2–5 segundos.

Configuração e permissões do SFSpeechRecognizer

Permissões do usuário: O SFSpeechRecognizer requer duas permissões explícitas. NSMicrophoneUsageDescription (Privacy — Microphone Usage Description) — para acesso ao microfone. NSSpeechRecognitionUsageDescription (Privacy — Speech Recognition Usage Description) — para acesso ao reconhecimento de fala. Ambas são strings explicando o motivo ao usuário. SFSpeechRecognizer.requestAuthorization — exibe o diálogo de permissão. Status: notDetermined, denied, restricted, authorized. Sem o status authorized, chamar o recognizer retorna o erro 216 (Speech framework error).

Verificação de disponibilidade: SFSpeechRecognizer.isAvailable — verifica se o ASR está disponível para o idioma atual. No iOS 16-, isAvailable = false sem internet. No iOS 17+, isAvailable = true para idiomas on-device mesmo offline. SFSpeechRecognizer.supportedLocales — método estático para obter a lista de idiomas suportados pelo dispositivo. Recomenda-se verificar isAvailable antes de cada inicialização (o usuário pode desativar o Siri/Ditado nas configurações). A disponibilidade depende da região: chinês — apenas na China, árabe — nos Emirados Árabes Unidos.

// Configuração do SFSpeechRecognizer
import Speech

SFSpeechRecognizer.requestAuthorization { status in
    guard status == .authorized else { return }
}

let recognizer = SFSpeechRecognizer(locale: Locale(identifier: "ru_RU"))!
guard recognizer.isAvailable else {
    print("ASR não disponível. Ative Siri e Ditado nas Configurações")
    return
}

let request = SFSpeechAudioBufferRecognitionRequest()
request.requiresOnDeviceRecognition = true

Tratamento de erros: O SFSpeechRecognizer é chamado com um completion handler que pode retornar um Error. Principais erros: 203 — sem internet (cloud, iOS 16-); 216 — não autorizado (sem permissão); 301 — erro de áudio (problema com microfone/formato); 401 — serviço indisponível (serviço sobrecarregado); 601 — idioma indisponível (idioma não suportado no dispositivo). Para on-device iOS 17+, principais erros: 301 (áudio), 601 (idioma). Sempre trate o completion handler — erros podem ocorrer a qualquer momento durante a gravação.

Reconhecimento de fala ao vivo do microfone

Pipeline ASR ao vivo: AVAudioEngine (captura do microfone) → installTap (buffer de áudio) → request.append(buffer) → SFSpeechRecognizer → recognitionTask → delegate/resultHandler. O AVAudioEngine oferece baixa latência (5–10 ms do microfone ao buffer). SFSpeechRecognitionDelegate: didHypothesizeTranscription (a cada 200–500 ms — texto parcial), didFinishRecognition (resultado final). Task.isFinishing — pode cancelar quando o reconhecimento estiver completo. Para reconhecimento contínuo (ditado infinito), crie uma nova tarefa após isFinal.

SFSpeechRecognitionTaskDelegate: métodos opcionais. speechRecognitionDidDetectSpeech (início da fala) — para indicação na UI. didHypothesizeTranscription (texto intermediário) — para exibição enquanto fala. didFinishRecognition (resultado final) — para finalizar o texto. didFinishSuccessfully (sucesso/erro) — para conclusão. didProcessAudio (buffer de áudio processado) — para medidor RMS. Recomenda-se implementar didHypothesizeTranscription — o usuário vê o texto imediatamente sem atraso. A transcrição final é para salvar.

// Reconhecimento de fala ao vivo
let audioEngine = AVAudioEngine()
let request = SFSpeechAudioBufferRecognitionRequest()
request.shouldReportPartialResults = true

recognitionTask = recognizer.recognitionTask(with: request) { result, error in
    if let result = result {
        textView.text = result.bestTranscription.formattedString
    }
    if error != nil || result?.isFinal == true {
        audioEngine.stop()
        request.endAudio()
    }
}

let inputNode = audioEngine.inputNode
let recordingFormat = inputNode.outputFormat(forBus: 0)
inputNode.installTap(onBus: 0, bufferSize: 1024,
                     format: recordingFormat) { buffer, _ in
    request.append(buffer)
}
audioEngine.prepare()
try audioEngine.start()

Reconhecimento contínuo: para o modo “sempre ouvindo” (entrada de voz, assistente), é necessário reiniciar a tarefa após isFinal. Crie um loop: finishTask → request = SFSpeechAudioBufferRecognitionRequest() → recognitionTask = recognizer.recognitionTask(with: request). Para evitar pausas, sobreponha o final de uma tarefa com o início da próxima (inicie uma nova solicitação 1–2 segundos antes do término da anterior). AVFoundation AVAudioSession — configure .playAndRecord para reprodução e gravação simultâneas. No iOS 17+, o ASR contínuo com on-device consome 2–5% de bateria por hora (A15+).

Reconhecimento de arquivos de áudio e gravações

SFSpeechURLRecognitionRequest — uma solicitação para reconhecer um arquivo de áudio por URL. Suporta formatos: .wav (16 kHz, 16 bit, mono), .m4a (AAC), .mp4, .mov. Comprimento máximo: ~1 minuto para cloud, ~2 minutos para on-device. Para arquivos mais longos, divida em partes (AVAssetExportSession + trim). O SFSpeechURLRecognitionRequest não suporta streaming (sem resultados parciais) — apenas o resultado final. Para resultados parciais com um arquivo, converta para uma solicitação de Audio Buffer.

Obtendo transcrição de arquivo de áudio: SFSpeechRecognizer.recognitionTask(with: request) resultHandler. Extraia bestTranscription.formattedString. Para timestamps no nível da palavra — segments de bestTranscription.segments (segment.duration, segment.timestamp, segment.substring). Confiança por segmento — confiança ASR para cada palavra (use para filtrar). Hipóteses alternativas — alternativas do transcriptionFormatter para palavras com baixa confiança. Para arquivos com vários falantes, o SFSpeechRecognitionRequest pode retornar várias solicitações (uma por falante, iOS 17+).

// Transcrição de arquivo de áudio
let audioURL = Bundle.main.url(forResource: "recording", withExtension: "m4a")!
let request = SFSpeechURLRecognitionRequest(url: audioURL)
request.requiresOnDeviceRecognition = true

recognizer.recognitionTask(with: request) { result, error in
    guard let result = result, error == nil else {
        print("Erro: \(error?.localizedDescription ?? "unknown")")
        return
    }

    let transcription = result.bestTranscription
    let text = transcription.formattedString
    let words = transcription.segments.map { segment in
        Word(text: segment.substring,
              start: segment.timestamp,
              duration: segment.duration,
              confidence: segment.confidence)
    }
}

Divisão de arquivos de áudio longos: para arquivos > 1 minuto, divida em partes de 30–60 segundos com sobreposição de 2–3 segundos (emenda). AVAssetExportSession + CMTimeRange — exportar partes. Alternativa: UISelectionView (o usuário seleciona um segmento). Emenda de transcrições: concatenar textos, emendar por sobreposição (as últimas 2–3 palavras da parte anterior são comparadas com as primeiras 2–3 da próxima — remover duplicatas). Vosk e Whisper suportam áudio longo nativamente, o SFSpeechRecognizer não. Para transcrição longa, recomendo Whisper (Core ML) — sem limite de comprimento.

On-device vs Cloud: comparação de modos

Modo On-device (iOS 17+): request.requiresOnDeviceRecognition = true. O ASR é executado localmente no Apple Neural Engine (ANE). Vantagens: sem necessidade de internet, privacidade (o áudio nunca sai do dispositivo), custo zero (gratuito), baixa latência (RTF 0.3–0.6). Desvantagens: menor precisão (WER 12–14% vs 7–12%), limite de 2 minutos por solicitação, conjunto limitado de idiomas (nem todos os 60 idiomas disponíveis on-device). O modelo on-device ocupa ~50–100 MB no dispositivo e é baixado na primeira solicitação.

Cloud (iOS 16-): request.requiresOnDeviceRecognition = false (ou parâmetro ausente). ASR nos servidores da Apple — mais preciso (WER 7% EN, 12% RU), mais idiomas, até 1 minuto por solicitação. Requer internet (WiFi ou celular). A Apple não cobra dos desenvolvedores pelo cloud ASR (gratuito). Limites: 1 solicitação por minuto por aplicativo (não especificado), mas a Apple pode limitar em escala de produção. O cloud ASR fornece qualidade de melhor esforço sem SLA. Para aplicativos empresariais, use Google Cloud ASR ou Whisper (Core ML).

Reconhecimento Combinado (iOS 17+): request.requiresOnDeviceRecognition = false com internet (cloud), = true offline (fallback). A Apple seleciona automaticamente o modo. Para aplicativos críticos para precisão: verifique o NetworkMonitor (NWPathMonitor) — use cloud com internet, on-device sem. Para aplicativos críticos para privacidade: sempre on-device. Para transcrição: cloud (mais preciso). Para entrada de voz: on-device (mais rápido). Recomenda-se Combinado: 80% cloud, 20% fallback on-device.

Uso do SFSpeechRecognizer em aplicativos iOS

Entrada de voz em teclado personalizado — SFSpeechRecognizer integrado em extensões de teclado (iOS 10+). O usuário pressiona o botão do microfone, o ASR transcreve a fala em texto e insere no campo de texto. Requisitos: resultados parciais (ver o texto em tempo real), on-device (o teclado deve funcionar sem internet). SFSpeechRecognizer + AVSpeechSynthesizer — entrada de voz + saída de voz. Para teclados personalizados no iOS 17+, use on-device. Limitações da extensão de teclado: AVAudioEngine está disponível, mas com restrições de tempo (execução em segundo plano limitada).

Transcrição de reuniões e palestras — aplicativos para gravar e transcrever áudio (Otter.ai, Rev, Apple Voice Memos). O SFSpeechURLRecognitionRequest processa arquivos .m4a. Para gravações longas (30–60 minutos) — Whisper Core ML (sem limite de comprimento). Os segments do SFSpeechRecognizer com timestamps — para sincronizar texto com áudio (destaque de texto durante a reprodução). Confiança por segmento — para exibir fragmentos não confiáveis (destaque amarelo). Para diarização de falantes (quem falou) — a Apple não fornece API, use pyannote-audio + Whisper no servidor.

Comandos de voz em aplicativos iOS — SFSpeechRecognizer + framework VGS (Voice Grammar Services) para executar comandos: “abrir configurações”, “enviar mensagem”, “acender a luz”. Reconhecimento baseado em gramática: SFSpeechRecognitionRequest contextualStrings = matriz de comandos. Isso melhora a precisão do reconhecimento de comandos para 95% (vs 85% de formato livre). SFSpeechRecognitionTask.cancel — para interromper após a execução do comando. VGS + SFSpeechRecognizer + Shortcuts — comandos de voz personalizados sem escrever UI. Para acessibilidade: Voice Control (integrado) + SFSpeechRecognizer (comandos personalizados).

// Comandos de voz com strings contextuais
let request = SFSpeechAudioBufferRecognitionRequest()
request.requiresOnDeviceRecognition = true
request.shouldReportPartialResults = true
request.contextualStrings = ["open contacts", "send message",
                             "show notifications", "acender lanterna"]

recognitionTask = recognizer.recognitionTask(with: request) { result, _ in
    guard let text = result?.bestTranscription.formattedString.lowercased() else { return }
    voiceCommands.first { text.contains($0) }.map { command in
        DispatchQueue.main.async { self.executeCommand(command) }
        recognitionTask?.cancel()
    }
}

Ditado em aplicativos médicos e jurídicos — SFSpeechRecognizer para criar documentos estruturados por voz. Adaptação de domínio: contextualStrings com termos médicos/jurídicos (500+ frases). SFSpeechRecognitionRequest.customLmProbability — impacto do contextualStrings (0.1–1.0). Para ditado médico, use on-device (privacidade dos dados do paciente). Whisper ajustado com dados médicos — alternativa com WER 5% em vez de 12% do SFSpeechRecognizer base. Conformidade HIPAA: modo on-device (os dados nunca saem do dispositivo). Para transcrição de consultas — SFSpeechURLRecognitionRequest + segments com timestamps de falante.