NKO-4.3 — SpeakFlow Voice Engine Integration

NKO-4.3 — SpeakFlow Voice Engine Integration

Status: ✅ COMPLETE
Build: ✅ BUILD SUCCEEDED (zero errors, iPhone 17 Pro Simulator, iOS 26.2)
Date: 2025-07-19

---

What Was Built

Voice-to-N'Ko transliteration module for the ߒߞߏ Bridge iOS app. Speak Manding, see N'Ko script in real-time.

New Files Created

ios/NKoBridge/Voice/
├── SpeechRecognizer.swift      (18KB) — On-device STT wrapper
├── VoiceTransliterator.swift   (11KB) — Speech → Latin → N'Ko pipeline
└── VoiceInputView.swift        (22KB) — Full voice UI + Bridge integration

Files Modified

---

Architecture

                    ┌─────────────────────────┐
                    │   User speaks Manding   │
                    └────────────┬────────────┘
                                 │ audio
                    ┌────────────▼────────────┐
                    │    SpeechRecognizer      │
                    │  (SFSpeechRecognizer)    │
                    │  Locale: fr-FR / bm-ML   │
                    │  On-device preferred      │
                    │  Real-time audio levels   │
                    └────────────┬────────────┘
                                 │ AsyncStream<VoiceTranscription>
                    ┌────────────▼────────────┐
                    │   VoiceTransliterator    │
                    │                          │
                    │  1. Phrase dictionary     │
                    │  2. French pre-processor  │
                    │  3. Word-by-word lookup   │
                    │  4. NKoTransliterator     │
                    │     (Latin → IPA → N'Ko)  │
                    └────────────┬────────────┘
                                 │ VoiceTransliterationResult
                    ┌────────────▼────────────┐
                    │     VoiceInputView       │
                    │                          │
                    │  • Waveform visualization │
                    │  • Latin partial display  │
                    │  • N'Ko final display     │
                    │  • "Use in Bridge" button │
                    │  • Session history        │
                    └────────────┬────────────┘
                                 │ onCommit(latinText)
                    ┌────────────▼────────────┐
                    │   BridgeView (existing)  │
                    │   engine.inputText = ...  │
                    │   → All 3 scripts output  │
                    └─────────────────────────┘

---

Language Support Findings

Apple SFSpeechRecognizer Manding Support

Mitigation Strategy

Since Apple doesn't support Bambara/Manding natively:

1. French (fr-FR) as primary recognizer — All Manding speakers in West Africa speak French as L2. The recognizer handles Manding words reasonably well since many are loan words or phonetically close.

2. Manding context hints — We inject 60+ common Manding words as `contextualStrings` to bias the French recognizer toward Manding phonemes. Words like "salam", "baara", "jama", "karan" etc.

3. French → Manding pre-processor — Maps French orthographic conventions to Manding equivalents before transliteration:
- `ou` → `u`, `gn` → `ny`, `ch` → `c`, `qu` → `k`
- French accented vowels → plain equivalents

4. Dictionary-first lookup — 30+ known Manding words/phrases checked before character-level transliteration for accuracy.

5. Auto-detection — If Apple ever adds `bm-ML`, the app automatically uses it (checked at runtime).

---

UI Features

### VoiceInputView
- Tap-to-record button with animated pulse ring
- Waveform visualization — 32-bar animated display driven by real-time audio RMS levels (~30fps)
- Dual display — Latin recognition (blue) above, N'Ko output (gold) below
- RTL layout — N'Ko text displayed right-to-left
- "Use in Bridge" button — commits voice result to BridgeView input
- Session history — scrollable list of past voice results with copy buttons
- Language selector sheet — switch between Bambara/French/English

### BridgeView Integration
- Compact mic button in the input field (gold gradient, always visible)
- Opens voice sheet via `.presentationDetents([.medium, .large])`
- Voice result feeds directly into `BridgeEngine.inputText` → all 3 script outputs

### Permission Flow
- Requests both Speech Recognition and Microphone permissions
- Clear error messages directing to Settings if denied
- Custom Info.plist descriptions explaining Manding-specific use case

---

Provenance

### Ported From
- `SpeakFlowCore/SpeechService.swift` (macOS) — audio engine, recognition task, AsyncStream pattern
- `SpeakFlowCore/NKoTransliterationService.swift` — character mappings, IPA intermediary, dictionary
- `SpeakFlowCore/AudioProcessingService.swift` — audio level metering pattern

### Uses
- `NKoTransliteration` Swift package (shared) — `NKoTransliterator` for Latin → IPA → N'Ko conversion
- Apple `Speech` framework — `SFSpeechRecognizer` for on-device STT
- Apple `AVFoundation` — `AVAudioEngine` for audio capture
- Apple `Accelerate` — `vDSP_measqv` for RMS level calculation

---

Build Verification

$ xcodebuild -project NKoBridge.xcodeproj -scheme NKoBridge \
    -sdk iphonesimulator -destination 'platform=iOS Simulator,name=iPhone 17 Pro' \
    build
** BUILD SUCCEEDED **

Zero errors. Zero warnings from Voice module files.

---

Cultural Note

> Voice input makes N'Ko Bridge accessible to non-literate Manding speakers — the very people N'Ko script was created for. Solomana Kanté invented N'Ko in 1949 so that Manding languages could be written. This module closes the circle: speak your language, see your script. ߒߞߏ