wantsong
/
skills-vault
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
skills-vault/skills/voice-generation/SKILL.md

3.6 KiB
Raw Blame History

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.