---
url: >-
  https://adk.nht.io/api/@nhtio/adk/batteries/tts/native/helpers/functions/buildNativeTtsInvocation.md
---

# Function: buildNativeTtsInvocation()

```ts
function buildNativeTtsInvocation(input: {
  command?: string;
  extraArgs?: string[];
  outPath: string;
  pitch?: number;
  platform: NativeTtsPlatform;
  rate?: number;
  text: string;
  voice?: string;
  wordsPerMinute?: number;
}): {
  args: string[];
  cmd: string;
};
```

Defined in: [src/batteries/tts/native/helpers.ts:109](https://github.com/NHTIO/ADK/blob/v1.20260718.0/src/src/batteries/tts/native/helpers.ts#L109)

Build the `{ cmd, args }` invocation for one native TTS synthesis call. Pure and side-effect-free.

## Parameters

| Parameter               | Type                                                                                                                                                                                                                                                                   | Description                                                                 |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `input`                 | { `command?`: `string`; `extraArgs?`: `string`\[]; `outPath`: `string`; `pitch?`: `number`; `platform`: [`NativeTtsPlatform`](../../types/type-aliases/NativeTtsPlatform.md); `rate?`: `number`; `text`: `string`; `voice?`: `string`; `wordsPerMinute?`: `number`; } | -                                                                           |
| `input.command?`        | `string`                                                                                                                                                                                                                                                               | Optional executable override (default: `say`/`espeak-ng`/`powershell.exe`). |
| `input.extraArgs?`      | `string`\[]                                                                                                                                                                                                                                                             | Optional extra args inserted before the platform-specific flags.            |
| `input.outPath`         | `string`                                                                                                                                                                                                                                                               | The scratch WAV output path the binary writes to.                           |
| `input.pitch?`          | `number`                                                                                                                                                                                                                                                               | Optional espeak-ng pitch (0–99).                                            |
| `input.platform`        | [`NativeTtsPlatform`](../../types/type-aliases/NativeTtsPlatform.md)                                                                                                                                                                                                   | The target platform.                                                        |
| `input.rate?`           | `number`                                                                                                                                                                                                                                                               | Optional resolved `-10..10` rate for PowerShell (win32 only).               |
| `input.text`            | `string`                                                                                                                                                                                                                                                               | The text to synthesize.                                                     |
| `input.voice?`          | `string`                                                                                                                                                                                                                                                               | Optional voice name.                                                        |
| `input.wordsPerMinute?` | `number`                                                                                                                                                                                                                                                               | Optional resolved wpm for `say`/`espeak-ng`.                                |

## Returns

```ts
{
  args: string[];
  cmd: string;
}
```

The `{ cmd, args }` pair to hand to the executor.

| Name   | Type       | Defined in                                                                                                                              |
| ------ | ---------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `args` | `string`\[] | [src/batteries/tts/native/helpers.ts:119](https://github.com/NHTIO/ADK/blob/v1.20260718.0/src/src/batteries/tts/native/helpers.ts#L119) |
| `cmd`  | `string`   | [src/batteries/tts/native/helpers.ts:119](https://github.com/NHTIO/ADK/blob/v1.20260718.0/src/src/batteries/tts/native/helpers.ts#L119) |

## Remarks

The caller (the adapter) resolves every policy decision BEFORE calling this:

* `wordsPerMinute` is the already-resolved wpm for `say`/`espeak-ng` (the adapter computes
  `wordsPerMinute ?? clamp(round(175 * (rate ?? 1)), 80, 500)`).
* `rate` is the already-resolved `-10..10` integer for PowerShell's `SpeechSynthesizer.Rate`
  (the adapter computes `clamp(round(((rate ?? 1) - 1) * 10), -10, 10)`). It is used ONLY on
  win32 and ignored on darwin/linux — the helper does NOT recompute it.
* `pitch` is the espeak-ng `-p` value (0–99); ignored on darwin/win32.

On every platform, `command` (when supplied) overrides only the executable; the platform's own
argument/script shape is still built around it. `extraArgs` are inserted before the
voice/rate/pitch/text flags on darwin/linux; they are IGNORED on win32, where the entire
synthesis is expressed as a single `-Command` PowerShell script (there is no positional-flag slot
to forward them into safely).