better-french-tts/com.github.kvnpetit.betterfrenchtts/BetterFrenchTts

BetterFrenchTts

class BetterFrenchTts(context: Context, config: BetterFrenchTts.Config = Config())

High-level French TTS wrapper around Android's native TextToSpeech.

Automatically selects the best offline French voice, generates SSML behind the scenes, and exposes a Kotlin DSL for fine-grained speech control.

Quick start

val tts = BetterFrenchTts(context, BetterFrenchTts.Config(
    onReady = { it.speak("Bonjour le monde !") }
))

DSL usage

tts.speak {
    text("Bonjour.")
    pause(500)
    slow { text("Ceci est important.") }
}

Coroutine usage

lifecycleScope.launch {
    val result = tts.speakAndAwait("Bonjour le monde !")
}

Parameters

context

Android context (application context is used internally to avoid leaks).

config

Optional Config to customize voice selection, presets, and callbacks.

Constructors

BetterFrenchTts

constructor(context: Context, config: BetterFrenchTts.Config = Config())

Types

AudioFocusMode

enum AudioFocusMode : Enum<BetterFrenchTts.AudioFocusMode>

Strategy for managing audio focus while speaking.

Companion

object Companion

Config

data class Config(val defaultPreset: SpeechPreset = SpeechPreset.NEUTRAL, val preferredVoiceNames: List<String> = FrenchVoiceSelector.DEFAULT_PREFERRED_VOICES, val preprocessText: Boolean = true, val autoChunkLongText: Boolean = true, val audioFocus: BetterFrenchTts.AudioFocusMode = AudioFocusMode.DUCK, val onReady: (BetterFrenchTts) -> Unit? = null, val onInitError: (Int) -> Unit? = null)

Configuration for BetterFrenchTts.

Properties

currentQueuePosition

val currentQueuePosition: Int

Zero-based index of the item currently being spoken, or -1 if no queue is active.

currentVoice

var currentVoice: Voice?

The currently active Voice, or null if the engine is not yet ready or no voice was found.

isInitialized

val isInitialized: Boolean

true once the TTS engine has been initialized and a French voice has been selected.

isQueuePaused

val isQueuePaused: Boolean

true if a queue is active but paused.

isQueuePlaying

val isQueuePlaying: Boolean

true if a queue is currently playing (not paused).

isSpeaking

val isSpeaking: Boolean

true if the TTS engine is currently speaking an utterance.

queueSize

val queueSize: Int

Number of items currently in the queue. Returns 0 when no queue is active.

Functions

addPronunciation

fun addPronunciation(rule: PronunciationRule): BetterFrenchTts

Adds a pronunciation rule to the dictionary.

buildSsml

fun buildSsml(block: SpeechBuilder.() -> Unit): String

Returns the SSML that would be generated by the DSL block, without speaking it.

fun buildSsml(text: String, preset: SpeechPreset = config.defaultPreset): String

Returns the SSML that would be generated for text with the given preset, without speaking it.

clearPronunciations

fun clearPronunciations(): BetterFrenchTts

Removes all entries from the pronunciation dictionary.

clearQueue

fun clearQueue(): BetterFrenchTts

Clears the speech queue and stops any ongoing playback.

enqueue

fun enqueue(block: SpeechBuilder.() -> Unit): BetterFrenchTts

Adds a DSL-built speech item to the queue.

fun enqueue(text: String, preset: SpeechPreset = config.defaultPreset): BetterFrenchTts

Adds a text item to the speech queue.

enqueueAll

fun enqueueAll(texts: List<String>, preset: SpeechPreset = config.defaultPreset): BetterFrenchTts

Adds multiple text items to the queue at once, all sharing the same preset.

listAvailableVoices

fun listAvailableVoices(): List<Voice>

Returns all available offline French voices on this device, sorted by quality (descending).

onDone

fun onDone(callback: (String) -> Unit): BetterFrenchTts

Registers a callback invoked on the main thread when an utterance finishes successfully.

onError

fun onError(callback: (String) -> Unit): BetterFrenchTts

Registers a callback invoked on the main thread when an utterance fails.

onQueueFinished

fun onQueueFinished(callback: () -> Unit): BetterFrenchTts

Registers a callback invoked on the main thread when all queue items have been spoken.

onQueueProgress

fun onQueueProgress(callback: (QueueProgress) -> Unit): BetterFrenchTts

Registers a callback invoked on the main thread each time a new queue item starts playing.

onStart

fun onStart(callback: (String) -> Unit): BetterFrenchTts

Registers a callback invoked on the main thread when an utterance starts playing.

onWordHighlight

fun onWordHighlight(callback: (WordHighlight) -> Unit): BetterFrenchTts

Registers a callback invoked on the main thread each time the TTS engine starts speaking a new word or text range.

pauseQueue

fun pauseQueue(): SpeechResult

Pauses the speech queue.

playQueue

fun playQueue(): SpeechResult

Starts playing the speech queue from the beginning.

removePronunciation

fun removePronunciation(word: String): BetterFrenchTts

Removes a word from the pronunciation dictionary.

resumeQueue

fun resumeQueue(): SpeechResult

Resumes a paused speech queue.

setVoice

fun setVoice(voice: Voice)

Manually sets the active TTS voice.

shutdown

fun shutdown()

Releases all TTS resources. Must be called when the instance is no longer needed (e.g. in Activity.onDestroy() or a Compose DisposableEffect).

skipToNext

fun skipToNext(): SpeechResult

Skips to the next item in the queue.

speak

fun speak(queueMode: Int = TextToSpeech.QUEUE_FLUSH, block: SpeechBuilder.() -> Unit): SpeechResult

Speaks content built with the Kotlin DSL.

fun speak(text: String, preset: SpeechPreset = config.defaultPreset, queueMode: Int = TextToSpeech.QUEUE_FLUSH): SpeechResult

Speaks text aloud using the given preset.

speakAndAwait

suspend fun speakAndAwait(queueMode: Int = TextToSpeech.QUEUE_FLUSH, block: SpeechBuilder.() -> Unit): SpeechResult

Suspends until the TTS engine finishes speaking the DSL content.

suspend fun speakAndAwait(text: String, preset: SpeechPreset = config.defaultPreset): SpeechResult

Suspends until the TTS engine finishes speaking text.

speakSsml

fun speakSsml(ssml: String, queueMode: Int = TextToSpeech.QUEUE_FLUSH): SpeechResult

Speaks raw SSML directly, bypassing the DSL and preset system.

speakWithPreset

fun speakWithPreset(preset: SpeechPreset, queueMode: Int = TextToSpeech.QUEUE_FLUSH, block: SpeechBuilder.() -> Unit): SpeechResult

Speaks DSL content wrapped in the given preset prosody.

stop

fun stop()

Stops any ongoing speech immediately and clears the playback queue.

synthesizeToFile

fun synthesizeToFile(text: String, file: File, preset: SpeechPreset = config.defaultPreset): SpeechResult

Renders text to a WAV audio file using the given preset.

BetterFrenchTts

Quick start

DSL usage

Coroutine usage

Parameters

See also

Constructors

Types

Properties

Functions