contaigents/AUDIO_COMMAND.md

Modular AI Content Ecosystem with Audio Generation

# 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
```

## Supported Providers

Currently supported providers:
- **Gemini** (default) - Google's Generative AI with TTS capabilities

## Available Voices (Gemini)

- Zephyr (default)
- Breeze
- Ember
- Tide
- Nova
- Aurora

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