deepgram-rust-text-to-speech
在 Rust SDK 中实现 Deepgram 文本转语音时使用,包括 Aura 模型选择、语音功能标志、输出文件或字节流处理,以及…
npx skills add https://github.com/deepgram/deepgram-rust-sdk --skill deepgram-rust-text-to-speechUsing Deepgram Text-to-Speech (Rust SDK)
Use this skill when generating audio from text with the Rust SDK's Speak surface.
When to use this product
- Converting text into audio files with
speak_to_file(...). - Streaming TTS bytes with
speak_to_stream(...). - Capturing the
dg-request-idDeepgram support asks for (plus model name/uuid, character count, content type) withspeak_to_file_with_metadata(...)/speak_to_stream_with_metadata(...), which return aSpeakMetadataalongside the audio. Every field is optional, so read it throughmetadata.request_id(). - Selecting Aura voices and output encodings with
speak::options::Options. - Streaming text in and audio out over the Aura WebSocket with
speak_stream().handle()— the shape to use when the text comes from an LLM and the audio goes to a player. - Synthesizing with Flux TTS (
/v2/speak) in batch withflux_speak_to_file(...)orflux_speak_to_stream(...), or turn by turn over the WebSocket withflux_request(options).handle().
Authentication
For a TTS-only install:
[dependencies]
deepgram = { version = "0.12", default-features = false, features = ["speak"] }
tokio = { version = "1", features = ["full"] }
futures = "0.3"
# Only add `bytes = "1"` if you need to name `bytes::Bytes` in your own signatures.
# The code below relies on type inference and does not import bytes directly.
let dg = deepgram::Deepgram::new(std::env::var("DEEPGRAM_API_KEY")?)?;
- API keys use
Authorization: Token <api_key>. - Aura text-to-speech (
/v1/speak) has both transports: REST (Speak::speak_to_file/speak_to_stream, a saved file or a stream of bytes) and the WebSocket (Speak::speak_stream().handle(), returning aSpeakStreamHandle:speak,flush,clear,close,receive, plussplit/senderfor sending and receiving from different tasks). Flux TTS (/v2/speak) likewise has both, in thespeak::fluxmodule:Speak::flux_speak_to_file/flux_speak_to_streamfor batch andSpeak::flux_request(options).handle()for the streaming WebSocket (FluxSpeakHandle:speak,flush,interrupt,configure_speed,close,receive).
Quick start
Quick start: save audio to a file
use std::{path::Path, time::Instant};
use deepgram::{
speak::options::{Container, Encoding, Model, Options},
Deepgram,
};
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let api_key = std::env::var("DEEPGRAM_API_KEY")?;
let dg = Deepgram::new(&api_key)?;
let options = Options::builder()
.model(Model::AuraAsteriaEn)
.encoding(Encoding::Linear16)
.sample_rate(16000)
.container(Container::Wav)
.build();
let start = Instant::now();
dg.text_to_speech()
.speak_to_file("Hello from Rust.", &options, Path::new("output.wav"))
.await?;
println!("Time to download audio: {:.2?}", start.elapsed());
Ok(())
}
Quick start: stream response bytes
use deepgram::{
speak::options::{Container, Encoding, Model, Options},
Deepgram,
};
use futures::stream::StreamExt;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let api_key = std::env::var("DEEPGRAM_API_KEY")?;
let dg = Deepgram::new(&api_key)?;
let options = Options::builder()
.model(Model::AuraAsteriaEn)
.encoding(Encoding::Linear16)
.sample_rate(16000)
.container(Container::Wav)
.build();
let mut stream = dg
.text_to_speech()
.speak_to_stream("Hello from Rust.", &options)
.await?;
while let Some(chunk) = stream.next().await {
println!("received {} bytes", chunk.len());
}
Ok(())
}
Quick start: Aura streaming (WebSocket)
use deepgram::{
speak::{
options::{Encoding, Model},
SpeakResponse,
},
Deepgram,
};
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let api_key = std::env::var("DEEPGRAM_API_KEY")?;
let dg = Deepgram::new(&api_key)?;
// The streaming endpoint emits raw audio only: linear16, mulaw, or alaw.
let handle = dg
.text_to_speech()
.speak_stream()
.model(Model::Aura2ThaliaEn)
.encoding(Encoding::Linear16)
.sample_rate(24_000)
.handle()
.await?;
// Split so text can be sent while audio is still arriving.
let (sender, mut events) = handle.split();
let producer = tokio::spawn(async move {
for piece in ["Hello, ", "this is streaming text to speech."] {
sender.speak(piece).await?;
}
sender.flush().await?;
sender.close().await
});
while let Some(message) = events.receive().await {
match message? {
SpeakResponse::Audio(_chunk) => { /* play or buffer the audio */ }
SpeakResponse::Flushed { .. } => { /* the flushed segment is complete */ }
SpeakResponse::Warning { description, .. } => {
eprintln!("warning: {description:?}");
}
_ => {}
}
}
producer.await.expect("producer task panicked")?;
Ok(())
}
clear() discards text the server has not synthesized yet — use it on barge-in. See examples/speak/websocket/text_to_speech_websocket.rs for the full loop, including writing the audio to a file.
Quick start: Flux TTS batch (REST)
use std::path::Path;
use deepgram::{
speak::flux::options::{Model, Options},
Deepgram,
};
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let api_key = std::env::var("DEEPGRAM_API_KEY")?;
let dg = Deepgram::new(&api_key)?;
// model is required; encoding defaults to mp3 on the batch transport.
let options = Options::builder(Model::FluxHaleyEn).build();
dg.text_to_speech()
.flux_speak_to_file("Your appointment is confirmed.", &options, Path::new("flux-tts-batch.mp3"))
.await?;
Ok(())
}
Quick start: Flux TTS streaming (WebSocket)
use deepgram::{
speak::flux::{
options::{Encoding, Model, Options},
response::FluxSpeakResponse,
},
Deepgram,
};
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let api_key = std::env::var("DEEPGRAM_API_KEY")?;
let dg = Deepgram::new(&api_key)?;
let options = Options::builder(Model::FluxHaleyEn)
.encoding(Encoding::Linear16)
.sample_rate(24_000)
.build();
// Connect to the /v2/speak WebSocket and get the handle.
let speak = dg.text_to_speech();
let mut handle = speak.flux_request(options).handle().await?;
// Stream the turn's text in, end the turn with flush, then close.
handle.speak("Hello! ").await?;
handle.speak("This audio was synthesized over the Flux TTS websocket.").await?;
handle.flush().await?;
handle.close().await?;
// Binary audio frames and JSON control events arrive on receive().
let mut saw_session_metadata = false;
while let Some(response) = handle.receive().await {
match response? {
FluxSpeakResponse::Audio(_bytes) => { /* play or buffer the audio */ }
FluxSpeakResponse::SpeechMetadata(_) => { /* end-of-turn signal */ }
FluxSpeakResponse::FatalError { code, description, .. } => {
return Err(format!("fatal Flux TTS error {code}: {description}").into());
}
FluxSpeakResponse::SessionMetadata { .. } => {
saw_session_metadata = true;
break;
}
_ => {}
}
}
if !saw_session_metadata {
return Err("session ended before its terminal SessionMetadata event".into());
}
Ok(())
}
handle.interrupt(playback_offset_ms) cancels the active turn on barge-in and the server answers with SpeechInterrupted; handle.configure_speed(speed) changes the speaking rate mid-session and the server answers with ConfigureSuccess or ConfigureFailure. See examples/speak/flux/websocket_synthesize.rs for the full event loop, including saving the audio as a WAV file.
Key parameters
- Entrypoints:
Deepgram::text_to_speech(),Speak::speak_to_file(...),Speak::speak_to_stream(...),Speak::speak_stream(). - TTS
Optionsbuilder fields:model,encoding,sample_rate,container,bit_rate. - Model enum lives in
deepgram::speak::options::Modeland names the Aura-1 and Aura-2 voices the API served as of this release —AuraAsteriaEn,AuraLunaEn,AuraOrionEn,Aura2ThaliaEn,Aura2AgustinaEs,Aura2UzumeJa, … — plusCustomId(String)for anything newer.Model::from("aura-2-thalia-en")resolves a wire string to its named variant; aCustomIdbuilt by hand is not==to the named variant it spells, so normalize throughModel::frombefore comparing. - Streaming (
speak_stream()) builder methods:model,encoding,sample_rate,speed,mip_opt_out, and aquery_paramsescape hatch.handle()validates locally first: the streaming endpoint accepts onlylinear16/mulaw/alaw, asample_rateof 8000 / 16000 / 24000 / 32000 / 48000, andspeedin0.7..=1.5; anything else isDeepgramError::InvalidOptionsbefore a socket is opened. There is nocontainerorbit_rate— the stream is raw audio. SpeakStreamHandle(andSpeakStreamEvents) implementsfutures::Stream<Item = Result<SpeakResponse>>;SpeakResponseisAudio/Metadata/Flushed/Cleared/Warning/Unknown. Sending text never blocks on undrained audio, and sends after the session ends return an error instead of being dropped.speak_to_stream(...)returnsimpl Stream<Item = bytes::Bytes>.- Flux TTS entrypoints:
Speak::flux_speak_to_file(text, &options, path),Speak::flux_speak_to_stream(text, &options),Speak::flux_request(options).handle()returningFluxSpeakHandle. - Flux TTS
Options::builder(Model)methods:encoding,sample_rate,speed,expressivity,mip_opt_out,tag, and the REST-onlycontainer,bit_rate,callback,callback_method,priority_low.priority_low()serializes aspriority=low. Models areflux-{voice}-{language}, for exampleModel::FluxHaleyEn; the WebSocket rejects REST-only options and the compressed encodings (mp3,opus,flac,aac) withDeepgramError::InvalidOptions.
API reference (layered)
- In-repo
README.mdsrc/speak/rest.rssrc/speak/options.rssrc/speak/websocket.rssrc/speak/flux/(rest.rs,websocket.rs,options.rs,response.rs)examples/speak/rest/text_to_speech_to_file.rsexamples/speak/rest/text_to_speech_to_stream.rsexamples/speak/websocket/text_to_speech_websocket.rsexamples/speak/flux/batch_synthesize.rsexamples/speak/flux/websocket_synthesize.rs
- OpenAPI
- Raw spec:
https://developers.deepgram.com/openapi.yaml - Endpoint reference:
https://developers.deepgram.com/reference/text-to-speech/speak-request
- Raw spec:
- AsyncAPI
- Rust SDK support: the Aura
/v1/speakWebSocket viaSpeak::speak_stream().handle(), and the Flux TTS/v2/speakWebSocket viaSpeak::flux_request(options).handle() - Raw spec:
https://developers.deepgram.com/asyncapi.yaml
- Rust SDK support: the Aura
- Context7
/llmstxt/developers_deepgram_llms_txt
- Product docs
https://developers.deepgram.com/docs/text-to-speechhttps://developers.deepgram.com/docs/tts-rest
Gotchas
- Aura and Flux TTS are separate endpoints with separate clients. Aura voices (
aura-*) go to/v1/speak— REST viaspeak_to_file/speak_to_stream, WebSocket viaspeak_stream(). Flux TTS voices (flux-*) go to/v2/speakviaspeak::flux. Aura voices are rejected on/v2/speakand vice versa; the twoModelenums (speak::options::Modelandspeak::flux::options::Model) are distinct types. - Pick encoding/container pairs deliberately. For raw output use
Container::None; for.wavoutput useContainer::Wav. speak_to_stream(...)is not the WebSocket. It streams HTTP response bytes fromPOST /v1/speak, so the whole request is one block of text. To send text incrementally and get audio back as it is generated, usespeak_stream()(Aura,/v1/speak) orflux_request(options)(Flux TTS,/v2/speak).- Use API keys with
Token. Do not send API keys asBearer.
Example files in this repo
examples/speak/rest/text_to_speech_to_file.rsexamples/speak/rest/text_to_speech_to_stream.rsexamples/speak/websocket/text_to_speech_websocket.rsexamples/speak/flux/batch_synthesize.rsexamples/speak/flux/websocket_synthesize.rs
Central product skills
For cross-language Deepgram product knowledge — the consolidated API reference, documentation finder, focused runnable recipes, third-party integration examples, and MCP setup — install the central skills:
npx skills add deepgram/skills
This SDK ships language-idiomatic code skills; deepgram/skills ships cross-language product knowledge (see api, docs, recipes, examples, starters, setup-mcp).