๐ŸŽ™๏ธ 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 Bot
  • ๐Ÿ‘ฅ 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:

    pip3 install --user piper-tts
    
  2. FFmpeg installed:

    # macOS
    brew install ffmpeg
    
    # Linux
    apt install ffmpeg  # or yum, pacman, etc.
    
  3. Piper voice models downloaded:

    • Download from Hugging Face
    • Place in ~/.bot/skills/piper-tts/models/
    • Default: fr_FR-siwis-medium.onnx

๐Ÿš€ Quick Start

Basic usage (with environment variables)

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

Specify recipient

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

Send to a WhatsApp group

tts-whatsapp "Hello everyone" --target "[email protected]"

Change language

# 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

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

Generate without sending

tts-whatsapp "Test" --no-send

๐Ÿ”ง Configuration

Environment Variables

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

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

๐ŸŽ›๏ธ All Options

tts-whatsapp "text to speak" [OPTIONS]

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

  --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 - Bot 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

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

Group announcement

tts-whatsapp "Meeting in 5 minutes!" --target "[email protected]"

With text caption

tts-whatsapp "Important update" --message "๐Ÿ“ข Please listen"

Different language and voice

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

Slow speech for learning

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

High quality for music/podcast

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

๐Ÿ” Troubleshooting

Model not found error

ERROR: Modรจle introuvable: ~/.bot/skills/piper-tts/models/en_US-lessac-medium.onnx

Solution: Download the model from Hugging Face

No default target error

โš ๏ธ  Erreur: Aucun destinataire dรฉfini

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

Bot not found

Solution: Make sure Bot is installed and in your PATH

๐Ÿ“„ License

MIT License - Feel free to use and modify

๐Ÿ™ Credits

S
Description
Hanzo Bot skill: tts-whatsapp (by hopyky)
Readme
35 KiB
Languages
Markdown 100%