> For the complete documentation index, see [llms.txt](https://ai.ortusbooks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ai.ortusbooks.com/main-components/audio/text-to-speech.md).

# 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

```javascript
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`, `cartesia`                                                                         |
| `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

```javascript
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:

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

### Custom provider and voice

```javascript
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

```javascript
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

```javascript
// 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:

```javascript
// 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:

```javascript
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

```javascript
audio = aiSpeak(
    "This is a premium voice synthesis example.",
    { voice_id: "EXAVITQu4vr4xnSDxMaL" },  // Sarah, a premade voice that works on every plan
    { provider: "elevenlabs" }
)
audio.saveToFile( "premium.mp3" )
println( "Format: #audio.getAudioFormat()#, Size: #audio.getSize()# bytes" )
```

### Cartesia: low-latency Sonic voices

```javascript
audio = aiSpeak(
    "Fast, natural speech with Cartesia Sonic.",
    {
        voice      : "db6b0ed5-d5d3-463d-ae85-518a07d3c2b4",  // Skylar. Any voice ID from the Cartesia library
        language   : "en",
        emotion    : "happy",   // generation_config: emotion, volume (0.5-2.0), speed (0.6-1.5)
        sample_rate: 44100
    },
    { provider: "cartesia", outputFormat: "wav" }
)
audio.saveToFile( "sonic.wav" )
```

Cartesia supports `mp3`, `wav`, `pcm`, `mulaw` and `alaw`. `flac` and `opus` throw `InvalidArgument`. Set `CARTESIA_API_KEY` or pass `apiKey`. To stream the audio instead, see [Streaming Text-to-Speech](https://ai.ortusbooks.com/main-components/audio/streaming-speech.md).

### Generate comparison files across all voices

```javascript
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**    | The name of one of your Mistral voices (looked up and sent as `voice_id`) or a voice id (UUID). Default: the first preset voice | *(provider default)*                            | *(first preset voice)*                          |
| **Gemini**     | `Fenrir`, `Aoede`, `Kore` (and others via API)                                                                                  | `Fenrir`                                        | `Aoede`                                         |
| **Grok / xAI** | `eve` (default), `ara`, `rex`                                                                                                   | `rex`                                           | `eve`                                           |
| **ElevenLabs** | Premade voices (e.g. `EXAVITQu4vr4xnSDxMaL` Sarah, `CwhRBWXzGAHq8TQ4Fs17` Roger) or any voice ID your plan can use              | `CwhRBWXzGAHq8TQ4Fs17` (Roger)                  | `EXAVITQu4vr4xnSDxMaL` (Sarah)                  |
| **Cartesia**   | Any voice ID (UUID) from the Cartesia voice library                                                                             | `47c38ca4-5f35-497b-b1a3-415245fb35e1` (Daniel) | `db6b0ed5-d5d3-463d-ae85-518a07d3c2b4` (Skylar) |

> For ElevenLabs and Cartesia, pass a `voice_id` in `params` (or `voice`) for specific voices. Library voices on ElevenLabs need a paid plan over the API.
>
> To stream audio as it is generated, see [Streaming Text-to-Speech](https://ai.ortusbooks.com/main-components/audio/streaming-speech.md). Provider notes: Cartesia supports `mp3`, `wav`, `pcm`, `mulaw` and `alaw` (not `flac` or `opus`). Grok supports `mp3`, `wav`, `pcm`, `mulaw` and `alaw`. ElevenLabs supports `mp3`, `wav`, `pcm`, `mulaw`, `alaw` and `opus`.
>
> For ElevenLabs 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`:

```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` |

```javascript
// 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](https://ai.ortusbooks.com/main-components/audio.md)
* [Speech-to-Text](https://ai.ortusbooks.com/main-components/audio/speech-to-text.md)
* [Audio Translation](https://ai.ortusbooks.com/main-components/audio/audio-translation.md)
* [aiSpeak BIF Reference](https://ai.ortusbooks.com/advanced/reference/built-in-functions/aispeak.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://ai.ortusbooks.com/main-components/audio/text-to-speech.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
