SFSpeechRecognizer — ce este, API și integrare în iOS

Ce este SFSpeechRecognizer: prezentare generală

SFSpeechRecognizer — o clasă din Speech.framework care reprezintă un recunoscător de vorbire pentru o limbă specifică. Se inițializează cu Locale (ru_RU, en_US, zh_CN). SFSpeechRecognizer gestionează cererea de recunoaștere (SFSpeechRecognitionRequest) și returnează un rezultat (SFSpeechRecognitionResult) cu transcrieri și metadate. Suportă două tipuri de cereri: SFSpeechAudioBufferRecognitionRequest (flux audio live) și SFSpeechURLRecognitionRequest (fișier audio). Ambele returnează SFTranscription — o matrice de variante alternative de recunoaștere.

SFSpeechRecognitionResult conține: bestTranscription (cea mai bună variantă, SFTranscription), transcriptions (toate alternativele), isFinal (final/parțial). SFTranscription conține: formattedString (text), segments (matrice SFTranscriptionSegment cu marcaje temporale, confidence, substringRange, alternativeSubstrings). Confidence pentru fiecare segment (0..1) — permite filtrarea fragmentelor nesigure. segments — caracteristica cheie a Speech.framework: oferă adnotarea fiecărui cuvânt cu încredere.

Arhitectura SFSpeechRecognizer: AVFoundation (captare audio) → Audio Buffer → SFSpeechAudioBufferRecognitionRequest → SFSpeechRecognizer (motor ASR) → SFSpeechRecognitionResult → SFSpeechRecognitionTask (control: cancel, finish, pause). Motorul ASR Apple utilizează o arhitectură hibridă: Conformer (codificator) + RNNT (decodificator) pentru on-device, Transducer pentru cloud. Modelele sunt optimizate pentru Apple Neural Engine (ANE). Pe A17 Pro on-device ASR funcționează cu RTF 0.3–0.6 (mai rapid decât timpul real).

Cerințe audio: SFSpeechRecognizer acceptă LPCM (16 kHz, 16 bit, mono) sau Opus (iOS 17+). AVFoundation poate capta bufferul în orice format, cererea convertește automat. Lungime minimă: 0.5 secunde (detectare tăcere). Maximă: 1 minut (cloud) / 2 minute (on-device) per cerere. Pentru transcrierea lungă, împărțiți audio în bucăți de 30–60 de secunde cu suprapunere de 2–5 secunde.

Configurare și permisiuni SFSpeechRecognizer

Permisiunile utilizatorului: SFSpeechRecognizer necesită două permisiuni explicite. NSMicrophoneUsageDescription (Privacy — Microphone Usage Description) — pentru acces la microfon. NSSpeechRecognitionUsageDescription (Privacy — Speech Recognition Usage Description) — pentru acces la recunoașterea vorbirii. Ambele sunt șiruri care explică utilizatorului de ce. SFSpeechRecognizer.requestAuthorization — apelul dialogului de permisiuni. Statusuri: notDetermined, denied, restricted, authorized. Fără authorized, apelul recognizer returnează eroarea 216 (Speech framework error).

Verificarea disponibilității: SFSpeechRecognizer.isAvailable — verifică dacă ASR este disponibil pentru limba curentă. Pe iOS 16- isAvailable = false fără internet. Pe iOS 17+ isAvailable = true pentru limbile on-device chiar și offline. SFSpeechRecognizer.supportedLocales — metodă statică pentru obținerea listei de limbi suportate de dispozitiv. Se recomandă verificarea isAvailable înainte de fiecare pornire (utilizatorul poate dezactiva Siri/Dictarea în setări). Disponibilitatea depinde de regiune: chineza — doar în China, araba — în EAU.

// Configurare 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 indisponibil. Activați Siri și Dictarea în Setări")
    return
}

let request = SFSpeechAudioBufferRecognitionRequest()
request.requiresOnDeviceRecognition = true

Gestionarea erorilor: SFSpeechRecognizer este apelat cu un completion handler care poate returna o eroare. Erori principale: 203 — no internet (cloud, iOS 16-); 216 — not authorized (fără permisiune); 301 — audio error (problemă cu microfonul/formatul); 401 — service unavailable (serviciu suprasolicitat); 601 — language unavailable (limba nu este suportată pe dispozitiv). Pentru on-device iOS 17+ erori principale: 301 (audio), 601 (language). Gestionați întotdeauna completion handler — erorile pot apărea în orice moment al înregistrării.

Recunoașterea fluxului vocal de la microfon

Pipeline Live ASR: AVAudioEngine (captare de la microfon) → installTap (buffer audio) → request.append(buffer) → SFSpeechRecognizer → recognitionTask → delegate/resultHandler. AVAudioEngine asigură latență scăzută (5–10 ms de la microfon la buffer). SFSpeechRecognitionDelegate: didHypothesizeTranscription (la fiecare 200–500 ms — text parțial), didFinishRecognition (rezultat final). Task.isFinishing — poate fi anulat când recunoașterea este finalizată. Pentru recunoaștere continuă (dictare infinită) — creați un nou task după isFinal.

SFSpeechRecognitionTaskDelegate: metode opționale. speechRecognitionDidDetectSpeech (începutul vorbirii) — pentru indicator UI. didHypothesizeTranscription (text parțial) — pentru afișare pe măsură ce se vorbește. didFinishRecognition (rezultat final) — pentru fixarea textului. didFinishSuccessfully (succes/eroare) — pentru finalizare. didProcessAudio (buffer audio procesat) — pentru metrul RMS. Se recomandă implementarea didHypothesizeTranscription — utilizatorul vede textul imediat, fără întârziere. Transcrierea finală — pentru salvare.

// Recunoaștere vocală live
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()

Recunoaștere continuă: pentru modul „ascultă mereu” (intrare vocală, asistent) este necesară repornirea task-ului după isFinal. Creați o buclă: finishTask → request = SFSpeechAudioBufferRecognitionRequest() → recognitionTask = recognizer.recognitionTask(with: request). Pentru a evita pauzele, suprapuneți sfârșitul unei sarcini cu începutul următoarei (începeți o nouă cerere cu 1–2 secunde înainte de finalizarea celei precedente). AVFoundation AVAudioSession — configurarea .playAndRecord pentru redare și înregistrare simultană. Pe iOS 17+ ASR continuu cu on-device consumă 2–5% baterie pe oră (A15+).

Recunoașterea fișierelor audio și înregistrărilor

SFSpeechURLRecognitionRequest — cerere pentru recunoașterea unui fișier audio prin URL. Suportă formate: .wav (16 kHz, 16 bit, mono), .m4a (AAC), .mp4, .mov. Lungime maximă: ~1 minut pentru cloud, ~2 minute pentru on-device. Pentru fișiere mai lungi — împărțiți în bucăți (AVAssetExportSession + trim). SFSpeechURLRecognitionRequest nu suportă streaming (fără rezultate parțiale) — doar rezultat final. Pentru rezultate parțiale cu fișier — convertiți în Audio Buffer Request.

Obținerea transcrierii fișierului audio: SFSpeechRecognizer.recognitionTask(with: request) resultHandler. Extrageți bestTranscription.formattedString. Pentru marcaje temporale la nivel de cuvânt — segments din bestTranscription.segments (segment.duration, segment.timestamp, segment.substring). Confidence pe segment — încrederea ASR în fiecare cuvânt (utilizați pentru filtrare). Variante alternative — alternative transcriptionFormatter pentru cuvinte cu confidence scăzut. Pentru fișiere cu mai mulți vorbitori — SFSpeechRecognitionRequest poate returna mai multe cereri (câte una per vorbitor, iOS 17+).

// Transcriere fișier audio
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("Eroare: \(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)
    }
}

Segmentarea fișierelor audio lungi: pentru fișiere > 1 minut tăiați în bucăți de 30–60 de secunde cu suprapunere de 2–3 secunde (împreunare). AVAssetExportSession + CMTimeRange — exportul bucăților. Alternativă: UISelectionView (utilizatorul selectează segmentul). Împreunarea transcrierilor: concatenarea textelor, împreunarea prin suprapunere (ultimele 2–3 cuvinte ale bucății precedente sunt comparate cu primele 2–3 cuvinte ale următoarei — eliminați duplicatele). Vosk și Whisper suportă audio lung nativ, SFSpeechRecognizer — nu. Pentru transcriere lungă recomand Whisper (Core ML) — fără limită de lungime.

On-device versus Cloud: compararea modurilor

Modul On-device (iOS 17+): request.requiresOnDeviceRecognition = true. ASR se execută local pe Apple Neural Engine (ANE). Avantaje: fără internet, confidențialitate (audio nu părăsește dispozitivul), cost zero (gratuit), latență scăzută (RTF 0.3–0.6). Dezavantaje: precizie mai mică (WER 12–14% vs 7–12%), limitare de 2 minute per cerere, set limitat de limbi (nu toate 60 sunt disponibile on-device). Modelul on-device ocupă ~50–100 MB pe dispozitiv, se încarcă la prima cerere.

Cloud (iOS 16-): request.requiresOnDeviceRecognition = false (sau parametrul lipsește). ASR pe serverele Apple — mai precis (WER 7% EN, 12% RU), mai multe limbi, până la 1 minut per cerere. Necesită internet (WiFi sau mobil). Apple nu percepe taxe dezvoltatorului pentru cloud ASR (gratuit). Limite: 1 cerere pe minut per aplicație (nespecificat), dar pentru scară de producție Apple poate limita. cloud ASR — calitate best-effort, fără SLA. Pentru aplicații corporative utilizați Google Cloud ASR sau Whisper (Core ML).

Combined Recognition (iOS 17+): request.requiresOnDeviceRecognition = false cu internet (cloud), = true la offline (fallback). Apple alege automat modul. Pentru aplicații critice în privința preciziei: verificați NetworkMonitor (NWPathMonitor) — cu internet cloud, fără el on-device. Pentru aplicații critice în privința confidențialității: întotdeauna on-device. Pentru transcriere: cloud (mai precis). Pentru intrare vocală: on-device (mai rapid). Se recomandă Combined: 80% cloud, 20% on-device fallback.

Utilizarea SFSpeechRecognizer în aplicațiile iOS

Intrare vocală în tastatura personalizată — SFSpeechRecognizer este integrat în extensiile de tastatură (iOS 10+). Utilizatorul apasă butonul microfon — ASR transcrie vorbirea în text și o inserează în câmpul de text. Cerințe: rezultate parțiale (a vedea textul în timp real), on-device (tastatura trebuie să funcționeze fără internet). SFSpeechRecognizer + AVSpeechSynthesizer — intrare vocală + ieșire vocală. Pentru tastatura personalizată pe iOS 17+ utilizați on-device. Limitări ale extensiei de tastatură: AVAudioEngine este disponibil, dar cu limitări de timp (background execution limited).

Transcrierea întâlnirilor și prelegerilor — aplicații pentru înregistrarea și transcrierea audio (Otter.ai, Rev, Apple Voice Memos). SFSpeechURLRecognitionRequest procesează fișierul .m4a. Pentru înregistrări lungi (30–60 de minute) — Whisper Core ML (fără limită de lungime). Segmentele SFSpeechRecognizer cu marcaje temporale — pentru sincronizarea textului cu audio (evidențierea textului în timpul redării). Confidence pe segment — pentru afișarea fragmentelor nesigure (evidențiere galbenă). Pentru diarizarea vorbitorilor (cine a vorbit) — Apple nu oferă API, utilizați pyannote-audio + Whisper pe server.

Comenzi vocale în aplicațiile iOS — SFSpeechRecognizer + VGS framework (Voice Grammar Services) pentru executarea comenzilor: „deschide setările”, „trimite mesaj”, „pornește lumina”. Recunoaștere bazată pe gramatică: SFSpeechRecognitionRequest contextualStrings = matrice de comenzi. Aceasta crește precizia recunoașterii comenzilor la 95% (vs 85% free-form). SFSpeechRecognitionTask.cancel — pentru întreruperea după executarea comenzii. VGS + SFSpeechRecognizer + Shortcuts — comenzi vocale personalizate fără scrierea unei interfețe. Pentru accesibilitate: Voice Control (încorporat) + SFSpeechRecognizer (comenzi personalizate).

// Comenzi vocale cu șiruri contextuale
let request = SFSpeechAudioBufferRecognitionRequest()
request.requiresOnDeviceRecognition = true
request.shouldReportPartialResults = true
request.contextualStrings = ["open contacts", "send message",
                             "show notifications", "pornițe 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()
    }
}

Dictare în aplicații medicale și juridice — SFSpeechRecognizer pentru crearea documentelor structurate prin voce. Domain Adaptation: contextualStrings cu termeni medicali/juridici (500+ fraze). SFSpeechRecognitionRequest.customLmProbability — influența contextualStrings (0.1–1.0). Pentru dictarea medicală utilizați on-device (confidențialitatea datelor pacientului). Whisper fine-tuned pe date medicale — alternativă cu WER 5% în loc de 12% al SFSpeechRecognizer de bază. Conformitatea HIPAA: modul on-device (datele nu părăsesc dispozitivul). Pentru transcrierea consultațiilor — SFSpeechURLRecognitionRequest + segments cu marcaje temporale ale vorbitorului.