80 lines
3.6 KiB
Markdown
80 lines
3.6 KiB
Markdown
---
|
|
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.
|