Speko Docs

Android (Kotlin)

Run a Speko voice conversation in a native Android app with ai.speko:client-android.

ai.speko:client-android joins a Speko voice session from an Android app. It captures the mic, plays the agent, and streams a reconciled transcript. It runs over LiveKit, or Daily when the session says so.

val conversation = VoiceConversation.create(
    context,
    VoiceConversationOptions(
        transportToken = session.transportToken,
        transportUrl = session.transportUrl,
        transport = Transport.fromWire(session.transport),
    ),
)

The three values come from your backend. See Mint a session on your backend.

Install

// build.gradle.kts (app module)
dependencies {
    implementation("ai.speko:client-android:0.1.0")
}

Your repositories need google(), mavenCentral() and JitPack, which hosts LiveKit's audio-routing dependency. The SDK requires minSdk 24.

// settings.gradle.kts
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven("https://jitpack.io")
    }
}

0.1.0 is not on Maven Central yet. Build it from packages/client-kotlin with ./gradlew :speko-client:publishToMavenLocal, then add mavenLocal() to your repositories.

Platform setup

Permissions

The SDK manifest merges in INTERNET, ACCESS_NETWORK_STATE, RECORD_AUDIO, MODIFY_AUDIO_SETTINGS and BLUETOOTH_CONNECT. You add nothing to your manifest.

RECORD_AUDIO is a runtime permission. Your app requests it before calling create. The SDK only checks it.

val requestMic = registerForActivityResult(ActivityResultContracts.RequestPermission()) { granted ->
    if (granted) startCall()
}
requestMic.launch(Manifest.permission.RECORD_AUDIO)

Without the permission, create throws MICROPHONE_FAILED before it joins. The session token stays unused, so you can retry text-only with micEnabled = false.

Audio session

During a call the device is in voice-call mode (MODE_IN_COMMUNICATION) and holds audio focus. The previous mode comes back when the call ends. On LiveKit, LiveKit's audio handler does this and routes to speaker, wired headset or Bluetooth. On Daily, the SDK does it.

Background audio

The SDK does not start a foreground service. To keep a call alive with the screen off, run it from your own foreground service of type microphone (FOREGROUND_SERVICE_MICROPHONE on Android 14 and later).

Quickstart

  1. Mint a session on your backend and return transport, transportToken and transportUrl.
  2. Request RECORD_AUDIO.
  3. Create the conversation and collect its flows.
import ai.speko.client.Transport
import ai.speko.client.VoiceConversation
import ai.speko.client.VoiceConversationOptions

class CallViewModel(private val app: Application) : AndroidViewModel(app) {
    var conversation: VoiceConversation? = null
        private set

    fun start(session: SessionResponse) = viewModelScope.launch {
        val conv = VoiceConversation.create(
            app,
            VoiceConversationOptions(
                transportToken = session.transportToken,
                transportUrl = session.transportUrl,
                transport = Transport.fromWire(session.transport),
            ),
        )
        conversation = conv
        conv.transcript.collect { lines -> render(lines) }
    }

    fun mute(muted: Boolean) = viewModelScope.launch { conversation?.setMicMuted(muted) }

    fun end() = viewModelScope.launch { conversation?.endSession() }
}

SessionResponse is your backend's JSON, and render is your UI.

Render the transcript

Collect transcript, not raw messages. Transcript updates are cumulative: a segment arrives again and again with growing text. The SDK merges them into one bubble per speaker turn, ordered by startedAt.

@Composable
fun Transcript(conversation: VoiceConversation) {
    val lines by conversation.transcript.collectAsState()
    LazyColumn {
        items(lines) { line ->
            val who = if (line.source == MessageSource.AGENT) "Agent" else "You"
            Text("$who: ${line.text}")
        }
    }
}

Java

VoiceConversation.createAsync(context, options, new VoiceConversation.CreateCallback() {
    @Override public void onSuccess(VoiceConversation conversation) { }
    @Override public void onFailure(Throwable error) { }
});

Java code can't collect flows, so pass a VoiceConversationListener as listener in the options. Each callback mirrors one ConversationEvent and runs on the main thread. Kotlin code should collect the flows instead.

API reference

VoiceConversationOptions

FieldTypeRequiredDefaultDescription
transportTokenStringYesFrom your backend.
transportUrlStringYesFrom your backend.
transportTransportNoLIVEKITLIVEKIT or DAILY. Use Transport.fromWire(session.transport).
micEnabledBooleanNotruefalse joins text-only. No permission needed.
audioConstraintsAudioConstraintsNoall trueechoCancellation, noiseSuppression, autoGainControl.
listenerVoiceConversationListener?NonullCallbacks for Java callers. Mirrors events.

VoiceConversation

MemberDescription
suspend create(context, options)Connects and returns the live conversation.
createAsync(context, options, callback)Java variant. Returns a cancellable Job.
statusStateFlow<ConversationStatus>: CONNECTING, CONNECTED, DISCONNECTING, DISCONNECTED.
modeStateFlow<ConversationMode>: SPEAKING while the agent talks, else LISTENING.
transcriptStateFlow<List<ConversationMessage>>: the reconciled transcript.
eventsSharedFlow<ConversationEvent>. Not replayed.
getId()LiveKit room name, or the Daily room URL.
isOpen()true while connected.
suspend endSession()Leaves the call. Safe to call twice.
suspend setMicMuted(muted)No-op on a text-only session.
setVolume(volume)Agent volume, 0.0 to 1.0. LiveKit only; a no-op on Daily.
suspend sendChatMessage(text)Typed user turn. The agent answers by voice.
canPlaybackAudiotrue while connected. Android has no autoplay block.
suspend startAudioPlayback()No-op, kept for parity.

Events and callbacks

ConversationEventListener methodWhen
Connected(conversationId)onConnectThe session is live. Fires inside create.
Disconnected(details)onDisconnectThe call ended. details.reason is USER, AGENT, ERROR, TIMEOUT or UNKNOWN.
Message(message)onMessageOne raw transcript update.
Transcript(messages)onTranscriptThe full reconciled transcript after an update.
StatusChanged(status)onStatusChangeStatus changed.
ModeChanged(mode)onModeChangeThe agent started or stopped speaking.
Error(error)onErrorNon-fatal error. The call continues.

ConversationMessage

FieldTypeDescription
sourceMessageSourceAGENT or USER.
textStringThe turn's text so far.
isFinalBooleanfalse while the turn is still being transcribed.
segmentIdString?Stable key of the turn.
startedAtLong?Epoch ms when the turn began.

Errors

SpekoClientException carries a code. Failures in create are thrown. Failures during a call go to events and onError.

CodeCauseWhat to do
MICROPHONE_FAILEDRECORD_AUDIO missing, or mic capture or publish failed.Request the permission, or retry with micEnabled = false.
CONNECTION_FAILEDThe transport rejected the join.Mint a fresh session. Tokens are short-lived.
CONNECTION_TIMEOUTDaily only: the agent was not ready within 30 seconds.Retry with a new session.
NOT_CONNECTEDA send ran before the call connected.Wait for CONNECTED.
UNSUPPORTED_TRANSPORTTransport.fromWire got a transport this SDK cannot run.Update the SDK.

A blank token or URL throws IllegalArgumentException.

Limitations

  • RealtimeVoiceConversation (provider-direct speech-to-speech), CallListener and the embed element are not yet available on mobile.
  • setVolume has no effect on Daily. The Pipecat Android client exposes no playback volume.
  • On Daily, getId() returns the room URL. The Pipecat Android client does not expose the session id.
  • Agent transcript lines on Daily come from Pipecat bot-output messages, so they follow what the bot speaks, not the raw LLM text.

Troubleshooting

SymptomFix
MICROPHONE_FAILED on every callThe app never got RECORD_AUDIO. Request it before create.
CONNECTION_FAILED on the second callThe token was reused. Mint one session per call.
Agent audio plays from the earpieceVoice-call mode prefers the earpiece. Route with LiveKit's audioSwitchHandler, or plug in a headset.
Call drops when the app goes to the backgroundRun the call from a microphone foreground service.
Transcript repeats wordsYou appended raw Message events. Render transcript instead.

Next step

On this page