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_client0.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
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
transportToken | String | Yes | Short-lived token from POST /v1/sessions. | |
transportUrl | String | Yes | Media URL from the same response. Pass it through unchanged. | |
transport | String? | No | livekit | The transport field from the session. daily throws unsupportedTransport. |
micEnabled | bool | No | true | false starts a text-only session with no mic prompt. |
audioConstraints | AudioConstraints | No | all true | echoCancellation, noiseSuppression, autoGainControl. |
onStatusChange | void Function(ConversationStatus)? | No | Status transitions, including the ones during create. | |
onConnect | void Function(String)? | No | Fires 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
| Member | Type | Description |
|---|---|---|
getId() | String | Conversation id (the LiveKit room name). |
isOpen() | bool | true while connected. |
status | ValueListenable<ConversationStatus> | connecting, connected, disconnecting, disconnected. |
mode | ValueListenable<ConversationMode> | speaking while the agent talks. |
transcript | ValueListenable<List<ConversationMessage>> | Reconciled transcript, one entry per speaker turn. The list is unmodifiable. |
messages | Stream<ConversationMessage> | Raw inbound messages, including cumulative re-deliveries. |
errors | Stream<Object> | Non-fatal errors. |
disconnected | Future<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) | void | Agent 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. |
canPlaybackAudio | bool | true while connected. Native apps have no autoplay block. |
startAudioPlayback() | Future<void> | No-op. Kept for parity with the browser SDK. |
ConversationMessage
| Field | Type | Description |
|---|---|---|
source | MessageSource | user or agent. |
text | String | Text so far. Interim text grows until isFinal. |
isFinal | bool | true once the turn's last segment is committed. |
segmentId | String? | Stable id of the turn's first segment. Use it as the render key. |
startedAt | int? | 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.
| Code | Wire name | Cause | What to do |
|---|---|---|---|
connectionFailed | CONNECTION_FAILED | LiveKit rejected the join: expired token, bad URL, or network. | Mint a new session and retry. |
microphoneFailed | MICROPHONE_FAILED | Mic capture or publish failed. Also sent to errors if the mic dies mid-call. | Ask for the permission, or retry with micEnabled: false. |
unsupportedTransport | UNSUPPORTED_TRANSPORT | The session asked for daily or an unknown transport. | Use an agent that runs on LiveKit. |
notConnected | NOT_CONNECTED | sendChatMessage 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'throwsunsupportedTransportbefore any network call. RealtimeVoiceConversation(provider-direct S2S) andCallListenerare not yet available on mobile.- Flutter web and desktop are not supported targets.
onAudioPlaybackBlockeddoes not exist on mobile.
Troubleshooting
| Symptom | Fix |
|---|---|
microphoneFailed on iOS with no prompt | NSMicrophoneUsageDescription is missing from Info.plist. |
microphoneFailed on Android | RECORD_AUDIO is missing, or the user denied it. Request it before create. |
| Agent audio plays from the earpiece | Call 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 target | Set platform :ios, '15.0' or higher in the Podfile. |
connectionFailed on a retry | Tokens are single-use. Mint a new session for every call. |
Next step
Set up the server side: Mint a session on your backend.