Speko Docs

Flutter

Run a Speko voice conversation in a Flutter app on iOS and Android with speko_client.

speko_client joins a Speko voice session from a Flutter app. It captures the mic, plays the agent, and streams a reconciled transcript. It runs on iOS and Android over LiveKit.

import 'package:speko_client/speko_client.dart';

final conversation = await VoiceConversation.create(
  transport: session['transport'] as String?,
  transportToken: session['transportToken'] as String,
  transportUrl: session['transportUrl'] as String,
);

session is the JSON your backend returns after it calls POST /v1/sessions. Mint a session on your backend shows that endpoint.

Install

flutter pub add speko_client

0.1.0 is not on pub.dev yet. Until it is, add speko_client as a path dependency pointing at packages/client-flutter.

The package needs Flutter 3.38 or newer and Dart 3.10 or newer. It brings in livekit_client 2.x.

Platform setup

iOS

Add the microphone prompt to ios/Runner/Info.plist:

<key>NSMicrophoneUsageDescription</key>
<string>Talk to the voice assistant.</string>

Current Flutter releases need iOS 15 or later. If your app still uses CocoaPods instead of Swift Package Manager, set the target in ios/Podfile and run pod install:

platform :ios, '15.0'

LiveKit sets the audio session to playAndRecord in voiceChat mode while the mic is published. To keep a call alive when the app goes to the background, add audio to UIBackgroundModes. The SDK doesn't turn this on for you.

Android

Add these permissions to android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />

Set minSdk = 24 in android/app/build.gradle.kts. LiveKit uses the Android communication audio mode during a call.

Microphone permission

Asking for the permission is your app's job. Request it before you call create, for example with permission_handler:

final status = await Permission.microphone.request();
if (!status.isGranted) {
  // Show a settings prompt, or start text-only with micEnabled: false.
}

If capture fails, create throws microphoneFailed before it joins the room. The session token is still unused, so you can retry the same session with micEnabled: false.

Quickstart

import 'dart:convert';

import 'package:http/http.dart' as http;
import 'package:speko_client/speko_client.dart';

Future<VoiceConversation> startCall() async {
  // Your backend calls POST /v1/sessions with your Speko API key.
  final response = await http.post(Uri.parse('https://your-app.example/api/voice-session'));
  final session = jsonDecode(response.body) as Map<String, dynamic>;

  return VoiceConversation.create(
    transport: session['transport'] as String?,
    transportToken: session['transportToken'] as String,
    transportUrl: session['transportUrl'] as String,
  );
}

Then watch and control the call:

conversation.disconnected.then((details) => print('Call ended: ${details.reason}'));
conversation.errors.listen((error) => print('Call error: $error'));

await conversation.setMicMuted(true);
conversation.setVolume(0.5);
await conversation.sendChatMessage('What are your opening hours?');
await conversation.endSession();

Render the transcript

Bind transcript to a ValueListenableBuilder. Each entry is one speaker turn, already deduplicated and ordered by startedAt.

ValueListenableBuilder<List<ConversationMessage>>(
  valueListenable: conversation.transcript,
  builder: (context, transcript, _) => ListView(
    children: [
      for (final m in transcript)
        ListTile(
          title: Text(m.text),
          subtitle: Text(m.source.name),
          // Interim text can still change; render it differently.
          enabled: m.isFinal,
        ),
    ],
  ),
);

Use segmentId as the widget key. Don't build your own list from the messages stream. It carries raw, cumulative re-deliveries of each segment.

API reference

VoiceConversation.create

ParameterTypeRequiredDefaultDescription
transportTokenStringYesShort-lived token from POST /v1/sessions.
transportUrlStringYesMedia URL from the same response. Pass it through unchanged.
transportString?NolivekitThe transport field from the session. daily throws unsupportedTransport.
micEnabledboolNotruefalse starts a text-only session with no mic prompt.
audioConstraintsAudioConstraintsNoall trueechoCancellation, noiseSuppression, autoGainControl.
onStatusChangevoid Function(ConversationStatus)?NoStatus transitions, including the ones during create.
onConnectvoid Function(String)?NoFires once the mic is published. Gets the conversation id.

Use them for events inside create, such as connected. Observe everything else on the returned conversation.

Members

MemberTypeDescription
getId()StringConversation id (the LiveKit room name).
isOpen()booltrue while connected.
statusValueListenable<ConversationStatus>connecting, connected, disconnecting, disconnected.
modeValueListenable<ConversationMode>speaking while the agent talks.
transcriptValueListenable<List<ConversationMessage>>Reconciled transcript, one entry per speaker turn. The list is unmodifiable.
messagesStream<ConversationMessage>Raw inbound messages, including cumulative re-deliveries.
errorsStream<Object>Non-fatal errors.
disconnectedFuture<DisconnectionDetails>Completes once when the session ends.
endSession()Future<void>Leaves the room and releases the mic.
setMicMuted(bool)Future<void>Mutes the mic. No-op on a text-only session.
setVolume(double)voidAgent volume, clamped to 0.0 to 1.0.
sendChatMessage(String)Future<void>Typed user turn on the lk.chat topic. The agent answers by voice.
canPlaybackAudiobooltrue while connected. Native apps have no autoplay block.
startAudioPlayback()Future<void>No-op. Kept for parity with the browser SDK.

ConversationMessage

FieldTypeDescription
sourceMessageSourceuser or agent.
textStringText so far. Interim text grows until isFinal.
isFinalbooltrue once the turn's last segment is committed.
segmentIdString?Stable id of the turn's first segment. Use it as the render key.
startedAtint?Milliseconds since epoch when the turn began.

Errors

create throws SpekoClientException. Its code is a SpekoClientErrorCode, and code.wireName matches the browser SDK's string.

CodeWire nameCauseWhat to do
connectionFailedCONNECTION_FAILEDLiveKit rejected the join: expired token, bad URL, or network.Mint a new session and retry.
microphoneFailedMICROPHONE_FAILEDMic capture or publish failed. Also sent to errors if the mic dies mid-call.Ask for the permission, or retry with micEnabled: false.
unsupportedTransportUNSUPPORTED_TRANSPORTThe session asked for daily or an unknown transport.Use an agent that runs on LiveKit.
notConnectedNOT_CONNECTEDsendChatMessage ran before connect or after the call ended.Check isOpen() first.

Unknown data packets from other room participants are ignored. They never reach errors.

Limitations

  • Daily (Pipecat) sessions are not supported. No official Pipecat Flutter client exists, so transport: 'daily' throws unsupportedTransport before any network call.
  • RealtimeVoiceConversation (provider-direct S2S) and CallListener are not yet available on mobile.
  • Flutter web and desktop are not supported targets.
  • onAudioPlaybackBlocked does not exist on mobile.

Troubleshooting

SymptomFix
microphoneFailed on iOS with no promptNSMicrophoneUsageDescription is missing from Info.plist.
microphoneFailed on AndroidRECORD_AUDIO is missing, or the user denied it. Request it before create.
Agent audio plays from the earpieceCall Hardware.instance.setSpeakerphoneOn(true) from livekit_client.
Bluetooth headset is ignored on Android 12+Request the BLUETOOTH_CONNECT runtime permission.
pod install fails on the deployment targetSet platform :ios, '15.0' or higher in the Podfile.
connectionFailed on a retryTokens are single-use. Mint a new session for every call.

Next step

Set up the server side: Mint a session on your backend.

On this page