CopiloTTS

1.0.0-2.3.21indexed

Text-to-speech SDK with native engines and HuggingFace ONNX models, SSML, voice selection, progress tracking, priority queuing, model management and on-demand downloads.

AndroidNative·sigmadeltasoftware/CopiloTTS

Stars

—

Used by

dependents

—

Health

/ 100

CopiloTTS Logo

CopiloTTS

A Kotlin Multiplatform Text-to-Speech SDK with support for native platform engines and HuggingFace open-source models.

Features

Native TTS Engines: Android TextToSpeech and iOS AVSpeechSynthesizer with full multilingual support
HuggingFace Models: High-quality Supertonic English TTS model via ONNX Runtime (4 voice styles: F1, F2, M1, M2)
Full-Featured API: SSML, voice selection, callbacks, progress tracking, priority queuing
Easy Integration: Simple API with sensible defaults
Kotlin Multiplatform: Shared code for Android and iOS (Compose Multiplatform)

As used in Drivista - the ultimate route planning and navigation app for driving enthusiasts.

Demo

https://github.com/user-attachments/assets/ab566f24-4248-484c-86a2-e9557a130f2f

Installation

Add the dependency to your build.gradle.kts:

dependencies {
    implementation("app.drivista:copilotts:1.0.0-2.3.21")
}

The version format is {library-version}-{kotlin-version}. Choose the artifact that matches your project's Kotlin version.

CopiloTTS Version
1.0.0

Supported Kotlin Versions
2.1.20
2.2.20
2.3.21

Quick Start

// Initialize
val tts = CopiloTTS()
tts.initialize()

// Simple speech
tts.speak("Hello, world!")

// With options
tts.speak(SpeakRequest(
    text = "Hello with options!",
    priority = TTSPriority.HIGH,
    speechRate = 1.2f,
    volume = 0.8f
))

// Cleanup
tts.shutdown()

Configuration

val config = TTSConfig(
    preferredEngine = TTSEngineType.NATIVE,
    defaultSpeechRate = 1.0f,
    defaultVolume = 0.8f,
    audioDucking = true,
    queueConfig = QueueConfig(
        maxQueueSize = 100,
        enablePriorityQueue = true
    )
)

val tts = CopiloTTS(config)

Voice Selection

// Get available voices
val voices = tts.availableVoices.value

// Set a specific voice
tts.setVoice(voices.first())

SSML Support

val ssml = ssml {
    text("Hello, ")
    emphasis("world", EmphasisLevel.STRONG)
    pause(500)
    prosody(text = "This is slower", rate = "slow")
}

tts.speak(SpeakRequest(text = "Hello", ssml = ssml))

Callbacks

tts.setCallback(ttsCallback {
    onStart { id -> println("Started: $id") }
    onDone { id -> println("Done: $id") }
    onProgress { id, progress, word ->
        println("Progress: ${(progress * 100).toInt()}%")
    }
    onError { id, error ->
        println("Error: ${error.message}")
    }
})

Priority Queue

// Normal priority (queued)
tts.speak(SpeakRequest(text = "First", priority = TTSPriority.NORMAL))
tts.speak(SpeakRequest(text = "Second", priority = TTSPriority.NORMAL))

// Urgent priority (interrupts current speech)
tts.speak(SpeakRequest(text = "Urgent!", priority = TTSPriority.URGENT))

HuggingFace Models

CopiloTTS supports HuggingFace open-source TTS models via ONNX Runtime on both Android and iOS. Models can be bundled with your app or downloaded on-demand with progress tracking.

Model Management APIs

The SDK provides comprehensive APIs for building model management UIs:

// Get all supported models with metadata
val models: List<ModelInfo> = tts.getAllSupportedModels()

// Get model status (downloaded, downloading, available)
val statuses: List<ModelStatus> = tts.getModelStatuses()
statuses.forEach { status ->
    println("${status.model.displayName}: ${status.state}")
    // state can be: NOT_DOWNLOADED, DOWNLOADING, DOWNLOADED, BUNDLED
    // downloaded models include file path and size
}

// Check specific model status
val status = tts.getModelStatus("Supertone/supertonic")

Download with Progress

// Download with Flow-based progress tracking
tts.downloadModelWithProgress(modelId = "Supertone/supertonic")
    .collect { progress ->
        when (progress) {
            is DownloadProgress.Starting -> showLoading()
            is DownloadProgress.Progress -> {
                updateProgressBar(progress.percent)
                updateProgressText("${progress.downloadedBytes} / ${progress.totalBytes}")
            }
            is DownloadProgress.Completed -> showSuccess()
             DownloadProgress.Error -> showError(progress.message)
        }
    }


tts.cancelModelDownload(modelId)


 isDownloading = tts.isAnyModelDownloading()

Storage Info

// Get storage information for UI
val storageInfo = tts.getStorageInfo()
println("Used: ${storageInfo.usedSpaceFormatted}")      // "1.2 GB"
println("Available: ${storageInfo.availableSpaceFormatted}") // "8.5 GB"
println("Downloaded models: ${storageInfo.downloadedModelCount}")

Switch Between Engines

// Use a HuggingFace model
val result = tts.useHuggingFaceModel("Supertone/supertonic")
result.onSuccess { tts.speak("Now using Supertonic model") }
       .onError { println("Failed: ${it.message}") }

// Switch back to native engine
tts.useNativeEngine()

// Check current engine
val engineType = tts.getActiveEngineType()

// Check if HuggingFace is available (model downloaded)
val available = tts.isHuggingFaceAvailable()

Delete Models

// Delete a downloaded model
tts.deleteModel("Supertone/supertonic")

Example: Model Selection UI

Dependency Injection (Koin)

// In your Application class
startKoin {
    androidContext(this@App)
    modules(copiloTTSModule())
}

// Inject CopiloTTS
class MyViewModel(private val tts: CopiloTTS) {
    // ...
}

Android Setup

// In Application.onCreate()
class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()
        NativeTTSEngine.setContext(this)
        ModelStorage.ContextProvider.setContext(this)
    }
}

iOS Setup

iOS integration uses Kotlin Multiplatform directly. The library exports protocols that you implement in Swift:

TTSNativeHandler - bridges to AVSpeechSynthesizer for native TTS
HuggingFaceHandler - bridges to ONNX Runtime for HuggingFace models

1. Build the Kotlin Framework

First, build the iOS framework from your KMP project:

# For simulator (development)
./gradlew :sample:linkDebugFrameworkIosSimulatorArm64

# For device (release)
./gradlew :sample:linkReleaseFrameworkIosArm64

2. Create Swift TTSNativeHandler Implementation

Create TTSNativeHandler.swift in your iOS app. Import your framework (the name matches your KMP module's baseName):

Note: See iosApp/iosApp/TTSNativeHandler.swift.

2b. Add ONNX Runtime for HuggingFace Support (Optional)

If you want HuggingFace model support on iOS, add ONNX Runtime via Swift Package Manager:

In Xcode, go to File → Add Package Dependencies
Add: https://github.com/microsoft/onnxruntime-swift-package-manager
Select version 1.19.2 or later
Add the onnxruntime package product to your target

Then create HuggingFaceHandler.swift:

Note: The full HuggingFaceHandler.swift implementation (~300 lines) including the complete Supertonic inference pipeline is available in the sample app at iosApp/iosApp/HuggingFaceHandler.swift.

3. Register Handlers Before Koin

In your iOS app's entry point, register the handlers before Koin starts (which happens when the Compose view loads):

import SwiftUI
import ComposeApp  // Your KMP framework name

@main
struct MyApp: App {
    init() {
        // Register handlers BEFORE Koin starts
        TTSNativeHandlerProvider.shared.setHandler(handler: TTSNativeHandlerImpl())
        .shared.setHandler(handler: ())
    }

     body:   {
         {
            ()
        }
    }
}

4. Include Platform Modules in Koin

In your KMP project's iosMain source set, include the iOS handler modules:

// In iosMain/kotlin/.../PlatformModule.ios.kt
actual fun platformModules(): List<Module> = listOf(
    ttsNativeHandlerModule(),
    huggingFaceHandlerModule()
)

5. Configure Xcode Project

Your Xcode project needs to link the Kotlin framework.

6. Run the iOS App

# Open Xcode project
open iosApp/iosApp.xcodeproj

# Or build from command line
xcodebuild -project iosApp/iosApp.xcodeproj -scheme iosApp -destination 'platform=iOS Simulator,name=iPhone 15'

API Reference

CopiloTTS

Model Management

StateFlows

Supported Models

Model	Size	Language	Voices	Platform
Supertonic	265 MB	English	4 (F1, F2, M1, M2)	Android & iOS

Note: For non-English languages, use Native TTS (Android TextToSpeech / iOS AVSpeechSynthesizer) which provides excellent multilingual support with no downloads required.

License

Related libraries

Surfaced from shared tags and platforms — no rankings paid for.

kubriko★ 249

pandulapeterLightweight 2D game engine enables creation of simple games with modular plugins for scaling, object management, audio, shaders, and physics. Offers tools like Scene Editor and Debug Menu.Shared: compose-multiplatform, compose, audio

material3-windowsizeclass-multiplatform★ 361

chrisbanesFacilitates responsive UI design by implementing Material 3 window size classes across multiple platforms, ensuring layouts adapt to various screen sizes. Supports Android, iOS, desktop, and web environments.Shared: compose-multiplatform, compose, apple

KScan★ 336

ismai117Enables easy barcode scanning in apps using Google’s MLKit on Android and Apple's AVFoundation on iOS, supporting QR and EAN-13 formats with simple integration.Shared: compose-multiplatform, compose, apple

MediaPlayer-KMP★ 302

KhubaibKhan4Enables seamless YouTube video and audio playback across multiple platforms, integrating with JetBrains Compose Multiplatform. Features include authentication tokens, event handling, and reels view support.Shared: compose-multiplatform, compose, audio

SaltAudioTag★ 161

MoriaflyCross-platform audio tag editor in early development, leveraging Compose for UI and kotlinx-io for IO operations, supporting FLAC format metadata reading and writing.Shared: compose-multiplatform, compose, apple

ComposeNativeWebview★ 155

kdroidFilterCross-platform WebView component exposing WebViewState and navigator APIs; backed by native OS webviews via Rust+UniFFI (Wry), with JS-native bridge, cookie API, request interceptor.Shared: compose-multiplatform, compose, apple

`initialize()`	Initialize the TTS engine
`speak(request)`	Speak text with options
`speak(text)`	Simple speak with text
`pause()`	Pause speech (iOS only)
`resume()`	Resume speech
`stop()`	Stop current speech
`stopAll()`	Stop and clear queue
`shutdown()`	Release resources
`setVoice(voice)`	Set the voice
`setSpeechRate(rate)`	Set speech rate (0.5-2.0)
`setVolume(volume)`	Set volume (0.0-1.0)
`downloadModel(id)`	Download HuggingFace model
`deleteModel(id)`	Delete downloaded model

`getAllSupportedModels()`	Get list of all supported models
`getModelStatuses()`	Get download status of all models
`getModelStatus(id)`	Get status of specific model
`downloadModelWithProgress(id)`	Download with Flow progress
`cancelModelDownload(id)`	Cancel ongoing download
`isAnyModelDownloading()`	Check for active downloads
`getStorageInfo()`	Get storage usage info
`useHuggingFaceModel(id)`	Switch to HuggingFace model
`useNativeEngine()`	Switch to native TTS
`getActiveEngineType()`	Get current engine type
`isHuggingFaceAvailable()`	Check if HF is ready

`state`	Current TTS state
`isSpeaking`	Whether currently speaking
`progress`	Speech progress (0.0-1.0)
`currentVoice`	Currently selected voice
`availableVoices`	Available voices
`queueSize`	Number of queued items