n8n-nodes-groq-speech/README.md

N8N Community Node for Groq Text-to-Speech API integration

# n8n-nodes-groq-speech

This is an N8N community node package for integration with Groq.com Text-to-Speech (TTS) API.

## Features

- Text to audio conversion using Groq API
- Support for multiple TTS models (playai-tts, playai-tts-arabic)
- 19 different voices available
- Speech speed control (0.25x to 4.0x)
- Multiple output formats (MP3, WAV, FLAC, OGG)
- Output as binary data for use in other nodes
- **NEW**: Built-in Base64 encoding for direct API integration
- **NEW**: WhatsApp-ready audio output format

## Installation

To use this community node, you need to install it in your N8N environment:

```bash
npm install n8n-nodes-groq-speech
```

## Configuration

1. Get your Groq API key from: https://console.groq.com/keys
2. **IMPORTANT**: Accept model terms at https://console.groq.com/playground?model=playai-tts (required before first use)
3. Configure "Groq API" credentials in N8N with your API key
4. Use the "Groq TTS" node in your workflows

### ⚠️ Important Setup Step

Before using any TTS model, you must accept the terms of service for that specific model:

- For **playai-tts**: Visit https://console.groq.com/playground?model=playai-tts
- For **playai-tts-arabic**: Visit https://console.groq.com/playground?model=playai-tts-arabic

Click on the model in the playground and accept the terms when prompted. This is a one-time requirement per model.

## Usage

The node accepts the following parameters:

- **Text**: The text to be converted to audio
- **Model**: TTS model to use (playai-tts or playai-tts-arabic)
- **Voice**: One of the 19 available voices
- **Response Format**: Audio file format (MP3, WAV, FLAC, OGG)
- **Speed**: Speech speed (0.25 to 4.0)
- **Output File Name**: Custom name for the output file
- **Include Base64 Output**: Generate base64 encoded audio for direct API usage

## Available Voices

- Arista-PlayAI
- Atlas-PlayAI
- Basil-PlayAI
- Briggs-PlayAI
- Calum-PlayAI
- Celeste-PlayAI
- Cheyenne-PlayAI
- Chip-PlayAI
- Cillian-PlayAI
- Deedee-PlayAI
- Fritz-PlayAI
- Gail-PlayAI
- Indigo-PlayAI
- Mamaw-PlayAI
- Mason-PlayAI
- Mikail-PlayAI
- Mitch-PlayAI
- Quinn-PlayAI
- Thunder-PlayAI

## Output

The node returns:
- **JSON**: Metadata about the generated audio (success, filename, format, etc.)
- **Binary Data**: The generated audio file, ready to be used by other nodes

### With Base64 Output Enabled:
```json
{
  "success": true,
  "fileName": "speech.mp3",
  "format": "mp3",
  "voice": "Fritz-PlayAI",
  "model": "playai-tts",
  "speed": 1.0,
  "textLength": 25,
  "binaryDataSize": 45678,
  "audioBase64": "UklGRnoGAABXQVZFZm10...",
  "audioDataUri": "data:audio/mp3;base64,UklGRnoGAAB...",
  "base64Enabled": true
}

## Use Cases

- Voice message generation for WhatsApp
- Audio creation for emails
- Voice announcement automation
- Audio content generation for social media
- Custom sound notification creation

### WhatsApp Integration Example

With the base64 output feature, you can send audio directly to WhatsApp APIs:

```
[Trigger] → [Groq TTS] → [HTTP Request to WhatsApp API]
```

**Groq TTS Configuration:**
- Enable "Include Base64 Output" in Additional Fields
- Set desired voice and format

**HTTP Request Body:**
```json
{
  "number": "5511999999999",
  "mediatype": "audio", 
  "media": "{{$json.audioDataUri}}",
  "fileName": "{{$json.fileName}}"
}
```

### Available Output Fields:

**Standard Output:**
- `success`: Boolean indicating operation success
- `fileName`: Generated audio file name
- `format`: Audio format (mp3, wav, etc.)
- `voice`: Selected voice name
- `model`: TTS model used
- `speed`: Speech speed applied
- `textLength`: Length of input text
- `binaryDataSize`: Size of generated audio in bytes

**With Base64 Output Enabled:**
- `audioBase64`: Raw base64 encoded audio data
- `audioDataUri`: Complete data URI with MIME type
- `base64Enabled`: Confirmation that base64 was generated

### Direct WhatsApp Integration

No additional nodes needed! Simply:

1. Enable "Include Base64 Output" in the Groq TTS node
2. Use `{{$json.audioDataUri}}` directly in your WhatsApp API calls
3. Send audio messages instantly

## Troubleshooting

### Common Issues

1. **"Model terms acceptance required"**: Visit the Groq playground and accept terms for your chosen model
2. **"Invalid API key"**: Verify your API key is correct and has TTS permissions
3. **"Rate limit exceeded"**: Wait a moment and try again, or check your Groq usage limits

### Error Messages

The node provides detailed error messages to help diagnose issues:
- Model terms errors include direct links to accept terms
- API errors show the specific Groq error message
- Network errors indicate connection problems

## Support

For issues with this N8N node, please check:
1. Your Groq API key is valid
2. Model terms have been accepted
3. Your text input is not empty
4. The selected voice is compatible with your chosen model

## License

MIT