# Phân tích kỹ thuật app com.aitutor.ai.language.tutor

**Ngày phân tích:** 2026-05-13  
**APK version:** LeranItalian_v-23_release  
**Package:** com.ai.tutor.translate  

---

## 1. Speech-to-Text (STT) — Nhận diện giọng nói

**Engine:** Android Native `SpeechRecognizer` (Google Speech Services)

- Sử dụng `android.speech.SpeechRecognizer.createSpeechRecognizer()` — API STT có sẵn trên Android.
- **Không dùng bất kỳ SDK bên thứ 3 nào** (không Azure, không Whisper, không Deepgram, không AssemblyAI...).
- Intent: `android.speech.action.RECOGNIZE_SPEECH`, language model: `free_form`.
- Hỗ trợ nhiều ngôn ngữ: en-US, es-ES, hi-IN, tl-PH, ar-SA, id-ID, pt-PT, ja-JP, zh-CN, fr-FR, ru-RU, nl-NL, vi-VN, tr-TR, ko-KR, it-IT, th-TH, ms-MY, de-DE.

### Các class xử lý STT

| Class | File | Mô tả |
|-------|------|--------|
| `SpeechHelper` | `utils/SpeechHelper.java` | Hardcode `en-US`, callback đơn giản (onTextDetected, onError) |
| `VoiceToTextRecognizer` | `helper/VoiceToTextRecognizer.java` | Dùng `Locale.getDefault()`, hỗ trợ partial results, toggle start/stop |
| `AiTutorChatActivity` | `activity/AiTutorChatActivity.java` | `initSpeechRecognizer()` — map ngôn ngữ theo cài đặt user, hỗ trợ listen liên tục (free-hand mode) |
| `LearnSpeakActivity` | `activity/speak/LearnSpeakActivity.java` | STT cho bài luyện phát âm, kết hợp với scoring |

---

## 2. Text-to-Speech (TTS) — Đọc văn bản

**Engine:** Android Native `TextToSpeech` (ưu tiên Google TTS — `com.google.android.tts`)

- Sử dụng `android.speech.tts.TextToSpeech` — API TTS có sẵn trên Android.
- **Không dùng SDK TTS bên thứ 3 nào** (không ElevenLabs, không Azure TTS, không Amazon Polly...).
- Ưu tiên Google TTS engine, kiểm tra qua helper `isGoogleTts()`:
  ```java
  // ContextKt.java
  public static final boolean isGoogleTts(TextToSpeech tts) {
      return Intrinsics.areEqual(tts.getDefaultEngine(), "com.google.android.tts");
  }
  ```
- Nếu thiết bị không có Google TTS cho CJK (zh, ja, ko), hiển thị dialog `DialogTtsEngineBinding` hướng dẫn user mở Settings > TTS để cài.

### Cấu hình TTS

| Tham số | Giá trị |
|---------|---------|
| Pitch | 1.0 |
| Speech Rate | 0.95 |
| Voice selection | Chọn theo ngôn ngữ học, lưu index vào `voiceNumber` (SharedPreferences) |
| Speed modes (LearnSpeak) | Normal, Slow, Very Slow |

### Flow TTS

1. Khởi tạo `TextToSpeech` trong `BaseActivity.onCreate()` / `ParentActivity.onCreate()`.
2. Preload bằng `tts.speak("", 0, null, "preload")`.
3. Lọc text trước khi đọc qua `cleanTextForTts()` — loại bỏ ký tự đặc biệt tuỳ ngôn ngữ.
4. Theo dõi tiến trình qua `UtteranceProgressListener` (onStart, onDone, onError).
5. Hỗ trợ hàng đợi đọc nhiều đoạn (`speakQueue`, `speakTexts()`).

---

## 3. Đánh giá phát âm (Pronunciation Assessment)

**Engine:** Tự xây dựng phía client — so sánh text đơn giản  
**KHÔNG dùng SDK chuyên dụng nào** (không Azure Speech Assessment, không SpeechAce, không Chivox, không ELSA, không iFlytek)

### Thuật toán scoring

Nằm trong `LearnSpeakActivity.calculateScore(phrase, spoken)`:

```
1. Normalize cả câu mẫu (phrase) và câu nói (spoken):
   - Loại bỏ ký tự đặc biệt
   - Chuyển lowercase
   - Split theo khoảng trắng

2. Đếm số từ khớp (exact word match):
   matchedWords = đếm từ trong phrase có xuất hiện trong spoken

3. Score = (matchedWords / totalWordsInPhrase) * 100
   Clamp trong khoảng [0, 100]
```

### Bảng đánh giá

| Score | Đánh giá | Màu |
|-------|----------|-----|
| >= 90% | Excellent | Xanh lá |
| >= 70% | Good | Xanh lá |
| >= 50% | Fair | Vàng (#FFC107) |
| < 50% | Try Again | Đỏ (#F44336) |

### Hạn chế

- Chỉ so sánh từ (word-level match), không phân tích âm vị (phoneme).
- Không đánh giá ngữ điệu, trọng âm, hay chất lượng phát âm.
- Phụ thuộc hoàn toàn vào độ chính xác của Google SpeechRecognizer.
- Thứ tự từ không ảnh hưởng đến điểm.

### UI hiển thị

- `scoreCard`: hiển thị % và label đánh giá.
- `accuracyBar`: thanh progress bar.
- `highlightSpokenWords()`: tô màu từng từ đúng/sai trong câu mẫu.
- `cardPronunciation`: hiển thị phiên âm (howToPronounce) cho từ vựng.

---

## 4. AI Chat Backend

**Engine:** OpenAI-compatible API thông qua backend riêng (Apero server)

### Kiến trúc

```
App  -->  Apero Backend (ai_base_url từ Firebase Remote Config)
              |
              v
         OpenAI-compatible API
         (model chọn dynamic qua ModelProvider.selectedModel)
```

### Các thành phần chính

| Class | Chức năng |
|-------|-----------|
| `AssistantManager` | Tạo assistant, lấy danh sách models, generate signature |
| `ConversationManager` | Tạo/xoá conversation, gửi tin nhắn, lấy lịch sử, sửa ngữ pháp |
| `ModelProvider` | Singleton lưu model đang chọn (`selectedModel`) |
| `ApiClient` | Định nghĩa data classes: Message(role, content), RequestBodyData(model, messages) |
| `AIChatManagerKt` | Lấy base URL từ Remote Config, fetch server timestamp |

### Bảo mật API

- Sử dụng signature-based authentication (`com.apero.signature.SignatureParser`).
- Signature = `parseData(apiKey, publicKey, serverTimestamp)`.
- API key và public key PEM lấy từ Firebase Remote Config.
- Device ID dùng để định danh request.

### Tính năng AI

- Chat với AI tutor (conversation-based).
- Dịch tin nhắn (`translatedMessage`).
- Sửa ngữ pháp (`sendGrammarFixRequest` → `GrammarResult` với `correctSentence` và `changeWords`).
- Hỗ trợ avatar/video playback kèm chat (ExoPlayer).

---

## 5. Tổng hợp

| Tính năng | Engine | Loại | SDK bên thứ 3 |
|-----------|--------|------|---------------|
| **STT** | Android SpeechRecognizer | Native Android API | Không |
| **TTS** | Android TextToSpeech (Google TTS) | Native Android API | Không |
| **Pronunciation Scoring** | Tự code (word matching) | Client-side | Không |
| **AI Chat** | OpenAI-compatible API | Server-side (Apero backend) | Không (tự host) |

### Nhận xét

- App sử dụng hoàn toàn các API native của Android cho speech, không tích hợp bất kỳ SDK speech chuyên dụng nào.
- Pronunciation assessment rất cơ bản (chỉ word-level matching), không có phân tích phoneme hay đánh giá chất lượng phát âm thực sự.
- AI chat đi qua backend Apero với OpenAI-compatible API, model được cấu hình dynamic qua Firebase Remote Config.
- TTS ưu tiên Google TTS engine, có xử lý fallback nếu engine không hỗ trợ ngôn ngữ.