# Audio Generation Command

The Contaigents CLI now includes an `audio` command that allows you to generate audio from text using AI providers.

## Usage

```bash
contaigents audio [options]
```

## Options

- `-t, --text <text>` - Text to convert to audio (direct input)
- `-f, --file <file>` - Path to file containing text to convert
- `-o, --output <output>` - Output file path (default: audio_output)
- `-p, --provider <provider>` - AI provider to use (default: "gemini")
- `-v, --voice <voice>` - Voice to use for generation (default: "Zephyr")
- `-m, --model <model>` - Model to use for generation
- `--api-key <apiKey>` - API key for the provider (or set GEMINI_API_KEY env var)
- `--output-dir <dir>` - Output directory (default: current directory)

## Examples

### Generate audio from direct text input:
```bash
contaigents audio --text "Hello, this is a test of the audio generation feature."
```

### Generate audio from a file:
```bash
contaigents audio --file script.txt --output my_audio
```

### Use a different voice:
```bash
contaigents audio --text "Hello world" --voice Breeze --output hello_breeze
```

### Specify output directory:
```bash
contaigents audio --text "Hello world" --output-dir ./audio_files --output greeting
```

### Use custom API key:
```bash
contaigents audio --text "Hello world" --api-key YOUR_API_KEY
```

### Use Echogarden (local/offline):
```bash
contaigents audio --text "Hello world" --provider echogarden --voice Bella
```

### Use different Echogarden engines:
```bash
# High-quality Kokoro engine (default)
contaigents audio --text "Hello world" --provider echogarden --model kokoro

# VITS engine
contaigents audio --text "Hello world" --provider echogarden --model vits

# eSpeak engine (lightweight)
contaigents audio --text "Hello world" --provider echogarden --model espeak
```

## Supported Providers

Currently supported providers:
- **Gemini** (default) - Google's Generative AI with TTS capabilities (requires API key)
- **Echogarden** - High-quality local/offline TTS using Kokoro, VITS, and other engines (no API key required)

## Available Voices

### Gemini Voices
- Zephyr (default)
- Breeze
- Ember
- Tide
- Nova
- Aurora

### Echogarden Voices

**Kokoro Engine (default):**
- Bella (default) - Natural female voice
- Nicole - Professional female voice
- Sarah - Warm female voice
- Nova - Modern female voice
- Sky - Clear female voice
- Jessica - Friendly female voice
- River - Calm female voice
- Emma - Expressive female voice
- Isabella - Elegant female voice
- Alice - Youthful female voice
- Lily - Gentle female voice

**Additional Engines:**
- VITS and eSpeak engines are also supported with their respective voice sets

## Environment Variables

You can set the following environment variables to avoid passing API keys as command line arguments:

- `GEMINI_API_KEY` - Your Google Gemini API key

## Output

The command will:
1. Process your text input (either from direct text or file)
2. Split long text into chunks if necessary
3. Generate audio using the specified AI provider
4. Save the audio file with the appropriate extension
5. Display the file path and a file:// URL for easy access

## Error Handling

The command includes comprehensive error handling for:
- Missing API keys
- Invalid file paths
- Empty text content
- API quota limits
- Network errors

## File Formats

The generated audio files are automatically saved in the appropriate format based on the provider's output:
- WAV format for raw PCM audio (with proper headers)
- Other formats as supported by the provider

## Notes

- Text is automatically split into chunks to handle provider character limits
- The system supports both direct text input and file-based input
- Output files are saved with appropriate extensions based on the audio format
- File URLs are provided for easy access to generated audio files