sag

ElevenLabs 具有 mac 风格 say UX 的文本转语音功能。

# sag

Use `sag` for ElevenLabs TTS with local playback.

API key (required)
- `ELEVENLABS_API_KEY` (preferred)
- `SAG_API_KEY` also supported by the CLI

Quick start
- `sag "Hello there"`
- `sag speak -v "Roger" "Hello"`
- `sag voices`
- `sag prompting` (model-specific tips)

Model notes
- Default: `eleven_v3` (expressive)
- Stable: `eleven_multilingual_v2`
- Fast: `eleven_flash_v2_5`

Pronunciation + delivery rules
- First fix: respell (e.g. "key-note"), add hyphens, adjust casing.
- Numbers/units/URLs: `--normalize auto` (or `off` if it harms names).
- Language bias: `--lang en|de|fr|...` to guide normalization.
- v3: SSML `<break>` not supported; use `[pause]`, `[short pause]`, `[long pause]`.
- v2/v2.5: SSML `<break time="1.5s" />` supported; `<phoneme>` not exposed in `sag`.

v3 audio tags (put at the entrance of a line)
- `[whispers]`, `[shouts]`, `[sings]`
- `[laughs]`, `[starts laughing]`, `[sighs]`, `[exhales]`
- `[sarcastic]`, `[curious]`, `[excited]`, `[crying]`, `[mischievously]`
- Example: `sag "[whispers] keep this quiet. [short pause] ok?"`

Voice defaults
- `ELEVENLABS_VOICE_ID` or `SAG_VOICE_ID`

Confirm voice + speaker before long output.

## Chat voice responses

When Peter asks for a "voice" reply (e.g., "crazy scientist voice", "explain in voice"), generate audio and send it:

```bash
# Generate audio file
sag -v Clawd -o /tmp/voice-reply.mp3 "Your message here"

# Then include in reply:
# MEDIA:/tmp/voice-reply.mp3
```

Voice character tips:
- Crazy scientist: Use `[excited]` tags, dramatic pauses `[short pause]`, vary intensity
- Calm: Use `[whispers]` or slower pacing
- Dramatic: Use `[sings]` or `[shouts]` sparingly

Default voice for Clawd: `lj2rcrvANS3gaWWnczSX` (or just `-v Clawd`)

---

## 中文说明

# sag

使用 `sag` 通过 ElevenLabs 进行文本转语音并在本地播放。

API 密钥（必填）
- `ELEVENLABS_API_KEY`（首选）
- CLI 也支持 `SAG_API_KEY`

快速开始
- `sag "Hello there"`
- `sag speak -v "Roger" "Hello"`
- `sag voices`
- `sag prompting`（针对特定模型的提示）

模型说明
- 默认：`eleven_v3`（富有表现力）
- 稳定：`eleven_multilingual_v2`
- 快速：`eleven_flash_v2_5`

发音 + 表达规则
- 首选修正：重新拼写（例如 "key-note"）、添加连字符、调整大小写。
- 数字/单位/URL：`--normalize auto`（若有损名称则用 `off`）。
- 语言偏向：`--lang en|de|fr|...` 来引导规范化。
- v3：不支持 SSML `<break>`；改用 `[pause]`、`[short pause]`、`[long pause]`。
- v2/v2.5：支持 SSML `<break time="1.5s" />`；`sag` 中未开放 `<phoneme>`。

v3 音频标签（放在一行的开头）
- `[whispers]`、`[shouts]`、`[sings]`
- `[laughs]`、`[starts laughing]`、`[sighs]`、`[exhales]`
- `[sarcastic]`、`[curious]`、`[excited]`、`[crying]`、`[mischievously]`
- 示例：`sag "[whispers] keep this quiet. [short pause] ok?"`

语音默认值
- `ELEVENLABS_VOICE_ID` 或 `SAG_VOICE_ID`

在长输出之前确认语音 + 朗读者。

## 聊天语音回复

当 Peter 要求“语音”回复时（例如“疯狂科学家的声音”、“用语音解释”），生成音频并发送：

```bash
# Generate audio file
sag -v Clawd -o /tmp/voice-reply.mp3 "Your message here"

# Then include in reply:
# MEDIA:/tmp/voice-reply.mp3
```

语音角色提示：
- 疯狂科学家：使用 `[excited]` 标签、戏剧性停顿 `[short pause]`、变化强度
- 平静：使用 `[whispers]` 或更慢的节奏
- 戏剧化：克制地使用 `[sings]` 或 `[shouts]`

Clawd 的默认语音：`lj2rcrvANS3gaWWnczSX`（或直接 `-v Clawd`）