EchoNova Dart and Flutter SDK
Official Dart and Flutter SDK for the EchoNova API: Text to Speech, Speech to Text and Sound Cleaning, plus website widget tickets and agent sessions.
Status: pre-release. This package is under active development and is not yet published to pub.dev.
- One pure-Dart package for server-side Dart and for Flutter on Android, iOS, desktop and the web.
- Proxy mode for apps: your backend keeps the API key; the app never holds it.
- Typed results, with the API's JSON kept on every result as
raw. - Retries that never charge you twice (idempotency keys on synchronous calls), client-side rate limiting, job polling and safe downloads.
Install
Until the package is on pub.dev, depend on a checkout of this repository:
dependencies:
echonova_ai:
path: ../echonova-sdks/dart # where you cloned the repository
Then dart pub get (or flutter pub get). Once it is published: dart pub add echonova_ai.
Requires Dart 3.5 or later (Flutter 3.24 or later).
Quick start: server-side Dart
import 'package:echonova_ai/echonova_ai.dart';
Future<void> main() async {
final client = EchoNova(); // reads ECHONOVA_API_KEY
try {
final voices = await client.textToSpeech.voices.list(); // changes rarely: cache it
final voice = voices.firstWhere((v) => v.language == 'ar');
final speech =
await client.textToSpeech.generate('أهلاً بك في إيكونوفا', voiceId: voice.id);
print('${speech.durationSeconds} s, ${speech.creditsConsumed} credits, '
'request ${speech.requestId}');
await client.downloadTo(speech.audioUrl!, 'speech.wav');
} finally {
client.close();
}
}
Create one client and reuse it: it keeps the connection pool and the rate-limit state. Close it with client.close() when you are done.
Quick start: Flutter (proxy mode)
Never ship an API key in an app. Anyone can extract it from the app bundle or, on the web, from the page. Instead, run a small proxy on your backend that checks your own user's session, adds the EchoNova key, and forwards the request to https://api.echonova.ai. Reference proxies (FastAPI and Express) are in ../proxy-examples.
Point the app at your proxy, with your app's own credentials:
import 'dart:typed_data';
import 'package:echonova_ai/echonova_ai.dart';
Future<String> sessionToken() async => '...'; // your app's own credentials
final recording = Uint8List(0); // audio your app recorded
final client = EchoNova.proxy(
baseUrl: Uri.parse('https://api.example.com/echonova'),
auth: () async => {'Authorization': 'Bearer ${await sessionToken()}'},
);
final job = await client.speechToText.jobs.create(
AudioFile.fromBytes(recording, 'memo.m4a'),
language: 'ar',
);
final done = await client.speechToText.jobs.wait(job.jobId);
print(done.transcription);
- API paths are appended to
baseUrl: the job above is created withPOST https://api.example.com/echonova/v1/speech-to-text. authis called before every attempt, so it can return a fresh token. On the web you can also use cookies, with anhttpClientthat sends them.- Your proxy should forward the
Idempotency-Keyheader (and allow it in CORS, for Flutter web), as the reference proxies do: it is what makes retried syntheses, transcriptions and cleanings safe. EchoNova(apiKey: ...)throwsUnsupportedEnvironmentExceptionin a browser unless you passdangerouslyAllowBrowser: true.- Paths (
AudioFile.fromPath,downloadTo) need a file system, so they don't work on the web: use bytes there (AudioFile.fromBytes,client.download).
Configuration
| Option | Default | |
|---|---|---|
apiKey |
ECHONOVA_API_KEY |
EchoNova() only. Surrounding whitespace is removed. |
baseUrl |
ECHONOVA_BASE_URL, else https://api.echonova.ai |
Required for EchoNova.proxy. Request paths already start with /v1. |
auth |
none | EchoNova.proxy only: returns your app's headers, before every attempt. |
timeout |
per operation | The time limit for each attempt of every call. |
deadline |
none | The total time for one call: attempts, retry delays and rate-limit waits. |
maxRetries |
2 |
|
rateLimitPreflight |
true |
Wait for the rate-limit window instead of sending a request that would be refused. |
defaultHeaders |
none | Sent with every API request (not with downloads). |
httpClient |
SDK-owned | Your own package:http client (proxies, certificates, cookies). close() leaves it open. |
downloadHttpClient |
SDK-owned | The client for signed download links. It must not add credentials. |
streamKeepalive |
30 s | How long a stream may send nothing before it sends a keepalive ping. null turns keepalive and the connection checks off. |
Every API method also takes options for one call:
import 'package:echonova_ai/echonova_ai.dart';
final client = EchoNova();
const jobId = '...'; // a job ID from jobs.create()
await client.textToSpeech.jobs.get(
jobId,
options: const RequestOptions(timeout: Duration(seconds: 5), maxRetries: 0, headers: {'X-Trace': 'abc'}),
);
final fast = client.withOptions(timeout: const Duration(seconds: 10)); // shares connections and rate limits
textToSpeech.generate, speechToText.transcribe and soundCleaning.clean also take idempotencyKey and waitTimeout (see Errors and retries and Jobs, pages and downloads).
Default time limits per attempt (package:http has one deadline per request, so each is the connect, write and read limits added together):
| Operation | Limit |
|---|---|
Get, list, delete; textToSpeech.jobs.create; widget tickets; agent sessions |
50 s |
| Transcript export | 80 s |
textToSpeech.generate |
260 s (it reads for 240 s, past the API's 202 at 220 s) |
speechToText.jobs.create |
190 s, plus time for the upload's size |
speechToText.transcribe, soundCleaning.clean |
670 s, plus time for the upload's size |
Text to Speech
import 'package:echonova_ai/echonova_ai.dart';
final client = EchoNova();
const text = 'أهلاً بك في إيكونوفا';
const voiceId = '...'; // a voice ID from client.textToSpeech.voices.list()
final speech = await client.textToSpeech.generate(text, voiceId: voiceId, speed: 1.1, numSteps: 64);
final job = await client.textToSpeech.jobs.create(text, voiceId: voiceId);
final done = await client.textToSpeech.jobs.wait(job.jobId); // polls every 3 s, for up to 20 minutes
final wav = await client.textToSpeech.jobs.download(done.id); // gets a fresh link first
await client.textToSpeech.jobs.delete(done.id);
Options you don't pass are not sent, so the API's defaults apply.
A job made on the Text to Speech stream has stream: its sessionId, its synthesisRequestId, and whether it was cancelled early or its audio was dropped.
Speech to Text
Uploads are AudioFiles:
import 'dart:io';
import 'package:echonova_ai/echonova_ai.dart';
final bytes = await File('call.mp3').readAsBytes();
final file = File('recording.ogg');
AudioFile.fromBytes(bytes, 'call.mp3');
AudioFile.fromPath('meeting.wav'); // not on the web; File works via file.path
AudioFile.fromStream(file.openRead(), await file.length(), 'recording.ogg'); // sent once: not retried after it was read
AudioFile.fromBytes(bytes, 'clip', contentType: 'audio/webm');
The SDK names the audio type from the file extension (mp3, wav, flac, ogg, opus, m4a, aac, webm, amr) or, failing that, from the file's first bytes. If it can't tell, it throws UsageException before sending anything. It never sends application/octet-stream, which the API rejects.
import 'package:echonova_ai/echonova_ai.dart';
final client = EchoNova();
final result = await client.speechToText.transcribe(
AudioFile.fromPath('call.mp3'),
language: 'ar',
identifySpeakers: true,
terminology: const Terminology([
Keyword('KYC'),
Keyword('Emirates NBD', variants: ['امريتس ان بي دي']),
]),
);
print(result.transcription);
print(result.terminology?.corrected);
for (final segment in result.segments ?? const <SttSegment>[]) {
print('${segment.start} ${segment.speaker}: ${segment.text}');
}
final job = await client.speechToText.jobs.create(AudioFile.fromPath('meeting.wav'), language: 'en');
final done = await client.speechToText.jobs.wait(job.jobId); // polls every 5 s
final srt = await client.speechToText.jobs.export(done.id, format: ExportFormat.srt); // String
final data = await client.speechToText.jobs.exportJson(done.id); // TranscriptExport
language is optional on transcribe, jobs.create, connect and transcribeStream: auto (what the API uses when you leave it out) detects Arabic or English, ar is for Arabic and mixed Arabic/English, en only for wholly English speech. Results report the language as the API returns it, which can be auto.
TerminologyResult.rawText holds the API's raw field, because raw is the JSON on every result. A job saved from the Speech to Text stream has stream.sessionId and audioUrl, a signed link to the recording.
Sound Cleaning
import 'package:echonova_ai/echonova_ai.dart';
final client = EchoNova();
final job = await client.soundCleaning.clean(
AudioFile.fromPath('noisy.wav'),
targetLufs: -16,
sampleRate: 48000,
bitDepth: 24,
);
print('${job.metrics?.integratedLufs} LUFS, ${job.creditsConsumed} credits');
final cleaned = await client.download(job.outputUrl!);
await client.soundCleaning.jobs.delete(job.id);
Widgets and agent sessions
Call these from your server.
import 'package:echonova_ai/echonova_ai.dart';
void sendToYourClient(String? wsUrl, String token) {} // your app's own channel
final client = EchoNova();
const agentId = '...'; // your agent's ID
final ticket = await client.widgets.createTicket(
'wdg_a1B2c3D4e5F6g7H8i9J0',
user: const WidgetUser(id: 'user_8431', name: 'Sara'),
ttlSeconds: 300,
); // hand ticket.ticket to that visitor's browser
final session = await client.agents.sessions.start(agentId, channel: AgentChannel.voice);
sendToYourClient(session.wsUrl, session.token); // only the client that joins the room
final status = (await client.agents.sessions.get(agentId, session.id)).status;
await client.agents.sessions.end(agentId, session.id);
The room token is a secret, returned only by start(). Hand it only to the client that joins the room, and don't log or store it. It is left out of toString(), and a response that carries it is never copied into an exception. start() is never sent twice once it may have reached the server, because a retried start opens a second session: a lost response throws with mayHaveExecuted == true. An agent at its call or chat limit throws ConcurrencyLimitException.
Jobs, pages and downloads
jobs.list(offset:, limit:)returns aPagewithitems,total,hasNextPageandnextPage().jobs.listAll(limit:)is aStreamof every job. It fetches pages as you read and skips jobs it already returned (a new job shifts later pages by one).jobs.wait(jobId, pollInterval:, timeout:, raiseOnFailure:)throwsJobFailedExceptionfor a failed job andJobWaitTimeoutExceptionwhen it gives up; calling it again is safe. Unknown statuses count as not finished. Allwaitcalls on one client share a budget of 80 polls a minute per endpoint.- When
textToSpeech.generate,speechToText.transcribeorsoundCleaning.cleanis still processing after 220 s, the API answers202and the SDK waits for the job the same way (every 3 s for Text to Speech, 5 s otherwise, within the same polling budget), then returns the usual result. A failed job throwsJobFailedException.RequestOptions(waitTimeout:)bounds the wait (default 20 minutes, and never past the call'sdeadline); past it,JobWaitTimeoutExceptionhas thejobId, and the job keeps running. - Download links are signed and expire.
client.download(url)returns the bytes andclient.downloadTo(url, path)writes a file (not on the web). Neither sends your API key or proxy credentials. An expired link throwsDownloadExpiredException.jobs.download(jobId)gets the job again for a fresh link.
Errors and retries
Every error the SDK throws is an EchoNovaException, a sealed class, so a switch over it is exhaustive. An error thrown by your own auth or streamQuery hook reaches you unchanged, as in the Python and TypeScript SDKs, so you can tell it from an API error:
import 'package:echonova_ai/echonova_ai.dart';
final client = EchoNova();
const text = 'أهلاً بك في إيكونوفا';
const voiceId = '...'; // a voice ID from client.textToSpeech.voices.list()
try {
await client.textToSpeech.generate(text, voiceId: voiceId);
} on InvalidRequestException catch (e) {
print('${e.errorMessage} (request ${e.requestId})');
} on SpendingLimitException {
// The key reached its Credit Limit: never retried.
} on RateLimitException catch (e) {
print('Still limited after the automatic retries; retry in ${e.retryAfter}');
} on RequestInProgressException catch (e) {
// The first request with this key is still running: send it again later.
print('Still running; send it again with idempotencyKey ${e.idempotencyKey}');
} on APIConnectionException catch (e) {
// Still no response after the retries. The same key returns the first
// result, without a second charge.
await client.textToSpeech.generate(text, voiceId: voiceId, options: RequestOptions(idempotencyKey: e.idempotencyKey));
} on APIStatusException catch (e) {
print('${e.statusCode} ${e.errorMessage} ${e.requestId}');
}
try {
await client.textToSpeech.jobs.create(text, voiceId: voiceId);
} on APIConnectionException catch (e) {
if (e.mayHaveExecuted ?? true) {
// Sent, but the response was lost: it may have run and been charged.
final candidates = await client.textToSpeech.jobs.findCandidates(e.sentAt!, text: text);
}
}
The SDK retries connection failures, rate limits and temporary outages, with backoff.
textToSpeech.generate, speechToText.transcribe and soundCleaning.clean send an Idempotency-Key: a new UUID for each call, the same on each of its retries. A repeat with the same key within 24 hours returns the first result and is not charged again, so these calls are also retried after a lost response and after a 500, 502, 503 or 504. Pass your own key with RequestOptions(idempotencyKey: ...) to retry safely across processes or restarts; a new request needs a new key. Errors from these calls carry the key as idempotencyKey. A key already used for a different request throws InvalidRequestException. While the first request with a key is still running, the API answers 409: the SDK sends the request again with the key every 5 s (or after a longer Retry-After), within the same waitTimeout as a 202, and throws RequestInProgressException only when it is still running after that, or at once when the upload is a stream it can't send again (retryDisabledReason is then body_not_replayable).
Any other request that may already have run, such as creating a job or starting an agent session, is never resent, because a second attempt could be charged again. Such errors have mayHaveExecuted == true and sentAt; findCandidates() lists the jobs created since then (skipping jobs made on a stream) so you can decide. It never picks one for you.
After a 429 with Retry-After, the client holds further calls to that endpoint until the wait is over, instead of sending more. A wait longer than 60 s, or past the call's deadline, throws RateLimitException without sending.
Response metadata
Every method has a …WithResponse twin that returns a RawResponse:
import 'package:echonova_ai/echonova_ai.dart';
final client = EchoNova();
const jobId = '...'; // a job ID from jobs.create()
final raw = await client.textToSpeech.jobs.getWithResponse(jobId);
print('${raw.statusCode} ${raw.requestId} ${raw.rateLimit} ${raw.headers}');
final job = raw.parse();
client.rateLimits; // the last rate-limit headers seen, per operation
Every result has requestId and raw (the API's JSON, including fields this version doesn't model yet).
Streaming
Keep one Text to Speech socket open and send a synthesis per sentence or reply. Audio arrives as PCM16LE mono chunks at synthesis.sampleRate, well before the whole text is spoken. speakStream() yields only chunks; their rate is tts.sampleRate, the rate of the latest synthesis to start.
import 'dart:typed_data';
import 'package:echonova_ai/echonova_ai.dart';
// Your app's audio output, voice activity detection and LLM text:
void play(Uint8List pcm) {}
bool userStartedTalking() => false;
final llmTextDeltas = Stream<String>.empty();
final client = EchoNova();
const voiceId = '...'; // a voice ID from client.textToSpeech.voices.list()
final tts = await client.textToSpeech.connect(voiceId: voiceId);
final synthesis = tts.synthesize('أهلاً بك، كيف يمكنني مساعدتك؟');
await for (final pcm in synthesis.audio) {
play(pcm);
if (userStartedTalking()) break; // cancelling the subscription cancels the synthesis
}
final result = await synthesis.result; // outcome, creditsConsumed, charged
await for (final pcm in tts.speakStream(llmTextDeltas)) {
play(pcm); // a voice agent: LLM text in, audio out, sentence by sentence, at tts.sampleRate
}
await tts.close();
final audio = await client.textToSpeech.speak('مرحبا', voiceId: voiceId); // one-shot; audio.toWav()
A synthesis is charged per character when it starts. One stopped after its audio started (a cancel, a barge-in or a service failure) costs only the share of audio sent, at least 1 credit; result.creditsConsumed reports the final cost. The SDK never resends a synthesis that was sent but not started, because it may already have been charged.
Speech to Text takes live PCM16LE mono audio and sends transcripts as each segment is cut (every 15 s of audio, or at endSegment()):
import 'dart:io';
import 'package:echonova_ai/echonova_ai.dart';
final microphone = Stream<List<int>>.empty(); // your audio: PCM16LE mono at 16 kHz
final chunks = File('meeting.pcm').openRead(); // the same format, from a file
final client = EchoNova();
final stt = await client.speechToText.connect(sampleRate: 16000, language: 'ar');
final feeding = stt.feedFrom(microphone); // sends the audio, then stop()
await for (final event in stt.events) {
switch (event) {
case Transcript(:final text):
print(text);
case SessionSaved(:final jobId):
print('saved as job $jobId');
default:
}
}
final summary = await feeding; // reason, totalSeconds, creditsConsumed, jobId, savedStatus
// Long or file-backed audio: rolls over to a new session before the session limit
await for (final event in client.speechToText.transcribeStream(chunks, sampleRate: 16000, language: 'en')) {
if (event is Transcript) print(event.text);
}
Sessions never reconnect on their own; transcribeStream does, replaying only audio that was never cut into a segment. Each session is saved as a Speech to Text job.
Flutter web: browsers can't send headers on a WebSocket, so streams there only work through your proxy, authenticated with cookies or EchoNova.proxy(streamQuery: () async => {'access_token': await streamToken()}). There auth isn't called for streams, since its headers couldn't be sent. On Android, iOS and desktop, the proxy's auth headers are sent as usual.
Webhooks
import 'dart:io';
import 'package:echonova_ai/echonova_ai.dart';
/// Call it with the request's body and headers, from any server framework.
void onWebhook(List<int> rawBody, Map<String, String> headers) {
final secret = Platform.environment['ECHONOVA_WEBHOOK_SECRET']!;
final event = verifyWebhook(rawBody, headers, [secret]);
switch (event) {
case JobCompleted(:final jobId, :final service):
print('$service job $jobId finished');
case JobFailed(:final jobId, :final error):
print('job $jobId failed: $error');
case SpendingWarning() || SpendingExhausted() || UnknownWebhookEvent():
break;
}
}
Pass the body bytes exactly as received.
Example
example/echonova_example.dart runs Text to Speech and Speech to Text against the API. It reads ECHONOVA_API_KEY.
Development
cd dart
dart pub get
dart test # unit and conformance tests (no network, no API key)
dart analyze --fatal-infos
dart format --output=none --set-exit-if-changed .
Tests read the shared contract in ../spec: the vendored API specs, the error rules, the parameter mapping and the test vectors every EchoNova SDK must pass.
License
MIT. See LICENSE.
Libraries
- echonova_ai
- Official Dart and Flutter SDK for the EchoNova speech API: Text to Speech, Speech to Text and Sound Cleaning, plus website widget tickets and agent sessions.