Text-to-Speech

Convert any text to natural-sounding audio using AI providers. aiSpeak() returns binary audio data wrapped in an AiSpeechResponse with helpers for saving, encoding, and streaming.

aiSpeak() converts text to natural-sounding speech using cloud AI providers. It returns an AiSpeechResponse object containing the binary audio data, with convenience methods for saving to disk, encoding as Base64, generating data URIs for HTML playback, and inspecting metadata.

🔧 The aiSpeak() Function

Syntax

aiSpeak( text, params={}, options={} )

Parameters

Parameter	Type	Required	Description
text	string	✅ Yes	The text to synthesize into speech
params	struct	No	Provider API parameters such as model, voice, speed
options	struct	No	Module-level options such as provider, apiKey, outputFile

Options

Option	Type	Default	Description
provider	string	(config)	AI provider: openai, mistral, gemini, grok, elevenlabs
apiKey	string	(env var)	Provider API key (falls back to <PROVIDER>_API_KEY env var)
voice	string	(config)	Voice name or ID for the provider, or the gender keyword "male" / "female" (resolved per provider via audio.voiceGenderMap in your config)
outputFormat	string	mp3	Audio output format: mp3, wav, flac, opus, pcm
speed	numeric	1.0	Playback speed multiplier (range: 0.25–4.0)
outputFile	string	""	If non-empty, saves audio to this path and returns the file path string instead of AiSpeechResponse
timeout	numeric	30	HTTP request timeout in seconds
logRequest	boolean	false	Log requests to the module log file
logRequestToConsole	boolean	false	Print request payload to console
logResponse	boolean	false	Log responses to the module log file
logResponseToConsole	boolean	false	Print raw provider response to console

📦 Return Value — AiSpeechResponse

When outputFile is not set, aiSpeak() returns an AiSpeechResponse object wrapping the binary audio data.

When outputFile is set, aiSpeak() saves the audio to that path and returns the absolute file path string instead of the response object.

AiSpeechResponse Methods

Method	Returns	Description
saveToFile( filePath )	string	Saves audio binary to disk; returns the absolute path
getBase64()	string	Returns the audio data as a Base64-encoded string
getMimeType()	string	Returns the MIME type (e.g. audio/mpeg for mp3)
toDataURI()	string	Returns a data:audio/mpeg;base64,... URI for an HTML <audio> src attribute
hasAudio()	boolean	Returns true if audio binary data is present and non-empty
getSize()	numeric	Returns the size of the audio data in bytes
getAudioFormat()	string	Returns the audio format string (e.g. mp3, wav)
toStruct()	struct	Returns a metadata struct (no binary data — safe for logging)
toJSON()	string	Returns JSON-serialized metadata
getMetadataValue( key )	any	Read a value from the response metadata bag
setMetadataValue( key, value )	this	Write a value to the metadata bag (fluent, chainable)

💡 Examples

Basic — synthesize and save to file

audio = aiSpeak( "Welcome to BoxLang AI!" )
audio.saveToFile( "welcome.mp3" )
println( "Size: #audio.getSize()# bytes" )

Shorthand with outputFile option

When you only need the file on disk, use outputFile to skip the response object entirely:

path = aiSpeak(
    "Your order has shipped.",
    {},
    { outputFile: "/audio/notification.mp3" }
)
println( "Saved to: #path#" )

Custom provider and voice

audio = aiSpeak(
    "Hello, this is a custom voice.",
    { speed: 1.2 },
    { provider: "openai", voice: "nova", outputFormat: "wav" }
)
audio.saveToFile( "custom.wav" )

🧱 Fluent Builder API (v3.2.0+)

Calling aiSpeak() with no arguments returns an AiSpeechRequest builder object for method chaining. This provides a more readable, self-documenting way to configure speech synthesis.

Basic Builder Usage

audio = aiSpeak()
    .of( "Welcome to BoxLang AI!" )
    .voice( "nova" )
    .provider( "openai" )
    .asMP3()
    .speak()

Builder Methods

Method	Description
of( text )	Set the text to synthesize (static factory)
.text( text )	Alias for of()
.model( name )	Set the TTS model
.provider( name )	Set the provider
.apiKey( key )	Set the API key
.voice( name )	Set the voice name
.male()	Use male voice (resolved per provider)
.female()	Use female voice (resolved per provider)
.speed( n )	Set playback speed (0.25–4.0)
.instructions( text )	Set voice instructions
.outputFile( path )	Set output file path
.asMP3()	Set output format to MP3
.asWav()	Set output format to WAV
.asFlac()	Set output format to FLAC
.asOpus()	Set output format to Opus
.asPCM()	Set output format to PCM
.withParams( struct )	Set provider params
.withOptions( struct )	Set module options
.withLogging()	Enable request/response logging
.speak()	Terminator — execute and return AiSpeechResponse

Fluent Examples

// Gender shortcuts
audio = aiSpeak()
    .of( "This uses a male voice." )
    .male()
    .speed( 1.2 )
    .speak()

// Save directly to file
path = aiSpeak()
    .of( "Notification alert!" )
    .asWav()
    .outputFile( "/audio/alert.wav" )
    .speak()

// Full configuration
audio = aiSpeak()
    .of( "Hello from BoxLang!" )
    .model( "tts-1-hd" )
    .provider( "openai" )
    .voice( "nova" )
    .speed( 1.0 )
    .asMP3()
    .withLogging()
    .speak()

💡 Backward Compatible: The traditional aiSpeak( text, params, options ) syntax continues to work unchanged. The fluent builder is an additional option — no migration required.

Gender keyword voices

Use "male" or "female" for provider-agnostic voice selection. The module resolves the keyword to the concrete voice configured in audio.voiceGenderMap for the active provider — no need to remember provider-specific names:

// Works with any provider — resolves to the configured male/female voice automatically
audio = aiSpeak( "This message uses a male voice.", {}, { voice: "male" } )
audio.saveToFile( "male-greeting.mp3" )

audio = aiSpeak( "This message uses a female voice.", {}, { voice: "female" } )
audio.saveToFile( "female-greeting.mp3" )

// Useful when switching providers without updating every voice call
audio = aiSpeak(
    "Same code, different provider.",
    {},
    { provider: "gemini", voice: "female" }  // resolves to "Aoede" on Gemini
)

Base64 / data URI for web responses

Embed audio directly in an HTML page or API response — no file I/O required:

audio = aiSpeak( "Click to play this message" )

// Embed directly in HTML
htmlOutput = '<audio controls src="#audio.toDataURI()#"></audio>'

// Or pass the raw Base64 to a front-end
jsonResponse = { audio: audio.getBase64(), mimeType: audio.getMimeType() }

ElevenLabs — high-quality multilingual voice

audio = aiSpeak(
    "This is a premium voice synthesis example.",
    { voice_id: "21m00Tcm4TlvDq8ikWAM" },  // Rachel voice ID
    { provider: "elevenlabs" }
)
audio.saveToFile( "premium.mp3" )
println( "Format: #audio.getAudioFormat()#, Size: #audio.getSize()# bytes" )

Generate comparison files across all voices

voices = [ "alloy", "echo", "fable", "onyx", "nova", "shimmer" ]
sampleText = "BoxLang AI — where imagination meets voice."

voices.each( voice => {
    aiSpeak(
        sampleText,
        { voice: voice },
        { outputFile: expandPath( "/tmp/voice-#voice#.mp3" ) }
    )
    println( "Generated: /tmp/voice-#voice#.mp3" )
})

🎙️ Provider Voice Reference

Provider	Available Voices	"male" keyword	"female" keyword
OpenAI	alloy, ash, echo, fable, onyx, nova, shimmer	ash	nova
Mistral	Charlotte	(provider default)	Charlotte
Gemini	Fenrir, Aoede, Kore (and others via API)	Fenrir	Aoede
Grok / xAI	alloy, echo, fable, onyx, nova, shimmer, eve	onyx	nova
ElevenLabs	Voice IDs from your ElevenLabs voice library	(provider default)	21m00Tcm4TlvDq8ikWAM

For ElevenLabs, pass a voice_id in params for specific voices. The "male"/"female" keywords resolve to the IDs configured in audio.voiceGenderMap.

Customising the gender map

The defaults can be overridden per-provider in config/boxlang.json:

"modules": {
    "bxai": {
        "settings": {
            "audio": {
                "voiceGenderMap": {
                    "openai": { "male": "echo", "female": "shimmer" },
                    "elevenlabs": { "male": "YOUR_MALE_VOICE_ID", "female": "YOUR_FEMALE_VOICE_ID" }
                }
            }
        }
    }
}

📡 Events

aiSpeak() fires two interception points you can hook into for logging, auditing, or modifying behavior.

Event	Data Available
beforeAISpeech	speechRequest, service
afterAISpeech	speechRequest, service, result

// Log all TTS calls with their output size
BoxRegisterInterceptor( "afterAISpeech", event => {
    var sizeKB = event.result.getSize() / 1024
    println( "TTS: provider=#event.service.getName()# size=#numberFormat( sizeKB, '0.0' )#KB" )
})

---

📖 Related Pages

• Audio Overview

• Speech-to-Text

• Audio Translation

• aiSpeak BIF Reference