termux-tts 0.1.1

package/tests/test_granular_tts.py

@@ -0,0 +1,141 @@
+"""
+Production-Grade Invariant & Acoustic Safety Test Suite for termux-tts.
+Validates G2P correctness, Number Normalization, Acoustic Signal Energy, Filter Stability, and Security Bounds.
+"""
+
+import os
+import time
+import pytest
+import numpy as np
+
+import termux_tts as tts
+from termux_tts.tokenizer import PhoneticTokenizer, decompose_hangul
+from termux_tts.audio import AudioBuffer
+from termux_tts.engine import TTSEngine, load
+from termux_tts.engine_dsp import apply_biquad_resonator
+from termux_tts.exceptions import (
+    TTSError,
+    TTSModelLoadError,
+    TTSInferenceError,
+    TTSAudioEncodingError,
+    TTSLanguageNotSupportedError,
+)
+
+# ==============================================================================
+# 1. Phonetic Tokenization & Number Normalization Invariants
+# ==============================================================================
+
+def test_hangul_jamo_decomposition():
+    jamos = decompose_hangul("한")
+    assert jamos == ["ㅎ", "ㅏ", "ㄴ"]
+    jamos_no_jong = decompose_hangul("가")
+    assert jamos_no_jong == ["ㄱ", "ㅏ"]
+
+def test_korean_number_normalization():
+    from termux_tts.tokenizer import normalize_numbers_korean
+    tok = PhoneticTokenizer(language="ko")
+    # 1. Place-value Sino-Korean string conversions
+    assert normalize_numbers_korean("100") == "백"
+    assert normalize_numbers_korean("1234") == "천이백삼십사"
+    assert normalize_numbers_korean("10000") == "만"
+    assert normalize_numbers_korean("2026년 9월 1일") == "이천이십육년 구월 일일"
+
+    # 2. G2P-applied phonetic normalization
+    phonetic_1234 = tok.normalize_text("1234")
+    assert "처니" in phonetic_1234  # Liaison: 천+이 -> 처니
+    assert "백" in phonetic_1234
+    
+    tokens = tok.tokenize("2026년 9월 1일")
+    assert len(tokens) > 10
+    assert all(isinstance(t, int) for t in tokens)
+
+def test_english_number_and_word_tokenization():
+    tok = PhoneticTokenizer(language="en")
+    norm_text = tok.normalize_text("System 123 active")
+    assert "one" in norm_text
+    assert "two" in norm_text
+    assert "three" in norm_text
+    tokens = tok.tokenize("System 123 active")
+    assert len(tokens) > 10
+
+def test_unsupported_language_guard():
+    with pytest.raises(TTSLanguageNotSupportedError):
+        PhoneticTokenizer(language="fr_unsupported")
+
+# ==============================================================================
+# 2. Audio Buffer & Acoustic Signal Invariants
+# ==============================================================================
+
+def test_audio_buffer_normalization():
+    raw = np.array([2.5, -3.0, 1.0, 0.5], dtype=np.float32)
+    buf = AudioBuffer(raw, sample_rate=22050)
+    assert np.max(np.abs(buf.samples)) <= 1.0
+    assert not np.isnan(buf.samples).any()
+    assert not np.isinf(buf.samples).any()
+
+def test_riff_wav_byte_encoding():
+    raw = np.sin(np.linspace(0, 2 * np.pi * 440, 2205, dtype=np.float32))
+    buf = AudioBuffer(raw, sample_rate=22050)
+    wav_bytes = buf.to_wav_bytes()
+    assert wav_bytes.startswith(b"RIFF")
+    assert b"WAVE" in wav_bytes
+    assert len(wav_bytes) > 2205 * 2
+
+def test_biquad_resonator_stability():
+    """Verify Biquad resonator does not explode or produce NaNs."""
+    impulse = np.zeros(1000, dtype=np.float32)
+    impulse[0] = 1.0
+    filtered = apply_biquad_resonator(impulse, f_res=800.0, bandwidth=80.0, sr=22050)
+    assert not np.isnan(filtered).any()
+    assert not np.isinf(filtered).any()
+    assert np.max(np.abs(filtered)) < 5.0
+
+# ==============================================================================
+# 3. Acoustic Synthesis & Fail-Fast Integrity
+# ==============================================================================
+
+def test_neural_synthesis_korean_acoustics():
+    with load(language="ko") as engine:
+        res = engine.synthesize("안녕하세요, 텀묵스 음향 합성 무결성 검증입니다.")
+        assert res.duration_sec > 0.5
+        assert res.sample_rate == 22050
+        assert res.rtf < 0.5
+        assert len(res.wav_bytes) > 1000
+        # Acoustic energy check: verify non-silent valid speech signal
+        rms = np.sqrt(np.mean(res.audio_buffer.samples ** 2))
+        assert rms > 0.005, f"Audio signal is virtually silent (RMS={rms})"
+
+def test_neural_synthesis_english_acoustics():
+    with load(language="en") as engine:
+        res = engine.synthesize("Hello world, this is termux speech synthesis.")
+        assert res.duration_sec > 0.5
+        rms = np.sqrt(np.mean(res.audio_buffer.samples ** 2))
+        assert rms > 0.005
+
+def test_zero_fallback_error_guards():
+    with load(language="ko") as engine:
+        with pytest.raises(TTSInferenceError):
+            engine.synthesize("")
+        with pytest.raises(TTSInferenceError):
+            engine.synthesize("   ")
+        with pytest.raises(TTSInferenceError):
+            engine.synthesize("Hello", speed=-1.0)
+        with pytest.raises(TTSInferenceError):
+            engine.synthesize("Hello", speed=5.0)
+
+# ==============================================================================
+# 4. Lifecycle & Performance Scaling
+# ==============================================================================
+
+def test_raii_context_manager_lifecycle():
+    with load(language="ko") as engine:
+        assert not engine._is_closed
+    assert engine._is_closed
+    with pytest.raises(TTSInferenceError):
+        engine.synthesize("Valid text")
+
+def test_speed_scaling_contract():
+    with load(language="ko") as engine:
+        res_normal = engine.synthesize("속도 테스트 문장입니다.", speed=1.0)
+        res_fast = engine.synthesize("속도 테스트 문장입니다.", speed=2.0)
+        assert res_fast.duration_sec < res_normal.duration_sec

package/tests/test_native_engine.py

@@ -0,0 +1,38 @@
+"""
+Unit Tests for Option B (Android Native System Voice Engine Bridge).
+"""
+
+import pytest
+import termux_tts as tts
+from termux_tts.engine_native import NativeAndroidEngine
+from termux_tts.exceptions import TTSInferenceError
+
+def test_native_engine_initialization():
+    engine = NativeAndroidEngine(language="ko", pitch=1.0, rate=1.0, stream="MUSIC")
+    assert engine.language == "ko"
+    assert engine.stream == "MUSIC"
+
+def test_native_engine_speak_empty_guard():
+    engine = NativeAndroidEngine(language="ko")
+    with pytest.raises(TTSInferenceError):
+        engine.speak("")
+    with pytest.raises(TTSInferenceError):
+        engine.speak("   ")
+
+def test_native_engine_speak_execution():
+    with tts.load(engine="native", language="ko") as engine:
+        if not engine.binary:
+            # 1. Non-Android host must fail-fast with strict TTSInferenceError (Zero-Fallback)
+            with pytest.raises(TTSInferenceError) as excinfo:
+                engine.speak("테스트 발화입니다.")
+            assert "FAIL-FAST" in str(excinfo.value)
+            print(f"\n[PASS NATIVE FAIL-FAST] Correctly rejected: {excinfo.value}")
+        else:
+            # 2. Genuine Android Termux system execution
+            res = engine.speak("테스트 발화입니다.")
+            assert res.engine_name == "Android_Native_Voice_Engine"
+            assert res.language == "ko"
+            assert res.elapsed_ms >= 0.0
+            print(f"\n[PASS NATIVE SPEAK] Engine: {res.engine_name} | Elapsed: {res.elapsed_ms:.2f}ms")
+
+

package/tests/test_onnx_engine.py

@@ -0,0 +1,48 @@
+"""
+Unit and Integration Tests for Real ONNX Neural Inference Engine & Gateway Routing.
+"""
+
+import os
+import pytest
+import numpy as np
+
+import termux_tts as tts
+from termux_tts.engine_onnx import ONNXNeuralEngine
+from termux_tts.engine_dsp import ParametricDSPEngine
+from termux_tts.exceptions import TTSModelLoadError, TTSInferenceError
+
+def test_onnx_engine_missing_model_fail_fast():
+    """Verify ONNXNeuralEngine raises TTSModelLoadError when model_path is None or onnxruntime missing."""
+    with pytest.raises(TTSModelLoadError) as excinfo:
+        ONNXNeuralEngine(model_path=None)
+    err_str = str(excinfo.value)
+    assert "model_path" in err_str or "onnxruntime" in err_str
+
+def test_onnx_engine_nonexistent_file_fail_fast():
+    """Verify ONNXNeuralEngine raises TTSModelLoadError when file does not exist or onnxruntime missing."""
+    with pytest.raises(TTSModelLoadError) as excinfo:
+        ONNXNeuralEngine(model_path="nonexistent_vits_model.onnx")
+    err_str = str(excinfo.value)
+    assert "does not exist" in err_str or "onnxruntime" in err_str
+
+def test_dsp_engine_explicit_execution():
+    """Verify ParametricDSPEngine executes with zero model dependencies."""
+    with tts.load(engine="dsp", language="ko") as engine:
+        assert isinstance(engine.synth_engine, ParametricDSPEngine)
+        res = engine.synthesize("DSP 포먼트 엔진 단독 구동 테스트입니다.")
+        assert res.duration_sec > 0.3
+        assert res.model_name == "parametric-formant-dsp"
+
+def test_gateway_auto_routing_to_dsp():
+    """Verify TTSEngine defaults to ParametricDSPEngine in auto mode when no model file is given."""
+    with tts.load(engine="auto", language="ko") as engine:
+        assert isinstance(engine.synth_engine, ParametricDSPEngine)
+        res = engine.synthesize("자동 라우팅 테스트입니다.")
+        assert res.duration_sec > 0.3
+
+def test_gateway_explicit_onnx_mode_requires_model():
+    """Verify tts.load(engine='onnx') fails fast if no model file is given."""
+    with pytest.raises(TTSModelLoadError):
+        with tts.load(engine="onnx", language="ko") as engine:
+            engine.synthesize("신경망 테스트")
+

package/tests/test_vulkan_routing.py

@@ -0,0 +1,52 @@
+"""
+Strict Dual Routing & Zero-Fallback Fail-Fast Verification for termux-tts.
+Tests:
+1. Explicit Vulkan mode (--device vulkan) -> Strict Fail-Fast on unavailable systems.
+2. Auto mode (--device auto) -> Auto-detection and seamless transition to CPU.
+3. Explicit CPU mode (--device cpu) -> Pure CPU execution.
+"""
+
+import pytest
+import termux_tts as tts
+from termux_tts.exceptions import VulkanInitializationError, TTSInferenceError
+from termux_tts.engine import load
+
+def test_explicit_cpu_mode():
+    with load(language="ko", device="cpu") as engine:
+        res = engine.synthesize("CPU 전용 모드 테스트입니다.")
+        assert "CPU" in res.backend
+        assert res.duration_sec > 0.3
+        print(f"\n[PASS CPU MODE] Backend: {res.backend}")
+
+def test_auto_routing_mode():
+    with load(language="ko", device="auto") as engine:
+        res = engine.synthesize("자동 라우팅 모드 테스트입니다.")
+        assert res.backend in ["VULKAN_GPU", "ARM64_NEON_CPU", "X86_64_AVX2_CPU", "X86_CPU"]
+        print(f"\n[PASS AUTO ROUTING] Resolved Backend: {res.backend}")
+
+def test_explicit_vulkan_fail_fast_when_disabled(monkeypatch):
+    from termux_tts import engine_dsp as dsp_mod
+    from termux_tts import engine_onnx as onnx_mod
+    from termux_tts import engine as eng_mod
+    
+    class FakeDoctorDisabled:
+        is_vulkan_available = False
+        def probe_all(self):
+            return {"V0_LoaderOpen": "FAIL"}
+
+    monkeypatch.setattr(dsp_mod, "VulkanDoctor", FakeDoctorDisabled)
+    monkeypatch.setattr(onnx_mod, "VulkanDoctor", FakeDoctorDisabled)
+    monkeypatch.setattr(eng_mod, "VulkanDoctor", FakeDoctorDisabled)
+
+    # 1. Explicit Vulkan MUST RAISE VulkanInitializationError (No silent fallback!)
+    with pytest.raises(VulkanInitializationError) as exc_info:
+        load(language="ko", device="vulkan")
+    assert "FAIL-FAST" in str(exc_info.value)
+    assert "--device cpu" in str(exc_info.value)
+    print(f"\n[PASS FAIL-FAST GUARD] Correctly rejected with: {exc_info.value}")
+
+    # 2. Auto mode MUST gracefully route to CPU
+    with load(language="ko", device="auto") as engine:
+        res = engine.synthesize("Vulkan 없을 때 자동 CPU 전환 테스트.")
+        assert "CPU" in res.backend
+        print(f"\n[PASS AUTO DEGRADE TO CPU] Gracefully resolved: {res.backend}")