pks tts

pks tts turns text or SSML into an MP3 using Azure AI Foundry's tts-hd deployment or Azure Speech's neural-voice endpoint, and can optionally render an audio-reactive MP4 from the result.

Overview

pks tts is a single leaf command — it has no subcommands, aliases, or hidden flags. It runs one of two independent synthesis paths and always writes the resulting audio to disk:

• Plain-text mode (default): text from the positional argument or --text-file goes to an Azure AI Foundry tts-hd deployment via an OpenAI-compatible endpoint. --voice and --model apply here.
• SSML mode: a file passed to --ssml-file goes to Azure Speech's neural-voice REST endpoint instead. --voice, --model, and any text input are ignored — the SSML document controls everything, including which voice speaks.

Either path can chain into an optional ffmpeg post-step (--video) that renders an audio-reactive MP4 alongside the MP3.

Use plain-text mode with the OpenAI-style voices (alloy, echo, fable, onyx, nova, shimmer) for generic English narration. Switch to --ssml-file mode for Danish narration or anything needing SSML control — neural voices such as da-DK-ChristelNeural or da-DK-JeppeNeural, multi-voice dialog, prosody, or breaks — since plain-text mode has no SSML support.

Prerequisites

• Azure AI Foundry authentication. Run pks foundry init first. pks tts does not authenticate on its own — it checks the stored Foundry session and a selected resource, and fails immediately if either is missing.
• ffmpeg, for --video only. Either put ffmpeg on PATH or point PKS_FFMPEG_BIN at the binary.

Synopsis

pks tts [text] [options]

tts    Synthesize speech from text or SSML, optionally rendering an audio-reactive MP4

Global environment variables

Arguments

Options

How synthesis and output work

The two modes hit genuinely different Azure endpoints. Plain-text mode POSTs a JSON body (model/input/voice) to the deployment's /openai/deployments/{deployment}/audio/speech route. SSML mode POSTs the raw SSML document as application/ssml+xml to /tts/cognitiveservices/v1, with --format sent as the X-Microsoft-OutputFormat header instead of anything in the body — this is why --format only applies to SSML mode. Both endpoints live under the cognitiveservices.azure.com resource family, not the newer services.ai.azure.com family used by some other pks Foundry integrations; if you're debugging a permissions or endpoint mismatch against your Foundry resource, check that family first.

pks tts resolves the output path to an absolute path and prints it as the first line of stdout via a plain write, the same convention pks image uses. It then writes a human-readable success line (file size, voice, and timing) to that same stdout stream right after it — nothing is redirected to stderr. A script that wants just the path should take the first line of stdout, not capture the whole stream; the progress spinner is the only output that stays off stdout.

When --video is set, ffmpeg runs as a post-step after synthesis succeeds, reading the generated audio and writing an MP4 next to it using the chosen --video-size and --video-style.

Examples

pks tts "Hello world"

Writes speech-<timestamp>.mp3 in the current directory using the default voice (alloy) and model (tts-hd).

pks tts --text-file script.txt --voice nova --output speech.mp3

Synthesizes a longer script from a file with the nova voice, writing to speech.mp3.

pks tts --ssml-file dialog-da.xml --output spike-dialog-da.mp3

Synthesizes Danish, multi-voice dialog from an SSML file via the Azure Speech neural endpoint. --voice and --model would be ignored here even if supplied.

pks tts "Launch day." --video --video-style pulse --video-size 1080x1920

Synthesizes the line and renders a vertical, pulse-style audio-reactive MP4 alongside the MP3 — ready for a LinkedIn Story post.

Troubleshooting

Note. --deployment/-d is documented as defaulting to the value from your stored Foundry credentials, but the command always falls back to the literal tts-hd when the flag is omitted — it does not read a deployment name from pks foundry init's stored resource selection. Pass --deployment explicitly if your Foundry deployment isn't named tts-hd.

See also

• pks foundry init — authenticate and select the Foundry resource pks tts requires
• pks foundry — the Azure AI Foundry auth and model area pks tts depends on
• pks — command families overview, including where tts sits among content and media commands