Speech Module

Module Android library cung cấp các chức năng liên quan đến giọng nói cho ứng dụng học ngôn ngữ.

Tổng quan

Module speech bao gồm 3 thành phần chính:

Cấu trúc thư mục

speech/
├── di/
│   └── SpeechModule.kt              # Koin DI module
├── stt/
│   ├── SpeechToTextProvider.kt       # Abstract class cho STT
│   ├── SttConfig.kt                  # Cấu hình: locale, partial results, max results
│   ├── SttResult.kt                  # Sealed interface SttEvent (Result, PartialResult, Error...)
│   └── android/
│       └── AndroidSpeechToTextProvider.kt   # Hiện thực bằng Android SpeechRecognizer
├── tts/
│   ├── TextToSpeechProvider.kt       # Abstract class cho TTS
│   ├── TtsConfig.kt                  # Cấu hình: locale, pitch, speechRate, voiceIndex
│   ├── TtsEvent.kt                   # Sealed interface TtsEvent (Start, Done, Error)
│   └── android/
│       └── AndroidTextToSpeechProvider.kt   # Hiện thực bằng Android TextToSpeech (Google TTS engine)
└── pronunciation/
    ├── PronunciationAssessor.kt      # Abstract class cho đánh giá phát âm
    ├── PronunciationResult.kt        # Kết quả: score, level, matched/unmatched words
    └── simple/
        └── SimpleWordMatchAssessor.kt # So khớp từ đơn giản giữa reference và spoken text

Chi tiết từng thành phần

1. Speech-to-Text (STT)

SpeechToTextProvider — abstract class định nghĩa interface chung:

• startListening(config) — bắt đầu nhận dạng giọng nói
• stopListening() — dừng nhận dạng
• cancel() / destroy() — huỷ và giải phóng tài nguyên
• events: Flow<SttEvent> — stream sự kiện realtime (kết quả, lỗi, trạng thái)

AndroidSpeechToTextProvider — hiện thực sử dụng android.speech.SpeechRecognizer:

• Hỗ trợ partial results (kết quả trung gian khi đang nói)
• Trả về alternatives và confidence score
• Map đầy đủ các error code (NETWORK, AUDIO, SERVER, NO_MATCH, v.v.)

Cấu hình (SttConfig):

• locale — ngôn ngữ nhận dạng (mặc định: Locale.US)
• partialResults — bật/tắt kết quả trung gian
• maxResults — số lượng kết quả tối đa

2. Text-to-Speech (TTS)

TextToSpeechProvider — abstract class định nghĩa interface chung:

• speak(text, queueMode) — đọc một đoạn văn bản
• speakSequence(texts) — đọc nhiều đoạn văn bản liên tiếp
• stop() / destroy() — dừng và giải phóng tài nguyên
• events: Flow<TtsEvent> — stream sự kiện (Start, Done, Error)

AndroidTextToSpeechProvider — hiện thực sử dụng android.speech.tts.TextToSpeech:

• Sử dụng Google TTS engine (com.google.android.tts)
• Hỗ trợ chọn voice theo index
• Tự động clean text trước khi đọc (loại bỏ markdown, ký tự đặc biệt)
• Xử lý riêng cho ngôn ngữ CJK (Trung, Nhật, Hàn)
• Queue mode: FLUSH (thay thế) hoặc ADD (nối tiếp)

Cấu hình (TtsConfig):

• locale — ngôn ngữ đọc
• pitch — cao độ giọng (mặc định: 1.0)
• speechRate — tốc độ đọc (mặc định: 0.95)
• voiceIndex — chọn giọng cụ thể

Tốc độ đọc (TtsSpeed): NORMAL (0.95), SLOW (0.7), VERY_SLOW (0.45)

3. Pronunciation Assessment

PronunciationAssessor — abstract class:

• assess(referenceText, spokenText, locale) — so sánh văn bản gốc với lời nói của người dùng
• normalizeText() — chuẩn hoá text (lowercase, loại bỏ ký tự đặc biệt, tách từ)

SimpleWordMatchAssessor — hiện thực đơn giản dựa trên so khớp từ:

• So sánh từng từ trong reference với tập spoken words
• Tính điểm theo tỷ lệ từ khớp: score = matched / total * 100

Kết quả (PronunciationResult):

• score — điểm 0-100
• level — xếp loại: EXCELLENT (>=90), GOOD (>=70), FAIR (>=50), TRY_AGAIN (<50)
• matchedWords / unmatchedWords — danh sách từ khớp và không khớp
• wordDetails — chi tiết từng từ

Dependency Injection (Koin)

val speechModule = module {
    factoryOf(::AndroidSpeechToTextProvider) bind SpeechToTextProvider::class
    singleOf(::AndroidTextToSpeechProvider) bind TextToSpeechProvider::class
    singleOf(::SimpleWordMatchAssessor) bind PronunciationAssessor::class
}

• STT: factory — tạo instance mới mỗi lần inject (vì SpeechRecognizer không nên tái sử dụng)
• TTS: single — dùng chung 1 instance (cần initialize 1 lần, dùng lại nhiều lần)
• PronunciationAssessor: single — stateless, dùng chung được

Dependencies

• kotlinx-coroutines-core — Flow cho event streaming
• koin-core — Dependency injection
• whisper.cpp (git submodule tại src/main/cpp/whisper.cpp) — thư viện C++ cho on-device speech recognition (chưa tích hợp vào code Kotlin)