<!--
  Public educational copy — Division Agent skill pack.
  Scrubbed for public download: no personal emails, Drive folder IDs, or private paths.
  Status labels such as Working Draft refer to the draft→approved lifecycle, not a site watermark.
-->
---
name: grok-tts
description: Make a narration audio file (WAV or MP3) from text with xAI Grok text-to-speech, signed in with the user's own SuperGrok / X Premium+ account (OAuth, no API key, no extra API cost). Cantonese by default. Use when a task needs spoken audio saved as a file — a voice-over, narration track, or read-out of a script — including "make a narration wav", "voice-over for this script", "turn this text into an mp3", "整旁白", "幫我讀成 wav", "配音檔". Not for live voice conversation or voice memos.
---

# Grok TTS

One script, `scripts/tts.py`. Run it from this skill's folder with `python3` on Linux/macOS, `python` or `py -3` on Windows. Python 3.9+, standard library only, nothing to install. Every command prints **one JSON object**; `"success": true` means `path` holds the saved file.

```bash
python3 scripts/tts.py speak --file script.txt [--name NAME] [--out DIR]
python3 scripts/tts.py speak --text "short line" [--voice eve] [--language yue] [--format wav|mp3] [--sample-rate 48000] [--speed 1.0]
python3 scripts/tts.py voices
python3 scripts/tts.py login | status | logout
```

On success, give the user the `path` and `duration_seconds`.

## Defaults

- Voice `eve`, language `yue` (Cantonese), **WAV, 48 kHz, mono, 16-bit**. Ask for `--format mp3` only when the user wants MP3 (128 kbps unless `--bit-rate` says otherwise).
- Files go to `~/grok-tts-output/`. Override per call with `--out DIR`, or for the whole machine with `GROK_TTS_OUTPUT_DIR`. If you work in a shared or synced workspace folder, save there so the user can reach the file.
- `--name` sets the file name (no extension). An existing file is never overwritten; a `-2`, `-3` suffix is added.

## Writing the text

- For anything longer than a sentence or two, write the script to a UTF-8 file and pass `--file`. Long Chinese text in a quoted command-line argument breaks easily. `--file -` reads stdin.
- Long scripts are fine. The text is split at paragraph and sentence breaks and joined into one file. About 4,000 characters of Cantonese is about 13 minutes of audio and takes about 2 minutes. Wait for the command to finish.
- A blank line between paragraphs gives a natural pause of about 0.3 s.
- Speech tags shape the delivery. Use them sparingly.
  - Inline, square brackets: `[pause]`, `[long-pause]`, `[breath]`, `[inhale]`, `[exhale]`, `[sigh]`, `[laugh]`, `[chuckle]`, `[giggle]`, `[cry]`, `[tsk]`, `[tongue-click]`, `[lip-smack]`, `[hum-tune]`.
  - Wrapping, angle brackets: `<slow>…</slow>`, `<fast>`, `<soft>`, `<whisper>`, `<loud>`, `<emphasis>`, `<higher-pitch>`, `<lower-pitch>`, `<build-intensity>`, `<decrease-intensity>`, `<sing-song>`, `<singing>`. Keep each wrapping tag inside one paragraph.
- Names, English words and numbers can be misread. If a word matters, generate a short test line first and have the user listen.

## Voices and languages

- 28 voices, all multilingual. `voices` lists them with gender. Keep one voice for a whole series.
- `--language`: `yue` (Cantonese, default), `en`, `zh`, `ja`, `ko`, `fr`, `de`, `es-ES`, `pt-BR`, `auto` and other BCP-47 codes.
- `--speed` 0.7–1.5 (default 1.0).

## Sign-in

Auth is xAI Grok OAuth on the user's SuperGrok / X Premium+ account. **It is the same sign-in as the Imagine skill**: if Imagine is signed in on this machine, there is nothing to do. If a call returns `auth_required`:

1. Run `tts.py login`. It returns `verification_uri_complete` and `user_code`.
2. Show the user both. Ask them to open the URL, check the code matches, and approve.
3. When they say done, run `login` again. Once it reports `signed_in: true`, retry the `speak` command.

`logout` signs Imagine out too, so run it only when the user asks. Never ask the user to paste a token or key into chat. Never read or copy another app's credentials (Hermes, Grok CLI).

## Errors

- `tts_forbidden` (HTTP 403): xAI refused TTS for this sign-in. Tell the user. Do not ask for an API key.
- `api_error`: the message says which piece failed (`piece 3 of 5`). Run the same command once more. If it fails again, report the error.
- `invalid_args`: fix the option named in the message.

## Do not

- Do not use this for chat replies or voice memos. Use it only when a file is needed.
- Do not re-encode or "clean up" the WAV afterwards. Hand over the file as it is.