TextToSpeech

OverviewPrzegląd

The TextToSpeech module provides high-quality local speech synthesis powered by neural VITS/Piper models running via Sherpa-ONNX. Unlike Android's built-in TTS, this module produces natural, expressive voices entirely on-device without sending any data to the cloud. Models are downloaded on-demand (~15-65 MB per voice) and cached locally. Moduł TextToSpeech zapewnia wysokiej jakości lokalną syntezę mowy opartą na neuronowych modelach VITS/Piper uruchamianych przez Sherpa-ONNX. W przeciwieństwie do wbudowanego TTS Androida, ten moduł generuje naturalne, ekspresyjne głosy w pełni na urządzeniu, bez wysyłania danych do chmury. Modele są pobierane na żądanie (~15-65 MB per głos) i cachowane lokalnie.

Quick StartSzybki start

// 1. Download a voice (one-time) / Pobierz głos (jednorazowo)
ADict.TextToSpeech.downloadVoice("pl_PL-gosia-medium").collect { state ->
    when (state) {
        is DownloadState.Downloading -> {
            val percent = (state.progress * 100).toInt()
            progressBar.progress = percent
        }
        is DownloadState.Extracting -> showStatus("Preparing...")
        is DownloadState.Completed -> showStatus("Ready!")
        is DownloadState.Error -> showError(state.message)
        else -> {}
    }
}

// 2. Speak! / Mów!
ADict.TextToSpeech.speak("Cześć! To jest test syntezy mowy.")

// With specific voice / Z konkretnym głosem:
ADict.TextToSpeech.speak("Hello world!", voiceId = "en_US-amy-medium")

Available VoicesDostępne głosy

Voice ManagementZarządzanie głosami

// List all available voices / Wszystkie dostępne głosy
val allVoices = ADict.TextToSpeech.getAvailableVoices()

// Voices for a language / Głosy dla języka
val polishVoices = ADict.TextToSpeech.getVoicesForLanguage("pl-PL")

// Available languages / Dostępne języki
val languages = ADict.TextToSpeech.getAvailableLanguages()

// Downloaded (ready) voices / Pobrane (gotowe) głosy
val downloaded = ADict.TextToSpeech.getDownloadedVoices()

// Check if voice is ready / Sprawdź czy głos jest gotowy
val ready = ADict.TextToSpeech.isVoiceReady("pl_PL-gosia-medium")

// Delete a voice / Usuń głos
ADict.TextToSpeech.deleteVoice("en_US-amy-medium")

// Storage used / Zajęte miejsce
val bytes = ADict.TextToSpeech.getStorageUsed()
val megabytes = bytes / (1024 * 1024)

ConfigurationKonfiguracja

// Configure module / Konfiguruj moduł
ADict.TextToSpeech.configure(
    useSystemFallback = true,   // Use Android TTS if model not downloaded
    defaultSpeed = 1.0f,        // Speech speed (0.5 - 2.0)
    defaultVoice = "pl_PL-gosia-medium"
)

// Change speed on the fly / Zmień prędkość
ADict.TextToSpeech.setSpeed(1.2f)  // Slightly faster

// Set default voice / Ustaw domyślny głos
ADict.TextToSpeech.setDefaultVoice("en_US-lessac-medium")

// Stop current speech / Zatrzymaj bieżącą mowę
ADict.TextToSpeech.stop()

// Check if speaking / Czy mówi
val speaking = ADict.TextToSpeech.isSpeaking()

Advanced: Raw SynthesisZaawansowane: surowa synteza

// Synthesize without playing (get raw audio data)
// Syntetyzuj bez odtwarzania (pobierz surowe dane audio)
val result: TtsResult? = ADict.TextToSpeech.synthesize(
    text = "Hello world",
    voiceId = "en_US-amy-medium"
)

result?.let {
    println("Samples: ${it.samples.size}")
    println("Sample rate: ${it.sampleRate} Hz")
    println("Synthesis time: ${it.synthesisTimeMs} ms")
    val durationSec = it.samples.size.toFloat() / it.sampleRate
    println("Audio duration: ${durationSec}s")
}

System FallbackFallback systemowy

When useSystemFallback = true, the module automatically falls back to Android's built-in TextToSpeech if the neural model is not downloaded. This ensures your app always has TTS capability, even before the user downloads a high-quality voice. Gdy useSystemFallback = true, moduł automatycznie przełącza się na wbudowany TextToSpeech Androida, jeśli model neuronowy nie jest pobrany. Dzięki temu aplikacja zawsze ma możliwość syntezy mowy, nawet zanim użytkownik pobierze głos wysokiej jakości.

ADict.TextToSpeech.configure(useSystemFallback = true)

// This will use system TTS if "pl_PL-gosia-medium" is not downloaded
// Użyje systemowego TTS jeśli "pl_PL-gosia-medium" nie jest pobrany
ADict.TextToSpeech.speak("Cześć!")

Download with Progress UIPobieranie z UI postępu

// Example: Download voice with ProgressBar in Fragment/Activity
lifecycleScope.launch {
    ADict.TextToSpeech.downloadVoice("pl_PL-gosia-medium").collect { state ->
        when (state) {
            is DownloadState.Idle -> {
                progressBar.visibility = View.GONE
                statusText.text = "Ready to download"
            }
            is DownloadState.Downloading -> {
                progressBar.visibility = View.VISIBLE
                progressBar.progress = (state.progress * 100).toInt()
                statusText.text = "${(state.bytesDownloaded / 1024 / 1024)} MB " +
                    "/ ${(state.totalBytes / 1024 / 1024)} MB"
            }
            is DownloadState.Extracting -> {
                statusText.text = "Preparing voice data..."
            }
            is DownloadState.Completed -> {
                progressBar.visibility = View.GONE
                statusText.text = "Voice ready! ✓"
                // Now you can speak
                ADict.TextToSpeech.speak("Gotowe!")
            }
            is DownloadState.Error -> {
                progressBar.visibility = View.GONE
                statusText.text = "Error: ${state.message}"
            }
        }
    }
}

API Reference

ArchitectureArchitektura

┌──────────────────────────────────────────────────────┐
│                  TextToSpeech (Facade)                │
│  speak() · synthesize() · downloadVoice() · stop()   │
├──────────────────────────────────────────────────────┤
│    TtsEngine         │  ModelManager  │  AudioPlayer  │
│  Sherpa-ONNX wrapper │  Download &    │  AudioTrack   │
│  VITS/Piper models   │  file mgmt     │  PCM playback │
├──────────────────────┼────────────────┤               │
│                      │  ModelPatcher  │               │
│                      │  ONNX metadata │               │
│                      │  injection     │               │
├──────────────────────────────────────────────────────┤
│              VoiceRegistry (voice catalog)            │
│  en_US-amy · pl_PL-gosia · de_DE-thorsten · ...     │
├──────────────────────────────────────────────────────┤
│           Sherpa-ONNX (native C++ via JNI)           │
│           ONNX Runtime · VITS inference              │
└──────────────────────────────────────────────────────┘