---
name: voice-generation
description: Use when the user wants to generate spoken audio/TTS from Markdown scripts, voice a markdown file, batch-generate narration audio, register or list custom MiniMax voice clones, or operate the local `voice-gen` CLI. Triggers include requests like "turn this script into speech", "generate podcast audio", "use BroTsong-Saying-2026-06-10 to read this md", "register a new voice", and "list my voices". Requires the `voice-gen` CLI plus MiniMax `mmx` authentication; do not use for music generation, sound effects, image/video generation, or generic non-MiniMax TTS.
---

# Voice Generation

This Skill operates the local `voice-gen` Python CLI. The CLI wraps MiniMax `mmx` for text-to-speech and maintains a local `voices.json` registry of custom cloned voices.

## Runtime Requirements

- Activate the configured Conda environment before running the CLI.
- Ensure the `voice-gen` package has been installed in editable mode from the repository source.
- Ensure the `mmx` CLI is installed and authenticated. On Windows, verify with `cmd /c mmx auth status` to avoid PowerShell shim policy issues.
- Run CLI commands from the user's project root unless the user specifies another working directory.

## Workflow

### Register A Voice

1. Ask for the path to the reference audio file (`.mp3`, `.wav`, `.flac`, or `.m4a`) if the user has not provided it.
2. Run:

   ```bash
   voice-gen voices add <audio-path>
   ```

3. The friendly voice name is derived from the filename stem. Use timestamped filenames such as `BroTsong-Saying-2026-06-10.m4a` when the user wants a stable unique voice ID.
4. Confirm registration:

   ```bash
   voice-gen voices list
   ```

To seed a fresh project with voices already on the server, run:

```bash
voice-gen voices pull
```

Use `voice-gen voices pull --force` only when overwriting existing local entries is intended.

### Generate Audio

1. Confirm the voice name. If needed, run:

   ```bash
   voice-gen voices list
   ```

2. Confirm the input directory and output directory. Defaults are `scripts/` and `output/`.
3. Run:

   ```bash
   voice-gen gen --voice <name> <input-dir> --out <output-dir> --format mp3
   ```

4. Report how many files succeeded, where outputs were written, and any failures.

## Conventions

- Input scripts are Markdown files matching `*.md`.
- Frontmatter, headings, code fences, list markers, bold, italic, and inline code markup are stripped before synthesis.
- Synthesis text is passed to mmx through a temporary UTF-8 file, not a command-line `--text` value or `--text-file -`; the temporary file is removed after the call.
- Status output escapes non-ASCII path characters as `\uXXXX` sequences for Windows console safety; generated files retain their original Unicode names.
- Output files are named `<script-stem>.<format>`.
- The local voice registry is `voices.json` in the current working directory.

## Failure Handling

- If `voice-gen voices list` is empty, ask the user to register or pull voices first.
- If a voice is not found, list available voices and ask the user to choose one.
- If `mmx` authentication fails on Windows, ask the user to run `cmd /c mmx auth status` and `cmd /c mmx auth login`.
- If quota fails, surface the quota error and suggest waiting for the next quota window or upgrading.
- If the request is for music, sound effects, video, image, or non-MiniMax TTS, do not use this Skill.

## Known Limitation

MiniMax voice IDs cannot be fully unregistered by this tool. Deleting a source audio file may not free the voice name on the server. Prefer unique timestamped filenames for voice registration.