---
name: text-to-speech
description: |
  Use when the user asks to narrate text / convert files or folders to an MP3
  audiobook — "narrate this", "read this aloud", "convert to audio",
  "text to speech", "make an audiobook", "narrate this file/folder".
---

# Skill: Text-to-Speech (narrate to MP3)

Run commands from the repository root. The package can be invoked either as
the installed console script or as a module:

```bash
audiobook narrate ...
# or, without installing:
python3 -m audiobook_generator narrate ...
```

## Main rule

**Narration is ONE run of the CLI per file or per folder, in the background.**
The tool walks the folder itself and produces one MP3 per supported file; no
model involvement is needed during synthesis. Do NOT split the work per file
and do NOT wrap it in subagents — that only burns tokens and can interrupt
synthesis. If parallelism is really needed, use a few background processes
(`&`), not agents.

## Usage

```bash
# MAIN CASE: folder → one MP3 per supported file (alphabetical order)
audiobook narrate /path/to/folder -o /path/to/out

# single file of any supported format → one MP3
audiobook narrate /path/to/file.txt -o /path/to/out
```

`narrate` options: `-o/--out` (default `audio_narration`), `--lang` (default
`ru`), `--engine gtts|gcloud`, `--voice` (for gcloud), `--max-chars-per-chunk`,
`--text-only` (extract text only, for a quick check), `-v`.

Specialized commands: `audiobook convert book.pdf` (PDF with chapter
boundaries from the table of contents or `Глава N` / `Chapter N` headings),
`audiobook web <URL>` (a web article), `audiobook epub book.epub`, `audiobook
book <folder_of_md_files>` (a folder of Markdown chapters as a single book).

## Engine policy

Default is **`gtts` (free), full stop** — do not switch engines on your own
even for large texts. Paid `--engine gcloud` — ONLY on an explicit signal in
the request:
- speed/urgency ("fast", "urgent", "ASAP" — gcloud is much faster: no 60-second
  pacing between requests);
- explicit request for paid/higher quality ("gcloud", "Wavenet", "Chirp", or a
  `--voice` is given).

`gcloud` requires `GOOGLE_APPLICATION_CREDENTIALS`; if credentials are not
configured, say so and offer a choice: set them up, or narrate for free
instead (slower).

## Workflow

1. Confirm the input path (file/folder) and the output directory if not
   given.
2. Optionally run with `--text-only` first for a quick check of the extracted
   text before spending time on synthesis.
3. Run ONE `narrate` command **in the background** (e.g. `run_in_background`
   or `nohup ... &`, logging to a file): gTTS paces requests roughly 60
   seconds apart, so a large text can take tens of minutes to hours. Do NOT
   poll with a sleep loop — wait for the completion notification. Progress is
   visible in the log (`Chapter N/M`); text chunks are cached under
   `<out>/.cache` (removed automatically once a chapter finishes
   successfully). If a run is interrupted, recover a listenable MP3 from the
   cache with:
   ```bash
   python3 -m audiobook_generator.assemble_cache <out>/.cache output.mp3
   ```
4. On completion, report the output path and total duration:
   ```bash
   ffprobe -v error -show_entries format=duration -of csv=p=0 file.mp3
   ```

## Quality: mixed-language text

gTTS reads Latin script poorly inside Russian text; technical terms are
transliterated to Cyrillic (e.g. Kafka → Кафка) or wrapped for correct
pronunciation. Frequent acronyms/terms can be added to `ACRONYM_MAP`/
`TERM_MAP` in `text_preprocessor.py` (applied automatically). Tables and code
are read poorly by TTS — rewrite them as prose in the source text before
narrating.

## Where to change what

| What to change | Where |
|---|---|
| New file format | `src/audiobook_generator/any_reader.py` → `read_any_file()` + `SUPPORTED_SUFFIXES`, plus a dedicated reader module if needed |
| Pronunciation / term replacement | `src/audiobook_generator/text_preprocessor.py` |
| Bitrate, sample rate, pauses | `src/audiobook_generator/config.py` (`AudioConfig`) |
| Chapter splitting / CLI commands | `src/audiobook_generator/main.py`, `src/audiobook_generator/chapter_splitter.py` |
| TTS engine behavior (retries, pacing, SSML) | `src/audiobook_generator/tts_engine.py` |
| Chunking, caching, assembly | `src/audiobook_generator/audio_generator.py` |