voice-gen

name	voice-gen
description	Generate AI speech with VoxCPM2 — voice design, controllable cloning, and ultimate cloning via MCP tools.

Voice Gen — VoxCPM2 TTS via MCP

Use the VoxCPM MCP server (voxcpm) to generate AI speech. The server is a 1:1 bridge to the VoxCPM2 Gradio app with three TTS modes and 12 voice presets.

Three Modes

Mode	How to activate	What it does
Voice Design	text + control_instruction, no ref_wav	Creates a new voice from a text description
Controllable Cloning	text + ref_wav + optional control_instruction	Clones timbre, optional style guidance
Ultimate Cloning	text + ref_wav + prompt_text_value + use_prompt_text=True	Audio continuation — full vocal nuance preservation

Voice Presets (12 available)

Use these as ref_wav for instant cloning. Auto-pick the best one silently based on user's described need. Only list them if explicitly asked.

Preset	Character
airy	Light, breathy, ethereal
buttery	Smooth, rich, warm
disconnected	Detached, flat, robotic
enter_voice_mode	System prompt — "entering voice mode"
exit_voice_mode	System prompt — "exiting voice mode"
final	Authoritative, conclusive, bold
glassy	Clear, crisp, brittle
intro	Opening/narrative tone
pre_recommendations	Recommendation lead-in
pre_voice	Voice mode preamble
recommendations	Suggestive, advisory tone
rounded	Full, warm, balanced

Steps

1. Understand the request

Determine what the user wants:

• Just speak text? → Voice Design with an appropriate control_instruction
• Sound like someone? → If a preset matches, use ref_wav=preset_name. If they provide a file path, use that.
• Clone with transcript? → Run run_asr on the audio first, then use Ultimate Cloning
• Creative/expressive? → Voice Design with a vivid control_instruction

Success criteria: You know the mode, the text, and have a rough control_instruction or ref_wav in mind.

2. Construct the MCP call

Call mcp__voxcpm__generate with appropriate parameters:

Voice Design (most common):

mcp__voxcpm__generate(text="...", control_instruction="...", dit_steps=10)

Cloning from preset:

mcp__voxcpm__generate(text="...", ref_wav="airy", dit_steps=10)

Cloning from file:

mcp__voxcpm__generate(text="...", ref_wav="/path/to/audio.wav", dit_steps=10)

Ultimate Cloning (with transcript): First transcribe: mcp__voxcpm__run_asr(audio_path="/path/to/ref.wav") Then generate: mcp__voxcpm__generate(text="...", ref_wav="/path/to/ref.wav", use_prompt_text=True, prompt_text_value="transcript here")

Parameter reference:

• control_instruction — Be vivid. Describe gender, age, tone, emotion, pace. Supports Chinese & English. Examples: "A warm maternal voice, mid 40s, gentle and reassuring", "年轻女性，甜美活泼，语速较快"
• cfg_value — 1.0-3.0. Default 2.0. Higher = stricter adherence to prompt. Lower = more creative variation.
• dit_steps — 1-50. Default 10. Higher = potentially better quality, slower. 10 is fine for most cases. Use 25+ for demanding quality.
• denoise — True if reference audio is noisy
• do_normalize — True to normalize numbers/dates in text

3. Return the result

The response includes audio_url — a direct link to the generated WAV file on the Gradio server. Tell the user the URL so they can listen or download.

If the call fails, read the error field and adjust. Common fixes: check that the VoxCPM container is running, try a different preset, or simplify the text.

Success criteria: You have an audio_url the user can play. If the user isn't satisfied, adjust the control_instruction or try a different preset.

Rules

• Never list all presets unless asked. Auto-pick based on context.
• Craft control_instructions actively. Don't ask the user to write them — you write them based on what they describe wanting.
• Start with dit_steps=10. Only increase if the user asks for higher quality.
• The VoxCPM container must be running (port 8808). If ping fails, tell the user to start it with docker compose up -d in /home/openclaudeuser/VoxCPM.
• Audio URLs are served by the Gradio container. They're only accessible while the container is running.