skills-vault/skills/voice-generation/SKILL.md

name

description

voice-generation

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:

   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:

   voice-gen voices list
   

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

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:

   voice-gen voices list
   

2. Confirm the input directory and output directory. Defaults are scripts/ and output/.

3. Run:

   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.