Piper Announce

🎵 AI-powered announcement generator using Piper TTS and OpenAI GPT models with automatic voice model downloads.

✨ New in v1.2.2

• 🚀 Automatic Voice Downloads: Voice models are now downloaded automatically during installation
• 📊 Progress Tracking: See real-time download progress for each voice model
• 🔍 Voice Status Checking: Check which voices are available with built-in commands
• ⚡ Smart Error Handling: Helpful suggestions when voice models are missing

Features

• AI-Powered Text Generation: Transform your ideas into polished announcements using OpenAI GPT
• High-Quality TTS: Generate natural-sounding speech with Piper neural voices
• Multiple Languages: Support for English, Spanish, and Catalan
• Voice Variety: Male and female voices for each language
• Style Presets: Choose from friendly, formal, urgent, or custom styles
• Audio Mastering: Professional audio processing with normalization and filtering
• Multiple Formats: Export to WAV, MP3, M4A, and Opus
• Automatic Setup: Voice models download automatically on installation

Quick Start

Installation

npm install piper-announce

That's it! Voice models will download automatically during installation. You'll see progress bars for each download:

🎵 Piper Announce Voice Downloader
==================================================

⬇️  Need to download (6):
   • en_GB-jenny_dioco-medium.onnx (English (GB), Female, 63MB)
   • en_GB-alan-low.onnx (English (GB), Male, 22MB)
   • es_ES-mls_10246-low.onnx (Spanish (ES), Female, 22MB)
   • es_ES-carlfm-x_low.onnx (Spanish (ES), Male, 9MB)
   • ca_ES-upc_ona-x_low.onnx (Catalan (ES), Female, 9MB)
   • ca_ES-upc_pau-x_low.onnx (Catalan (ES), Male, 9MB)

📥 Downloading en_GB-jenny_dioco-medium.onnx...
   [████████████████████████████████████████] 100% 63.2MB/63.2MB
   ✅ Successfully downloaded en_GB-jenny_dioco-medium.onnx

Prerequisites

You'll need these tools installed:

• Node.js 16+
• Piper TTS - Install using pip: pip install piper-tts
• FFmpeg - For audio processing and format conversion
• OpenAI API Key - Set as OPENAI_API_KEY environment variable

Installing Piper TTS

The easiest way to install Piper TTS is using pip. This library uses the python package from piper.

pip install piper-tts

After installation, find the piper binary location:

macOS:

which piper
# Typical path: /opt/homebrew/bin/piper (Homebrew) or /usr/local/bin/piper

Linux:

which piper
# Typical paths: ~/.local/bin/piper or /usr/local/bin/piper

Windows:

where piper
# Typical path: C:\Python311\Scripts\piper.exe or similar

Add the path shown by the command above to your environment variables:

Method 1: Environment Variable

export PIPER_BIN=/opt/homebrew/bin/piper

Method 2: .env file

# Create or edit your .env file
PIPER_BIN=/opt/homebrew/bin/piper
OPENAI_API_KEY=your_openai_api_key_here

Method 3: Add to shell profile

# Add to ~/.zshrc or ~/.bash_profile
echo 'export PIPER_BIN=/opt/homebrew/bin/piper' >> ~/.zshrc
source ~/.zshrc

Voice Model Management

After installing the package, you can manage voice models using the piper-voices command:

Check Voice Status

piper-voices status

This shows which voice models are available:

📊 Voice Model Status:
═══════════════════════════════════════════════

English (GB) (en):
  Female: ✅ Available
  Male: ✅ Available

Spanish (ES) (es):
  Female: ✅ Available
  Male: ❌ Missing

💡 To download missing voices:
   piper-voices download

Download Missing Voices

piper-voices download

Force Re-download All Voices

piper-voices download --force

Alternative: Use npx

If the piper-voices command is not available in your PATH:

npx piper-voices status
npx piper-voices download
npx piper-voices download --force

Programmatic Voice Management

You can also check voice status programmatically:

import { getVoiceStatus } from "piper-announce";

const { availability, missingVoices } = getVoiceStatus();
console.log(availability);
// {
//   en: { female: true, male: true },
//   es: { female: true, male: false },
//   ca: { female: true, male: true }
// }

if (missingVoices.length > 0) {
  console.log("Missing voices:", missingVoices);
}

Usage

Basic Example

import { generateAnnouncementText, makeAnnouncement } from "piper-announce";

// Step 1: Generate announcement text
const text = await generateAnnouncementText(
  "The library will close in 15 minutes",
  {
    language: "en",
    style: "friendly",
  }
);

console.log(text); // "The library will be closing in 15 minutes. Please gather your belongings and head to the checkout desk."

// Step 2: Generate audio
const result = makeAnnouncement(text, {
  language: "en",
  gender: "female",
  style: "friendly",
  exportFormats: ["mp3", "m4a"],
});

console.log(result);
// {
//   text: "The library will be closing in 15 minutes...",
//   audio: "announcement_en_friendly_female_20241201123045.wav",
//   extras: {
//     mp3: "announcement_en_friendly_female_20241201123045.mp3",
//     m4a: "announcement_en_friendly_female_20241201123045.m4a"
//   }
// }

Check Voice Availability Programmatically

import { getVoiceStatus } from "piper-announce";

const { availability, missingVoices } = getVoiceStatus();

console.log(availability);
// {
//   en: { female: true, male: true },
//   es: { female: true, male: false },
//   ca: { female: true, male: true }
// }

if (missingVoices.length > 0) {
  console.log("Missing voices:", missingVoices);
}

Advanced Usage

import { generateAnnouncementText, makeAnnouncement } from "piper-announce";

// Custom style with specific requirements
const customText = await generateAnnouncementText("Fire drill in 5 minutes", {
  language: "en",
  style: "custom",
  customStyle: "Calm but authoritative, reassuring tone",
});

// High-quality audio with multiple formats
const result = makeAnnouncement(customText, {
  language: "en",
  gender: "male",
  style: "urgent",
  master: true, // Apply audio mastering
  exportFormats: ["mp3", "opus"],
  keepWav: false, // Delete WAV after conversion
});

Configuration

Environment Variables

# Required
OPENAI_API_KEY=your_openai_api_key_here
PIPER_BIN=/opt/homebrew/bin/piper    # Path to piper binary (from 'which piper')

# Optional
VOICES_DIR=/path/to/voices           # Custom voices directory
SKIP_VOICE_DOWNLOAD=true            # Skip automatic voice download

Supported Languages & Voices

| Language | Code | Female Voice | Male Voice | Quality | | ------------ | ---- | ------------ | ---------- | ---------- | | English (GB) | en | jenny_dioco | alan | Medium/Low | | Spanish (ES) | es | mls_10246 | carlfm | Low/X-Low | | Catalan (ES) | ca | upc_ona | upc_pau | X-Low |

Style Options

• friendly - Warm, welcoming, upbeat tone
• formal - Polite, concise, professional tone
• urgent - Direct, time-sensitive with clear call-to-action
• custom - Specify your own style requirements

API Reference

generateAnnouncementText(userText, options)

Generate polished announcement text using AI.

Parameters:

• userText (string) - Your announcement request
• options (object)
  • language (string) - Language code: 'en', 'es', 'ca'
  • style (string) - Style: 'friendly', 'formal', 'urgent', 'custom'
  • customStyle (string) - Custom style description (when style='custom')

Returns: Promise - Generated announcement text

makeAnnouncement(text, options)

Convert text to high-quality speech.

Parameters:

• text (string) - Text to synthesize
• options (object)
  • language (string) - Language code: 'en', 'es', 'ca'
  • gender (string) - Voice gender: 'female', 'male'
  • style (string) - Audio style preset
  • master (boolean) - Apply audio mastering (default: true)
  • exportFormats (array) - Additional formats: ['mp3', 'm4a', 'opus']
  • keepWav (boolean) - Keep WAV file (default: false)

Returns: Object with text, audio, and extras properties

getVoiceStatus()

Check voice model availability.

Returns: Object with availability and missingVoices properties

Voice Models

Voice models are automatically downloaded from Hugging Face's rhasspy/piper-voices repository. Total download size is approximately ~134MB for all voices.

Manual Voice Management

If you need to manage voices manually:

# Check what's available
node -e "import('./src/index.js').then(m => console.log(m.getVoiceStatus()))"

# Download missing voices
npm run download-voices

# Force re-download all
npm run download-voices:force

Troubleshooting

Piper Installation Issues

"Piper command not found"

1. Install Piper TTS using pip:

   pip install piper-tts

2. Find the installation path:

   which piper

3. Set the environment variable:

   export PIPER_BIN=/opt/homebrew/bin/piper
   # or add to your .env file

Voice Download Issues

If voice downloads fail during installation:

# Retry voice downloads
npm run download-voices

# Check your internet connection and try again
npm run download-voices:force

# Check voice status
node examples/voice-status.js

Common Issues

"Missing voice for language/gender"

npm run download-voices

"FFmpeg command not found"

# Install FFmpeg
# macOS: brew install ffmpeg
# Ubuntu: sudo apt install ffmpeg
# Windows: Download from https://ffmpeg.org

Permission denied errors

If you get permission errors when running piper, make sure it's executable:

chmod +x $(which piper)

Examples

Check the examples/ directory:

• examples/basic-usage.js - Basic text generation and synthesis
• examples/voice-status.js - Check voice availability
• examples/batch-announcements.js - Generate multiple announcements

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT License - see the LICENSE file for details.

Changelog

v1.2.2

• ✨ Simplified Piper TTS installation using pip
• 📝 Updated documentation with pip installation instructions
• 🔧 Enhanced environment variable configuration
• 🛠️ Improved troubleshooting guide

v1.2.0

• ✨ Added automatic voice model downloads during installation
• 📊 Added progress tracking for downloads
• 🔍 Added voice status checking functionality
• ⚡ Improved error messages with helpful suggestions
• 🛠️ Enhanced API with getVoiceStatus() function

v1.1.2

• 🎵 Initial release with manual voice setup
• 🤖 AI-powered text generation
• 🗣️ Multi-language TTS support
• 🎛️ Audio mastering and format conversion