# Narration audio — rules for Codex agents (Pre-Uni New College Lesson Voice Creator)

All narration for solution videos is made with the **Lesson Voice Creator** (cloned teacher voice).
Never call ElevenLabs, Qwen, Inworld or any other TTS service directly, and never put API keys in code.

## How to make audio

Preferred: the MCP tool `make_narration` (server `preuni_voice` in ~/.codex/config.toml).

- `code`: the question code used as the file name, e.g. `QID191568`
- `script`: the narration script (rules below). Blank line between paragraphs.
- `pauses`: the sheet's "Thinking pauses" value, e.g. `1.77 s / 1.62 s / 1.70 s` (one per paragraph gap). Optional.
- Leave `speed` and `style` out unless a person asked; the studio defaults apply.

The tool returns a download URL (valid 24 h). Save the file with the curl command it gives.

Without MCP, use the command-line client:

```bash
python lvc_client.py --code QID191568 --text-file script.txt --pauses "1.77 / 1.62 / 1.70" --out audio
python lvc_client.py --batch scripts.csv --out audio
```

## Cost rules

- Every new generation costs money. The same script with the same settings is cached and free.
- **Never use `force`** unless a person asked to regenerate that question.
- Fix the script first, then generate once. Do not try several versions.
- Budget reached (HTTP 402 / exit code 3): stop all audio work and report it.
- Server or token problem (exit code 2): stop and report it. Do not loop.

## How to write the script

The voice reads exactly what you write, so write it the way a teacher says it aloud.

- Plain spoken Australian English, short sentences, no markdown, bullets, emojis or stage directions.
- One blank line between paragraphs. Each paragraph that ends with a question gets a thinking pause after it.
- Numbers and maths in words where reading could go wrong:
  `3/4` → "three quarters", `2 1/2` → "two and a half", `$12.50` → "twelve dollars fifty",
  `45%` → "forty-five percent", `x² + 3 = 12` → "x squared plus three equals twelve",
  `3:2` → "three to two", `km/h` → "kilometres per hour", `cm²` → "square centimetres",
  `7:45 am` → "seven forty-five in the morning", option `(C)` → "option C".
- Start directly with the explanation. End with the answer: "The correct answer is C."