Files

5.9 KiB

πŸ“¦ Installation Guide

Complete installation guide for the tts-whatsapp skill.

Prerequisites

Before installing this skill, ensure you have:

  1. βœ… Bot installed and configured
  2. βœ… WhatsApp connected to Bot
  3. βœ… Node.js v14 or higher
  4. βœ… Python 3.9+ (for Piper TTS)

Step 1: Install Dependencies

Install Piper TTS

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

# Verify installation
piper --version

Install FFmpeg

# 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

# Coming soon - Skills automatic installation
bot skills install tts-whatsapp

Option B: Manual Installation

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

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

Step 3: Download Voice Models

Choose Your Language

Visit Piper Voice Samples to listen to available voices.

Download Models

# Create models directory
mkdir -p ~/.bot/skills/piper-tts/models/

# Example: Download French model (siwis, medium quality)
cd ~/.bot/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
# 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 Bot configuration:

nano ~/.bot/bot.json

Add the skill configuration:

{
  "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:

# List recent messages to see group IDs
bot message read --channel whatsapp

# Group IDs look like: [email protected]

Step 5: Test the Installation

Test TTS generation (without sending)

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

tts-whatsapp "Test message to myself"

You should receive the voice message on WhatsApp.

Test different language

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

Troubleshooting

Piper not found

# 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

# Verify FFmpeg installation
which ffmpeg
ffmpeg -version

# Reinstall if needed (see Step 1)

Model not found

ERROR: Modèle introuvable: ~/.bot/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

# Make the script executable
chmod +x ~/.bot/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:

# Via Skills (when available)
bot skills update tts-whatsapp

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

Uninstall

# Remove the skill
rm -rf ~/.bot/skills/tts-whatsapp

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

# Optionally uninstall Piper
pip3 uninstall piper-tts

Next Steps

  • πŸ“– Read README.md for usage examples
  • 🌍 Check LANGUAGES.md for all available voices
  • 🎀 Test different voices and qualities
  • πŸ‘₯ Try sending to WhatsApp groups

Need Help?