sam-tts

使用 SAM（软件自动嘴）（经典的 C64 文本转语音合成器）生成复古机器人语音音频。使用 for /sam 命令生成语音消息。支持 /sam 开/关切换模式，其中所有响应均以 SAM 语音说出。支持音调、速度、嘴巴和喉咙参数以进行语音定制。

## 概述（中文）

使用 SAM（软件自动嘴）（经典的 C64 文本转语音合成器）生成复古机器人语音音频。使用 for /sam 命令生成语音消息。支持 /sam 开/关切换模式，其中所有响应均以 SAM 语音说出。支持音调、速度、嘴巴和喉咙参数以进行语音定制。

## 原文

# SAM TTS - Software Automatic Mouth

Generate WAV audio files using the classic SAM text-to-speech engine -- the iconic robotic voice from the Commodore 64 era.

## Requirements

- Node.js 18+
- Run `npm install` in the skill directory to install dependencies

## SAM Mode Toggle

**State file:** `memory/sam-mode.json`

### `/sam on` -- Enable SAM Mode
When SAM mode is enabled, ALL text responses are converted to SAM voice messages.

**Implementation:**
1. Set `enabled: true` in `memory/sam-mode.json`
2. Confirm with voice message: "SAM mode enabled. I will now speak in robotic voice."

### `/sam off` -- Disable SAM Mode
Return to normal text-to-text communication.

**Implementation:**
1. Set `enabled: false` in `memory/sam-mode.json`
2. Confirm with text: "SAM mode disabled. Back to text."

### Check current mode
Read `memory/sam-mode.json` at session start to know current state.

## Response Behavior

### When SAM mode is ON:
1. Generate response text as normal
2. Convert to SAM TTS: `node scripts/sam-tts-wrapper.js "response" --output=/tmp/sam-XXX.wav --quiet`
3. Send the generated WAV file as audio output
4. Include brief text caption if helpful

### When SAM mode is OFF:
Respond with normal text (default behavior).

## Chat Commands

### `/sam <text>`
Generate a one-time voice message using SAM TTS (works regardless of SAM mode state).

**Implementation:**
1. Extract text after `/sam `
2. Generate WAV: `node scripts/sam-tts-wrapper.js "text" --output=/tmp/sam-XXX.wav --quiet`
3. Return the WAV file as audio output

### `/sam on`
Enable SAM mode for all responses.

### `/sam off`
Disable SAM mode.

### `/sam status`
Report current SAM mode state (text response).

## Voice Parameters

All parameters accept 0-255 range values. Store defaults in `memory/sam-mode.json`:

| Parameter | Default | Effect |
|-----------|---------|--------|
| `pitch`   | 64      | Voice pitch (higher = higher pitch) |
| `speed`   | 72      | Speech speed (lower = faster) |
| `mouth`   | 128     | Mouth cavity size (affects resonance) |
| `throat`  | 128     | Throat size (affects timbre) |

### `/sam pitch <number>`
Set pitch parameter (0-255).

### `/sam speed <number>`
Set speed parameter (1-255, lower is faster).

### `/sam mouth <number>`
Set mouth parameter (0-255).

### `/sam throat <number>`
Set throat parameter (0-255).

## Scripts

### `scripts/sam-tts-wrapper.js`
Primary wrapper script. Outputs JSON metadata for automation.

```bash
node scripts/sam-tts-wrapper.js "Hello world" --output=/tmp/out.wav --quiet
node scripts/sam-tts-wrapper.js "Hello world" --output=/tmp/out.wav --quiet --pitch=80 --speed=60
```

**Options:**
- `--output=PATH` (required) - Output WAV file path
- `--quiet` - Suppress debug output, output only JSON
- `--pitch=N`, `--speed=N`, `--mouth=N`, `--throat=N` - Voice parameters
- `--phonetic` - Input is phonetic notation

**Output format:**
```json
{"success":true,"outputPath":"/tmp/sam.wav","duration":1.44,"size":31741}
```

### `scripts/sam-tts.js`
Standalone CLI tool with human-readable output.

```bash
node scripts/sam-tts.js "Hello world" output.wav --pitch=80 --speed=60
```

## State Management

### File: `memory/sam-mode.json`
```json
{
  "enabled": false,
  "pitch": 64,
  "speed": 72,
  "mouth": 128,
  "throat": 128
}
```

Read at session start. Update when user toggles mode or changes parameters. Create the `memory/` directory if it doesn't exist.

## Examples

### Enable SAM mode
User: `/sam on`
Agent: [Voice: "SAM mode enabled. I will now speak in robotic voice."]

### Normal conversation in SAM mode
User: "What's the weather?"
Agent: [Voice: "Current temperature is 72 degrees with partly cloudy skies."]

### Disable SAM mode
User: `/sam off`
Agent: SAM mode disabled. Back to text.

### One-time voice (even when mode is off)
User: `/sam Hello there`
Agent: [Voice: "Hello there"]

### Custom voice parameters
User: `/sam pitch 100`
Agent: Pitch set to 100.

User: `/sam Testing higher pitch`
Agent: [Voice with pitch=100: "Testing higher pitch"]

## Phonetic Notation

For precise pronunciation, use `--phonetic` flag:

- Vowels: `IY` (bee), `IH` (bit), `EY` (bay), `AE` (bat), `AA` (father), `AH` (bought), `AO` (hot), `OW` (boat), `UH` (book), `UW` (boot), `ER` (bird), `AX` (about)
- Numbers 1-8 indicate stress: `HEH4LOW` (emphasized second syllable)

See `references/phonemes.md` for the full phoneme chart.

## Output Format

- **Format**: WAV (RIFF/WAVE PCM)
- **Sample rate**: 22050 Hz
- **Bit depth**: 8-bit
- **Channels**: Mono

## Directory Structure

```
sam-tts/
+-- SKILL.md
+-- package.json
+-- scripts/
|   +-- sam-tts-wrapper.js
|   +-- sam-tts.js
+-- references/
|   +-- phonemes.md
+-- memory/
    +-- sam-mode.json
```

## Platform Integration

The skill outputs WAV format by default. Some messaging platforms require different audio formats.

### Format Conversion (Optional)

**(Warning):** Before installing ffmpeg or any conversion tools, the agent MUST ask the user for confirmation. Do not auto-install dependencies.

Example agent prompt:
> "This platform requires OGG/OPUS format. I need to install ffmpeg for audio conversion. Would you like me to proceed with the installation?"

Only proceed with installation after explicit user approval.

### Telegram / WhatsApp (OGG/OPUS)
```bash
ffmpeg -i input.wav -c:a libopus -b:a 24k output.ogg
```

### Discord (MP3/OGG)
```bash
ffmpeg -i input.wav -c:a libmp3lame -b:a 64k output.mp3
```

### Web / Direct Playback
WAV works directly -- no conversion needed.

**Note:** The agent should detect the target platform and handle format conversion as needed, but always with user consent for any new dependencies.

## Credits

**Skill by:** [fourthdensity](https://github.com/fourthdensity)

**Active Dependency:** [sam-js](https://github.com/discordier/sam) by discordier
- The npm package used for TTS synthesis (JavaScript/Node.js port)

**Historical Lineage:** sam-js builds upon earlier community ports:
- [SAM by Stefan Macke](https://github.com/s-macke/SAM) (C adaptation)
- [SAM by Vidar Hokstad](https://github.com/vidarh/SAM) (refactoring)
- [SAM by 8BitPimp](https://github.com/8BitPimp/SAM) (refactoring)

Original SAM (Software Automatic Mouth) (c) 1982 Don't Ask Software (now SoftVoice, Inc.)

**License Note:** The original SAM software is considered abandonware. The JavaScript adaptation is provided as-is. See the sam-js repository for full license details.

---

## 中文说明

# SAM TTS - Software Automatic Mouth

使用经典的 SAM 文本转语音引擎生成 WAV 音频文件 —— 那是 Commodore 64 时代标志性的机器人语音。

## 要求

- Node.js 18+
- 在技能目录中运行 `npm install` 以安装依赖

## SAM 模式切换

**状态文件：** `memory/sam-mode.json`

### `/sam on` —— 启用 SAM 模式
启用 SAM 模式后，所有文本响应都会被转换为 SAM 语音消息。

**实现：**
1. 在 `memory/sam-mode.json` 中设置 `enabled: true`
2. 用语音消息确认：“SAM mode enabled. I will now speak in robotic voice.”

### `/sam off` —— 禁用 SAM 模式
返回常规的文本对文本通信。

**实现：**
1. 在 `memory/sam-mode.json` 中设置 `enabled: false`
2. 用文本确认：“SAM mode disabled. Back to text.”

### 检查当前模式
在会话开始时读取 `memory/sam-mode.json` 以了解当前状态。

## 响应行为

### 当 SAM 模式为 ON 时：
1. 照常生成响应文本
2. 转换为 SAM TTS：`node scripts/sam-tts-wrapper.js "response" --output=/tmp/sam-XXX.wav --quiet`
3. 将生成的 WAV 文件作为音频输出发送
4. 如有帮助，附上简短的文本说明

### 当 SAM 模式为 OFF 时：
以常规文本响应（默认行为）。

## 聊天命令

### `/sam <text>`
使用 SAM TTS 生成一次性语音消息（无论 SAM 模式状态如何都有效）。

**实现：**
1. 提取 `/sam ` 之后的文本
2. 生成 WAV：`node scripts/sam-tts-wrapper.js "text" --output=/tmp/sam-XXX.wav --quiet`
3. 将 WAV 文件作为音频输出返回

### `/sam on`
为所有响应启用 SAM 模式。

### `/sam off`
禁用 SAM 模式。

### `/sam status`
报告当前 SAM 模式状态（文本响应）。

## 语音参数

所有参数都接受 0-255 范围的值。将默认值存储在 `memory/sam-mode.json` 中：

| 参数 | 默认值 | 效果 |
|-----------|---------|--------|
| `pitch`   | 64      | 语音音调（越高 = 音调越高） |
| `speed`   | 72      | 语速（越低 = 越快） |
| `mouth`   | 128     | 口腔大小（影响共鸣） |
| `throat`  | 128     | 喉部大小（影响音色） |

### `/sam pitch <number>`
设置音调参数（0-255）。