text-to-speech

name

text-to-speech

description

Use this skill whenever the user wants to convert text to speech, generate audio/MP3 from text, add voice narration, build a TTS tool or web service, do batch text-to-audio conversion, synthesize dialogue with multiple voices, or extract text from an image and read it aloud. Trigger even if the user just says "make this text into audio", "I want to read this aloud", "generate a voiceover", or "turn my script into MP3". Supports 50+ languages and 200+ neural voices. Use scripts/ for ready-to-run code.

Text-to-Speech Skill

Convert text to natural-sounding MP3 audio. Supports 50+ languages, 200+ neural voices, speed/pitch control, batch processing, dialogue synthesis, image OCR, and web service deployment.

Engine Selection

Engine	Cost	Quality	Languages	API Key
edge-tts	Free	High — Neural	50+	None
gTTS	Free	Medium	30+	None
OpenAI TTS	Paid	Very High	Multilingual	Yes
Azure TTS	Paid / free tier	Highest	100+	Yes

Default choice: edge-tts — free, no sign-up, Microsoft neural voices, runs offline after install. For gTTS / OpenAI / Azure details → see references/engines.md.

Quick Start

pip install edge-tts

import asyncio, edge_tts

async def tts(text, output="output.mp3", voice="zh-CN-XiaoxiaoNeural",
              rate="+0%", pitch="+0Hz"):
    await edge_tts.Communicate(text, voice, rate=rate, pitch=pitch).save(output)

asyncio.run(tts("你好，这是语音合成测试。"))

Or use the bundled CLI directly:

python scripts/tts.py "你好世界" -o hello.mp3
python scripts/tts.py "Hello!" -v en-US-JennyNeural -r "+25%"
python scripts/tts.py --list-voices zh
echo "pipe text in" | python scripts/tts.py -o out.mp3

Common Voices

Language	Voice	Gender
中文（普通话）	zh-CN-XiaoxiaoNeural	F
中文（普通话）	zh-CN-YunxiNeural	M
中文（粤语）	zh-HK-HiuMaanNeural	F
中文（台湾）	zh-TW-HsiaoChenNeural	F
日語	ja-JP-NanamiNeural	F
日語	ja-JP-KeitaNeural	M
English (US)	en-US-JennyNeural	F
English (US)	en-US-GuyNeural	M
English (UK)	en-GB-SoniaNeural	F
한국어	ko-KR-SunHiNeural	F
Français	fr-FR-DeniseNeural	F
Deutsch	de-DE-KatjaNeural	F
Español	es-ES-ElviraNeural	F

List all voices for a language:

import asyncio, edge_tts
async def show(lang):
    for v in await edge_tts.list_voices():
        if lang in v["Locale"]:
            print(v["ShortName"], v["Gender"])
asyncio.run(show("zh"))

Speed & Pitch

# rate: "-50%" (slow) .. "+100%" (fast)   pitch: "-20Hz" (low) .. "+20Hz" (high)
await tts("Hello", rate="-25%", pitch="-5Hz")   # slow, deep
await tts("Hello", rate="+50%", pitch="+10Hz")  # fast, high

Batch Conversion — scripts/batch_convert.py

Converts a list of texts concurrently. Run directly or import as a module:

python scripts/batch_convert.py items.json -o audio/

items.json format:

[
  {"text": "第一句", "voice": "zh-CN-XiaoxiaoNeural", "filename": "01.mp3"},
  {"text": "Second", "voice": "en-US-JennyNeural",    "filename": "02.mp3"}
]

Dialogue / Multi-Voice — scripts/dialogue.py

Combines multiple voices into one MP3 (requires ffmpeg, no pydub needed):

python scripts/dialogue.py dialogue.json -o conversation.mp3

dialogue.json format:

[
  {"voice": "zh-CN-XiaoxiaoNeural", "text": "你好，我叫小晓。"},
  {"voice": "zh-CN-YunxiNeural",    "text": "你好小晓，我叫云希。"}
]

Image OCR → Speech — scripts/image_to_speech.py

Extracts text from an image then converts to audio:

# macOS:  brew install tesseract tesseract-lang
# Ubuntu: apt install tesseract-ocr tesseract-ocr-chi-sim
pip install pytesseract Pillow edge-tts
python scripts/image_to_speech.py photo.jpg -o from_image.mp3 --lang chi_sim+eng

Web Service — scripts/web_app.py

A FastAPI web app with /tts endpoint and voice listing:

pip install fastapi uvicorn edge-tts python-multipart
python scripts/web_app.py          # http://localhost:8000

Endpoints:

• GET / — Simple HTML form UI
• POST /tts — Convert text, returns MP3 download
• GET /voices?lang=zh — List available voices

Error Handling

Wrap calls with retry for network hiccups:

async def safe_tts(text, output, voice="zh-CN-XiaoxiaoNeural", retries=3):
    for i in range(retries):
        try:
            await edge_tts.Communicate(text, voice).save(output)
            return output
        except Exception as e:
            if i < retries - 1:
                await asyncio.sleep(2 ** i)
    return None

Streaming

async def stream_to_file(text, output, voice="zh-CN-XiaoxiaoNeural"):
    with open(output, "wb") as f:
        async for chunk in edge_tts.Communicate(text, voice).stream():
            if chunk["type"] == "audio":
                f.write(chunk["data"])

Bundled Scripts

Script	Purpose	Key deps
scripts/tts.py	CLI: single text → MP3	edge-tts
scripts/batch_convert.py	Batch JSON → MP3s	edge-tts
scripts/dialogue.py	Multi-voice dialogue → MP3	edge-tts, ffmpeg
scripts/image_to_speech.py	Image OCR → MP3	pytesseract, Pillow, edge-tts
scripts/web_app.py	FastAPI TTS web service	fastapi, uvicorn, edge-tts

For alternative engines (gTTS, OpenAI, Azure) → references/engines.md