Fabric 项目 Gemini TTS 音色样本指南：从 6 个示例 WAV 到 30+ 音色的选型与实践

本文基于 Fabric 仓库中 docs/voices/README.md 展开，系统讲解该项目内置的 Gemini TTS（文本转语音）音色样本集：每个样本文件对应一种音色、统一使用同一句测试文本录制，用于直观对比音色质感。读完本文，你将掌握音色样本的生成命令、WAV 输出规格（24kHz / 16-bit / Mono）的底层实现依据，以及如何借助 --voice 与 --list-gemini-voices 在 Fabric 的管道式工作流中完成语音合成。

一、音色样本目录是什么

docs/voices/ 目录是 Fabric 为演示 Gemini TTS 能力而存放的音频样例集合。每个 .wav 文件均由 Fabric 的 TTS 命令行功能直接生成，统一朗读同一句英文测试句：

The quick brown fox jumped over the lazy dog

使用同一句文本录制所有样本，是为了让听者在完全一致的发音内容下，仅凭声音特质对比不同音色的差异，从而在正式使用前完成"试听选型"。

目录内置 6 个代表性音色样本，覆盖了从沉稳到轻快、从温暖到富有表现力的不同风格：

样本文件	音色名称	音色特征	适合场景（示例）
Kore.wav	Kore	Firm and confident（坚定自信），默认音色	默认播报、正式声明类内容
Charon.wav	Charon	Informative and clear（信息清晰）	教程讲解、知识科普
Vega.wav	Vega	Smooth and pleasant（顺滑悦耳）	通用旁白、品牌宣传
Capella.wav	Capella	Warm and welcoming（温暖亲切）	欢迎语、客服播报
Achird.wav	Achird	Friendly and approachable（友好亲和）	社区互动、日常助手
Lyra.wav	Lyra	Melodic and expressive（旋律感强、富有表现力）	故事朗读、有声内容

关于音色特征的精确来源：仓库源码 internal/plugins/ai/gemini/voices.go 中以 GeminiVoice 结构体维护了官方音色清单，每条记录包含 Name、Description 与 Characteristics，本文表格中的特征描述即取自该清单，与官方 Gemini 文档保持一致。

二、重新生成这些样本：逐条命令实战

样本文件并非手工录制，而是由 Fabric 的 CLI 直接调用 Gemini TTS 模型生成。原文档给出了完整的生成命令，每一条都以 echo 向 fabric 管道输入文本，再通过 -m 指定 TTS 模型、--voice 选择音色、-o 指定输出文件：

# Generate each voice sample
echo "The quick brown fox jumped over the lazy dog" | fabric -m gemini-2.5-flash-preview-tts --voice Kore -o docs/voices/Kore.wav
echo "The quick brown fox jumped over the lazy dog" | fabric -m gemini-2.5-flash-preview-tts --voice Charon -o docs/voices/Charon.wav
echo "The quick brown fox jumped over the lazy dog" | fabric -m gemini-2.5-flash-preview-tts --voice Vega -o docs/voices/Vega.wav
echo "The quick brown fox jumped over the lazy dog" | fabric -m gemini-2.5-flash-preview-tts --voice Capella -o docs/voices/Capella.wav
echo "The quick brown fox jumped over the lazy dog" | fabric -m gemini-2.5-flash-preview-tts --voice Achird -o docs/voices/Achird.wav
echo "The quick brown fox jumped over the lazy dog" | fabric -m gemini-2.5-flash-preview-tts --voice Lyra -o docs/voices/Lyra.wav

对上述命令逐项拆解：

• -m gemini-2.5-flash-preview-tts：指定具备 TTS 能力的 Gemini 模型。源码 internal/plugins/ai/gemini/gemini.go 中 isTTSModel 通过检测模型名是否包含 tts、preview-tts 或 text-to-speech 来判断是否走语音合成分支；
• --voice <name>：选择音色。该参数定义于 internal/cli/flags.go，默认值为 Kore，即在省略该参数时自动使用默认音色（见 gemini.go）；
• -o docs/voices/Kore.wav：TTS 模型的必填参数。源码在调用前会校验：若模型为 TTS 类型而未指定输出文件，直接返回 tts_model_requires_audio_output 错误（gemini.go）。

如果只是想快速验证某个音色，不必逐条手写 6 条命令，可随时换用其他文本：

echo "Welcome to Fabric" | fabric -m gemini-2.5-flash-preview-tts --voice Capella -o welcome.wav

三、输出音频格式：24kHz / 16-bit / Mono 从何而来

原文档明确了样本的音频规格：

• 格式：WAV（无压缩 PCM）
• 采样率：24kHz
• 位深：16-bit
• 声道：单声道（Mono）
• 单样本体积：约 500KB

这些数值并非凭空设定，而是 Fabric 在本地为 Gemini 返回的 PCM 原始音频补写 WAV 头部时采用的固定规格，定义于 gemini.go：

DefaultChannels      = 1      // 单声道
DefaultSampleRate    = 24000  // 24kHz
DefaultBitsPerSample = 16     // 16-bit
WAVHeaderSize        = 44     // 标准 WAV 头长度
RIFFHeaderSize       = 36
MaxAudioDataSize     = 100 * 1024 * 1024 // 100MB 安全上限
MinAudioDataSize     = 44
AudioDataPrefix      = "FABRIC_AUDIO_DATA:"

在 generateWAVFile 中，Fabric 会按上述常量计算 byteRate = sampleRate × channels × bitsPerSample / 8 与 blockAlign，随后依次写入 RIFF/WAVE 头、fmt 块（音频格式为 PCM、声道数、采样率、位深）与 data 块，最终拼装出标准的 44 字节 WAV 头。整个过程对调用方透明：CLI 通过 AudioDataPrefix 前缀识别并剥离音频数据，把 -o 指定的文件落盘。

由此可以推断：约 500KB 的体积是"约 2.5 秒朗读时长 × 24kHz × 16bit ÷ 8"的自然结果，属于中等时长短文本的典型体积；朗读内容越长，文件随之线性增大（受 100MB 上限保护）。

四、不止 6 个：音色清单的完整视野

目录里的 6 个样本只是精选代表。Fabric 在 voices.go 中维护了 30+ 个音色，按"Firm（沉稳）、Upbeat（明快）、Bright（明亮）、Informative（信息型）、Natural（自然）、Gentle（温和）、Warm（温暖）、Clear（清晰）、Pleasant（悦耳）、Textured（质感）、Relaxed（放松）、Mature（成熟）、Expressive（表现力）、Dynamic（活力）、Friendly（友好）、Casual（随意）"等风格分组，例如：

• 沉稳系：Kore（默认）、Orus、Alnilam
• 明快系：Puck、Laomedeia
• 信息型：Charon、Rasalgethi
• 温暖系：Capella、Sulafat
• 表现力：Lyra、Pulcherrima
• 实验音色：Sadaltager、Schedar、Umbriel（注释标明为实验性音色）

需要全部名单时，无需翻阅文档，直接在终端查询：

# 按风格分组列出全部音色及描述（Kore 会标注 default）
fabric --list-gemini-voices

# 仅输出音色名（用于 shell 补全脚本消费）
fabric --list-gemini-voices --shell-complete-list

该命令由 internal/cli/listing.go 调用 gemini.ListGeminiVoices 实现；--shell-complete-list 模式只输出纯名字列表，正是为 shell 补全场景设计的。在交互式补全中，completions/ 目录下的 _fabric、fabric.bash、fabric.fish 等补全脚本会消费 voice 参数，详见 Shell-Completions 文档。

五、在 Fabric 管道中组合使用 TTS

TTS 只是 Fabric 处理链路的一个环节，可以与模式（pattern）自由组合。例如先对输入文本执行 summarize 模式，再把摘要直接转成语音：

fabric -p summarize --voice Puck -m gemini-2.5-flash-preview-tts -o summary.wav < document.txt

其中 -p summarize 复用 data/patterns/ 下的现成提示词模板完成文本处理，--voice Puck 选择轻快音色，最终产出 summary.wav。这种"处理 → 语音"的两段式管道，是 TTS 在 Fabric 中最典型的落地方式。

六、配置默认音色与其他注意事项

通过配置文件固定默认音色

如果大部分场景都使用同一音色，可在 Fabric 配置文件中设置默认值，避免每次敲 --voice：

voice: "Charon"  # Set your preferred default voice

配置项与 CLI 标志同源，均映射到 flags.go 中定义的 Voice 字段（默认 Kore），命令行参数优先级高于配置文件。

常见报错与处理

• TTS model requires audio output：使用了 TTS 模型但漏掉 -o。补上 -o filename.wav 即可；
• Invalid voice 'X'：音色名拼写有误或不在支持清单内。可用 fabric --list-gemini-voices 核对名称；源码中 IsValidGeminiVoice（voices.go）会在发起 API 调用前校验音色名，拼写错误会直接报错而不浪费配额；
• HTTP 429 配额超限：Google 免费层对 TTS 模型通常有每日请求上限。Fabric 侧可等待配额重置或升级付费套餐；更多限流说明见 Gemini-TTS 指南；
• 前置条件：需要有效的 Gemini API Key，且模型名包含 tts、preview-tts 或 text-to-speech 字样才会走语音合成分支（见 gemini.go）。

获取帮助

fabric --help

七、延伸阅读

• Gemini TTS 完整使用指南：覆盖基本用法、限流说明、YAML 配置与故障排查的完整文档；
• 音色清单源码实现：查看全部 30+ 音色的名称、描述与特征分组；
• TTS 生成与 WAV 封装实现：了解模型识别、音色校验、PrebuiltVoiceConfig 调用与 WAV 头部生成的完整链路；
• CLI 标志定义：--voice 与 --list-gemini-voices 的参数定义与默认值。