Python Text to Speech
Turn any text into spoken audio

⚙️ The Three Properties You Can Control

• rate — Words per minute. Default is usually ~200. Lower = slower.
• volume — Float between 0.0 (silent) and 1.0 (full).
• voice — A specific voice object from engine.getProperty("voices").

You set these with engine.setProperty(name, value) and read them with engine.getProperty(name).

🧪 Runnable Example — Slow, Loud, Custom Voice

import pyttsx3

engine = pyttsx3.init()

current_rate   = engine.getProperty("rate")
current_volume = engine.getProperty("volume")
print(f"Default rate: {current_rate} wpm")
print(f"Default volume: {current_volume}")

engine.setProperty("rate", 150)
engine.setProperty("volume", 0.9)

voices = engine.getProperty("voices")
if len(voices) > 1:
    engine.setProperty("voice", voices[1].id)

engine.say("Now I am speaking slower, and my volume is turned up.")
engine.runAndWait()

• 1
  Import pyttsx3.
• 3
  engine = pyttsx3.init() — Initialise.
• 5–6
  current_rate = engine.getProperty("rate") and current_volume = engine.getProperty("volume") — Reads the current settings so you know what you're starting from. Useful for debugging — sometimes a system's default rate is wildly different from what you expect.
• 7–8
  Print the current defaults. On most systems you'll see something like Default rate: 200 wpm and Default volume: 1.0. Rates vary by OS — Windows SAPI5 typically defaults to 200, espeak often defaults to 175.
• 10
  engine.setProperty("rate", 150) — Sets the speaking rate to 150 words per minute. Slower than the default 200. Try values like 100 (very slow), 150 (comfortable), 200 (normal), 300 (fast). Note: some engines interpret rate as a percentage rather than WPM — espeak, for example, uses a 80–450 range. Test empirically on your platform.
• 11
  engine.setProperty("volume", 0.9) — Sets volume to 90% of max. Range is 0.0 to 1.0. Values outside this range are usually clamped — but don't rely on that; keep values in [0.0, 1.0].
• 13
  voices = engine.getProperty("voices") — Retrieves the list of available voices.
• 14–15
  if len(voices) > 1: engine.setProperty("voice", voices[1].id) — If at least two voices exist, select the second one. We pass voices[1].id, not voices[1] — the engine expects the voice ID string, not the Voice object. This is a very common mistake for beginners.
• 17
  engine.say("Now I am speaking slower...") — Queue the text. It will be spoken with the rate, volume, and voice we just set. Note that properties are read when the engine actually plays the audio, not when say() is called — so you can change properties between say calls if you want different utterances to have different settings.
• 18
  engine.runAndWait() — Plays it.

🗣️ Listing Voices with Names and Languages

For a more useful voice picker, inspect each voice's attributes:

import pyttsx3

engine = pyttsx3.init()
voices = engine.getProperty("voices")

for i, v in enumerate(voices):
    langs = ", ".join(v.languages) if v.languages else "unknown"
    gender = getattr(v, "gender", "unknown") or "unknown"
    print(f"[{i}] {v.name}")
    print(f"     ID: {v.id}")
    print(f"     Languages: {langs}")
    print(f"     Gender: {gender}\n")

• 1–2
  Import and initialise.
• 3
  Get the voices list.
• 5
  for i, v in enumerate(voices): — Loop with index and voice object.
• 6
  langs = ", ".join(v.languages) if v.languages else "unknown" — v.languages is a list like ["en-US"]. Join into a comma-separated string. If the list is empty or missing, show "unknown". The ternary prevents an AttributeError if a voice doesn't expose languages.
• 7
  gender = getattr(v, "gender", "unknown") or "unknown" — Two layers of safety: getattr returns "unknown" if the attribute doesn't exist; the or "unknown" handles the case where the attribute exists but is None. Some voices report gender, some don't.
• 8–11
  Print the four attributes. Two blank lines (\n\n) between voices make the output readable.

💾 The save_to_file() Pattern

import pyttsx3

engine = pyttsx3.init()
engine.setProperty("rate", 160)

text = "This audio is being saved to a file for later listening."
output_path = "speech.wav"

engine.save_to_file(text, output_path)
engine.runAndWait()

print(f"Saved to {output_path}")

• 1
  Import pyttsx3.
• 3
  Initialise the engine.
• 4
  engine.setProperty("rate", 160) — Set the speaking rate. This property applies to the saved audio too — whatever properties are set at the time save_to_file runs will be baked into the file.
• 6
  text = "..." — The text to convert to speech.
• 7
  output_path = "speech.wav" — The output file path. Use a .wav extension, not .mp3. pyttsx3 uses each OS's native TTS engine, and those engines typically output WAV (SAPI5 outputs WAV, NSSpeechSynthesizer outputs AIFF on some macOS versions, espeak outputs WAV). Some platforms won't produce valid MP3s even if you name the file .mp3.
• 9
  engine.save_to_file(text, output_path) — Queues a "save this text to this file" operation. Like say(), this just queues the operation — it doesn't actually write anything yet.
• 10
  engine.runAndWait() — Executes the queued operations. This is what actually synthesises the audio and writes the file. Without this call, the file is never created.
• 12
  print(f"Saved to {output_path}") — Confirmation. At this point the file should exist — but see the warning below.

📼 Converting WAV to MP3 (Optional)

If you need an MP3 (smaller files, wider compatibility), the pydub library can convert — but it requires ffmpeg installed on your system:

from pydub import AudioSegment

audio = AudioSegment.from_wav("speech.wav")
audio.export("speech.mp3", format="mp3")

print("Converted to speech.mp3")

• 1
  from pydub import AudioSegment — Import the audio-processing class. Install with pip install pydub. You also need ffmpeg installed on your system (brew install ffmpeg on macOS, sudo apt install ffmpeg on Linux, or download from ffmpeg.org on Windows).
• 3
  AudioSegment.from_wav("speech.wav") — Loads the WAV file into memory as an AudioSegment object. This object exposes dozens of audio operations (trimming, volume, fade, speed).
• 4
  audio.export("speech.mp3", format="mp3") — Encodes and writes an MP3 file. The format="mp3" tells pydub which codec to use. Behind the scenes, pydub calls ffmpeg.
• 6
  Confirmation print.

🌐 Generating Speech with gTTS

from gtts import gTTS

text = "Hello, this is Google Text to Speech. I sound more natural than pyttsx3."

tts = gTTS(text=text, lang="en", slow=False)
tts.save("google_tts.mp3")

print("Saved to google_tts.mp3")

• 1
  from gtts import gTTS — Import the class. Install first with pip install gTTS.
• 3
  text = "..." — The text to speak. This gets sent to Google's servers — don't use it for anything confidential.
• 5
  tts = gTTS(text=text, lang="en", slow=False) — Creates a gTTS object. Three arguments:
• —
    text — The string to convert. Can be up to ~100 characters per request if you're calling repeatedly; for longer text, gTTS handles chunking internally, but rate limits apply.
• —
    lang — ISO 639-1 language code. "en" for English, "es" for Spanish, "fr" for French, "ja" for Japanese, etc. Use "en-gb" for British accent, "en-au" for Australian, "en-in" for Indian English.
• —
    slow=False — When True, gTTS speaks more slowly — useful for language learners. When False, natural pace.
• 6
  tts.save("google_tts.mp3") — Writes the audio to an MP3 file. Unlike pyttsx3, this saves the file immediately — no runAndWait needed. gTTS handles the network call and MP3 encoding synchronously inside .save().
• 8
  Confirmation print.

🎧 Playing gTTS Audio Immediately

If you want to hear the audio right away (rather than just saving it), combine gTTS with a playback library. The simplest option is playsound:

from gtts import gTTS
from playsound import playsound

tts = gTTS(text="Playing audio directly from memory.", lang="en")
tts.save("temp_speech.mp3")

playsound("temp_speech.mp3")

print("Playback complete.")

• 1
  Import gTTS.
• 2
  from playsound import playsound — Import the play function. Install with pip install playsound. Note: newer versions of playsound have compatibility issues on Python 3.10+; if you hit problems, use pip install playsound==1.2.2 to get the stable version.
• 4–5
  Generate speech and save it to a temporary file. gTTS needs a file to write to — it can't play audio directly from memory with the playsound library.
• 7
  playsound("temp_speech.mp3") — Plays the MP3 through your default audio device. Blocks until playback finishes — so the next line runs only after the audio completes.
• 9
  Confirmation print — reached only after playback finishes.

🌍 Multilingual Example — Speak in Three Languages

from gtts import gTTS

phrases = [
    ("en", "Hello, how are you?"),
    ("es", "Hola, ¿cómo estás?"),
    ("fr", "Bonjour, comment allez-vous ?"),
]

for lang, text in phrases:
    tts = gTTS(text=text, lang=lang)
    filename = f"hello_{lang}.mp3"
    tts.save(filename)
    print(f"Saved: {filename}")

• 3–7
  phrases = [...] — A list of tuples. Each tuple is (language_code, text). This structure makes it easy to loop over many language/text pairs.
• 9
  for lang, text in phrases: — Tuple unpacking in the loop header. lang gets the first element of each tuple, text gets the second.
• 10
  tts = gTTS(text=text, lang=lang) — Creates a new gTTS object per iteration, with the current language and text.
• 11
  filename = f"hello_{lang}.mp3" — Builds a filename that includes the language code. So the outputs are hello_en.mp3, hello_es.mp3, hello_fr.mp3. Simple but effective — each language gets its own file.
• 12
  tts.save(filename) — Saves the audio. Note that each language uses the same voice infrastructure but with a different language model — so the Spanish version will sound like native Spanish, not English-with-Spanish-words.
• 13
  Print confirmation for each file.

🔐 Setting Up AWS Credentials

Before you can call Polly, you need AWS credentials. Here's the process:

1. Create a free AWS account at aws.amazon.com.
2. Go to IAM → Users → Create user.
3. Name the user (e.g. polly-user), choose "Programmatic access".
4. Attach the AmazonPollyFullAccess policy.
5. Save the Access Key ID and Secret Access Key.
6. Install the SDK: pip install boto3.
7. Set credentials either via aws configure (recommended) or environment variables.

🧪 Generating Speech with Polly

import boto3

polly = boto3.client("polly", region_name="us-east-1")

text = "Welcome to Amazon Polly. This voice is neural and sounds almost human."

response = polly.synthesize_speech(
    Text=text,
    OutputFormat="mp3",
    VoiceId="Joanna",
    Engine="neural",
)

with open("polly_output.mp3", "wb") as f:
    f.write(response["AudioStream"].read())

print("Saved polly_output.mp3")

• 1
  import boto3 — The AWS SDK for Python. boto3 is the current version (boto2 is legacy). Install with pip install boto3.
• 3
  polly = boto3.client("polly", region_name="us-east-1") — Creates a client for the Polly service in the US East (N. Virginia) region. Region matters — voice availability varies by region. us-east-1 has the widest selection, including all the neural voices. Other regions have fewer voices. If you don't have credentials set up yet, this line will fail with a NoCredentialsError.
• 5
  The text to speak. Polly handles up to 3,000 characters per call (for long text, use the async start_speech_synthesis_task API).
• 7
  response = polly.synthesize_speech(...) — The API call. Returns a response dict with the audio stream.
• 8
  Text=text — The string to convert. Max 3,000 characters for the synchronous API.
• 9
  OutputFormat="mp3" — Audio format. Options: "mp3", "ogg_vorbis", "pcm". MP3 is the most universally playable.
• 10
  VoiceId="Joanna" — The voice name. Popular neural voices: Joanna (en-US female), Matthew (en-US male), Amy (en-GB female), Olivia (en-AU female), Lucia (es-ES female), Takumi (ja-JP male). Full list at docs.aws.amazon.com/polly/latest/dg/voicelist.html.
• 11
  Engine="neural" — Choose the neural engine. This is what gives Polly its natural sound. Alternatives: "standard" (older, cheaper, more robotic) and "long-form" (for reading long text with consistent intonation). Neural costs more per character but sounds dramatically better.
• 14
  with open("polly_output.mp3", "wb") as f: — Opens a binary-write file. The "wb" mode is critical — audio is bytes, not text. Using "w" would corrupt the file with Unicode encoding errors.
• 15
  f.write(response["AudioStream"].read()) — response["AudioStream"] is a StreamingBody object (a file-like object holding the audio data). .read() loads all its bytes into memory. Then f.write(...) writes those bytes to disk. If the audio is very long, this could be memory-heavy — for those cases, use shutil.copyfileobj(response["AudioStream"], f) to stream instead.
• 17
  Confirmation.

📊 Polly Pricing (as of 2026)

📄 Reading a Text File Aloud

import pyttsx3
from pathlib import Path

engine = pyttsx3.init()
engine.setProperty("rate", 170)

file_path = Path("article.txt")

if not file_path.exists():
    print(f"File not found: {file_path}")
else:
    text = file_path.read_text(encoding="utf-8")
    print(f"Read {len(text)} characters")

    engine.say(text)
    engine.runAndWait()

    print("Finished reading.")

• 1
  Import pyttsx3.
• 2
  from pathlib import Path — The modern, cross-platform way to work with file paths. Always prefer pathlib over string concatenation or os.path — it's cleaner and handles Windows vs Unix differences automatically.
• 4–5
  Initialise the engine and set a comfortable rate of 170 wpm.
• 7
  file_path = Path("article.txt") — Creates a Path object pointing to the file. If you need an absolute path, use Path.cwd() / "article.txt" or Path.home() / "Documents" / "article.txt".
• 9
  if not file_path.exists(): — Checks whether the file exists before trying to open it. This is defensive — if the file is missing, we print a helpful message rather than crashing with FileNotFoundError.
• 10
  Error message with the path — this is much more useful than just "file not found", because it tells the user which file and where.
• 11
  else: — The file exists, so we can safely read it.
• 12
  text = file_path.read_text(encoding="utf-8") — Reads the entire file as one string. encoding="utf-8" is explicit and important — without it, Python uses the system default, which mangles non-ASCII characters on many Windows systems. read_text() handles the file open, read, and close all in one call.
• 13
  print(f"Read {len(text)} characters") — Reports the file size. Useful for confirming you actually read the file you expected (a 3,000-char file that reports 15 chars probably means you read the wrong file).
• 15
  engine.say(text) — Queues the entire text for speech. Note: some TTS engines cut off at a certain length. If your text is very long, see the "chunking" pattern below.
• 16
  engine.runAndWait() — Plays it.
• 18
  Confirmation, printed after the audio finishes.

✂️ Splitting Long Text into Speakable Chunks

import pyttsx3
import re

engine = pyttsx3.init()

def chunk_text(text, max_chars=500):
    sentences = re.split(r"(?<=[.!?])\s+", text)
    chunks = []
    current = ""
    for s in sentences:
        if len(current) + len(s) + 1 <= max_chars:
            current = (current + " " + s).strip()
        else:
            if current:
                chunks.append(current)
            current = s
    if current:
        chunks.append(current)
    return chunks

long_text = (
    "This is the first sentence. Here is another one with more content. "
    "And a third. Finally, a fourth sentence to close."
)

for i, chunk in enumerate(chunk_text(long_text, 80)):
    print(f"Chunk {i+1}: {chunk}")
    engine.say(chunk)
    engine.runAndWait()

• 1–2
  Import pyttsx3 and re (for regex-based sentence splitting).
• 4
  Initialise the engine.
• 6
  def chunk_text(text, max_chars=500): — Helper function. Default max chunk size is 500 characters — comfortable for most engines.
• 7
  sentences = re.split(r"(?<=[.!?])\s+", text) — Regex split. The (?<=[.!?]) is a lookbehind: it matches a position preceded by ., !, or ?, followed by whitespace. This splits the text at sentence boundaries while keeping the punctuation attached to the sentence.
• 8
  chunks = [] and current = "" — Initialize the accumulator list and the current in-progress chunk.
• 9
  for s in sentences: — Process one sentence at a time.
• 10–11
  If adding this sentence would keep us under the limit, add it. The +1 accounts for the space we'll add between sentences.
• 12–14
  Otherwise, this sentence would overflow the current chunk. Save the current chunk (if non-empty) and start a new one with this sentence.
• 15–16
  After the loop, don't forget the final chunk — the loop exits before appending it.
• 17
  Return the list of chunks.
• 19–22
  A multi-line string sample. Note the parentheses around the strings — Python allows adjacent strings to be concatenated when separated by whitespace, and parentheses make that work across multiple lines.
• 24
  for i, chunk in enumerate(chunk_text(long_text, 80)): — Loop with an index over the returned chunks. We pass max_chars=80 to force chunking in this small example — the actual output will produce 2–3 chunks.
• 25
  Print the chunk number and content for debugging.
• 26–27
  engine.say(chunk) then engine.runAndWait() — Speak each chunk one at a time. Calling runAndWait per chunk ensures each finishes before the next starts, and gives a natural pause between chunks.

🌐 Reading an Article from a URL

Combine requests + BeautifulSoup + TTS to speak a web article aloud. This is the pattern used by podcast generators and accessibility tools.

import requests
from bs4 import BeautifulSoup
from gtts import gTTS

url = "https://en.wikipedia.org/wiki/Text-to-speech"
response = requests.get(url, timeout=10, headers={"User-Agent": "TTS-Reader/1.0"})
soup = BeautifulSoup(response.text, "html.parser")

paragraphs = soup.select("#mw-content-text p")[:5]
article_text = " ".join(p.get_text(strip=True) for p in paragraphs)

print(f"Extracted {len(article_text)} characters")

tts = gTTS(text=article_text, lang="en")
tts.save("article_audio.mp3")

print("Saved article_audio.mp3")

• 1–3
  Imports: requests for the HTTP fetch, BeautifulSoup for HTML parsing, gTTS for speech.
• 5
  url = "..." — The article URL.
• 6
  response = requests.get(url, timeout=10, headers={"User-Agent": "TTS-Reader/1.0"}) — Fetch with a timeout and a custom User-Agent. Wikipedia is generous with bots, but a descriptive UA is respectful.
• 7
  soup = BeautifulSoup(response.text, "html.parser") — Parse the HTML.
• 10
  paragraphs = soup.select("#mw-content-text p")[:5] — Select all <p> tags inside the article content container, then slice the first 5. Wikipedia's article body is inside <div id="mw-content-text">. This selects the article paragraphs while excluding nav, sidebars, and footer links.
• 11
  article_text = " ".join(p.get_text(strip=True) for p in paragraphs) — Extracts text from each paragraph tag and joins them with spaces. The generator expression inside join is more memory-efficient than a list comprehension — it doesn't hold all the strings in memory at once.
• 13
  Print the extracted character count — if it's suspiciously small (like 15 chars), the selector probably didn't match; if it's huge (like 100,000 chars), you're grabbing too much.
• 15
  tts = gTTS(text=article_text, lang="en") — Create the gTTS object. gTTS will chunk the long text internally.
• 16
  tts.save("article_audio.mp3") — Saves the whole article as one MP3. For a 5-paragraph Wikipedia intro, this is usually 2–3 minutes of audio and takes 5–10 seconds to generate.
• 18
  Confirmation.

🎯 The Design

🧱 Step 1 — The Argument Parser

import argparse
from pathlib import Path

def build_parser():
    p = argparse.ArgumentParser(
        description="Convert text to speech from a file, string, or stdin."
    )
    p.add_argument("source", nargs="?", default="-",
                   help="File path, '-' for stdin, or a quoted string.")
    p.add_argument("-o", "--output", default=None,
                   help="Save audio to this file (.mp3 or .wav). Omit to play.")
    p.add_argument("-e", "--engine", choices=["pyttsx3", "gtts"], default="gtts",
                   help="Which TTS engine to use (default: gtts).")
    p.add_argument("-v", "--voice", default=None,
                   help="Voice ID (pyttsx3) or language code (gTTS).")
    p.add_argument("-r", "--rate", type=int, default=170,
                   help="Speech rate in words per minute (pyttsx3 only).")
    p.add_argument("--volume", type=float, default=1.0,
                   help="Volume between 0.0 and 1.0 (pyttsx3 only).")
    return p

if __name__ == "__main__":
    args = build_parser().parse_args()
    print(args)

• 1–2
  argparse for CLI parsing; Path for file handling.
• 4
  def build_parser(): — Encapsulates parser construction in a function, which makes it importable and testable.
• 5–7
  ArgumentParser(description=...) — Creates the parser with a one-line description shown in --help output.
• 8–9
  p.add_argument("source", nargs="?", default="-") — Positional argument. nargs="?" makes it optional. default="-" means "read from stdin if not provided".
• 10–11
  -o/--output — Destination file. Default None means "play aloud, don't save".
• 12–13
  -e/--engine — Restricted to pyttsx3 or gtts by choices. Default gtts because most users want to save an MP3 file.
• 14–15
  -v/--voice — Free-form string. Could be a voice ID or a language code depending on the engine.
• 16–17
  -r/--rate — type=int means argparse converts the string automatically and errors on non-numbers.
• 18–19
  --volume — type=float for decimal values.
• 20
  Return the configured parser.
• 22–24
  if __name__ == "__main__": — Only executes when the file is run directly, not when imported as a module. Parses args and prints the resulting namespace for inspection.

🔧 Step 2 — Reading Input from Any Source

import sys
from pathlib import Path

def read_input(source):
    if source == "-":
        if sys.stdin.isatty():
            raise SystemExit("No input. Pass a file, a quoted string, or pipe via stdin.")
        return sys.stdin.read()

    p = Path(source)
    if p.is_file():
        return p.read_text(encoding="utf-8")

    return source

• 1–2
  Import sys (for stdin) and Path (for files).
• 4
  def read_input(source): — One function handles all three cases: stdin, file, or literal string.
• 5
  if source == "-": — The conventional Unix marker for stdin.
• 6–7
  sys.stdin.isatty() — True when the user is at a terminal and hasn't piped anything. In that case, block indefinitely waiting for input — so we exit with a helpful error instead.
• 8
  return sys.stdin.read() — Reads all piped input at once.
• 10
  p = Path(source) — Treat the argument as a path to check.
• 11–12
  if p.is_file(): return p.read_text(...) — If it's a real file, read it as UTF-8.
• 14
  return source — Fall back to treating the argument as literal text. So python tts.py "hello world" speaks "hello world" without needing a file.

⚙️ Step 3 — The Engine Functions

def speak_pyttsx3(text, output=None, voice=None, rate=170, volume=1.0):
    import pyttsx3
    engine = pyttsx3.init()
    engine.setProperty("rate", rate)
    engine.setProperty("volume", volume)
    if voice:
        engine.setProperty("voice", voice)

    if output:
        engine.save_to_file(text, str(output))
    else:
        engine.say(text)
    engine.runAndWait()

def speak_gtts(text, output=None, voice="en"):
    from gtts import gTTS
    tts = gTTS(text=text, lang=voice or "en")
    if output:
        tts.save(str(output))
    else:
        import tempfile, os
        from playsound import playsound
        with tempfile.NamedTemporaryFile(suffix=".mp3", delete=False) as f:
            tmp = f.name
        try:
            tts.save(tmp)
            playsound(tmp)
        finally:
            os.unlink(tmp)

• 1
  def speak_pyttsx3(text, output=None, voice=None, rate=170, volume=1.0): — All pyttsx3-specific logic lives here. output is optional — if omitted, we play aloud.
• 2
  import pyttsx3 — Deliberately imported inside the function. This lets the tool run (with gTTS) on systems where pyttsx3 isn't installed.
• 3–5
  Initialise and set properties. Properties are applied regardless of play-vs-save, since they affect the saved file too.
• 6–7
  if voice: engine.setProperty("voice", voice) — Only set voice if the user passed one. Trying to set it to None would crash the engine.
• 9–10
  If output is provided, queue a save operation. str(output) converts a Path object to string — pyttsx3 doesn't accept Path directly.
• 11–12
  Otherwise, queue say() for immediate playback.
• 13
  engine.runAndWait() — Executes whichever operation we queued.
• 15
  def speak_gtts(text, output=None, voice="en"): — gTTS uses voice as a language code, so the parameter is reused with a different meaning.
• 16–17
  gTTS(text=text, lang=voice or "en") — If voice is empty/None, default to English.
• 18–19
  If saving to a file, call tts.save() directly — the simplest case.
• 20–22
  Otherwise, use tempfile.NamedTemporaryFile to create a safe temporary path with a unique name. delete=False means Python won't auto-delete — we handle cleanup ourselves in finally.
• 23–25
  try/finally pattern: save the audio, play it, and always remove the temp file — even if playback errors out. Without finally, a playback crash would leave the MP3 on disk.

🚀 Step 4 — Wiring It All Together

def main():
    parser = build_parser()
    args = parser.parse_args()

    try:
        text = read_input(args.source)
    except SystemExit as e:
        parser.error(str(e))

    if not text.strip():
        parser.error("Input text is empty.")

    if args.engine == "pyttsx3":
        speak_pyttsx3(
            text,
            output=args.output,
            voice=args.voice,
            rate=args.rate,
            volume=args.volume,
        )
    else:
        speak_gtts(text, output=args.output, voice=args.voice or "en")

    if args.output:
        print(f"Saved: {args.output}")

if __name__ == "__main__":
    main()

• 1
  def main(): — Entry point. Keeps the module importable and testable.
• 2–3
  Build the parser and parse sys.argv. argparse handles --help, invalid choices, and type conversion automatically.
• 5–6
  Read the input. This may raise SystemExit from read_input when stdin is empty.
• 7–8
  Catch SystemExit and convert it to parser.error() — which prints a clean message and the usage line, exits with code 2, and behaves like any other argparse error.
• 10–11
  if not text.strip(): — Refuse empty input. Without this check, pyttsx3 plays nothing and gTTS raises a confusing API error.
• 13–20
  Dispatch to the correct engine. pyttsx3 gets all five parameters; the CLI defaults flow through.
• 21–22
  gTTS only uses voice (as language). args.voice or "en" handles the case where the user didn't pass -v.
• 24–25
  Confirmation print — but only when actually saving, so a play-only invocation stays quiet (Unix-friendly).
• 27–28
  Standard entry-point guard.

📋 Full Usage Examples

# Play a quoted string aloud (default engine)
python tts.py "Hello, world."

# Read a file and play it with pyttsx3
python tts.py article.txt -e pyttsx3

# Save an MP3 with a British accent
python tts.py article.txt -o speech.mp3 -v en-gb

# Pipe from another program
cat long_article.txt | python tts.py - -o article.mp3

# Slow, quiet pyttsx3 output to a WAV file
python tts.py notes.txt -e pyttsx3 -r 120 --volume 0.6 -o notes.wav

# Save in Spanish
python tts.py "Hola, mundo" -o hola.mp3 -v es

🎯 What We're Building

📚 Step 1 — Parse the Chapters

import re
from pathlib import Path
from dataclasses import dataclass, field

@dataclass
class Chapter:
    number: int
    title: str
    body: str
    slug: str = ""

    def __post_init__(self):
        # Safe, filesystem-friendly slug from the title
        s = re.sub(r"[^a-z0-9]+", "-", self.title.lower()).strip("-")
        self.slug = f"{self.number:02d}-{s[:40]}"

def parse_chapters(text):
    pattern = re.compile(r"^##\s*Chapter\s+(\d+)\s*[:\-–]\s*(.+)$", re.MULTILINE)
    matches = list(pattern.finditer(text))
    if not matches:
        # No chapter markers: treat entire file as one chapter
        return [Chapter(1, "Full Text", text.strip())]

    chapters = []
    for i, m in enumerate(matches):
        number = int(m.group(1))
        title = m.group(2).strip()
        start = m.end()
        end = matches[i + 1].start() if i + 1 < len(matches) else len(text)
        chapters.append(Chapter(number, title, text[start:end].strip()))
    return chapters

• 1–3
  Imports: re for pattern matching, Path for later file work, dataclass for a clean data container.
• 5
  @dataclass — Auto-generates __init__, __repr__, and __eq__ based on the annotated fields. Saves boilerplate for a simple record type.
• 6–9
  Four fields: number (int), title (str), body (str), and slug (str, default empty — computed post-init).
• 11
  __post_init__ — A dataclass hook that runs automatically after the auto-generated __init__. Perfect place to compute derived fields like slug.
• 13
  re.sub(r"[^a-z0-9]+", "-", self.title.lower()) — Lowercases the title, then replaces every run of non-alphanumeric characters with a single dash. Produces URL- and filesystem-safe slugs.
• 14
  self.slug = f"{self.number:02d}-{s[:40]}" — Zero-padded chapter number (so files sort correctly: 01-, 02-, …, 10-) plus the first 40 characters of the slug. Result: 01-the-beginning.
• 16
  def parse_chapters(text): — The parsing logic.
• 17
  re.compile(r"^##\s*Chapter\s+(\d+)\s*[:\-–]\s*(.+)$", re.MULTILINE) — The chapter-header pattern:
  • ^## — a line starting with ##
  • \s*Chapter\s+ — the word "Chapter" (with flexible whitespace)
  • (\d+) — capture group 1: the chapter number
  • \s*[:\-–]\s* — a colon, hyphen, or en-dash separator
  • (.+)$ — capture group 2: the title
  • re.MULTILINE — makes ^ and $ match at line boundaries, not just string boundaries.
• 18
  matches = list(pattern.finditer(text)) — Finds every match. Converting to a list lets us index it (matches[i + 1] for the next chapter).
• 19–21
  if not matches: — Fallback: no chapter markers found. Treat the entire file as a single chapter titled "Full Text". Robust behavior for unstructured input.
• 23
  chapters = [] — Accumulator.
• 24
  for i, m in enumerate(matches): — Loop with both index and match object.
• 25–26
  Extract the number and title from the regex capture groups.
• 27–28
  start = m.end() (end of the header line) and end = next chapter's start, or end of file. This defines the chapter body boundaries. The conditional handles the last chapter specially.
• 29
  Slice the body and construct the Chapter object.
• 30
  Return the list.

🎙️ Step 2 — Synthesize Each Chapter with Resume Support

import json, sys
from pathlib import Path

def chunk_text(text, max_chars=4500):
    sentences = re.split(r"(?<=[.!?])\s+", text)
    chunks, current = [], ""
    for s in sentences:
        if len(current) + len(s) + 1 <= max_chars:
            current = (current + " " + s).strip()
        else:
            if current:
                chunks.append(current)
            current = s
    if current:
        chunks.append(current)
    return chunks

def synthesize_chapter(chapter, out_dir, lang="en", force=False):
    out_path = out_dir / f"{chapter.slug}.mp3"
    if out_path.exists() and not force:
        print(f"  ↻ Skipping {out_path.name} (already exists)")
        return out_path

    from gtts import gTTS
    chunks = chunk_text(chapter.body)

    if len(chunks) == 1:
        gTTS(text=chunks[0], lang=lang).save(str(out_path))
    else:
        # Multiple chunks: synthesize each, then concatenate with pydub
        import tempfile, os
        from pydub import AudioSegment
        combined = AudioSegment.empty()
        for i, chunk in enumerate(chunks):
            with tempfile.NamedTemporaryFile(suffix=".mp3", delete=False) as f:
                tmp = f.name
            try:
                gTTS(text=chunk, lang=lang).save(tmp)
                combined += AudioSegment.from_mp3(tmp)
            finally:
                os.unlink(tmp)
        combined.export(str(out_path), format="mp3")

    return out_path

• 1–2
  json (for the manifest later) and Path.
• 4
  chunk_text(text, max_chars=4500) — Same function as Lesson 7, but with a higher limit (4,500) because Google TTS accepts longer chunks than most engines.
• 15
  def synthesize_chapter(chapter, out_dir, lang="en", force=False): — force allows regenerating existing files; otherwise resume-skip.
• 16
  out_path = out_dir / f"{chapter.slug}.mp3" — Build the full output path using Path / str.
• 17–19
  Resume logic: if the file exists and force is False, print a skip message and return. This makes the tool re-runnable — a crash mid-batch means you resume where you left off instead of re-generating everything.
• 21
  from gtts import gTTS — Lazy import, keeping the function importable even if gTTS isn't installed.
• 22
  chunks = chunk_text(chapter.body) — Split into API-safe pieces.
• 24–25
  Fast path: if there's only one chunk, synthesize directly to the output path — no temp files needed.
• 26–38
  Multi-chunk path: synthesize each chunk to a temp file, load it as a pydub AudioSegment, and accumulate into combined via +=. The += operator on AudioSegment concatenates audio in-place.
• 33–37
  try/finally ensures the temp file is deleted even if MP3 loading fails. combined += requires the temp MP3 to be fully readable, so the whole chunk must be present first.
• 38
  combined.export(str(out_path), format="mp3") — Write the concatenated audio as one MP3. Requires ffmpeg installed (see Lesson 4).

📦 Step 3 — Orchestration and Manifest

def generate_audiobook(input_path, out_dir, lang="en", force=False):
    input_path = Path(input_path)
    out_dir = Path(out_dir)
    out_dir.mkdir(parents=True, exist_ok=True)

    if not input_path.exists():
        sys.exit(f"Input not found: {input_path}")

    text = input_path.read_text(encoding="utf-8")
    chapters = parse_chapters(text)
    print(f"Found {len(chapters)} chapter(s) in {input_path.name}")

    generated = []
    for ch in chapters:
        print(f"[{ch.number}/{len(chapters)}] {ch.title}")
        try:
            path = synthesize_chapter(ch, out_dir, lang=lang, force=force)
            generated.append({
                "number": ch.number,
                "title": ch.title,
                "file": path.name,
                "chars": len(ch.body),
            })
        except Exception as e:
            print(f"  ✗ Failed: {e}")
            continue

    manifest = {
        "source": input_path.name,
        "language": lang,
        "chapters": generated,
        "total_chapters": len(generated),
    }
    (out_dir / "manifest.json").write_text(
        json.dumps(manifest, indent=2, ensure_ascii=False),
        encoding="utf-8",
    )
    print(f"\nDone. {len(generated)} file(s) in {out_dir}/")
    print(f"Manifest: {out_dir / 'manifest.json'}")

• 1–3
  Coerce both paths to Path objects, then create the output directory. parents=True creates intermediate dirs (book/chapters/); exist_ok=True avoids errors if it already exists.
• 5–6
  Fail fast if the input doesn't exist. sys.exit() with a message is the cleanest way to signal a fatal CLI error.
• 8–10
  Read the whole file, parse chapters, print a summary. Users need confirmation the tool saw the right file and the expected chapter count.
• 12–13
  generated = [] then loop over chapters. The progress line [1/10] Title is essential UX for anything longer than a few seconds.
• 15–21
  Call synthesize_chapter, then append a metadata dict to generated. The chars field gives the user a rough sense of chapter length.
• 22–24
  Error containment: except Exception as e: print(...); continue — one failed chapter doesn't abort the whole book. This is the right call for long batch operations; users would rather have 9 of 10 chapters than 0.
• 26–31
  Build the manifest dict. It records source, language, chapter list, and total. This becomes the metadata that downstream tools (players, catalogs) can rely on.
• 32–35
  Write manifest.json with indent=2 (human-readable) and ensure_ascii=False (preserves Unicode titles — important for non-English books).
• 36–37
  Final summary, including the manifest path so the user knows where to look.

🏁 Step 4 — The Entry Point

import argparse

if __name__ == "__main__":
    parser = argparse.ArgumentParser(description="Generate an audiobook from a text file.")
    parser.add_argument("input", help="Source text file with '## Chapter N: Title' headers.")
    parser.add_argument("-o", "--out", default="audiobook", help="Output directory.")
    parser.add_argument("-l", "--lang", default="en", help="Language code (default: en).")
    parser.add_argument("--force", action="store_true", help="Regenerate existing files.")
    args = parser.parse_args()

    generate_audiobook(args.input, args.out, lang=args.lang, force=args.force)

python audiobook.py my-book.txt -o output -l en

# Force regeneration (overwrite existing files)
python audiobook.py my-book.txt -o output --force

# Non-English
python audiobook.py libro.txt -o salida -l es

🔊 pyttsx3 — Offline TTS

import pyttsx3

engine = pyttsx3.init()
engine.setProperty("rate", 170)       # words per minute
engine.setProperty("volume", 1.0)     # 0.0 to 1.0
engine.setProperty("voice", voice_id)   # voice ID string

voices = engine.getProperty("voices")
for v in voices:
    print(v.id, v.name)

engine.say("Hello, world")
engine.runAndWait()

engine.save_to_file("Save me", "out.wav")
engine.runAndWait()

engine.stop()

🌐 gTTS — Google TTS (Online)

from gtts import gTTS

tts = gTTS(text="Hello", lang="en", slow=False)
tts.save("out.mp3")

# Language codes: en, en-gb, en-au, en-in, es, fr, de, it, ja, ko, zh-CN, pt, ru

gTTS(text="Hola", lang="es", slow=True).save("slow.mp3")

☁️ Amazon Polly — Neural Voices

import boto3

polly = boto3.client("polly", region_name="us-east-1")

response = polly.synthesize_speech(
    Text="Hello from Polly",
    OutputFormat="mp3",
    VoiceId="Joanna",
    Engine="neural",
)

with open("out.mp3", "wb") as f:
    f.write(response["AudioStream"].read())

# Popular neural voices:
# en-US: Joanna, Matthew, Danielle, Gregory
# en-GB: Amy, Emma, Brian, Arthur
# en-AU: Olivia, Nicole, Russell
# es-ES: Lucia, Mia
# ja-JP: Takumi, Kazuha

🎧 Playing Audio

from playsound import playsound
playsound("out.mp3")

from pydub import AudioSegment
from pydub.playback import play
play(AudioSegment.from_mp3("out.mp3"))

audio = AudioSegment.from_wav("in.wav")
audio.export("out.mp3", format="mp3")
audio.export("out.ogg", format="ogg")

📄 Reading Text Sources

from pathlib import Path
text = Path("article.txt").read_text(encoding="utf-8")

import requests
from bs4 import BeautifulSoup
r = requests.get(url, timeout=10)
soup = BeautifulSoup(r.text, "html.parser")
text = " ".join(p.get_text(strip=True) for p in soup.select("article p"))

import sys
if not sys.stdin.isatty():
    text = sys.stdin.read()

✂️ Chunking Long Text

import re

def chunk_text(text, max_chars=500):
    sentences = re.split(r"(?<=[.!?])\s+", text)
    chunks, current = [], ""
    for s in sentences:
        if len(current) + len(s) + 1 <= max_chars:
            current = (current + " " + s).strip()
        else:
            if current:
                chunks.append(current)
            current = s
    if current:
        chunks.append(current)
    return chunks

📦 Installation Summary

pip install pyttsx3
pip install gTTS
pip install boto3
pip install playsound==1.2.2
pip install pydub simpleaudio

# Linux also needs: sudo apt install espeak espeak-data libespeak1 libespeak-dev
# pydub also needs ffmpeg: brew/apt install ffmpeg

🚀 Your Next Steps

• Build an audiobook generator — one MP3 per chapter, with a chapter index, from any EPUB or text file.
• Add TTS to a chatbot — stream LLM responses through gTTS or Polly to hear ChatGPT-style conversations.
• Build a voice assistant — combine speech_recognition (STT) with TTS for a full voice loop.
• Explore neural TTS — try Azure Neural TTS or ElevenLabs for voices almost indistinguishable from humans.
• Learn audio processing — pydub, librosa, and soundfile open up mixing, normalisation, and sound design.

📚 Related Lessons on Poetic Bytes