SFSpeechRecognizer — bu nədir, API və iOS-da inteqrasiya

SFSpeechRecognizer nədir: imkanların icmalı

SFSpeechRecognizer — müəyyən bir dil üçün nitq tanıyıcısını təmsil edən Speech.framework sinfi. O, Locale (ru_RU, en_US, zh_CN) ilə başladılır. SFSpeechRecognizer tanıma sorğusunu (SFSpeechRecognitionRequest) idarə edir və transkripsiyalar və metadata ilə nəticə (SFSpeechRecognitionResult) qaytarır. İki növ sorğunu dəstəkləyir: SFSpeechAudioBufferRecognitionRequest (canlı audio axını) və SFSpeechURLRecognitionRequest (audio fayl). Hər ikisi SFTranscription — alternativ tanıma variantları massivi qaytarır.

SFSpeechRecognitionResult ehtiva edir: bestTranscription (ən yaxşı variant, SFTranscription), transcriptions (bütün alternativlər), isFinal (yekun/aralıq). SFTranscription ehtiva edir: formattedString (mətn), segments (vaxt damğaları, confidence, substringRange, alternativeSubstrings ilə SFTranscriptionSegment massivi). Hər seqment üçün Confidence (0..1) — etibarsız fraqmentləri filtrləməyə imkan verir. segments — Speech.framework-ın əsas xüsusiyyəti: hər sözü ehtimalla qeyd edir.

SFSpeechRecognizer arxitekturası: AVFoundation (audio tutma) → Audio Buffer → SFSpeechAudioBufferRecognitionRequest → SFSpeechRecognizer (ASR mühərriki) → SFSpeechRecognitionResult → SFSpeechRecognitionTask (idarə: cancel, finish, pause). Apple ASR mühərriki hibrid arxitekturadan istifadə edir: on-device üçün Conformer (enkoder) + RNNT (dekoder), cloud üçün Transducer. Modellər Apple Neural Engine (ANE) üçün optimallaşdırılıb. A17 Pro-da on-device ASR RTF 0.3–0.6 ilə işləyir (real vaxtdan daha sürətli).

Audio tələbləri: SFSpeechRecognizer LPCM (16 kHz, 16 bit, mono) və ya Opus (iOS 17+) qəbul edir. AVFoundation istənilən formatda bufer tuta bilər, sorğu avtomatik konvert edir. Minimum uzunluq: 0.5 saniyə (səssizlik aşkarlanması). Maksimum: 1 dəqiqə (cloud) / 2 dəqiqə (on-device) bir sorğu üçün. Uzun transkripsiya üçün audionu 30–60 saniyəlik parçalara 2–5 saniyə üst-üstə düşmə ilə bölün.

SFSpeechRecognizer-ın qurulması və icazələri

İstifadəçi icazələri: SFSpeechRecognizer iki açıq icazə tələb edir. NSMicrophoneUsageDescription (Privacy — Microphone Usage Description) — mikrofona giriş üçün. NSSpeechRecognitionUsageDescription (Privacy — Speech Recognition Usage Description) — nitqin tanınmasına giriş üçün. Hər ikisi istifadəçiyə nəyə görə izah edən sətrlərdir. SFSpeechRecognizer.requestAuthorization — icazə dialoqunun çağrılması. Statuslar: notDetermined, denied, restricted, authorized. Authorized olmadan recognizer çağrısı 216 xətası qaytarır (Speech framework error).

Mövcudluğun yoxlanması: SFSpeechRecognizer.isAvailable — ASR-in cari dil üçün mövcud olub-olmadığını yoxlayır. iOS 16- də internet olmadan isAvailable = false. iOS 17+ də on-device dillər üçün hətta offline-da isAvailable = true. SFSpeechRecognizer.supportedLocales — cihazın dəstəklədiyi dillərin siyahısını almaq üçün statik metod. Hər işə salmadan əvvəl isAvailable yoxlamaq tövsiyə olunur (istifadəçi parametrlərdə Siri/Diktəni söndürə bilər). Mövcudluq bölgədən asılıdır: çin dili — yalnız Çində, ərəb dili — BƏƏ-də.

// SFSpeechRecognizer qurulması
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 mövcud deyil. Parametrlərdə Siri və Diktəni aktivləşdirin")
    return
}

let request = SFSpeechAudioBufferRecognitionRequest()
request.requiresOnDeviceRecognition = true

Xəta idarəsi: SFSpeechRecognizer Error qaytara bilən completion handler ilə çağrılır. Əsas xətalar: 203 — no internet (cloud, iOS 16-); 216 — not authorized (icazə yoxdur); 301 — audio error (mikrofon/format problemi); 401 — service unavailable (xidmət həddindən artıq yüklənib); 601 — language unavailable (dil cihazda dəstəklənmir). On-device iOS 17+ üçün əsas xətalar: 301 (audio), 601 (language). Həmişə completion handler-i idarə edin — xətalar yazının istənilən anında baş verə bilər.

Mikrofondan axın nitq tanıma

Live ASR pipeline: AVAudioEngine (mikrofondan tutma) → installTap (audio bufer) → request.append(buffer) → SFSpeechRecognizer → recognitionTask → delegate/resultHandler. AVAudioEngine aşağı gecikmə təmin edir (mikrofondan buferə 5–10 ms). SFSpeechRecognitionDelegate: didHypothesizeTranscription (hər 200–500 ms — qismən mətn), didFinishRecognition (yekun nəticə). Task.isFinishing — tanıma tamamlandıqda ləğv edilə bilər. Davamlı tanıma üçün (sonsuz diktə) — isFinal-dan sonra yeni task yaradın.

SFSpeechRecognitionTaskDelegate: isteğə bağlı metodlar. speechRecognitionDidDetectSpeech (nitqin başlanğıcı) — UI göstəricisi üçün. didHypothesizeTranscription (aralıq mətn) — danışma zamanı göstərmək üçün. didFinishRecognition (yekun nəticə) — mətnin təsbiti üçün. didFinishSuccessfully (uğur/xəta) — tamamlama üçün. didProcessAudio (audio bufer emal edildi) — RMS ölçən üçün. didHypothesizeTranscription tətbiqi tövsiyə olunur — istifadəçi mətn dərhal görünür, gecikməsiz. Yekun transkripsiya — saxlamaq üçün.

// Canlı nitq tanıma
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()

Davamlı tanıma: „həmişə dinlə” rejimi (səs girişi, köməkçi) üçün isFinal-dan sonra tapşırığı yenidən başlatmaq tələb olunur. Dövüryaradın: finishTask → request = SFSpeechAudioBufferRecognitionRequest() → recognitionTask = recognizer.recognitionTask(with: request). Fasilələrin qarşısını almaq üçün bir tapşırığın sonunu digərinin başlanğıcı ilə üst-üstə qoyun (əvvəlki bitməzdən 1–2 saniyə əvvəl yeni sorğu başlat). AVFoundation AVAudioSession — eyni vaxtda oxutma və yazma üçün .playAndRecord konfiqurasiyası. iOS 17+ də on-device ilə davamlı ASR saatda 2–5% batareya sərf edir (A15+).

Audio faylların və yazıların tanınması

SFSpeechURLRecognitionRequest — URL üzrə audio faylı tanıma sorğusudur. Formatları dəstəkləyir: .wav (16 kHz, 16 bit, mono), .m4a (AAC), .mp4, .mov. Maksimum uzunluq: ~1 dəqiqə cloud üçün, ~2 dəqiqə on-device üçün. Daha uzun fayllar üçün — parçalara bölün (AVAssetExportSession + trim). SFSpeechURLRecognitionRequest axını dəstəkləmir (qismən nəticə yoxdur) — yalnız yekun nəticə. Fayl ilə qismən nəticələr üçün — Audio Buffer Request-ə çevirin.

Audio faylın transkripsiyasının alınması: SFSpeechRecognizer.recognitionTask(with: request) resultHandler. bestTranscription.formattedString çıxarın. Söz səviyyəsində vaxt damğaları üçün — bestTranscription.segments-dən segments (segment.duration, segment.timestamp, segment.substring). Seqment üzrə Confidence — ASR-in hər sözdə inamı (filtrləmə üçün istifadə edin). Alternativ variantlar — aşağı confidence olan sözlər üçün transcriptionFormatter alternativləri. Bir neçə danışanlı fayllar üçün — SFSpeechRecognitionRequest bir neçə sorğu qaytara bilər (hər danışan üçün bir, iOS 17+).

// Audio fayl transkripsiyası
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("Xəta: \(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)
    }
}

Uzun audio faylların bölünməsi: > 1 dəqiqəlik fayllar üçün 30–60 saniyəlik parçalara 2–3 saniyə üst-üstə düşmə ilə kəsin (birləşdirmə). AVAssetExportSession + CMTimeRange — parçaların eksportu. Alternativ: UISelectionView (istifadəçi seqmenti seçir). Transkripsiyaların birləşdirilməsi: mətnlərin konkatenasiyası, üst-üstə düşmə ilə birləşdirmə (əvvəlki parçanın son 2–3 sözü növbətinin ilk 2–3 sözü ilə müqayisə edilir — dublikatları sil). Vosk və Whisper uzun audioları təbii şəkildə dəstəkləyir, SFSpeechRecognizer isə yox. Uzun transkripsiya üçün Whisper (Core ML) tövsiyə edirəm — uzunluq məhdudiyyəti yoxdur.

On-device və Cloud: rejimlərin müqayisəsi

On-device rejimi (iOS 17+): request.requiresOnDeviceRecognition = true. ASR Apple Neural Engine (ANE) də lokal olaraş icra olunur. Üstünlüklər: internet olmadan, məxfilik (audio cihazı tərk etmir), sıfır xərc (pulsuz), aşağı gecikmə (RTF 0.3–0.6). Çatışmazlıqlar: aşağı dəqiqlik (WER 12–14% vs 7–12%), sorğu başına 2 dəqiqə məhdudiyyəti, məhdud dil dəsti (bütün 60 dil on-device mövcud deyil). On-device modeli cihazda ~50–100 MB yer tutur, ilk sorğuda yüklənir.

Cloud (iOS 16-): request.requiresOnDeviceRecognition = false (və ya parametr yoxdur). Apple serverlərində ASR — daha dəqiq (WER 7% EN, 12% RU), daha çox dil, sorğu başına 1 dəqiqəyə qədər. İnternet tələb edir (WiFi və ya mobil). Apple cloud ASR üçün tərtibatçıdan pul almır (pulsuz). Limitlər: tətbiq başına dəqiqədə 1 sorğu (göstərilməyib), lakin istehsal miqyası üçün Apple məhdudlaşdıra bilər. cloud ASR — best-effort keyfiyyəti, SLA olmadan. Korporativ tətbiqlər üçün Google Cloud ASR və ya Whisper (Core ML) istifadə edin.

Combined Recognition (iOS 17+): internet olduqda request.requiresOnDeviceRecognition = false (cloud), offline olduqda = true (fallback). Apple avtomatik rejim seçir. Dəqiqliyə həssas tətbiqlər üçün: NetworkMonitor (NWPathMonitor) yoxlayın — internet varsa cloud, yoxdursa on-device. Məxfiliyə həssas tətbiqlər üçün: həmişə on-device. Transkripsiya üçün: cloud (daha dəqiq). Səs girişi üçün: on-device (daha sürətli). Tövsiyə olunan Combined: 80% cloud, 20% on-device fallback.

iOS tətbiqlərində SFSpeechRecognizer-ın tətbiqi

Xüsusi klaviaturada səs girişi — SFSpeechRecognizer klaviatura genişlənmələrinə daxil edilir (iOS 10+). İstifadəçi mikrofon düyməsini basır — ASR nitqi mətnə çevirir və mətn sahəsinə daxil edir. Tələblər: qismən nəticələr (mətni real vaxtda görmək), on-device (klaviatura internet olmadan işləməlidir). SFSpeechRecognizer + AVSpeechSynthesizer — səs girişi + səs çıxışı. iOS 17+ üçün xüsusi klaviatura üçün on-device istifadə edin. Klaviatura genişlənməsinin məhdudiyyətləri: AVAudioEngine mövcuddur, lakin vaxt məhdudiyyətləri ilə (background execution limited).

Görüş və mühazirə transkripsiyası — audio yazma və transkripsiya tətbiqləri (Otter.ai, Rev, Apple Voice Memos). SFSpeechURLRecognitionRequest .m4a faylını emal edir. Uzun yazılar üçün (30–60 dəqiqə) — Whisper Core ML (uzunluq məhdudiyyəti yoxdur). SFSpeechRecognizer seqmentləri vaxt damğaları ilə — mətnin audio ilə sinxronizasiyası üçün (oxutma zamanı mətnin vurğulanması). Seqment üzrə Confidence — etibarsız fraqmentlərin göstərilməsi üçün (sarı rəngdə vurğulama). Danışan diarizasiyası (kim danışdı) üçün — Apple API təmin etmir, serverdə pyannote-audio + Whisper istifadə edin.

iOS tətbiqlərində səs əmrləri — SFSpeechRecognizer + VGS framework (Voice Grammar Services) əmrləri yerinə yetirmək üçün: „tənzimlamaları aç”, „mesaj göndər”, „işığı yandır”. Qrammatikaya əsaslanan tanıma: SFSpeechRecognitionRequest contextualStrings = əmrlər massivi. Bu, əmrlərin tanınma dəqiqliyini 95%-ə qaldırır (85% free-form vs). SFSpeechRecognitionTask.cancel — əmrin yerinə yetirilməsindən sonra kəsmək üçün. VGS + SFSpeechRecognizer + Shortcuts — interfeys yazmadan xüsusi səs əmrləri. Girişilik üçün: Voice Control (daxili) + SFSpeechRecognizer (xüsusi əmrlər).

// Kontekst sətrləri ilə səs əmrləri
let request = SFSpeechAudioBufferRecognitionRequest()
request.requiresOnDeviceRecognition = true
request.shouldReportPartialResults = true
request.contextualStrings = ["open contacts", "send message",
                             "show notifications", "fənəri yandır"]

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()
    }
}

Tibbi və hüquqi tətbiqlərdə diktə — SFSpeechRecognizer səslə strukturlaşdırılmış sənədlər yaratmaq üçün. Domain Adaptation: tibbi/hüquqi terminlərlə contextualStrings (500+ ifadə). SFSpeechRecognitionRequest.customLmProbability — contextualStrings-in təsiri (0.1–1.0). Tibbi diktə üçün on-device istifadə edin (xəstə məlumatlarının məxfiliyi). Tibbi məlumatlar üzrə Whisper fine-tuned — əsas SFSpeechRecognizer-in 12% WER əvəzinə 5% WER ilə alternativ. HIPAA uyğunluğu: on-device rejimi (məlumatlar cihazı tərk etmir). Qəbul transkripsiyası üçün — SFSpeechURLRecognitionRequest + danışan vaxt damğaları ilə segments.