voicebox

Voicebox TTS Skill

路径约定： 以下所有命令均使用 $SKILL_DIR 表示此技能的基础目录。Claude 加载技能时，系统提示词中会包含 Base directory for this skill: <path> — 请使用该路径。例如，如果安装在 ~/.agent/skills/voicebox/，则 $SKILL_DIR = ~/.agent/skills/voicebox。

使用 mlx-audio 独立进行文本转语音。支持自定义语音设计（根据文本描述）和语音克隆（根据音频样本）。无需外部应用。

重要：默认操作规则

当 /voicebox 后面跟着普通文本（而非“create”“clone”“transcribe”“record”“list”“delete”等关键词）时，默认操作始终是立即使用“Calm Narrator”配置生成语音。不要追问。不要提供选项菜单。直接运行生成命令并播放音频。

示例：/voicebox hello → 立即运行：

uv run $SKILL_DIR/scripts/voicebox.py generate "Calm Narrator" "hello" --play

只有在输入中包含明确关键词时，才切换到其他模式：

• “create” / “design” → 模式 2（创建配置）
• “clone” / “record” → 模式 3/4（克隆语音）
• “transcribe” → 模式 5（转录）
• “conversation” / “drama” / “audiobook” → 模式 6（多说话人）
• “list” / “delete” / “speakers” / “models” → 管理命令

其他所有情况 = 立即生成语音。

用法

生成语音

/voicebox "Hello world"                                     (uses default: Calm Narrator)
/voicebox "Calm Narrator" "Hello world"                     (explicit profile)
/voicebox "angry tone" "My Voice" "I can't believe this!"   (style + profile)

创建配置

/voicebox create a calm narrator voice profile              (designed - from description)
/voicebox create a custom profile using Ryan                (custom - preset speaker)
/voicebox clone my voice from /path/to/audio.wav            (cloned - from audio file)
/voicebox clone my voice                                    (record from mic + clone)

转录音频/视频

/voicebox transcribe /path/to/audio.wav
/voicebox transcribe /path/to/video.mp4

生成多说话人对话

/voicebox create a news broadcast with anchor, reporter, and expert
/voicebox make a conversation between Calm Narrator and Cheerful Girl
/voicebox generate a drama scene with these characters...

触发短语（自动激活此技能）

• “clone my voice”“record my voice”“create a voice clone”
• “transcribe this”“transcribe audio”“transcribe video”
• “create a conversation”“make a drama”“generate a dialogue”“audiobook”
• 任何涉及音频/视频转录或语音转文本的请求

架构

三种模型类别，各有不同质量档位：

类别	高（默认）	标准	用途
语音设计	Qwen3-TTS-12Hz-1.7B-VoiceDesign-bf16	（相同 — 仅有 1.7B）	根据描述创建自定义语音
语音克隆	Qwen3-TTS-12Hz-1.7B-Base-bf16	Qwen3-TTS-12Hz-0.6B-Base-bf16	克隆真实语音
自定义语音	Qwen3-TTS-12Hz-1.7B-CustomVoice-bf16	Qwen3-TTS-12Hz-0.6B-CustomVoice-bf16	9 种预设高级说话人，支持风格控制
ASR（转录）	Qwen/Qwen3-ASR-1.7B	Qwen/Qwen3-ASR-0.6B	语音转文本

所有命令都接受 --quality standard 或 --quality high（默认），用于选择模型档位。

所有状态都存储在技能的 data/ 目录中（默认：$SKILL_DIR/data/）：

• profiles.json — 配置注册表
• samples/ — 用作参考音频的 WAV 文件

脚本：scripts/voicebox.py（相对于技能根目录）

---

默认配置

使用场景	默认配置	类型	最适合
通用默认（英文文本）	Calm Narrator	设计型	中性旁白
CustomVoice 中文	Dylan	自定义（说话人：dylan）	带情感的中文
CustomVoice 英文	Aiden	自定义（说话人：aiden）	带情感的英文
CustomVoice 日文	Ono Anna	自定义（说话人：ono_anna）	带情感的日文

用户运行 /voicebox "some text" 且只提供文本（一个带引号的参数）时，默认使用 Calm Narrator。

文本需要带有情感地演绎，或用户指定了某种情绪（生气、悲伤、兴奋等）时，优先按语言使用 CustomVoice 默认配置：中文用 Dylan，英文用 Aiden，日文用 Ono Anna。CustomVoice 支持使用 --instruct 控制情绪。

---

模式 1：生成语音

分步工作流

1. 解析参数 — 计算带引号的参数数量：

   • 一个带引号的参数 → 仅文本。使用默认配置（“Calm Narrator”）。
   • 两个带引号的参数 → 第一个是配置名称，第二个是要朗读的文本。
   • 三个带引号的参数 → 第一个是风格/指令，第二个是配置名称，第三个是要朗读的文本。

2. 查找音色配置 — 在 profiles.json 中查找音色配置名称（不区分大小写，可进行部分匹配）。

3. 情绪分段（仅限主动请求 — 默认绝不执行）：

   **默认情况下，长文本通过一次 generate 调用生成。**不要自动将文本拆分为带有不同情绪的片段。只有用户明确使用以下类似表述提出请求时，才启用情绪分段：

   • “带有情绪”、“自动添加情绪”、“按情绪分段”、“情绪化演绎”
   • “按情绪拆分”、“改变情绪”、“让表达更有感染力”

   如果用户没有要求情绪分段，则跳过整个步骤，直接进入步骤 4（简单生成），无论文本长度如何。

   用户明确要求进行情绪分段时：

   a. 分析文本 — 识别不同的情绪片段（例如：兴奋 → 担忧 → 坚定 → 感激）。

   b. 拆分片段 — 在自然的情绪边界处拆分文本（句子或分句级别）。

   c. 为每个片段添加标签，使用以下情绪选项中合适的 instruct：

   • 喜悦/兴奋： "excited, enthusiastic, joyful tone"、"ecstatic, breathless with joy"
   • 愤怒： "angry, furious, intense tone"、"irritated, sharp and impatient"
   • 悲伤/哀痛： "sorrowful, heartbroken, tearful voice"、"melancholic, quiet and reflective"
   • 恐惧/惊慌： "panicked, terrified, desperate tone"、"anxious, nervous, trembling voice"
   • 平静/中性： "calm, steady, composed delivery"、"warm and reassuring tone"
   • 惊讶： "shocked, astonished, wide-eyed disbelief"
   • 坚定： "determined, resolute, firm and confident"
   • 温柔： "gentle, tender, soft-spoken with warmth"

   d. 生成对话脚本 — 关键：每一行都使用同一个音色配置。

   **这不是多说话人的对话。**情绪分段表示由一个人以不同情绪说话。脚本中的每个 "profile" 值都必须相同 — 即用户选择的音色配置（或默认音色配置）。只有 "instruct" 字段会因行而异。不要为不同片段指定不同的音色配置。

   {
     "title": "emotional_speech",
     "gap": 0.15,
     "lines": [
       {"profile": "Dylan", "text": "Segment 1 text...", "instruct": "excited, enthusiastic tone"},
       {"profile": "Dylan", "text": "Segment 2 text...", "instruct": "worried, anxious, trembling voice"},
       {"profile": "Dylan", "text": "Segment 3 text...", "instruct": "determined, resolute, firm tone"},
       {"profile": "Dylan", "text": "Segment 4 text...", "instruct": "gentle, grateful, warm and tender"}
     ]
   }
   

   注意：上面的四行都使用 "Dylan" — 即同一个音色配置。这是有意为之，也是必须遵守的要求。

   e. 使用对话命令，而不是单次生成：

   uv run $SKILL_DIR/scripts/voicebox.py conversation /tmp/emotional_script.json --play --gap 0.15
   

   重要 — 情绪分段与多说话人：

   • **情绪分段（本节）：**仅限主动请求。一个声音，情绪各异。每一行使用相同的音色配置。
   • **多说话人对话（模式 6）：**多个声音，每行使用不同的音色配置。仅当用户要求对话、对白或戏剧效果时使用。
   • **长文本的默认处理方式：**调用一次 generate。不分段，不拆分。

4. 简单生成（短文本或不需要情绪）：

   uv run $SKILL_DIR/scripts/voicebox.py generate "Profile Name" "text to speak" --play
   

   使用风格覆盖（带情绪的短文本）：

   uv run $SKILL_DIR/scripts/voicebox.py generate "Profile Name" "text to speak" --instruct "angry tone" --play
   

   对克隆声音使用高质量模式（1.7B 模型）：

   uv run $SKILL_DIR/scripts/voicebox.py generate "Profile Name" "text to speak" --quality high --play
   

   **重要：**使用 300000ms 的超时 — 首次运行时，加载模型并完成生成需要一些时间。

5. 报告结果 — 告知用户音频已生成并播放。显示时长和使用的音色配置。

如果没有音色配置

提出使用模式 2 创建一个。

---

模式 2：根据描述创建语音档案（设计）

当用户说“创建一个……语音档案”时：

1. 解析语音描述，从用户的请求中提取信息。

2. 构建丰富的语音描述——将用户简短的描述扩展为详细的多维语音提示词：

   • 模板：[年龄] [性别]，具有 [音高]、[特征] 的嗓音，语速 [快慢]，[情绪/语气]，适合用于 [使用场景]
   • 示例：“平静的旁白”→“平静的中年男性旁白，嗓音低沉温暖，语速缓慢而沉稳，语气舒缓且值得信赖，适合有声书旁白”
   • 描述要具体：使用“低沉”“清晰”“语速快”等词，不要使用“不错”这类含糊的词语

3. 选择符合语音情绪的示例文本：

   • 中性：“晨曦轻柔地洒在宁静的村庄上，为鹅卵石街道镀上金色的光芒。鸟儿唱起晨曲，世界也慢慢苏醒。”
   • 愤怒：“我已经告诉过你一百次不要那样做了。这完全不可接受，我再也不会容忍下去了。”
   • 欢快：“大家好，欢迎回来！今天有一些超棒的消息要和大家分享，我已经迫不及待想开始了！”

4. 创建档案：

   uv run $SKILL_DIR/scripts/voicebox.py create-designed "Calm Narrator" \
     --desc "Calm middle-aged male narrator with a deep warm baritone voice, slow measured pace, soothing and trustworthy tone, suitable for audiobook narration" \
     --lang en
   

   重要：使用 300000ms 超时。

5. 确认——告知用户档案已创建，可以开始使用。

档案命名约定

• 根据用户的描述命名，并采用标题式大小写：“平静的旁白”“愤怒的女性”
• 名称要简短（2-3 个词）

---

模式 2b：根据预设说话人创建语音档案（自定义）

当用户想使用高级预设语音（无需描述或音频）时：

1. 如果用户尚未选择，请显示可用的说话人：

   • 中文： serena, vivian, uncle_fu, dylan, eric
   • 英语： ryan, aiden
   • 日语： ono_anna
   • 韩语： sohee

2. 创建档案：

   uv run $SKILL_DIR/scripts/voicebox.py create-custom "Profile Name" <speaker>
   

   根据说话人自动检测语言。可使用 --desc 设置标签。

3. 使用风格覆盖生成——自定义档案支持使用 --instruct 指定情绪/风格：

   uv run voicebox.py generate "Profile Name" "text" --instruct "angry tone" --play
   

何时使用自定义、设计或克隆模式

• 自定义——快速设置，使用稳定的高品质预设语音，并支持风格指令
• 设计——创意不受限，可描述你想要的任何语音
• 克隆——根据音频复现特定真实人物的语音

---

模式 3：根据音频文件创建语音档案（克隆）

当用户说“从 /path/to/file.wav 克隆我的语音”，或提供音频文件时：

1. 获取音频文件路径以及录音内容的文字转录。

2. 如果未提供转录文本，使用内置转录功能自动转录：

   uv run $SKILL_DIR/scripts/transcribe.py /path/to/audio.wav
   

   最后再考虑询问用户。

3. 创建档案：

   uv run $SKILL_DIR/scripts/voicebox.py create-cloned "My Voice" \
     --audio /path/to/sample.wav \
     --ref-text "transcript of what was said" \
     --lang en
   

4. 确认——告知用户档案已创建。

---

模式 4：通过麦克风录音并克隆（重要）

当用户说“克隆我的语音”“录下我的语音”“我想克隆一种语音”，或提出任何未提供音频文件的克隆请求时，启用此模式。

分步工作流

1. 询问用户想要的配置文件名称（或者根据名称生成一个，例如“My Voice”或“[User's Name]'s Voice”）。

2. 询问用户想说什么，或者推荐一句合适的示例句：

   • “清晨的阳光温柔地洒在宁静的村庄上，为鹅卵石街道镀上一层金色的光。”
   • 也可以让用户随意说——清晰说话 5-15 秒效果最佳。

3. 确认用户已准备就绪，然后用一条命令录制并自动克隆：

   uv run $SKILL_DIR/scripts/voicebox.py record "My Voice" --duration 10 --lang en
   

   • 默认时长为 10 秒。用户想录得更久或更短时，可使用 --duration 调整。
   • 如果用户已知道要说什么，可以传入：--ref-text "what they said"（跳过转录）
   • 不使用 --ref-text 时，命令会通过内置的 transcribe.py（Qwen3-ASR）自动转录——无需外部技能！
   • 重要：使用 300000ms 的超时时间。

4. 播放录音，让用户确认：

   afplay $SKILL_DIR/data/samples/<slug>.wav
   

5. 确认——告知用户配置文件已创建，可以通过 /voicebox "My Voice" "text to speak" 使用。

要求

• 必须安装 ffmpeg（brew install ffmpeg）
• 必须向终端应用授予 macOS 麦克风权限

---

模式 5：转录音频/视频

当用户说“转录这个”“转录音频/视频”、提供用于转录的音频/视频文件，或提出任何语音转文本请求时，将启用此模式。

分步工作流

1. 从用户的请求中获取文件路径。

2. 运行转录：

   uv run $SKILL_DIR/scripts/transcribe.py /path/to/file.wav
   

   可选语言：

   uv run $SKILL_DIR/scripts/transcribe.py /path/to/file.wav --language zh
   

   重要：使用 300000ms 的超时时间。

3. 将转录文本返回给用户。

支持的格式

• 音频： wav、mp3、flac、m4a、ogg、aac、wma
• 视频： mp4、mkv、mov、avi、webm、m4v、flv、wmv（ffmpeg 会自动提取音频）

支持的语言

支持 52 种语言并可自动检测，包括：英语、中文（含方言）、日语、韩语、德语、法语、西班牙语、意大利语、葡萄牙语、俄语、阿拉伯语、印地语、泰语、越南语、印度尼西亚语等。

---

模式 6：生成对话/有声书/戏剧

当用户要求生成多说话人对话、对白、戏剧、包含多个角色的有声书、新闻播报，或任何由多个语音配置文件依次发言的内容时，将启用此模式。

分步工作流

1. 根据用户的请求创建 JSON 脚本文件。脚本格式如下：

   {
     "title": "Evening News",
     "gap": 0.25,
     "lines": [
       {"profile": "News Anchor", "text": "Good evening and welcome to the six o'clock news."},
       {"profile": "Cheerful Girl", "text": "Thanks, Tom! I'm here live at the scene.", "instruct": "excited field reporting tone"},
       {"profile": "Aiden", "text": "Well, this is actually quite common in my experience."}
     ]
   }
   

   脚本字段：

   • title — 输出目录和合并后文件的名称
   • gap — 片段之间的静音时长，以秒为单位（默认：0.25）
   • lines — 对白行数组，每行包含：
     • profile — 现有语音配置文件的名称（必须完全匹配或部分匹配）
     • text — 要朗读的文本
     • instruct —（可选）“designed”和“custom”配置文件的风格/情绪覆盖设置

2. 将脚本保存到临时文件：

   cat > /tmp/my_script.json << 'EOF'
   { ... }
   EOF
   

3. 检查所需的配置文件是否存在——先运行 list。如果缺少配置文件，请先使用模式 2 或模式 3 创建。

4. 运行对话命令：

   uv run $SKILL_DIR/scripts/voicebox.py conversation /tmp/my_script.json --play
   

   重要：使用 300000ms 的超时时间——多片段生成可能需要几分钟。

   选项：

   • --output-dir DIR / -o DIR — 保存片段和合并文件的位置（默认：/tmp/voicebox_{title_slug}）
   • --gap 0.5 — 覆盖片段之间的间隔（覆盖脚本中的值）
   • --quality high — 使用 1.7B 模型以获得更好的质量
   • --trim-silence（默认）/ --no-trim-silence — 使用 ffmpeg 修剪每个片段中的静音
   • --play / --no-play — 完成后播放合并结果

5. 报告结果——显示脚本输出中的各片段时长和合并后的总时长。

如何编写优秀的对话脚本

• 保持行文简短 — 每行 1-3 句话效果最好。将冗长的独白拆分成多行。
• 使用 instruct 表达情绪 — 对于设计型音色配置，可添加 "instruct": "excited tone" 或 "instruct": "whispering"，按行覆盖默认的音色描述。
• 混合音色配置类型 — 可以在同一个脚本中自由混用设计型和克隆型音色配置。
• 调整间隔 — 快速对话使用 0.15-0.25s，戏剧性停顿使用 0.4-0.6s，场景切换使用 0.8-1.0s。

示例：新闻播报

{
  "title": "Evening News",
  "gap": 0.3,
  "lines": [
    {"profile": "News Anchor", "text": "Good evening. Tonight's top story: a breakthrough in renewable energy."},
    {"profile": "Cheerful Girl", "text": "Thanks, Tom! I'm here at the research lab where scientists made the announcement earlier today.", "instruct": "excited field reporting tone"},
    {"profile": "Aiden", "text": "This discovery could fundamentally change how we think about solar power. The efficiency gains are remarkable."},
    {"profile": "News Anchor", "text": "Fascinating. We'll have more on this story after the break."}
  ]
}

要求

• 使用 --trim-silence 时（默认开启）必须安装 ffmpeg。如果无法使用 ffmpeg，请使用 --no-trim-silence。
• 脚本中引用的所有音色配置必须已存在。

---

脚本命令参考

# List all profiles
uv run $SKILL_DIR/scripts/voicebox.py list

# List available models and quality tiers
uv run $SKILL_DIR/scripts/voicebox.py models

# Create designed voice profile
uv run $SKILL_DIR/scripts/voicebox.py create-designed "Name" --desc "description" --lang en

# Create custom voice profile (preset speaker)
uv run $SKILL_DIR/scripts/voicebox.py create-custom "Name" <speaker>

# List available preset speakers
uv run $SKILL_DIR/scripts/voicebox.py speakers

# Create cloned voice profile (from existing audio file)
uv run $SKILL_DIR/scripts/voicebox.py create-cloned "Name" --audio /path/to.wav --ref-text "transcript" --lang en

# Record from microphone and clone (with known transcript)
uv run $SKILL_DIR/scripts/voicebox.py record "Name" --duration 10 --lang en --ref-text "what I said"

# Record from microphone and clone (auto-transcribe, high quality ASR)
uv run $SKILL_DIR/scripts/voicebox.py record "Name" --duration 10 --lang en --quality high

# Transcribe an audio file (built-in, no external skill needed)
uv run $SKILL_DIR/scripts/transcribe.py /path/to/audio.wav

# Transcribe with high quality ASR (1.7B model)
uv run $SKILL_DIR/scripts/transcribe.py /path/to/audio.wav --model Qwen/Qwen3-ASR-1.7B

# Generate speech
uv run $SKILL_DIR/scripts/voicebox.py generate "Name" "text" --play

# Generate with high quality (1.7B clone model)
uv run $SKILL_DIR/scripts/voicebox.py generate "Name" "text" --play --quality high

# Generate with style override
uv run $SKILL_DIR/scripts/voicebox.py generate "Name" "text" --instruct "angry" --play

# Generate a multi-speaker conversation from JSON script
uv run $SKILL_DIR/scripts/voicebox.py conversation /tmp/script.json --play

# Conversation with custom gap and no silence trimming
uv run $SKILL_DIR/scripts/voicebox.py conversation /tmp/script.json --gap 0.5 --no-trim-silence -o /tmp/my_show

# Conversation with high quality models
uv run $SKILL_DIR/scripts/voicebox.py conversation /tmp/script.json --quality high --play

# Delete a profile
uv run $SKILL_DIR/scripts/voicebox.py delete "Name"

质量档位

所有 TTS 和录音命令默认使用 --quality high（1.7B）。若需使用更快的 0.6B 模型，请使用 --quality standard：

档位	克隆模型	ASR 模型	所需 RAM	速度
high（默认）	1.7B (~3.5GB)	1.7B (~3.5GB)	~8GB+	质量更好
standard	0.6B (~1.5GB)	0.6B (~1.5GB)	~4GB+	速度更快，所需 RAM 更少

语音设计始终使用 1.7B（仅此一种规格）。

当用户要求“更快”或“更轻量”时，请使用 --quality standard。

音色描述指南

快速规则

1. 描述具体 — 使用“低沉”“清晰”“节奏快”，而不是“好听”或“不错”
2. 多维描述 — 结合性别 + 年龄 + 情绪 + 说话风格
3. 客观描述 — 描述音色特征，而非个人偏好
4. 保持原创 — 切勿要求模仿名人
5. 简洁明了 — 每个词都应有意义

优秀示例

"Calm middle-aged male with deep magnetic voice, medium pace, warm and trustworthy"
"Young adult female with crisp energetic tone, fast pace, cheerful and engaging"
"Senior male narrator with slow rich baritone, composed delivery, for audiobook"
"Angry adult female with sharp intense voice, fast aggressive pace, furious and commanding"

支持的语言

英语（en）、中文（zh）、日语（ja）、韩语（ko）、德语（de）、法语（fr）、俄语（ru）、葡萄牙语（pt）、西班牙语（es）、意大利语（it）。默认语言为英语。

错误处理

错误	操作
没有匹配的音色配置	显示可用的音色配置，并询问是否创建
不存在音色配置	提供使用模式 2 创建的选项
模型尚未下载	通知用户，模型会在首次使用时自动下载（约 3GB）
生成失败	显示错误消息，并检查是否已安装 mlx-audio
沙盒无法访问 uv	使用带有 general-purpose 子 Agent 的 Task 工具

首次下载

首次使用时，模型会从 HuggingFace 下载（1.7B 模型每个约 3.5GB）。脚本会自动检测并打印：

First-time setup: downloading <model> (~3.5GB)...
This is a one-time download — future runs will be instant.

致 Claude 的重要提示：首次运行任何 voicebox 命令时（或清除 HF 缓存后），请提醒用户首次运行下载模型需要几分钟。所有生成、录音和转录命令的超时时间均设为 300000ms（5 分钟）。后续运行会从缓存加载，速度会快很多。

实现说明

• 音频输出为 WAV 格式，采样率为 24000 Hz
• 模型缓存在 ~/.cache/huggingface/hub/
• mlx-audio 软件包会在首次运行时通过 uv 自动安装
• 如果 Bash 沙盒阻止访问 ~/.claude/skills/，请使用 general-purpose 子 Agent 类型的 Task 工具，该工具会启动一个全新的 shell
• 播放后清理临时文件：rm -f /tmp/voicebox_output.wav