Enhance ASR and feedback mechanisms with Vietnamese pronunciation tips

- Added VietnameseTipsProvider for detailed pronunciation guidance.
- Implemented audio quality assessment and error handling in EnhancedWav2Vec2CharacterASR.
- Improved transcription process with retry mechanism and audio validation.
- Enhanced feedback generation with specific tips for common phoneme errors.
- Updated error handling in ProductionPronunciationAssessor to provide more helpful suggestions.
- Refactored existing methods to utilize new Vietnamese tips for better user experience.

src/apis/controllers/speaking_controller.py

@@ -13,10 +13,12 @@ from loguru import logger
 import Levenshtein
 from dataclasses import dataclass
 from enum import Enum
+import os
 from src.AI_Models.wave2vec_inference import (
     create_inference,
     export_to_onnx,
 )
+from src.utils.vietnamese_tips import vietnamese_tips
 
 # Download required NLTK data
 try:
@@ -70,9 +72,7 @@ class EnhancedWav2Vec2CharacterASR:
         if onnx:
             import os
 
-            model_path = (
-                f"wav2vec2-large-960h-lv60-self{'.quant' if quantized else ''}.onnx"
-            )
+            model_path = f"{model_name}{'.quant' if quantized else ''}.onnx"
             if not os.path.exists(model_path):
                 export_to_onnx(model_name, quantize=quantized)
 
@@ -81,17 +81,71 @@ class EnhancedWav2Vec2CharacterASR:
             model_name=model_name, use_onnx=onnx, use_onnx_quantize=quantized
         )
 
-    def transcribe_with_features(self, audio_path: str) -> Dict:
-        """Enhanced transcription with audio features for prosody analysis - Optimized"""
+    def transcribe_with_features(self, audio_path: str, retry_count: int = 0) -> Dict:
+        """Enhanced transcription with audio features for prosody analysis - Optimized with retry mechanism"""
+        max_retries = 2
+
         try:
             start_time = time.time()
 
+            # Validate audio file
+            if not os.path.exists(audio_path):
+                logger.error(f"Audio file not found: {audio_path}")
+                return self._create_detailed_error_result(
+                    "Không tìm thấy file âm thanh"
+                )
+
+            # Check audio file size and duration
+            try:
+                y, sr = librosa.load(audio_path, sr=self.sample_rate)
+                duration = len(y) / sr
+
+                if duration < 0.5:
+                    logger.warning(f"Audio too short: {duration}s")
+                    return self._create_detailed_error_result(
+                        "Âm thanh quá ngắn. Hãy nói dài hơn và rõ ràng hơn."
+                    )
+
+                if duration > 30:
+                    logger.warning(f"Audio too long: {duration}s")
+                    return self._create_detailed_error_result(
+                        "Âm thanh quá dài. Hãy nói ngắn gọn hơn."
+                    )
+
+                # Check audio volume/energy
+                rms_energy = np.sqrt(np.mean(y**2))
+                if rms_energy < 0.01:  # Very quiet audio
+                    logger.warning(f"Audio too quiet: RMS={rms_energy}")
+                    return self._create_detailed_error_result(
+                        "Âm thanh quá nhỏ. Hãy nói to hơn hoặc di chuyển gần microphone hơn."
+                    )
+
+            except Exception as e:
+                logger.error(f"Audio preprocessing error: {e}")
+                return self._create_detailed_error_result(
+                    "Lỗi xử lý âm thanh. Hãy kiểm tra định dạng file âm thanh."
+                )
+
             # Basic transcription (already fast - 0.3s)
             character_transcript = self.model.file_to_text(audio_path)
             character_transcript = self._clean_character_transcript(
                 character_transcript
             )
 
+            # Check if transcription is empty or too short
+            if not character_transcript or len(character_transcript.strip()) < 2:
+                if retry_count < max_retries:
+                    logger.warning(
+                        f"Empty transcription, retry {retry_count + 1}/{max_retries}"
+                    )
+                    time.sleep(0.1)  # Brief pause before retry
+                    return self.transcribe_with_features(audio_path, retry_count + 1)
+                else:
+                    logger.error("No speech detected after retries")
+                    return self._create_detailed_error_result(
+                        "Không phát hiện được giọng nói. Hãy nói to và rõ ràng hơn, hoặc kiểm tra microphone."
+                    )
+
             # Fast phoneme conversion
             phoneme_representation = self._characters_to_phoneme_representation(
                 character_transcript
@@ -109,11 +163,19 @@ class EnhancedWav2Vec2CharacterASR:
                 "phoneme_representation": phoneme_representation,
                 "audio_features": audio_features,
                 "confidence": self._estimate_confidence(character_transcript),
+                "audio_quality": self._assess_audio_quality(y, sr),
             }
 
         except Exception as e:
             logger.error(f"Enhanced ASR error: {e}")
-            return self._empty_result()
+            if retry_count < max_retries:
+                logger.warning(f"ASR failed, retry {retry_count + 1}/{max_retries}")
+                time.sleep(0.2)
+                return self.transcribe_with_features(audio_path, retry_count + 1)
+            else:
+                return self._create_detailed_error_result(
+                    f"Lỗi xử lý âm thanh sau {max_retries} lần thử. Hãy kiểm tra file âm thanh và thử lại."
+                )
 
     def _extract_basic_audio_features(self, audio_path: str) -> Dict:
         """Extract basic audio features for prosody analysis - Optimized"""
@@ -231,6 +293,119 @@ class EnhancedWav2Vec2CharacterASR:
             if letter in letter_to_phoneme
         ]
 
+    def _assess_audio_quality(self, y: np.ndarray, sr: int) -> Dict:
+        """Assess audio quality and provide feedback"""
+        try:
+            # RMS energy
+            rms_energy = np.sqrt(np.mean(y**2))
+
+            # Signal-to-noise ratio estimation
+            # Calculate energy in different frequency bands
+            stft = librosa.stft(y)
+            mag_spectrum = np.abs(stft)
+
+            # Estimate noise floor (lowest 10% of energy)
+            noise_floor = np.percentile(mag_spectrum, 10)
+            signal_energy = np.mean(mag_spectrum)
+            snr_estimate = 20 * np.log10(signal_energy / (noise_floor + 1e-10))
+
+            # Assess clipping
+            clipping_ratio = np.sum(np.abs(y) > 0.95) / len(y)
+
+            quality_score = 1.0
+            issues = []
+
+            if rms_energy < 0.01:
+                quality_score -= 0.3
+                issues.append("volume_too_low")
+            elif rms_energy > 0.8:
+                quality_score -= 0.2
+                issues.append("volume_too_high")
+
+            if snr_estimate < 10:
+                quality_score -= 0.3
+                issues.append("noisy_background")
+
+            if clipping_ratio > 0.01:
+                quality_score -= 0.4
+                issues.append("audio_clipping")
+
+            return {
+                "quality_score": max(0.0, quality_score),
+                "rms_energy": float(rms_energy),
+                "snr_estimate": float(snr_estimate),
+                "clipping_ratio": float(clipping_ratio),
+                "issues": issues,
+                "recommendations": self._get_audio_quality_recommendations(issues),
+            }
+
+        except Exception as e:
+            logger.error(f"Audio quality assessment error: {e}")
+            return {
+                "quality_score": 0.5,
+                "issues": ["assessment_failed"],
+                "recommendations": ["Thử ghi âm lại với chất lượng tốt hơn"],
+            }
+
+    def _get_audio_quality_recommendations(self, issues: List[str]) -> List[str]:
+        """Get specific recommendations based on audio quality issues"""
+        recommendations = []
+
+        if "volume_too_low" in issues:
+            recommendations.extend(
+                [
+                    "Nói to hơn hoặc di chuyển gần microphone hơn",
+                    "Kiểm tra cài đặt âm lượng microphone",
+                ]
+            )
+
+        if "volume_too_high" in issues:
+            recommendations.extend(
+                [
+                    "Nói nhỏ hơn hoặc di chuyển xa microphone",
+                    "Giảm âm lượng microphone trong cài đặt",
+                ]
+            )
+
+        if "noisy_background" in issues:
+            recommendations.extend(
+                [
+                    "Tìm nơi yên tĩnh hơn để ghi âm",
+                    "Tắt các thiết bị gây tiếng ồn xung quanh",
+                ]
+            )
+
+        if "audio_clipping" in issues:
+            recommendations.extend(
+                ["Giảm âm lượng microphone", "Nói nhỏ hơn hoặc di chuyển xa microphone"]
+            )
+
+        return recommendations
+
+    def _create_detailed_error_result(self, error_message: str) -> Dict:
+        """Create detailed error result with helpful tips"""
+        return {
+            "character_transcript": "",
+            "phoneme_representation": "",
+            "audio_features": {"duration": 0},
+            "confidence": 0.0,
+            "error": True,
+            "error_message": error_message,
+            "audio_quality": {
+                "quality_score": 0.0,
+                "issues": ["detection_failed"],
+                "recommendations": vietnamese_tips.get_audio_quality_tips(),
+            },
+            "retry_suggestions": [
+                vietnamese_tips.get_retry_encouragement(),
+                "Thử các bước sau:",
+                "1. Kiểm tra microphone hoạt động tốt",
+                "2. Nói to và rõ ràng hơn",
+                "3. Tìm nơi yên tĩnh để ghi âm",
+                "4. Thử ghi âm lại",
+            ],
+        }
+
     def _estimate_confidence(self, transcript: str) -> float:
         """Estimate transcription confidence"""
         if not transcript or len(transcript.strip()) < 2:
@@ -240,13 +415,8 @@ class EnhancedWav2Vec2CharacterASR:
         return max(0.0, 1.0 - (repeated_chars * 0.2))
 
     def _empty_result(self) -> Dict:
-        """Empty result for error cases"""
-        return {
-            "character_transcript": "",
-            "phoneme_representation": "",
-            "audio_features": {"duration": 0},
-            "confidence": 0.0,
-        }
+        """Empty result for error cases - deprecated, use _create_detailed_error_result instead"""
+        return self._create_detailed_error_result("Không thể xử lý âm thanh")
 
 
 class EnhancedG2P:
@@ -1164,7 +1334,7 @@ class EnhancedProsodyAnalyzer:
         return max(1, syllable_count)
 
     def _empty_prosody_result(self) -> Dict:
-        """Return empty prosody result for error cases"""
+        """Return enhanced prosody result for error cases"""
         return {
             "pace_score": 0.5,
             "intonation_score": 0.5,
@@ -1172,7 +1342,12 @@ class EnhancedProsodyAnalyzer:
             "stress_score": 0.5,
             "overall_prosody": 0.5,
             "details": {},
-            "feedback": ["Không thể phân tích ngữ điệu"],
+            "feedback": [
+                "Không thể phân tích ngữ điệu chi tiết.",
+                "Hãy thử nói rõ ràng và tự nhiên hơn.",
+                vietnamese_tips.get_retry_encouragement(),
+            ],
+            "suggestions": vietnamese_tips.get_audio_quality_tips()[:3],
         }
 
 
@@ -1187,43 +1362,68 @@ class EnhancedFeedbackGenerator:
         mode: AssessmentMode,
         prosody_analysis: Dict = None,
     ) -> List[str]:
-        """Generate comprehensive feedback based on assessment mode"""
+        """Generate comprehensive feedback based on assessment mode with Vietnamese tips"""
 
         feedback = []
 
-        # Overall score feedback
-        if overall_score >= 0.9:
-            feedback.append("Phát âm xuất sắc! Bạn đã làm rất tốt.")
-        elif overall_score >= 0.8:
-            feedback.append("Phát âm rất tốt! Chỉ còn một vài điểm nhỏ cần cải thiện.")
-        elif overall_score >= 0.6:
-            feedback.append("Phát âm khá tốt, còn một số điểm cần luyện tập thêm.")
-        elif overall_score >= 0.4:
-            feedback.append("Cần luyện tập thêm. Tập trung vào những từ được đánh dấu.")
-        else:
-            feedback.append("Hãy luyện tập chậm rãi và rõ ràng hơn.")
+        # Overall score feedback with encouragement
+        encouragement = vietnamese_tips.get_encouragement_message(overall_score)
+        feedback.append(encouragement)
+
+        # Collect problematic phonemes for detailed tips
+        problematic_phonemes = []
+        for comparison in phoneme_comparisons:
+            if comparison.get("status") in ["wrong", "substitution"]:
+                ref_phoneme = comparison.get("reference_phoneme")
+                if ref_phoneme and ref_phoneme not in problematic_phonemes:
+                    problematic_phonemes.append(ref_phoneme)
 
         # Mode-specific feedback
         if mode == AssessmentMode.WORD:
-            feedback.extend(
-                self._generate_word_mode_feedback(wrong_words, phoneme_comparisons)
+            mode_feedback = self._generate_word_mode_feedback(
+                wrong_words, phoneme_comparisons
             )
+            feedback.extend(mode_feedback)
         elif mode == AssessmentMode.SENTENCE:
-            feedback.extend(
-                self._generate_sentence_mode_feedback(wrong_words, prosody_analysis)
+            mode_feedback = self._generate_sentence_mode_feedback(
+                wrong_words, prosody_analysis
             )
+            feedback.extend(mode_feedback)
 
-        # Common error patterns
+        # Add detailed Vietnamese tips for problematic phonemes
+        if problematic_phonemes and overall_score < 0.8:
+            vietnamese_feedback = vietnamese_tips.get_comprehensive_feedback(
+                problematic_phonemes[:3], overall_score  # Limit to top 3
+            )
+
+            if vietnamese_feedback["detailed_tips"]:
+                feedback.append("🎯 Hướng dẫn cải thiện:")
+                for tip in vietnamese_feedback["detailed_tips"][
+                    :2
+                ]:  # Limit to 2 most important
+                    tip_lines = tip["instruction"].strip().split("\n")
+                    # Add first few lines of instruction
+                    for line in tip_lines[
+                        1:4
+                    ]:  # Skip title, take first 3 instruction lines
+                        if line.strip():
+                            feedback.append(f"  • {line.strip()}")
+
+            # Add pattern-based tips
+            if vietnamese_feedback["pattern_tips"]:
+                feedback.extend(vietnamese_feedback["pattern_tips"][:2])
+
+        # Common error patterns analysis
         error_patterns = self._analyze_error_patterns(phoneme_comparisons)
         if error_patterns:
-            feedback.extend(error_patterns)
+            feedback.extend(error_patterns[:2])  # Limit to avoid overwhelming
 
         return feedback
 
     def _generate_word_mode_feedback(
         self, wrong_words: List[Dict], phoneme_comparisons: List[Dict]
     ) -> List[str]:
-        """Generate feedback specific to word mode"""
+        """Generate feedback specific to word mode with detailed phoneme guidance"""
         feedback = []
 
         if wrong_words:
@@ -1231,11 +1431,18 @@ class EnhancedFeedbackGenerator:
                 word = wrong_words[0]["word"]
                 feedback.append(f"Từ '{word}' cần luyện tập thêm")
 
-                # Character-level feedback
+                # Character-level feedback with phoneme guidance
                 char_errors = wrong_words[0].get("character_errors", [])
                 if char_errors:
                     error_chars = [err.character for err in char_errors[:3]]
                     feedback.append(f"Chú ý các âm: {', '.join(error_chars)}")
+
+                    # Add specific tips for each problematic character/phoneme
+                    for char_error in char_errors[:2]:  # Limit to 2 most important
+                        phoneme = char_error.expected_sound
+                        tip = vietnamese_tips.get_detailed_tip(phoneme)
+                        if tip:
+                            feedback.append(f"Âm /{phoneme}/: {tip.mouth_position}")
             else:
                 word_list = [w["word"] for w in wrong_words[:3]]
                 feedback.append(f"Các từ cần luyện: {', '.join(word_list)}")
@@ -1263,7 +1470,7 @@ class EnhancedFeedbackGenerator:
         return feedback
 
     def _analyze_error_patterns(self, phoneme_comparisons: List[Dict]) -> List[str]:
-        """Analyze common error patterns across phonemes"""
+        """Analyze common error patterns across phonemes with detailed Vietnamese guidance"""
         feedback = []
 
         # Count error types
@@ -1276,21 +1483,18 @@ class EnhancedFeedbackGenerator:
                 difficult_phonemes[phoneme] += 1
                 error_counts[comparison["status"]] += 1
 
-        # Most problematic phoneme
+        # Most problematic phoneme with detailed Vietnamese tips
         if difficult_phonemes:
             most_difficult = max(difficult_phonemes.items(), key=lambda x: x[1])
             if most_difficult[1] >= 2:
                 phoneme = most_difficult[0]
-                phoneme_tips = {
-                    "θ": "Lưỡi giữa răng, thổi nhẹ",
-                    "ð": "Lưỡi giữa răng, rung dây thanh",
-                    "v": "Môi dưới chạm răng trên",
-                    "r": "Cuộn lưỡi nhẹ",
-                    "z": "Như 's' nhưng rung dây thanh",
-                }
+                tip = vietnamese_tips.get_detailed_tip(phoneme)
 
-                if phoneme in phoneme_tips:
-                    feedback.append(f"Âm khó nhất /{phoneme}/: {phoneme_tips[phoneme]}")
+                if tip:
+                    feedback.append(f"Âm khó nhất /{phoneme}/ ({tip.vietnamese_name})")
+                    feedback.append(f"💡 Mẹo: {tip.mouth_position}")
+                    if tip.common_mistakes:
+                        feedback.append(f"Tránh lỗi: {tip.common_mistakes[0]}")
 
         return feedback
 
@@ -1353,8 +1557,36 @@ class ProductionPronunciationAssessor:
             # Step 1: Enhanced ASR transcription with features (0.3s)
             asr_result = self.asr.transcribe_with_features(audio_path)
 
+            # Enhanced error handling for ASR results
+            if asr_result.get("error", False):
+                error_message = asr_result.get(
+                    "error_message", "Không thể xử lý âm thanh"
+                )
+                return self._create_enhanced_error_result(
+                    error_message,
+                    asr_result.get("retry_suggestions", []),
+                    asr_result.get("audio_quality", {}),
+                )
+
             if not asr_result["character_transcript"]:
-                return self._create_error_result("No speech detected in audio")
+                # Provide more helpful error message based on audio quality
+                audio_quality = asr_result.get("audio_quality", {})
+                quality_score = audio_quality.get("quality_score", 0.0)
+
+                if quality_score < 0.3:
+                    error_msg = "Chất lượng âm thanh không đủ tốt để nhận diện."
+                    suggestions = audio_quality.get("recommendations", [])
+                else:
+                    error_msg = "Không phát hiện được giọng nói rõ ràng."
+                    suggestions = [
+                        "Hãy nói to và rõ ràng hơn",
+                        "Kiểm tra microphone có hoạt động tốt không",
+                        "Thử ghi âm trong môi trường yên tĩnh hơn",
+                    ]
+
+                return self._create_enhanced_error_result(
+                    error_msg, suggestions, audio_quality
+                )
 
             # Step 2: Parallel analysis processing
             future_word_analysis = self.executor.submit(
@@ -1436,7 +1668,13 @@ class ProductionPronunciationAssessor:
 
         except Exception as e:
             logger.error(f"Production assessment error: {e}")
-            return self._create_error_result(f"Assessment failed: {str(e)}")
+            error_msg = f"Lỗi xử lý: {str(e)}"
+            suggestions = [
+                "Thử ghi âm lại với chất lượng tốt hơn",
+                "Kiểm tra định dạng file âm thanh",
+                "Đảm bảo file âm thanh không bị hỏng",
+            ]
+            return self._create_enhanced_error_result(error_msg, suggestions)
 
     def _normalize_mode(self, mode: str, reference_text: str) -> AssessmentMode:
         """Normalize mode parameter with backward compatibility"""
@@ -1581,7 +1819,30 @@ class ProductionPronunciationAssessor:
         return result
 
     def _create_error_result(self, error_message: str) -> Dict:
-        """Create error result structure"""
+        """Create error result structure - deprecated, use _create_enhanced_error_result"""
+        return self._create_enhanced_error_result(error_message, [], {})
+
+    def _create_enhanced_error_result(
+        self,
+        error_message: str,
+        suggestions: List[str] = None,
+        audio_quality: Dict = None,
+    ) -> Dict:
+        """Create enhanced error result with helpful tips and suggestions"""
+
+        if suggestions is None:
+            suggestions = vietnamese_tips.get_audio_quality_tips()
+
+        if audio_quality is None:
+            audio_quality = {
+                "quality_score": 0.0,
+                "issues": ["unknown"],
+                "recommendations": suggestions,
+            }
+
+        # Add encouraging retry message
+        retry_encouragement = vietnamese_tips.get_retry_encouragement()
+
         return {
             "transcript": "",
             "transcript_phonemes": "",
@@ -1591,8 +1852,17 @@ class ProductionPronunciationAssessor:
             "word_highlights": [],
             "phoneme_differences": [],
             "wrong_words": [],
-            "feedback": [f"Lỗi: {error_message}"],
+            "feedback": [
+                f"❌ {error_message}",
+                f"💪 {retry_encouragement}",
+                "",
+                "🔧 Gợi ý cải thiện:",
+                *[f"  • {suggestion}" for suggestion in suggestions[:4]],
+            ],
             "error": error_message,
+            "error_type": "audio_processing",
+            "audio_quality": audio_quality,
+            "retry_suggestions": suggestions,
             "assessment_mode": "error",
             "processing_info": {
                 "processing_time": 0,
@@ -1601,6 +1871,7 @@ class ProductionPronunciationAssessor:
                 "confidence": 0.0,
                 "enhanced_features": False,
                 "optimized": True,
+                "error_handled": True,
             },
         }
 

src/utils/vietnamese_tips.py

@@ -0,0 +1,528 @@
+"""
+Vietnamese Pronunciation Tips for English Learners
+Mẹo phát âm tiếng Anh dành cho người Việt Nam
+
+This module provides detailed pronunciation guidance in Vietnamese
+for common English phonemes that are challenging for Vietnamese speakers.
+"""
+
+from typing import Dict, List, Optional, Tuple
+from dataclasses import dataclass
+import random
+
+
+@dataclass
+class PronunciationTip:
+    """Structured pronunciation tip with detailed guidance"""
+
+    phoneme: str
+    vietnamese_name: str
+    mouth_position: str
+    tongue_position: str
+    breathing: str
+    common_mistakes: List[str]
+    practice_words: List[str]
+    detailed_instruction: str
+    difficulty_level: int  # 1-5, where 5 is most difficult
+
+
+class VietnameseTipsProvider:
+    """Provides detailed pronunciation tips in Vietnamese for English learners"""
+
+    def __init__(self):
+        self.tips_database = self._initialize_tips_database()
+        self.error_patterns = self._initialize_error_patterns()
+
+    def _initialize_tips_database(self) -> Dict[str, PronunciationTip]:
+        """Initialize comprehensive tips database"""
+
+        tips = {
+            # Consonants that are difficult for Vietnamese speakers
+            "θ": PronunciationTip(
+                phoneme="θ",
+                vietnamese_name="âm th không thanh (như trong 'think')",
+                mouth_position="Miệng mở vừa phải, môi tự nhiên",
+                tongue_position="Đưa lưỡi ra ngoài, đặt giữa răng trên và răng dưới",
+                breathing="Thổi khí nhẹ qua khe giữa lưỡi và răng",
+                common_mistakes=[
+                    "Phát âm thành /f/ (như 'think' thành 'fink')",
+                    "Phát âm thành /s/ (như 'think' thành 'sink')",
+                    "Phát âm thành /t/ (như 'think' thành 'tink')",
+                ],
+                practice_words=["think", "three", "thank", "thing", "throw"],
+                detailed_instruction="""
+Cách luyện tập chi tiết:
+1. Đưa lưỡi ra ngoài sao cho đầu lưỡi chạm nhẹ vào răng trên
+2. Thổi khí nhẹ qua khe giữa lưỡi và răng - KHÔNG rung dây thanh
+3. Luyện tập từ 'think' - bắt đầu chậm, sau đó tăng tốc
+4. Đặt gương trước mặt để kiểm tra vị trí lưỡi
+5. Luyện tập 10-15 phút mỗi ngày
+                """,
+                difficulty_level=5,
+            ),
+            "ð": PronunciationTip(
+                phoneme="ð",
+                vietnamese_name="âm th có thanh (như trong 'this')",
+                mouth_position="Miệng mở vừa phải, môi tự nhiên",
+                tongue_position="Đưa lưỡi ra ngoài, đặt giữa răng trên và răng dưới",
+                breathing="Rung dây thanh và thổi khí nhẹ",
+                common_mistakes=[
+                    "Phát âm thành /d/ (như 'this' thành 'dis')",
+                    "Phát âm thành /z/ (như 'this' thành 'zis')",
+                    "Phát âm thành /v/ (như 'this' thành 'vis')",
+                ],
+                practice_words=["this", "that", "they", "there", "mother"],
+                detailed_instruction="""
+Cách luyện tập chi tiết:
+1. Giống như âm /θ/ nhưng phải rung dây thanh
+2. Đặt tay lên cổ họng để cảm nhận rung động
+3. Bắt đầu với âm /z/, sau đó đưa lưỡi ra giữa răng
+4. Luyện cặp từ: 'sink/think' và 'zis/this'
+5. Tập đọc câu: 'This is the thing they threw'
+                """,
+                difficulty_level=5,
+            ),
+            "v": PronunciationTip(
+                phoneme="v",
+                vietnamese_name="âm v (như trong 'very')",
+                mouth_position="Môi dưới chạm nhẹ vào răng trên",
+                tongue_position="Lưỡi ở vị trí tự nhiên, không chạm răng",
+                breathing="Rung dây thanh, khí thổi qua khe môi-răng",
+                common_mistakes=[
+                    "Phát âm thành /w/ (như 'very' thành 'wery')",
+                    "Phát âm thành /f/ (như 'very' thành 'fery')",
+                    "Dùng cả hai môi như âm /w/ trong tiếng Việt",
+                ],
+                practice_words=["very", "voice", "video", "love", "have"],
+                detailed_instruction="""
+Cách luyện tập chi tiết:
+1. CHỈ dùng môi dưới chạm răng trên - đây là điểm khác biệt chính
+2. Đừng dùng cả hai môi như âm 'u' trong tiếng Việt
+3. Luyện phân biệt: 'west/vest', 'wine/vine'
+4. Đặt ngón tay lên môi trên để tránh cử động
+5. Tập đọc: 'Very valuable video'
+                """,
+                difficulty_level=4,
+            ),
+            "w": PronunciationTip(
+                phoneme="w",
+                vietnamese_name="âm w (như trong 'water')",
+                mouth_position="Cả hai môi chu tròn như âm 'u'",
+                tongue_position="Lưỡi co lại ở phía sau",
+                breathing="Rung dây thanh, thổi qua môi tròn",
+                common_mistakes=[
+                    "Phát âm thành /v/ (như 'water' thành 'vater')",
+                    "Không chu môi đủ tròn",
+                    "Lưỡi đặt sai vị trí",
+                ],
+                practice_words=["water", "wind", "wall", "woman", "sweet"],
+                detailed_instruction="""
+Cách luyện tập chi tiết:
+1. Bắt đầu với âm 'u' trong tiếng Việt, sau đó chuyển sang âm tiếp theo
+2. Cả hai môi phải chu tròn - không chỉ môi dưới
+3. Luyện phân biệt: 'vest/west', 'vine/wine'
+4. Tập nói chậm: 'W-A-T-E-R' rồi tăng tốc
+5. Luyện câu: 'We went to the west wall'
+                """,
+                difficulty_level=3,
+            ),
+            "r": PronunciationTip(
+                phoneme="r",
+                vietnamese_name="âm r tiếng Anh (như trong 'red')",
+                mouth_position="Miệng mở vừa, không mỉm cười",
+                tongue_position="Cuộn lưỡi lên không chạm vòm miệng",
+                breathing="Rung dây thanh, khí đi qua lưỡi cuộn",
+                common_mistakes=[
+                    "Cuộn lưỡi quá mạnh như tiếng Việt",
+                    "Lưỡi chạm vào vòm miệng",
+                    "Phát âm thành /l/",
+                    "Rung lưỡi như âm 'r' tiếng Việt",
+                ],
+                practice_words=["red", "run", "right", "car", "very"],
+                detailed_instruction="""
+Cách luyện tập chi tiết:
+1. Cuộn lưỡi lên NHƯNG KHÔNG chạm vào vòm miệng
+2. Âm /r/ tiếng Anh mềm hơn nhiều so với tiếng Việt
+3. Luyện phân biệt: 'light/right', 'long/wrong'
+4. Bắt đầu với âm 'ơ' rồi cuộn lưỡi nhẹ
+5. Tập từ cuối: 'car', 'far', 'star' - đây dễ hơn
+                """,
+                difficulty_level=4,
+            ),
+            "l": PronunciationTip(
+                phoneme="l",
+                vietnamese_name="âm l tiếng Anh (như trong 'love')",
+                mouth_position="Miệng mở tự nhiên",
+                tongue_position="Đầu lưỡi chạm vào nướu răng trên",
+                breathing="Rung dây thanh, khí đi qua hai bên lưỡi",
+                common_mistakes=[
+                    "Phát âm thành /r/",
+                    "Đầu lưỡi không chạm đúng vị trí",
+                    "Phát âm quá nặng như tiếng Việt",
+                ],
+                practice_words=["love", "light", "blue", "apple", "wall"],
+                detailed_instruction="""
+Cách luyện tập chi tiết:
+1. Đầu lưỡi phải chạm vào nướu răng trên, không phải răng
+2. Âm /l/ tiếng Anh nhẹ hơn tiếng Việt
+3. Luyện phân biệt: 'right/light', 'wrong/long'
+4. Tập âm /l/ cuối từ: 'wall', 'ball', 'call'
+5. Luyện câu: 'Lucy loves blue apples'
+                """,
+                difficulty_level=3,
+            ),
+            "z": PronunciationTip(
+                phoneme="z",
+                vietnamese_name="âm z (như trong 'zero')",
+                mouth_position="Miệng như âm /s/ nhưng rung dây thanh",
+                tongue_position="Đầu lưỡi gần răng trên nhưng không chạm",
+                breathing="Rung dây thanh, khí đi qua khe nhỏ",
+                common_mistakes=[
+                    "Phát âm thành /s/ (không rung dây thanh)",
+                    "Phát âm thành /dʒ/ (như 'gi' trong tiếng Việt)",
+                    "Quá to, quá rõ",
+                ],
+                practice_words=["zero", "zoo", "easy", "buzz", "maze"],
+                detailed_instruction="""
+Cách luyện tập chi tiết:
+1. Giống hệt âm /s/ nhưng phải rung dây thanh
+2. Đặt tay lên cổ họng để kiểm tra rung động
+3. Luyện cặp: 'sip/zip', 'seal/zeal'
+4. Bắt đầu với âm 's' rồi thêm rung dây thanh
+5. Tập câu: 'Zero zebras in the zoo'
+                """,
+                difficulty_level=3,
+            ),
+            "ʒ": PronunciationTip(
+                phoneme="ʒ",
+                vietnamese_name="âm zh (như trong 'measure')",
+                mouth_position="Môi chu tròn nhẹ",
+                tongue_position="Đầu lưỡi gần vòm miệng nhưng không chạm",
+                breathing="Rung dây thanh, khí đi qua khe rộng hơn /z/",
+                common_mistakes=[
+                    "Phát âm thành /ʃ/ (như 'sh' nhưng không thanh)",
+                    "Phát âm thành /z/",
+                    "Quá giống âm 'gi' tiếng Việt",
+                ],
+                practice_words=["measure", "pleasure", "vision", "usual", "garage"],
+                detailed_instruction="""
+Cách luyện tập chi tiết:
+1. Giống âm /ʃ/ (sh) nhưng có rung dây thanh
+2. Luyện cặp: 'ship/vision', 'cash/casual'
+3. Bắt đầu với 'sh' rồi thêm thanh âm
+4. Âm này ít gặp ở đầu từ, nhiều ở giữa và cuối
+5. Tập câu: 'It's my pleasure to measure'
+                """,
+                difficulty_level=4,
+            ),
+            "ʃ": PronunciationTip(
+                phoneme="ʃ",
+                vietnamese_name="âm sh (như trong 'ship')",
+                mouth_position="Môi chu tròn nhẹ, hơi thụt vào",
+                tongue_position="Lưỡi cong lên gần vòm miệng",
+                breathing="Không rung dây thanh, thổi khí mạnh",
+                common_mistakes=[
+                    "Phát âm thành /s/",
+                    "Không chu môi",
+                    "Lưỡi đặt sai vị trí",
+                ],
+                practice_words=["ship", "shoe", "wash", "fish", "shell"],
+                detailed_instruction="""
+Cách luyện tập chi tiết:
+1. Chu môi như chuẩn bị huýt sáo nhưng nhẹ hơn
+2. Lưỡi cong lên, tạo khoảng rộng hơn âm /s/
+3. Luyện phân biệt: 'sip/ship', 'sass/shash'
+4. Âm /ʃ/ dài hơn và êm hơn âm /s/
+5. Tập câu: 'She sells seashells'
+                """,
+                difficulty_level=3,
+            ),
+            # Vowels challenging for Vietnamese speakers
+            "æ": PronunciationTip(
+                phoneme="æ",
+                vietnamese_name="âm ae (như trong 'cat')",
+                mouth_position="Miệng mở rộng, góc miệng kéo ra",
+                tongue_position="Lưỡi thấp, phẳng ở đáy miệng",
+                breathing="Rung dây thanh",
+                common_mistakes=[
+                    "Phát âm thành /ɛ/ (như 'bet')",
+                    "Phát âm thành /a/ (như 'car')",
+                    "Không mở miệng đủ rộng",
+                ],
+                practice_words=["cat", "hat", "bad", "man", "apple"],
+                detailed_instruction="""
+Cách luyện tập chi tiết:
+1. Mở miệng rộng như đang cười nhưng kéo dài
+2. Lưỡi phải thấp xuống đáy miệng
+3. Luyện phân biệt: 'bet/bat', 'pen/pan'
+4. Âm này không có trong tiếng Việt
+5. Tập câu: 'The fat cat sat on the mat'
+                """,
+                difficulty_level=4,
+            ),
+            "ɪ": PronunciationTip(
+                phoneme="ɪ",
+                vietnamese_name="âm i ngắn (như trong 'bit')",
+                mouth_position="Miệng mở hẹp hơn âm /i/",
+                tongue_position="Lưỡi hơi thấp hơn âm /i/ dài",
+                breathing="Rung dây thanh, âm ngắn",
+                common_mistakes=[
+                    "Phát âm thành /i/ dài (như 'bee')",
+                    "Kéo dài âm quá mức",
+                    "Lưỡi đặt quá cao",
+                ],
+                practice_words=["bit", "sit", "big", "fish", "list"],
+                detailed_instruction="""
+Cách luyện tập chi tiết:
+1. Ngắn và thư giãn hơn âm /i/ dài
+2. Miệng mở hơi rộng hơn âm /i/
+3. Luyện phân biệt: 'bit/beat', 'sit/seat'
+4. Đừng kéo dài như âm 'i' tiếng Việt
+5. Tập câu: 'The big fish sits in the dish'
+                """,
+                difficulty_level=3,
+            ),
+            "ʊ": PronunciationTip(
+                phoneme="ʊ",
+                vietnamese_name="âm u ngắn (như trong 'book')",
+                mouth_position="Môi chu tròn nhẹ, không căng",
+                tongue_position="Lưỡi co lại ở phía sau, thấp hơn /u/",
+                breathing="Rung dây thanh, âm ngắn",
+                common_mistakes=[
+                    "Phát âm thành /u/ dài (như 'boot')",
+                    "Chu môi quá mạnh",
+                    "Kéo dài âm",
+                ],
+                practice_words=["book", "look", "good", "put", "could"],
+                detailed_instruction="""
+Cách luyện tập chi tiết:
+1. Thư giãn hơn âm /u/ dài
+2. Môi chu tròn nhẹ, không căng
+3. Luyện phân biệt: 'book/boot', 'look/Luke'
+4. Âm ngắn và êm dịu
+5. Tập câu: 'Look at the good book'
+                """,
+                difficulty_level=3,
+            ),
+            "ŋ": PronunciationTip(
+                phoneme="ŋ",
+                vietnamese_name="âm ng (như trong 'sing')",
+                mouth_position="Miệng mở tự nhiên",
+                tongue_position="Phần sau lưỡi chạm vào vòm miệng mềm",
+                breathing="Rung dây thanh, khí đi qua mũi",
+                common_mistakes=[
+                    "Thêm âm /g/ ở cuối (sing thành 'singg')",
+                    "Phát âm thành /n/",
+                    "Không dùng mũi",
+                ],
+                practice_words=["sing", "ring", "long", "thing", "walking"],
+                detailed_instruction="""
+Cách luyện tập chi tiết:
+1. Phần sau lưỡi chạm vòm miệng mềm - như chuẩn bị nuốt
+2. KHÔNG phát âm /g/ ở cuối
+3. Khí ra qua mũi, không qua miệng
+4. Luyện: 'sin' vs 'sing' - cảm nhận khác biệt
+5. Tập câu: 'The king is singing a long song'
+                """,
+                difficulty_level=2,
+            ),
+        }
+
+        return tips
+
+    def _initialize_error_patterns(self) -> Dict[str, List[str]]:
+        """Initialize common error patterns for Vietnamese speakers"""
+        return {
+            "th_sounds": [
+                "Âm /θ/ và /ð/ là khó nhất với người Việt - hãy kiên nhẫn luyện tập",
+                "Đặt gương trước mặt để kiểm tra vị trí lưỡi khi phát âm /θ/ và /ð/",
+                "Luyện tập /θ/ và /ð/ ít nhất 10 phút mỗi ngày",
+            ],
+            "v_w_confusion": [
+                "Nhớ: âm /v/ chỉ dùng môi dưới, âm /w/ dùng cả hai môi",
+                "Luyện cặp từ: 'very/wary', 'vest/west' để phân biệt /v/ và /w/",
+                "Đặt ngón tay lên môi trên khi tập âm /v/ để tránh cử động",
+            ],
+            "r_l_confusion": [
+                "Âm /r/ tiếng Anh không rung lưỡi như tiếng Việt",
+                "Âm /l/ cần đầu lưỡi chạm nướu răng trên",
+                "Luyện từ có cả /r/ và /l/: 'really', 'library', 'world'",
+            ],
+            "final_consonants": [
+                "Phát âm âm cuối rõ ràng nhưng không thêm nguyên âm",
+                "Tập nhóm âm cuối: -st, -nd, -th, -ng",
+                "Đừng nuốt âm cuối như trong tiếng Việt",
+            ],
+            "vowel_length": [
+                "Phân biệt nguyên âm dài/ngắn: /i/ vs /ɪ/, /u/ vs /ʊ/",
+                "Nguyên âm tiếng Anh có nhiều biến thể hơn tiếng Việt",
+                "Luyện các cặp tối thiểu: 'bit/beat', 'book/boot'",
+            ],
+        }
+
+    def get_detailed_tip(self, phoneme: str) -> Optional[PronunciationTip]:
+        """Get detailed pronunciation tip for a specific phoneme"""
+        return self.tips_database.get(phoneme)
+
+    def get_error_pattern_tips(self, error_phonemes: List[str]) -> List[str]:
+        """Get tips based on common error patterns"""
+        tips = []
+
+        # Analyze error patterns
+        has_th_sounds = any(p in ["θ", "ð"] for p in error_phonemes)
+        has_v_w = any(p in ["v", "w"] for p in error_phonemes)
+        has_r_l = any(p in ["r", "l"] for p in error_phonemes)
+
+        if has_th_sounds:
+            tips.extend(random.sample(self.error_patterns["th_sounds"], 2))
+
+        if has_v_w:
+            tips.extend(random.sample(self.error_patterns["v_w_confusion"], 1))
+
+        if has_r_l:
+            tips.extend(random.sample(self.error_patterns["r_l_confusion"], 1))
+
+        return tips
+
+    def get_comprehensive_feedback(
+        self, incorrect_phonemes: List[str], difficulty_threshold: float = 0.7
+    ) -> Dict[str, any]:
+        """
+        Generate comprehensive feedback with detailed tips
+
+        Args:
+            incorrect_phonemes: List of phonemes that were pronounced incorrectly
+            difficulty_threshold: Score threshold below which to provide detailed tips
+
+        Returns:
+            Dictionary with comprehensive feedback and tips
+        """
+
+        if not incorrect_phonemes:
+            return {
+                "status": "excellent",
+                "message": "Phát âm xuất sắc! Bạn đã phát âm chính xác.",
+                "tips": [],
+                "practice_suggestions": [
+                    "Tiếp tục luyện tập để duy trì độ chính xác",
+                    "Thử các từ khó hơn để thách thức bản thân",
+                ],
+            }
+
+        # Get detailed tips for each problematic phoneme
+        detailed_tips = []
+        practice_words = set()
+
+        for phoneme in incorrect_phonemes[:3]:  # Limit to top 3 problematic phonemes
+            tip = self.get_detailed_tip(phoneme)
+            if tip:
+                detailed_tips.append(
+                    {
+                        "phoneme": phoneme,
+                        "vietnamese_name": tip.vietnamese_name,
+                        "instruction": tip.detailed_instruction,
+                        "common_mistakes": tip.common_mistakes,
+                        "difficulty": tip.difficulty_level,
+                    }
+                )
+                practice_words.update(tip.practice_words[:3])
+
+        # Get pattern-based tips
+        pattern_tips = self.get_error_pattern_tips(incorrect_phonemes)
+
+        # Generate practice suggestions
+        practice_suggestions = [
+            f"Luyện tập các từ này: {', '.join(list(practice_words)[:5])}",
+            "Tập phát âm trước gương để kiểm tra vị trí môi và lưỡi",
+            "Thu âm và nghe lại để so sánh với bản gốc",
+            "Luyện tập 10-15 phút mỗi ngày cho mỗi âm kh��",
+        ]
+
+        return {
+            "status": "needs_improvement",
+            "message": f"Cần cải thiện {len(incorrect_phonemes)} âm. Đừng nản lòng, cứ luyện tập từ từ!",
+            "detailed_tips": detailed_tips,
+            "pattern_tips": pattern_tips,
+            "practice_suggestions": practice_suggestions,
+            "priority_phonemes": incorrect_phonemes[
+                :2
+            ],  # Focus on top 2 most problematic
+        }
+
+    def get_encouragement_message(self, score: float) -> str:
+        """Get encouraging message based on score"""
+
+        if score >= 0.9:
+            messages = [
+                "Tuyệt vời! Phát âm của bạn rất chuẩn!",
+                "Xuất sắc! Bạn đã tiến bộ rất nhiều!",
+                "Hoàn hảo! Tiếp tục duy trì nhé!",
+            ]
+        elif score >= 0.8:
+            messages = [
+                "Rất tốt! Chỉ còn một vài điểm nhỏ cần cải thiện.",
+                "Tuyệt! Bạn đang trên đúng con đường.",
+                "Giỏi lắm! Tiếp tục cố gắng nhé!",
+            ]
+        elif score >= 0.6:
+            messages = [
+                "Khá tốt! Hãy tập trung vào những âm được gạch chân.",
+                "Bạn đang tiến bộ! Cứ luyện tập đều đặn.",
+                "Tốt đấy! Từ từ sẽ chuẩn thôi.",
+            ]
+        elif score >= 0.4:
+            messages = [
+                "Đừng nản lòng! Mọi người đều phải trải qua giai đoạn này.",
+                "Tiếp tục cố gắng! Luyện tập là chìa khóa thành công.",
+                "Bạn đang học! Mỗi lần luyện là một bước tiến.",
+            ]
+        else:
+            messages = [
+                "Bạn đang bắt đầu hành trình! Hãy luyện chậm và rõ ràng.",
+                "Đừng vội! Phát âm cần thời gian để hoàn thiện.",
+                "Cứ bình tĩnh luyện tập, bạn sẽ tiến bộ nhanh thôi!",
+            ]
+
+        return random.choice(messages)
+
+    def get_audio_quality_tips(self) -> List[str]:
+        """Get tips for better audio recording quality"""
+        return [
+            "Nói to và rõ ràng hơn - microphone cần âm thanh đủ mạnh",
+            "Tìm nơi yên tĩnh để thu âm, tránh tiếng ồn xung quanh",
+            "Giữ khoảng cách 15-20cm từ miệng đến microphone",
+            "Nói chậm rãi và phát âm từng âm một cách rõ ràng",
+            "Kiểm tra microphone có hoạt động tốt không",
+            "Thử thu âm lại nếu âm thanh không rõ ràng",
+        ]
+
+    def get_retry_encouragement(self) -> str:
+        """Get encouraging message for retry attempts"""
+        messages = [
+            "Không sao! Hãy thử lại và nói to hơn một chút.",
+            "Microphone không nghe rõ. Bạn có thể nói rõ ràng hơn không?",
+            "Thử nói chậm và to hơn để hệ thống có thể nhận diện tốt hơn.",
+            "Đừng lo! Hãy thở sâu và thử lại một lần nữa.",
+            "Có thể do tiếng ồn xung quanh. Hãy tìm nơi yên tĩnh hơn và thử lại.",
+        ]
+        return random.choice(messages)
+
+
+# Global instance for easy access
+vietnamese_tips = VietnameseTipsProvider()
+
+
+def get_phoneme_tip(phoneme: str) -> Optional[str]:
+    """Quick access function to get tip for a phoneme"""
+    tip = vietnamese_tips.get_detailed_tip(phoneme)
+    return tip.detailed_instruction if tip else None
+
+
+def get_quick_tips(phonemes: List[str]) -> List[str]:
+    """Get quick tips for a list of phonemes"""
+    tips = []
+    for phoneme in phonemes[:3]:  # Limit to 3 most important
+        tip = vietnamese_tips.get_detailed_tip(phoneme)
+        if tip:
+            tips.append(f"Âm /{phoneme}/: {tip.vietnamese_name} - {tip.mouth_position}")
+    return tips