flutter_deepgram library

A complete, production-grade Deepgram SDK for Dart and Flutter.

What's included

  • Speech-to-Text — pre-recorded (REST), live streaming (WebSocket), and turn-based Flux (WebSocket) transcription, with the full option surface of every API.
  • Text-to-Speech — Aura, Aura-2, and Flux voices over REST and WebSocket, including turn-based Flux TTS with barge-in interrupts.
  • Voice Agent API — a single WebSocket that runs listening, thinking (any major LLM), and speaking, with function calling and conversation context.
  • Text Intelligence — sentiment, topics, summarization, and intents for plain text.
  • Resilience — every streaming session runs on a self-healing WebSocket with generation-token reconnection, failure classification, exponential backoff with jitter, keepalive heartbeats, and (for live transcription) disconnect gap recovery through the pre-recorded API.

Quick start

final deepgram = DeepgramClient(apiKey: 'YOUR_DEEPGRAM_API_KEY');

final result = await deepgram.prerecorded.transcribeFromUrl(
  'https://example.com/podcast.mp3',
  options: const PrerecordedOptions(
    smartFormat: true,
    diarize: true,
    summarize: SummarizeOptions(mode: SummarizeMode.paragraphs),
  ),
);
print(result.channels.first.alternatives.first.transcript);

Classes

AgentAgentAudioDone
An AgentAudioDone frame — the agent finished speaking.
AgentAgentSettings
The agent block of VoiceAgentSettings: providers, conversation context, greeting, and the deprecated top-level language.
AgentAgentStartedSpeaking
An AgentStartedSpeaking frame — the agent begins a spoken reply.
AgentAgentThinking
An AgentThinking frame — the agent's visible thought process.
AgentAudioInput
audio.input — encoding and sample rate of the media the client streams to the agent.
AgentAudioOutput
audio.output — the format the agent's text-to-speech audio is delivered in.
AgentAudioSettings
The audio block of VoiceAgentSettings.
AgentBedrockCredentials
AWS Bedrock credentials (STS short-lived or IAM long-lived).
AgentCancelledFunction
One cancelled function inside a AgentFunctionCallCancelled.
AgentConfiguration
A reusable agent configuration.
AgentConfigurationsClient
REST client for managing reusable Voice Agent configurations.
AgentContext
Conversation history injected at session start (agent.context).
AgentConversationText
A ConversationText frame: a transcribed or generated statement.
AgentCustomThinkPayload
A __customFromThinkProvider frame — the think provider's response body passed through unchanged.
AgentErrorEvent
An Error frame — the server reports a failure.
AgentFunctionCallCancelled
A FunctionCallCancelled frame — pending calls are no longer valid.
AgentFunctionCallRecord
A single function-call record used inside AgentHistoryMessage entries.
AgentFunctionCallRequest
A FunctionCallRequest frame — the server asks your application (or a client-side function) to execute and reply.
AgentFunctionDefinition
A function definition: client-side (executed by your application) or server-side (executed by Deepgram against an HTTP endpoint).
AgentHistoryEvent
A History frame echoing a conversation entry (a role/content message or a function-call record list).
AgentHistoryMessage
One history entry: either a role/content message or a function-call record list, both tagged {'type': 'History', ...} on the wire.
AgentInjectionRefused
An InjectionRefused frame — an injected message was rejected.
AgentLatencyReport
A LatencyReport frame with per-stage timings, in seconds.
AgentListen
agent.listen — Deepgram speech-to-text configuration.
AgentListenProvider
The Deepgram listen (speech-to-text) provider.
AgentProviderUpdate
A provider/settings update confirmation: ListenUpdated, ThinkUpdated, SpeakUpdated, PromptUpdated, or SettingsApplied.
AgentRequestedFunction
One requested function inside a AgentFunctionCallRequest.
AgentSettingsApplied
The SettingsApplied frame confirming the server accepted the Settings.
AgentSettingsFlags
Feature flags carried by the Settings message.
AgentSpeak
agent.speak — Deepgram text-to-speech configuration.
AgentSpeakProvider
The Deepgram speak (text-to-speech) provider.
AgentThink
agent.think — LLM provider, system prompt, and function definitions.
AgentThinkModel
A think-provider model available to Voice Agents.
AgentThinkProvider
An LLM (think) provider configuration.
AgentUserStartedSpeaking
The UserStartedSpeaking frame — the user began talking (barge-in).
AgentVariable
A template variable usable inside agent configurations.
AgentWarningEvent
A Warning frame — the server reports a non-fatal issue.
AgentWelcome
The Welcome frame sent by the server right after the connection opens.
BackoffPolicy
Computes reconnect delays.
ConnectivityProbe
Probes general internet reachability.
CustomIntentMode
Allowed values for the custom_intent_mode parameter.
CustomTopicMode
Allowed values for the custom_topic_mode parameter.
DeepgramAuth
Holds credentials and produces Authorization header values.
DeepgramClient
Provides access to every Deepgram API surface.
DeepgramConfig
Immutable configuration object shared by every sub-client.
DeepgramLiveClient
A live transcription session over wss://api.deepgram.com/v1/listen.
DeepgramLogger
Pluggable logger for the Deepgram SDK.
DeepgramRedactions
Redaction policies accepted by the redact parameter.
DeepgramSttModels
Well-known Deepgram speech-to-text model identifiers accepted by the model parameter.
DeepgramVoiceAgent
A Voice Agent session over a resilient WebSocket.
DeepgramVoices
Static voice-ID catalogs for Deepgram text-to-speech.
FluxAppliedConfig
The synthesis configuration in effect after a successful Configure.
FluxConfigure
A Configure message for the Flux session: mid-stream updates of turn thresholds, keyterms, language hints, and numeral formatting.
FluxConfigureFailure
A ConfigureFailure message: a Configure message was rejected.
FluxConfigureSuccess
A ConfigureSuccess message: a Configure message was applied.
FluxConnected
A Connected message: the session was established.
FluxControlsApplied
Counts of the inline controls the server acted on during a turn.
FluxFatalError
An Error message: a fatal error. The server closes the session right after sending it.
FluxFlushed
A Flushed message: an echo confirming receipt of a manual flush.
FluxSessionMetadata
A SessionMetadata message: cumulative session totals, delivered before the socket closes.
FluxSpeakConfigureFailure
A ConfigureFailure message: rejection of a configuration change.
FluxSpeakConfigureSuccess
A ConfigureSuccess message: acknowledgment of a configuration change.
FluxSpeakConnected
The Connected handshake of a /v2/speak session.
FluxSpeakError
An Error message: a fatal error, followed by a WebSocket close.
FluxSpeechInterrupted
A SpeechInterrupted message: what the user heard when barging in.
FluxSpeechMetadata
Per-turn billing and timing for a SpeechMetadata message.
FluxSpeechStarted
A SpeechStarted message: the start of a new turn.
FluxSttClient
A Flux speech-to-text session over wss://api.deepgram.com/v2/listen.
FluxSttOptions
Query parameters for a /v2/listen Flux transcription session.
FluxTtsClient
A turn-based Flux TTS session over WSS /v2/speak.
FluxTtsOptions
Options for WSS /v2/speak (Flux TTS streaming) and POST /v2/speak (Flux TTS batch) — model strings follow the format flux-{voice}-{language}, e.g. flux-alexis-en.
FluxTurnInfo
A TurnInfo message: the current state of the turn being transcribed.
FluxWarning
A Warning message: a non-fatal condition; the connection stays open.
FluxWord
A TurnInfo word.
HttpCancelToken
A cancellation token, inspired by Dio's CancelToken. Cancels the single request (or stream download) it is passed to.
HttpEngine
The resilient REST engine used by every sub-client.
JsonApiResult
The result of a JSON REST call: the decoded body plus selected headers.
LiveErrorMessage
An Error message: a non-fatal server-side rejection.
LiveGapRecoveryOptions
Gap-recovery behaviour for a live transcription session.
LiveMetadataMessage
The Metadata message: a summary flushed by the server after CloseStream, once all final results have been delivered.
LiveSpeechStarted
A SpeechStarted message: speech was detected after a silence (requires vad_events).
LiveTranscriptionOptions
Query parameters for a /v1/listen live transcription session.
LiveTranscriptionResult
A Results message: an interim or final transcription for one channel.
LiveUtteranceEnd
An UtteranceEnd message: the microphone went silent long enough to end an utterance (requires utterance_end_ms).
PrerecordedClient
Transcribes audio that has already been recorded.
PrerecordedOptions
Options for POST /v1/listen.
PrerecordedTranscriptionResult
The complete response of POST /v1/listen (pre-recorded transcription).
ResilientWebSocket
A resilient, auto-reconnecting WebSocket session.
ResilientWebSocketOptions
Tuning knobs for a ResilientWebSocket.
SpeakOptions
Options for POST /v1/speak and WSS /v1/speak — Aura and Aura-2 voices.
SttAlternative
One transcription hypothesis for an audio channel.
SttChannel
Transcription results for a single audio channel.
SttDiarizeInfo
Information about the diarizer that produced speaker labels, present only when diarization ran.
SttEntity
An entity (a labeled value such as a person, place, or number) extracted from the transcript.
SttHit
A single match produced by the search or replace features.
SttIntent
An intent detected over a span of the transcript.
SttMetadata
Response metadata shared by all transcription results.
SttModelInfo
Identifying information about a Deepgram model that produced a result.
SttParagraph
A paragraph of transcription, produced when paragraphs=true is requested.
SttSentence
A single sentence within a paragraph.
SttSentiment
A sentiment segment: positive, neutral, or negative.
SttSummary
A summary covering a span of the transcript.
SttTopic
A topic detected over a span of the transcript.
SttTranslation
A transcript translated into a single target language.
SttUtterance
A semantic unit of speech, produced when utterances=true is requested.
SttWord
A single transcribed word with timing, confidence, and optional speaker and language information.
StubWsFactory
A WsFactory that always fails — replaced at compile time by the conditional export.
SummarizeOptions
Options for Deepgram's summarization feature (summarize).
TextIntelligenceClient
REST client for the Deepgram Text Intelligence API (/v1/read).
TextIntelligenceMetadata
Metadata accompanying a text intelligence response.
TextIntelligenceOptions
Options for POST /v1/read text analysis.
TextIntelligenceResult
The result of a POST /v1/read text analysis.
TextIntent
One detected intent within a segment of the analyzed text.
TextModelUsageInfo
Per-feature model usage accounting from text intelligence metadata.
TextSentiment
One sentiment segment of the analyzed text.
TextSummary
One generated summary of the analyzed text.
TextTopic
One detected topic within a segment of the analyzed text.
TtsClient
Synthesizes speech from text over the Deepgram REST API.
TtsMetadataMessage
Metadata about an audio generation on /v1/speak.
TtsStreamClient
A continuous text-to-speech session over WSS /v1/speak.
TtsWarning
A non-fatal warning from a TTS WebSocket API.
VoiceAgentSettings
The complete Settings message, sent to the agent right after the server's Welcome frame.
WsCloseContext
Context handed to ResilientWebSocketOptions.shouldReconnect after an unexpected disconnect or failed connect.
WsFactory
Creates platform-appropriate WebSocket connections.
WsFailureClassifier
Classifies raw WebSocket connect errors.
WsMessage
A single inbound WebSocket frame.
WsReconnectContext
Context describing a scheduled reconnection.
WsSocket
A connected WebSocket wrapper used by WsFactory.

Enums

AgentAudioEncoding
Audio encodings accepted for the agent's inbound (speech-to-text) media.
AgentAudioOutputContainer
Container formats for the agent's outbound (text-to-speech) media.
AgentAudioOutputEncoding
Audio encodings accepted for the agent's outbound (text-to-speech) media.
DeepgramRegion
Deepgram processing regions.
LiveEncoding
Audio encodings accepted by Deepgram's streaming endpoints.
SummarizeAudioType
The kind of audio being summarized (summarize_audio_type).
SummarizeMode
The style of summary produced by Deepgram's summarizer (summarize_mode).
TtsCallbackMethod
HTTP method by which a text-to-speech callback request is delivered.
TtsContainer
Container (file wrapper) for batch text-to-speech output.
TtsEncoding
Audio encodings accepted by the Deepgram TTS APIs.
WsConnectionState
Lifecycle states of a ResilientWebSocket.
WsFailureClassification
Classification of a failed WebSocket connection attempt.

Extensions

SummarizeAudioTypeWire on SummarizeAudioType
Wire-string mapping for SummarizeAudioType.
SummarizeModeWire on SummarizeMode
Wire-string mapping for SummarizeMode.

Properties

defaultWsFactory → WsFactory
The factory instance exported on unsupported platforms.
final

Typedefs

DeepgramLogListener = void Function(String level, String message, Object? error)
Signature for a log listener.
DeepgramTokenProvider = Future<String> Function()
Signature of a callback that supplies a fresh JWT when needed.

Exceptions / Errors

DeepgramAuthException
The API key or token was missing, malformed, expired, or unauthorized.
DeepgramBadRequestException
The request was syntactically invalid (HTTP 400 / validation error).
DeepgramException
Base class for all errors thrown by the flutter_deepgram SDK.
DeepgramNetworkException
The transport layer failed before Deepgram could answer (DNS, TCP, TLS).
DeepgramNotFoundException
The referenced resource does not exist (HTTP 404).
DeepgramQuotaException
The account is out of credit / quota for this operation.
DeepgramRateLimitException
Deepgram is throttling the client (HTTP 429).
DeepgramServerException
Deepgram failed to process the request (HTTP 5xx).
DeepgramStateException
Raised when an operation is attempted on a session that is already closed or disposed.
DeepgramTimeoutException
A request or connection attempt exceeded its configured timeout.
DeepgramWebSocketException
A WebSocket-level failure: refused upgrade, abnormal close, or protocol error.