termux-tts 0.1.1

package/termux_tts/g2p_korean.py

@@ -0,0 +1,242 @@
+"""
+Production-Grade Korean Grapheme-to-Phoneme (G2P) Engine for termux-tts.
+Strict adherence to National Institute of Korean Language (국립국어원) Standard Pronunciation Rules.
+Implements:
+1. Neutralization (평폐쇄음화 및 겹받침 단순화, 제8/9항)
+2. Liaison (연음 및 ㅎ 탈락, 제13/14/12항)
+3. Palatalization (구개음화: ㄷ,ㅌ+ㅣ -> ㅈ,ㅊ, 제17항)
+4. Aspiration (격음화/거센소리되기: ㄱ,ㄷ,ㅂ,ㅈ+ㅎ -> ㅋ,ㅌ,ㅍ,ㅊ, 제12항)
+5. Nasalization (비음화: ㄱ,ㄷ,ㅂ+ㄴ,ㅁ -> ㅇ,ㄴ,ㅁ 및 ㅁ,ㅇ+ㄹ -> ㄴ, 제18/19항)
+6. Liquidization (유음화: ㄴ+ㄹ, ㄹ+ㄴ -> ㄹ+ㄹ, 제20항)
+7. Tensification (경음화/된소리되기: ㄱ,ㄷ,ㅂ+ㄱ,ㄷ,ㅂ,ㅅ,ㅈ -> ㄲ,ㄸ,ㅃ,ㅆ,ㅉ, 제23항)
+8. Sino-Korean & Compound Exceptions (한자어/사이시옷 특수 발음 사전)
+"""
+
+from typing import Tuple, Dict
+
+HANGUL_BASE = 0xAC00
+HANGUL_END = 0xD7A3
+
+CHO_LIST = [
+    'ㄱ', 'ㄲ', 'ㄴ', 'ㄷ', 'ㄸ', 'ㄹ', 'ㅁ', 'ㅂ', 'ㅃ', 'ㅅ',
+    'ㅆ', 'ㅇ', 'ㅈ', 'ㅉ', 'ㅊ', 'ㅋ', 'ㅌ', 'ㅍ', 'ㅎ'
+]
+JUNG_LIST = [
+    'ㅏ', 'ㅐ', 'ㅑ', 'ㅒ', 'ㅓ', 'ㅔ', 'ㅕ', 'ㅖ', 'ㅗ', 'ㅘ',
+    'ㅙ', 'ㅚ', 'ㅛ', 'ㅜ', 'ㅝ', 'ㅞ', 'ㅟ', 'ㅠ', 'ㅡ', 'ㅢ', 'ㅣ'
+]
+JONG_LIST = [
+    '', 'ㄱ', 'ㄲ', 'ㄳ', 'ㄴ', 'ㄵ', 'ㄶ', 'ㄷ', 'ㄹ', 'ㄺ',
+    'ㄻ', 'ㄼ', 'ㄽ', 'ㄾ', 'ㄿ', 'ㅀ', 'ㅁ', 'ㅂ', 'ㅄ', 'ㅅ',
+    'ㅆ', 'ㅇ', 'ㅈ', 'ㅊ', 'ㅋ', 'ㅌ', 'ㅍ', 'ㅎ'
+]
+
+CHO_MAP = {c: i for i, c in enumerate(CHO_LIST)}
+JUNG_MAP = {c: i for i, c in enumerate(JUNG_LIST)}
+JONG_MAP = {c: i for i, c in enumerate(JONG_LIST)}
+
+# 대표 종성 중화 맵 (제8항)
+NEUTRAL_JONG = {
+    'ㄲ': 'ㄱ', 'ㄳ': 'ㄱ', 'ㅋ': 'ㄱ', 'ㄺ': 'ㄱ',
+    'ㅅ': 'ㄷ', 'ㅆ': 'ㄷ', 'ㅈ': 'ㄷ', 'ㅊ': 'ㄷ', 'ㅌ': 'ㄷ', 'ㅎ': 'ㄷ', 'ㄵ': 'ㄴ', 'ㄶ': 'ㄴ',
+    'ㄼ': 'ㄹ', 'ㄽ': 'ㄹ', 'ㄾ': 'ㄹ', 'ㅀ': 'ㄹ',
+    'ㄻ': 'ㅁ',
+    'ㄿ': 'ㅂ', 'ㅄ': 'ㅂ', 'ㅍ': 'ㅂ'
+}
+
+# 겹받침 연음 시 분리 맵 (제14항: 닭을 -> 달글, 값을 -> 갑슬)
+DOUBLE_JONG_SPLIT = {
+    'ㄳ': ('ㄱ', 'ㅅ'),
+    'ㄵ': ('ㄴ', 'ㅈ'),
+    'ㄶ': ('ㄴ', 'ㅎ'),
+    'ㄺ': ('ㄹ', 'ㄱ'),
+    'ㄻ': ('ㄹ', 'ㅁ'),
+    'ㄼ': ('ㄹ', 'ㅂ'),
+    'ㄽ': ('ㄹ', 'ㅅ'),
+    'ㄾ': ('ㄹ', 'ㅌ'),
+    'ㄿ': ('ㄹ', 'ㅍ'),
+    'ㅀ': ('ㄹ', 'ㅎ'),
+    'ㅄ': ('ㅂ', 'ㅅ')
+}
+
+# 한자어/특수 복합어 불규칙 예외 사전
+IRREGULAR_WORDS = {
+    '신라': '실라', '난로': '날로', '칼날': '칼랄', '물약': '물략',
+    '생산량': '생산냥', '결단력': '결딴녁', '의견란': '의견난', '임진란': '임진난',
+    '이원론': '이원논', '입원료': '이붠뇨', '동양루': '동양누', '구원투수': '구원투수',
+    '금융': '금늉', '식용유': '식용뉴', '맨입': '맨닙', '솜이불': '솜니불',
+    '눈요기': '눈뇨기', '남존여비': '남존녀비', '신여성': '신녀성', '꽃잎': '꼰닙',
+    '깻잎': '깬닙', '나뭇잎': '나문닙', '학여울': '항녀울', '독립': '동닙',
+    '백로': '뱅노', '협력': '혐녁', '국립': '궁닙', '막일': '망닐'
+}
+
+def is_hangul_syllable(ch: str) -> bool:
+    return len(ch) == 1 and (HANGUL_BASE <= ord(ch) <= HANGUL_END)
+
+def decompose_syllable(ch: str) -> Tuple[str, str, str]:
+    code = ord(ch) - HANGUL_BASE
+    cho = CHO_LIST[code // (21 * 28)]
+    jung = JUNG_LIST[(code % (21 * 28)) // 28]
+    jong = JONG_LIST[code % 28]
+    return cho, jung, jong
+
+def compose_syllable(cho: str, jung: str, jong: str = '') -> str:
+    cho_i = CHO_MAP.get(cho, 0)
+    jung_i = JUNG_MAP.get(jung, 0)
+    jong_i = JONG_MAP.get(jong, 0)
+    return chr(HANGUL_BASE + (cho_i * 21 * 28) + (jung_i * 28) + jong_i)
+
+class KoreanG2PEngine:
+    """High-Performance Bigram Korean Grapheme-to-Phoneme Engine."""
+
+    def __init__(self):
+        self.irregular_dict = IRREGULAR_WORDS
+
+    def convert(self, text: str) -> str:
+        if not text or not text.strip():
+            return ''
+
+        # 1. Dictionary-based irregular word replacement
+        res_text = text
+        for k, v in self.irregular_dict.items():
+            if k in res_text:
+                res_text = res_text.replace(k, v)
+
+        # 2. Syllable-by-syllable phonological transformation
+        tokens = list(res_text)
+        n = len(tokens)
+        if n <= 1:
+            return self._neutralize_single(res_text)
+
+        i = 0
+        while i < n - 1:
+            c1, c2 = tokens[i], tokens[i+1]
+            if is_hangul_syllable(c1) and is_hangul_syllable(c2):
+                t1, t2 = self._apply_bigram_rules(c1, c2)
+                tokens[i] = t1
+                tokens[i+1] = t2
+            i += 1
+
+        # 3. Final word-final neutralization on last character
+        if n > 0 and is_hangul_syllable(tokens[-1]):
+            cho, jung, jong = decompose_syllable(tokens[-1])
+            if jong in NEUTRAL_JONG:
+                tokens[-1] = compose_syllable(cho, jung, NEUTRAL_JONG[jong])
+
+        return ''.join(tokens)
+
+    def _neutralize_single(self, ch: str) -> str:
+        if len(ch) == 1 and is_hangul_syllable(ch):
+            cho, jung, jong = decompose_syllable(ch)
+            if jong in NEUTRAL_JONG:
+                return compose_syllable(cho, jung, NEUTRAL_JONG[jong])
+        return ch
+
+    def _apply_bigram_rules(self, c1: str, c2: str) -> Tuple[str, str]:
+        cho1, jung1, jong1 = decompose_syllable(c1)
+        cho2, jung2, jong2 = decompose_syllable(c2)
+
+        if not jong1:
+            return c1, c2
+
+        # -------------------------------------------------------------
+        # Rule 1: 구개음화 (Palatalization - 제17항)
+        # ㄷ, ㅌ + 이, 여, 야, 유 -> ㅈ, ㅊ
+        # -------------------------------------------------------------
+        if jong1 in ('ㄷ', 'ㅌ', 'ㄾ') and cho2 == 'ㅇ' and jung2 in ('ㅣ', 'ㅑ', 'ㅕ', 'ㅛ', 'ㅠ'):
+            if jong1 == 'ㄷ':
+                return compose_syllable(cho1, jung1, ''), compose_syllable('ㅈ', jung2, jong2)
+            elif jong1 in ('ㅌ', 'ㄾ'):
+                new_jong1 = 'ㄹ' if jong1 == 'ㄾ' else ''
+                return compose_syllable(cho1, jung1, new_jong1), compose_syllable('ㅊ', jung2, jong2)
+
+        # -------------------------------------------------------------
+        # Rule 2: 격음화 / 거센소리되기 (Aspiration - 제12항)
+        # [ㄱ, ㄷ, ㅂ, ㅈ] + [ㅎ] -> [ㅋ, ㅌ, ㅍ, ㅊ]
+        # [ㅎ, ㄶ, ㅀ] + [ㄱ, ㄷ, ㅂ, ㅈ] -> [ㅋ, ㅌ, ㅍ, ㅊ]
+        # -------------------------------------------------------------
+        if cho2 == 'ㅎ':
+            asp_map = {'ㄱ': 'ㅋ', 'ㄷ': 'ㅌ', 'ㅂ': 'ㅍ', 'ㅈ': 'ㅊ', 'ㄺ': 'ㅋ', 'ㄼ': 'ㅍ', 'ㄵ': 'ㅊ'}
+            if jong1 in asp_map:
+                new_jong1 = 'ㄹ' if jong1 in ('ㄺ', 'ㄼ') else ('ㄴ' if jong1 == 'ㄵ' else '')
+                return compose_syllable(cho1, jung1, new_jong1), compose_syllable(asp_map[jong1], jung2, jong2)
+            elif jong1 in ('ㅅ', 'ㅆ', 'ㅊ', 'ㅌ'):
+                return compose_syllable(cho1, jung1, ''), compose_syllable('ㅌ', jung2, jong2)
+
+        if jong1 in ('ㅎ', 'ㄶ', 'ㅀ'):
+            asp_map2 = {'ㄱ': 'ㅋ', 'ㄷ': 'ㅌ', 'ㅂ': 'ㅍ', 'ㅈ': 'ㅊ', 'ㅅ': 'ㅆ'}
+            if cho2 in asp_map2:
+                new_jong1 = 'ㄴ' if jong1 == 'ㄶ' else ('ㄹ' if jong1 == 'ㅀ' else '')
+                return compose_syllable(cho1, jung1, new_jong1), compose_syllable(asp_map2[cho2], jung2, jong2)
+            elif cho2 == 'ㅇ':  # ㅎ 탈락 (좋은 -> 조은)
+                new_jong1 = 'ㄴ' if jong1 == 'ㄶ' else ('ㄹ' if jong1 == 'ㅀ' else '')
+                return compose_syllable(cho1, jung1, new_jong1), compose_syllable('ㅇ', jung2, jong2)
+
+        # -------------------------------------------------------------
+        # Rule 3: 연음 규칙 (Liaison - 제13/14항)
+        # 받침 뒤에 초성 'ㅇ'(모음)이 오는 경우
+        # -------------------------------------------------------------
+        if cho2 == 'ㅇ':
+            if jong1 in DOUBLE_JONG_SPLIT:
+                j_first, j_second = DOUBLE_JONG_SPLIT[jong1]
+                # 겹받침 앞 글자는 남고 뒤 글자는 초성으로 이동
+                return compose_syllable(cho1, jung1, j_first), compose_syllable(j_second, jung2, jong2)
+            else:
+                # 홑받침 전체가 다음 음절 초성으로 이동
+                return compose_syllable(cho1, jung1, ''), compose_syllable(jong1, jung2, jong2)
+
+        # -------------------------------------------------------------
+        # Rule 4: 유음화 (Liquidization - 제20항)
+        # ㄴ + ㄹ -> ㄹ + ㄹ / ㄹ + ㄴ -> ㄹ + ㄹ
+        # -------------------------------------------------------------
+        if jong1 == 'ㄴ' and cho2 == 'ㄹ':
+            return compose_syllable(cho1, jung1, 'ㄹ'), compose_syllable('ㄹ', jung2, jong2)
+        if jong1 in ('ㄹ', 'ㄾ', 'ㅀ', 'ㄼ') and cho2 == 'ㄴ':
+            return compose_syllable(cho1, jung1, 'ㄹ'), compose_syllable('ㄹ', jung2, jong2)
+
+        # -------------------------------------------------------------
+        # Rule 5: 비음화 (Nasalization - 제18/19항)
+        # ㄱ, ㄷ, ㅂ + ㄴ, ㅁ -> ㅇ, ㄴ, ㅁ + ㄴ, ㅁ
+        # ㅁ, ㅇ + ㄹ -> ㅁ, ㅇ + ㄴ
+        # ㄱ, ㅂ + ㄹ -> ㅇ, ㅁ + ㄴ (연쇄 비음화)
+        # -------------------------------------------------------------
+        effective_jong = NEUTRAL_JONG.get(jong1, jong1)
+
+        # ㅁ, ㅇ + ㄹ -> ㅁ, ㅇ + ㄴ
+        if jong1 in ('ㅁ', 'ㅇ') and cho2 == 'ㄹ':
+            return c1, compose_syllable('ㄴ', jung2, jong2)
+
+        # ㄱ, ㅂ + ㄹ -> ㅇ, ㅁ + ㄴ
+        if effective_jong == 'ㄱ' and cho2 == 'ㄹ':
+            return compose_syllable(cho1, jung1, 'ㅇ'), compose_syllable('ㄴ', jung2, jong2)
+        if effective_jong == 'ㅂ' and cho2 == 'ㄹ':
+            return compose_syllable(cho1, jung1, 'ㅁ'), compose_syllable('ㄴ', jung2, jong2)
+
+        # ㄱ, ㄷ, ㅂ + ㄴ, ㅁ -> ㅇ, ㄴ, ㅁ
+        if cho2 in ('ㄴ', 'ㅁ'):
+            if effective_jong == 'ㄱ':
+                return compose_syllable(cho1, jung1, 'ㅇ'), c2
+            elif effective_jong == 'ㄷ':
+                return compose_syllable(cho1, jung1, 'ㄴ'), c2
+            elif effective_jong == 'ㅂ':
+                return compose_syllable(cho1, jung1, 'ㅁ'), c2
+
+        # -------------------------------------------------------------
+        # Rule 6: 경음화 / 된소리되기 (Tensification - 제23항)
+        # 받침 [ㄱ, ㄷ, ㅂ] + [ㄱ, ㄷ, ㅂ, ㅅ, ㅈ] -> [ㄲ, ㄸ, ㅃ, ㅆ, ㅉ]
+        # -------------------------------------------------------------
+        tense_map = {'ㄱ': 'ㄲ', 'ㄷ': 'ㄸ', 'ㅂ': 'ㅃ', 'ㅅ': 'ㅆ', 'ㅈ': 'ㅉ'}
+        if effective_jong in ('ㄱ', 'ㄷ', 'ㅂ') and cho2 in tense_map:
+            return compose_syllable(cho1, jung1, effective_jong), compose_syllable(tense_map[cho2], jung2, jong2)
+
+        # 기본 자음 앞 겹받침 단순화 (제9항)
+        if jong1 in NEUTRAL_JONG:
+            return compose_syllable(cho1, jung1, NEUTRAL_JONG[jong1]), c2
+
+        return c1, c2
+
+_g2p_instance = KoreanG2PEngine()
+
+def korean_text_to_phonemes(text: str) -> str:
+    """Public API: Convert standard Korean orthographic text into phonetic Hangul sequence."""
+    return _g2p_instance.convert(text)

package/termux_tts/tokenizer.py

@@ -0,0 +1,184 @@
+"""
+Grapheme-to-Phoneme (G2P) Phonetic Tokenizer for Korean and English.
+Includes Number-to-Speech Normalizer and Inline Expressive Tag Parser.
+"""
+
+import re
+from typing import List, Dict
+from .exceptions import TTSLanguageNotSupportedError
+from .g2p_korean import korean_text_to_phonemes
+
+HANGUL_BASE = 0xAC00
+HANGUL_END = 0xD7A3
+
+CHO = [
+    "ㄱ", "ㄲ", "ㄴ", "ㄷ", "ㄸ", "ㄹ", "ㅁ", "ㅂ", "ㅃ", "ㅅ",
+    "ㅆ", "ㅇ", "ㅈ", "ㅉ", "ㅊ", "ㅋ", "ㅌ", "ㅍ", "ㅎ"
+]
+JUNG = [
+    "ㅏ", "ㅐ", "ㅑ", "ㅒ", "ㅓ", "ㅔ", "ㅕ", "ㅖ", "ㅗ", "ㅘ",
+    "ㅙ", "ㅚ", "ㅛ", "ㅜ", "ㅝ", "ㅞ", "ㅟ", "ㅠ", "ㅡ", "ㅢ", "ㅣ"
+]
+JONG = [
+    "", "ㄱ", "ㄲ", "ㄳ", "ㄴ", "ㄵ", "ㄶ", "ㄷ", "ㄹ", "ㄺ",
+    "ㄻ", "ㄼ", "ㄽ", "ㄾ", "ㄿ", "ㅀ", "ㅁ", "ㅂ", "ㅄ", "ㅅ",
+    "ㅆ", "ㅇ", "ㅈ", "ㅊ", "ㅋ", "ㅌ", "ㅍ", "ㅎ"
+]
+
+EXPRESSIVE_TAGS = {
+    "[laugh]": 1001,
+    "[sigh]": 1002,
+    "[breath]": 1003,
+    "[uv_break]": 1004,
+    "[clears_throat]": 1005,
+    "[pause]": 1006
+}
+
+VOCAB: List[str] = [
+    "_", " ", "!", "?", ",", ".", "~", "-",
+    *CHO, *JUNG, *[j for j in JONG if j],
+    *"abcdefghijklmnopqrstuvwxyz"
+]
+VOCAB_TO_ID: Dict[str, int] = {sym: idx for idx, sym in enumerate(VOCAB)}
+PAD_ID: int = VOCAB_TO_ID["_"]
+SPACE_ID: int = VOCAB_TO_ID[" "]
+
+KOREAN_DIGITS = ["", "일", "이", "삼", "사", "오", "육", "칠", "팔", "구"]
+SMALL_UNITS = ["", "십", "백", "천"]
+BIG_UNITS = ["", "만", "억", "조", "경"]
+
+ENGLISH_WORDS = {
+    "0": "zero", "1": "one", "2": "two", "3": "three", "4": "four",
+    "5": "five", "6": "six", "7": "seven", "8": "eight", "9": "nine",
+    "10": "ten", "11": "eleven", "12": "twelve", "13": "thirteen", "14": "fourteen",
+    "15": "fifteen", "16": "sixteen", "17": "seventeen", "18": "eighteen", "19": "nineteen",
+    "20": "twenty", "30": "thirty", "40": "forty", "50": "fifty",
+    "60": "sixty", "70": "seventy", "80": "eighty", "90": "ninety",
+    "100": "hundred", "1000": "thousand"
+}
+
+def decompose_hangul(char: str) -> List[str]:
+    code = ord(char)
+    if HANGUL_BASE <= code <= HANGUL_END:
+        offset = code - HANGUL_BASE
+        cho_idx = offset // (21 * 28)
+        jung_idx = (offset % (21 * 28)) // 28
+        jong_idx = offset % 28
+        res = [CHO[cho_idx], JUNG[jung_idx]]
+        if jong_idx > 0:
+            res.append(JONG[jong_idx])
+        return res
+    return [char]
+
+def _convert_4digits_korean(chunk: str) -> str:
+    num = int(chunk)
+    if num == 0:
+        return ""
+    res = []
+    str_num = str(num).zfill(4)
+    for i, ch in enumerate(str_num):
+        d = int(ch)
+        if d > 0:
+            unit = SMALL_UNITS[3 - i]
+            if d == 1 and unit != "":
+                res.append(unit)
+            else:
+                res.append(KOREAN_DIGITS[d] + unit)
+    return "".join(res)
+
+def number_to_korean_sino(num_str: str) -> str:
+    """Convert integer string to authentic Sino-Korean place-value numerals (e.g. 1234 -> 천이백삼십사, 10000 -> 만)."""
+    try:
+        n = int(num_str)
+    except ValueError:
+        return num_str
+    if n == 0:
+        return "영"
+    rev_str = str(n)[::-1]
+    chunks = [rev_str[i:i+4][::-1] for i in range(0, len(rev_str), 4)]
+    parts = []
+    for i, chunk in enumerate(chunks):
+        c_korean = _convert_4digits_korean(chunk)
+        if c_korean:
+            unit = BIG_UNITS[i]
+            # 10000일 때 '일만' 대신 '만' (단, 210000 -> 이십일만)
+            if c_korean == "일" and unit != "" and len(chunks) == i + 1:
+                parts.append(unit)
+            else:
+                parts.append(c_korean + unit)
+    return "".join(reversed(parts))
+
+def normalize_numbers_korean(text: str) -> str:
+    """Convert digit sequences into spoken Korean place-value numerals."""
+    return re.sub(r"\d+", lambda m: number_to_korean_sino(m.group(0)), text)
+
+def normalize_numbers_english(text: str) -> str:
+    """Convert digit sequences into spoken English words."""
+    def _en_repl(m):
+        num_str = m.group(0)
+        if num_str in ENGLISH_WORDS:
+            return " " + ENGLISH_WORDS[num_str] + " "
+        # Digit-by-digit for phone numbers / codes
+        return " " + " ".join(ENGLISH_WORDS.get(d, d) for d in num_str) + " "
+    return re.sub(r"\d+", _en_repl, text)
+
+class PhoneticTokenizer:
+    def __init__(self, language: str = "ko"):
+        self.language = language.lower()
+        self.vocab = VOCAB
+        if self.language not in ["ko", "korean", "en", "english"]:
+            raise TTSLanguageNotSupportedError(f"Language '{language}' is not supported. Supported: ['ko', 'en']")
+
+    def normalize_text(self, text: str) -> str:
+        if not text or not text.strip():
+            return ""
+        # 1. Normalize linebreaks and tabs
+        text = re.sub(r"[\r\n\t]+", " ", text)
+        
+        # 2. Digits to spoken words
+        if self.language in ["ko", "korean"]:
+            text = normalize_numbers_korean(text)
+            text = korean_text_to_phonemes(text)
+        else:
+            text = normalize_numbers_english(text)
+
+        # 3. Collapse multiple spaces
+        text = re.sub(r"\s{2,}", " ", text)
+        return text.strip()
+
+    def tokenize(self, text: str) -> List[int]:
+        normalized = self.normalize_text(text)
+        if not normalized:
+            return []
+
+        # Parse expressive tags first
+        tag_pattern = re.compile(r"(\[[a-zA-Z_]+\])")
+        parts = tag_pattern.split(normalized)
+
+        tokens: List[int] = []
+        for part in parts:
+            if not part:
+                continue
+            if part in EXPRESSIVE_TAGS:
+                tokens.append(EXPRESSIVE_TAGS[part])
+                continue
+
+            if self.language in ["ko", "korean"]:
+                for char in part:
+                    if char == " ":
+                        tokens.append(SPACE_ID)
+                    elif char in [".", ",", "!", "?", "~", "-"]:
+                        if char in VOCAB_TO_ID:
+                            tokens.append(VOCAB_TO_ID[char])
+                    else:
+                        jamos = decompose_hangul(char)
+                        for j in jamos:
+                            if j in VOCAB_TO_ID:
+                                tokens.append(VOCAB_TO_ID[j])
+            else: # en
+                for char in part.lower():
+                    if char in VOCAB_TO_ID:
+                        tokens.append(VOCAB_TO_ID[char])
+
+        return tokens
+

package/termux_tts/vulkan_probe.py

@@ -0,0 +1,25 @@
+"""
+[DEPRECATED] This file is deprecated. 12-Stage Vulkan diagnostics are 100% delegated to ameva-vulkan-runtime.
+"""
+from typing import Dict, Any
+
+class VulkanDoctor:
+    """Legacy compatibility bridge delegating directly to ameva-vulkan-runtime."""
+    def __init__(self):
+        self.is_vulkan_available = False
+        self.ameva_runtime_bound = True
+        self.report = None
+
+    def probe_all(self) -> Dict[str, Any]:
+        try:
+            import ameva_vulkan_runtime as avr
+            doc = avr.Doctor()
+            rep = doc.run_self_test(verbose=False)
+            return {
+                "overall_success": getattr(rep, "overall_success", False),
+                "passed_stages": getattr(rep, "passed_stages", 0),
+                "recommended_backend": getattr(rep, "recommended_backend", "cpu"),
+                "status": "BOUND_AMEVA_VULKAN"
+            }
+        except Exception as e:
+            return {"overall_success": False, "passed_stages": 0, "status": "FALLBACK_CPU", "error": str(e)}

package/tests/test_expressive_presets.py

@@ -0,0 +1,29 @@
+"""
+Expressive Presets & Non-Verbal Acoustic Tokens Audit Suite for termux-tts.
+Tests Fast, Balanced, Expressive, Ultra presets and [laugh], [sigh], [breath], [clears_throat] tags.
+"""
+
+import time
+import pytest
+import numpy as np
+import termux_tts as tts
+from termux_tts.engine import QUALITY_PRESETS, load
+
+def test_all_four_presets_synthesis():
+    for preset_name in ["fast", "balanced", "expressive", "ultra"]:
+        t0 = time.perf_counter()
+        with load(language="ko", preset=preset_name) as engine:
+            res = engine.synthesize(f"현재 {preset_name} 품질 프리셋으로 음성을 합성 중입니다.")
+            assert res.preset == preset_name
+            assert res.sample_rate == QUALITY_PRESETS[preset_name]["sample_rate"]
+            assert res.duration_sec > 0.3
+            assert len(res.wav_bytes) > 1000
+            print(f"\n[PASS PRESET: {preset_name:10s}] Duration={res.duration_sec:.2f}s | Latency={res.elapsed_ms:.1f}ms | Rate={res.sample_rate}Hz")
+
+def test_expressive_breath_and_laugh_tokens():
+    expressive_text = "[clears_throat] 으흠! 안녕하세요 [laugh] 하하하! 오늘 날씨가 참 좋습니다 [sigh] 휴... [breath]"
+    with load(language="ko", preset="expressive") as engine:
+        res = engine.synthesize(expressive_text, output="expressive_demo.wav")
+        assert res.duration_sec > 1.0
+        assert res.sample_rate == 24000
+        print(f"\n[PASS EXPRESSIVE SYNTHESIS] Synthesized in {res.elapsed_ms:.1f}ms | Duration={res.duration_sec:.2f}s")

package/tests/test_g2p_korean.py

@@ -0,0 +1,73 @@
+"""
+Unit and Granular Test Suite for Korean Grapheme-to-Phoneme (G2P) Engine.
+Validates adherence to National Institute of Korean Language Standard Pronunciation Rules.
+"""
+
+import pytest
+from termux_tts.g2p_korean import korean_text_to_phonemes, KoreanG2PEngine
+from termux_tts.tokenizer import PhoneticTokenizer
+
+def test_palatalization_rule():
+    """Verify 구개음화 (제17항): ㄷ, ㅌ + ㅣ -> ㅈ, ㅊ"""
+    assert korean_text_to_phonemes("굳이") == "구지"
+    assert korean_text_to_phonemes("같이") == "가치"
+    assert korean_text_to_phonemes("미닫이") == "미다지"
+    assert korean_text_to_phonemes("붙이다") == "부치다"
+    assert korean_text_to_phonemes("핥이다") == "할치다"
+
+def test_aspiration_rule():
+    """Verify 격음화 / 거센소리되기 (제12항): ㄱ,ㄷ,ㅂ,ㅈ + ㅎ -> ㅋ,ㅌ,ㅍ,ㅊ"""
+    assert korean_text_to_phonemes("축하") == "추카"
+    assert korean_text_to_phonemes("좋다") == "조타"
+    assert korean_text_to_phonemes("입학") == "이팍"
+    assert korean_text_to_phonemes("맞히다") == "마치다"
+    assert korean_text_to_phonemes("좋은") == "조은"
+
+def test_nasalization_rule():
+    """Verify 비음화 (제18/19항): ㄱ,ㄷ,ㅂ + ㄴ,ㅁ -> ㅇ,ㄴ,ㅁ & ㅁ,ㅇ + ㄹ -> ㄴ"""
+    assert korean_text_to_phonemes("국물") == "궁물"
+    assert korean_text_to_phonemes("닫는") == "단는"
+    assert korean_text_to_phonemes("밥먹다") == "밤먹따"
+    assert korean_text_to_phonemes("독립") == "동닙"
+    assert korean_text_to_phonemes("백로") == "뱅노"
+    assert korean_text_to_phonemes("종로") == "종노"
+    assert korean_text_to_phonemes("심리") == "심니"
+
+def test_liquidization_rule():
+    """Verify 유음화 (제20항): ㄴ+ㄹ, ㄹ+ㄴ -> ㄹ+ㄹ"""
+    assert korean_text_to_phonemes("신라") == "실라"
+    assert korean_text_to_phonemes("난로") == "날로"
+    assert korean_text_to_phonemes("칼날") == "칼랄"
+    assert korean_text_to_phonemes("줄넘기") == "줄럼기"
+
+def test_tensification_rule():
+    """Verify 경음화 / 된소리되기 (제23항): ㄱ,ㄷ,ㅂ + ㄱ,ㄷ,ㅂ,ㅅ,ㅈ -> ㄲ,ㄸ,ㅃ,ㅆ,ㅉ"""
+    assert korean_text_to_phonemes("국밥") == "국빱"
+    assert korean_text_to_phonemes("학교") == "학꾜"
+    assert korean_text_to_phonemes("옷고름") == "옫꼬름"
+    assert korean_text_to_phonemes("옆집") == "엽찝"
+
+def test_liaison_rule():
+    """Verify 연음 규칙 (제13/14항): 받침 + 모음"""
+    assert korean_text_to_phonemes("옷이") == "오시"
+    assert korean_text_to_phonemes("닭을") == "달글"
+    assert korean_text_to_phonemes("값을") == "갑슬"
+
+def test_sino_korean_exceptions():
+    """Verify 특수 한자어 및 복합어 사전 예외 발음"""
+    assert korean_text_to_phonemes("생산량") == "생산냥"
+    assert korean_text_to_phonemes("결단력") == "결딴녁"
+    assert korean_text_to_phonemes("금융") == "금늉"
+    assert korean_text_to_phonemes("솜이불") == "솜니불"
+    assert korean_text_to_phonemes("맨입") == "맨닙"
+    assert korean_text_to_phonemes("꽃잎") == "꼰닙"
+
+def test_tokenizer_integration_with_g2p():
+    """Verify PhoneticTokenizer end-to-end normalization with G2P and numbers."""
+    tok = PhoneticTokenizer(language="ko")
+    # 100원 -> 백원 -> 배권 (연음/자음동화)
+    norm = tok.normalize_text("100원 국물 같이 굳이 먹자")
+    assert "배권" in norm or "백원" in norm
+    assert "궁물" in norm
+    assert "가치" in norm
+    assert "구지" in norm