Design & media

speech

Try it

Turn scripts and prompt lists into spoken audio files through the bundled OpenAI text-to-speech CLI.

What it does

Generates narration, voiceover, IVR prompts, and accessibility reads from text using the OpenAI Audio API, defaulting to gpt-4o-mini-tts-2025-12-15 with built-in voices (cedar by default, marin for a brighter tone). Runs the bundled scripts/text_to_speech.py CLI for single clips or JSONL batches, augments your direction into a short labeled spec (voice affect, tone, pacing, emphasis) without rewriting the input text, and writes results to paths you set with --out or --out-dir. Requires OPENAI_API_KEY, caps requests at 50 per minute, and splits text over 4096 characters into chunks.

When to use it

  • Narrating a product demo or explainer video from a finished script
  • Generating a set of IVR or phone menu prompts in one batch run
  • Producing accessibility audio reads of written content
  • Iterating on a single clip by changing voice, speed, or delivery instructions

The skill document

Speech Generation Skill

Generate spoken audio for the current project (narration, product demo voiceover, IVR prompts, accessibility reads). Defaults to gpt-4o-mini-tts-2025-12-15 and built-in voices, and prefers the bundled CLI for deterministic, reproducible runs.

When to use

  • Generate a single spoken clip from text
  • Generate a batch of prompts (many lines, many files)

Decision tree (single vs batch)

  • If the user provides multiple lines/prompts or wants many outputs -> batch
  • Else -> single

Workflow

  1. Decide intent: single vs batch (see decision tree above).
  2. Collect inputs up front: exact text (verbatim), desired voice, delivery style, format, and any constraints.
  3. If batch: write a temporary JSONL under tmp/ (one job per line), run once, then delete the JSONL.
  4. Augment instructions into a short labeled spec without rewriting the input text.
  5. Run the bundled CLI (scripts/text_to_speech.py) with sensible defaults (see references/cli.md).
  6. For important clips, validate: intelligibility, pacing, pronunciation, and adherence to constraints.
  7. Iterate with a single targeted change (voice, speed, or instructions), then re-check.
  8. Save/return final outputs and note the final text + instructions + flags used.

Temp and output conventions

  • Use tmp/speech/ for intermediate files (for example JSONL batches); delete when done.
  • Write final artifacts under output/speech/ when working in this repo.
  • Use --out or --out-dir to control output paths; keep filenames stable and descriptive.

Dependencies (install if missing)

Prefer uv for dependency management.

Python packages:

uv pip install openai

If uv is unavailable:

python3 -m pip install openai

Environment

  • OPENAI_API_KEY must be set for live API calls.

If the key is missing, give the user these steps:

  1. Create an API key in the OpenAI platform UI: https://platform.openai.com/api-keys
  2. Set OPENAI_API_KEY as an environment variable in their system.
  3. Offer to guide them through setting the environment variable for their OS/shell if needed.
  • Never ask the user to paste the full key in chat. Ask them to set it locally and confirm when ready.

If installation isn't possible in this environment, tell the user which dependency is missing and how to install it locally.

Defaults & rules

  • Use gpt-4o-mini-tts-2025-12-15 unless the user requests another model.
  • Default voice: cedar. If the user wants a brighter tone, prefer marin.
  • Built-in voices only. Custom voices are out of scope for this skill.
  • instructions are supported for GPT-4o mini TTS models, but not for tts-1 or tts-1-hd.
  • Input length must be <= 4096 characters per request. Split longer text into chunks.
  • Enforce 50 requests/minute. The CLI caps --rpm at 50.
  • Require OPENAI_API_KEY before any live API call.
  • Provide a clear disclosure to end users that the voice is AI-generated.
  • Use the OpenAI Python SDK (openai package) for all API calls; do not use raw HTTP.
  • Prefer the bundled CLI (scripts/text_to_speech.py) over writing new one-off scripts.
  • Never modify scripts/text_to_speech.py. If something is missing, ask the user before doing anything else.

Instruction augmentation

Reformat user direction into a short, labeled spec. Only make implicit details explicit; do not invent new requirements.

Quick clarification (augmentation vs invention):

  • If the user says "narration for a demo", you may add implied delivery constraints (clear, steady pacing, friendly tone).
  • Do not introduce a new persona, accent, or emotional style the user did not request.

Template (include only relevant lines):

Voice Affect: 
Tone: 
Pacing: 
Emotion: 
Pronunciation: 
Pauses: 
Emphasis: 
Delivery: 

Augmentation rules:

  • Keep it short; add only details the user already implied or provided elsewhere.
  • Do not rewrite the input text.
  • If any critical detail is missing and blocks success, ask a question; otherwise proceed.

Examples

Single example (narration)

Input text: "Welcome to the demo. Today we'll show how it works."
Instructions:
Voice Affect: Warm and composed.
Tone: Friendly and confident.
Pacing: Steady and moderate.
Emphasis: Stress "demo" and "show".

Batch example (IVR prompts)

{"input":"Thank you for calling. Please hold.","voice":"cedar","response_format":"mp3","out":"hold.mp3"}
{"input":"For sales, press 1. For support, press 2.","voice":"marin","instructions":"Tone: Clear and neutral. Pacing: Slow.","response_format":"wav"}

Instructioning best practices (short list)

  • Structure directions as: affect -> tone -> pacing -> emotion -> pronunciation/pauses -> emphasis.
  • Keep 4 to 8 short lines; avoid conflicting guidance.
  • For names/acronyms, add pronunciation hints (e.g., "enunciate A-I") or supply a phonetic spelling in the text.
  • For edits/iterations, repeat invariants (e.g., "keep pacing steady") to reduce drift.
  • Iterate with single-change follow-ups.

More principles: references/prompting.md. Copy/paste specs: references/sample-prompts.md.

Guidance by use case

Use these modules when the request is for a specific delivery style. They provide targeted defaults and templates.

  • Narration / explainer: references/narration.md
  • Product demo / voiceover: references/voiceover.md
  • IVR / phone prompts: references/ivr.md
  • Accessibility reads: references/accessibility.md

CLI + environment notes

  • CLI commands + examples: references/cli.md
  • API parameter quick reference: references/audio-api.md
  • Instruction patterns + examples: references/voice-directions.md
  • If network approvals / sandbox settings are getting in the way: references/codex-network.md

Reference map

  • references/cli.md: how to run speech generation/batches via scripts/text_to_speech.py (commands, flags, recipes).
  • references/audio-api.md: API parameters, limits, voice list.
  • references/voice-directions.md: instruction patterns and examples.
  • references/prompting.md: instruction best practices (structure, constraints, iteration patterns).
  • references/sample-prompts.md: copy/paste instruction recipes (examples only; no extra theory).
  • references/narration.md: templates + defaults for narration and explainers.
  • references/voiceover.md: templates + defaults for product demo voiceovers.
  • references/ivr.md: templates + defaults for IVR/phone prompts.
  • references/accessibility.md: templates + defaults for accessibility reads.
  • references/codex-network.md: environment/sandbox/network-approval troubleshooting.

Questions people ask

Which model and voice does it use by default?
It uses gpt-4o-mini-tts-2025-12-15 with the built-in voice cedar, and suggests marin when a brighter tone is wanted. Custom voice creation is out of scope.
What do I need before running it?
The openai Python package (installed via uv pip install openai or pip) and an OPENAI_API_KEY set in your environment. The skill walks you through creating a key and setting the variable rather than having you paste it into chat.
How are long texts and large batches handled?
Each request is limited to 4096 characters, so longer text is split into chunks. Batches are written as a temporary JSONL file under tmp/speech/, run once, then deleted, with requests capped at 50 per minute.

Related skills

Join a video meeting as an AI bot with voice, avatar, and screenshare across four operating modes.

by johnpatternai22 installs8 stars

docx

Official

Create, edit, read, and redline .docx and .dotx files, with rendered output to check before you ship.

by Anthropic197.6k stars

pdf

Official

Read, extract, merge, split, rotate, watermark, encrypt, and create PDF files with Python libraries and CLI tools.

by Anthropic197.6k stars

chatgpt-apps

Official

Scaffold and refactor ChatGPT Apps SDK apps that pair an MCP server with a widget UI.

by OpenAI28.8k stars

Build or update full Figma screens from code using your published design system's components, variables, and styles.

by OpenAI28.8k stars

More from OpenAI

Browse all skills

chatgpt-apps

Official

Scaffold and refactor ChatGPT Apps SDK apps that pair an MCP server with a widget UI.

by OpenAI28.8k stars

Build or update full Figma screens from code using your published design system's components, variables, and styles.

by OpenAI28.8k stars

Build a Figma design system from your codebase through phased, checkpointed steps.

by OpenAI28.8k stars

figma-use

Official

Run JavaScript in Figma files through the Plugin API, with the API rules that keep scripts from failing.

by OpenAI28.8k stars

hatch-pet

Official

Turn a concept, brand cue, or reference art into a validated 8x9 animated Codex pet atlas with QA sheets and pet.json packaging.

by OpenAI28.8k stars

imagegen

Official

Generate or edit raster images for your project, with prompts shaped into structured specs and outputs saved into the workspace.

by OpenAI28.8k stars