Back to Details

tts

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

TTS (Text-to-Speech) - Complete API Reference

TTS（文本转语音）- 完整API参考

Convert text to natural-sounding speech using ElevenLabs, macOS say, or espeak.
使用ElevenLabs、macOS say或espeak将文本转换为自然语音。

Chat Commands

聊天命令

Synthesize Speech

合成语音

/speak "Your order has been filled"         Speak text aloud
/speak "Market alert" --voice rachel        Use specific voice
/speak "Portfolio up 5%" --speed 1.2        Adjust speed
/speak "Your order has been filled"         朗读文本
/speak "Market alert" --voice rachel        使用指定语音
/speak "Portfolio up 5%" --speed 1.2        调整语速

Voice Management

语音管理

/voices                                     List available voices
/voices preview rachel                      Preview a voice
/voice set rachel                           Set default voice
/voices                                     列出可用语音
/voices preview rachel                      预览语音
/voice set rachel                           设置默认语音

Settings

设置

/tts status                                 Check TTS status
/tts provider elevenlabs                    Set provider
/tts speed 1.0                              Set default speed
/tts volume 0.8                             Set volume (0-1)
/tts status                                 查看TTS状态
/tts provider elevenlabs                    设置服务提供商
/tts speed 1.0                              设置默认语速
/tts volume 0.8                             设置音量（0-1）

TypeScript API Reference

TypeScript API参考

Create TTS Service

创建TTS服务

typescript
import { createTTSService } from 'clodds/tts';

const tts = createTTSService({
  provider: 'elevenlabs',
  apiKey: process.env.ELEVENLABS_API_KEY,

  // Defaults
  defaultVoice: 'rachel',
  defaultSpeed: 1.0,
  defaultPitch: 1.0,
});
typescript
import { createTTSService } from 'clodds/tts';

const tts = createTTSService({
  provider: 'elevenlabs',
  apiKey: process.env.ELEVENLABS_API_KEY,

  // 默认配置
  defaultVoice: 'rachel',
  defaultSpeed: 1.0,
  defaultPitch: 1.0,
});

Synthesize Speech

合成语音

typescript
// Basic synthesis
const audio = await tts.synthesize('Hello, your trade was executed.');

// Play immediately
await tts.speak('Portfolio value is $10,000');

// With options
await tts.speak('Market alert: BTC crossed $100k', {
  voice: 'josh',
  speed: 1.2,
  pitch: 1.0,
  volume: 0.8,
});
typescript
// 基础合成
const audio = await tts.synthesize('Hello, your trade was executed.');

// 立即播放
await tts.speak('Portfolio value is $10,000');

// 带选项配置
await tts.speak('Market alert: BTC crossed $100k', {
  voice: 'josh',
  speed: 1.2,
  pitch: 1.0,
  volume: 0.8,
});

Streaming Synthesis

流式合成

typescript
// Stream for long text (lower latency)
const stream = await tts.streamSynthesize(longText, {
  voice: 'rachel',
});

stream.on('data', (chunk) => {
  // Play audio chunks as they arrive
  audioPlayer.write(chunk);
});

stream.on('end', () => {
  console.log('Synthesis complete');
});
typescript
// 长文本流式合成（更低延迟）
const stream = await tts.streamSynthesize(longText, {
  voice: 'rachel',
});

stream.on('data', (chunk) => {
  // 收到音频片段后立即播放
  audioPlayer.write(chunk);
});

stream.on('end', () => {
  console.log('合成完成');
});

List Voices

列出语音

typescript
// Get available voices
const voices = await tts.listVoices();

for (const voice of voices) {
  console.log(`${voice.id}: ${voice.name}`);
  console.log(`  Gender: ${voice.gender}`);
  console.log(`  Accent: ${voice.accent}`);
  console.log(`  Use case: ${voice.useCase}`);
}
typescript
// 获取可用语音
const voices = await tts.listVoices();

for (const voice of voices) {
  console.log(`${voice.id}: ${voice.name}`);
  console.log(`  性别: ${voice.gender}`);
  console.log(`  口音: ${voice.accent}`);
  console.log(`  适用场景: ${voice.useCase}`);
}

Voice Preview

语音预览

typescript
// Preview a voice
await tts.preview('rachel', 'This is a preview of the Rachel voice.');
typescript
// 预览语音
await tts.preview('rachel', 'This is a preview of the Rachel voice.');

Queue Management

队列管理

typescript
// Queue multiple messages
tts.queue('First message');
tts.queue('Second message');
tts.queue('Third message');

// Messages play in order

// Clear queue
tts.clearQueue();

// Skip current
tts.skip();
typescript
// 加入多条消息到队列
tts.queue('First message');
tts.queue('Second message');
tts.queue('Third message');

// 消息将按顺序播放

// 清空队列
tts.clearQueue();

// 跳过当前播放
tts.skip();

ElevenLabs Voices

ElevenLabs语音列表

Voice IDNameGenderAccentBest For
rachel
RachelFAmericanNarration
domi
DomiFAmericanConversational
bella
BellaFAmericanSoft, gentle
antoni
AntoniMAmericanNarration
josh
JoshMAmericanDeep, authoritative
arnold
ArnoldMAmericanGruff, character
adam
AdamMAmericanDeep, narration
sam
SamMAmericanRaspy, character
语音ID名称性别口音最佳适用场景
rachel
Rachel女美式旁白
domi
Domi女美式对话
bella
Bella女美式柔和、温婉
antoni
Antoni男美式旁白
josh
Josh男美式低沉、权威
arnold
Arnold男美式粗犷、角色配音
adam
Adam男美式低沉、旁白
sam
Sam男美式沙哑、角色配音

Providers

服务提供商

ProviderQualityLatencyCostSetup
ElevenLabsPremium~500ms$5/100k charsAPI key
say (macOS)Good~100msFreeBuilt-in
espeakBasic~50msFreeInstall
提供商音质延迟成本配置要求
ElevenLabs顶级~500ms5美元/10万字符API密钥
say（macOS）良好~100ms免费内置
espeak基础~50ms免费需安装

Provider Configuration

提供商配置

typescript
// ElevenLabs (best quality)
const tts = createTTSService({
  provider: 'elevenlabs',
  apiKey: process.env.ELEVENLABS_API_KEY,
});

// macOS say (free, local)
const tts = createTTSService({
  provider: 'say',
  defaultVoice: 'Samantha',  // macOS voice
});

// espeak (cross-platform, free)
const tts = createTTSService({
  provider: 'espeak',
  defaultVoice: 'en-us',
});
typescript
// ElevenLabs（最佳音质）
const tts = createTTSService({
  provider: 'elevenlabs',
  apiKey: process.env.ELEVENLABS_API_KEY,
});

// macOS say（免费、本地）
const tts = createTTSService({
  provider: 'say',
  defaultVoice: 'Samantha',  // macOS内置语音
});

// espeak（跨平台、免费）
const tts = createTTSService({
  provider: 'espeak',
  defaultVoice: 'en-us',
});

Audio Output

音频输出

typescript
// Set output device
tts.setOutputDevice('Built-in Speakers');

// Get available devices
const devices = await tts.listOutputDevices();
typescript
// 设置输出设备
tts.setOutputDevice('Built-in Speakers');

// 获取可用设备
const devices = await tts.listOutputDevices();

SSML Support (ElevenLabs)

SSML支持（ElevenLabs）

typescript
// Use SSML for advanced control
await tts.speak(`
  <speak>
    <prosody rate="slow">Important alert:</prosody>
    <break time="500ms"/>
    Your stop loss was triggered.
  </speak>
`, { ssml: true });
typescript
// 使用SSML进行高级控制
await tts.speak(`
  <speak>
    <prosody rate="slow">重要提醒：</prosody>
    <break time="500ms"/>
    您的止损已触发。
  </speak>
`, { ssml: true });

Best Practices

最佳实践

  1. Use streaming — For long text, reduces time to first audio
  2. Cache common phrases — "Order filled", "Alert triggered"
  3. Adjust speed — Faster for alerts, slower for details
  4. Queue management — Don't overlap important messages
  5. Fallback provider — Use say/espeak if ElevenLabs unavailable
  1. 使用流式合成 — 处理长文本时，减少首段音频等待时间
  2. 缓存常用语句 — 如“订单已完成”、“触发提醒”
  3. 调整语速 — 提醒类内容用较快语速，详情类用较慢语速
  4. 队列管理 — 避免重要消息重叠播放
  5. 备用提供商 — 若ElevenLabs不可用，使用say/espeak作为 fallback