Skill: hopyky/tts-whatsapp (version 1.0.0)

--- name: tts-whatsapp version: 1.0.0 description: Send high-quality text-to-speech voice messages on WhatsApp in 40+ languages with automatic delivery user-invocable: true disable-model-invocation: false tags: - whatsapp - tts - voice - messaging - multilingual - audio author: Community repository: https://github.com/clawdbot/clawdhub --- # 🎙️ TTS WhatsApp - Voice Messages in 40+ Languages Send high-quality text-to-speech voice messages on WhatsApp with automatic delivery. Supports 40+ languages, personal messages, and group broadcasts. ## ✨ Features - 🎙️ **High-quality TTS** powered by Piper (40+ languages) - 🎵 **Automatic conversion** to OGG/Opus (WhatsApp format) - 📤 **Automatic sending** via Clawdbot - 👥 **Group support** - Send to individuals or WhatsApp groups - 🌍 **Multi-language** - French, English, Spanish, German, and 40+ more - 🧹 **Smart cleanup** - Auto-delete files after successful send - ⚡ **Fast** - ~2-3s from command to delivery ## 📦 Prerequisites 1. **Piper TTS**: `pip3 install --user piper-tts` 2. **FFmpeg**: `brew install ffmpeg` (macOS) or `apt install ffmpeg` (Linux) 3. **Voice models**: Download from [Hugging Face](https://huggingface.co/rhasspy/piper-voices) - Place in `~/.clawdbot/skills/piper-tts/models/` - Example: `fr_FR-siwis-medium.onnx` ## 🚀 Quick Start ### Basic usage ```bash tts-whatsapp "Hello, this is a test" --target "+15555550123" ``` ### Send to WhatsApp group ```bash tts-whatsapp "Hello everyone" --target "[REDACTED_SECRET]" ``` ### Change language ```bash tts-whatsapp "Hola mundo" --lang es_ES --voice carlfm --target "+34..." ``` ### Different quality levels ```bash tts-whatsapp "High quality" --quality high --target "+1..." ``` ## 🌍 Supported Languages - 🇫🇷 French (`fr_FR`): siwis, upmc, tom - 🇬🇧 English GB (`en_GB`): alan, alba - 🇺🇸 English US (`en_US`): lessac, amy, joe - 🇪🇸 Spanish (`es_ES`, `es_MX`): carlfm, davefx - 🇩🇪 German (`de_DE`): thorsten, eva_k - 🇮🇹 Italian (`it_IT`): riccardo - 🇵🇹 Portuguese (`pt_BR`, `pt_PT`): faber - 🇳🇱 Dutch (`nl_NL`): mls, rdh - 🇷🇺 Russian (`ru_RU`): dmitri, irina - And 30+ more! [Full voice list →](https://rhasspy.github.io/piper-samples/) ## 🔧 Configuration Configure in `~/.clawdbot/clawdbot.json`: ```json { "skills": { "entries": { "tts_whatsapp": { "enabled": true, "env": { "WHATSAPP_DEFAULT_TARGET": "+15555550123", "PIPER_DEFAULT_LANG": "en_US", "PIPER_DEFAULT_VOICE": "lessac", "PIPER_DEFAULT_QUALITY": "medium" } } } } } ``` ## 🎛️ All Options ``` --target NUMBER WhatsApp number or group ID --message TEXT Text message with audio --lang LANGUAGE Language (default: fr_FR) --voice VOICE Voice name (default: auto) --quality QUALITY x_low, low, medium, high --speed SPEED Playback speed (default: 1.0) --no-send Don't send automatically ``` ## 📊 Performance ~2.3s total for a 10-second message: - TTS generation: ~1s - Format conversion: ~0.2s - WhatsApp delivery: ~1s ## 📚 Full Documentation See [README.md](README.md) for complete documentation, examples, and troubleshooting.

path: CHANGELOG.md
content: # Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [1.0.0] - 2026-01-22

### Added
- 🎙️ High-quality text-to-speech using Piper TTS
- 🌍 Support for 40+ languages (French, English, Spanish, German, and more)
- 📤 Automatic WhatsApp message sending via Clawdbot
- 👥 Support for WhatsApp groups (use group ID as target)
- 🎛️ Multiple quality levels (x_low, low, medium, high)
- 🎵 Automatic conversion to OGG/Opus format for WhatsApp
- 🧹 Smart file cleanup:
  - Auto-delete files after successful send
  - Auto-cleanup files older than 24 hours
  - Keep files on send error for manual retry
- ⚙️ Flexible configuration via environment variables
- 🚫 `--no-send` option to generate audio without sending
- 🎚️ `--speed` option to adjust playback speed
- 💬 `--message` option to add text caption with audio
- 📊 Clear progress logging and error messages
- 🔍 Model existence validation with helpful error messages

### Features
- **Multi-language support**: Switch between 40+ languages with `--lang`
- **Voice selection**: Choose specific voices with `--voice`
- **Quality control**: Adjust quality/size trade-off with `--quality`
- **Group messaging**: Send to WhatsApp groups using group IDs
- **Environment-based defaults**: Set preferences via environment variables
- **Fast generation**: ~2-3s from command to WhatsApp delivery

### Technical Details
- Node.js script with minimal dependencies
- Integration with Piper TTS for speech synthesis
- FFmpeg for audio format conversion
- Clawdbot CLI for WhatsApp delivery
- Automatic cleanup of temporary files
- Comprehensive error handling

[1.0.0]: https://github.com/clawdbot/clawdhub/releases/tag/tts-whatsapp-v1.0.0


path: INSTALL.md
content: # 📦 Installation Guide

Complete installation guide for the tts-whatsapp skill.

## Prerequisites

Before installing this skill, ensure you have:

1. ✅ **Clawdbot** installed and configured
2. ✅ **WhatsApp** connected to Clawdbot
3. ✅ **Node.js** v14 or higher
4. ✅ **Python 3.9+** (for Piper TTS)

## Step 1: Install Dependencies

### Install Piper TTS

```bash
# macOS / Linux
pip3 install --user piper-tts

# Verify installation
piper --version
```

### Install FFmpeg

```bash
# macOS
brew install ffmpeg

# Ubuntu/Debian
sudo apt update && sudo apt install ffmpeg

# Fedora/RHEL
sudo dnf install ffmpeg

# Arch Linux
sudo pacman -S ffmpeg

# Verify installation
ffmpeg -version
```

## Step 2: Install the Skill

### Option A: Via ClawdHub (Recommended)

```bash
# Coming soon - ClawdHub automatic installation
clawdbot skills install tts-whatsapp
```

### Option B: Manual Installation

```bash
# Clone or download this repository
cd ~/.clawdbot/skills/
git clone https://github.com/clawdbot/clawdhub.git temp
cp -r temp/skills/tts-whatsapp tts-whatsapp
rm -rf temp

# Or download and extract manually
mkdir -p ~/.clawdbot/skills/tts-whatsapp
cd ~/.clawdbot/skills/tts-whatsapp
# Extract downloaded files here
```

## Step 3: Download Voice Models

### Choose Your Language

Visit [Piper Voice Samples](https://rhasspy.github.io/piper-samples/) to listen to available voices.

### Download Models

```bash
# Create models directory
mkdir -p ~/.clawdbot/skills/piper-tts/models/

# Example: Download French model (siwis, medium quality)
cd ~/.clawdbot/skills/piper-tts/models/

# Download .onnx file
wget https://huggingface.co/rhasspy/piper-voices/resolve/main/fr/fr_FR/siwis/medium/fr_FR-siwis-medium.onnx

# Download .onnx.json file (required)
wget https://huggingface.co/rhasspy/piper-voices/resolve/main/fr/fr_FR/siwis/medium/fr_FR-siwis-medium.onnx.json
```

### Popular Models to Download

```bash
# English US (lessac - female, high quality)
wget https://huggingface.co/rhasspy/piper-voices/resolve/main/en/en_US/lessac/medium/en_US-lessac-medium.onnx
wget https://huggingface.co/rhasspy/piper-voices/resolve/main/en/en_US/lessac/medium/en_US-lessac-medium.onnx.json

# Spanish ES (carlfm - male)
wget https://huggingface.co/rhasspy/piper-voices/resolve/main/es/es_ES/carlfm/medium/es_ES-carlfm-medium.onnx
wget https://huggingface.co/rhasspy/piper-voices/resolve/main/es/es_ES/carlfm/medium/es_ES-carlfm-medium.onnx.json

# German (thorsten - male, high quality)
wget https://huggingface.co/rhasspy/piper-voices/resolve/main/de/de_DE/thorsten/medium/de_DE-thorsten-medium.onnx
wget https://huggingface.co/rhasspy/piper-voices/resolve/main/de/de_DE/thorsten/medium/de_DE-thorsten-medium.onnx.json
```

**Note:** Always download BOTH the `.onnx` and `.onnx.json` files for each model.

## Step 4: Configure the Skill

Edit your Clawdbot configuration:

```bash
nano ~/.clawdbot/clawdbot.json
```

Add the skill configuration:

```json
{
  "skills": {
    "entries": {
      "tts_whatsapp": {
        "enabled": true,
        "env": {
          "PIPER_BIN_PATH": "/Users/YOUR_USERNAME/Library/Python/3.9/bin/piper",
          "WHATSAPP_DEFAULT_TARGET": "+15555550123",
          "PIPER_DEFAULT_LANG": "en_US",
          "PIPER_DEFAULT_VOICE": "lessac",
          "PIPER_DEFAULT_QUALITY": "medium"
        }
      }
    }
  }
}
```

### Configuration Values

Replace these values:

- `PIPER_BIN_PATH`: Run `which piper` to find your path
- `WHATSAPP_DEFAULT_TARGET`: Your WhatsApp number in E.164 format (+1234567890)
- `PIPER_DEFAULT_LANG`: Your preferred language code
- `PIPER_DEFAULT_VOICE`: Your preferred voice name
- `PIPER_DEFAULT_QUALITY`: `x_low`, `low`, `medium`, or `high`

### Find WhatsApp Group IDs

To send to a WhatsApp group, you need the group ID:

```bash
# List recent messages to see group IDs
clawdbot message read --channel whatsapp

# Group IDs look like: [REDACTED_SECRET]
```

## Step 5: Test the Installation

### Test TTS generation (without sending)

```bash
tts-whatsapp "This is a test" --no-send
```

You should see:
- ✅ TTS generation successful
- ✅ Conversion to OGG successful
- ✅ File path displayed

### Test sending to yourself

```bash
tts-whatsapp "Test message to myself"
```

You should receive the voice message on WhatsApp.

### Test different language

```bash
tts-whatsapp "Hola mundo" --lang es_ES --voice carlfm
```

## Troubleshooting

### Piper not found

```bash
# Find piper location
which piper

# If not found, reinstall
pip3 install --user piper-tts

# Check Python bin directory
ls ~/Library/Python/3.9/bin/  # macOS
ls ~/.local/bin/               # Linux
```

### FFmpeg not found

```bash
# Verify FFmpeg installation
which ffmpeg
ffmpeg -version

# Reinstall if needed (see Step 1)
```

### Model not found

```
ERROR: Modèle introuvable: ~/.clawdbot/skills/piper-tts/models/en_US-lessac-medium.onnx
```

**Solution:** Make sure you downloaded BOTH files:
- `en_US-lessac-medium.onnx`
- `en_US-lessac-medium.onnx.json`

### Permission denied

```bash
# Make the script executable
chmod +x ~/.clawdbot/skills/tts-whatsapp/bin/tts-whatsapp
```

### No default target error

Either:
1. Set `WHATSAPP_DEFAULT_TARGET` in your config, OR
2. Always use `--target` when calling the command

## Upgrade

To upgrade to a newer version:

```bash
# Via ClawdHub (when available)
clawdbot skills update tts-whatsapp

# Manual upgrade
cd ~/.clawdbot/skills/tts-whatsapp
git pull  # or re-download and extract
```

## Uninstall

```bash
# Remove the skill
rm -rf ~/.clawdbot/skills/tts-whatsapp

# Optionally remove voice models
rm -rf ~/.clawdbot/skills/piper-tts

# Optionally uninstall Piper
pip3 uninstall piper-tts
```

## Next Steps

- 📖 Read [README.md](README.md) for usage examples
- 🌍 Check [LANGUAGES.md](LANGUAGES.md) for all available voices
- 🎤 Test different voices and qualities
- 👥 Try sending to WhatsApp groups

## Need Help?

- 📚 [Full Documentation](README.md)
- 🐛 [Report Issues](https://github.com/clawdbot/clawdhub/issues)
- 💬 [Clawdbot Discussions](https://github.com/clawdbot/clawdbot/discussions)


path: LANGUAGES.md
content: # 🌍 Supported Languages & Voices

Complete list of languages and voices available with Piper TTS for the tts-whatsapp skill.

## How to Use

```bash
tts-whatsapp "Your text" --lang LANGUAGE_CODE --voice VOICE_NAME --quality QUALITY
```

## Quality Levels

- `x_low` - Smallest model, fastest, lower quality
- `low` - Small model, fast, decent quality
- `medium` - Balanced (recommended)
- `high` - Largest model, slowest, best quality

Not all voices have all quality levels. Check [Hugging Face](https://huggingface.co/rhasspy/piper-voices) for available combinations.

## Available Languages

### 🇫🇷 French (fr_FR)
- **siwis** - Female voice (medium, low)
- **upmc** - Female voice (medium)
- **tom** - Male voice (medium)

### 🇬🇧 English - British (en_GB)
- **alan** - Male voice (medium, low)
- **alba** - Female Scottish voice (medium)
- **northern_english_male** - Male Northern English (medium)
- **semaine** - Female voice (medium)
- **southern_english_female** - Female Southern English (medium, low)

### 🇺🇸 English - US (en_US)
- **lessac** - Female voice, high quality (high, medium, low)
- **libritts** - Multi-speaker (high)
- **amy** - Female voice (medium, low)
- **joe** - Male voice (medium)
- **kristin** - Female voice (medium)
- **kusal** - Male voice (medium)
- **l2arctic** - Multi-speaker (medium)
- **ljspeech** - Female voice (high, medium, low)
- **norman** - Male voice (medium)
- **ryan** - Male voice (high, medium, low)

### 🇪🇸 Spanish - Spain (es_ES)
- **carlfm** - Male voice (medium, low)
- **davefx** - Male voice (medium)
- **mls_9972** - Female voice (medium)
- **mls_10246** - Male voice (medium)
- **sharvard** - Male voice (medium)

### 🇲🇽 Spanish - Mexico (es_MX)
- **claude** - Male voice (medium)
- **ald** - Female voice (medium)

### 🇦🇷 Spanish - Argentina (es_AR)
- **tux** - Male voice (medium)

### 🇩🇪 German (de_DE)
- **thorsten** - Male voice, high quality (high, medium, low)
- **thorsten_emotional** - Male voice with emotions (medium)
- **eva_k** - Female voice (medium, low)
- **karlsson** - Male voice (medium)
- **kerstin** - Female voice (medium)
- **pavoque** - Male voice (medium)
- **ramona** - Female voice (medium)

### 🇮🇹 Italian (it_IT)
- **riccardo** - Male voice (medium, low)
- **paola** - Female voice (medium)

### 🇵🇹 Portuguese - Brazil (pt_BR)
- **faber** - Male voice (medium)
- **edresson** - Male voice (medium, low)

### 🇵🇹 Portuguese - Portugal (pt_PT)
- **tugao** - Male voice (medium)

### 🇳🇱 Dutch (nl_NL)
- **mls** - Multi-speaker (medium)
- **rdh** - Male voice (medium)
- **nathalie** - Female voice (medium)

### 🇷🇺 Russian (ru_RU)
- **dmitri** - Male voice (medium)
- **irina** - Female voice (medium)
- **ruslan** - Male voice (medium)

### 🇨🇳 Chinese - Simplified (zh_CN)
- **huayan** - Female voice (medium, low)

### 🇵🇱 Polish (pl_PL)
- **darkman** - Male voice (medium)
- **gosia** - Female voice (medium)
- **mc_speech** - Multi-speaker (medium)

### 🇺🇦 Ukrainian (uk_UA)
- **ukrainian_tts** - Multi-speaker (medium)
- **lada** - Female voice (medium)

### 🇨🇿 Czech (cs_CZ)
- **jirka** - Male voice (medium)

### 🇸🇪 Swedish (sv_SE)
- **nst** - Multi-speaker (medium)

### 🇳🇴 Norwegian (no_NO)
- **talesyntese** - Multi-speaker (medium)

### 🇩🇰 Danish (da_DK)
- **talesyntese** - Multi-speaker (medium)

### 🇫🇮 Finnish (fi_FI)
- **harri** - Male voice (medium)

### 🇭🇺 Hungarian (hu_HU)
- **anna** - Female voice (medium)
- **berta** - Female voice (medium)
- **imre** - Male voice (medium)

### 🇹🇷 Turkish (tr_TR)
- **dfki** - Male voice (medium)
- **fahrettin** - Male voice (medium)

### 🇬🇷 Greek (el_GR)
- **rapunzelina** - Female voice (medium)

### 🇮🇳 Hindi (hi_IN)
- **coqui** - Multi-speaker (medium)

### 🇮🇳 Malayalam (ml_IN)
- **male** - Male voice (medium)

### 🇳🇵 Nepali (ne_NP)
- **google** - Multi-speaker (medium)

### 🇻🇳 Vietnamese (vi_VN)
- **vais1000** - Multi-speaker (medium)
- **25hours** - Multi-speaker (medium)

### 🇦🇪 Arabic (ar_AE, ar_JO, ar_SY)
- Various regional voices available

### 🇮🇷 Persian/Farsi (fa_IR)
- **amir** - Male voice (medium)
- **gyro** - Male voice (medium)

### 🇰🇿 Kazakh (kk_KZ)
- **iseke** - Female voice (medium)
- **issai** - Multi-speaker (medium)
- **raya** - Female voice (medium)

### 🇬🇪 Georgian (ka_GE)
- **natia** - Female voice (medium)

### 🇱🇻 Latvian (lv_LV)
- **tilde** - Multi-speaker (medium)

### 🇷🇴 Romanian (ro_RO)
- **mihai** - Male voice (medium)

### 🇷🇸 Serbian (sr_RS)
- **serbian_tts** - Multi-speaker (medium)

### 🇸🇰 Slovak (sk_SK)
- **lili** - Female voice (medium)

### 🇸🇮 Slovenian (sl_SI)
- **artur** - Male voice (medium)

### 🇹🇿 Swahili (sw_CD)
- **lanfrica** - Multi-speaker (medium)

### 🇮🇸 Icelandic (is_IS)
- **bui** - Male voice (medium)
- **salka** - Female voice (medium)
- **steinn** - Male voice (medium)
- **ugla** - Female voice (medium)

### 🏴󐁧󐁢󐁷󐁬󐁳󐁿 Welsh (cy_GB)
- **gwryw_gogleddol** - Male Northern (medium)

### 🇱🇺 Luxembourgish (lb_LU)
- **thorsten** - Male voice (medium)

## Download Models

Visit [Hugging Face - Piper Voices](https://huggingface.co/rhasspy/piper-voices) to download models.

### Example Downloads

```bash
# Create models directory
mkdir -p ~/.clawdbot/skills/piper-tts/models/

# Download French model
wget https://huggingface.co/rhasspy/piper-voices/resolve/main/fr/fr_FR/siwis/medium/fr_FR-siwis-medium.onnx \
  -O ~/.clawdbot/skills/piper-tts/models/fr_FR-siwis-medium.onnx

wget https://huggingface.co/rhasspy/piper-voices/resolve/main/fr/fr_FR/siwis/medium/fr_FR-siwis-medium.onnx.json \
  -O ~/.clawdbot/skills/piper-tts/models/fr_FR-siwis-medium.onnx.json

# Download English model
wget https://huggingface.co/rhasspy/piper-voices/resolve/main/en/en_US/lessac/medium/en_US-lessac-medium.onnx \
  -O ~/.clawdbot/skills/piper-tts/models/en_US-lessac-medium.onnx

wget https://huggingface.co/rhasspy/piper-voices/resolve/main/en/en_US/lessac/medium/en_US-lessac-medium.onnx.json \
  -O ~/.clawdbot/skills/piper-tts/models/en_US-lessac-medium.onnx.json
```

## Listen to Samples

Before downloading, listen to voice samples at:
[https://rhasspy.github.io/piper-samples/](https://rhasspy.github.io/piper-samples/)

## Usage Examples

```bash
# French with different voices
tts-whatsapp "Bonjour" --lang fr_FR --voice siwis
tts-whatsapp "Bonjour" --lang fr_FR --voice upmc
tts-whatsapp "Bonjour" --lang fr_FR --voice tom

# English US with different voices
tts-whatsapp "Hello" --lang en_US --voice lessac
tts-whatsapp "Hello" --lang en_US --voice amy
tts-whatsapp "Hello" --lang en_US --voice joe

# Spanish variations
tts-whatsapp "Hola" --lang es_ES --voice carlfm
tts-whatsapp "Hola" --lang es_MX --voice claude
tts-whatsapp "Hola" --lang es_AR --voice tux

# German with high quality
tts-whatsapp "Guten Tag" --lang de_DE --voice thorsten --quality high

# Italian
tts-whatsapp "Ciao" --lang it_IT --voice riccardo

# Portuguese
tts-whatsapp "Olá" --lang pt_BR --voice faber
tts-whatsapp "Olá" --lang pt_PT --voice tugao
```


path: README.md
content: # 🎙️ TTS WhatsApp - Text-to-Speech Voice Messages

Send voice messages on WhatsApp with high-quality text-to-speech in 40+ languages.

## ✨ Features

- 🎙️ **High-quality TTS** powered by Piper (40+ languages)
- 🎵 **Automatic conversion** to OGG/Opus (WhatsApp format)
- 📤 **Automatic sending** via Clawdbot
- 👥 **Group support** - Send to individuals or WhatsApp groups
- 🌍 **Multi-language** - French, English, Spanish, German, and 40+ more
- 🧹 **Smart cleanup** - Auto-delete files after successful send
- ⚡ **Fast** - ~2-3s from command to delivery

## 📦 Prerequisites

1. **Piper TTS** installed:
   ```bash
   pip3 install --user piper-tts
   ```

2. **FFmpeg** installed:
   ```bash
   # macOS
   brew install ffmpeg

   # Linux
   apt install ffmpeg  # or yum, pacman, etc.
   ```

3. **Piper voice models** downloaded:
   - Download from [Hugging Face](https://huggingface.co/rhasspy/piper-voices)
   - Place in `~/.clawdbot/skills/piper-tts/models/`
   - Default: `fr_FR-siwis-medium.onnx`

## 🚀 Quick Start

### Basic usage (with environment variables)

```bash
tts-whatsapp "Hello, this is a test message"
```

### Specify recipient

```bash
tts-whatsapp "Hello" --target "+15555550123"
```

### Send to a WhatsApp group

```bash
tts-whatsapp "Hello everyone" --target "[REDACTED_SECRET]"
```

### Change language

```bash
# English
tts-whatsapp "Hello world" --lang en_US --voice lessac

# Spanish
tts-whatsapp "Hola mundo" --lang es_ES --voice carlfm

# German
tts-whatsapp "Guten Tag" --lang de_DE --voice thorsten
```

### Adjust voice quality

```bash
tts-whatsapp "High quality audio" --quality high
```

### Generate without sending

```bash
tts-whatsapp "Test" --no-send
```

## 🔧 Configuration

### Environment Variables

Set these in `~/.clawdbot/clawdbot.json` under the skill configuration:

```json
{
  "skills": {
    "entries": {
      "tts_whatsapp": {
        "enabled": true,
        "env": {
          "PIPER_BIN_PATH": "/path/to/piper",
          "WHATSAPP_DEFAULT_TARGET": "+15555550123",
          "PIPER_DEFAULT_LANG": "en_US",
          "PIPER_DEFAULT_VOICE": "lessac",
          "PIPER_DEFAULT_QUALITY": "medium"
        }
      }
    }
  }
}
```

### Available Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `PIPER_BIN_PATH` | Path to piper executable | `~/Library/Python/3.9/bin/piper` |
| `WHATSAPP_DEFAULT_TARGET` | Default recipient phone number or group ID | None (required) |
| `PIPER_DEFAULT_LANG` | Default language code | `fr_FR` |
| `PIPER_DEFAULT_VOICE` | Default voice name | `siwis` |
| `PIPER_DEFAULT_QUALITY` | Default quality level | `medium` |

## 🌍 Supported Languages

Piper supports 40+ languages. Here are some examples:

| Language | Code | Example Voices |
|----------|------|----------------|
| 🇫🇷 French | `fr_FR` | `siwis`, `upmc`, `tom` |
| 🇬🇧 English (GB) | `en_GB` | `alan`, `alba`, `northern_english_male` |
| 🇺🇸 English (US) | `en_US` | `lessac`, `libritts`, `amy`, `joe` |
| 🇪🇸 Spanish | `es_ES` | `carlfm`, `davefx` |
| 🇲🇽 Spanish (MX) | `es_MX` | `claude` |
| 🇩🇪 German | `de_DE` | `thorsten`, `eva_k`, `karlsson` |
| 🇮🇹 Italian | `it_IT` | `riccardo` |
| 🇵🇹 Portuguese (BR) | `pt_BR` | `faber` |
| 🇵🇹 Portuguese (PT) | `pt_PT` | `tugão` |
| 🇳🇱 Dutch | `nl_NL` | `mls`, `rdh` |
| 🇷🇺 Russian | `ru_RU` | `dmitri`, `irina` |
| 🇨🇳 Chinese | `zh_CN` | `huayan` |

**Full list:** [Piper Voice Samples](https://rhasspy.github.io/piper-samples/)

## 🎛️ All Options

```bash
tts-whatsapp "text to speak" [OPTIONS]

Options:
  --target NUMBER       WhatsApp number or group ID
                        Examples: +15555550123, [REDACTED_SECRET]

  --message TEXT        Text message accompanying the audio

  --lang LANGUAGE       Language code (default: fr_FR)
                        Examples: en_US, es_ES, de_DE, it_IT

  --voice VOICE         Specific voice name (default: auto per language)
                        Examples: lessac, siwis, thorsten

  --quality QUALITY     Audio quality: x_low, low, medium, high
                        Default: medium

  --speed SPEED         Playback speed (default: 1.0)
                        Examples: 0.8 (slower), 1.2 (faster)

  --no-send            Generate audio file without sending
```

## 📊 How It Works

1. **Text → Speech** - Piper generates high-quality audio (~1s)
2. **Convert** - FFmpeg converts to OGG/Opus format (~0.2s)
3. **Send** - Clawdbot sends to WhatsApp (~1s)
4. **Cleanup** - File deleted after successful send

**Total time: ~2.3s** for a 10-second message

## 🗑️ File Management

- **Auto-delete after send** - Files removed after successful WhatsApp delivery
- **Auto-cleanup old files** - Files older than 24h are deleted on next run
- **Keep on error** - Files preserved if sending fails

## 💡 Examples

### Personal message

```bash
tts-whatsapp "Don't forget the meeting at 3pm" --target "+15555550123"
```

### Group announcement

```bash
tts-whatsapp "Meeting in 5 minutes!" --target "[REDACTED_SECRET]"
```

### With text caption

```bash
tts-whatsapp "Important update" --message "📢 Please listen"
```

### Different language and voice

```bash
tts-whatsapp "Guten Morgen" --lang de_DE --voice thorsten --target "+491234567890"
```

### Slow speech for learning

```bash
tts-whatsapp "Practice your pronunciation" --speed 0.7 --lang en_US
```

### High quality for music/podcast

```bash
tts-whatsapp "Welcome to my podcast" --quality high --lang en_US --voice lessac
```

## 🔍 Troubleshooting

### Model not found error

```
ERROR: Modèle introuvable: ~/.clawdbot/skills/piper-tts/models/en_US-lessac-medium.onnx
```

**Solution:** Download the model from [Hugging Face](https://huggingface.co/rhasspy/piper-voices/tree/main/en/en_US/lessac/medium)

### No default target error

```
⚠️  Erreur: Aucun destinataire défini
```

**Solution:** Either set `WHATSAPP_DEFAULT_TARGET` in your config or use `--target`

### Clawdbot not found

**Solution:** Make sure Clawdbot is installed and in your PATH

## 📄 License

MIT License - Feel free to use and modify

## 🙏 Credits

- **Piper TTS** by [Rhasspy](https://github.com/rhasspy/piper)
- **Clawdbot** by [clawdbot team](https://github.com/clawdbot/clawdbot)
- **FFmpeg** by the FFmpeg team

## 🔗 Links

- [Piper Voice Samples](https://rhasspy.github.io/piper-samples/)
- [Download Voice Models](https://huggingface.co/rhasspy/piper-voices)
- [Clawdbot Documentation](https://docs.clawd.bot)
- [ClawdHub](https://clawdhub.com)


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)